GitHub - JuliaLang/JuliaC.jl: Package for compiling and bundling julia binaries, specially trimmed ones

3 min read Original article ↗

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:

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.
  • --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",
    rpath        = nothing, # set automatically when bundling
)

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.

Trimming

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

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.