blob: ca1026e3e30a6cc9ad8acec5c9cc0079d2f38e8a [file] [log] [blame] [view]
David Brazdil5ecf75f2019-07-21 10:39:47 +02001# 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
12in nightly 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## Installing Docker
17
18### Stable
19
20If you don't mind running a Docker daemon with root privileges on your system,
21you can follow the [official guide](https://docs.docker.com/install/) to install
22Docker, or [go/installdocker](https://goto.google.com/installdocker) if you are
23a Googler.
24
25Because the daemon runs as root, files generated by the container are owned by
26root as well. To work around this, the build will automatically derive a local
27container image from the base container, adding user `hafnium` with the same
28UID/GID as the local user.
29
30### Nightly with rootless
31
32The latest nightly version of Docker has support for running containers with
33user namespaces, thus eliminating the need for a daemon with root privileges.
34It can be installed into the local user's `bin` directory with a script:
35``` shell
36curl -fsSL https://get.docker.com/rootless -o get-docker.sh
37sh get-docker.sh
38```
39
40The script will also walk you through the installation of dependencies,
41changes to system configuration files and environment variable values needed
42by the client to discover the rootless daemon.
43
44## Enabling for local builds
45
46Hermetic builds are controlled by the `HAFNIUM_HERMETIC_BUILD` environment
47variable. Setting it to `true` instructs the build to run commands inside the
48container. Any other value disables the feature.
49
50To always enable hermetic builds, put this line in your `~/.bashrc`:
51``` shell
52export HAFNIUM_HERMETIC_BUILD=true
53```
54
55When you now run `make`, you should see the following line:
56``` shell
57$ make
58Running in container: make all
59...
60```
61## Running commands inside the container
62
63An arbitrary command can be executed inside the container with
64`build/run_in_container.sh [-i] <command> ...`. This is done
65automatically inside `Makefile` and `kokoro/ubuntu/build.sh` which
66detect whether they are already running inside the container and respawn
67themselves using `run_in_container.sh` if not.
68
69For example, you can spawn a shell with:
70``` shell
71./build/run_in_container.sh -i bash
72```
73
74## Building container image
75
76The container image is defined in `build/docker/Dockerfile` and can be built
77locally:
78``` shell
79./build/docker/build.sh
80```
81
82Owners of the `hafnium-build` GCP repository can publish the new image
83(requires [go/cloud-sdk](https://goto.google.com/cloud-sdk) installed and
84authenticated):
85``` shell
86./build/docker/publish.sh
87```