Produce BOLT-compatible libraries

[fheinecke]

Description

This is the first in a series of changes to produce BOLT-optimized TE libraries for arm64. This does not produce binaries actually optimized by BOLT, rather, it produces binaries that can be optimized by BOLT. We'll need to start producing and publishing profiles to be able to actually start release with this optimization built in.

This is arguably a breaking change, but in an area where we haven't explicitly defined compatibility guarantees. NCCL >= 2.30.4 is now required for arm64 builds, and older compilers that don't support the newly added build-time flags will fail. In addition, A53 core errata workarounds 835769 and 843419 are now disabled, which may cause correctness problems on older A53 core revisions.

This change is enabled by default for arm64 builds.

Type of change

• Documentation change (change only to the documentation, either a fix or a new content)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Infra/Build change
• Code refactoring

Changes

Please list the changes introduced in this PR:

• Made all shared libraries compatible with BOLT

Checklist:

• I have read and followed the contributing guidelines
• The functionality is complete
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[fheinecke]

/te-ci

[fheinecke]

CI failures are all runner scheduling failures, not related to this changeset

[greptile-apps]

Greptile Summary

The PR makes the common, PyTorch, and JAX shared libraries suitable for subsequent LLVM BOLT optimization, enabled by default on Linux Arm64.

• Adds BOLT compiler and linker flags to the framework extension builders and common CMake target.
• Disables Cortex-A53 errata workarounds for Arm64 BOLT-compatible builds.
• Adds eager symbol binding, relocation retention, compiler capability checks, and an NCCL 2.30.4 build-time gate.
• Documents the new NVTE_ENABLE_BOLT_COMPATIBLE environment variable.

Confidence Score: 4/5

The PR appears safe to merge for the native release builds, with a non-blocking inconsistency remaining for cross-compilation.

Native Arm64 builds consistently receive the intended BOLT options, but framework extensions derive architecture from the host while the common library derives it from the CMake target, producing inconsistent artifacts when those architectures differ.

Files Needing Attention: build_tools/utils.py and transformer_engine/common/CMakeLists.txt

Important Files Changed

Filename	Overview
build_tools/utils.py	Introduces host-derived BOLT defaults and flag generation; cross-compilation can make these disagree with the CMake target.
build_tools/pytorch.py	Applies the generated host compiler and linker flags to the PyTorch extension.
build_tools/jax.py	Applies the generated host compiler and linker flags to the JAX extension.
setup.py	Forwards an explicitly configured BOLT setting to the common CMake build.
transformer_engine/common/CMakeLists.txt	Adds target-aware BOLT configuration, capability checks, relocation/eager-binding options, and the NCCL minimum-version gate.
docs/envvars.rst	Documents the option, defaults, platform restrictions, and fresh-build-directory requirement.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  ENV["NVTE_ENABLE_BOLT_COMPATIBLE"] --> PY["Python build helpers"]
  ENV --> CMAKE["Common CMake build"]
  PY --> PT["PyTorch extension"]
  PY --> JAX["JAX extension"]
  CMAKE --> CORE["libtransformer_engine.so"]
  PT --> PKG["BOLT-compatible package artifacts"]
  JAX --> PKG
  CORE --> PKG

Loading

_{Reviews (1): Last reviewed commit: "Produce BOLT-compatible libraries" | Re-trigger Greptile}

[greptile-apps]

Host-derived BOLT architecture flags

If the build host and target use different architectures, the framework extensions select BOLT defaults and Arm64 flags from platform.machine() while the core uses CMAKE_SYSTEM_PROCESSOR, producing inconsistent BOLT compatibility across the packaged libraries or passing Arm64-only flags to a non-Arm64 extension target.

Knowledge Base Used: Build and Packaging