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