Guardrails / Collectors

C and C++ build

The C or C++ build in the project directory: which build system and package manager it uses, the C++ standard and CMake version it requires, the packages it declares and which of them are pinned, and the packages it expects the machine to carry. CMakeLists.txt is a script, so what it declares conditionally is not seen and scanned says so.

Facts key	cpp
Version	v1
Script	cpp.py
Timeout	30 seconds

Inputs

Input	Description	Default	Environment
projectDir	Directory holding the project, relative to the directory the CLI runs in.	.	GUARDRAIL_INPUT_PROJECTDIR

A guardrail that declares an input of the same name passes it through, so the guardrail's configuration in buildnote.json is what decides these values.

A guardrail asks for these facts by name, and reads them back the same way:

{
  "collect": ["cpp"]
}

cpp = guardrail.facts("cpp")

Facts

The document cpp collects. A path carrying [] is an entry of the list before it, and one carrying [path] is a key of the object before it.

Fact	Meaning
directory	The projectDir input, as the guardrail configured it.
exists	Whether that directory is there. Nothing else is collected when it is not.
manifest	Path of the primary manifest, relative to projectDir: CMakeLists.txt when there is one, otherwise the package manifest that was found.
sources	Every manifest that was read and understood, in the order they were read. One the reader could not handle is in unparsed instead.
scanned	Every manifest that is a program rather than a declaration and was read by pattern. CMakeLists.txt and conanfile.py are scripts, so a target or a dependency added inside an if() or a function is not seen.
buildSystem	Which build system the checkout uses: cmake, meson, bazel, make, or null when none of them is there and only a package manifest was found.
packageManager	Which package manager declares the dependencies: vcpkg, conan, both, or null when neither is there and dependencies are vendored or found on the system.
declared	The C++ standard the build asks for, or null when it asks for none and the compiler's default decides.
declared.version	Standard as written, such as 20.
declared.source	Manifest declaring it, relative to projectDir.
declared.pinned	Whether the build requires that standard rather than treating it as a preference. CXX_STANDARD_REQUIRED off means the compiler may fall back to an older one.
cmakeMinimum	The version cmake_minimum_required names, such as 3.25, or null when the reader saw none. Below 3.5 modern CMake refuses to configure at all.
baseline	The builtin-baseline commit vcpkg.json pins, which is what makes a vcpkg build reproducible, or null when it pins none.
projects	Every project the reader saw: each project() call in a CMakeLists.txt, or the package the manifest declares.
projects[].path	Directory of the project, relative to projectDir, . for the project directory itself.
projects[].manifest	The manifest declaring it, relative to projectDir.
projects[].name	Name it declares, or null when the reader could not see one.
dependencies	What the manifests declare, split by whether the build asks for it itself.
dependencies.direct	Every dependency the package manifests name, in manifest order. A library found with find_package and no manifest entry is not one of these, because nothing in the checkout says which version it expects.
dependencies.direct[].name	Package name, such as fmt.
dependencies.direct[].version	Version exactly as written, such as 10.2.1, or null when the entry names none and the registry baseline decides.
dependencies.direct[].scopes	default, or test for a vcpkg feature named test and build for a Conan build requirement.
dependencies.direct[].source	Manifest declaring it, relative to projectDir.
dependencies.direct[].pinned	Whether the entry names one exact version. A vcpkg version>= is a floor rather than a pin, and an entry with no version at all is decided by the baseline.
dependencies.transitive	Always empty. What a resolver settles on is not read: lockfiles says whether one is committed.
findPackages	Every package a CMakeLists.txt looks for with find_package, which is what the build expects the machine to already carry.
languages	Every language a project() call enables, such as C and CXX, in the order they are named. Empty when no call names any, which is CMake enabling C and C++ both, and ["NONE"] when a call disables them. A checkout whose only language is C has no C++ standard to declare.
lockfiles	Every lock file committed, relative to projectDir, such as conan.lock.
unparsed	Every manifest the reader could not handle, so a guardrail can tell a build that declares nothing from one nobody could read.
unparsed[].path	Path of that manifest, relative to projectDir.
unparsed[].reason	What stopped the reader.

A collector that cannot finish prints what it had along with an incomplete key saying why, so the facts below the point it stopped are absent. A check that cares reads incomplete before the rest.

Example facts

The example facts collected by cpp collector:

{
  "directory": ".",
  "exists": true,
  "manifest": "CMakeLists.txt",
  "sources": [
    "CMakeLists.txt",
    "vcpkg.json"
  ],
  "scanned": [
    "CMakeLists.txt"
  ],
  "buildSystem": "cmake",
  "packageManager": "vcpkg",
  "declared": {
    "version": "20",
    "source": "CMakeLists.txt",
    "pinned": true
  },
  "cmakeMinimum": "3.25",
  "baseline": "6f3a1c2d9b8e4f7a0c5d2e1b3a4f5c6d7e8f9a0b",
  "projects": [
    {
      "path": ".",
      "manifest": "CMakeLists.txt",
      "name": "widget"
    }
  ],
  "dependencies": {
    "direct": [
      {
        "name": "fmt",
        "version": null,
        "scopes": [
          "default"
        ],
        "source": "vcpkg.json",
        "pinned": false
      },
      {
        "name": "spdlog",
        "version": "1.13.0",
        "scopes": [
          "default"
        ],
        "source": "vcpkg.json",
        "pinned": false
      },
      {
        "name": "catch2",
        "version": null,
        "scopes": [
          "test"
        ],
        "source": "vcpkg.json",
        "pinned": false
      }
    ],
    "transitive": []
  },
  "findPackages": [
    "Threads",
    "fmt"
  ],
  "languages": [
    "CXX"
  ],
  "lockfiles": [],
  "unparsed": []
}

Collected for

Guardrail	Category	Inputs
cpp/cmake-minimum-floor	cpp	projectDir
cpp/package-manager-declared	cpp	projectDir
cpp/standard-declared	cpp	projectDir
cpp/standard-required	cpp	projectDir

All collectors