Best-practices for providing an external config header to a dependency

[mitchgrout]

It's not uncommon to have a library that expects a special user-supplied configuration header to be present. This is particular prevalent within embedded libraries, for example FreeRTOS' FreeRTOSConfig.h file.

In older projects, we usually see these in-tree with the project code itself. I'm personally opposed to this as it makes it difficult to properly separate out ours vs theirs, and can cause irritation with tooling such as linters trying to run on thirdparty code.

I've got quite a few libraries like this, each needing their own special set of header files, and sometimes even source files in order to compile. I treat these as external dependencies, providing each their own .wrap files. I've trialled a few strategies for making this work, which I've detailed below:

1. packagefiles/

Simply place all the customization files you need in here, and adjust the .wrap file to reference the directory.
The main downside with this is, meson will not re-apply any files after the subproject has been downloaded,
so any modifications made to the packagesfiles/ directory will only be replicated after you either
manually copy it across, or nuke the subproject. This absolutely sucks in a collaborative environment,
and I don't use it for this reason.

2. <x>-config dependencies

Ensure that each library accepts a dependency named <x>-config, where <x> is the project name.
For example, for FreeRTOS, have FreeRTOS-config, which can be defined in the consuming project via:

FreeRTOS_config_dep = declare_dependency(include_directories: 'config/FreeRTOS', sources: 'config/FreeRTOS/FreeRTOSConfig.c')
meson.override_dependency('FreeRTOS-config', FreeRTOS_config_dep)
FreeRTOS = dependency('FreeRTOS')

This resolves the main problem with option 1, as you can freely edit the sources and headers in-tree,
and the subproject will react and recompile as required. It also requires that the library be very careful
about how it uses the <x>-config dependency, since if it contains a sources: list, this will need to be
removed via .partial_dependency() before the config is used in the public-facing declare_dependency() call.

3. Source-only dependencies

Transform the library into a dependency(sources: ...) and export this from the subproject,
and then in the top-level project, create the build target with any extra configuration required:

FreeRTOS_template_dep = dependency('FreeRTOS-template')
FreeRTOS_lib = library('FreeRTOS', dependencies: FreeRTOS_template_dep, sources: 'config/FreeRTOS/FreeRTOSConfig.c', include_directories: 'config/FreeRTOS')
FreeRTOS_dep = dependency(link_with: FreeRTOS_lib, include_directories: 'config/FreeRTOS' dependencies: FreeRTOS_template_dep.partial_dependency(includes: false))

The main downside to this is that you no longer have a clean separation between ours and theirs code,
as thirdparty code is being compiled as part of your build target. This means that warnings are harder
to inhibit, and linters may need extra config to exclude these files.4

---

There's a few other strategies I've explored in the past, but these are the main ones I've seen much success with.
I could see meson potentially being enhanced to approach this problem, saving the need for copying
around the same code everywhere. For example:

FreeRTOS_dep = dependency('FreeRTOS', properties: {
 'includes': include_directories('config/FreeRTOS'),
  'sources': files('config/FreeRTOS/FreeRTOSConfig.c'),
  # Analogous to setting these as a `[property]` in a machine file
})

# within subprojects/FreeRTOS/meson.build
includes = meson.get_external_property('includes', [])
sources = meson.get_external_property('sources', [])
# ... or an alternative method more specialized for the task

FreeRTOS_lib = library('FreeRTOS', core_sources + sources, include_directories: [core_includes, includes])
FreeRTOS_dep = declare_dependency(link_with: FreeRTOS_lib, include_directories: [core_includes, includes])
# ^ can be sure we aren't accidentally re-exporting the sources to consumers of the dependency