Skip to content

Latest commit

 

History

History
56 lines (43 loc) · 2.87 KB

build_instructions.md

File metadata and controls

56 lines (43 loc) · 2.87 KB

Setup

Ubuntu 22.04 is used for testing. Other Linux distributions may or may not work. Adjust the commands below accordingly.

Install the package prerequisites

# This includes dependencies for tools, testing and examples
sudo apt install -y g++ pkg-config clang libclang-dev llvm-dev \
                    ninja-build zlib1g-dev python3-pip cmake   \
                    libavformat-dev libavutil-dev              \
                    libswscale-dev libsdl2-dev                 \
                    libusb-1.0-0-dev libcriterion-dev

# Install LLVM's LIT tool
pip install lit

# Get rustc nightly. See https://rustup.rs for alternative install methods
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# May need to log out and back in to the shell to see rustup in $PATH
rustup install nightly

Configure with CMake

Note: Adjust paths to your version of Clang/LLVM or use llvm-config --cmakedir. We currently test with LLVM 16 and older versions of libclang may or may not work.

mkdir build && pushd build
cmake ..                                                   \
            -DClang_DIR=$(llvm-config --cmakedir)/../clang \
            -DLLVM_DIR=$(llvm-config --cmakedir)           \
            -DLLVM_EXTERNAL_LIT=$(which lit)               \
            -G Ninja

Notable CMake variables

  • IA2_DEBUG - Adds additional runtime assertions to validate control-flow.
  • LIBIA2_AARCH64 - Builds the runtime and tests for AArch64 using MTE instead of x86-64 with MPK. Tools are still built for the host.
  • CMAKE_TOOLCHAIN_FILE - Typically set to cmake/aarch64-toolchain.cmake to build for AArch64 using GCC. This also sets LIBIA2_AARCH64.
  • IA2_TRACER - Can be used to unconditionally disable the syscall tracer for all tests. Individual tests can opt-out of syscall tracing by specifying WITHOUT_SANDBOX in define_test.

CMake targets

  • check - builds and runs the test suite. Pass -v to ninja to see build commands and output from failing tests.
  • ia2-rewriter - builds the source code rewriter. Depends on libclang-dev and llvm-dev.
  • pad-tls - builds the pad-tls script. Only required for compartmentalized DSOs that use thread-local storage.
  • tools - builds both ia2-rewriter and pad-tls (NOTE: does not always detect when to rebuild accurately).
  • libia2 - builds the runtime as a static library. This does not include call gate transitions as those are program-specific and generated by the rewriter.
  • partition-alloc-padding - builds the compartment-aware shim for Chromium's PartitionAlloc allocator.
  • ia2-sandbox - builds the syscall tracer.

Tests are enumerated in tests/CMakeLists.txt. To build a specific test, use $TEST as the target. See the directory structure doc for an overview of the rest of the repo's contents.