Install Lumen¶
Installing Lumen gives you lumenc, the command you use to create, run, and
package apps, the Lumen runtime library it loads, the launcher a packaged app
is built from, the runtime modules an app can declare, the
candela standard library scripts import, and the app
templates lumenc new writes. You do not need a Rust toolchain
to build apps, or to package one for someone else.
Linux and macOS¶
The installer resolves the current release, downloads the archive for your
platform, and unpacks it under ~/.lumen. It prints what it is about to do and
asks before writing anything.
Every release publishes a sha256sums.txt covering its assets. The installer
downloads that file first and checks the archive against the line for it;
anything that does not match is not installed.
Builds are published for Linux and macOS on x86_64 and aarch64. The installer
needs curl or wget, and sha256sum or shasum.
Afterwards, lumenc lives in ~/.lumen/bin. If that directory is not on your
PATH, the installer offers to add a line to your shell's startup file, and
tells you the line to add if you decline. Open a new shell and check:
The install also carries a shell completion script for bash, zsh, and fish
under ~/.lumen/share, and prints the one line your shell needs to load it.
See shell completions.
Runtime modules¶
Some capabilities live outside the engine, in libraries the runtime loads at
startup: files, audio, canvas, downloads, processes, archives. An app asks for
one by name under [dependencies]
in lumen.toml, which lists the modules and their config keys;
scripting covers the calls each one adds.
The installer downloads them with the toolchain, from the module archive
published with the same release, and unpacks them into the same tree, so the
libraries sit in ~/.lumen/bin beside the engine, which is where the runtime
looks for them. --no-modules installs the toolchain without them.
LICENSE, NOTICE and THIRD-PARTY-LICENSES land at the root of the prefix,
carrying the license text of the toolchain and of everything it is built from.
lumenc package copies them into each app you package.
An app whose modules are missing prints one line per module,
lumen-runtime: MODULE LOAD FAILED: <name>, with the paths it probed under
it, then keeps running with every call into that module's namespace failing.
To put the modules in place, run the installer again with --force; a plain
rerun at the same version stops at "Already up to date" and changes nothing:
Installer options¶
| Option | Effect |
|---|---|
--prefix DIR |
Install root. Default ~/.lumen. |
--version VERSION |
Install a specific release and pin to it. |
--no-confirm |
Accept the defaults without prompting. |
--no-modify-path |
Never write to a shell startup file. |
--no-modules |
Skip the bundled runtime modules and install the toolchain alone. |
--no-lpm |
Skip lpm, the package-registry client. |
--force |
Reinstall even when already at the target version. |
--uninstall |
Remove every file the installer wrote. |
-h, --help |
Show the installer's own help. |
LUMEN_PREFIX sets the install root like --prefix.
To pass options through the pipe, hand them to sh:
The package registry client¶
lpm resolves the packages an app declares and downloads them. It goes to
~/.local/bin/lpm, outside the prefix, because one copy serves every
toolchain on the machine and lumenc looks for it there. You do not have to
put that directory on your PATH; add it if you want to run lpm yourself.
--no-lpm skips it, and lumenc installs it the first time an app names a
registry package.
Uninstall¶
The installer records every path it writes, so an uninstall removes exactly
those files and nothing else. A PATH line added to a shell startup file stays
behind; delete it by hand, and so does lpm, which sits outside the prefix.
Homebrew¶
The formula unpacks the same release archive the script installs, so lumenc,
the runtime library, the launcher, the candela standard library, and the app
templates all come with it. brew upgrade lumen moves you to a newer release.
A Homebrew install carries no runtime modules and no shell completions, and it never checks for updates on its own, because Homebrew owns when the version moves. Use the script installer if you want any of those.
Windows¶
Download and run the per-user installer for your machine:
https://github.com/lumen-fx/lumen/releases/latest/download/lumen-windows-x86_64.msi
https://github.com/lumen-fx/lumen/releases/latest/download/lumen-windows-aarch64.msi
It installs under your user profile, so it needs no administrator rights, and
it adds lumenc to your user PATH. Open a new terminal afterwards. Remove it
from Settings > Installed apps, which also removes the PATH entry.
Each release also publishes lumen-windows-x86_64.zip and
lumen-windows-aarch64.zip, portable archives you can unpack anywhere. A
portable copy never checks for updates; you replace it by unpacking a newer
zip.
A Windows install carries no runtime modules, so an app that declares
[dependencies] starts without
them and says so in one line on stderr.
lumenc package --static
compiles them into the executable instead.
Scoop¶
Scoop installs the portable zip rather than the MSI, so the two never end up
side by side. scoop update lumen moves versions and scoop uninstall lumen
removes it. Like the zip, it carries no runtime modules and
does not check for updates on its own.
Platforms with no build¶
Releases cover Linux, macOS, and Windows, each on x86_64 and aarch64. On anything else install from source:
This needs a Rust toolchain. It builds lumenc, then fetches the matching
Lumen source and builds the runtime library, the launcher, and the candela
standard library from it, putting all three beside the installed lumenc so
running and packaging an app work the same as they do from a release. Expect it
to take a while: it is compiling the engine.
A source install does not carry the app templates, because cargo keeps only the
binary it installed. lumenc new wants a release install, or a clone of the
template repository you were going to scaffold from.
It does not build the runtime modules either, so the
capabilities behind [dependencies]
need a release install.
Set LUMEN_SKIP_ENGINE_BUILD=1 to install only the compiler, if you are
building the rest yourself. lumenc run, build, and check work without the
runtime library and the launcher; lumenc package needs them, and it says so
and names the directory to put them in. A script that reaches for
import "std/..." or an array method needs the libs/ directory beside
lumenc, or CANDELA_LIB_PATH naming one elsewhere.
Nightly builds¶
A build of main goes up every night as a prerelease, on one tag:
Take one to try a fix or a feature before it is released. It carries the same archives a release does, and the notes on it name the commit it was built from.
Download the archive for your platform and unpack it yourself; on Windows take
lumen-windows-x86_64.zip. Nothing installs a nightly for you. install.sh,
the setup-lumen action, and lumenc's own update check all resolve the current
release, and a prerelease is not one, so a nightly never arrives on a machine
that did not ask for it and never offers to replace itself.
Three things to expect from a nightly:
- There is no Windows installer, only the portable zip. An installer would share product identity with a released install and take it over.
lumenc --versionreports the versionmaincarries, which no release is behind. It does not say which night you have; the commit in the notes does.lumenc webandlumenc package --targetdownload their extra files from the current release rather than from the nightly, because that is the only version they can resolve. A nightly compiler pairs them with a released browser runtime.
Every night's assets replace the last, so a link keeps working and the build before it is gone. Keep a copy if you need one to stay around.
Staying up to date¶
An installed lumenc looks for a newer release at most once a day and prints a
single line when it finds one:
In a terminal it then offers to update for you. On Linux and macOS that reruns
the installer. On Windows it downloads the new installer and runs it once the
current command exits, because Windows cannot replace a running lumenc.exe.
The check is deliberately quiet:
- Only the commands you type by hand are checked:
run,check,build,bundle,new,fmt, andi18n. Automation subcommands stay silent. - Only an installed copy checks. A copy built from source, or unpacked from the portable Windows zip, never reaches the network.
- Anything with
--headless, a non-terminal stderr, or aCIenvironment variable turns it off. LUMEN_NO_UPDATE_CHECKset to any non-empty value turns it off everywhere.
Pinning a version¶
Install with --version to hold a project on a known release:
A pinned install is never offered a newer release, and the files it downloads
later stay on the pinned version: lumenc package --target and lumenc web
fetch from the release the pin names. Run the installer again without
--version to lift the pin.
Releases from before sha256sums.txt was published cannot be installed this
way; the installer has nothing to verify them against and stops.
Continuous integration¶
A GitHub Actions workflow installs the toolchain with the setup-lumen action instead of the script above, which prompts and writes to a shell startup file:
steps:
- uses: actions/checkout@v4
- uses: lumen-fx/lumen/tools/setup-lumen@main
- run: lumenc check .
It runs on Linux, macOS, and Windows runners, downloads the release built for
the runner, checks it against the release's sha256sums.txt, and puts lumenc
on PATH. Pass version to hold a workflow on a release:
The unpacked toolchain is kept in the workflow cache, keyed on the release and the runner's platform, so later runs skip the download.
Two things behave differently in a workflow than on a workstation. The update
check never runs: a CI environment variable turns it off, and an unpacked
archive has no install receipt to check against in the first place. And
lumenc run loads the runtime library, which on Linux links GTK, ALSA, X11,
and Wayland; a job that runs an app installs those first, while check, new,
and fmt need none of them.
The action's own inputs and outputs are documented with it, in tools/setup-lumen.
Next¶
- Write your first app.
- Every
lumencsubcommand and flag. - Build Lumen from source if you want to work on the framework itself.