cxx-common

Build and installation scripts for C and C++ libraries that are commonly used by Trail of Bits.

Docker Builds

This project includes a Dockerfile that is automatically built and pushed to DockerHub and Github Package Registry. Both registries should have identical packages, but some architectures (currently, AArch64) packages are updated manually and may be out of sync between registries.

Quick Package Repository Links:

• GitHub Package Repository
• DockerHub Package Repository

Binary build artifacts are also automatically published with each passing CI build on Github Actions.

Using the Docker Build

Docker images are parameterized by LLVM version, OS, and architecture. Not all LLVM/OS/Architecture combinations packages are pre-built.

Supported LLVM Versions: 4.0.1 through current Supported Architectures: amd64, aarch64 Supported OSes: Ubuntu 16.04, Ubuntu 18.04; Other Linux distributions likely also work but are untested. Windows and MacOS are supported via manual (that is, non-Docker) builds.

For example, to fetch the cxx-common image using LLVM 8.0 for Ubuntu 18.04 on AMD64, you'd use:

# for DockerHub Packages
docker pull trailofbits/cxx-common:llvm800-ubuntu18.04-amd64

or

# for GitHub Package Repository packages
docker pull docker.pkg.github.com/trailofbits/cxx-common/llvm800-ubuntu18.04-amd64:latest

Building The Docker Image Yourself

The Dockerfile can be built locally. It is parameterized by LLVM version and OS release. Currently same-architecture builds are expected (i.e., build amd64 images on amd64 and build aarch64 images on aarch64). Some examples below:

Building cxx-common for LLVM 8 on Ubuntu 18.04 on AArch64 (ARM v8 64-bit):

docker build . -t cxx-common:llvm800-ubuntu18.04-aarch64 -f Dockerfile --build-arg UBUNTU_BASE=arm64v8/ubuntu:18.04 --build-arg LLVM_VERSION=800

Building cxx-common for LLVM 4.0.1 on Ubuntu 16.04 for AMD64 (x86-64):

docker build . -t cxx-common:llvm401-ubuntu16.04-amd64 -f Dockerfile --build-arg UBUNTU_BASE=ubuntu:16.04 --build-arg LLVM_VERSION=401

Manual (non-Docker) Builds

There may be cases where Dockerized builds are not desired or not possible. The project can be also built manually.

macOS/Linux prerequisites

When building LLVM < 5.x on Linux you will need the 'xlocale.h' include header from the libc6-dev package. This file was deprecated in Ubuntu > 16.04.x, so if you are building on a recent distribution, you should probably build version 5.0.1 or better.

1. LZMA (liblzma-dev on Ubuntu)
2. Python LZMA module (pip install backports.lzma)

How to build the 'libraries' repository

• Dependencies can be installed using Travis build script: ./travis.sh <linux|macos> initialize
• If you are building recent LLVM versions, you can probably just run ./travis.sh <linux|macos> build
• If you are calling pkgman.py directly, always try to use the best compiler available, passing the --c_compiler and -cxx_compiler parameters.
• When calling the build function of the Travis script, you can set your preferred compiler using the standard environment variables: CC and CXX.

Errors are always printed but if you'd rather see the build output in real time, the --verbose parameter can be passed to pkgman.py.

Windows support

Note that only LLVM 5.0.1 is known to work right now; when running the script on Windows, the --llvm_version parameter defaults to 501.

Prerequisites

1. Python 2.7 (x64): https://www.python.org/ftp/python/2.7.14/python-2.7.14.amd64.msi (add to PATH)
2. Visual Studio 2017: https://www.visualstudio.com/thank-you-downloading-visual-studio/?sku=Community&rel=15
3. LLVM 5.0.1 x64 for Visual Studio: http://releases.llvm.org/5.0.1/LLVM-5.0.1-win64.exe (do NOT add to PATH)
4. 7-Zip (x64): https://www.7-zip.org/a/7z1805-x64.exe

Building the llvm35 version

Prerequisites

• Ubuntu 14.04 or OS X with Homebrew
• Clang-3.5 or newer
• Travis script dependencies (./travis.sh linux initialize or ./travis.sh osx initialize)

Build steps

• Run ./travis.sh <linux or osx> build
• Or, manually:
  • Build CMake: ./pkgman.py --c_compiler=clang-3.5 --cxx_compiler=clang++-3.5 --repository_path=/opt/TrailOfBits/libraries --packages=cmake
  • Update the PATH: export PATH="/opt/TrailOfBits/libraries/cmake/bin:${PATH}"
  • Build the remaining packages: ./pkgman.py --llvm_version=352 --c_compiler=clang-3.5 --cxx_compiler=clang++-3.5 --repository_path=/opt/TrailOfBits/libraries --packages=llvm,capstone,google,xed,capnproto