Build flags

A build flag is a name, with an optional value, that elide.pkl reads when it is evaluated.

Pass flags

elide build run --args="Hello World 🌎" --flag=RELEASE --flag=VERSION=1.2.3
elide build run --args="Hello World 🌎" -fRELEASE -fVERSION=1.2.3

--flag NAME and -f NAME also work, in any position. Arguments after -- are never flags. --args belongs to the run task; see Build Tasks.

Every project-aware command takes flags:

elide run -fRELEASE -fVERSION=1.2.3 -- "Hello World 🌎"
elide install --flag=RELEASE
elide format -fNO_KOTLIN
elide build -fRELEASE
elide test -fFAST
elide project export -fRELEASE    # shows the evaluated result

A flag without a value (-fRELEASE) is bare: true to bool(...), an error to string(...).
The value is everything after the first =, verbatim: -fEXPR=a=b gives a=b.
A repeated flag keeps every value; scalar accessors read the last (Repeated flags).
Flags need no declaration; an unknown name is absent.
Names cannot be empty or contain , or =.

Read flags in elide.pkl

amends "elide:project.pkl"

local isRelease = build.flags.bool("RELEASE")

name = if (isRelease) "demo-release" else "demo-debug"
version = build.flags.stringOr("VERSION", "0.0.0")

Accessor	Returns
`has(name)`	Whether the flag was passed, with or without a value.
`count(name)`	Times passed; `0` when absent.
`string(name)`	The value; `null` when absent; throws when bare.
`stringOr(name, orElse)`	The value, or `orElse` when absent.
`bool(name)`	`false` absent, `true` bare; `true`/`false`, `yes`/`no`, `on`/`off`, `1`/`0` (any case); else throws.
`int(name)`	The value as `Int`; `null` when absent; throws if not an integer.
`strings(name)`	Every value in order; empty when absent; throws on a bare occurrence.
`stringsOr(name, orElse)`	Every value, or `orElse` when absent.
`ints(name)`	Every value as `Int`; empty when absent; throws if any is not an integer.
`bools(name)`	Every value as `Boolean`; empty when absent; bare reads `true`.
`raw`	`Mapping<String, String>` of effective values; bare maps to `""`.
`all`	`Mapping<String, List<String>>` of every value.

Use strings(...) to accept one or more values. Typed accessors fail on bad input:

–– Pkl Error ––
build flag `RELEASE` is not a boolean: `perhaps`

Environment variables

read("env:NAME") sees only PATH, HOME, USER, LANG, LC_*, TZ, CI, TERM, SHELL, OS, TMPDIR and ELIDE_*; any other variable reads as absent. Use a build flag, or allow more:

elide build --allow-env=GITHUB_SHA,JAVA_HOME
elide build --allow-env            # every variable

Repeated flags

elide build -fARG=one -fARG=two -fARG='three, and a half'

local args = build.flags.strings("ARG")  // List("one", "two", "three, and a half")
local first = build.flags.all["ARG"].first
local latest = build.flags.string("ARG") // "three, and a half" — scalars read the last value

Values keep commas, spaces, = and Unicode. List accessors check every element:

–– Pkl Error ––
build flag `N` is not an integer: `x1`

Flags inside nested blocks

Inside a nested object body, bare build does not resolve. Bind a module-level local, or use module.build.flags:

local wantsExtra = build.flags.bool("EXTRA")

dependencies {
  maven {
    packages {
      "com.google.guava:guava:33.0.0-jre"
      when (wantsExtra) {
        "com.example:extra:1.0.0"
      }
      when (module.build.flags.bool("MORE")) {
        "com.example:more:1.0.0"
      }
    }
  }
}