rules_julia

Overview

This repository implements Bazel rules for the Julia programming language.

Setup

To begin using the rules, add the following to your MODULE.bazel file.

bazel_dep(name = "rules_julia", version = "{version}")

julia = use_extension("@rules_julia//julia:extensions.bzl", "julia")
use_repo(julia, "julia_toolchains")

register_toolchains(
    "@julia_toolchains//:all",
)

The default Julia version is always registered. To make additional versions available, request them and select one with the version setting:

julia.toolchain(version = "1.11.9")

bazel build --@rules_julia//julia/settings:version=1.11.9 //...

Compilation mode

Optimization level, bounds checking and debug info follow --compilation_mode through the toolchain's opt_level, check_bounds and debug_info attributes, and apply uniformly to precompilation, system images and the binaries that load them, since Julia rejects compile caches built with other values. By default fastbuild and opt use Julia's own defaults, which also match the standard library caches Julia ships, and dbg builds with -O0, --check-bounds=yes and -g2. Per-target julia_flags carry everything else, such as --threads.

Package layout

Targets follow Julia's conventions. A julia_library named Foo is loaded with using Foo from src/Foo.jl (or Foo.jl next to the BUILD.bazel file). When the package directory also holds a Project.toml, list it in data so Julia loads the package through it. The package then has the name and UUID recorded there, which packages such as Preferences and package extensions depend on, and its dependencies resolve from the [deps] table:

julia_library(
    name = "Foo",
    srcs = glob(["src/**/*.jl"]),
    data = ["Project.toml"],
    deps = ["@deps//:JSON"],
)

Packages installed by the pkg extension are always set up this way.

System images

A system image is Julia's own ahead-of-time format: the shared library julia --sysimage loads in place of the stock one, with every included module already compiled, so loading them costs nothing at startup. julia_sysimage produces one from a set of packages and their dependencies as an ordinary, cached target:

julia_sysimage(
    name = "image",
    deps = ["@deps//:JSON", "//my/lib"],
)

julia --sysimage="$(bazel cquery --output=files //:image)" -e 'using JSON'

julia_standalone_binary builds on the same actions to produce an executable around a package with a julia_main function.

External dependencies

Third party packages are declared the way Julia expects: a Project.toml with a resolved Manifest.toml next to it. The pkg module extension turns every package in the manifest into a julia_library target.

pkg = use_extension("@rules_julia//julia/pkg:extensions.bzl", "pkg")
pkg.from_manifest(
    name = "deps",
    manifest = "//:Manifest.toml",
)
use_repo(pkg, "deps")

Packages are then available as @deps//:<PackageName>:

julia_binary(
    name = "app",
    srcs = ["app.jl"],
    deps = ["@deps//:JSON"],
)

Package tarballs are fetched from the Julia package server using the UUID and git tree hash recorded in the manifest. On Bazel 9 and newer the integrity value of each tarball is stored in the facts section of MODULE.bazel.lock the first time it is needed, so no additional lockfile has to be maintained. Keep --lockfile_mode at its default (update) so the facts are persisted.

A julia_pkg_resolve target resolves manifests from Project.toml without leaving Bazel, and julia_pkg_resolve_test fails when they drift apart. Pkg resolves against one Julia version, so each manifest is declared with the Julia minor version it is for and is resolved and verified under a toolchain of that version, whatever the version setting selects elsewhere:

load("@rules_julia//julia/pkg:defs.bzl", "julia_pkg_resolve", "julia_pkg_resolve_test")

julia_pkg_resolve(
    name = "pkg_update",
    project_toml = "Project.toml",
    manifests = {"Manifest.toml": "1.12"},
)

julia_pkg_resolve_test(
    name = "pkg_test",
    resolver = ":pkg_update",
)

bazel run //:pkg_update
bazel run //:pkg_update -- --add JSON

Several Julia versions

A manifest is only valid for the Julia minor version that resolved it: the standard libraries, compat bounds and Pkg itself all move with the minor version. A project supporting several versions carries one manifest per version, following Pkg's Manifest-v<major>.<minor>.toml convention, and one run of the resolver updates all of them:

julia_pkg_resolve(
    name = "pkg_update",
    project_toml = "Project.toml",
    manifests = {
        "Manifest-v1.10.toml": "1.10",
        "Manifest-v1.12.toml": "1.12",
    },
)

pkg.from_manifest(
    name = "deps",
    manifests = [
        "//:Manifest-v1.10.toml",
        "//:Manifest-v1.12.toml",
    ],
)

The extension reads the Julia version recorded in each manifest and builds a package graph per version. @deps//:<PackageName> selects the graph matching @rules_julia//julia/settings:version, and every package is marked incompatible with other versions, so targets depending on a package without a manifest for the selected Julia are skipped by wildcard builds and fail with Bazel's standard incompatibility message when built explicitly.

Artifacts

Many packages depend on prebuilt binaries or data shipped as Julia artifacts, most visibly the _jll packages wrapping C libraries. These are built by BinaryBuilder inside a cross compilation environment that cannot be reproduced in a Bazel action, so the published tarballs are consumed as-is, pinned by the SHA-256 and git tree hash recorded in each package's Artifacts.toml.

The pkg extension defines a repository per artifact variant and chooses in two steps, so only relevant variants are ever downloaded. Operating system and CPU come from the target platform and are decided by select(). The remaining tags, the libgfortran ABI and the C++ std::string ABI, describe the runtimes bundled with the Julia distribution rather than the machine, so they are decided against the resolved toolchain's libgfortran_version and cxxstring_abi attributes, which default to what official Julia binaries ship. Users pick a platform and a Julia version; nothing else needs setting.

On Linux the C library is assumed to be glibc, which is what official Julia binaries are built against; musl variants are not selected. This will follow the libc constraint from platforms_contrib once it is available. Artifacts for other operating systems carry no libc tag.

Variants that differ only in tags the rules do not model (for example libstdcxx_version) resolve to the newest one, matching what Pkg picks on a current Julia. A package whose artifact has no variant for the target platform fails to analyze with a message listing the platforms it is available for. Lazy artifacts, which Julia itself only downloads on first use, are the exception: they are fetched like any other where a variant exists, and simply omitted on platforms without one, so a package that never touches the artifact there still builds. Code that does touch it fails at the point of use, as it would under Julia without network access.

Artifact metadata is recorded next to the package integrity values, in MODULE.bazel.lock facts or in Manifest.bazel.json, so reading Artifacts.toml happens once per package version.

Publishing a module

Facts are only persisted in the root module's lockfile. A module consumed by other Bazel modules should instead ship a Manifest.bazel.json so consumers never download tarballs just to learn their hashes. Set manifest_bazel_json on julia_pkg_resolve to generate it and pass it to pkg.from_manifest as lockfile instead of manifest.

pkg.from_manifest(
    name = "deps",
    lockfile = "//:Manifest.bazel.json",
)

Publishing artifacts

Julia distributes binaries and large data as artifacts: gzipped tarballs identified by the git tree hash of their contents, listed in a package's Artifacts.toml with a download URL and SHA-256. There is no registry for them; any URL works, and GitHub releases are the usual host.

julia_artifact builds one from Bazel targets, so a cc_binary, a generated data set or any other output becomes an artifact in exactly the form Pkg expects. The tarball is packed with the Tar and 7z Julia ships and both hashes come from the code Pkg uses to verify downloads:

load("@rules_julia//julia:defs.bzl", "julia_artifact")

julia_artifact(
    name = "libfoo",
    srcs = ["include/foo.h"],
    files = {":libfoo_shared": "lib/libfoo.so"},
    platform_tags = ["os", "arch", "libc"],
    url = "https://github.com/me/Foo.jl/releases/download/v1.0.0/{file}",
)

This produces libfoo.tar.gz and libfoo.Artifacts.toml:

[[libfoo]]
arch = "x86_64"
git-tree-sha1 = "..."
libc = "glibc"
os = "linux"

    [[libfoo.download]]
    sha256 = "..."
    url = "https://github.com/me/Foo.jl/releases/download/v1.0.0/libfoo.tar.gz"

Upload the tarball to the URL and merge the entry into the package's Artifacts.toml. Platform tags are read from the target platform and the @rules_julia//julia/settings flags, so building the same target under several --platforms gives one entry per platform to concatenate. Leave platform_tags empty for platform independent artifacts. Without url the entry has no download table, for filling in once the file is hosted.

Packages themselves need no publishing step: Pkg installs a package from its git tree, so a repository built with these rules is registered with Registrator or LocalRegistry exactly like any other Julia package.

Julia Bazel rules

Rules

• julia_artifact
• julia_binary
• julia_format_test
• julia_library
• julia_standalone_binary
• julia_sysimage
• julia_test
• julia_toolchain

Aspects

• julia_format_aspect

julia_artifact

load("@rules_julia//julia:defs.bzl", "julia_artifact")

julia_artifact(name, srcs, out, artifact_name, files, lazy, platform_tags, strip_prefix, url)

Build a Julia artifact from Bazel targets.

Julia distributes binaries and data as artifacts: gzipped tarballs identified by the git tree hash of their contents and listed in a package's Artifacts.toml with a download URL and SHA-256. This rule produces both halves: the tarball, packed with the same Tar and 7z Julia itself uses, and an Artifacts.toml holding the entry for it, with both hashes computed by the code Pkg uses to verify downloads. Upload the tarball to the URL and merge the entry into the package's Artifacts.toml; Pkg and artifact"name" then install it like any other artifact.

Files from srcs keep their path relative to the package (or strip_prefix below it); files places outputs from anywhere at an explicit path. Directories (tree artifacts) are copied whole.

Platform specific artifacts set platform_tags. The values are taken from the target platform (os, arch) and the @rules_julia//julia/settings flags (libgfortran_version and cxxstring_abi from the toolchain; libc is assumed glibc on Linux), so building the same target under several --platforms yields one entry per platform, ready to be concatenated. Platform independent artifacts (data, models, ...) leave it empty.

Example:

julia_artifact(
    name = "libfoo",
    srcs = ["include/foo.h"],
    files = {":libfoo_shared": "lib/libfoo.so"},
    platform_tags = ["os", "arch", "libc"],
    url = "https://github.com/me/Foo.jl/releases/download/v1.0.0/{file}",
)

produces libfoo.tar.gz and libfoo.Artifacts.toml:

[[libfoo]]
arch = "x86_64"
git-tree-sha1 = "..."
libc = "glibc"
os = "linux"

    [[libfoo.download]]
    sha256 = "..."
    url = "https://github.com/me/Foo.jl/releases/download/v1.0.0/libfoo.tar.gz"

ATTRIBUTES

julia_binary

load("@rules_julia//julia:defs.bzl", "julia_binary")

julia_binary(name, deps, srcs, data, env, julia_flags, main)

A Julia executable.

ATTRIBUTES

julia_format_test

load("@rules_julia//julia:defs.bzl", "julia_format_test")

julia_format_test(name, config, target)

A rule for running JuliaFormatter on a Julia target.

ATTRIBUTES

julia_library

load("@rules_julia//julia:defs.bzl", "julia_library")

julia_library(name, deps, srcs, data, precompile)

A sharable Julia library or module.

ATTRIBUTES

julia_standalone_binary

load("@rules_julia//julia:defs.bzl", "julia_standalone_binary")

julia_standalone_binary(name, binary, cpu_target, precompile_statements)

Build a Julia package and its dependencies into a custom system image and produce an executable that starts Julia with it.

The system image is produced in two actions: julia --output-o emits the object archive of the image, which is then linked into a shared library. By default the link uses the lld bundled with Julia, the same way Julia links its own package images; --@rules_julia//julia/settings:linker=cc selects the C++ toolchain instead. The executable is the regular Julia wrapper started with --sysimage, so all code is loaded precompiled and startup is immediate. No network access or host tools outside the Bazel toolchains are involved.

The target in binary must be a Julia package: its entry point is src/<name>.jl defining module <name> with a julia_main()::Cint function, which is called with the command line arguments in ARGS.

Example:

julia_binary(
    name = "my_app_bin",
    srcs = ["src/my_app_bin.jl"],
    deps = ["//my/lib"],
)

julia_standalone_binary(
    name = "my_app",
    binary = ":my_app_bin",
)

ATTRIBUTES

julia_sysimage

load("@rules_julia//julia:defs.bzl", "julia_sysimage")

julia_sysimage(name, deps, cpu_target, precompile_statements)

Compile Julia packages and their dependencies into a system image.

A system image is Julia's own ahead-of-time format: the shared library that julia --sysimage loads in place of the stock one, with every included module already compiled. The image is produced in two actions: julia --output-o emits the object archive, which is then linked into a shared library. By default the link uses the lld bundled with Julia, the same way Julia links its own package images; --@rules_julia//julia/settings:linker=cc selects the C++ toolchain instead. No network access or host tools outside the Bazel toolchains are involved, and the image is rebuilt only when its inputs change.

Every target in deps must be a Julia package: its entry point is src/<name>.jl defining module <name>. The output is the shared library; the object archive is available in the archive output group. For a self-contained executable around a package with a julia_main function, see julia_standalone_binary, which builds on the same actions.

Example:

julia_sysimage(
    name = "image",
    deps = ["@deps//:JSON", "//my/lib"],
)

julia --sysimage=$(bazel cquery --output=files //:image) -e 'using JSON'

ATTRIBUTES

julia_test

load("@rules_julia//julia:defs.bzl", "julia_test")

julia_test(name, deps, srcs, data, env, julia_flags, main)

A Julia test executable.

ATTRIBUTES

julia_toolchain

load("@rules_julia//julia:defs.bzl", "julia_toolchain")

julia_toolchain(name, check_bounds, cpu_target, cxxstring_abi, debug_info, julia,
                libgfortran_version, link_files, linker, opt_level, sysimage, version)

A toolchain for building Julia targets.

ATTRIBUTES

julia_format_aspect

load("@rules_julia//julia:defs.bzl", "julia_format_aspect")

julia_format_aspect()

An aspect for running JuliaFormatter on targets with Julia sources.

ASPECT ATTRIBUTES

ATTRIBUTES

Julia bzlmod extensions

Module Extensions

• julia

julia

julia = use_extension("@rules_julia//julia:extensions.bzl", "julia")
julia.toolchain(linker, version)

Bzlmod extensions for Julia

TAG CLASSES

toolchain

Request that a Julia version be made available via @julia_toolchains.

Attributes

Julia settings

Definitions for all @rules_julia//julia settings

formatter_config

--@rules_julia//julia/settings:formatter_config

The JuliaFormatter config file to use in formatting rules.

PARAMETERS

julia_minor_version

--@rules_julia//julia/settings:julia_minor_version

Return the <major>.<minor> prefix of a Julia version string.

PARAMETERS

julia_minor_versions

--@rules_julia//julia/settings:julia_minor_versions

The minor versions (1.10, 1.12, ...) with known toolchains.

linker

--@rules_julia//julia/settings:linker

The linker used to turn a system image object archive into a shared library.

• toolchain (default): whatever the resolved Julia toolchain's linker attribute says (julia for toolchains registered by the julia extension unless a julia.toolchain(linker = ...) tag says otherwise).
• julia: the lld bundled with Julia, invoked through Base.Linking exactly as Julia links its own package images. Works on every platform Julia ships for and needs no C++ toolchain.
• cc: cc_common.link with the resolved C++ toolchain. Requires a GNU-compatible toolchain; fails if no C++ toolchain resolves.

PARAMETERS

version

--@rules_julia//julia/settings:version

The version of julia to use.

Besides the flag, a config_setting named version_<major>.<minor>.<patch> is defined per known release and a version_<major>.<minor> setting per minor version matching any of its releases. Package graphs resolved for a Julia minor version are selected with the latter.

PARAMETERS

Julia Pkg rules

Rules

• julia_pkg_resolve
• julia_pkg_resolve_test

Functions

• julia_pkg_compiler
• julia_pkg_test

Module Extensions

• pkg

julia_pkg_resolve

load("@rules_julia//julia/pkg:defs.bzl", "julia_pkg_resolve")

julia_pkg_resolve(name, manifest_bazel_json, manifests, project_toml)

A rule for resolving Julia manifests from Project.toml using Julia's Pkg manager.

Running the target resolves the project once per manifest listed in manifests, each time with a Julia toolchain of the version the manifest is declared for, and writes the results in place. Pkg resolves against one Julia version (its standard libraries, compat bounds and manifest format), so a project supporting several Julia minor versions carries one manifest per version, following Pkg's own Manifest-v<major>.<minor>.toml convention. Pass the manifests to the pkg module extension via pkg.from_manifest(manifests = ...); no additional lockfile is required.

Optionally, manifest_bazel_json may be set (with a single manifest) to also write a Manifest.bazel.json containing package URLs, integrity values and artifacts. Pass that file to pkg.from_manifest(lockfile = ...) for modules consumed by other Bazel modules, since module extension facts are only persisted in the root module's MODULE.bazel.lock.

Note that when setting this target up for the first time, empty manifest files need to be created. If you specify manifest_bazel_json, that file should also be created as an empty JSON object {}.

Example:

julia_pkg_resolve(
    name = "pkg_update",
    project_toml = "Project.toml",
    manifests = {
        "Manifest-v1.10.toml": "1.10",
        "Manifest-v1.12.toml": "1.12",
    },
)

Then run:

bazel run //:pkg_update

Packages can be added to Project.toml at the same time:

bazel run //:pkg_update -- --add JSON

ATTRIBUTES

julia_pkg_resolve_test

load("@rules_julia//julia/pkg:defs.bzl", "julia_pkg_resolve_test")

julia_pkg_resolve_test(name, resolver)

A test rule that verifies the manifests managed by julia_pkg_resolve are up to date.

Every manifest is checked under a Julia toolchain of the version it is declared for, by comparing the manifest's recorded project_hash with the hash of the current Project.toml. Pkg's hash algorithm differs between Julia minor versions, which is why the resolver's declaration drives which Julia runs each check. When the resolver also tracks a Manifest.bazel.json, that file is checked against the manifest as well.

The test will fail if:

• A manifest is out of date with respect to Project.toml
• A manifest was resolved with a different Julia minor version than declared
• A package is missing from Manifest.bazel.json
• Versions or UUIDs don't match between the manifest and Manifest.bazel.json
• The git-tree-sha1 is not in the package URL
• Integrity values are missing

Example:

julia_pkg_resolve(
    name = "pkg_update",
    project_toml = "Project.toml",
    manifests = {"Manifest.toml": "1.12"},
)

julia_pkg_resolve_test(
    name = "pkg_sync_test",
    resolver = ":pkg_update",
)

Then run:

bazel test //:pkg_sync_test

If the files are out of sync the test fails with details on what needs to be regenerated.

ATTRIBUTES

julia_pkg_compiler

load("@rules_julia//julia/pkg:defs.bzl", "julia_pkg_compiler")

julia_pkg_compiler(name, **kwargs)

Resolve Julia manifests from Project.toml; the former name of julia_pkg_resolve.

PARAMETERS

DEPRECATED

Use julia_pkg_resolve. The rule was renamed because "package compiler" means PackageCompiler.jl to Julia users, and this rule runs Pkg's resolver. This alias will be removed in a future release.

julia_pkg_test

load("@rules_julia//julia/pkg:defs.bzl", "julia_pkg_test")

julia_pkg_test(name, compiler, **kwargs)

Check that manifests are up to date; the former name of julia_pkg_resolve_test.

PARAMETERS

DEPRECATED

Use julia_pkg_resolve_test with resolver in place of compiler. This alias will be removed in a future release.

pkg

pkg = use_extension("@rules_julia//julia/pkg:defs.bzl", "pkg")
pkg.from_manifest(name, lockfile, manifest, manifests, pkg_server)
pkg.install(name, lockfile, manifest, manifests, pkg_server)
pkg.pkg_annotation(dep, patch_args, patch_tool, patches)

A module extension for defining Julia package dependencies.

pkg = use_extension("@rules_julia//julia/pkg:extensions.bzl", "pkg")
pkg.from_manifest(
    name = "my_deps",
    manifests = ["//:Manifest.toml"],
)
use_repo(pkg, "my_deps")

Each package in the manifests becomes a julia_library target available as @my_deps//:<PackageName>. See the from_manifest tag for how integrity values and multiple Julia versions are handled.

TAG CLASSES

from_manifest

Fetch the Julia packages recorded in one or more Manifest.toml files, or in a Manifest.bazel.json.

Exactly one of manifests (or the single-file alias manifest) or lockfile must be set.

With manifests, the stock Manifest.toml files written by Pkg are the only lockfiles. Each manifest records the Julia version that resolved it; its packages are built for that Julia minor version and marked incompatible with others, and the hub selects among manifests with @rules_julia//julia/settings:version. A project supporting several Julia versions lists one manifest per minor version (Pkg's Manifest-v<major>.<minor>.toml convention); julia_pkg_resolve resolves them all. Package tarballs are fetched from pkg_server using the UUID and git tree hash recorded for each package. On Bazel 9 and newer the integrity value of every tarball and the artifacts each package declares are persisted in the facts section of MODULE.bazel.lock, so after the first evaluation no network access is needed to evaluate the extension. On older Bazel versions the generated repositories are recorded in MODULE.bazel.lock instead.

With lockfile, a Manifest.bazel.json produced by julia_pkg_resolve provides URLs, integrity values and artifacts up front and the extension never touches the network. The lockfile carries no Julia version, so its packages are available under every version. Prefer this for modules consumed by others, since facts are only persisted in the root module's lockfile.

Pkg itself never runs: the manifest is parsed in Starlark and every package is fetched by its recorded hash.

Attributes

install

Deprecated alias of from_manifest, kept for one release.

Attributes

pkg_annotation

Attributes