System Image Building

    This operation is useful for multiple reasons. A user may:

    • Build a precompiled shared library system image on a platform that did not ship with one, thereby improving startup times.
    • Modify Base, rebuild the system image and use the new Base next time Julia is started.
    • Include a userimg.jl file that includes packages into the system image, thereby creating a system image that has packages embedded into the startup environment.

    Julia now ships with a script that automates the tasks of building the system image, wittingly named build_sysimg.jl that lives in DATAROOTDIR/julia/. That is, to include it into a current Julia session, type:

    This will include a build_sysimg function:

    Main.BuildSysImg.build_sysimg — Function.

    Rebuild the system image. Store it in sysimg_path, which defaults to a file named sys.ji that sits in the same folder as libjulia.{so,dylib}, except on Windows where it defaults to Sys.BINDIR/../lib/julia/sys.ji. Use the cpu instruction set given by cpu_target. Valid CPU targets are the same as for the -C option to julia, or the -march option to gcc. Defaults to native, which means to use all CPU instructions available on the current processor. Include the user image file given by userimg_path, which should contain directives such as using MyPackage to include that package in the new system image. New system image will not replace an older image unless force is set to true.

    Note that this file can also be run as a script itself, with command line arguments taking the place of arguments passed to the function. For example, to build a system image in /tmp/sys.{so,dll,dylib}, with the core2 CPU instruction set, a user image of ~/userimg.jl and force set to true, one would execute:

    System image optimized for multiple microarchitectures

    A multi-microarchitecture system image can be enabled by passing multiple targets during system image compilation. This can be done either with the JULIA_CPU_TARGET make option or with the -C command line option when running the compilation command manually. Multiple targets are separated by ; in the option string. The syntax for each target is a CPU name followed by multiple features separated by ,. All features supported by LLVM are supported and a feature can be disabled with a - prefix. (+ prefix is also allowed and ignored to be consistent with LLVM syntax). Additionally, a few special features are supported to control the function cloning behavior.

    1. base(<n>)

      Where <n> is a placeholder for a non-negative number (e.g. base(0), base(1)). By default, a partially cloned (i.e. not clone_all) target will use functions from the default target (first one specified) if a function is not cloned. This behavior can be changed by specifying a different base with the base(<n>) option. The nth target (0-based) will be used as the base target instead of the default (0th) one. The base target has to be either 0 or another target. Specifying a non-clone_all target as the base target will cause an error.

    2. opt_size

      This causes the function for the target to be optimized for size when there isn’t a significant runtime performance impact. This corresponds to -Os GCC and Clang option.

    3. This cause the function for the targe to be optimize for size that might have a significant runtime performance impact. This corresponds to -Oz Clang option.

    As an example, at the time of this writing, the following string is used in the creation of the official x86_64 Julia binaries downloadable from julialang.org:

    This creates a system image with three separate targets; one for a generic x86_64 processor, one with a sandybridge ISA (explicitly excluding xsaveopt) that explicitly clones all functions, and one targeting the haswell ISA, based off of the sandybridge sysimg version, and also excluding rdrnd. When a Julia implementation loads the generated sysimg, it will check the host processor for matching CPU capability flags, enabling the highest ISA level possible. Note that the base level (generic) requires the cx16 instruction, which is disabled in some virtualization software and must be enabled for the generic target to be loaded. Alternatively, a sysimg could be generated with the target generic,-cx16 for greater compatibility, however note that this may cause performance and stability problems in some code.

    Implementation overview

    This is a brief overview of different part involved in the implementation. See code comments for each components for more implementation details.

    1. System image loading