Skip to content

Document generated headers

Generated headers stay generated: they are not checked in for cpdocs. cpdocs reads headers only after the build hook has returned, so the hook only has to run the generators first, and the manifest names where their output lands.

Run the generators in the build hook

Headers written by configure_file exist as soon as CMake has configured the build. Headers written by a build target, such as a code generator, need that target built. The build hook does both:

build:
  build: >
    cmake -S "{{source}}" -B "{{tmpdir}}" -G Ninja
    -DCPDOCS_FEATURE_SET="{{feature-set}}"
    -DCPDOCS_MANIFEST_OUTPUT="{{output-file}}"
    && cmake --build "{{tmpdir}}" --target acme-generated-headers

Building only the generator target is enough; cpdocs does not need the library itself compiled.

Name the output directory in the manifest

The generated include directory is an API root of its own, marked generated, next to the checked-in one:

{
  "id": "acme",
  "language": "cpp",
  "api": [
    {"path": "/src/include"},
    {"path": "/src/build/generated/include", "generated": true}
  ],
  "parse": {"include": ["/src/include", "/src/build/generated/include"]}
}

Both directories go on the include path, so a checked-in header can include a generated one, as it would in an ordinary build.

What the reference shows

Generated declarations are documented like any other, from the comments the generator writes, and each generated header appears at its include path, such as acme/status.hpp, marked as generated by the build.

The generated-cpp example generates acme/version.hpp from a template at configure time and acme/status.hpp from a table of status codes at build time; its checked-in header includes both.