diff --git a/docs/conf.py b/docs/conf.py index d07ded8..d5a02b2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,10 +10,17 @@ # # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +import importlib.util + project = "S-CORE Bazel C/C++ Toolchain configurations" project_url = "https://eclipse-score.github.io/bazel_cpp_toolchains" version = "0.1" -extensions = [ + +_optional_extensions = [ "sphinxcontrib.plantuml", "score_sphinx_bundle", ] + +extensions = [ + ext for ext in _optional_extensions if importlib.util.find_spec(ext) is not None +] diff --git a/docs/examples_and_validation.rst b/docs/examples_and_validation.rst new file mode 100644 index 0000000..08e1318 --- /dev/null +++ b/docs/examples_and_validation.rst @@ -0,0 +1,84 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Examples And Validation +======================= + +Example Workspace Purpose +------------------------- + +The ``examples/`` directory is a separate Bazel workspace used as a lightweight +integration test bed for the repository. + +It demonstrates how consumers declare toolchains while also serving as the main +smoke-test surface for validating that the generated toolchains can build and, +where appropriate, run example targets. + +Important Files +--------------- + +``examples/MODULE.bazel`` + Declares representative Linux and QNX toolchain repositories and wires the + example workspace back to the local checkout with ``local_path_override``. + +``examples/.bazelrc`` + Defines named Bazel configurations that activate the generated toolchains and + platforms. + +``examples/BUILD`` + Contains small C++ targets used to verify compilation, linking, pthread + support, and sanitizer integration. + +``examples/tests/toolchain_smoke_tests.sh`` + Matrix runner that maps each configuration name to a small build or test + sequence. + +Smoke-Test Matrix +----------------- + +The example workspace currently validates these configuration groups: + +- Linux host toolchains +- Linux cross-compilation toolchains +- runtime-specific Linux toolchains such as AutoSD and EB corbos Linux for Safety Applications +- packaged QNX toolchains +- locally built QNX SDP toolchains + +The smoke-test runner isolates Bazel state per configuration so it does not rely +on ``bazel clean --expunge`` between cases. + +Useful Commands +--------------- + +.. code-block:: bash + + cd examples + ./test.sh --list + ./test.sh host_config_1 + ./test.sh --keep-going + +What The Tests Prove +-------------------- + +The example workspace is not intended to be an exhaustive compiler correctness +suite. Instead, it answers a narrower question: did the configuration repository +produce a usable toolchain definition for each supported scenario? + +In practice this means checking: + +- successful compilation with the selected compiler and sysroot, +- correct toolchain registration and platform matching, +- basic linking behavior, +- feature coverage such as pthread-enabled builds, +- optional sanitizer feature wiring for the local Linux toolchain path. \ No newline at end of file diff --git a/docs/extension_api.rst b/docs/extension_api.rst new file mode 100644 index 0000000..8f44201 --- /dev/null +++ b/docs/extension_api.rst @@ -0,0 +1,121 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Extension API +============= + +Consumer Entry Point +-------------------- + +Consumers interact with this repository through the ``gcc`` module extension in +``@score_bazel_cpp_toolchains//extensions:gcc.bzl``. + +Typical usage looks like this: + +.. code-block:: starlark + + bazel_dep(name = "score_bazel_cpp_toolchains", version = "0.4.0") + + gcc = use_extension("@score_bazel_cpp_toolchains//extensions:gcc.bzl", "gcc") + + gcc.toolchain( + name = "score_gcc_toolchain", + target_cpu = "x86_64", + target_os = "linux", + version = "12.2.0", + use_default_package = True, + ) + + use_repo(gcc, "score_gcc_toolchain") + +Public Tags +----------- + +``gcc.toolchain(...)`` + Declares a toolchain repository to generate. + +``gcc.sdp(...)`` + Declares a package repository explicitly. This is used when the package is + not taken from the default version matrix or when local QNX SDP generation is + required. + +``gcc.toolchain(...)`` Attributes +--------------------------------- + +Required attributes: + +- ``name``: name of the generated repository +- ``target_cpu``: target CPU, currently ``x86_64`` or ``aarch64`` +- ``target_os``: target OS, currently ``linux`` or ``qnx`` + +Common package selection attributes: + +- ``use_default_package``: resolve package metadata from ``packages/version_matrix.bzl`` +- ``version``: GCC version string for Linux toolchains +- ``sdp_version``: QNX SDP version string +- ``sdk_version``: alternative SDK identifier used in matrix resolution +- ``sdp_to_link``: override the package repository name that the toolchain uses + +Flag and runtime attributes: + +- ``extra_compile_flags`` +- ``extra_c_compile_flags`` +- ``extra_cxx_compile_flags`` +- ``extra_link_flags`` +- ``ld_library_paths`` +- ``runtime_ecosystem`` +- ``use_base_constraints_only`` + +QNX-specific attributes: + +- ``license_path`` +- ``license_info_variable`` +- ``license_info_url`` + +``gcc.sdp(...)`` Attributes +--------------------------- + +The ``gcc.sdp`` tag defines the package side of the toolchain setup. Important +attributes are: + +- ``name``: repository name for the package +- ``build_file``: BUILD file that exposes the package contents as Bazel targets +- ``url`` and ``sha256``: archive or installer source +- ``strip_prefix``: extraction prefix for packaged archives +- ``mode``: ``archive`` or ``build`` +- ``patchset``: QNX SDP patchset definition used in build mode +- ``target_cpu``: target CPU used when building an SDP locally + +Activation In A Workspace +------------------------- + +Declaring a toolchain repository is not enough on its own. Consumers still need +to activate the generated toolchain during Bazel analysis, typically with a +configuration such as: + +.. code-block:: text + + --extra_toolchains=@score_gcc_toolchain//:x86_64-linux-gcc_12.2.0 + +The example workspace under ``examples/`` provides complete ``.bazelrc`` +configurations for this activation step. + +Behavior Notes +-------------- + +- The extension is intended for the root module. +- When ``use_default_package`` is enabled, the version matrix can inject extra + include and link flags required by non-standard sysroot layouts. +- QNX toolchains use additional licensing and include-path parameters that do + not apply to Linux toolchains. \ No newline at end of file diff --git a/docs/generation_flow.rst b/docs/generation_flow.rst new file mode 100644 index 0000000..ca3e227 --- /dev/null +++ b/docs/generation_flow.rst @@ -0,0 +1,98 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +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 a BUILD file and configuration files into a new + repository. +4. Platform-specific templates from ``templates/linux/`` or ``templates/qnx/`` + are populated with CPU, version, licensing, and flag information. +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. + +``rules/common.bzl`` + Provides small helpers that convert lists of flags into the Bazel + ``flag_group`` representation needed by the templates and repository rules. + +``rules/gcc.bzl`` + Generates the toolchain repository. It decides whether Linux or QNX template + content is required, performs placeholder substitution, and emits the final + ``BUILD``, ``cc_toolchain_config.bzl``, ``flags.bzl``, and Linux ``gcov`` + wrapper files. + +``rules/qnx_sdp_gen.bzl`` + Handles the special case where a QNX SDP must be built locally rather than + downloaded as a ready-made archive. + +Template Families +----------------- + +Linux templates: + +- ``templates/linux/cc_toolchain_config.bzl.template`` +- ``templates/linux/cc_toolchain_flags.bzl.template`` +- ``templates/linux/cc_gcov_wrapper.template`` + +QNX templates: + +- ``templates/qnx/cc_toolchain_config.bzl.template`` +- ``templates/qnx/cc_toolchain_flags.bzl.template`` + +Shared template: + +- ``templates/BUILD.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. +- QNX ``aarch64`` is mapped internally to ``aarch64le`` where required by the + underlying SDK layout. +- SDP version ``8.0.3`` is normalized to ``8.0.0`` in the generated toolchain + configuration because platform constraint support currently uses the older + identifier. +- Linux toolchains generate an extra ``gcov_wrapper`` script to work around the + current ``rules_cc`` coverage integration behavior. + +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. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 8ce2ace..05a65f2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,22 +11,49 @@ # # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Bazel C/C++ Toolchain Config Documentation -============================ -TBD +S-CORE Bazel C/C++ Toolchain Configuration Repository +===================================================== -.. contents:: Table of Contents - :depth: 2 - :local: +This repository contains the configuration layer for S-CORE C and C++ +toolchains used in Bazel builds. It does not ship compiler binaries. Instead, +it defines the metadata, templates, repository rules, module extension logic, +and validation workspace needed to fetch and register external toolchain +packages reproducibly. -Purpose -------- -TBD +The documentation below is organized around the main subsystems of the +repository: how consumers declare toolchains, how Bazel repositories are +generated, how platform packages are described, how the example workspace +validates the setup, and how QNX-specific authentication and licensing fit in. -Summary -------- +.. toctree:: + :maxdepth: 2 + :caption: Contents -**Library:** `Score C/C++ Toolchain configurations` + overview + repository_layout + extension_api + generation_flow + examples_and_validation + qnx_integration + maintenance -**Type:** Bazel toolchain configurations \ No newline at end of file +Quick Summary +------------- + +**Library:** S-CORE Bazel C/C++ toolchain configurations + +**Type:** Bazel module with repository rules, templates, and example validation + +**Primary consumer entry point:** ``@score_bazel_cpp_toolchains//extensions:gcc.bzl`` + +**Main validation surface:** ``examples/`` smoke-test workspace + +Key Capabilities +---------------- + +- Define Linux and QNX toolchains through a Bzlmod extension. +- Resolve default package metadata through ``packages/version_matrix.bzl``. +- Generate toolchain repositories from platform-specific templates. +- Support both packaged and locally built QNX SDP flows. +- Validate toolchain selections through the example workspace test matrix. \ No newline at end of file diff --git a/docs/maintenance.rst b/docs/maintenance.rst new file mode 100644 index 0000000..33ca5c4 --- /dev/null +++ b/docs/maintenance.rst @@ -0,0 +1,66 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Maintenance +=========== + +Adding A New Toolchain Variant +------------------------------ + +Adding support for a new toolchain variant usually touches several layers: + +1. add or extend package metadata in ``packages/version_matrix.bzl``, +2. add a package BUILD descriptor under ``packages/linux/`` or ``packages/qnx/``, +3. ensure the required template placeholders already exist, or extend the + platform template files, +4. update the example workspace if the new variant should be validated by the + smoke-test matrix, +5. add or update documentation in this Sphinx tree and the repository README. + +When To Use The Version Matrix +------------------------------ + +Use the version matrix when a package should be part of the supported default +surface for consumers. This gives downstream users a shorter configuration and +centralizes special sysroot flags in one place. + +Use explicit ``gcc.sdp(...)`` declarations when package metadata is local, +experimental, or intentionally not part of the default support matrix. + +Common Gotchas +-------------- + +- runtime-specific toolchains may need extra include and link flags that do not + exist for standard GCC archives, +- QNX ``aarch64`` naming differs from some underlying SDK paths, +- QNX licensing and authentication requirements live outside Bazel target + analysis and must be configured in the execution environment, +- documentation examples must stay aligned with actual ``examples/.bazelrc`` + configuration names. + +Recommended Validation After Changes +------------------------------------ + +For repository changes that affect toolchain resolution, package metadata, or +template generation, validate with the example workspace: + +.. code-block:: bash + + cd examples + ./test.sh --list + ./test.sh host_config_1 + ./test.sh --keep-going + +For documentation-only changes, build the Sphinx site to catch markup and +toctree issues before publishing. \ No newline at end of file diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..8ee26c0 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,71 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Overview +======== + +Purpose +------- + +The repository separates toolchain *configuration logic* from toolchain +*binary distributions*. + +It exists to answer three practical needs: + +- provide a single Bazel-native way to declare Linux and QNX C/C++ toolchains, +- keep package provenance, compiler flags, and platform constraints consistent, +- validate those toolchains through an example workspace instead of relying on + ad hoc local setup. + +What The Repository Contains +---------------------------- + +The repository does not contain GCC, QCC, or QNX SDK binaries. Instead, it +contains the layers Bazel needs in order to fetch those binaries and expose +them as ``cc_toolchain`` targets: + +- module extension logic in ``extensions/`` +- repository rules in ``rules/`` +- package metadata in ``packages/`` +- generated-file templates in ``templates/`` +- authentication helpers in ``tools/`` +- an example validation workspace in ``examples/`` + +Supported Platform Families +--------------------------- + +The current repository surface supports these platform families: + +- Linux ``x86_64`` with packaged GCC toolchains +- Linux ``aarch64`` with packaged GCC toolchains +- Linux runtime-specific variants such as AutoSD and EB corbos Linux for Safety Applications +- QNX ``x86_64`` with packaged or locally built SDP-based toolchains +- QNX ``aarch64`` with packaged or locally built SDP-based toolchains + +Core Design Model +----------------- + +The configuration pipeline is intentionally layered: + +1. A consuming project declares toolchains in ``MODULE.bazel``. +2. The ``gcc`` module extension interprets those declarations. +3. Package metadata is resolved from either the default version matrix or a + manually declared package. +4. Repository rules generate a Bazel repository containing the toolchain + definition and platform-specific configuration files. +5. The consuming project activates those toolchains via ``--extra_toolchains`` + and compatible platform constraints. + +This keeps the consuming workspace small while centralizing platform policy, +default flags, sysroot wiring, and repository authentication behavior. \ No newline at end of file diff --git a/docs/qnx_integration.rst b/docs/qnx_integration.rst new file mode 100644 index 0000000..67ab328 --- /dev/null +++ b/docs/qnx_integration.rst @@ -0,0 +1,87 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +QNX Integration +=============== + +QNX Packaging Modes +------------------- + +QNX support in this repository has two distinct modes: + +- use a prepackaged SDP archive from the version matrix, +- build an SDP locally from the QNX Software Center installer. + +Both modes eventually expose the same kind of generated toolchain repository, +but the package acquisition path is different. + +Licensing +--------- + +QNX toolchains require access to a valid license setup at execution time. +The repository exposes this through toolchain attributes rather than embedding +license material into the package itself. + +Relevant ``gcc.toolchain(...)`` attributes are: + +- ``license_path`` +- ``license_info_variable`` +- ``license_info_url`` + +The default shared license path is ``/opt/score_qnx/license/licenses``. + +Credential Helper +----------------- + +Authenticated QNX downloads are handled by the standalone script +``tools/qnx_credential_helper.py``. + +Its purpose is to translate locally available QNX credentials into the cookie +header format expected by ``qnx.com`` download endpoints. Bazel executes it via +``--credential_helper``; it is not referenced as a Bazel target. + +Supported registration patterns include: + +.. code-block:: text + + common --credential_helper=*.qnx.com=/absolute/path/to/qnx_credential_helper.py + common --credential_helper=*.qnx.com=qnx_credential_helper.py + common --credential_helper=*.qnx.com=%workspace%/path/to/qnx_credential_helper.py + +The helper reads credentials in this order: + +- ``SCORE_QNX_USER`` and ``SCORE_QNX_PASSWORD`` +- ``~/.netrc`` entry for ``qnx.com`` + +Local SDP Generation +-------------------- + +When ``gcc.sdp(..., mode = "build")`` is used, the repository rule in +``rules/qnx_sdp_gen.bzl`` performs these steps: + +1. download the QNX Software Center installer, +2. extract it locally, +3. invoke ``packages/qnx/common/sdp_gen/qnx_sdp_install.py``, +4. apply the patchset definition from ``packages/qnx/common/sdp_gen/patchset.plist``, +5. generate a BUILD file describing the installed SDP. + +Operational Notes +----------------- + +- Local SDP generation depends on external QNX infrastructure and valid + credentials. +- The repository rule currently uses fixed execution timeouts, so slow network + environments may need adjustment in the rule implementation. +- Some QNX version identifiers are normalized during generation to match the + current platform-constraint model used by the repository. \ No newline at end of file diff --git a/docs/repository_layout.rst b/docs/repository_layout.rst new file mode 100644 index 0000000..419ca73 --- /dev/null +++ b/docs/repository_layout.rst @@ -0,0 +1,78 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Repository Layout +================= + +Top-Level Structure +------------------- + +The repository is organized by subsystem rather than by platform product: + +.. code-block:: text + + . + |- docs/ Sphinx documentation sources + |- examples/ Example workspace and smoke tests + |- extensions/ Bzlmod extension entry points + |- packages/ Toolchain package descriptors and version matrix + |- rules/ Repository rules and shared helpers + |- templates/ Generated file templates for toolchain repositories + `- tools/ Standalone utility scripts + +Directory Responsibilities +-------------------------- + +``extensions/`` + Hosts the public module extension used by consumers. The main file, + ``extensions/gcc.bzl``, defines the tag classes and resolves user + declarations into repository rule invocations. + +``rules/`` + Contains the repository rules that materialize a toolchain repository. + ``rules/gcc.bzl`` renders BUILD and configuration files from templates. + ``rules/qnx_sdp_gen.bzl`` handles the special case where a QNX SDP is built + locally from the QNX Software Center installer. + +``packages/`` + Stores package metadata and BUILD descriptors for supported toolchain + archives. The most important file is ``packages/version_matrix.bzl``, which + maps logical toolchain identifiers to URLs, checksums, build files, and any + required extra flags. + +``templates/`` + Holds the template files used by repository rules. These templates are + rendered into the generated toolchain repository and differ between Linux and + QNX because the execution environment, sysroot layout, and licensing model + are different. + +``examples/`` + A standalone Bazel workspace used as an integration surface. It declares + representative toolchain configurations and validates them with a smoke-test + runner. + +``tools/`` + Contains utility scripts that Bazel executes directly, most notably the QNX + credential helper used for authenticated downloads from ``qnx.com``. + +How These Pieces Relate +----------------------- + +Each directory is part of a single flow: + +- ``packages/`` defines *what* to fetch, +- ``templates/`` define *what to generate*, +- ``rules/`` define *how to generate it*, +- ``extensions/`` define *how consumers ask for it*, +- ``examples/`` prove that the generated result actually works. \ No newline at end of file