Build tasks

elide build derives tasks from the source sets and artifacts in elide.pkl and runs them in dependency order. Tasks with unchanged inputs are skipped or restored from the cache.

Run a build

elide build                   # run the default group
elide build compile-java-main # run one task
elide build compile           # run a group
elide build clean             # the clean target
elide build --inspect         # list tasks and their options without running
elide build jvm-test --help   # one task's options and what they mean
elide build --no-cache        # ignore cached results and build state
elide build --offline         # no network: no dependency fetches, no shared cache
elide build --workers=4       # run at most four tasks at once

An argument names a task or group; a leading colon (:compile-java-main) is optional. A target that matches nothing fails the build.

Some tasks take options, listed by --inspect:

elide build test --select=class:com.example.SomeTest
elide build run --args="a b c"

In a workspace, prefix the project: core:compile-kotlin-main, core:compile, or core for its default tasks. Unprefixed targets resolve in the current project, then the root. --inspect groups tasks by project, and progress rows name it ([core] Compiling Kotlin sources).

A project can add groups — and tasks — of its own, including tasks that run ahead of the built-in ones: see Build extensions.

Options

Options are --name or --name=value, anywhere among the targets. Arguments after -- go to the process a task launches. --inspect lists every task’s options; elide build <task> --help describes one task’s own.

Options are checked against the tasks before anything runs. An unknown option, a missing or unexpected value, or a repeated option fails:

Unknown option '--worker', did you mean '--workers'?
Option '--workers' requires a value, as '--workers=<value>'

Global flags (-p, -v, --debug and the rest) are exempt. Task options: Dependencies, Testing.

Build cache

The local tier is always on: ~/.elide/cache/entries-v2, one directory per key with a record and a tar of the outputs. Restores are checked against the recorded fingerprint. Entries in an older format miss.

The shared tier is an HTTP cache, set up by environment variables:

• Local is checked first; remote hits are stored locally.
• Typical setup: CI pushes; developers set ELIDE_REMOTE_CACHE_PUSH=false.
• Unreachable, slow or unreadable remote entries are misses. Three transport failures in a row turn the tier off for the rest of the build. HTTP errors such as 404 are not transport failures; a rejected credential warns once.
• The build fails on a non-http/https URL, a password without a username, a non-boolean PUSH/PULL, or credentials over plain http to a non-loopback host.
• The cache serves executable outputs: use https, require authentication for writes, and limit who can write.
• --offline turns off the shared tier for one run; --no-cache turns off caching.

.eliderc and the smart policy

Under smart, an entry is downloaded only when that is cheaper than rebuilding, and uploaded only when the upload costs less than the work it saves. Costs come from .eliderc (java.util.Properties syntax): ~/.eliderc, then <project>/.eliderc over it. It describes the machine, so do not commit it.

# ~/.eliderc
network.downlink = 200mbps
network.uplink = 20mbps
network.latency = 250ms
network.stability = good        # good | fair | poor
machine.compute = fast          # slow | normal | fast, or a multiplier such as 1.5

cache.remote.policy = smart     # smart | eager (default)
cache.remote.upload-budget = 2.0
cache.remote.min-build = 500ms  # work cheaper than this is never published

Mb/s and mbps are megabits; MB/s is megabytes. Unreadable values warn and use the default. ELIDE_REMOTE_CACHE_POLICY overrides cache.remote.policy. Under eager, the file has no effect.

Build state

• Binary files; do not edit.
• There is no dependency lockfile for every ecosystem; npm writes aube-lock.yaml.
• In a workspace, state is stored in the root’s .dev/ for every member; outputs stay in each project’s .dev/.
• --no-cache ignores the local state file but still reads the shared one.
• elide install reuses resolution while the dependency list is unchanged; --fresh downloads every dependency again, refreshing the global cache.
• Each compiler’s arguments are written beside its output as <tool>.args, one per line.

See The .dev directory for generated files, workspace paths and cleanup.

Time a build

Each task prints its duration. For more:

elide build -v                                                # everything, at debug
ELIDE_LOG=dev.elide.tooling.build.telemetry=debug elide build # only the timings

[debug] dev.elide.tooling.build.telemetry stage graph took 590us
[debug] dev.elide.tooling.build.telemetry op compile-kotlin-main · up-to-date (up-to-date) took 420us
[debug] dev.elide.tooling.build.telemetry task compile-kotlin-main (skipped: up-to-date) took 12.6ms

Regions are a stage (configuration, graph, execution, state save), a task, or an operation on a task (prepare, fingerprint, up-to-date, execute, cache lookups and stores). Work inside execute is not split out.

ELIDE_BUILD_TELEMETRY writes a local Chrome trace when the build ends; nothing is uploaded:

ELIDE_BUILD_TELEMETRY=1 elide build             # .dev/telemetry/build-<stamp>.trace.json
ELIDE_BUILD_TELEMETRY=profile.json elide build  # a file you name
ELIDE_BUILD_TELEMETRY=/tmp/traces elide build   # a directory you name

Open it in Perfetto, chrome://tracing or speedscope, or:

jq -r '.traceEvents[] | select(.ph=="X") | "\(.dur/1000 | floor)ms \(.cat) \(.name)"' \
  .dev/telemetry/build-*.trace.json | sort -rn | head

Restore observations and session correlation

Servers supporting Elide restore receipts may return x-elide-recall-receipt when an archive download requests x-elide-recall: 1. The client reports the outcome to outcomes beneath the configured cache endpoint after extraction and validation. Downloading bytes alone does not count as a successful restore; subsequent local hits do not duplicate remote observations. Reporting is best effort and does not decide whether a build succeeds.

ELIDE_STUDIO_SESSION_ID supplies bounded request correlation metadata to the configured build-cache endpoint and the HTTPS Maven Pkgst origin. It is not a credential and does not change action keys. Authenticated or session-correlated build-cache requests do not follow redirects, preventing metadata leakage to another origin.

Restore reports include the original task duration as a bounded estimate, so a server can compare likely rebuild cost with measured restore cost. That estimate is not a billing measurement or proof of time saved.