Skip to content

generation_flow.md

Latest commit

 

History

History
103 lines (82 loc) · 4.3 KB

generation_flow.md

File metadata and controls

103 lines (82 loc) · 4.3 KB
Raw

Generation Flow

End-To-End Flow

The repository turns a small MODULE.bazel declaration into a generated toolchain repository through these steps:

  1. extensions/gcc.bzl collects gcc.toolchain and gcc.sdp tags.
  2. Package metadata is resolved from packages/version_matrix.bzl or from an explicit gcc.sdp declaration.
  3. rules/gcc.bzl renders the shared templates/BUILD.template and templates/cc_toolchain_config.bzl.template into a new repository, substituting CPU, version, licensing, and flag placeholders.
  4. The rendered BUILD file wires in the toolchain's feature set: per-instance features created at generation time (extra compile/link flags, sysroot link flags, compiler library search paths) plus the ordered known_features/enabled_features lists from features/custom/linux/ or features/custom/qnx/, which reference the reusable cc_feature targets under features/native/.
  5. The consuming workspace enables the generated toolchain with --extra_toolchains and compatible platform constraints.

Subsystem Roles

packages/version_matrix.bzl

Defines the supported package matrix. Each entry maps a logical toolchain key to download metadata and, when needed, extra compiler or linker flags and archive patches.

rules/common.bzl

Provides small helpers that convert lists of flags into the Bazel flag_group representation needed by the templates and repository rules. It also defines the SDP version mappings used to map package releases to platform constraints.

rules/gcc.bzl

Generates the toolchain repository. It performs placeholder substitution and emits the final BUILD, cc_toolchain_config.bzl, and gcov wrapper files, substituting OS-specific values (e.g. compiler, abi_version, toolchain_identifier) into the shared templates below.

features/

Defines the toolchain's cc_feature / cc_args targets with @rules_cc//cc/toolchains. features/native/ holds one reusable target per toolchain feature; features/custom/linux/ and features/custom/qnx/ hold OS-specific features plus the ordered known_features/enabled_features lists that templates/BUILD.template passes to cc_toolchain_config.

Template Families

Shared templates (used by both Linux and QNX):

  • templates/cc_toolchain_config.bzl.template
  • templates/BUILD.template
  • templates/cc_gcov_wrapper.template

Important Implementation Details

  • Some package definitions rely on the %{toolchain_pkg}% placeholder, which is rewritten to the canonical Bzlmod repository name during repository-rule generation. This is handled by the _get_canonical_pkg_name() helper in rules/gcc.bzl.
  • QNX aarch64 is mapped internally to aarch64le where required by the underlying SDK layout. This normalization is a QNX-specific convention, centralized in the _normalize_cpu() helper. Linux toolchain binaries use the CPU name unchanged (e.g., aarch64-unknown-linux-gnu-gcov).
  • SDP version mapping is handled through SDP_VERSION_MAPPING in rules/common.bzl. Currently, SDP version 8.0.4 is mapped to 8.0.0 because platform constraint support uses the older identifier. This mapping is configurable for future extensibility.
  • Linux toolchains generate an extra gcov_wrapper script to work around the current rules_cc coverage integration behavior. The gcov path uses the {cpu}-unknown-linux-gnu-gcov naming convention.

Version Matrix Responsibilities

The version matrix is more than a list of URLs. It is also the place where the repository centralizes:

  • package build-file selection,
  • archive extraction prefixes,
  • sysroot-specific compiler flags,
  • extra link flags,
  • compiler library search paths,
  • runtime-ecosystem variants such as AutoSD or EB corbos Linux for Safety Applications.