JuliaLang/JuliaC.jl

JuliaC

JuliaC is a companion to PackageCompiler that streamlines turning Julia code into a native executable, shared library, system image, or intermediate object/bitcode. It provides:

• A CLI app juliac
• A simple library API with explicit "compile → link → bundle" steps
• Optional bundling of libjulia/stdlibs and artifacts for portable distribution
• Optional trimming of IR, metadata, and unreachable code for smaller binaries on Julia 1.12+

Built on top of PackageCompiler.jl.

Requirements

• Julia 1.12+
• A working C compiler (clang/gcc on macOS/Linux; MSYS2 mingw on Windows)

Installation

Install JuliaC as a Julia app:

pkg> app add JuliaC

Optional: enable Pkg app shims on your shell PATH so you can run juliac directly:

echo 'export PATH="$HOME/.julia/bin:$PATH"' >> ~/.bashrc    # adapt for your shell

Quick start (CLI)

Given an app in test/AppProject (see the files in this repository), compile an executable and produce a self-contained bundle in build/:

juliac \
  --output-exe app_test_exe \
  --bundle build \
  --trim=safe \
  --experimental \
  test/AppProject

Notes:

• --trim[=mode] enables removing unreachable code; on 1.12 prereleases this implies --experimental.
• Define function @main(args::Vector{String}) in your package or source file to build an executable.
• For simple scripts, a source file may be specified instead of a package directory, but this is not recommended.

Quick start (without app install)

julia --project -e "using JuliaC; JuliaC.main(ARGS)" -- \
  --output-exe app_test_exe \
  --bundle build \
  --trim=safe \
  --experimental \
  test/AppProject

CLI reference

• --output-exe <name>: Output native executable name (no path). Use --bundle to choose destination directory.
• --output-lib|--output-sysimage|--output-o|--output-bc <path>: Output path for non-executable artifacts.
• --project <path>: Project to instantiate/precompile (defaults to active project).
• --bundle <dir>: Copy required Julia libs/stdlibs and artifacts next to the output; also sets a relative rpath.
• --bundle-lazy-artifacts: Also copy lazy artifacts into the bundle (off by default; opt in when your dependencies download artifacts on first use).
• --trim[=mode]: Enable code trimming (e.g. --trim=safe). Use --trim=no to disable.
• --compile-ccallable: Export ccallable entrypoints (see C-callable section).
• --experimental: Forwarded to Julia; required for --trim on some builds.
• --verbose: Print underlying commands and timing.
• <file>: The Julia entry file or package to compile (must define @main for executables).

Library API

using JuliaC

img = ImageRecipe(
    output_type = "--output-exe",
    file        = "test/AppProject",
    trim_mode   = "safe",
    add_ccallables = false,
    verbose     = true,
)

link = LinkRecipe(
    image_recipe = img,
    outname      = "build/app_test_exe",
)

bun = BundleRecipe(
    link_recipe = link,
    output_dir  = "build", # or `nothing` to skip bundling
)

compile_products(img)
link_products(link)
bundle_products(bun)

Bundling and rpath

When --bundle (or BundleRecipe.output_dir) is set, JuliaC:

• Places the executable in <output_dir>/bin and libraries in <output_dir>/lib and <output_dir>/lib/julia (Windows: everything under <output_dir>/bin).
• Copies required artifacts alongside the bundle.
• Links your output with a relative rpath so the executable finds sibling libs (Unix uses @loader_path/../lib or $ORIGIN/../lib).
• On macOS, creates convenience versioned .dylib symlinks if missing.

This produces a relocatable directory you can distribute.

When using the Library API, set rpath = "@bundle" in LinkRecipe to use relative rpaths suitable for a relocatable bundle. The default ("@julia") uses absolute paths to the current Julia installation, which is convenient for development but not for distribution.

Trimming

On Julia 1.12+, JuliaC can exclude code proven not to be reachable from entry points, reducing binary size:

--trim=safe

On certain builds, --trim requires --experimental (JuliaC will pass it through if needed).

C-callable entrypoints

If you pass --compile-ccallable (or set ImageRecipe.add_ccallables = true), JuliaC will export ccallable entrypoints discovered in your code. This is often used when building libraries intended to be called from C or other languages.

Platform notes

• macOS/Linux: requires clang or gcc available on PATH
• Windows: looks for a MinGW compiler via LazyArtifacts or JULIA_CC
• You can override the compiler with ENV["JULIA_CC"] (e.g. clang/gcc path)

Acknowledgements

JuliaC builds on PackageCompiler.jl and Julia's own build machinery. Many thanks to their authors and contributors.

Contributing

Issues and PRs are welcome. Please provide OS, Julia version, and a minimal reproducer when reporting problems.

License

MIT. See the LICENSE file for details.