2020-04-26 12:40:06 +00:00
# Description
2020-06-05 09:23:22 +00:00
This document describes the layout of our Nix setup.
2020-04-26 12:40:06 +00:00
# Folders
There are four main folders in the `nix` directory:
2020-06-05 09:23:22 +00:00
* [`nix/scripts` ](./scripts ) - Bash scripts for easier usage of Nix
* [`nix/pkgs` ](./pkgs ) - Packages we add to or modify in `nixpkgs`
* [`nix/deps` ](./deps ) - Project dependencies managed by Nix
* [`nix/lib` ](./lib ) - Our tools we merge into `pkgs.lib`
* [`nix/tools` ](./tools ) - Various tools used by our derivations and shells
* [`nix/status-go` ](./status-go ) - Derivations for building [`status-go` ](https://github.com/status-im/status-go ) repo
2020-04-26 12:40:06 +00:00
# Files
There are a few main files that define the whole build environment:
2020-06-05 09:23:22 +00:00
* [`nix/nix.conf` ](./nix.conf ) - Binary cache configuration
* [`nix/default.nix` ](./default.nix ) - Entry point for both shells and targets
* [`nix/shell.nix` ](./shell.nix ) - Definition of the default Nix shell
* [`nix/shells.nix` ](./shells.nix ) - Definitions of other Nix shells used in builds
* [`nix/targets.nix` ](./targets.nix ) - Hierarchy of main build targets
* [`nix/pkgs.nix` ](./pkgs.nix ) - Definition of a custom `nixpkgs` repo
* [`nix/overlay.nix` ](./overlay.nix ) - Overrides for `nixpkgs` , custom packages
2020-04-26 12:40:06 +00:00
2020-06-05 09:23:22 +00:00
The [`default.nix` ](../default.nix ) and [`shell.nix` ](../shell.nix ) files at th repo root are just a gateway into the `nix` sub folder.
# Scripts
There's a few scripts in [`nix/scripts` ](./scripts ) that make use of Nix simpler:
* [`nix/scripts/setup.sh` ](./scripts/setup.sh ) - Installs Nix Package manager
* [`nix/scripts/source.sh` ](./scripts/source.sh ) - Sources the Nix profile or installs Nix
* [`nix/scripts/build.sh` ](./scripts/build.sh ) - A wrapper around `nix-build` with sane defaults
* [`nix/scripts/shell.sh` ](./scripts/shell.sh ) - A wrapper around `nix-shell` for `Makefile`
* [`nix/scripts/clean.sh` ](./scripts/clean.sh ) - For cleaning Nix store after builds
* [`nix/scripts/purge.sh` ](./scripts/purge.sh ) - For purging everything Nix related from system
2020-04-23 18:19:12 +00:00
2020-04-26 12:40:06 +00:00
# Start
The starting point for using our Nix shells and targets is the [`default.nix` ](/default.nix ) file.
It pulls in all the `pkgs` , `targets` and `shells` defined in [`nix/default.nix` ](/nix/default.nix ). The point is easy access to them via commands like `nix-build` or `nix-shell` , which you'll see next.
2020-06-05 09:23:22 +00:00
# Shells
2021-11-05 12:59:33 +00:00
Normally shells are started using `make shell TARGET=default` , but that is essentially the same as calling:
2020-06-05 09:23:22 +00:00
```bash
2021-11-05 12:59:33 +00:00
nix-shell -A shells.default default.nix
2020-06-05 09:23:22 +00:00
```
The [`nix/scripts/shell.sh` ](./scripts/shell.sh ) script is essentially a wrapper around that command to make it usable as shell for the `Makefile` .
# Building
2020-04-26 12:40:06 +00:00
2023-05-16 16:42:56 +00:00
We will use the `make jsbundle` target as an example of a derivation you can build using Nix:
2020-04-26 12:40:06 +00:00
2023-05-16 16:42:56 +00:00
1. `make jsbundle` is called by developer
2. `make` calls `nix/scripts/build.sh targets.mobile.jsbundle`
3. [`build.sh` ](/nix/scripts/build.sh ) calls `nix-build --attr targets.mobile.jsbundle` with extra arguments
4. `nix-build` builds the derivation from [`nix/mobile/jsbundle/default.nix` ](/nix/mobile/jsbundle/default.nix )
2020-04-26 12:40:06 +00:00
2024-02-15 08:18:11 +00:00
The same can be done for other targets like `targets.mobile.android.build` .
2020-04-26 12:40:06 +00:00
Except in that case extra arguments are required which is why the [`scripts/release-android.sh` ](/scripts/release-android.sh ) is used in the `make release-android` target.
If you run `make release-android` you'll see the `nix-build` command used:
```
nix-build \
--pure \
--fallback \
--no-out-link \
--show-trace \
2024-02-15 08:18:11 +00:00
--attr targets.mobile.android.build \
2022-07-17 12:37:46 +00:00
--argstr secrets-file '/tmp/tmp-status-mobile-559a3a441/tmp.xAnrPuNtAP' \
--option extra-sandbox-paths '/home/joe/.gradle/status-im.keystore /tmp/tmp-status-mobile-559a3a441/tmp.xAnrPuNtAP' \
2020-04-26 12:40:06 +00:00
default.nix
```
Some of those are required which is why just calling:
```
2024-02-15 08:18:11 +00:00
nix-build --attr targets.mobile.android.build
2020-04-26 12:40:06 +00:00
```
Would fail.
2020-06-19 13:43:58 +00:00
# Garbage Collection
2024-02-07 10:44:43 +00:00
The `make nix-gc` target calls `nix-store --gc` and normally would remove almost everything, but to prevent that we place symlinks to protected derivations in `.nix-gcroots` folder. Specifically:
2020-06-19 13:43:58 +00:00
```sh
2024-02-07 10:44:43 +00:00
_NIX_GCROOTS="${_NIX_GCROOTS:-${GIT_ROOT}/.nix-gcroots}
2020-06-19 13:43:58 +00:00
```
2024-02-07 10:44:43 +00:00
These symlinks in turn will be symlinked from `/nix/var/nix/gcroots/auto` through use of `nix-store --add-gcroots` .
2020-06-19 13:43:58 +00:00
Whenever `nix/scripts/build.sh` or `nix/scripts/shell.sh` are called they update symlinks named after given targets in that folder. This in combination with `keep-outputs = true` set in `nix/nix.conf` prevents garbage collection from removing too much.
