helly25 · Nov 4, 2026 · Oct 31, 2026 · Oct 31, 2026 · Oct 31, 2026 · Oct 31, 2026
@@ -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,19 +63,15 @@ 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()
 
 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")

@@ -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

@@ -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).
 
-<!-- Release Notes template is at .github/workflows/release_prep.sh -->
+<!-- Release notes template: .github/workflows/release_notes_template.txt -->
 
 ## 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).
 
 <!-- prettier-ignore -->
 | 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)`
 

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