diff --git a/.github/workflows/release_notes_template.txt b/.github/workflows/release_notes_template.txt index 5b858b19f..463bcdbaa 100644 --- a/.github/workflows/release_notes_template.txt +++ b/.github/workflows/release_notes_template.txt @@ -1,5 +1,12 @@ Minimum bazel version: **7.0.0** +See the [changelog](https://github.com/bazel-contrib/toolchains_llvm/blob/{tag}/CHANGELOG.md) +for changes in this release. In 1.13.0, `first` / `latest` prerelease selection +requires `llvm_version_allow_prereleases = True`, or +`linker_version_allow_prereleases = True` for catalogued linkers. Exact pins are +unchanged. Read the [1.13.0 migration guide](https://github.com/bazel-contrib/toolchains_llvm/blob/{tag}/docs/migration-1.13.0.md) +for configuration changes, range choices, and SemVer RC ordering. + If you're using `bzlmod`, add the following to `MODULE.bazel`: ```starlark @@ -8,11 +15,7 @@ bazel_dep(name = "toolchains_llvm", version = "{version}") # Configure and register the toolchain. llvm = use_extension("@toolchains_llvm//toolchain/extensions:llvm.bzl", "llvm") llvm.toolchain( - llvm_version = "23.1.2", - linker = { - "darwin-aarch64": "auto", - "darwin-x86_64": "auto", - }, + llvm_version = "23.1.5", ) use_repo(llvm, "llvm_toolchain") @@ -21,6 +24,11 @@ use_repo(llvm, "llvm_toolchain") register_toolchains("@llvm_toolchain//:all") ``` +These examples use the linker bundled with LLVM 23.1.5; its macOS linker does +not require the LLVM 23.1.0–23.1.2 SDK/TAPI workaround. LLVM 23.1.5 has no macOS +x86_64 archive; Intel Mac users must select another available LLVM version +through `llvm_version` or `llvm_versions`. + To directly use a commit from GitHub, add this block and replace commit with the commit you want. ```starlark git_override( @@ -55,7 +63,7 @@ load("@rules_cc//cc:extensions.bzl", "compatibility_proxy_repo") # If you see an error: # ERROR: Cycle caused by autoloads, failed to load .bzl file '@@cc_compatibility_proxy//:symbols.bzl'. -# then you might need to add the following to your .bzelrc: +# then you might need to add the following to your .bazelrc: # common --repositories_without_autoloads=cc_compatibility_proxy compatibility_proxy_repo() @@ -63,11 +71,7 @@ load("@toolchains_llvm//toolchain:rules.bzl", "llvm_toolchain") llvm_toolchain( name = "llvm_toolchain", - llvm_version = "23.1.2", - linker = { - "darwin-aarch64": "auto", - "darwin-x86_64": "auto", - }, + llvm_version = "23.1.5", ) load("@llvm_toolchain//:toolchains.bzl", "llvm_register_toolchains") diff --git a/CHANGELOG.md b/CHANGELOG.md index 75509274c..4fb5c7b3b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,68 @@ exhaustive list of fixes, dependency updates, or newly catalogued LLVM archives. See the [GitHub releases](https://github.com/bazel-contrib/toolchains_llvm/releases) for release artifacts and the [README](README.md) for configuration and requirements. +## 1.13.0 + +### Migration required for prerelease selectors + +- `first` / `latest` prerelease selection now requires an explicit opt-in; + specifying an RC in a requirement no longer suffices. Exact pins are unchanged. + See the [1.13.0 migration guide](docs/migration-1.13.0.md) for the required + flags, range choices, and changed RC ordering under SemVer. + +### Version selection + +- Shared expression-based LLVM and linker version selectors, including + `major`, `minor`, and `patch` constants, function expressions, wildcards, + and compatible-release comparisons. Candidates must have an artifact for + the execution platform before version selection. +- Environment-derived linker versions through `getenv(NAME,fallback)`, matching + LLVM version selection. +- Independent prerelease policies in feature overrides; linker-only policy + changes can reuse the base LLVM archive. + +### LLVM distributions + +- Add checksum-pinned LLVM 23.1.5 archives for Linux ARM64/x86_64, macOS ARM64, + and Windows ARM64/x86_64. Both xz and zstd metadata are retained; automatic + selection continues to use xz. Existing LLVM and mold entries are preserved. + +### Dependencies and publishing + +- WORKSPACE dependencies: `rules_cc` 0.2.27, `apple_support` 2.11.0, and + `bazel_features` 1.54.1. +- Test dependencies, including `rules_python` 2.4.6, `rules_go` 0.65.0, + `rules_foreign_cc` 0.17.0, `rules_rust` 0.75.0, BoringSSL 0.20261020.0, + and WORKSPACE `aspect_bazel_lib` 3.8.0. +- BCR publishing workflow to `publish-to-bcr` 1.6.0. + +## 1.12.0 + +- Add checksum-pinned LLVM 23.1.4 archives for Linux ARM64/x86_64, macOS ARM64, + and Windows ARM64/x86_64. Both xz and zstd metadata are retained; automatic + selection continues to use xz. Existing LLVM and mold entries are preserved. +- Fix remote execution of dynamically linked LLVM tools: wrappers execute + auxiliary tools from their original distribution paths, preserving relative + shared-library lookup. Downloaded distributions supply the relevant LLVM, + Clang, and libc++ shared libraries as tool inputs. +- Explicit `archive_flags`, `link_libs`, optimization/debug/fastbuild flags, + coverage flags, and `unfiltered_compile_flags` replace their corresponding + defaults. Use the corresponding `extra_*` attribute where available for + additive behavior. `compile_flags`, `cxx_flags`, and `link_flags` still append + to their computed defaults. +- Use `-fstack-protector-strong` instead of `-fstack-protector` by default. +- Report Linux `target_libc` as `glibc` instead of `glibc_unknown`. +- Upgrade `mboworks_bzl` to 0.8.0 and the WORKSPACE test dependency Google + Benchmark to 1.10.0. The new selector expressions and explicit prerelease + controls are introduced in 1.13.0, not in this dependency upgrade. + +## 1.11.3 + +- Recognize LLVM 23.1.3's bundled macOS linker fix. The SDK/TAPI warning now + applies only to LLVM 23.1.0 through 23.1.2, not all LLVM 23 releases. +- Update WORKSPACE dependencies to `apple_support` 2.10.1 and `bazel_features` + 1.52.0, and test dependencies to `rules_python` 2.4.2 and `rules_go` 0.64.2. + ## 1.11.2 - Honor the empty-key fallback in `conly_flags` for every target, matching the diff --git a/README.md b/README.md index 322d210dd..583910117 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ for how to get started, and the [changelog](CHANGELOG.md) for feature availabili NOTE: For releases prior to 0.10.1, please also see [these notes](REPO_RENAME.md). - + ## Basic Usage @@ -18,6 +18,13 @@ below for more options. See in-code documentation in [rules.bzl](toolchain/rules.bzl) for available attributes to `llvm_toolchain`. +### Upgrading to 1.13.0 + +`first` / `latest` selectors now require an explicit opt-in to select +prereleases. Exact pins, including RC pins, are unchanged. Read the +[1.13.0 migration guide](docs/migration-1.13.0.md) for the required configuration +changes, range choices, and RC ordering under SemVer. + ## Advanced Usage ### Per host architecture LLVM version @@ -236,6 +243,11 @@ for how CC toolchains work in general. ### Requirements +Expression-based selectors and the independent prerelease controls below are +available starting with toolchains_llvm 1.13.0. Basic `first` / `latest` +comparisons were introduced in 1.6.0; see the [changelog](CHANGELOG.md) for +earlier feature availability. + Version requirements let projects bind automatic LLVM upgrades to deliberate `toolchains_llvm` release upgrades. A `toolchains_llvm` release can add new LLVM release identifiers to its checksummed catalogue. Upgrading the pinned module then makes those releases eligible without a @@ -270,7 +282,7 @@ linker versions, and lets one configuration accommodate hosts whose available ar Conditions are comma-separated and combined with AND. toolchains_llvm supplies `major`, `minor`, and `patch` as numeric release-component constants, so `latest:major==23,minor>=2` stays within LLVM 23 and requires a minor version of at least 2. Comparisons and function expressions use -[mboworks_bzl's SemVer mode](https://mboworks.github.io/bzl/site/tag/0.7.0/docs/versions.html#semver). +[mboworks_bzl's SemVer mode](https://mboworks.github.io/bzl/site/tag/0.8.0/docs/versions.html#semver). | Selector | Selection policy | @@ -281,30 +293,32 @@ LLVM 23 and requires a minor version of at least 2. Comparisons and function exp | `first:>=22,<23` | Oldest stable LLVM 22 release for the host | For all comparison operators, wildcard matching and compatible-release boundaries, see -[Compatible and matching requirements](https://mboworks.github.io/bzl/site/tag/0.7.0/docs/versions.html#compatible-and-matching-requirements). +[Compatible and matching requirements](https://mboworks.github.io/bzl/site/tag/0.8.0/docs/versions.html#compatible-and-matching-requirements). Function clauses such as `major()==23` and more advanced inspection are documented under -[Requirement expressions and constants](https://mboworks.github.io/bzl/site/tag/0.7.0/docs/versions.html#requirement-expressions-and-constants). +[Requirement expressions and constants](https://mboworks.github.io/bzl/site/tag/0.8.0/docs/versions.html#requirement-expressions-and-constants). `llvm_version_allow_prereleases` and `linker_version_allow_prereleases` each default to `False`. They independently control bare and constrained -`first`/`latest` selectors for LLVM and catalogued linkers, respectively. Requirements always -apply; enabling prereleases does not bypass ranges or host availability. Naming -an RC in a requirement does not implicitly enable prereleases. Exact version pins -are unaffected. +`first`/`latest` selectors for LLVM and catalogued linkers, respectively. +The flag controls whether prereleases are eligible; the requirements control +which versions qualify. Constraints do not need to name an RC, and naming +one does not by itself enable prereleases. Requirements and host availability +always apply. Exact version pins are unaffected. ```starlark llvm.toolchain( name = "llvm_rc", - llvm_version = "latest:>=23.1.0-rc1,<23.1.0", + llvm_version = "latest:>23.0,<=23.1", llvm_version_allow_prereleases = True, ) ``` -This selects the newest matching release candidate available for the execution -host. With `llvm_version_allow_prereleases = False`, that RC-only range has no matching release. -With the option enabled, expressions such as `is_prerelease()==True` can further -restrict selection to prereleases; `is_prerelease()==False` can restrict a -particular selector to stable releases. +This selects the newest matching LLVM 23.1.0 release candidate, then the final +23.1.0 release once its archive is in the configured catalogue for the execution +host. The bound `<=23.1` means `<=23.1.0`, not all 23.1.x patches. +See the migration guide for [other RC upgrade policies](docs/migration-1.13.0.md#choose-the-scope-of-rc-upgrades) +and [SemVer RC ordering](docs/migration-1.13.0.md#check-rc-ordering-under-semver), +including the difference between `rc10` and `rc.10`. Linker selectors use the same bzl SemVer comparisons, requirement expressions, projection constants, and first/latest selection as LLVM. For example: @@ -334,12 +348,11 @@ reuse the base LLVM archive. It is further possible to provide the version or requirement from an environment variable with a fallback version or requirement. This works for both LLVM and linker versions, for example `linker_version = "getenv(MOLD_VERSION,latest:major==3)"` -with `--repo_env=MOLD_VERSION=3.0.0`. In this case it is important to -also use the bazel flag `--repo_env=LLVM_VERSION=version_or_requirement`. It is -important to use both correctly because otherwise the resulting builds are not -reproducible. The main purpose of using an environment variable to encode the -version for integration or batch testing on multiple platforms where multiple -LLVM versions should be tested. +with `--repo_env=MOLD_VERSION=3.0.0`. Set the same variable named in `getenv` +through Bazel's `--repo_env=NAME=value`; for LLVM examples below, use +`--repo_env=LLVM_VERSION=version_or_requirement`. This makes the selected input +explicit. Environment-based selection is useful for integration or batch +testing across multiple LLVM or linker versions. - `getenv(ENVIRONMENT_VARIABLE_NAME,fallback)` diff --git a/docs/migration-1.13.0.md b/docs/migration-1.13.0.md new file mode 100644 index 000000000..c8ab8c254 --- /dev/null +++ b/docs/migration-1.13.0.md @@ -0,0 +1,97 @@ +# Migrating to toolchains_llvm 1.13.0 + +toolchains_llvm 1.13.0 changes prerelease eligibility and version comparisons +for `first` / `latest` selectors. Configurations selecting prereleases must +explicitly enable them and review their constraints. Exact version pins, +including RC pins, are unchanged. + +For other changes, see the [1.13.0 changelog](../CHANGELOG.md#1130). +For the current configuration reference, see [Requirements](../README.md#requirements). + +## Enable prereleases explicitly + +In 1.12.x, `first` / `latest` selectors admitted prereleases only when a +requirement explicitly specified a prerelease version, and only for that +same major/minor/patch release. For example, a requirement naming +`23.1.0-rc1` admitted other 23.1.0 RCs, but not 23.1.1 or 24.1.0 RCs. + +In 1.13.0, naming an RC in a requirement is no longer sufficient. Enable +prereleases with the corresponding attribute: + +- LLVM: `llvm_version_allow_prereleases = True`. +- Catalogued linkers: `linker_version_allow_prereleases = True`. + +Both flags default to `False` and are independent. They apply to bare and +constrained `first` / `latest` selectors, not exact pins. Use the same attributes +with `llvm.toolchain` in Bzlmod or `llvm_toolchain` in WORKSPACE; they are also +available in feature overrides. The linker flag has no effect on bundled +linkers, `auto`, or absolute executable paths. + +The flag now controls prerelease eligibility separately from the constraints. +Those constraints no longer need to name an RC. Enabling prereleases admits +every prerelease satisfying them, not just prereleases with a release tuple +explicitly named in a requirement. For example, adding the flag to +`latest:>=23.1.0-rc1` also admits later releases' RCs. Review unbounded ranges +when migrating rather than only adding the flag. + +Requirements and execution-host availability always apply. Selection uses +the configured LLVM or linker catalogue; it does not discover live upstream +releases. New candidates become available through a toolchains_llvm upgrade +or an explicit catalogue change. + +## Choose the scope of RC upgrades + +To follow LLVM 23.1.0 RCs and then select the final 23.1.0 release once its +archive is available for the execution host: + +```starlark +llvm.toolchain( + name = "llvm_rc", + llvm_version = "latest:>23.0,<=23.1", + llvm_version_allow_prereleases = True, +) +``` + +Choose the range according to the intended upgrade policy. These examples +all assume `llvm_version_allow_prereleases = True`: + +| Selector | Upgrade policy | +| --------------------------- | --------------------------------------------------------- | +| `latest:>23.0,<23.1` | Admits 23.1.0 RCs, excludes final 23.1.0. | +| `latest:>23.0,<=23.1` | Follows 23.1.0 RCs, then selects final 23.1.0. | +| `latest:major==23,minor==1` | Follows all 23.1.x releases, including their prereleases. | + +`23.1` means `23.1.0`, so `<=23.1` excludes 23.1.1 and its prereleases. +Stable releases within the constraints remain eligible; for example, the +two bounded ranges would also admit a 23.0.1 release if present in a custom catalogue. +Append `,is_prerelease()==True` if selection must be strictly prerelease-only. +With the flag set to `False`, only matching stable releases are eligible. +Conversely, `is_prerelease()==False` restricts a particular selector to stable +releases even when the flag is enabled. + +The same constraints work for catalogued linkers through `linker_version` +with `linker_version_allow_prereleases = True`. + +## Check RC ordering under SemVer + +Version comparisons now use +[bzl's SemVer mode](https://mboworks.github.io/bzl/site/tag/0.8.0/docs/versions.html#semver). +[SemVer compares dot-separated prerelease identifiers](https://semver.org/#spec-item-11) +numerically when they contain only digits (`rc.2 < rc.10`), but lexically when +they contain letters (`rc10 < rc2`). `latest` follows that precedence, not +release chronology. + +LLVM uses the undotted form for its 23.1.0 RCs, for example +[23.1.0-rc3](https://github.com/llvm/llvm-project/releases/tag/llvmorg-23.1.0-rc3), +not `23.1.0-rc.3`. Between matching `23.1.0-rc2` and hypothetical `23.1.0-rc10`, +`latest` would choose `rc2`. If LLVM instead used `23.1.0-rc.2` and +`23.1.0-rc.10`, `latest` would choose `rc.10`. + +Both spellings are valid SemVer; they are not normalized into one another. +Mixing forms also matters: `23.1.0-rc.10 < 23.1.0-rc9`, because the first +identifier `rc` sorts before `rc9`. Switching from `rc9` to `rc.10` would +therefore leave `latest` selecting `rc9` if both remain eligible. + +Use an exact pin if SemVer ordering differs from the intended upstream RC +order. Exact pins such as `llvm_version = "23.1.0-rc3"` do not require the +prerelease flag and bypass `first` / `latest` ordering.