expand JULIA_CPU_TARGET docs

Author: IanButterworth

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
 

doc/src/manual/environment-variables.md

@@ -489,7 +489,22 @@ 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
+
+#### Package image compatibility constraints
+
+**Important:** 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. `clone_all`
 
      This forces the target to have all functions in sysimg cloned.