Skip to content

Commit 0f09f1e

Browse files
nradakovicnradakovic
committed
Add list of toolchain features
1 parent 73728e2 commit 0f09f1e

3 files changed

Lines changed: 365 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ validates the setup, and how QNX-specific authentication and licensing fit in.
3232
- [Repository layout](docs/repository_layout.md)
3333
- [Extension API](docs/extension_api.md)
3434
- [Generation flow](docs/generation_flow.md)
35+
- [Linux toolchain feature set](docs/linux_toolchain_feature_set.md)
36+
- [QNX toolchain feature set](docs/qnx_toolchain_feature_set.md)
3537
- [Tests and validation](docs/tests_and_validation.md)
3638
- [QNX integration](docs/qnx_integration.md)
3739
- [Test Suite](docs/test_suite.md)

‎docs/linux_toolchain_feature_set.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
<!--
2+
# *******************************************************************************
3+
# Copyright (c) 2026 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
-->
15+
16+
# Linux Toolchain Required Feature Set
17+
18+
## Purpose
19+
20+
This document lists the feature set required for the Linux (GCC) C/C++
21+
toolchains generated from
22+
[templates/linux/cc_toolchain_config.bzl.template](../templates/linux/cc_toolchain_config.bzl.template),
23+
and classifies how each feature is currently provided. It is intended to drive
24+
implementation, validation, and documentation follow-up when moving the Linux
25+
toolchain to an explicit, `no_legacy_features`-based configuration.
26+
27+
## How Features Are Resolved
28+
29+
The Linux template **does not** enable the `no_legacy_features` feature.
30+
As a result, Bazel automatically injects its full legacy feature set around the
31+
features we declare. Every feature below is therefore in one of three states:
32+
33+
| Classification | Meaning |
34+
|---|---|
35+
| **Explicit** | Defined in this template and present in the `features` list (or wired through an `action_config` / `tool_path`). |
36+
| **Injected** | Not defined by us. Supplied automatically by Bazel's legacy feature injection because `no_legacy_features` is not enabled. |
37+
| **Implicit** | Behavior provided without a dedicated feature — via `action_config` tool bindings, `builtin_sysroot`, `cxx_builtin_include_directories`, `tool_paths`, an `implies` reference, or flags baked into another explicit feature. |
38+
39+
> Consequence: if `no_legacy_features` is enabled for Linux, every **Injected**
40+
> feature marked *Required* below must be added explicitly, or the toolchain
41+
> will stop compiling/linking.
42+
43+
## Required Feature Set
44+
45+
### Compilation
46+
47+
| Feature | Purpose | Required | Classification | Notes |
48+
|---|---|---|---|---|
49+
| `default_compile_flags` | Base compile flags (`-fPIC`, hardening, arch, build-mode variants) | Yes | Explicit | In `features` list. |
50+
| `unfiltered_compile_flags` | Redact `__DATE__`/`__TIME__`/`__TIMESTAMP__` for reproducibility | Yes | Explicit | In `features` list. |
51+
| `include_paths` | Emit `-I`, `-iquote`, `-isystem` | Yes | **Injected** | Legacy default. |
52+
| `preprocessor_defines` | Emit `-D` defines | Yes | **Injected** | Legacy default. |
53+
| `user_compile_flags` | Pass through per-target `copts` | Yes | **Injected** | Legacy default. Distinct from our `extra_*_compile_flags`. |
54+
| `compiler_input_flags` | `-c` and source input | Yes | **Injected** | Legacy default. |
55+
| `compiler_output_flags` | `-o` / `-S` / `-E` output | Yes | **Injected** | Legacy default. |
56+
| `dependency_file` | Generate `.d` header deps (`-MD`) | Yes | **Injected** | Legacy default. Required for correct incremental builds. |
57+
| `pic` | Emit `-fPIC` from the `pic` build variable | Yes | **Injected** + Implicit | Legacy default; `-fPIC` is also baked into `default_compile_flags`. |
58+
| `random_seed` | Deterministic `-frandom-seed` per output | Optional | Not provided | No feature; relies on compiler default. |
59+
60+
### Linking
61+
62+
| Feature | Purpose | Required | Classification | Notes |
63+
|---|---|---|---|---|
64+
| `default_link_flags` | Hardening, `--as-needed`, `--gc-sections`, libc++/libm | Yes | Explicit | In `features` list. |
65+
| `user_link_flags` | Pass through per-target `linkopts` | Yes | **Injected** | Legacy default. Distinct from our `extra_link_flags`. |
66+
| `output_execpath_flags` | `-o` for link output | Yes | **Injected** | Legacy default. |
67+
| `library_search_directories` | Emit `-L` search paths | Yes | **Injected** | Legacy default. |
68+
| `runtime_library_search_directories` | Emit `-rpath` | Yes | **Injected** | Legacy default. |
69+
| `libraries_to_link` | Emit `-l` / object linking, whole-archive, static/dynamic | Yes | **Injected** | Legacy default. |
70+
| `shared_flag` | `-shared` for dynamic libraries | Yes | **Injected** | Legacy default. |
71+
| `linker_param_file` | `@param_file` for long link commands | Yes | **Injected** | Legacy default. |
72+
| `force_pic_flags` | `-pie` for position-independent executables | Optional | **Injected** | Legacy default. |
73+
| `fully_static_link` | `-static` fully static linking | Optional | **Injected** | Legacy default; unused by current tests. |
74+
| `static_libgcc` | `-static-libgcc` in opt dynamic links | Optional | **Injected** | Legacy default. |
75+
76+
### Archiving
77+
78+
| Feature | Purpose | Required | Classification | Notes |
79+
|---|---|---|---|---|
80+
| `archiver_flags` | `ar` flags (`rcsD`) and library-list handling | Yes | **Injected** + Implicit | Feature injected; `cpp_link_static_library` `action_config` binds the `ar` tool and `implies = ["archiver_flags"]`. |
81+
82+
### Sysroot
83+
84+
| Feature | Purpose | Required | Classification | Notes |
85+
|---|---|---|---|---|
86+
| `sysroot` (compile) | `--sysroot` on compile actions | Yes | Implicit | Provided via `builtin_sysroot` passed to `create_cc_toolchain_config_info`. |
87+
| `sysroot_link_flags` | `--sysroot` / `-Wl,--sysroot` on link actions | Yes | Explicit | Custom feature in `features` list. |
88+
89+
### Coverage
90+
91+
| Feature | Purpose | Required | Classification | Notes |
92+
|---|---|---|---|---|
93+
| `coverage` | Enable coverage instrumentation build mode | Yes | Explicit | In `features` list. |
94+
| `gcc_coverage_map_format` | `-fprofile-arcs -ftest-coverage` / `--coverage` (gcov) | Yes | Explicit | In `features` list; `requires` `coverage`. |
95+
| `llvm_coverage_map_format` | LLVM coverage map | No | **Injected** | Not used — GCC toolchain. |
96+
97+
### Capabilities
98+
99+
| Feature | Purpose | Required | Classification | Notes |
100+
|---|---|---|---|---|
101+
| `supports_pic` | Declares PIC capability | Yes | Explicit | In `features` list. |
102+
| `supports_dynamic_linker` | Declares dynamic-linker capability | Yes | Explicit | In `features` list. |
103+
| `supports_fission` | Declares Fission capability | Optional | Explicit | In `features` list; no `per_object_debug_info`/`fission_support` features defined. |
104+
105+
### Custom / project features
106+
107+
| Feature | Purpose | Required | Classification | Notes |
108+
|---|---|---|---|---|
109+
| `dbg` / `opt` | Build-mode selectors | Yes | Explicit | |
110+
| `compiler_library_search_paths` | Set `LD_LIBRARY_PATH` for toolchain libs | Yes | Explicit | |
111+
| `extra_compile_flags` / `extra_c_compile_flags` / `extra_cxx_compile_flags` | Injection point for user-supplied compile flags | Yes | Explicit | |
112+
| `extra_link_flags` | Injection point for user-supplied link flags | Yes | Explicit | |
113+
| `minimal_warnings` / `strict_warnings` / `all_wall_warnings` / `warnings_as_errors` | Warning-level control | Optional | Explicit | |
114+
| `sanitizer` / `asan` / `lsan` / `tsan` / `ubsan` | Sanitizer builds | Optional | Explicit | |
115+
| `use_pthread` | Link pthread | Optional | Explicit | |
116+
| `gnu11` | Select `-std=gnu11` vs `-std=c11` | Optional | Explicit | Marked temporary in source. |
117+
| `supports_header_path_normalization` | Suppress absolute-path warnings for system headers | Optional | Explicit | |
118+
119+
### Tooling (non-feature wiring)
120+
121+
| Behavior | Classification | Notes |
122+
|---|---|---|
123+
| `assemble` / `c_compile` / `cpp_compile` / link / `ar` / `strip` tool bindings | Implicit | Provided by `action_config` entries. |
124+
| `gcov` path | Implicit | Provided by `tool_paths` (`gcov_wrapper`). |
125+
126+
## Behaviors Depending On Bazel Legacy Defaults
127+
128+
The following required behaviors are currently supplied **only** by Bazel's
129+
legacy feature injection and are **not** defined in the Linux template. These
130+
are the concrete gaps to close before enabling `no_legacy_features`:
131+
132+
- `include_paths`
133+
- `preprocessor_defines`
134+
- `user_compile_flags`
135+
- `compiler_input_flags`
136+
- `compiler_output_flags`
137+
- `dependency_file`
138+
- `pic` (also partly implicit via `default_compile_flags`)
139+
- `user_link_flags`
140+
- `output_execpath_flags`
141+
- `library_search_directories`
142+
- `runtime_library_search_directories`
143+
- `libraries_to_link`
144+
- `shared_flag`
145+
- `linker_param_file`
146+
- `archiver_flags` (feature body; tool binding is already explicit via `action_config`)
147+
148+
Optional legacy behaviors currently injected (add only if the capability is
149+
needed): `force_pic_flags`, `fully_static_link`, `static_libgcc`,
150+
`per_object_debug_info`, `fission_support`, `strip_debug_symbols`, `includes`,
151+
`build_interface_libraries`, `dynamic_library_linker_tool`, `linkstamps`, and
152+
all FDO/AutoFDO features.
153+
154+
Not applicable to this toolchain: `llvm_coverage_map_format`,
155+
`legacy_compile_flags`, `legacy_link_flags`.
156+
157+
## Follow-Up Tasks
158+
159+
**Implementation**
160+
- Define the required Injected features explicitly in the Linux template,
161+
mirroring the reference implementations already present in the QNX template
162+
where applicable.
163+
- Add the `no_legacy_features` feature (enabled) once the required set is
164+
complete.
165+
- Decide whether `pic` should be an explicit feature or remain baked into
166+
`default_compile_flags`, and make it consistent with QNX.
167+
168+
**Validation**
169+
- Build and run the `tests/` suites (`feature_verification_tests`,
170+
`language_and_standards_tests`) on the `x86_64-linux` config before and after
171+
enabling `no_legacy_features`, and diff the resulting command lines
172+
(`--subcommands`) to confirm parity.
173+
- Verify static libraries (`archiver_flags`), shared libraries (`shared_flag`),
174+
whole-archive linking (`libraries_to_link`), coverage, PIC, and header
175+
dependency tracking (`dependency_file`) still function.
176+
177+
**Documentation**
178+
- Update [docs/features.md](features.md) to reflect the explicit feature set.
179+
- Cross-link this document from [docs/overview.md](overview.md) and the README.

0 commit comments

Comments
 (0)