Instrumented libraries for dynamic tools

Instrumented libraries are a part of Chromium's development infrastructure. They are intended to completent sanitizer tools (AddressSanitizer, MemorySanitizer, ThreadSanitizer).

Supported platforms: Ubuntu Trusty, Ubuntu Precise (both x86_64 only).


Sanitizer tools rely on compile-time instrumentation. However, Chromium code may call into system-installed third-party shared libraries, which were not built with the appropriate instrumentation. This is a problem:
  • bugs in third-party libraries, which may affect Chromium, go undetected,
  • certain Chromium bugs may go undetected (e.g. passing an invalid buffer to third-party code),
  • MemorySanitizer generates lots of bogus reports, which makes it unusable. This happens because MSan doesn't recognize any memory initialization which happens in uninstrumented code.
To avoid this issue, we've made it possible to make Chromium use sanitizer-instrumented versions of third-party DSOs. By setting a GYP flag, you can either have them built from source during Chromium build, or download pre-built binaries from Google Storage. The list contains ~50 third-party packages, which should cover most of the DSO dependencies of Chrome and tests (enough at least to run MSan without bogus reports).

Using pre-built binaries

Just add use_prebuilt_instrumented_libraries=1 to GYP_DEFINES. An archive containing the full set of instrumented libraries will be downloaded from GCS and unpacked into $OUTPUT_DIR/instrumented_libraries_prebuilt. The correct build configuration will be chosen automatically depending on your other GYP flags.

Note that we don't provide pre-built binaries for every configuration. At this point in time only MSan is supported, with msan_track_origins either 0 or 2.

Building from source

First you need to install build dependencies:

sudo third_party/instrumented_libraries/scripts/

To build instrumented libraries from source, add use_instrumented_libraries=1 to GYP_DEFINES. This will add ~50 extra steps to the build. Each step runs a script which does the following:
  • checks out a specific package with apt-get source,
  • maybe applies a Chromium-specific patch,
  • builds the package using ./configure + make,
  • installs the shared libraries into $OUTPUT_DIR/instrumented_libraries/<sanitizer_name>/lib/,
  • copies the source archives to $OUTPUT_DIR/instrumented_libraries/sources/.
Extra GYP flags that affect the build:
  • instrumented_libraries_jobs: Controls the number of jobs spawned per package. This will be the -j parameter passed to make. Note that the total number of jobs will be much higher if you have multiple packages building in parallel.
  • instrumented_libraries_cc, instrumented_libraries_cxx: These specify the compiler to use for instrumented libraries. The default is Chromium's bundled clang (from third_party/llvm-build/). If you pass CC/CXX to gclient runhooks (e.g. to build with tip-of-tree clang), you must also override the instrumented libraries compiler with these GYP flags.
GOMA is supported (just add use_goma=1). If this is set and you override the compiler with the GYP flags above, then GOMA will use the new compiler.

Adding new packages

You'll need to ping earthdok@ or glider@ to do this. The information below is for reference. 

To add a new package, you need to do the following:
  • get OSS compliance approval,
  • add a new target to third_party/instrumented_libraries/instrumented_libraries.gyp,
  • add the package to third_party/instrumented_libraries/scripts/,
  • make sure it builds and works on Precise and/or Trusty (i.e. where applicable),
  • update the pre-built binaries.
Usually you want to use the same configure flags that debian/rules uses.

To rebuild the binaries, run:

third_party/instrumented_libraries/scripts/ all

You may need to do this on both Precise and Trusty (depending on what your change affects). It's a good idea to not do this on Goobuntu. We have a couple GCE instances configured for this.

After uploading the archives to GCS as the script instructs, you'll get several .sha1 files. You should commit those under third_party/instrumented_libraries/binaries/.