1# Linux sysroot images
2
3The chromium build system for Linux will (by default) use a sysroot image
4rather than building against the libraries installed on the host system.
5This serves several purposes.  Firstly, it ensures that binaries will run on all
6supported linux systems independent of the packages installed on the build
7machine.  Secondly, it makes the build more hermetic, preventing issues that
8arise for variations among developers' systems.
9
10The sysroot consists of a minimal installation of Debian/stable (or old-stable)
11to ensure maximum compatibility.  Pre-built sysroot images are stored in
12Google Cloud Storage and downloaded during `gclient runhooks`
13
14## Installing the sysroot images
15
16Installation of the sysroot is performed by
17`build/linux/sysroot_scripts/install-sysroot.py`.
18
19This script can be run manually but is normally run as part of gclient
20hooks. When run from hooks this script in a no-op on non-linux platforms.
21
22## Rebuilding the sysroot image
23
24The pre-built sysroot images occasionally needs to be rebuilt.  For example,
25when security updates to Debian are released, or when a new package is needed by
26the chromium build.  If you just want to update the sysroots without adding any
27new packages, skip to `Using build_and_upload.py`.
28
29### Adding new packages
30
31To add a new package, edit the `sysroot-creator-*.sh` scripts and modify the
32`DEBIAN_PACKAGES` list.
33
34### Rebuilding
35
36To rebuild the images (without any changes) run the following commands:
37
38    $ cd build/linux/sysroot_scripts
39    $ ./sysroot-creator-stretch.sh BuildSysrootAll
40
41The above command will rebuild the sysroot for all architectures. To build
42just one architecture use `BuildSysroot<arch>`.  Run the script with no
43arguments for a list of possible architectures.  For example:
44
45    $ ./sysroot-creator-stretch.sh BuildSysrootAmd64
46
47This command on its own should be a no-op and produce an image identical to
48the one on Google Cloud Storage.
49
50### Uploading new images
51
52To upload images to Google Cloud Storage run the following command:
53
54    $ ./sysroot-creator-stretch.sh UploadSysrootAll
55
56Here you should use the SHA1 of the git revision at which the images were
57created.
58
59Uploading new images to Google Clound Storage requires write permission on the
60`chrome-linux-sysroot` bucket.
61
62### Rolling the sysroot version used by chromium
63
64Once new images have been uploaded, the `sysroots.json` file needs to be updated
65to reference the new versions.  This process is manual and involves updating the
66`Revision` and `Sha1Sum` values in the file.
67
68### Using `build-and-upload.py`
69
70The `build_and_upload.py` script automates the above four steps.  It is
71recommended to use this just before you're ready to submit your CL, after you've
72already tested one of the updated sysroots on your local configuration.  Build
73or upload failures will not produce detailed output, but will list the script
74and arguments that caused the failure.  To debug this, you must run the failing
75command manually.  This script requires Google Cloud Storage write permission on
76the `chrome-linux-sysroot` bucket.
77