References
PackageCompiler.create_sysimage
— Functioncreate_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
: Iftrue
, build the new sysimage on top of the sysimage of the current process otherwise build a new sysimage from scratch. Defaults totrue
.filter_stdlibs::Bool
: Iftrue
, only include stdlibs that are in the project file. Defaults tofalse
, only set totrue
if you know the potential pitfalls.include_transitive_dependencies::Bool
: Iftrue
, 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 totrue
.import_into_main::Bool
: Iftrue
, import all packages frompackages
intoMain
. This allows callingusing .Package
without the Project.toml the sysimage was built with.
Advanced keyword arguments
base_sysimage::Union{Nothing, String}
: If aString
, names an existing sysimage upon which to build the new sysimage incrementally, instead of the sysimage of the current process. Defaults tonothing
. Keyword argumentincremental
must betrue
ifbase_sysimage
is notnothing
.cpu_target::String
: The value to use forJULIA_CPU_TARGET
when building the system image. Defaults tonative
.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
.
PackageCompiler.create_app
— Functioncreate_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 ofexecutable_name => julia_main
whereexecutable_name
is the name of the produced executable with the julia functionjulia_main
. If not provided, the name of the package (as specified inProject.toml
) is used and the main function in julia is taken asjulia_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
: Iftrue
, build the new sysimage on top of the sysimage of the current process otherwise build a new sysimage from scratch. Defaults tofalse
.filter_stdlibs::Bool
: Iftrue
, only include stdlibs that are in the project file. Defaults tofalse
, only set totrue
if you know the potential pitfalls.force::Bool
: Remove the foldercompiled_app
if it exists before creating the app.include_lazy_artifacts::Bool
: if lazy artifacts should be included in the bundled artifacts, defaults tofalse
.include_transitive_dependencies::Bool
: Iftrue
, 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 totrue
.include_preferences::Bool
: Iftrue
, store all preferences visible by the project inpackage_dir
in the app bundle. Defaults totrue
.
Advanced keyword arguments
cpu_target::String
: The value to use forJULIA_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.
PackageCompiler.create_library
— Functioncreate_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, orLD_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
: Iftrue
, build the new sysimage on top of the sysimage of the current process otherwise build a new sysimage from scratch. Defaults tofalse
.filter_stdlibs::Bool
: Iftrue
, only include stdlibs that are in the project file. Defaults tofalse
, only set totrue
if you know the potential pitfalls.force::Bool
: Remove the foldercompiled_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 viajulia_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 withcompat_level
, used to determine and set thecurrent_version
,compatibility_version
(on Apple) andsoname
(on Linux/UNIX)compat_level::String
: compatibility level for library. One of "major", "minor". Used to determine and set thecompatibility_version
(on Apple) andsoname
(on Linux/UNIX).include_lazy_artifacts::Bool
: if lazy artifacts should be included in the bundled artifacts, defaults tofalse
.include_transitive_dependencies::Bool
: Iftrue
, 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 totrue
.include_preferences::Bool
: Iftrue
, store all preferences visible by the project inproject_or_package
in the library bundle. Defaults totrue
.script::String
: Path to a file that gets executed in the--output-o
process.
Advanced keyword arguments
cpu_target::String
: The value to use forJULIA_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
.