Skip to content

fileapi: add a file-based api for semantic buildsystem information

Brad King requested to merge brad.king/cmake:fileapi into master

Add a file-based API that clients may use to get semantic information about the buildsystem that CMake generates. Clients will write query files under a designated location in the build tree, and CMake will write reply files for clients to read.

This offers an alternative to the server mode that does not require a long-running CMake process or generation of a single monolithic response object in memory.

Add support for three kinds of query files:

  • shared stateless: These allow clients to share requests for major object versions and get all those recognized by CMake. Once any client has written a shared request to a build tree it will persist. Other clients will not need to overwrite the request (since it is stateless) and should not remove it either.

  • client-owned stateless: These allow clients to own requests for major object versions and get all those recognized by CMake. Clients may add and remove their own queries freely.

  • client-owned stateful: These allow clients to request a list of versions of each object kind and get only the first-listed version that CMake recognizes. Since clients own their stateful query files they can mutate them over time. As a client installation is updated it may update the queries that it writes to build trees to get newer object versions without paying the cost of continuing to generate older versions.

The first two are simple but such clients may cause CMake to write more than they need. The last is the preferred way for real clients to interact.

Add support for three kinds of objects:

  • codemodel: Describes the build system structure as modeled by CMake.
  • cache: Lists cache entries.
  • cmakeFiles: Lists files used by CMake while configuring and generating the build system. These include the CMakeLists.txt files as well as included .cmake files.

These are inspired by those in the server mode but have been revised.

Issue: #18398 (closed)

Merge request reports