References

create_sysimage(packages::Vector{String}; kwargs...)

Create a system image that includes the package(s) in packages given as a string or vector).

An attempt to automatically find a compiler will be done but can also be given explicitly by setting the environment variable JULIA_CC to a path to a compiler (can also include extra arguments to the compiler, like -g).

Keyword arguments:

• sysimage_path::Union{String,Nothing}: The path to where the resulting sysimage should be saved. If set to nothing the keyword argument replace_default needs to be set to true.

• project::String: The project that should be active when the sysimage is created, defaults to the currently active project.

• precompile_execution_file::Union{String, Vector{String}}: A file or list of files that contain code from which precompilation statements should be recorded.

• precompile_statements_file::Union{String, Vector{String}}: A file or list of files that contain precompilation statements that should be included in the sysimage.

• incremental::Bool: If true, build the new sysimage on top of the sysimage of the current process otherwise build a new sysimage from scratch. Defaults to true.

• filter_stdlibs::Bool: If true, only include stdlibs that are in the project file. Defaults to false, only set to true if you know the potential pitfalls.

• replace_default::Bool: If true, replace the default system image which is automatically used when Julia starts. To replace with the one Julia ships with, use restore_default_sysimage()

• include_transitive_dependencies::Bool: If true, explicitly put all transitive dependencies into the sysimage. This only makes a differecnce if some packages do not load all their dependencies when themselves are loaded. Defaults to true.

Advanced keyword arguments

• base_sysimage::Union{Nothing, String}: If a String, names an existing sysimage upon which to build the new sysimage incrementally, instead of the sysimage of the current process. Defaults to nothing. Keyword argument incremental must be true if base_sysimage is not nothing.

• cpu_target::String: The value to use for JULIA_CPU_TARGET when building the system image.

• script::String: Path to a file that gets executed in the --output-o process.

• sysimage_build_args::Cmd: A set of command line options that is used in the Julia process building the sysimage, for example -O1 --check-bounds=yes.

restore_default_sysimage()

Restores the default system image to the one that Julia shipped with. Useful after running create_sysimage with replace_default=true.

create_app(package_dir::String, compiled_app::String; kwargs...)

Compile an app with the source in package_dir to the folder compiled_app. The folder package_dir needs to contain a package where the package includes a function with the signature

julia_main()::Cint
    # Perhaps do something based on ARGS
    ...
end

The executable will be placed in a folder called bin in compiled_app and when the executable run the julia_main function is called.

Standard Julia arguments are set by passing them after a --julia-args argument, for example:

$ ./MyApp input.csv --julia-args -O3 -t8

An attempt to automatically find a compiler will be done but can also be given explicitly by setting the environment variable JULIA_CC to a path to a compiler (can also include extra arguments to the compiler, like -g).

Keyword arguments:

• app_name::String: an alternative name for the compiled app. If not provided, the name of the package (as specified in Project.toml) is used.

• precompile_execution_file::Union{String, Vector{String}}: A file or list of files that contain code from which precompilation statements should be recorded.

• precompile_statements_file::Union{String, Vector{String}}: A file or list of files that contain precompilation statements that should be included in the sysimage for the app.

• incremental::Bool: If true, build the new sysimage on top of the sysimage of the current process otherwise build a new sysimage from scratch. Defaults to false.

• filter_stdlibs::Bool: If true, only include stdlibs that are in the project file. Defaults to false, only set to true if you know the potential pitfalls.

• audit::Bool: Warn about eventual relocatability problems with the app, defaults to true.

• force::Bool: Remove the folder compiled_app if it exists before creating the app.

• include_lazy_artifacts::Bool: if lazy artifacts should be included in the bundled artifacts, defaults to true.

• include_transitive_dependencies::Bool: If true, explicitly put all transitive dependencies into the sysimage. This only makes a differecnce if some packages do not load all their dependencies when themselves are loaded. Defaults to true.

Advanced keyword arguments

• cpu_target::String: The value to use for JULIA_CPU_TARGET when building the system image.

• sysimage_build_args::Cmd: A set of command line options that is used in the Julia process building the sysimage, for example -O1 --check-bounds=yes.

create_library(package_dir::String, dest_dir::String; kwargs...)

Compile a library with the source in package_dir to the folder dest_dir. The folder package_dir should to contain a package with C-callable functions, e.g.

Base.@ccallable function julia_cg(fptr::Ptr{Cvoid}, cx::Ptr{Cdouble}, cb::Ptr{Cdouble}, len::Csize_t)::Cint
    try
        x = unsafe_wrap(Array, cx, (len,))
        b = unsafe_wrap(Array, cb, (len,))
        A = COp(fptr,len)
        cg!(x, A, b)
    catch
        Base.invokelatest(Base.display_error, Base.catch_stack())
        return 1
    end
    return 0
end

The library will be placed in the lib folder in dest_dir (or bin on Windows), and can be linked to and called into from C/C++ or other languages that can use C libraries.

Note that any applications/programs linking to this library may need help finding it at run time. Options include

• Installing all libraries somewhere in the library search path.
• Adding /path/to/libname to an appropriate library search path environment variable (DYLD_LIBRARY_PATH on OSX, PATH on Windows, or LD_LIBRARY_PATH on Linux/BSD/Unix).
• Running install_name_tool -change libname /path/to/libname (OSX)

To use any Julia exported functions, you must first call init_julia(argc, argv), where argc and argv are parameters that would normally be passed to julia on the command line (e.g., to set up the number of threads or processes).

When your program is exiting, it is also suggested to call shutdown_julia(retcode), to allow Julia to cleanly clean up resources and call any finalizers. (This function simply calls jl_atexit_hook(retcode).)

An attempt to automatically find a compiler will be done but can also be given explicitly by setting the environment variable JULIA_CC to a path to a compiler (can also include extra arguments to the compiler, like -g).

Keyword arguments:

• lib_name::String: an alternative name for the compiled library. If not provided, the name of the package (as specified in Project.toml) is used. lib will be prepended to the name if it is not already present.

• precompile_execution_file::Union{String, Vector{String}}: A file or list of files that contain code from which precompilation statements should be recorded.

• precompile_statements_file::Union{String, Vector{String}}: A file or list of files that contain precompilation statements that should be included in the sysimage for the library.

• incremental::Bool: If true, build the new sysimage on top of the sysimage of the current process otherwise build a new sysimage from scratch. Defaults to false.

• filter_stdlibs::Bool: If true, only include stdlibs that are in the project file. Defaults to false, only set to true if you know the potential pitfalls.

• audit::Bool: Warn about eventual relocatability problems with the library, defaults to true.

• force::Bool: Remove the folder compiled_lib if it exists before creating the library.

• header_files::Vector{String}: A list of header files to include in the library bundle.

• julia_init_c_file::String: File to include in the system image with functions for initializing julia from external code.

• version::VersionNumber: Library version number. Added to the sysimg .so name on Linux, and the .dylib name on Apple platforms, and with compat_level, used to determine and set the current_version, compatibility_version (on Apple) and soname (on Linux/UNIX)

• compat_level::String: compatibility level for library. One of "major", "minor". Used to determine and set the compatibility_version (on Apple) and soname (on Linux/UNIX).

• include_lazy_artifacts::Bool: if lazy artifacts should be included in the bundled artifacts, defaults to true.

• include_transitive_dependencies::Bool: If true, explicitly put all transitive dependencies into the sysimage. This only makes a differecnce if some packages do not load all their dependencies when themselves are loaded. Defaults to true.

Advanced keyword arguments

• cpu_target::String: The value to use for JULIA_CPU_TARGET when building the system image.

• sysimage_build_args::Cmd: A set of command line options that is used in the Julia process building the sysimage, for example -O1 --check-bounds=yes.

audit_app(app_dir::String)

Check for possible problems with regards to relocatability for the project at app_dir.