Skip to content

livery.extensions.cmake._build

livery.extensions.cmake._build

The gate build of a CMake project: configure, compile, and run its tests.

The build lands in the package's build/gate directory, configured with the Ninja generator and a compilation database for the tools that read one. The tests run through ctest. While coverage is listed, this extension's [for.coverage] table applies (measures): the build is instrumented and each run is measured by the compiler family CMake detected, gcov for gcc, llvm-cov for clang, Microsoft's engine for MSVC, whose output _readings turns into the package's part; while it is not, the build is not instrumented and ctest runs alone. On Windows with no compiler chosen, the build enters the newest Visual Studio's C++ environment itself. Nothing here names a language: CMake chooses the compilers its project asks for.

Every tool here is a tool of the store, reached through its toolroom handle, so the version is the one this checkout's lock pins. A handle spawns its tool by name, so a machine that never deployed one raises OSError, which becomes a refusal naming the sync that supplies it.

Functions:

Name Description
measurer_for

The measurer for compiler_id as CMake spells it; empty without one.

measures

Whether package's gate build is measured: cmake contributes to coverage.

toolchain_env

The environment the gate's build tools run in.

vswhere_path

Where this machine keeps vswhere, present or not.

configure

Configure package into the gate's build directory; arguments go to cmake.

compile

Build the configured package, arguments to cmake's build; incremental.

gate_build

Configure and build package into the gate's build directory.

test

Run ctest over the gate build: every test, or selection's alone.

compiler_of

The gate build's C++ compiler id and path, as CMake detected them.

compile_commands

Where the package's gate build writes its compilation database.

Attributes:

Name Type Description
GATE_BUILD_DIR
COVERAGE_CMAKE
NAME
MEASURED_FOR
PROJECT_INCLUDE
PROFILE_DIR
FAMILIES
SHELL
VSWHERE
MSVC_TOOLS
MSVC_TOOLS_X64
ENGINE_RUNTIME

GATE_BUILD_DIR module-attribute

GATE_BUILD_DIR = 'build/gate'

COVERAGE_CMAKE module-attribute

COVERAGE_CMAKE = Path(__file__).with_name('coverage.cmake')

NAME module-attribute

NAME = 'cmake'

MEASURED_FOR module-attribute

MEASURED_FOR = 'coverage'

PROJECT_INCLUDE module-attribute

PROJECT_INCLUDE = 'CMAKE_PROJECT_INCLUDE'

PROFILE_DIR module-attribute

PROFILE_DIR = 'coverage'

FAMILIES module-attribute

FAMILIES = {'GNU': 'gcov', 'Clang': 'llvm', 'AppleClang': 'llvm', 'MSVC': 'msvc'}

SHELL module-attribute

SHELL = 'cmd.exe'

VSWHERE module-attribute

VSWHERE = ('Microsoft Visual Studio', 'Installer', 'vswhere.exe')

MSVC_TOOLS module-attribute

MSVC_TOOLS = {'ARM64': ('Microsoft.VisualStudio.Component.VC.Tools.ARM64', 'vcvarsarm64.bat')}

MSVC_TOOLS_X64 module-attribute

MSVC_TOOLS_X64 = ('Microsoft.VisualStudio.Component.VC.Tools.x86.x64', 'vcvars64.bat')

ENGINE_RUNTIME module-attribute

ENGINE_RUNTIME = re.compile('(static_)?covrun\\d*\\.dll', re.IGNORECASE)

measurer_for

measurer_for(compiler_id: str) -> str

The measurer for compiler_id as CMake spells it; empty without one.

Source code in packages/extensions/cmake/src/livery/extensions/cmake/_build.py
def measurer_for(compiler_id: str) -> str:
    """The measurer for *compiler_id* as CMake spells it; empty without one."""
    return FAMILIES.get(compiler_id, "")

measures

measures(package: Package) -> bool

Whether package's gate build is measured: cmake contributes to coverage.

True while the workspace package belongs to lists coverage and this extension's [for.coverage] table applies (livery.workshop.contributions_for).

Source code in packages/extensions/cmake/src/livery/extensions/cmake/_build.py
def measures(package: Package) -> bool:
    """Whether *package*'s gate build is measured: cmake contributes to coverage.

    True while the workspace *package* belongs to lists coverage and
    this extension's ``[for.coverage]`` table applies
    ([livery.workshop.contributions_for][]).
    """
    from livery.workshop import contributions_for

    return NAME in contributions_for(MEASURED_FOR, package.directory)

toolchain_env

toolchain_env() -> dict[str, str]

The environment the gate's build tools run in.

This process's environment, entered into MSVC's on Windows: with no CXX set and no cl on PATH, vswhere names the newest Visual Studio that has the C++ build tools for this architecture, and the environment its vcvars batch file leaves is read back through set. CC and CXX then name cl, so CMake takes MSVC over a MinGW gcc that is also on PATH: on Windows the gate builds with MSVC unless CXX says otherwise, and a person who sets it chooses. Read once per process; a copy each call.

Raises:

Type Description
Failed

on Windows with no compiler chosen and no Visual Studio installation with the C++ build tools to enter.

Source code in packages/extensions/cmake/src/livery/extensions/cmake/_build.py
def toolchain_env() -> dict[str, str]:
    """The environment the gate's build tools run in.

    This process's environment, entered into MSVC's on Windows: with
    no ``CXX`` set and no ``cl`` on PATH, vswhere names the newest
    Visual Studio that has the C++ build tools for this architecture,
    and the environment its vcvars batch file leaves is read back
    through ``set``. ``CC`` and ``CXX`` then name ``cl``, so CMake
    takes MSVC over a MinGW gcc that is also on PATH: on Windows the
    gate builds with MSVC unless ``CXX`` says otherwise, and a person
    who sets it chooses. Read once per process; a copy each call.

    Raises:
        Failed: on Windows with no compiler chosen and no Visual
            Studio installation with the C++ build tools to enter.
    """
    return dict(_entered())

vswhere_path

vswhere_path(env: dict[str, str] | None = None) -> Path

Where this machine keeps vswhere, present or not.

Under the 32-bit program files directory env names, this process's when env is None; the key is read in both spellings, since Windows upper-cases the ones a process inherits.

Source code in packages/extensions/cmake/src/livery/extensions/cmake/_build.py
def vswhere_path(env: dict[str, str] | None = None) -> Path:
    """Where this machine keeps vswhere, present or not.

    Under the 32-bit program files directory *env* names, this
    process's when *env* is None; the key is read in both spellings,
    since Windows upper-cases the ones a process inherits.
    """
    variables = dict(os.environ) if env is None else env
    program_files = (
        variables.get("PROGRAMFILES(X86)")
        or variables.get("ProgramFiles(x86)")
        or r"C:\Program Files (x86)"
    )
    return Path(program_files).joinpath(*VSWHERE)

configure

configure(package: Package, arguments: tuple[str, ...] = ()) -> None

Configure package into the gate's build directory; arguments go to cmake.

CMake configures against the host's toolchain with the Ninja generator, in the environment toolchain_env enters, and exports the compile commands clang-tidy reads. A measured build (measures) includes coverage.cmake, and an unmeasured one removes the include from the cache. A dependency the project's CMakeLists.txt cannot find fails the configure with cmake's own message.

Source code in packages/extensions/cmake/src/livery/extensions/cmake/_build.py
def configure(package: Package, arguments: tuple[str, ...] = ()) -> None:
    """Configure *package* into the gate's build directory; *arguments* go to cmake.

    CMake configures against the host's toolchain with the Ninja
    generator, in the environment ``toolchain_env`` enters, and
    exports the compile commands clang-tidy reads. A measured build
    (`measures`) includes ``coverage.cmake``, and an unmeasured one
    removes the include from the cache. A dependency the project's
    ``CMakeLists.txt`` cannot find fails the configure with cmake's own
    message.
    """
    build_dir = package.directory / GATE_BUILD_DIR
    include = (
        f"-D{PROJECT_INCLUDE}={COVERAGE_CMAKE}"
        if measures(package)
        else f"-U{PROJECT_INCLUDE}"
    )
    tools.cmake.opts(cwd=package.directory, env=toolchain_env())(
        "-S",
        ".",
        "-B",
        str(build_dir),
        "-G",
        "Ninja",
        "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON",
        include,
        *arguments,
    )

compile

compile(package: Package, arguments: tuple[str, ...] = ()) -> None

Build the configured package, arguments to cmake's build; incremental.

Source code in packages/extensions/cmake/src/livery/extensions/cmake/_build.py
def compile(package: Package, arguments: tuple[str, ...] = ()) -> None:
    """Build the configured *package*, *arguments* to cmake's build; incremental."""
    build_dir = package.directory / GATE_BUILD_DIR
    tools.cmake.opts(cwd=package.directory, env=toolchain_env())(
        "--build", str(build_dir), *arguments
    )

gate_build

gate_build(package: Package, root: Path) -> None

Configure and build package into the gate's build directory.

What the package's ctest runs on, in one call, for the affected gate's test-only step; the two halves are the build.configure and build.compile steps.

Source code in packages/extensions/cmake/src/livery/extensions/cmake/_build.py
def gate_build(package: Package, root: Path) -> None:
    """Configure and build *package* into the gate's build directory.

    What the package's ctest runs on, in one call, for the affected
    gate's test-only step; the two halves are the ``build.configure``
    and ``build.compile`` steps.
    """
    del root
    configure(package)
    compile(package)

test

test(package: Package, root: Path, *, selection: tuple[str, ...] = (), arguments: tuple[str, ...] = ()) -> None

Run ctest over the gate build: every test, or selection's alone.

arguments go to ctest after the workshop's own.

A selected test file maps to the ctest named after its stem (tests/test_acme.cpp runs test_acme), which is how the template registers tests; a selection no ctest answers to is a refusal naming the rule. A measured run (measures) is measured by the family of the compiler CMake configured the gate build with: gcov and llvm-cov read the counters a green run left, and Microsoft's engine collects around the run itself. The lines reached land as the package's part in the line format at the workspace root (write_part), and the package's part of an earlier run goes first, so a red run leaves none; a family without a measurer refuses by name, since a suite that ran unmeasured never passes as measured. A run that is not measured runs ctest alone and leaves no part.

Source code in packages/extensions/cmake/src/livery/extensions/cmake/_build.py
def test(
    package: Package,
    root: Path,
    *,
    selection: tuple[str, ...] = (),
    arguments: tuple[str, ...] = (),
) -> None:
    """Run ctest over the gate build: every test, or *selection*'s alone.

    *arguments* go to ctest after the workshop's own.

    A selected test file maps to the ctest named after its stem
    (``tests/test_acme.cpp`` runs ``test_acme``), which is how the
    template registers tests; a selection no ctest answers to is a
    refusal naming the rule. A measured run (`measures`) is measured by
    the family of the compiler CMake configured the gate build with: gcov
    and llvm-cov read the counters a green run left, and Microsoft's
    engine collects around the run itself. The lines reached land as
    the package's part in the line format at the workspace *root*
    (`write_part`), and the package's part of an earlier run goes
    first, so a red run leaves none; a family without a measurer
    refuses by name, since a suite that ran unmeasured never passes as
    measured. A run that is not measured runs ctest alone and leaves no
    part.
    """
    build_dir = package.directory / GATE_BUILD_DIR
    names = [Path(path).stem for path in selection]
    argv = ["--test-dir", str(build_dir), "--output-on-failure"]
    if names:
        pattern = "^(" + "|".join(re.escape(name) for name in names) + ")$"
        argv += ["-R", pattern]
    argv += arguments
    env = {**toolchain_env(), "CTEST_OUTPUT_ON_FAILURE": "1"}
    if not measures(package):
        _run_ctest(package, argv, env, names)
        return
    remove_parts(root, package.path)
    env.update(_fresh_profiles(package))
    compiler_id, compiler = compiler_of(package)
    family = measurer_for(compiler_id)
    if family == "msvc":
        measured = _measure_msvc(package, argv, env, names)
    else:
        _run_ctest(package, argv, env, names)
        if not compiler_id:
            fail(
                f"{package.name}: the gate build names no C++ compiler, so no"
                " coverage measurer can be chosen: CMake names it in"
                f" {GATE_BUILD_DIR}/CMakeFiles/*/CMakeCXXCompiler.cmake when it"
                " configures, and no such file names one; configure the gate"
                f" build with `{footman.prog()} build.configure`"
            )
        if not family:
            fail(
                f"{package.name}: the gate build's compiler {compiler_id} has no"
                " coverage measurer; configure the gate build with a compiler of"
                f" one of the families {', '.join(sorted(FAMILIES))}"
            )
        measured = (
            _measure_gcov(package, compiler)
            if family == "gcov"
            else _measure_llvm(package, compiler)
        )
    kept = within(relativise(measured, root), package)
    write_part(root, package.path, kept, family)
    print(f"  {package.name}: coverage: {len(kept)} file(s) measured by {family}")

compiler_of

compiler_of(package: Package) -> tuple[str, str]

The gate build's C++ compiler id and path, as CMake detected them.

Read from the compiler file CMake writes on configure; both empty for a package whose gate build is not configured.

Source code in packages/extensions/cmake/src/livery/extensions/cmake/_build.py
def compiler_of(package: Package) -> tuple[str, str]:
    """The gate build's C++ compiler id and path, as CMake detected them.

    Read from the compiler file CMake writes on configure; both empty
    for a package whose gate build is not configured.
    """
    build_dir = package.directory / GATE_BUILD_DIR
    found = sorted(build_dir.glob("CMakeFiles/*/CMakeCXXCompiler.cmake"))
    if not found:
        return "", ""
    text = found[-1].read_text(encoding="utf-8", errors="replace")
    identity = re.search(r'set\(CMAKE_CXX_COMPILER_ID "([^"]*)"\)', text)
    compiler = re.search(r'set\(CMAKE_CXX_COMPILER "([^"]*)"\)', text)
    return (
        identity.group(1) if identity else "",
        compiler.group(1) if compiler else "",
    )

compile_commands

compile_commands(package: Package) -> Path | None

Where the package's gate build writes its compilation database.

Source code in packages/extensions/cmake/src/livery/extensions/cmake/_build.py
def compile_commands(package: Package) -> Path | None:
    """Where the package's gate build writes its compilation database."""
    return package.directory / GATE_BUILD_DIR / "compile_commands.json"