quoll-cli 0.2.0__py3-none-any.whl

quoll/languages/base.py

@@ -0,0 +1,350 @@
+"""The contract every language and framework plugin implements.
+
+A language is a `Language` instance that bundles:
+- what identifies it (`markers`) and what quoll.toml may contain for it (package managers, tools);
+- `detect`, which inspects a project and returns a `Detection`;
+- `ci`, a `CISteps` implementation that turns the validated [ci] config into platform-neutral steps
+  (quoll.ci.steps), which each CI platform renders;
+- its `frameworks`, tried in order once the language is known.
+
+A framework (`Framework`) refines the language: it adjusts the detection (test runner, tools...) and
+can add its own lint tools, test runner, environment and steps through a `FrameworkCI`.
+
+Both can ship a `DockerImage`; a framework's replaces its language's, and `Starter`s creating new projects
+(`quoll new`).
+"""
+from __future__ import annotations
+
+import inspect
+import json
+import shlex
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+from jinja2 import Environment, FileSystemLoader, PrefixLoader, StrictUndefined
+
+from quoll.ci.steps import Cache, Item, Step
+from quoll.platforms.base import Remote
+from quoll.project import Project
+from quoll.services import ServiceEnv, no_service_env
+
+if TYPE_CHECKING:
+    from quoll.ci.config import CIConfig
+    from quoll.docker.config import DockerConfig
+
+__all__ = ["Cache", "Item", "Step"]
+
+# Languages with `scripts=True` also accept "script:<name>" as a lint tool or test runner.
+SCRIPT_PREFIX = "script:"
+
+
+@dataclass
+class Detection:
+    """What quoll inferred about a project. Languages fill the toolchain fields; quoll fills the rest."""
+
+    stack: Optional[str] = None
+    framework: str = ""
+    package_manager: str = ""
+    package_manager_version: str = ""
+    lockfile: str = ""
+    install: str = ""
+    cache: bool = True
+    version: str = ""
+    version_file: str = ""
+    matrix_versions: List[str] = field(default_factory=list)
+    source_dir: str = "."
+    lint_tools: List[str] = field(default_factory=list)
+    test_runner: str = ""
+    coverage: bool = True
+    # The language can run its tests under sanitizers (C/C++).
+    sanitizers: bool = False
+    # A dependency audit exists for the project (e.g. a lock file the scanner reads).
+    audit: bool = True
+    build_command: str = ""
+    # Backing services the app uses (see quoll.services), from its client libraries.
+    services: List[str] = field(default_factory=list)
+    # Filled by quoll, not by languages.
+    has_dockerfile: bool = False
+    # Directory of the project's Helm chart ([k8s] in quoll.toml).
+    chart: str = ""
+    env_vars: Dict[str, str] = field(default_factory=dict)
+    default_branch: str = "main"
+    platform: str = "github"
+    remote: Optional[Remote] = None
+    other_stacks: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+
+class CISteps(ABC):
+    """CI steps for one language. `cfg` is the validated [ci] section of quoll.toml.
+
+    The toolchain comes from `setup` on GitHub Actions (setup actions on a bare runner) and from `image` plus
+    `image_setup` on GitLab CI (jobs run in containers). Every other method returns steps for both: a step that
+    uses a GitHub Action must also give the equivalent `run` command.
+    """
+
+    # Matrix variable, e.g. "python-version".
+    version_key: str = ""
+    # False when the audit action installs the toolchain itself (GitHub).
+    audit_needs_setup: bool = True
+    # False when the audit only reads the lockfile: the toolchain's dependency cache would have nothing to save.
+    audit_uses_cache: bool = True
+    # CodeQL language (https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/), empty
+    # when CodeQL doesn't support it; "autobuild" when the code must be compiled to be analyzed.
+    codeql_language: str = ""
+    codeql_build_mode: str = "none"
+
+    @abstractmethod
+    def setup(self, cfg: CIConfig, version: Optional[str]) -> List[Item]:
+        """GitHub Actions steps installing the toolchain. `version` is None when read from `cfg.version_file`."""
+
+    @abstractmethod
+    def image(self, cfg: CIConfig, version: str) -> str:
+        """Container image providing the toolchain at `version` (which may be a variable such as $NODE_VERSION)."""
+
+    def image_setup(self, cfg: CIConfig) -> List[Step]:
+        """Commands completing `image` before the job's steps (package manager, components...)."""
+        return []
+
+    def cache(self, cfg: CIConfig) -> Optional[Cache]:
+        """Dependency cache of container jobs; on GitHub, `setup` caches."""
+        return None
+
+    @abstractmethod
+    def install(self, cfg: CIConfig, packages: Sequence[str] = ()) -> List[Item]:
+        """Install the project dependencies, plus extra CI-only `packages` where the language supports it."""
+
+    def exec(self, cfg: CIConfig, command: str) -> str:
+        """`command` run with the project's installed tools (e.g. `uv run --no-sync`, `npx`)."""
+        return command
+
+    @abstractmethod
+    def lint(self, cfg: CIConfig, tools: List[str]) -> List[Item]:
+        """Install dependencies and run `tools`, a subset of the language's lint tools."""
+
+    @abstractmethod
+    def test(self, cfg: CIConfig) -> List[Item]:
+        """Install dependencies and run the tests, enforcing the coverage threshold when enabled."""
+
+    @abstractmethod
+    def coverage_file(self, cfg: CIConfig) -> str:
+        """Coverage report uploaded to Codecov (a glob for some languages)."""
+
+    def reports(self, cfg: CIConfig) -> TestReports:
+        """What the test steps leave for the platform to show, when `cfg.test.reports` is on."""
+        return TestReports()
+
+    @abstractmethod
+    def audit(self, cfg: CIConfig) -> List[Item]:
+        """Scan dependencies for known vulnerabilities."""
+
+    @abstractmethod
+    def build(self, cfg: CIConfig) -> List[Item]:
+        """Run `cfg.build.command`."""
+
+    def build_artifacts(self, det: Detection) -> List[str]:
+        """What the detected build command produces, for the build job to keep (nothing if not a distributable)."""
+        return []
+
+    @abstractmethod
+    def dependabot_ecosystem(self, cfg: CIConfig) -> str:
+        """Dependabot `package-ecosystem` for the project's dependencies."""
+
+
+# Runtime images on Debian or Ubuntu: the security fixes released since the base image was built (the image scan
+# fails on them otherwise, and rebuilding picks up the next ones).
+OS_UPDATES = """# Security fixes released since the base image was built.
+RUN apt-get update \\
+    && DEBIAN_FRONTEND=noninteractive apt-get upgrade -y \\
+    && rm -rf /var/lib/apt/lists/*"""
+
+# The line printed by quoll's own coverage threshold checks: "Coverage 85.0% (threshold 80%)".
+THRESHOLD_REGEX = r"/Coverage (\d+(?:\.\d+)?)% \(threshold/"
+
+
+@dataclass(frozen=True)
+class TestReports:
+    __test__ = False  # not a pytest test class
+
+    # JUnit XML results (a glob).
+    junit: str = ""
+    # Cobertura XML coverage, shown on the diff of merge requests (GitLab).
+    cobertura: str = ""
+    # Regex extracting the total coverage from the job log (GitLab badge and MR widget).
+    coverage_regex: str = ""
+
+
+class FrameworkCI:
+    """Optional framework hooks. The defaults add nothing, so a framework only overrides what it changes."""
+
+    def env(self, cfg: CIConfig) -> Dict[str, str]:
+        """Environment variables for the whole workflow."""
+        return {}
+
+    def lint(self, cfg: CIConfig, tool: str) -> List[Item]:
+        """Steps for one of the framework's lint tools, run after the language's (dependencies installed)."""
+        raise NotImplementedError(f"{type(self).__name__} declares lint tool '{tool}' but does not implement it")
+
+    def test(self, cfg: CIConfig) -> List[Item]:
+        """Full test steps when `cfg.test.runner` is one of the framework's test runners."""
+        raise NotImplementedError(f"{type(self).__name__} declares a test runner but does not implement it")
+
+    def before_build(self, cfg: CIConfig) -> List[Item]:
+        """Steps before the build (e.g. a framework build cache)."""
+        return []
+
+
+@dataclass
+class DockerDefaults:
+    """What an image infers from the project; becomes the [docker] section of quoll.toml."""
+
+    port: int
+    command: str = ""
+    build_command: str = ""
+    output_dir: str = ""
+    static: bool = False
+    warnings: List[str] = field(default_factory=list)
+
+
+class DockerImage(ABC):
+    """A Dockerfile, rendered from the `Dockerfile.j2` next to the class (or its closest parent's).
+
+    Images inherit like their classes. A framework image subclasses its language's: it overrides `defaults`
+    (port, command) or `context`, and when the image itself differs, ships a Dockerfile.j2 that extends the
+    language's and overrides only the stages (blocks) that change:
+
+        {% extends "node/Dockerfile.j2" %}
+        {% block app_files %}...{% endblock %}
+
+    Templates are addressed as "<directory>/Dockerfile.j2", e.g. "node/Dockerfile.j2".
+    """
+
+    # False when the base image already runs a server (e.g. FrankenPHP).
+    requires_command: bool = True
+
+    @abstractmethod
+    def defaults(self, project: Project, det: Detection) -> DockerDefaults:
+        """Port, start command and build settings inferred from the project."""
+
+    def context(self, project: Project, cfg: DockerConfig) -> Dict[str, Any]:
+        """Template variables besides `cfg`."""
+        return {}
+
+    def dockerignore(self, cfg: DockerConfig) -> List[str]:
+        """Patterns to keep out of the build context, on top of the common ones."""
+        return []
+
+    def writable_paths(self, cfg: DockerConfig) -> Optional[List[str]]:
+        """Directories the app writes to: Kubernetes mounts them on a read-only root filesystem. None: the app
+        writes in its own tree, the root filesystem stays writable."""
+        return ["/tmp"]
+
+    def render(self, project: Project, cfg: DockerConfig) -> str:
+        dirs = self._template_dirs()
+        env = Environment(
+            loader=PrefixLoader({d.name: FileSystemLoader(str(d)) for d in dirs}),
+            keep_trailing_newline=True,
+            trim_blocks=True,
+            lstrip_blocks=True,
+            undefined=StrictUndefined,
+        )
+        env.filters["exec_form"] = exec_form
+        env.globals["os_updates"] = OS_UPDATES
+        return env.get_template(f"{dirs[0].name}/Dockerfile.j2").render(cfg=cfg, **self.context(project, cfg))
+
+    def _template_dirs(self) -> List[Path]:
+        """Directories holding a Dockerfile.j2, from this class up to its oldest ancestor."""
+        dirs: List[Path] = []
+        for cls in type(self).__mro__:
+            if cls in (DockerImage, ABC, object):
+                continue
+            directory = Path(inspect.getfile(cls)).parent
+            if (directory / "Dockerfile.j2").exists() and directory not in dirs:
+                dirs.append(directory)
+        return dirs
+
+
+def exec_form(command: str) -> str:
+    """JSON (exec) form of a command, so the process receives signals; through `sh -c` if it needs a shell."""
+    if any(c in command for c in "$&|;<>*`") or "\n" in command:
+        return json.dumps(["sh", "-c", command])
+    return json.dumps(shlex.split(command))
+
+
+@dataclass(frozen=True)
+class StarterOptions:
+    # Package name of the new project.
+    name: str
+    # Version of the framework, e.g. "18" for Angular 18 (empty: the latest).
+    version: str = ""
+    # Version of the language's runtime, e.g. "20" for Node.js 20 (empty: the starter's default).
+    runtime: str = ""
+
+
+@dataclass(frozen=True)
+class Starter:
+    """Creates a new project in an empty directory (see quoll.starters for templates and generators)."""
+
+    # Key used on the command line: `quoll new --front angular` (`angular@18` for a version).
+    name: str
+    label: str
+    # Where it fits in a front-end + back-end repository: "front" or "back".
+    role: str
+    # (directory, options) -> warnings for the user (e.g. an unsupported version). The directory exists, empty.
+    create: Callable[[Path, StarterOptions], Optional[List[str]]]
+    # The runtime `runtime` options are for: `quoll new --node 20`.
+    runtime: str = ""
+    runtime_default: str = ""
+    # Front-ends: (directory, path, url) makes the dev server forward `path` (e.g. "/api") to the API at `url`, as
+    # nginx does in the image ([docker] proxy).
+    proxy: Optional[Callable[[Path, str, str], None]] = None
+
+
+@dataclass(frozen=True)
+class Framework:
+    name: str
+    # Name of the language it belongs to.
+    language: str
+    # Returns True when the framework is used, and may refine the detection (tools, test runner...).
+    detect: Callable[[Project, Detection], bool]
+    ci: FrameworkCI = field(default_factory=FrameworkCI)
+    lint_tools: Tuple[str, ...] = ()
+    test_runners: Tuple[str, ...] = ()
+    # Replaces the language's image when set.
+    docker: Optional[DockerImage] = None
+    # Extra variables pointing the app at a service, e.g. Laravel's DB_HOST.
+    service_env: ServiceEnv = no_service_env
+    starters: Tuple[Starter, ...] = ()
+
+
+@dataclass(frozen=True)
+class Language:
+    name: str
+    # Any of these files (or glob patterns) at the project root identifies the language.
+    markers: Tuple[str, ...]
+    package_managers: Tuple[str, ...]
+    lint_tools: Tuple[str, ...]
+    test_runners: Tuple[str, ...]
+    detect: Callable[[Project], Detection]
+    ci: CISteps
+    # Tried in order: the first whose detect() returns True is the project's framework.
+    frameworks: Tuple[Framework, ...] = ()
+    scripts: bool = False
+    docker: Optional[DockerImage] = None
+    # Extra variables pointing the app at a service, e.g. Spring's datasource URL.
+    service_env: ServiceEnv = no_service_env
+    starters: Tuple[Starter, ...] = ()
+
+    def matches(self, project: Project) -> bool:
+        return project.glob_any(*self.markers)
+
+    def is_lint_tool(self, value: str) -> bool:
+        return value in self.lint_tools or self._is_script(value)
+
+    def is_test_runner(self, value: str) -> bool:
+        return value in self.test_runners or self._is_script(value)
+
+    def _is_script(self, value: str) -> bool:
+        return self.scripts and value.startswith(SCRIPT_PREFIX) and len(value) > len(SCRIPT_PREFIX)

quoll/languages/cpp/Dockerfile.j2

@@ -0,0 +1,37 @@
+{% block build %}
+FROM gcc:{{ gcc_tag }} AS build
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update \
+    && apt-get install -y --no-install-recommends {{ packages }}
+WORKDIR /src
+COPY . .
+{% if conan %}
+# Conan resolves the dependencies; its toolchain file points CMake at them.
+RUN --mount=type=cache,target=/root/.conan2 \
+    pipx run conan profile detect --exist-ok \
+    && pipx run conan install . --output-folder=build --build=missing -s build_type=Release
+ENV CMAKE_TOOLCHAIN_FILE=/src/build/conan_toolchain.cmake
+{% endif %}
+{% if vcpkg %}
+RUN git clone --depth 1 https://github.com/microsoft/vcpkg /opt/vcpkg \
+    && /opt/vcpkg/bootstrap-vcpkg.sh -disableMetrics
+ENV VCPKG_ROOT=/opt/vcpkg \
+    CMAKE_TOOLCHAIN_FILE=/opt/vcpkg/scripts/buildsystems/vcpkg.cmake
+{% endif %}
+# libstdc++ and libgcc linked statically: the runtime image only needs glibc.
+ENV LDFLAGS="-static-libstdc++ -static-libgcc"
+RUN {% if vcpkg %}--mount=type=cache,target=/root/.cache/vcpkg {% endif %}{{ cfg.build_command }} \
+    && mkdir -p /out \
+    && cp "$(find build -type f -name '{{ target }}' -perm -u+x | head -n 1)" /out/app
+{% endblock %}
+
+{% block runtime %}
+# distroless/cc: glibc only, no shell, no package manager, non-root.
+FROM gcr.io/distroless/cc-debian13:nonroot
+COPY --from=build /out/app /app
+# distroless' nonroot, numeric: Kubernetes can then check it isn't root (runAsNonRoot).
+USER 65532:65532
+EXPOSE {{ cfg.port }}
+CMD {{ cfg.command | exec_form }}
+{% endblock %}

quoll/languages/cpp/__init__.py

@@ -0,0 +1,17 @@
+"""C and C++: CMake (plain, Conan or vcpkg) and Meson."""
+
+from quoll.languages.base import Language
+from quoll.languages.cpp.ci import CppCI
+from quoll.languages.cpp.detect import detect
+from quoll.languages.cpp.docker import CppImage
+
+language = Language(
+    name="cpp",
+    markers=("CMakeLists.txt", "meson.build"),
+    package_managers=("cmake", "conan", "vcpkg", "meson"),
+    lint_tools=("clang-format", "clang-tidy", "cppcheck"),
+    test_runners=("ctest", "meson"),
+    detect=detect,
+    ci=CppCI(),
+    docker=CppImage(),
+)

quoll/languages/cpp/ci.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Optional, Sequence
+
+from quoll.ci.steps import Item, Step, step
+from quoll.ci.tools import install_osv_scanner
+from quoll.languages.base import CISteps, TestReports
+
+if TYPE_CHECKING:
+    from quoll.ci.config import CIConfig
+
+# Ubuntu 24.04 on both platforms (GitHub's runner, GitLab's image): the toolchain comes from its packages.
+IMAGE = "ubuntu:24.04"
+SOURCES = "'*.c' '*.cc' '*.cpp' '*.cxx' '*.h' '*.hh' '*.hpp' '*.hxx'"
+COVERAGE_REGEX = r"/^TOTAL\s+\d+\s+\d+\s+(\d+(?:\.\d+)?)%/"
+
+# Installs "<gcc|clang>-<major>" and exports CC, CXX and GCOV (gcovr reads clang's coverage through llvm-cov),
+# for the next steps too on GitHub.
+_TOOLCHAIN = """compiler="{compiler}"
+case "$compiler" in
+  gcc-*)
+    v="${{compiler#gcc-}}"; packages="gcc-$v g++-$v"; cc="gcc-$v"; cxx="g++-$v"; gcov="gcov-$v" ;;
+  clang-*)
+    v="${{compiler#clang-}}"; packages="clang-$v llvm-$v"; cc="clang-$v"; cxx="clang++-$v"; gcov="llvm-cov-$v gcov" ;;
+  *) echo "Unknown compiler '$compiler' (expected gcc-<major> or clang-<major>)"; exit 1 ;;
+esac
+sudo=""; [ "$(id -u)" -eq 0 ] || sudo=sudo
+$sudo apt-get update -qq
+# shellcheck disable=SC2086 # $packages lists several packages
+$sudo env DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends \\
+  $packages {tools}
+export CC="$cc" CXX="$cxx" GCOV="$gcov"
+if [ -n "${{GITHUB_ENV:-}}" ]; then printf 'CC=%s\\nCXX=%s\\nGCOV=%s\\n' "$cc" "$cxx" "$gcov" >> "$GITHUB_ENV"; fi"""
+
+# vcpkg is preinstalled on GitHub's runners; elsewhere it is bootstrapped once per job.
+_VCPKG = """if [ -z "${VCPKG_ROOT:-}" ]; then
+  if [ -n "${VCPKG_INSTALLATION_ROOT:-}" ]; then
+    VCPKG_ROOT="$VCPKG_INSTALLATION_ROOT"
+  else
+    git clone --quiet --depth 1 https://github.com/microsoft/vcpkg "$HOME/vcpkg"
+    "$HOME/vcpkg/bootstrap-vcpkg.sh" -disableMetrics
+    VCPKG_ROOT="$HOME/vcpkg"
+  fi
+fi"""
+
+_CLANG_FORMAT = f"git ls-files -z {SOURCES} | xargs -0 -r clang-format --dry-run --Werror"
+# Sources of the project only: FetchContent dependencies are built under build/.
+_CLANG_TIDY = 'run-clang-tidy -p build -quiet "^$PWD/(?!build/)"'
+_CPPCHECK = (
+    "cppcheck --project=build/compile_commands.json -ibuild --enable=warning,style,performance,portability "
+    "--inline-suppr --suppress=missingIncludeSystem --error-exitcode=1 --quiet"
+)
+
+
+class CppCI(CISteps):
+    version_key = "compiler"
+    codeql_language = "c-cpp"
+    # CodeQL watches our own configure + build (dependencies included).
+    codeql_build_mode = "manual"
+
+    def setup(self, cfg: CIConfig, version: Optional[str]) -> List[Item]:
+        return [self._toolchain(cfg, version or cfg.versions[-1])]
+
+    def image(self, cfg: CIConfig, version: str) -> str:
+        return IMAGE
+
+    def image_setup(self, cfg: CIConfig) -> List[Step]:
+        # In a matrix job, COMPILER is the entry's.
+        return [self._toolchain(cfg, f"${{COMPILER:-{cfg.versions[-1]}}}")]
+
+    def install(self, cfg: CIConfig, packages: Sequence[str] = ()) -> List[Item]:
+        return [configure(cfg)]
+
+    def lint(self, cfg: CIConfig, tools: List[str]) -> List[Item]:
+        steps: List[Item] = []
+        if "clang-format" in tools:
+            steps.append(step("clang-format", run=_CLANG_FORMAT))
+        if "clang-tidy" in tools or "cppcheck" in tools:
+            # Both read the compilation database written by the configure step.
+            steps.append(configure(cfg))
+        if "clang-tidy" in tools:
+            steps.append(step("clang-tidy", run=_CLANG_TIDY))
+        if "cppcheck" in tools:
+            steps.append(step("cppcheck", run=_CPPCHECK))
+        return steps
+
+    def test(self, cfg: CIConfig) -> List[Item]:
+        t = cfg.test
+        meson = cfg.package_manager == "meson"
+        env = {}
+        if t.sanitizers:
+            env = {"ASAN_OPTIONS": "detect_leaks=1:abort_on_error=1", "UBSAN_OPTIONS": "print_stacktrace=1"}
+        if meson:
+            run = "meson compile -C build\nmeson test -C build --print-errorlogs"
+        else:
+            run = "cmake --build build\nctest --test-dir build --output-on-failure"
+            if t.reports:
+                run += " --output-junit junit.xml"
+        name = "Tests" + (" with sanitizers" if t.sanitizers else "")
+        steps: List[Item] = [configure(cfg, instrumented=True), step(name, run=run, env=env, secrets=t.env_secrets)]
+        if t.coverage:
+            command = (
+                'gcovr --root . --exclude build/ --exclude "(.+/)?tests?/" --gcov-executable "$GCOV" '
+                f"--txt --cobertura coverage.xml --fail-under-line {t.coverage_threshold}"
+            )
+            steps.append(step("Coverage threshold", run=command))
+        return steps
+
+    def coverage_file(self, cfg: CIConfig) -> str:
+        return "coverage.xml"
+
+    def reports(self, cfg: CIConfig) -> TestReports:
+        junit = "build/meson-logs/testlog.junit.xml" if cfg.package_manager == "meson" else "build/junit.xml"
+        coverage = cfg.test.coverage
+        return TestReports(
+            junit=junit,
+            cobertura="coverage.xml" if coverage else "",
+            coverage_regex=COVERAGE_REGEX if coverage else "",
+        )
+
+    def audit(self, cfg: CIConfig) -> List[Item]:
+        scan = step("Dependency vulnerability scan", run="osv-scanner scan source -L conan.lock")
+        return [install_osv_scanner(), scan]
+
+    def build(self, cfg: CIConfig) -> List[Item]:
+        default = "meson compile -C build" if cfg.package_manager == "meson" else "cmake --build build"
+        return [configure(cfg, release=True), step("Build", run=cfg.build.command or default)]
+
+    def dependabot_ecosystem(self, cfg: CIConfig) -> str:
+        # Dependabot has no ecosystem for CMake, Conan or Meson.
+        return ""
+
+    def _toolchain(self, cfg: CIConfig, compiler: str) -> Step:
+        tools = ["ca-certificates", "git", "ninja-build"]
+        tools.append("meson" if cfg.package_manager == "meson" else "cmake")
+        if cfg.package_manager == "conan":
+            tools.append("pipx")
+        if cfg.package_manager == "vcpkg":
+            tools += ["curl", "zip", "unzip", "tar", "pkg-config"]
+        if cfg.lint.enabled:
+            tools += [{"clang-format": "clang-format", "clang-tidy": "clang-tidy", "cppcheck": "cppcheck"}[t]
+                      for t in cfg.lint.tools if t in ("clang-format", "clang-tidy", "cppcheck")]
+        if cfg.test.enabled and cfg.test.coverage:
+            tools.append("gcovr")
+        if cfg.security.audit:
+            tools.append("curl")
+        tools_list = " ".join(dict.fromkeys(tools))
+        if "${{" in compiler:
+            # An expression (the setup action's input): through the environment, never pasted into the script.
+            run = _TOOLCHAIN.format(compiler="$QUOLL_COMPILER", tools=tools_list)
+            return step("Set up the toolchain", run=run, env={"QUOLL_COMPILER": compiler})
+        return step("Set up the toolchain", run=_TOOLCHAIN.format(compiler=compiler, tools=tools_list))
+
+
+def configure(cfg: CIConfig, instrumented: bool = False, release: bool = False) -> Step:
+    """Configure the build in build/ (compilation database included), resolving the dependencies.
+
+    `instrumented` adds coverage and sanitizers (tests); `release` builds optimized (build job).
+    """
+    t = cfg.test
+    flags: List[str] = []
+    if instrumented and t.coverage:
+        flags.append("--coverage")
+    if instrumented and t.sanitizers:
+        flags.append("-fsanitize=address,undefined -fno-sanitize-recover=all -fno-omit-frame-pointer")
+    build_type = "Release" if release else "Debug"
+
+    if cfg.package_manager == "meson":
+        options = [f"--buildtype={build_type.lower()}"]
+        if instrumented and t.coverage:
+            options.append("-Db_coverage=true")
+        if instrumented and t.sanitizers:
+            options.append("-Db_sanitize=address,undefined -Dc_args=-fno-sanitize-recover=all "
+                           "-Dcpp_args=-fno-sanitize-recover=all")
+        return step("Configure", run=f"meson setup build {' '.join(options)}")
+
+    lines: List[str] = []
+    args = [f"-DCMAKE_BUILD_TYPE={build_type}", "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON"]
+    if flags:
+        joined = " ".join(flags)
+        args += [f'-DCMAKE_C_FLAGS="{joined}"', f'-DCMAKE_CXX_FLAGS="{joined}"']
+    if cfg.package_manager == "conan":
+        lines += [
+            "pipx run conan profile detect --exist-ok",
+            f"pipx run conan install . --output-folder=build --build=missing -s build_type={build_type}",
+        ]
+        args.append("-DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake")
+    elif cfg.package_manager == "vcpkg":
+        lines.append(_VCPKG)
+        args.append('-DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"')
+    lines.append(f"cmake -S . -B build -G Ninja {' '.join(args)}")
+    return step("Configure", run="\n".join(lines))