cmake

llpkgc is a utility library used within this repository. It is maintained in an upstream repository and is not a native part of the CMake core logic.

Upstream Repository: https://gitlab.kitware.com/utils/llpkgc

Note for Contributors: Updates to llpkgc should generally be made in the upstream repository rather than within the CMake repository, unless the changes are exceptionally specific to CMake.

The CMake File-Based API v1 allows external tools (clients) to interact with CMake by reading and writing JSON files in the build directory. The API is organized into two main subdirectories under <build>/.cmake/api/v1/:

• query/: Contains request files written by the client to ask CMake for information.
• reply/: Contains response files written by CMake. Clients should only read these files by following references found in a reply index file.

Note: Clients must never remove files in the reply/ directory. For user-wide queries across all projects, you can add query files to api/v1/query inside the directory specified by the CMAKE_CONFIG_DIR environment variable.

The CMake Instrumentation API collects timing, target, and system diagnostic information during the configure, generate, build, test, and install steps of a CMake project.

Supported Generators: This feature is only available when using:

• Makefile Generators
• Ninja Generators
• FASTBuild

Workflow:

1. Data Collection: CMake writes v1 Snippet Files into the project build tree during command execution (e.g., compile, link, custom commands).
2. Indexing: CMake collates these snippets into a v1 Index File based on configured "hooks" (e.g., after every build or ctest invocation).
3. Callbacks: User-defined callbacks process the v1 Index File. Once all callbacks complete, CMake automatically deletes the index and snippet files.

CMake target commands modify the properties of a target (e.g., sources, compile flags, output names, or requirements for consumers). They are categorized by their commonality and recommended usage:

• Common/Recommended: target_compile_definitions, target_compile_features, target_link_libraries, target_sources.
• Advanced/Caution: get_target_property, set_target_properties, target_compile_options, target_link_options, target_precompile_headers.
• Esoteric/Footguns (Avoid if possible): target_include_directories, target_link_directories.

When applying these commands, use the following scope keywords:

• PRIVATE: Requirements needed only to build the target itself.
• INTERFACE: Requirements needed only to consume the target.
• PUBLIC: Requirements needed for both building and consuming the target.

CMake provides a file-based API that allows external clients to obtain semantic information about the build systems CMake generates.

To use the API, a client writes 'query files' to a specific directory within the build tree. When CMake runs the generation step in that build tree, it detects these files, processes the requests, and writes 'reply files' containing the requested information.

The API is located at <build>/.cmake/api/ at the top of the build tree.

CMake uses an Explicit Static build design for C++ modules.

• Explicit: Build controls which modules are visible to each translation unit directly by providing exact paths to Binary Module Interface (BMI) files via a module map.
• Static: Uses a static set of build commands. Dependencies are discovered via a scanning step and then added as edges to the existing build graph, rather than creating new commands dynamically during the build.

This design aims for correct, deterministic builds, support for generated sources, static communication (using files instead of background services), and minimized build graph regeneration.

The Tests/ directory contains the CMake test suite. Tests are organized into several specialized subdirectories based on their purpose:

• CMakeLib/: Tests that link to the CMakeLib library defined in Source/.
• Module/: Tests for specific CMake modules.
• RunCMake/: Tests that execute CMake and/or other tools to verify return codes and stdout/stderr content. These are primarily used for testing error cases and diagnostic output.
• Fuzzing/: Fuzz testing targets using libFuzzer, integrated with OSS-Fuzz.
• Find*/: Tests for specific find modules (requires corresponding packages to be installed on the machine).
• CMakeOnly/ (Deprecated): Tests that run CMake to generate a project without building it. Use Tests/RunCMake/ instead.