move network config wrappers to separate header

[goatshriek]

Stumpless uses a scheme involving #definenames and macro functions to separate its portability measures from the application logic itself. This was originally done via a single header, include/private/config/wrapper.h, but as the library grows this single header has become bloated. Now features are instead contained in their own dedicated wrapper headers. Older features need to be moved to their own as well to address the original problem.

Your task here is to factor out the network support wrappers into their own header. This is a good task for those with some C knowledge looking to learn about how to implement portability in a C application. As this is a refactoring task you can rely on the existing unit and integration tests as a safety net as you make changes and explore.

Check out the Contributing Guidelines and the development guide for the basics on working with stumpless and submitting changes.

General Approach

There are a few details left out of the following approach, for you to fill in as you encounter them. If you find you need help, please ask here or on the project gitter and someone can help you get past the stumbling block. You are also free to take a different approach if you feel it is better - this is merely meant as a starting point.

First, read through the portability documentation to understand how portability is approached in the library.

Next, have a look at include/private/config/wrapper/journald.h. This header does the same wrapping for targets for systemd's journal service that the network support should. This is a great file to copy as a starting point and modify to suit your needs.

Finally, have a look at tools/check_headers/stumpless.yml and tools/check_headers/stumpless_private.yml. These files are used by a custom tool for header inclusion checks across the library's source code. For all symbols that you move to your new header file, you'll also need to change to point to your new header in these files. Any files that are present in stumpless.yml should be moved to stumpless_private.yml as well, as they were added before the public/private split in the yaml files was made. You'll see symbols for the journald and thread safety wrappers already in stumpless_private.yml as an example.

Once you have moved things to your new header and updated the header checking tool manifests, you can use the header check tool to tell you what files need to have their #include statements updated. You can find examples of how to run the tool in the testing workflow that does it, .github/workflows/analysis.yml, or you can use the one-liner included below. You will need Ruby to run the tool.

tools/check_headers/check_headers.rb "include/**/*.h*" "src/**/*.c" "test/**/*.cpp" "docs/examples/**/*.c"

Good luck!

[SchattenMonarch]

Hi @goatshriek,

So the task is basically to split the code from include/private/config/wrapper.h file to the .h files where it's used?

I just cloned your rep and used the program agent ransack to search through the whole project and find out where the mentioned file is included:

[goatshriek]

Hello @SchattenMonarch, thanks for your interest in the project and reaching out about this issue!

The task does involve splitting part of this header into a new separate one, more specifically the portion between lines 25 and 106 in the current latest branch. You'll then need to update the source files that need the moved definitions (which won't be all of the source files that reference the original) to use the new header. The existing header check tool should identify which sources these are, once the yaml files described above are updated.

The list you've generated above looks like a good starting point! Just keep in mind that some files in the list, for example the file target source in file.c, likely won't need any changes based on network configuration refactoring.

[acass91]

Hi @goatshriek, I have some experience with C from working with embedded systems. Could I work on this as part of Hacktoberfest?

[goatshriek]

Absolutely, I'll assign this to you so that it's marked for you to work.

[goatshriek]

Closed by #243.