1# Linux Instrumented Libraries 2 3The instrumented libraries are a collection of Chromium's dependencies built 4with *SAN enabled. The MSAN libraries are required for an MSAN build to run. The 5others are optional, and are currently unused. 6 7## Building the instrumented libraries 8 9### Setting up a chroot 10 11Building the libraries requires `apt-get source`, so the build must be done from 12an Ubuntu 14.04 environment. The preferred way is using a chroot. To get 13started, install `debootstrap` and `schroot`. If you're running a Debian-based 14distro, run: 15 16```shell 17sudo apt install debootstrap schroot 18``` 19 20Create a configuration for a Trusty chroot: 21 22```shell 23sudo $EDITOR /etc/schroot/chroot.d/trusty_amd64.conf 24``` 25 26Add the following to the new file, replacing the instances of `thomasanderson` 27with your own username. 28 29``` 30[trusty_amd64] 31description=Ubuntu 14.04 Trusty for amd64 32directory=/srv/chroot/trusty_amd64 33personality=linux 34root-users=thomasanderson 35type=directory 36users=thomasanderson 37``` 38 39Bootstrap the chroot: 40 41```shell 42sudo mkdir -p /srv/chroot/trusty_amd64 43sudo debootstrap --variant=buildd --arch=amd64 trusty /srv/chroot/trusty_amd64 http://archive.ubuntu.com/ubuntu/ 44``` 45 46If your `$HOME` directory is not `/home` (as is the case on gLinux), then route 47`/home` to the real thing. `schroot` automatically mounts `/home`, which is 48where I'm assuming you keep your source tree and `depot_tools`. 49 50```shell 51sudo mount --bind "$HOME" /home 52``` 53 54Add `sources.list`: 55 56```shell 57sudo $EDITOR /srv/chroot/trusty_amd64/etc/apt/sources.list 58``` 59 60Add the following contents to the file: 61 62``` 63deb http://archive.ubuntu.com/ubuntu/ trusty main restricted universe 64deb-src http://archive.ubuntu.com/ubuntu/ trusty main restricted universe 65deb http://archive.ubuntu.com/ubuntu/ trusty-security main restricted universe 66deb-src http://archive.ubuntu.com/ubuntu/ trusty-security main restricted universe 67deb http://archive.ubuntu.com/ubuntu/ trusty-updates main restricted universe 68deb-src http://archive.ubuntu.com/ubuntu/ trusty-updates main restricted universe 69``` 70 71Enter the chroot and install the necessary packages: 72 73```shell 74schroot -c trusty_amd64 -u root --directory / 75apt update 76apt install lsb-release sudo python pkg-config libgtk2.0-bin libdrm-dev nih-dbus-tool help2man 77``` 78 79Add `depot_tools` to your `PATH`. For example, I have it in `~/dev/depot_tools`, 80so I use: 81 82```shell 83export PATH=/home/thomasanderson/dev/depot_tools/:$PATH 84``` 85 86Change to your src directory: 87 88```shell 89cd /home/thomasanderson/dev/chromium/src 90``` 91 92Install library packages: 93 94```shell 95third_party/instrumented_libraries/scripts/install-build-deps.sh 96``` 97 98Now we're ready to build the libraries. A clean build takes a little over 8 99minutes on a 72-thread machine. 100 101```shell 102third_party/instrumented_libraries/scripts/build_and_package.py --parallel -j $(nproc) all 103``` 104 105## Uploading the libraries 106 107This requires write permission on the `chromium-instrumented-libraries` GCS 108bucket. `dpranke@` can grant access. 109 110```shell 111# Exit the chroot. 112exit 113 114# Fix permissions. 115sudo chown -R `whoami`:`groups | awk '{print $1;}'` *.tgz out/Instrumented-* 116 117# Move files into place. 118mv *.tgz third_party/instrumented_libraries/binaries 119 120# Upload. 121upload_to_google_storage.py -b chromium-instrumented-libraries third_party/instrumented_libraries/binaries/msan-chained-origins-trusty.tgz 122upload_to_google_storage.py -b chromium-instrumented-libraries third_party/instrumented_libraries/binaries/msan-no-origins-trusty.tgz 123``` 124 125## Testing and uploading a CL 126 127After uploading, run `gclient sync` and test out a build with `is_msan = true` 128in your `args.gn`. Try running eg. `chrome` and `unit_tests` to make sure it's 129working. The binaries should work natively on gLinux. 130 131When uploading a CL, make sure to add the following in the description so that 132the MSAN bot will run on the CQ: 133 134``` 135CQ_INCLUDE_TRYBOTS=luci.chromium.try:linux_chromium_msan_rel_ng 136``` 137