Skip to content

Latest commit

 

History

History
104 lines (83 loc) · 4.4 KB

INSTALL.md

File metadata and controls

104 lines (83 loc) · 4.4 KB
Raw

Building 3C

This document describes our current setup and build process for 3C. You may find helpful information about topics not addressed here in the general Checked C build documentation. Some items here are potentially applicable to Checked C as a whole, and we hope to eventually harmonize them with the Checked C documentation as appropriate.

Supported environments

We aim to support Linux, Windows, and Mac OS X. We do most of our work on Linux and test the other OSes less frequently (additional information), so you are more likely to run into problems on the other OSes; if you do, please file an issue and we will try to fix it if it is severe enough. Getting 3C to work on Mac OS X can be fiddly, but we have managed it so far.

Basics

As described here, you can use either https://github.com/correctcomputation/checkedc-clang or https://github.com/microsoft/checkedc-clang (or, of course, a third-party fork, though we can't be responsible for that). Assuming you have already cloned one of these repositories, run the following (from the checkedc-clang directory or whatever you named your clone) for a basic build:

# Get a copy of the Checked C system headers. Use Microsoft's
# "checkedc" repository regardless of which "checkedc-clang"
# repository you use.
git clone https://github.com/microsoft/checkedc llvm/projects/checkedc-wrapper/checkedc

mkdir build && cd build
cmake ../llvm -G Ninja -DLLVM_ENABLE_PROJECTS=clang
ninja TARGET

where TARGET stands for the target(s) you want to build. For the 3c command-line tool, the target is 3c, but assuming you want to actually compile the Checked C source files generated by 3C, you'll also want to build clang (the Checked C compiler, which is a modified version of Clang). Executables will end up in build/bin; you'll likely want to add this directory to your $PATH or write suitable wrapper scripts.

Here is how to use the 3c tool once you build it.

Build options

Because all of LLVM and clang are built as dependencies, this may consume up to ~50 GB of disk space, take several hours (depending on the speed of your computer), and require ~10 GB of RAM. Incremental builds will usually be faster. Here are some things you can do that may reduce the build time and/or peak memory use:

  • The above instructions already assume the use of the Ninja build tool; you may have to install it. You can alternatively use make (remove -G Ninja from the cmake command and replace ninja with make), but Ninja is much faster in our experience.

  • Pass -DLLVM_TARGETS_TO_BUILD=X86 (or whatever your machine's architecture is, e.g., ARM) to cmake to build only the parts of clang needed to compile programs for your machine.

  • Pass -DLLVM_USE_LINKER=lld. This requires a sufficiently recent version of lld to be installed on your system.

  • Pass -DLLVM_USE_SPLIT_DWARF=ON. We have tested the build with this option, but it may affect some debugging tools.

  • Pass -DLLVM_OPTIMIZED_TABLEGEN=ON.

  • Pass -DLLVM_APPEND_VC_REV=OFF to turn off embedding of your Git head commit ID in the executables and thus avoid the need to re-link all of them every time the commit ID changes.

(The reference for improving build performance is this LLVM page, but we have attempted to describe the most promising options here.)

You might want to use -DCMAKE_BUILD_TYPE=RelWithDebInfo if you are running 3C enough between builds that the faster running time outweighs the slower build time or you simply want to test a release build of 3C, assuming that's what end users will eventually be encouraged to use.

Mac OS X

On some OS X versions, you have to add -DDEFAULT_SYSROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk to the cmake command; add it just after the -DLLVM_ENABLE... flags. You also need to make sure that the XCode developer command-line tools are installed, per this thread. Go to https://developer.apple.com/download/more/, log in with your Apple Developer ID, and download "Command Line Tools for Xcode 11.3.1". Then, enable these by invoking (from the command line), sudo xcode-select -r.