vcpkg should provide an official strategy for library config headers

[JonTheBurger]

Use Case

I am currently working on rolling out vcpkg for an embedded project and have been busy packaging repositories like FreeRTOS-Kernel and lvgl for consumption. While my current workarounds are okay, I think this is the main thing preventing vcpkg from being the choice for serious C/C++ package management for microcontrollers.

Current State of Affairs

At time of writing, the most proper way I have found to handle this is for the triplet file to specify a VCPKG_CMAKE_CONFIGURE_OPTIONS that contains -D<project-specific-var>=<path-to>/somelib_config.h, and then add that same path to VCPKG_HASH_ADDITIONAL_FILES. This often requires also patching projects to use $<BUILD_INTERFACE:...> for the somelib_config.h, as well as add the file to its PUBLIC_HEADER target property (assuming the corresponding install command correctly specifies PUBLIC_HEADER, which I have a separate helper for. The config header must of course be installed so that consumers can find it.)

Where Can We Go

For my purposes, I wrote a helper function to use in portfile.cmake that:

1. Ensures the file is in VCPKG_HASH_ADDITIONAL_FILES
2. Adds -D${VAR}=<path-to-header-dir> to VCPKG_CMAKE_CONFIGURE_OPTIONS (eventually, I decided that if a port didn't officially support a header variable I'd just use COM_VCPKG_CONFIG_HEADER_DIR by default and patch its CMakeLists.txt)
3. Install the config header (this allows us to avoid patching in some cases)

This is of course tailored to my use case, and requires more workarounds if the project specifically expects a CONFIG_FILE (not directory) variable, but it at least provides an opinionated strategy for handling config files that my group can follow.

I think it would be great for vcpkg to at the very least take a stance on how to handle config headers, specifically a stance other than "we don't support them" (which would be a shame, since all of the great machinery to do so is already present).

I've included the docs for my helper function below - I can add more details if need be, but it's just a wrapper over the above concerns for convenience:

---

com_install_config_header

Some libraries, especially for embedded systems, require users to provide a configuration header. This function ensures the user has supplied the header, and installs it alongside the project's bundled headers. Lastly, the config header VAR is added to VCPKG_CMAKE_CONFIGURE_OPTIONS for use in the port's CMakeLists.txt $<BUILD_INTERFACE:...> include directories.

Signatures:

com_install_config_header(
    HEADER <header>
    [DEST <install-destination>]
    [VAR <containing-directory-variable>]
    [OPTIONAL]
)

The options are:

• HEADER <header>: The name of the header file, such as somelib_config.h.
• DEST <install-destination>: Location where the header will be installed. By default, this is set to "${CURRENT_PACKAGES_DIR}/include/${PORT}/". Because this script installs the header, the port's CMakeLists.txt does not need to be patched to do so.
• VAR <containing-directory-variable>: CMake variable listing the directory that contains the HEADER file. By default, this is set to COM_VCPKG_CONFIG_HEADER_DIR. A consuming project may specify COM_VCPKG_CONFIG_HEADER_DIR by default - the call to the library CMake project will be converted to -D${VAR}=<value> in this case.
• OPTIONAL: Flags that the config header is optional, suppressing errors if the file was not found.

Example usage:

com_install_config_header(
  DEST coreMQTT
  HEADER core_mqtt_config.h
  OPTIONAL
)

[Neumann-A]

Why is your "Config Header" not simply a port?

[JonTheBurger]

In my mind, the issue with making the config header a port is that it doesn't scale the same way that having every embedded system as a user-contributed triplet doesn't scale. Using FreeRTOS-Kernel as an example, we can see the user-configurable settings here: https://www.freertos.org/Documentation/02-Kernel/03-Supported-devices/02-Customization

Looking at just one of the macros #define configSYSTICK_CLOCK_HZ 1000000, we could have a ton of differences based on this numeric configuration option alone. Would I create a new port my-company-specific-product and make it an optional feature of freertos-kernel? Would every new product therefore need to override the freertos-kernel port so they can be included as features? I may be missing your meaning here, but this is where my mind goes when considering the port option.

Because the triplet file describes the target platform, I believe the information to belong there (and for config headers, I would recommend them be captured as additional ABI affecting files). Hopefully that helps elaborate upon the use case.