1# Container build for Floss
2
3This repo contains the Container-image build rule, used to generate the
4(docker/podman) container image necessary to build Floss. If building a new
5docker/podman image, run `container-build-image.py` with the tag `floss:latest`.
6
7## Container binary: setting up podman (default)
8
9On most Debian based machines, you should be able to simply use `apt-get` and
10install these requisite packages.
11```
12sudo apt-get install \
13  podman \
14  uidmap
15```
16
17Then, we need to set up podman for [rootless
18mode](https://docs.podman.io/en/latest/markdown/podman.1.html#rootless-mode):
19```
20sudo usermod --add-subuids 10000-75535 USERNAME
21sudo usermod --add-subgids 10000-75535 USERNAME
22```
23
24## Container binary: setting up docker (alternative)
25
26Follow the installation instructions at:
27https://docs.docker.com/engine/install/, such as
28https://docs.docker.com/engine/install/debian/.
29
30Also consider configuring Docker to run in rootless mode:
31https://docs.docker.com/engine/security/rootless/
32
33## Generating the floss-build image
34
35Run the following to generate the required image:
36```
37container-build-image.py --tag floss:latest
38```
39
40If you use the `docker` binary, add the flag: `--use-docker` when running
41`container-build-image.py`.
42
43This uses the default tag of `floss:latest` so you don't have to provide it
44specifically when invoking `build-in-container.py`.
45
46Run the following command to check if the image has been installed
47```
48$ podman images
49REPOSITORY                TAG         IMAGE ID      CREATED         SIZE
50localhost/floss           latest      6e66bc573bd7  8 minutes ago   3.27 GB
51localhost/floss           buildtemp   8cd97b8cb7bb  10 minutes ago  3.25 GB
52```
53
54## Using the container image to build
55
56Once the container image is built (and assuming it's tagged as `floss:latest`), you
57should use the `build-in-container.py` script to build the current repo.
58
59Basic build:
60```
61build-in-container.py
62```
63
64This script will use the local `floss:latest` (or pull it from the registry),
65mount (or create) the `floss-out` volume to `/root/.floss` and the current
66source to `/root/src` before running these commands in the container:
67
68* `cd /root/src`
69* `./build.py --run-bootstrap`
70* `./build.py --libdir=/usr/lib/x86-64_linux_gnu/`
71
72If you want to run the build more quickly (or pass other commands), run
73`build-in-container.py --only-start`. This will only start the container for you
74(doing the correct mounts) and will print the commands it would have run via
75`<container_binary> exec` normally.
76For example, you might want to run all unit tests after making a change:
77```
78./build-in-container.py --only-start
79podman exec -it floss-container-runner /root/src/build.py --target test
80```
81
82Important: after syncing the repository, perform a clean build using
83`build-in-container.py` to prevent unexpected build failures
84