References

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

Create a system image that includes the package(s) in packages (given as a string or vector). If the packages argument is not passed, all packages in the project will be put into the sysimage.

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::String: The path to where the resulting sysimage should be saved.

• project::String: The project directory 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.

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

• import_into_main::Bool: If true, import all packages from packages into Main. This allows calling using .Package without the Project.toml the sysimage was built with.

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. Defaults to native.

• 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.

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. Note that since an app-specific Project.toml is placed in the share/julia folder in compiled_app, it is generally not possible to install multiple unrelated apps to the same location.

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:

• executables::Vector{Pair{String, String}}: A list of executables to produce, given as pairs of executable_name => julia_main where executable_name is the name of the produced executable with the julia function julia_main. If not provided, the name of the package (as specified in Project.toml) is used and the main function in julia is taken as julia_main.

• 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.

• 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 false.

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

• include_preferences::Bool: If true, store all preferences visible by the project in package_dir in the app bundle. 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.

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

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

Compile a library with the source in package_or_project to the folder dest_dir. The folder package_or_project should 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

Alternatively, it can contain a project with dependencies that have C-callable functions.

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 since a library-specific Project.toml is placed in the share/julia folder in dest_dir, it is generally not possible to install multiple libraries to the same location.

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.

• 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::::Union{String, Vector{String}}: A file or list of files to include in the system image with functions for initializing Julia from external code (default: PackageCompiler.default_julia_init()).

• julia_init_h_file::::Union{String, Vector{String}}: A file or list of files to include in the library bundle, with declarations for the functions defined in the file(s) provided via julia_init_c_file (default: PackageCompiler.default_julia_init_header()).

• 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 false.

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

• include_preferences::Bool: If true, store all preferences visible by the project in project_or_package in the library bundle. Defaults to true.

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

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.