maintainers/scripts/bootstrap-files/README.md

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