Build OpenCilk from source

This page describes how to download and build OpenCilk from source. OpenCilk is available as source code in three Git repositories. We provide an infrastructure facilities repository with scripts for downloading and building OpenCilk from source. OpenCilk 1.1 is only guaranteed to support 64-bit x86 on Linux and other Unix-like operating systems, although prototype support for 64-bit ARM is included.

Requirements

The build requirements for OpenCilk are largely consistent with those for LLVM. In summary, to build OpenCilk on a modern system running Linux or MacOSX, you will need the following:

  • A relatively recent version of Git.
  • A relatively modern C/C++ compiler, such as GCC or Clang, that is capable of building LLVM. Any compiler you are likely to have installed on a modern multicore system should work.
  • CMake version 3.13.4 or newer.
  • Approximately 1.5 GB of space for the source code (mostly LLVM) plus 2.5 GB of space to build, for a total of 4 GB.

More details on build requirements for LLVM can be found here: https://llvm.org/docs/GettingStarted.html#requirements

Quick start

Clone the OpenCilk infrastructure repository:

$ git clone -b opencilk/v1.1 https://github.com/OpenCilk/infrastructure

Run the following script to get the OpenCilk source code:

$ infrastructure/tools/get $(pwd)/opencilk

Then run the following script to build OpenCilk:

$ infrastructure/tools/build $(pwd)/opencilk $(pwd)/build

You should now be ready to use OpenCilk. Skip to Usage now, or read on for more explicit directions on building OpenCilk from source.

Obtaining the OpenCilk source code

Clone the OpenCilk compiler, runtime, and productivity-tool repositories. The Cheetah runtime and OpenCilk tool repositories must be cloned into sub-directories of the OpenCilk project directory:

$ git clone -b opencilk/v1.1 https://github.com/OpenCilk/opencilk-project
$ git clone -b opencilk/v1.1 https://github.com/OpenCilk/cheetah opencilk-project/cheetah
$ git clone -b opencilk/v1.1 https://github.com/OpenCilk/productivity-tools opencilk-project/cilktools

Note that, because these commands clone specific tags of the OpenCilk repositories, it is normal for Git to report that each clone is in a 'detached HEAD' state after cloning.

Clone the OpenCilk infrastructure repository, which contains the OpenCilk build script:

$ git clone -b opencilk/v1.1 https://github.com/OpenCilk/infrastructure

Building OpenCilk

Run the infrastructure/tools/build script with two or three arguments. The 1st argument is the absolute pathname to the opencilk-project repository directory. The 2nd argument is the absolute pathname of a directory to build OpenCilk. The 3rd argument, if present, tells the build system how many parallel jobs to run. Default parallelism is equal to the number of logical cores, or 10 if the number of cores is not detected.

For example:

# ...git clone as above...
$ infrastructure/tools/build $(pwd)/opencilk-project $(pwd)/build

Alternatively, to explicitly build OpenCilk using 8 build threads:

# ...git clone as above...
$ infrastructure/tools/build $(pwd)/opencilk-project $(pwd)/build 8

OpenCilk takes a few CPU-hours to build on a modern system --- less than 10 minutes on a 24-core Ryzen with a fast disk. It might take all day single-threaded on an older machine.

To echo the OpenCilk build script call syntax, use the --help switch:

$ infrastructure/tools/build --help

Advanced build options: If you wish, you can customize your build of OpenCilk beyond what the script provides --- e.g., to build additional LLVM subprojects --- by running the necessary CMake commands yourself. When run, the infrastructure/tools/build script will print out the cmake commands it runs to build OpenCilk from source. OpenCilk supports many of the same CMake build options as standard LLVM, which are documented here: https://llvm.org/docs/CMake.html. If you wish to customize your OpenCilk build with these options, we recommend keeping clang in the list passed to -DLLVM_ENABLE_PROJECTS and cheetah;cilktools in the list passed to -DLLVM_ENABLE_RUNTIMES.

Usage

You can run the OpenCilk C compiler out of its build tree, adding /bin/clang to the build directory name. Similarly, add /bin/clang++ for the OpenCilk C++ compiler.

Running on x86, you must have a chip with Intel's Advanced Vector Instructions (AVX). This includes Sandy Bridge and newer Intel processors (released starting in 2011), and Steamroller and newer AMD processors (released starting in 2014).

OpenCilk should work on any 64-bit ARM via its experimental ARM support. In particular, OpenCilk has been tested on Apple's M1. It may be helpful to try different values of the CILK_NWORKERS environment variable on chips like the M1 that mix low- and high-power cores.

On MacOSX, you will need an XCode or CommandLineTools installation to provide standard system libraries and header files for clang. To run clang with those header files and libraries, invoke the clang binary with xcrun; for example:

$ xcrun $(pwd)/build/bin/clang

Optional: Installing OpenCilk

You can install OpenCilk into a directory of your choosing by running the cmake_install.cmake script generated in the build directory. For example, run the following to install OpenCilk into the directory /tmp/llvm:

$ cd $(pwd)/build
$ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake

Troubleshooting

Here are a few common problems encountered when building from source, along with suggested workarounds.

  • The build fails with the error message, collect2: error: ld returned 1 exit status.

This error typically occurs when the build process exhausts the physical memory available on the system. Building OpenCilk from source with many parallel build threads can consume a large amount of physical memory, roughly speaking, in the tens of gigabytes.

Fix: Try reducing the number of parallel threads for building OpenCilk. Alternatively, try building OpenCilk from source using clang and LLVM's linker, lld, which tends to consume less physical memory than ld.

  • The build fails with the error message, unrecognized argument to '-fno-sanitize=' option: 'safe-stack'.

This error typically occurs when the C and C++ compilers on the system are mismatched, e.g., if gcc and g++ refer to different compiler versions on the system.

Fix: Make sure that the versions of gcc and g++ installed on the system are consistent.