pyrox.dev
1# Bootstrap files
2
3Currently `nixpkgs` builds most of it's packages using bootstrap seed binaries (without the reliance on external inputs):
4
5- `bootstrap-tools`: an archive with the compiler toolchain and other helper tools enough to build the rest of the `nixpkgs`.
6- initial binaries needed to unpack `bootstrap-tools.*`.
7 On `linux` it's just `busybox`, on `darwin` and `freebsd` it is unpack.nar.xz which contains the binaries and script needed to unpack the tools.
8 These binaries can be executed directly from the store.
9
10These are called "bootstrap files".
11
12Bootstrap files should always be fetched from hydra and uploaded to `tarballs.nixos.org` to guarantee that all the binaries were built from the code committed into `nixpkgs` repository.
13
14The uploads to `tarballs.nixos.org` are done by `@lovesegfault` today.
15
16This document describes the procedure of updating bootstrap files in `nixpkgs`.
17
18## How to request the bootstrap seed update
19
20To get the tarballs updated let's use an example `i686-unknown-linux-gnu` target:
21
221. Create a local update:
23
24 ```
25 $ maintainers/scripts/bootstrap-files/refresh-tarballs.bash --commit --targets=i686-unknown-linux-gnu
26 ```
27
282. Test the update locally. I'll build local `hello` derivation with the result:
29
30 ```
31 $ nix-build -A hello --argstr system i686-linux
32 ```
33
34 To validate cross-targets `binfmt` `NixOS` helper can be useful.
35 For `riscv64-unknown-linux-gnu` the `/etc/nixos/configuration.nix` entry would be `boot.binfmt.emulatedSystems = [ "riscv64-linux" ]`.
36
373. Propose the commit as a PR to update bootstrap tarballs, tag people who can help you test the updated architecture and once reviewed tag `@lovesegfault` to upload the tarballs.
38
39## How to add bootstrap files for a new target
40
41The procedure to add a new target is very similar to the update procedure.
42The only difference is that you need to set up a new job to build the `bootstrapFiles`.
43To do that you will need the following:
44
451. Add your new target to `lib/systems/examples.nix`
46
47 This will populate `pkgsCross.$target` attribute set.
48 If you are dealing with `bootstrapFiles` upload you probably already have it.
49
502. Add your new target to `pkgs/stdenv/linux/make-bootstrap-tools-cross.nix`.
51 This will add a new hydra job to `nixpkgs:cross-trunk` jobset.
52
533. Wait for a hydra to build your bootstrap tarballs.
54
554. Add your new target to `maintainers/scripts/bootstrap-files/refresh-tarballs.bash` around `CROSS_TARGETS=()`.
56
575. Add your new target to `pkgs/stdenv/linux/default.nix` and follow standard bootstrap seed update procedure above.
58
59## Bootstrap files job definitions
60
61There are two types of bootstrap files:
62
63- natively built `stdenvBootstrapTools.build` hydra jobs in [`nixpkgs:trunk`](https://hydra.nixos.org/jobset/nixpkgs/trunk#tabs-jobs) jobset.
64 Incomplete list of examples is:
65
66 * `aarch64-unknown-linux-musl.nix`
67 * `i686-unknown-linux-gnu.nix`
68
69 These are Tier 1 hydra platforms.
70
71- cross-built by `bootstrapTools.build` hydra jobs in [`nixpkgs:cross-trunk`](https://hydra.nixos.org/jobset/nixpkgs/cross-trunk#tabs-jobs) jobset.
72 Incomplete list of examples is:
73
74 * `mips64el-unknown-linux-gnuabi64.nix`
75 * `mips64el-unknown-linux-gnuabin32.nix`
76 * `mipsel-unknown-linux-gnu.nix`
77 * `powerpc64le-unknown-linux-gnu.nix`
78 * `riscv64-unknown-linux-gnu.nix`
79
80 These are usually Tier 2 and lower targets.
81
82The `.build` job contains `/on-server/` subdirectory with binaries to be uploaded to `tarballs.nixos.org`.
83The files are uploaded to `tarballs.nixos.org` by writers to `S3` store.