1# Hermetic build
2
3Hafnium build is not hermetic as it uses some system tools and libraries, e.g.
4`bison` and `libssl`. To ensure consistency and repeatability, the team
5maintains and periodically publishes a container image as the reference build
6environment. The image is hosted on Google Cloud Platform as
7`eu.gcr.io/hafnium-build/hafnium_ci`.
8
9Building inside a container is always enabled only for Kokoro pre-submit tests
10but can be enabled for local builds too. It is disabled by default as it
11requires the use of Docker which currently supports rootless containers only in
12nightly builds. As rootless container tools mature, Hafnium may change the
13default settings. For now, running the hermetic build locally is intended
14primarily to reproduce issues in pre-submit tests.
15
16[TOC]
17
18## Installing Docker
19
20### Stable
21
22If you don't mind running a Docker daemon with root privileges on your system,
23you can follow the [official guide](https://docs.docker.com/install/) to install
24Docker, or [go/installdocker](https://goto.google.com/installdocker) if you are
25a Googler.
26
27Because the daemon runs as root, files generated by the container are owned by
28root as well. To work around this, the build will automatically derive a local
29container image from the base container, adding user `hafnium` with the same
30UID/GID as the local user.
31
32### Nightly with rootless
33
34The latest nightly version of Docker has support for running containers with
35user namespaces, thus eliminating the need for a daemon with root privileges. It
36can be installed into the local user's `bin` directory with a script:
37
38```shell
39curl -fsSL https://get.docker.com/rootless -o get-docker.sh
40sh get-docker.sh
41```
42
43The script will also walk you through the installation of dependencies, changes
44to system configuration files and environment variable values needed by the
45client to discover the rootless daemon.
46
47## Enabling for local builds
48
49Hermetic builds are controlled by the `HAFNIUM_HERMETIC_BUILD` environment
50variable. Setting it to `true` instructs the build to run commands inside the
51container. Any other value disables the feature.
52
53To always enable hermetic builds, put this line in your `~/.bashrc`:
54
55```shell
56export HAFNIUM_HERMETIC_BUILD=true
57```
58
59When you now run `make`, you should see the following line:
60
61```shell
62$ make
63Running in container: make all
64...
65```
66
67## Running commands inside the container
68
69An arbitrary command can be executed inside the container with
70`build/run_in_container.sh [-i] <command> ...`. This is done automatically
71inside `Makefile` and `kokoro/build.sh` which detect whether they are already
72running inside the container and respawn themselves using `run_in_container.sh`
73if not.
74
75For example, you can spawn a shell with:
76
77```shell
78./build/run_in_container.sh -i bash
79```
80
81## Building container image
82
83The container image is defined in `build/docker/Dockerfile` and can be built
84locally:
85
86```shell
87./build/docker/build.sh
88```
89
90Owners of the `hafnium-build` GCP repository can publish the new image (requires
91[go/cloud-sdk](https://goto.google.com/cloud-sdk) installed and authenticated):
92
93```shell
94./build/docker/publish.sh
95```
96