| 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, |
| 25 | when security updates to debian are released, or when a new package is needed by |
| 26 | the chromium build. |
| 27 | |
| 28 | ### Rebuilding |
| 29 | |
| 30 | To rebuild the images (without any changes) run the following commands: |
| 31 | |
| 32 | $ cd build/linux/sysroot_scripts |
| 33 | $ ./sysroot-creator-wheezy.sh BuildSysrootAll |
| 34 | |
| 35 | The above command will rebuild the sysroot for all architectures. To build |
| 36 | just one architecture use `BuildSysroot<arch>`. Run the script with no |
| 37 | arguments for a list of possible architectures. For example: |
| 38 | |
| 39 | $ ./sysroot-creator-wheezy.sh BuildSysrootAmd64 |
| 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 | |
| 44 | ### Updating existing package list |
| 45 | |
| 46 | To update packages to the latest versions run: |
| 47 | |
| 48 | $ ./sysroot-creator-wheezy.sh UpdatePackageListsAll |
| 49 | |
| 50 | This command will update the package lists that are stored alongside the script. |
| 51 | If no packages have changed then this script will have no effect. |
| 52 | |
| 53 | ### Adding new packages |
| 54 | |
| 55 | To add a new package, edit the `sysroot-creator-wheezy.sh` script and modify |
| 56 | the `DEBIAN_PACKAGES` list, then run the update step above |
| 57 | (`UpdatePackageListsAll`). |
| 58 | |
| 59 | ### Uploading new images |
| 60 | |
| 61 | To upload images to Google Cloud Storage run the following command: |
| 62 | |
| 63 | $ ./sysroot-creator-wheezy.sh UploadSysrootAll <SHA1> |
| 64 | |
| 65 | Here you should use the SHA1 of the git revision at which the images were |
| 66 | created. |
| 67 | |
| 68 | Uploading new images to Google Clound Storage requires write permission on the |
| 69 | `chrome-linux-sysroot` bucket. |
| 70 | |
| 71 | ### Rolling the sysroot version used by chromium |
| 72 | |
| 73 | Once new images have been uploaded the `install-sysroot.py` script needs to be |
| 74 | updated to reference the new versions. This process is manual and involves |
| 75 | updating the `REVISION` and `SHA1SUM` variables in the script. |
