Skip to content

Add extended documentation about toolchain model #64

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AlexanderLanin merged 2 commits into from
Jun 19, 2026
Merged

Add extended documentation about toolchain model #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5f27b23
Add Sphinx docs
nradakovic Jun 17, 2026
d4866fd
Convert all .rst into markdown
nradakovic Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
278 changes: 42 additions & 236 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,248 +1,54 @@
# S-CORE Bazel C/C++ Toolchain Configuration Repository

This repository provides the configuration layer for all S-CORE C++ toolchains used in Bazel builds.</br>
It contains **no compiler binaries**. Instead, it defines:
* Toolchain configurations
* Toolchain rules and extensions for Bzlmod
* Common compiler flags
* Templates for generating toolchain configs
* Package descriptors for external toolchain binaries
* Tests ensuring correct toolchain behavior

All toolchain binaries (GCC, QCC, etc.) are downloaded through Bazel repositories defined in consuming workspaces. </br>
This repository is structured and versioned as a Bazel module and is intended to be consumed through MODULE.bazel.

## Key Goals

* Provide a centralized, unified configuration source for all C++ toolchains used across S-CORE.
* Enforce consistency through shared flags, templates, and mandatory feature tests.
* Support multiple compilers (GCC, QCC) and multiple platforms (Linux, QNX).
* Ensure reproducible builds across architectures by separating:
* configuration logic (this repo).
* binary/toolchain distributions (external packages).
* Support plug-and-play toolchain activation via Bzlmod extensions.

## Repository Structure

```bash
.
│
├── .github # Configuration directory for GitHub operations.
├── docs # Sphinx documentation sources.
├── examples # Functional examples for toolchain validation.
├── extensions # Module extensions for GCC/QCC toolchains
│ ├── BUILD
│ └── gcc.bzl # Module extension for setting up GCC toolchains in Bazel.
├── packages # Toolchain package descriptors (no binaries)
│ ├── linux/ # Linux toolchain versions (GCC only)
│ ├── qnx/ # QNX SDP/QCC toolchain metadata
│ └── version_matrix.bzl # Supported toolchain version definitions
├── rules # Bazel rule implementations for toolchains
│ ├── BUILD
│ ├── common.bz # Common rules used by all drivers
│ └── gcc.bzl # Module rule for defining GCC toolchains in Bazel.
├── templates # Templates for toolchain definition and configuration
│ ├── linux/
│ ├── qnx/
│ ├── BUILD
│ └── BUILD.template
├── tools # Utility scripts (e.g., QNX credential helper)
├── MODULE.bazel # Module declaration for Bzlmod
├── BUILD
├── LICENSE
├── NOTICE
└── README.md
```

## Toolchain Model

This repository does not contain compiler binaries. </br>
Instead:
- Toolchain **packages** describe how to fetch compiler binaries via `http_archive` or internal artifact storage.
- Toolchain **templates** describe how Bazel should use the binaries.
- Toolchain **rules** and **extensions** generate and register toolchains.
- Toolchain **examples** validate the toolchains.
- This separation provides:
- Hermetic configurations
- Full reproducibility
- Clear ownership boundaries
- Easy addition of new compilers or versions


## Using Toolchains in a different Bazel Module

### GCC Example (Linux x86_64)

```starlark
bazel_dep(name = "score_cpp_toolchains", version = "0.1.0")
use_extension("@score_cpp_toolchains//extensions:gcc.bzl", "gcc")
gcc(
target_os = "linux",
target_cpu = "x86_64",
version = "12.2.0",
use_default_package = True,
)
use_repo(gcc, "score_gcc_toolchain")
```

### QCC Example (QNX ARM64)

```starlark
bazel_dep(name = "score_cpp_toolchains", version = "0.2.0")
use_extension("@score_cpp_toolchains//extensions:gcc.bzl", "gcc")
gcc(
target_os = "qnx",
target_cpu = "arm64",
sdp_version = "8.0.0",
version = "12.2.0",
use_default_package = True,
)
use_repo(gcc, "score_gcc_qnx_toolchain")
```

The registration of toolchains is done by adding command line option `--extra_toolchains=@<toolchain_repo>//:toolchain_name`
In case above this would be:
```bash
--extra_toolchains=@score_gcc_toolchain//:x86_64-linux-gcc-12.2.0
--extra_toolchains=@score_gcc_qnx_toolchain//:x86_64-qnx-sdp-8.0.0
```

> NOTE: In case that more than one toolchain needs to be defined, the registration must be protected via config flags otherwise</br>
the first toolchain that matches constraints will be selected by toolchain resolutions.

## Configuration Flags

Shared flag sets live under:

- [linux](templates/linux/cc_toolchain_flags.bzl.template)
- [qnx](templates/qnx/cc_toolchain_config.bzl.template)

These define:

- Base C/C++ flags
- Optimization flags
- PIC/PIE handling
- Debug and sanitizer modes
- Linker behavior
- Warning levels

## Templates

Templates define how toolchain files are generated:

- `BUILD.template`
- `cc_toolchain_config.bzl.template`
- `cc_gcov_wrapper.template`
- `cc_toolchain_flags.bzl.template`

These templates simplify adding:
<!--
# *******************************************************************************
# 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
# *******************************************************************************
-->

- New compiler versions
- New compiler families
- New OS/arch combinations

## Testing and Validation

Testing is part of the **integration gate pipeline**.

## Examples

Example cover:

- Simple compilation ( [examples/main.cpp](./examples/main.cpp))
- Toolchain registration behavior ([examples/.bazelrc](./examples/.bazelrc))

# Documentation

Documentation uses **Sphinx** and lives in `docs/`. (Not yet prepared!)

# QNX License

## Local License File

By default, the QNX toolchain uses `/opt/score_qnx/license/licenses` as the license path.
If you want to change this location, you can override it by setting the `license_path` variable
when calling the `gcc.toolchain(...)` function in your `MODULE.bazel` file.

**Example:**

```bazel
gcc.toolchain(
name = "score_qcc_toolchain",
target_os = "qnx",
...
license_path = "/path/to/your/custom/licenses",
)
```

> **TODO:** Is it possible to set this via environment variable?

## License Servers

In case you are using a license server for QNX licenses (FLEXlm), you can set the license server information
either locally in your module or centrally in your bazel configuration.
This also applies to floating licenses.

### Module Local Configuration

You can set the license server for your toolchains by setting the variables `license_info_variable` and
`license_info_url` when calling the `gcc.toolchain(...)` function in your `MODULE.bazel` file.

**Example (for QNXLM_LICENSE_FILE variable):**

```bazel
gcc.toolchain(
name = "score_qcc_toolchain",
target_os = "qnx",
...
license_info_variable = "QNXLM_LICENSE_FILE",
license_info_url = "<port>@<license_server_host>",
)
```

### Central Configuration

In case you want to set the license server for all your bazel projects you can set the
environment variable in your `~/.bazelrc` file:

**Example (for QNXLM_LICENSE_FILE variable):**

```bazel
common --action_env=QNXLM_LICENSE_FILE=<port>@<license_server_host>
```

In case you do not want to set it for all commands you can also set it per build/test command:

```bazel
build --action_env=QNXLM_LICENSE_FILE=<port>@<license_server_host>
test --action_env=QNXLM_LICENSE_FILE=<port>@<license_server_host>
```
# S-CORE Bazel C/C++ Toolchain Configuration Repository

# Adding New Toolchain Versions
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.

1. Update `packages/version_matrix.bzl`
2. Add a package descriptor (e.g., `packages/linux/x86_64/gcc/13.1.0`)
3. Generate configuration from templates
4. Update flags if needed
5. Submit through integration gate
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.

---
## Documentation

# Tools
- [Overview](docs/overview.md)
- [Repository layout](docs/repository_layout.md)
- [Extension API](docs/extension_api.md)
- [Generation flow](docs/generation_flow.md)
- [Examples and validation](docs/examples_and_validation.md)
- [QNX integration](docs/qnx_integration.md)
- [Maintenance](docs/maintenance.md)

Utility scripts such as:
## Quick Summary

```
tools/qnx_credential_helper.py
```
**Module:** S-CORE Bazel C/C++ toolchain configurations

are used for repository authentication flows.
**Type:** Bazel module with repository rules, templates, and example validation

---
**Primary consumer entry point:** `@score_bazel_cpp_toolchains//extensions:gcc.bzl`

# License
**Main validation surface:** `examples/` smoke-test workspace

Distributed under:
## Key Capabilities

- `LICENSE`
- `NOTICE`
- 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.
- Validate toolchain selections through the example workspace test matrix.
19 changes: 0 additions & 19 deletions docs/conf.py
View file
Open in desktop

This file was deleted.

82 changes: 82 additions & 0 deletions docs/examples_and_validation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
<!--
# *******************************************************************************
# 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/test.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

The smoke-test runner isolates Bazel state per configuration so it does not
rely on `bazel clean --expunge` between cases.

## Useful Commands

```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 among other things:

- 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.
Loading
Loading