Update Public Headers

update-public-headers maintains the public include tree, domain umbrellas, namespace declarations and consumer exports. Run it after adding, moving, or removing public headers or source directories. Library builds consume the checked-in results and do not run the generator automatically. See Run and Configure Commands for shared options and Set Up the Repository for installation.

Configure and Generate

Edit tool/conf/tools/update_public_headers.elcl. Every source directory outside an excluded subtree needs a directory section. Header patterns match filenames in that directory only. An organizational subdirectory inherits its parent’s namespace and publication settings; set Nested Namespace: Yes when its name is also a C++ namespace. Each entry computes its own output location from Flatten: the include root for Yes, or its full source-relative directory for No. Use Target Directory only for a local override such as the shortened zip destination.

./erbsland-core-tool update-public-headers

Reading, parsing and rendering use the worker-count hint from Core’s system service by default. Use --jobs 2 to limit concurrency while other builds are running, or --jobs 1 to use a single maintenance worker. The accepted range is 1 to 64; worker count does not change the generated output.

Review the public wrappers, source umbrellas, core/Namespaces.hpp, core/impl/MakeOneNamespace.hpp, and tool/data/public_headers/header_map.txt together with the source changes. Do not edit these generated files. The generator retains compatible include aliases and removes obsolete files carrying its generated-file marker. The repository’s pre-commit utility runs this command before normalizing consumer includes.

Use Focused Includes

Prefer the canonical public header for each API unit, for example <erbsland/TlsClientConnection.hpp> or <erbsland/RegEx.hpp>. Real public namespaces keep their own include directories, such as <erbsland/cterm/Terminal.hpp>. Disabling consumer namespace flattening does not change these include paths.

Named umbrellas such as <erbsland/all_network.hpp> include only the public headers directly in that directory. Include a subgroup explicitly, for example <erbsland/all_network_http.hpp> or <erbsland/network/http/all.hpp>. Nested aliases such as <erbsland/network/all.hpp> remain available. There is no universal <erbsland/all.hpp>. Global Excluded From All Headers patterns apply to every umbrella; directory patterns add local exclusions. Optional formatter adapters and resource-storage registration require explicit includes.

Check and Diagnose

./erbsland-core-tool update-public-headers --check

Check mode fails for missing, changed, or obsolete outputs without writing or removing files. Run without --check to refresh them. Unchanged files retain their timestamps.

An uncovered-directory error requires a directory section or an explicit exclusion. A namespace mismatch requires correcting the declaration or the directory’s Nested Namespace setting. Wrapper collisions require distinct targets or an intentional entry in Mergeable Header Names. Unsupported selective declarations need a canonical forward header. These errors are reported before any outputs change.

If the installed tool does not recognize pre-commit, rerun setup.py to refresh it. See Public Headers Reference for configuration inheritance, exports, and the mapping format.