Robotnix provides a number of Nix outputs that can be built with a given configuration.
The specific output is selected using the
-A option of
For example, the following will build an
img zip associated with the configuration in
$ nix-build --arg configuration ./config.nix -A img
Some of the outputs provided by robotnix are the following:
img- Image zip, which can be flashed to a device using
factoryImg- Factory image, a zip which contains the contents of
imgas well as a radio / bootloader if available.
ota- Over-the-air zip, which can be flashed to a device in recovery mode using
releaseScript- Script which produces the
factoryImgproducts outside of Nix.
generateKeysScript- Script to generate required device / application keys for a given configuration.
After creating a configuration file, you need to generate keys for your device (if you are using signed builds, with
signing.enable = true;):
$ nix-build --arg configuration ./crosshatch.nix -A generateKeysScript -o generate-keys $ ./generate-keys ./keys
This will create a
keys directory containing the app and device keys needed for the build.
The output of this script should be placed in the location specified by
signing.keyStorePath in the robotnix configuration.
If you intend to build the
ota Nix outputs instead of using the
releaseScript, do not apply a passphrase to your keys here.
(You can still encrypt them at rest on your own through other means.)
This is because we cannot prompt you for your passphrase during the Nix build, but we can outside of Nix using
Sometimes changing your configuration will require that you generate additional new keys (e.g. for additional applications). Rebuilding and rerunning the generate keys script will produce the new keys (without overwriting your existing keys).
Next, build and sign your release. There are two ways to do this. The first option is to build the final products entirely inside Nix.
$ nix-build ./default.nix --arg configuration ./crosshatch.nix -A img --option extra-sandbox-paths /keys=$(pwd)/keys
If the Nix sandbox is enabled (it normally is), this will require a sandbox exception so the secret keys are available to the build scripts.
extra-sandbox-paths, the user must be a
If the Nix sandbox is not enabled, we can instead set
signing.buildTimeKeysStorePath in addition to
signing.keyStorePath to a string of the absolute path to the generated keys.
Additionally, the nix builder will also need read access to these keys.
This can be set using
chgrp -R nixbld ./keys and
chmod -R g+r ./keys.
The second option involves building a "release script" with Nix, which depends on and therefore builds the unsigned image inside the Nix build sandbox. The final build steps of signing target files and creating
ota files are then done outside the sandbox by running the release script:
$ nix-build --arg configuration ./crosshatch.nix -A releaseScript -o release $ ./release ./keys
This has the additional benefit that the build can take place on a remote machine, and the
releaseScript could be copied using
nix-copy-closure to a local machine which containing the keys.
You might need to manually set certain required options like
apps.prebuilt.<name>.fingerprint if you build on a remote machine that does not have access to the
Robotnix now has an optional binary cache provided by Cachix on robotnix.cachix.org.
Using the robotnix binary cache will allow the user to avoid building some parts that can be shared between users.
Currently, only the device kernels and browser builds are published through the binary cache.
This is because these derivation outputs are most likely to be shared between users, and those outputs also can take a very long time to build.
The build products previously discussed should be uploaded for at least every robotnix release tag.
To use, install
cachix use robotnix, and then build robotnix like normal.
If the robotnix configuration is specified in a flake, the robotnix outputs can be produced by running (for example):
$ nix build .#robotnixConfigurations.dailydriver.img
This is assuming the
flake.nix is in the current directory, the desired configuration is named
dailydriver, and will produce the
Other robotnix outputs are available using a similar command.