rules_ada

Bazel rules for building Ada with GNAT.

Install

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

Getting started

1. Add rules_ada to MODULE.bazel.
2. Define Ada targets with rules from @rules_ada//ada:defs.bzl.
3. Build or test with Bazel:

bazel build //:your_target
bazel test //:your_test

Features

• Ada libraries, binaries, and tests
• Static and shared library outputs
• Coverage support via bazel coverage
• Interop with C/C++/Rust via CcInfo
• Hermetic GNAT toolchains, registered automatically (see Toolchains)

Example

load("@rules_ada//ada:defs.bzl", "ada_binary", "ada_library", "ada_test")

ada_library(
    name = "math_utils",
    srcs = [
        "math_utils.ads",
        "math_utils.adb",
    ],
)

ada_binary(
    name = "calculator",
    srcs = ["main.adb"],
    deps = [":math_utils"],
)

ada_test(
    name = "math_test",
    srcs = ["math_test.adb"],
    deps = [":math_utils"],
)

Rule reference

See Rules.

Runfiles

Programs that need data files at runtime can locate them with the runfiles library.

Toolchains

rules_ada ships with hermetic GNAT toolchains built by hermetic-gnat. The ada module extension declared in @rules_ada//ada:extensions.bzl downloads the archive for the execution platform on first use and rules_ada registers the resulting toolchains itself, so a consumer only needs the bazel_dep.

Supported platforms

Selecting a GCC version

Every rules_ada release tracks exactly one hermetic-gnat release. That release contains one toolchain per supported GCC version; the newest is the default. The version build setting selects another one:

bazel build --@rules_ada//ada/settings:version=15.3.0 //...

The accepted values, the tracked hermetic-gnat release and the default are all recorded in ada/private/versions.bzl. A config_setting named @rules_ada//ada/settings:version_<gcc version> exists for each entry and can be used in select().

The C/C++ toolchain

Linking, archiving (when the GNAT archive ships no ar) and interop with cc_* targets use the C/C++ toolchain registered by rules_cc. On macOS the Apple toolchain from apple_support must be registered before the default one, so add it to your own MODULE.bazel ahead of any bazel_dep on rules_cc:

bazel_dep(name = "apple_support", version = "2.5.4")

Link lines

Every link command is the compiler followed by the expansion of the toolchain's args: ada_args targets whose templates reference the variables of the action, in the order the toolchain lists them, then the arguments of enabled features in known_features order. The rules add nothing on their own, not even -o, so a toolchain has full control over the command line.

rules_ada ships complete link lines per platform family that the hermetic toolchains use and a custom toolchain can reuse, extend or replace:

The building blocks live in @rules_ada//ada/toolchains/args (objects, gnu_libraries_to_link, darwin_libraries_to_link, dep_link_flags, user_link_flags, runtime_libraries, coverage_link_flags, output, ...). The two link actions, link_executable and link_shared_library, expose these variables:

A template is a plain string with {name} or {name.field} placeholders. An argument that is exactly {name} for a list expands to one argument per element; iterate_over expands a whole ada_args once per element with the element bound to the list's name; requires_true, requires_false, requires_not_none and requires_none make an ada_args (or an ada_nested_args inside an iteration) conditional. An empty list counts as unset. Templates are checked against the action's variables when the ada_args target is analyzed.

ada_args can also target compile, bind and archive; those actions expose no variables, and the arguments are appended after the toolchain's compile_flags or bind_flags, or right after the archiver.

Features

Features follow the cc_* rules' conventions. An ada_feature names a set of arguments; a toolchain lists the features it understands in known_features and the ones on by default in enabled_features; a target adds or removes them with features = ["name"] or features = ["-name"]; --features applies to every target. The effective set is also forwarded to the C/C++ toolchain.

linkopts are passed through verbatim and never inspected; a target that wants the shared libgcc disables the feature rather than passing -shared-libgcc.

Differences from gnatlink

The hermetic toolchains aim to produce the binaries gnatmake and gprbuild would, so that moving a project to Bazel changes as little as possible. Two things take precedence over that, in order: every output must be byte-for-byte reproducible across machines, and it must not depend on files of the build machine that another machine may lack. Where gnatlink falls short of either, rules_ada deviates, and the comment next to the deviation says what the ecosystem does instead. The shipped arg sets and features make every one of them reversible for a custom toolchain or a target.

Linking on macOS

GCC's Darwin driver, as built for the hermetic toolchains, records absolute -rpath entries for its own lib/ directories in every executable and shared library, and links @rpath/libgcc_s.1.1.dylib from there. Inside Bazel those directories live in the output base that ran the link, so such a binary loads only on that machine and fails with Library not loaded: @rpath/libgcc_s.1.1.dylib when a remote cache hands it to another one.

The hermetic macOS toolchains therefore link with @rules_ada//ada/toolchains/args/darwin:nodefaultrpaths and, like every hermetic toolchain, enable the static_libgcc feature, which leaves the output with no dependency on the toolchain at all. Exception propagation across dlopen boundaries does not need a shared libgcc on macOS: the unwinder is libSystem's for every image.

A target that disables static_libgcc with features = ["-static_libgcc"] keeps the dynamic libgcc. rules_ada then symlinks the toolchain's dynamic_runtime_lib into <output>.runtime_libs/ beside the executable or library, lists that directory in runtime_library_search_directories (which the darwin link line turns into an @loader_path rpath), and carries the staged copy in the target's runfiles and, for ada_shared_library, its default outputs. The result loads from bazel-bin, from a runfiles tree and from a remote cache hit alike. The staged files are symlinks, so copying a binary out of bazel-bin by hand needs cp -L.

Other dylibs in the toolchain's lib/ are not staged. In particular -lstdc++ resolves to the bundled GNU libstdc++.6.dylib and has the same problem; link Apple's -lc++ instead when mixing in C++ built by the Xcode toolchain.

Deployment target

The Apple C/C++ toolchain compiles and links for --macos_minimum_os, which defaults to the version of the selected SDK. GNAT's driver defaults to the macOS release the toolchain was built on, and Apple's linker warns about every C/C++ object "built for newer macOS version than being linked" when the two differ. rules_ada reads the version from the C/C++ toolchain's -target or -mmacosx-version-min flag and exposes it as the macos_deployment_target variable; the darwin link line passes it as -mmacosx-version-min to every executable and shared library link, so the output's deployment target is the one its C/C++ parts already require. Set --macos_minimum_os to lower both at once. Without a registered C/C++ toolchain the variable is unset and the GNAT default is left alone.

Defining custom toolchains

The hermetic-gnat toolchains above are registered automatically and need no configuration. A GNAT installation that rules_ada does not ship, such as a distribution package or a vendor build, is declared with the ada_toolchain rule and a toolchain() for @rules_ada//ada:toolchain_type. The runtime archives go in static_runtime_lib, in link order, and the link line is assembled from ada_args, here the shipped ELF one plus the system libraries:

load("@rules_ada//ada:ada_toolchain.bzl", "ada_toolchain")
load("@rules_ada//ada/toolchains:defs.bzl", "LINK_ACTIONS", "ada_args")

ada_args(
    name = "system_libs",
    actions = LINK_ACTIONS,
    args = ["-lm", "-lpthread", "-ldl", "-lrt"],
)

ada_toolchain(
    name = "gnat_toolchain",
    compiler = "@gnat//:bin/gcc",
    binder = "@gnat//:bin/gnatbind",
    ar = "@gnat//:bin/ar",
    gcov = "@gnat//:bin/gcov",
    ada_std = "@gnat//:ada_std",
    compiler_lib = "@gnat//:compiler_lib",
    static_runtime_lib = [
        "@gnat//:lib/gcc/x86_64-pc-linux-gnu/16.1.0/adalib/libgnarl.a",
        "@gnat//:lib/gcc/x86_64-pc-linux-gnu/16.1.0/adalib/libgnat.a",
        "@gnat//:lib/gcc/x86_64-pc-linux-gnu/16.1.0/libgcc.a",
    ],
    args = [
        "@rules_ada//ada/toolchains/args/elf:link_line",
        ":system_libs",
    ],
    known_features = ["@rules_ada//ada/toolchains/features:static_libgcc"],
    target_triple = "x86_64-pc-linux-gnu",
)

toolchain(
    name = "gnat",
    exec_compatible_with = ["@platforms//os:linux", "@platforms//cpu:x86_64"],
    toolchain = ":gnat_toolchain",
    toolchain_type = "@rules_ada//ada:toolchain_type",
)

GNU ld scans archives once, so libgnarl.a (which references libgnat.a) must come first, as in gnatlink's own -lgnarl -lgnat. Coverage builds look for libgcov.a next to the listed libgcc.a. Anything the shipped link line does not cover is one more ada_args; a toolchain that needs a different structure lists the building blocks from @rules_ada//ada/toolchains/args itself, or its own ada_args, instead of link_line.

A macOS toolchain additionally declares the shared libgcc, enables static_libgcc, and keeps the driver's rpaths out of the outputs (-nodefaultrpaths needs GCC 13 or newer):

ada_toolchain(
    name = "gnat_toolchain",
    # ... as above, with the aarch64-apple-darwin paths ...
    dynamic_runtime_lib = ["@gnat//:lib/libgcc_s.1.1.dylib"],
    args = [
        "@rules_ada//ada/toolchains/args/darwin:link_line",
        "@rules_ada//ada/toolchains/args/darwin:sysroot_from_env",
        "@rules_ada//ada/toolchains/args/darwin:nodefaultrpaths",
    ],
    known_features = ["@rules_ada//ada/toolchains/features:static_libgcc"],
    enabled_features = ["@rules_ada//ada/toolchains/features:static_libgcc"],
    target_triple = "aarch64-apple-darwin24.6.0",
)

Output file names follow artifact_name_patterns; a Windows toolchain sets {"executable": "%{name}.exe", "shared_library": "%{name}.dll"} and uses @rules_ada//ada/toolchains/args/windows:link_line. A DLL declared in dynamic_runtime_lib is staged and carried in runfiles like on any other platform, but Windows has no rpath: it is only found if its directory is on PATH.

Migrating from 0.2.x

• link_flags is gone. Flags move into an ada_args target listed in args after the shipped link_line for the platform (so they follow the runtime archives), as system_libs does above. Runtime archives go in static_runtime_lib, in the same order they had.
• enabled_features now takes ada_feature labels, and every enabled feature must also be in known_features.
• -shared-libgcc in linkopts is no longer special; use features = ["-static_libgcc"]. On the hermetic macOS toolchains the linkopt now reaches the driver together with -static-libgcc, which wins.
• On macOS, executables now use @loader_path rpaths like shared libraries and cc_binary; staged runtime libraries follow the real output name (main.exe.runtime_libs/ on Windows).

Runfiles

@rules_ada//ada/runfiles is an Ada implementation of Bazel's runfiles lookup, equivalent to the C++ and Python libraries that ship with Bazel. It finds the runfiles manifest or directory from the environment or from the program's own path and resolves Rlocation paths, honouring the bzlmod repository mapping.

ada_binary(
    name = "tool",
    srcs = ["tool.adb"],
    data = ["config.toml"],
    deps = ["@rules_ada//ada/runfiles"],
)

with Runfiles;

procedure Tool is
   R    : constant Runfiles.Context := Runfiles.Create;
   Path : constant String :=
     R.Rlocation ("my_module/config.toml", Source_Repo => "");
begin
   ...
end Tool;

The full API and discovery rules are documented in the library's README.

Rules

• ada_args
• ada_args_list
• ada_binary
• ada_feature
• ada_info
• ada_library
• ada_nested_args
• ada_shared_library
• ada_static_library
• ada_test
• ada_toolchain

ada_args

Rules

• ada_args

ada_args

load("@rules_ada//ada/toolchains:args.bzl", "ada_args")

ada_args(name, data, actions, args, iterate_over, nested, requires_false, requires_none,
         requires_not_none, requires_true)

Arguments an Ada toolchain passes to some of its actions.

Templates expand variables of the action ({output}, {objects}, ...) and can be conditional on them; the toolchains documentation lists the variables of each action. Order matters: an ada_toolchain emits its args in the order given, after the tool and before the arguments of enabled features.

load("@rules_ada//ada/toolchains:defs.bzl", "LINK_ACTIONS", "ada_args")

ada_args(
    name = "soname",
    actions = ["link_shared_library"],
    args = ["-Wl,-soname,{output_basename}"],
)

ada_args(
    name = "rpaths",
    actions = LINK_ACTIONS,
    args = ["-Wl,-rpath,$ORIGIN/{runtime_library_search_directories}"],
    iterate_over = "runtime_library_search_directories",
)

An ada_args target can be listed directly in ada_toolchain.args or bundled with ada_args_list.

ATTRIBUTES

ada_args_list

Rules

• ada_args_list

ada_args_list

load("@rules_ada//ada/toolchains:args_list.bzl", "ada_args_list")

ada_args_list(name, args)

An ordered bundle of ada_args (or other lists).

The default link lines shipped under @rules_ada//ada/toolchains/args/... are ada_args_list targets; a custom toolchain can list one of them next to its own ada_args.

ATTRIBUTES

ada_binary

Rules

• ada_binary

ada_binary

load("@rules_ada//ada:ada_binary.bzl", "ada_binary")

ada_binary(name, deps, srcs, data, compile_data, copts, linkopts, linkstatic, main, subunits)

Compiles Ada source files, binds them, and links into an executable.

ATTRIBUTES

ada_feature

Rules

• ada_feature

ada_feature

load("@rules_ada//ada/toolchains:feature.bzl", "ada_feature")

ada_feature(name, args, feature_name)

A named set of arguments that can be toggled per target.

A toolchain lists the features it understands in known_features and the ones on by default in enabled_features. Targets add or remove them with the common features attribute (features = ["-static_libgcc"]), and --features applies globally. The arguments of enabled features are emitted after the toolchain's own args, in known_features order.

ada_feature(
    name = "static_libgcc",
    feature_name = "static_libgcc",
    args = [":static_libgcc_flags"],
)

ATTRIBUTES

ada_info

Providers

• AdaInfo

Functions

• merge_ada_infos

AdaInfo

load("@rules_ada//ada:ada_info.bzl", "AdaInfo")

AdaInfo(cc_info, direct_body_alis, direct_objects, direct_spec_alis, transitive_body_alidirs,
        transitive_body_alis, transitive_exported_bodies, transitive_objects, transitive_spec_alidirs,
        transitive_spec_alis, transitive_specs, transitive_srcdirs, units)

Carries the spec/body ALI/object/source closure of an Ada compilation target.

FIELDS

merge_ada_infos

load("@rules_ada//ada:ada_info.bzl", "merge_ada_infos")

merge_ada_infos(deps)

Combine AdaInfo from deps into an aggregate view used by action helpers.

PARAMETERS

ada_library

Rules

• ada_library

ada_library

load("@rules_ada//ada:ada_library.bzl", "ada_library")

ada_library(name, deps, srcs, data, compile_data, copts, exports_bodies, linkopts, subunits)

Compiles Ada source files into a library. This is the primary rule for Ada-to-Ada dependencies and cross-language interop via CcInfo. Use ada_static_library or ada_shared_library when you need to produce a specific artifact type for external consumption.

ATTRIBUTES

ada_nested_args

Rules

• ada_nested_args

ada_nested_args

load("@rules_ada//ada/toolchains:nested_args.bzl", "ada_nested_args")

ada_nested_args(name, data, args, iterate_over, nested, requires_false, requires_none,
                requires_not_none, requires_true)

A node inside an ada_args template tree.

Nested args exist for conditions that must be evaluated per element of an iterated list, such as wrapping only alwayslink libraries:

ada_args(
    name = "libraries_to_link",
    actions = LINK_ACTIONS,
    iterate_over = "libraries_to_link",
    nested = [":whole_archive_library", ":plain_library"],
)

ada_nested_args(
    name = "whole_archive_library",
    args = ["-Wl,-force_load,{libraries_to_link.file}"],
    requires_true = "libraries_to_link.whole_archive",
)

ada_nested_args(
    name = "plain_library",
    args = ["{libraries_to_link.file}"],
    requires_false = "libraries_to_link.whole_archive",
)

ATTRIBUTES

ada_shared_library

Rules

• ada_shared_library

ada_shared_library

load("@rules_ada//ada:ada_shared_library.bzl", "ada_shared_library")

ada_shared_library(name, deps, srcs, data, compile_data, copts, exports_bodies, lib_name, linkopts,
                   subunits)

Compiles Ada source files into a shared (dynamic) library.

ATTRIBUTES

ada_static_library

Rules

• ada_static_library

ada_static_library

load("@rules_ada//ada:ada_static_library.bzl", "ada_static_library")

ada_static_library(name, deps, srcs, data, compile_data, copts, exports_bodies, lib_name, linkopts,
                   subunits)

Compiles Ada source files into a static archive (.a) for external consumption.

ATTRIBUTES

ada_test

Rules

• ada_test

ada_test

load("@rules_ada//ada:ada_test.bzl", "ada_test")

ada_test(name, deps, srcs, data, compile_data, copts, env, env_inherit, linkopts, linkstatic, main,
         subunits)

Compiles Ada source files, binds them, and links into a test executable. Run with bazel test.

ATTRIBUTES

ada_toolchain

Rules

• ada_toolchain

Providers

• AdaToolchainInfo

ada_toolchain

load("@rules_ada//ada:ada_toolchain.bzl", "ada_toolchain")

ada_toolchain(name, ada_std, ar, args, artifact_name_patterns, bind_flags, binder, compile_flags,
              compiler, compiler_id, compiler_lib, dynamic_runtime_lib, enabled_features, gcov,
              known_features, static_runtime_lib, target_triple)

Defines an Ada toolchain: the GNAT compiler (gcc), binder (gnatbind) and archiver (ar), the runtime libraries, and the arguments every action is built from.

The hermetic-gnat toolchains shipped with rules_ada are created and registered by its module extension; this rule is only needed to define a custom toolchain around a GNAT installation that rules_ada does not ship.

How the toolchain builds its command lines is declared with ada_args targets listed in args; rules_ada ships complete link lines per platform family under @rules_ada//ada/toolchains/args/... that can be reused, extended or replaced. The GNAT runtime archives are listed in static_runtime_lib, tasking runtime first:

load("@rules_ada//ada:ada_toolchain.bzl", "ada_toolchain")
load("@rules_ada//ada/toolchains:defs.bzl", "LINK_ACTIONS", "ada_args")

ada_args(
    name = "system_libs",
    actions = LINK_ACTIONS,
    args = ["-lm", "-lpthread", "-ldl", "-lrt"],
)

ada_toolchain(
    name = "gnat_toolchain",
    compiler = "@gnat//:bin/gcc",
    binder = "@gnat//:bin/gnatbind",
    ar = "@gnat//:bin/ar",
    ada_std = "@gnat//:ada_std",
    compiler_lib = "@gnat//:compiler_lib",
    gcov = "@gnat//:bin/gcov",
    compile_flags = ["-O2"],
    static_runtime_lib = [
        "@gnat//:lib/gcc/x86_64-pc-linux-gnu/16.1.0/adalib/libgnarl.a",
        "@gnat//:lib/gcc/x86_64-pc-linux-gnu/16.1.0/adalib/libgnat.a",
        "@gnat//:lib/gcc/x86_64-pc-linux-gnu/16.1.0/libgcc.a",
    ],
    args = [
        "@rules_ada//ada/toolchains/args/elf:link_line",
        ":system_libs",
    ],
    known_features = ["@rules_ada//ada/toolchains/features:static_libgcc"],
    target_triple = "x86_64-pc-linux-gnu",
)

See the toolchains documentation for the variables available to ada_args, the shipped link lines, features and dynamic_runtime_lib.

ATTRIBUTES

AdaToolchainInfo

load("@rules_ada//ada:ada_toolchain.bzl", "AdaToolchainInfo")

AdaToolchainInfo(ada_std, ar, args, args_files, artifact_name_patterns, bind_flags, binder,
                 compile_flags, compiler, compiler_id, compiler_lib, dynamic_runtime_lib,
                 enabled_features, gcov, known_features, label, process_wrapper, static_runtime_lib,
                 target_triple)

Information about a configured Ada toolchain.

FIELDS