Use external AXL modules

MODULE.aspect at your repo root declares external AXL module dependencies, the way MODULE.bazel declares Bazel dependencies. Once declared, a module is loadable from any .axl file in the repo.

Declaring a dependency

Use axl_archive_dep to pull in a module from an archive URL:

MODULE.aspect

axl_archive_dep(
    name = "aspect_rules_lint",
    urls = ["https://github.com/aspect-build/rules_lint/archive/65525d871f677071877d3ea1ec096499ff7dd147.tar.gz"],
    integrity = "sha512-TGcxutWr8FwxrK3G+uthbEpuYM2oOVpHPOvaVPzLLuHkfPY0jn/GWFp9myQeFzDFsRZ4ilT0jAWfGZhTk/nesQ==",
    strip_prefix = "rules_lint-65525d871f677071877d3ea1ec096499ff7dd147",
    auto_use_tasks = True,
    dev = True,
)

aspect axl add writes this entry for you from a GitHub release, integrity included. Parameters:

Parameter	Description
`name`	The module name used in `load()` statements as `@name`
`urls`	List of archive URLs. Only `.tar.gz` archives are supported
`integrity`	SHA-512 checksum in subresource integrity format for reproducibility
`strip_prefix`	Directory prefix to strip from the archive (usually `repo-commitsha`)
`auto_use_tasks`	If `True`, every task the module exports is registered as a CLI command, with no `load()` needed in your `.axl` files. Defaults to `False`
`dev`	Required, and must be `True`: modules can’t declare dependencies of their own yet

To use a module from a directory on disk, such as a checkout you’re developing, use axl_local_dep. A relative path resolves against the directory holding MODULE.aspect:

MODULE.aspect

axl_local_dep(
    name = "my_tasks",
    path = "../my-tasks",
    auto_use_tasks = True,
)

Loading from a module

After declaring a dependency, use load() to import specific symbols. This example loads a shared list of lint aspects from the my_tasks module declared above and sets it as the lint task’s default:

.aspect/config.axl

load("@my_tasks//lint_aspects.axl", "LINT_ASPECTS")

def config(ctx: ConfigContext):
    ctx.tasks["lint"].args.aspects = LINT_ASPECTS

load() path forms:

"@module_name//path/to/file.axl": a file inside a declared external module
"@aspect//traits.axl": the built-in Aspect library (always available, no declaration needed)
"./relative.axl": relative to the current file
"path/from/repo/root.axl": absolute from the workspace root (no leading ./)

Exporting tasks and features from a module

A module’s own MODULE.aspect names what it exports, with paths relative to the module root. auto_use_tasks = True in the consuming repo registers the exported tasks.

MODULE.aspect (in the module)

use_task("lint.axl", "lint")
use_task("bazelrc.axl", "bazelrc", "ci_bazelrc")   # several tasks from one file
use_feature("feature/artifacts.axl", "ArtifactUpload")

Built-in `@aspect` library

The @aspect module is always available without a MODULE.aspect declaration. It exports the built-in traits, features and utilities used throughout the config examples in these docs:

load("@aspect//traits.axl", "BazelTrait")
load("@aspect//feature/artifacts.axl", "ArtifactUpload")
load("@aspect//format.axl", "format")

Every feature it registers, with its options and defaults, is in the built-in features reference.

​Declaring a dependency

​Loading from a module

​Exporting tasks and features from a module

​Built-in @aspect library

Declaring a dependency

Loading from a module

Exporting tasks and features from a module

Built-in `@aspect` library