flox build

NAME

flox-build - Build packages with Flox

SYNOPSIS

flox [<general-options>] build
     [-d=<path>]
     [--stability <stability>]
     [<package>]...

DESCRIPTION

Build the specified <package> from the environment in <path>, and the output at result-<package> adjacent to the environment.

Manifest-defined packages

Possible values for <package> are all keys under the build attribute in the manifest.toml. If no <package> is specified, Flox will attempt to build all packages that are defined in the manifest.toml.

Packages are built by running the script defined in build.<package>.command within a bash subshell. The shell will behave as if flox activate was run immediately prior to running the build script.

Pure and impure builds

Builds can be performed in a sandbox for the sake of reproducibility. By default this sandbox is turned off and the build is run in the root of the repository. This allows you to perform incremental builds using existing caches and intermediate build artifacts. We call this an "impure" build. With the sandbox disabled, building is similar to running the build script manually within a shell created by flox activate.

Pure builds are run in a temporary directory with the sandbox enabled. The sandbox can be enabled by setting build.<package>.sandbox = "pure". Only files tracked by git are copied into the temporary build directory. This ensures that the build doesn't accidentally depend on untracked files.

For this kind of "sandboxed" build, access to untracked files and files outside of the repository are restricted to provide a reproducible build environment. Sandboxed builds on Linux additionally are restricted from accessing the network, but the sandboxing mechanisms on macOS are somewhat limited and thus pure builds on macOS will be able to access the network.

Referring to other builds

Any build can access the results of other builds (including non-sandboxed ones) by referring to their name via ${<package>}. This allows multi-stage builds. In the example below, the app package depends on the dep package by using ${deps}/node_modules.

Build outputs

flox build creates a temporary directory for the build script to output built packages to. The environment variable out is set to this directory, and the build script is expected to copy or move packages to $out.

Upon completion of the build, the build result will be symlinked to result-<package> adjacent to the .flox directory that defines the package.

Metadata

Specifying the build.<package>.description and build.<package>.version fields of the build provide extra metadata that can be used by flox install, flox search, and flox show commands if the build is later published.

The build.<package>.version field can be specified in one of the following ways:

as a string: version = "0.0.1"
as read from a file: version.file = "<path>"
as returned by a command: version.command = "<cmd> <args>"

Catalog imports for Nix expression builds

Nix expression builds (packages defined as .nix files under .flox/pkgs/) can depend on packages from external catalogs. Declare catalog sources in nix-builds.toml(5), then run flox build update-catalogs to resolve and lock them. The resulting lockfile pins every catalog to a specific revision, ensuring reproducible builds.

See flox-build-update-catalogs(1) and nix-builds.toml(5) for details.

OPTIONS

<package> The package(s) to build. Possible values are all keys under the build attribute in the environment's manifest.toml.

--stability <stability> Perform a nix expression build using a base package set of the given stability as tracked by the catalog server. A stability (e.g., "stable") identifies a curated nixpkgs revision managed by the catalog server. When omitted, the base package set is derived from the environment's toplevel group; if no toplevel group exists, the "stable" stability is used by default. An explicit --stability value overrides both of these defaults. Cannot be used with manifest builds.

Environment Options

If no environment is specified for an environment command, the environment in the current directory or the active environment that was last activated is used.

-d, --dir Path containing a .flox/ directory.

General Options

-h, --help Prints help information.

The following options can be passed when running any flox subcommand but must be specified before the subcommand.

-v, --verbose Increase logging verbosity. Invoke multiple times for increasing detail.

-q, --quiet Silence logs except for errors.

EXAMPLES

Building a simple pure package

Add build instructions to the manifest:

# file: .flox/env/manifest.toml

...
[build]
hello.command = '''
# produce something and move it to $out
mkdir -p $out
echo "hello world" >> $out/hello.txt
'''
description = "Produces a file containing 'hello world'"
version = "0.0.0"

Build the package and verify its contents:

$ flox build hello
$ ls ./result-hello
hello.txt
$ cat ./result-hello/hello.txt
hello world

Building a simple multi-stage app

Assume a simple nodejs project

.
├── .git/
├── package-lock.json
├── package.json
├── public/
├── README.md
├── src/
...

Initialize a Flox environment

flox init

Install dependencies and add build instructions

# file: .flox/env/manifest.toml
version = 1

[install]
nodejs.pkg-path = "nodejs"
rsync.pkg-path = "rsync"

# install node dependencies using npm
# disable the sandbox to allow access to the network
[build]
deps.command = '''
npm ci
mkdir -p $out
mv node_modules $out/node_modules
'''
deps.sandbox = "off"

# build the application using previously fetched dependencies
app.command = '''
rsync -lr ${deps}/node_modules ./
npm run build
mv dist $out/
'''

Verify the result

npx serve result-app