From 1d272f740d79fdaa300163d36477417bf2de46c9 Mon Sep 17 00:00:00 2001 From: Ian Butterworth Date: Thu, 10 Jul 2025 12:19:54 -0400 Subject: [PATCH 1/2] expand JULIA_CPU_TARGET docs --- doc/src/devdocs/pkgimg.md | 18 ++++++++++++++++-- doc/src/manual/environment-variables.md | 13 +++++++++++++ 2 files changed, 29 insertions(+), 2 deletions(-) diff --git a/doc/src/devdocs/pkgimg.md b/doc/src/devdocs/pkgimg.md index 64f4e640b7c19..3bf613dafa9a5 100644 --- a/doc/src/devdocs/pkgimg.md +++ b/doc/src/devdocs/pkgimg.md @@ -33,8 +33,22 @@ Dynamic libraries on macOS need to link against `-lSystem`. On recent macOS vers To that effect we link with `-undefined dynamic_lookup`. ## [Package images optimized for multiple microarchitectures](@id pkgimgs-multi-versioning) -Similar to [multi-versioning](@ref sysimg-multi-versioning) for system images, package images support multi-versioning. If you are in a heterogeneous environment, with a unified cache, -you can set the environment variable `JULIA_CPU_TARGET=generic` to multi-version the object caches. + +Similar to [multi-versioning](@ref sysimg-multi-versioning) for system images, package images support multi-versioning. This allows creating package caches that can run efficiently on different CPU architectures within the same environment. + +### Usage and constraints + +Package images can only target the same or more specific CPU features than their base system image. This constraint ensures compatibility and prevents runtime errors. + +To enable multi-versioning for package images, set the [`JULIA_CPU_TARGET`](@ref JULIA_CPU_TARGET) environment variable when building packages: + +```bash +# Create multi-versioned package images for generic and optimized targets +export JULIA_CPU_TARGET="generic;haswell" + +# For heterogeneous environments, use generic to ensure broad compatibility +export JULIA_CPU_TARGET="generic" +``` ## Flags that impact package image creation and selection diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index 636f6711cdbdd..a796293446fdb 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -495,6 +495,19 @@ A `generic` or empty CPU name means the basic required feature set of the target which is at least the architecture the C/C++ runtime is compiled with. Each string is interpreted by LLVM. +#### Examples of valid `JULIA_CPU_TARGET` values + +- `generic` - produces portable code for the basic ISA +- `haswell` - optimizes for Intel Haswell microarchitecture +- `generic;haswell` - creates multi-versioned images with both generic and optimized variants +- `x86-64-v3;x86-64-v4` - targets x86-64 microarchitecture levels v3 and v4 + +!!! note + Package images can only target the same or more specific CPU features than + their base system image. If your system image was built with `JULIA_CPU_TARGET=generic`, + package images can use any target. However, if your system image targets a specific CPU + (e.g., `haswell`), package images cannot target a less capable CPU. + A few special features are supported: 1. `sysimage` From ecbad5d49c45b8de2fd8656f9da3c82c8ea5e6dd Mon Sep 17 00:00:00 2001 From: Ian Butterworth Date: Fri, 18 Jul 2025 15:00:45 -0400 Subject: [PATCH 2/2] simplfy --- doc/src/devdocs/pkgimg.md | 14 +------------- doc/src/manual/environment-variables.md | 11 +---------- 2 files changed, 2 insertions(+), 23 deletions(-) diff --git a/doc/src/devdocs/pkgimg.md b/doc/src/devdocs/pkgimg.md index 3bf613dafa9a5..0bc28b07b0c29 100644 --- a/doc/src/devdocs/pkgimg.md +++ b/doc/src/devdocs/pkgimg.md @@ -36,19 +36,7 @@ To that effect we link with `-undefined dynamic_lookup`. Similar to [multi-versioning](@ref sysimg-multi-versioning) for system images, package images support multi-versioning. This allows creating package caches that can run efficiently on different CPU architectures within the same environment. -### Usage and constraints - -Package images can only target the same or more specific CPU features than their base system image. This constraint ensures compatibility and prevents runtime errors. - -To enable multi-versioning for package images, set the [`JULIA_CPU_TARGET`](@ref JULIA_CPU_TARGET) environment variable when building packages: - -```bash -# Create multi-versioned package images for generic and optimized targets -export JULIA_CPU_TARGET="generic;haswell" - -# For heterogeneous environments, use generic to ensure broad compatibility -export JULIA_CPU_TARGET="generic" -``` +See the [`JULIA_CPU_TARGET`](@ref JULIA_CPU_TARGET) environment variable for more information on how to set the CPU target for package images. ## Flags that impact package image creation and selection diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index a796293446fdb..4a3018c481276 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -495,18 +495,9 @@ A `generic` or empty CPU name means the basic required feature set of the target which is at least the architecture the C/C++ runtime is compiled with. Each string is interpreted by LLVM. -#### Examples of valid `JULIA_CPU_TARGET` values - -- `generic` - produces portable code for the basic ISA -- `haswell` - optimizes for Intel Haswell microarchitecture -- `generic;haswell` - creates multi-versioned images with both generic and optimized variants -- `x86-64-v3;x86-64-v4` - targets x86-64 microarchitecture levels v3 and v4 - !!! note Package images can only target the same or more specific CPU features than - their base system image. If your system image was built with `JULIA_CPU_TARGET=generic`, - package images can use any target. However, if your system image targets a specific CPU - (e.g., `haswell`), package images cannot target a less capable CPU. + their base system image. A few special features are supported: