Add 'sysimage' keyword for JULIA_CPU_TARGET to match (or extend) the sysimage target (#58970)

Author: IanButterworth

NEWS.md

@@ -26,6 +26,7 @@ Command-line option changes
 ---------------------------
 
 * The option `--sysimage-native-code=no` has been deprecated.
+* The `JULIA_CPU_TARGET` environment variable now supports a `sysimage` keyword to match (or extend) the CPU target used to build the current system image ([#58970]).
 
 Multi-threading changes
 -----------------------
@@ -47,6 +48,7 @@ New library functions
 * `ispositive(::Real)` and `isnegative(::Real)` are provided for performance and convenience ([#53677]).
 * Exporting function `fieldindex` to get the index of a struct's field ([#58119]).
 * `Base.donotdelete` is now public. It prevents deadcode elemination of its arguments ([#55774]).
+* `Sys.sysimage_target()` returns the CPU target string used to build the current system image ([#58970]).
 
 New library features
 --------------------

base/sysinfo.jl

@@ -16,6 +16,7 @@ export BINDIR,
        JIT,
        cpu_info,
        cpu_summary,
+       sysimage_target,
        uptime,
        loadavg,
        free_memory,
@@ -312,6 +313,23 @@ function cpu_info()
     return cpus
 end
 
+"""
+    Sys.sysimage_target()
+
+Return the CPU target string that was used to build the current system image.
+
+This function returns the original CPU target specification that was passed to Julia
+when the system image was compiled. This can be useful for reproducing the same
+system image or for understanding what CPU features were enabled during compilation.
+
+If the system image was built with the default settings this will return `"native"`.
+
+See also [`JULIA_CPU_TARGET`](@ref).
+"""
+function sysimage_target()
+    return ccall(:jl_get_sysimage_cpu_target, Ref{String}, ())
+end
+
 """
     Sys.uptime()
 

doc/src/base/base.md

@@ -397,6 +397,7 @@ Base.Sys.total_memory
 Base.Sys.free_physical_memory
 Base.Sys.total_physical_memory
 Base.Sys.uptime
+Base.Sys.sysimage_target
 Base.Sys.isjsvm
 Base.Sys.loadavg
 Base.Sys.isexecutable

doc/src/manual/environment-variables.md

@@ -479,9 +479,15 @@ stored in memory.
 
 Valid values for [`JULIA_CPU_TARGET`](@ref JULIA_CPU_TARGET) can be obtained by executing `julia -C help`.
 
+To get the CPU target string that was used to build the current system image,
+use [`Sys.sysimage_target()`](@ref). This can be useful for reproducing
+the same system image or understanding what CPU features were enabled during compilation.
+
 Setting [`JULIA_CPU_TARGET`](@ref JULIA_CPU_TARGET) is important for heterogeneous compute systems where processors of
 distinct types or features may be present. This is commonly encountered in high performance
-computing (HPC) clusters since the component nodes may be using distinct processors.
+computing (HPC) clusters since the component nodes may be using distinct processors. In this case,
+you may want to use the `sysimage` CPU target to maintain the same configuration as the sysimage.
+See below for more details.
 
 The CPU target string is a list of strings separated by `;` each string starts with a CPU
 or architecture name and followed by an optional list of features separated by `,`.
@@ -490,25 +496,33 @@ which is at least the architecture the C/C++ runtime is compiled with. Each stri
 is interpreted by LLVM.
 
 A few special features are supported:
-1. `clone_all`
+
+1. `sysimage`
+
+     A special keyword that can be used as a CPU target name, which will be replaced
+     with the CPU target string that was used to build the current system image. This allows
+     you to specify CPU targets that build upon or extend the current sysimage's target, which
+     is particularly helpful for creating package images that are as flexible as the sysimage.
+
+2. `clone_all`
 
      This forces the target to have all functions in sysimg cloned.
      When used in negative form (i.e. `-clone_all`), this disables full clone that's
      enabled by default for certain targets.
 
-2. `base([0-9]*)`
+3. `base([0-9]*)`
 
      This specifies the (0-based) base target index. The base target is the target
      that the current target is based on, i.e. the functions that are not being cloned
      will use the version in the base target. This option causes the base target to be
      fully cloned (as if `clone_all` is specified for it) if it is not the default target (0).
      The index can only be smaller than the current index.
 
-3. `opt_size`
+4. `opt_size`
 
      Optimize for size with minimum performance impact. Clang/GCC's `-Os`.
 
-4. `min_size`
+5. `min_size`
 
      Optimize only for size. Clang's `-Oz`.
 

pkgimage.mk

@@ -26,7 +26,7 @@ print-depot-path:
 	@$(call PRINT_JULIA, $(call spawn,$(JULIA_EXECUTABLE)) --startup-file=no -e '@show Base.DEPOT_PATH')
 
 $(BUILDDIR)/stdlib/%.image: $(JULIAHOME)/stdlib/Project.toml $(JULIAHOME)/stdlib/Manifest.toml $(INDEPENDENT_STDLIBS_SRCS) $(DEPOTDIR)/compiled
-	@$(call PRINT_JULIA, JULIA_CPU_TARGET="$(JULIA_CPU_TARGET)" $(call spawn,$(JULIA_EXECUTABLE)) --startup-file=no -e \
+	@$(call PRINT_JULIA, JULIA_CPU_TARGET="sysimage" $(call spawn,$(JULIA_EXECUTABLE)) --startup-file=no -e \
 		'Base.Precompilation.precompilepkgs(configs=[``=>Base.CacheFlags(debug_level=2, opt_level=3), ``=>Base.CacheFlags(check_bounds=1, debug_level=2, opt_level=3)])')
 	touch $@
 

src/aotcompile.cpp

@@ -2344,15 +2344,24 @@ void jl_dump_native_impl(void *native_code,
                                                         "jl_small_typeof");
             jl_small_typeof_copy->setVisibility(GlobalValue::HiddenVisibility);
             jl_small_typeof_copy->setDSOLocal(true);
-            AT = ArrayType::get(T_psize, 5);
+
+            // Create CPU target string constant
+            auto cpu_target_str = jl_options.cpu_target ? jl_options.cpu_target : "native";
+            auto cpu_target_data = ConstantDataArray::getString(Context, cpu_target_str, true);
+            auto cpu_target_global = new GlobalVariable(metadataM, cpu_target_data->getType(), true,
+                                                       GlobalVariable::InternalLinkage,
+                                                       cpu_target_data, "jl_cpu_target_string");
+
+            AT = ArrayType::get(T_psize, 6);
             auto pointers = new GlobalVariable(metadataM, AT, false,
                                             GlobalVariable::ExternalLinkage,
                                             ConstantArray::get(AT, {
                                                     ConstantExpr::getBitCast(header, T_psize),
                                                     ConstantExpr::getBitCast(shards, T_psize),
                                                     ConstantExpr::getBitCast(ptls, T_psize),
                                                     ConstantExpr::getBitCast(jl_small_typeof_copy, T_psize),
-                                                    ConstantExpr::getBitCast(target_ids, T_psize)
+                                                    ConstantExpr::getBitCast(target_ids, T_psize),
+                                                    ConstantExpr::getBitCast(cpu_target_global, T_psize)
                                             }),
                                             "jl_image_pointers");
             addComdat(pointers, TheTriple);

src/jl_exported_funcs.inc

@@ -190,6 +190,7 @@
     XX(jl_check_binding_currently_writable) \
     XX(jl_get_cpu_name) \
     XX(jl_get_cpu_features) \
+    XX(jl_get_sysimage_cpu_target) \
     XX(jl_cpu_has_fma) \
     XX(jl_get_current_task) \
     XX(jl_get_default_sysimg_path) \

src/processor.cpp

@@ -506,6 +506,20 @@ parse_cmdline(const char *option, F &&feature_cb)
     if (!option)
         abort();
 
+    // Preprocess the option string to expand "sysimage" keyword
+    std::string processed_option;
+    if (strncmp(option, "sysimage", 8) == 0 && (option[8] == '\0' || option[8] == ';')) {
+        // Replace "sysimage" with the actual sysimage CPU target
+        jl_value_t *target_str = jl_get_sysimage_cpu_target();
+        if (target_str != nullptr) {
+            processed_option = std::string(jl_string_data(target_str), jl_string_len(target_str));
+            if (option[8] == ';') {
+                processed_option += option + 8;  // append the rest after "sysimage"
+            }
+            option = processed_option.c_str();
+        }
+    }
+
     llvm::SmallVector<TargetData<n>, 0> res;
     TargetData<n> arg{};
     auto reset_arg = [&] {
@@ -633,6 +647,12 @@ static inline jl_image_t parse_sysimg(jl_image_buf_t image, F &&callback, void *
 
     const jl_image_pointers_t *pointers = (const jl_image_pointers_t *)image.pointers;
     const void *ids = pointers->target_data;
+
+    // Set the sysimage CPU target from the stored string
+    if (pointers->cpu_target_string) {
+        jl_set_sysimage_cpu_target(pointers->cpu_target_string);
+    }
+
     jl_value_t* rejection_reason = nullptr;
     JL_GC_PUSH1(&rejection_reason);
     uint32_t target_idx = callback(ctx, ids, &rejection_reason);
@@ -1002,6 +1022,9 @@ static std::string jl_get_cpu_features_llvm(void)
 
 #endif
 
+// Global variable to store the CPU target string used for the sysimage
+static std::string sysimage_cpu_target;
+
 JL_DLLEXPORT jl_value_t *jl_get_cpu_name(void)
 {
     return jl_cstr_to_string(host_cpu_name().c_str());
@@ -1038,3 +1061,17 @@ extern "C" JL_DLLEXPORT void jl_reflect_feature_names(const FeatureName **fnames
     *fnames = feature_names;
     *nf = nfeature_names;
 }
+
+extern "C" JL_DLLEXPORT jl_value_t *jl_get_sysimage_cpu_target(void) {
+    if (sysimage_cpu_target.empty()) {
+        return jl_cstr_to_string("native");
+    }
+    return jl_cstr_to_string(sysimage_cpu_target.c_str());
+}
+
+// Function to set the sysimage CPU target (called during initialization)
+void jl_set_sysimage_cpu_target(const char *cpu_target) {
+    if (cpu_target) {
+        sysimage_cpu_target = cpu_target;
+    }
+}

src/processor.h

@@ -195,6 +195,8 @@ typedef struct {
     //  This contains the number of targets
     //  in addition to the name and feature set of each target.
     const void *target_data;
+    // Original CPU target string used to build this sysimage
+    const char *cpu_target_string;
 } jl_image_pointers_t;
 
 /**
@@ -210,10 +212,15 @@ typedef struct {
 jl_image_t jl_init_processor_sysimg(jl_image_buf_t image, const char *cpu_target);
 jl_image_t jl_init_processor_pkgimg(jl_image_buf_t image);
 
+// Internal function to set the sysimage CPU target during initialization
+void jl_set_sysimage_cpu_target(const char *cpu_target);
+
 // Return the name of the host CPU as a julia string.
 JL_DLLEXPORT jl_value_t *jl_get_cpu_name(void);
 // Return the features of the host CPU as a julia string.
 JL_DLLEXPORT jl_value_t *jl_get_cpu_features(void);
+// Return the CPU target string used to build the current sysimage
+JL_DLLEXPORT jl_value_t *jl_get_sysimage_cpu_target(void);
 // Dump the name and feature set of the host CPU
 JL_DLLEXPORT jl_value_t *jl_cpu_has_fma(int bits);
 // Check if the CPU has native FMA instructions;

test/cmdlineargs.jl

@@ -1028,6 +1028,14 @@ end
         @test v[2] == ""
         @test contains(v[3], "More than one command line CPU targets specified")
     end
+
+    # Testing this more precisely would be very platform and build system dependent and brittle.
+    withenv("JULIA_CPU_TARGET" => "sysimage") do
+        v = readchomp(`$julia_path -E "Sys.sysimage_target()"`)
+        # Local builds will likely be "native" but CI shouldn't be.
+        invalid_results = Base.get_bool_env("CI", false) ? ("", "native", "sysimage") : ("", "sysimage",)
+        @test !in(v, invalid_results)
+    end
 end
 
 # Find the path of libjulia (or libjulia-debug, as the case may be)