Necessary Maintenance #25465
Need to discuss and implement better dependency hygiene in C++ code development
I'd like us to discuss the more careful management of dependencies in the context of the more granular dependency specification that "modern" (c. 2014) CMake provides.
In particular, I think we should:
- Be very careful and explicit about what we consider to be the public API for a package, and have only those headers in the main include directory.
- Partition what we currently describe as "detail" into an additional, "private" category, where
- `detail` and its accompanying namespace is intended for headers (and their associated implementation compilation units) that are required by API headers (and therefore should be installed); and
- `private` is for headers, etc. that should not be installed as they are only required by in-library compilation units.
- Avoid using `detail/` (and `private`) headers from outside the library with which they are associated. If this is necessary, then the composition and public API of the libraries concerned should be reviewed.
Modern CMake gives us the ability to define header-only, "interface" targets with their own dependencies, allowing us to more finely manage dependencies for macro, template, and other inline functionality, giving increased granularity to what it means to "depend" on a library. Eventually, we should progress to more carefully managing symbol export to libraries.