Composition setup variants

You can create a setup.toml file in your composition. It allows you to specify build‑time options and variant parameters at runtime.

Note

setup.toml must be referenced in your flake.nix for this mechanism to work.

outputs = { self, nixpkgs, nxc }: {
  packages = forAllSystems (system:
    nxc.lib.compose {
      inherit nixpkgs system;
      setup = ./setup.toml;
      composition = ./composition.nix;
  })};

What you can do with this

You can create profiles for your compositions & configure them with various parameters that can be used within your composition;

Tip

You can initialize the setup composition template by running:

nxc init -t setup

Global options

[options]
nix-flags = "--impure"
composition-file = "testing.nix"
composition-flavour = "testing::vm"
flavour = "vm"
kernel-params = "intel_pstate=disable"

These values are used as defaults for the nxc build command. The arguments you specify when running the command always take precedence over this file.

Parameters

You can define arbitrary parameters under a params table. They are made available to your Nix expressions in composition via the setup object.

[params]
a = "hello"
b = 74

environment.variables.A = setup.params.a; # Evaluates to "hello"
environment.variables.B = builtins.toString (setup.params.b + 1); # Evaluates to "75"

Tip

You can temporarily override them when running the command by using the --setup-param flag (i.e. --setup-param "a=world")

You can repeat this argument to add some more.

Variants

A variant is a named section that can provide its own [options] and [params].

[dev]
[dev.params]
a = "dev‑value"
b = 74

[dev.options]
nix-flags = "--impure"
composition-file = "dev.nix"

Select a variant with --setup:

nxc build --setup dev

The selected variant in this example will then be stored in the file under:

[project]
selected = "dev"

Example

Given the following setup.toml:

[project]

[params]
a = "hello world"
b = 10

[options]
nix-flags = "--impure"

[dev.options]
nix-flags = "--impure -L debug"
composition-file = "dev.nix"

Running

nxc build --setup dev

will build using the dev variant options, while

nxc build --setup-param "a=override"

will override the a parameter with the value override.