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 2.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 macOS, 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
In most cases, the following three steps suffice to build OpenCilk from
source on a compatible system with prerequisite software installed.
- Clone the OpenCilk infrastructure repository:
$ git clone -b opencilk/v2.1 https://github.com/OpenCilk/infrastructure
- Run the
get script to get the OpenCilk source code:
$ infrastructure/tools/get $(pwd)/opencilk
- Run the
build 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 (detailed instructions)
Clone the OpenCilk compiler, runtime, and productivity-tool repositories. The
Cheetah runtime and OpenCilk tool repositories must be cloned into specific
subdirectories of the OpenCilk project directory:
$ git clone -b opencilk/v2.1 https://github.com/OpenCilk/opencilk-project
$ git clone -b opencilk/v2.1 https://github.com/OpenCilk/cheetah opencilk-project/cheetah
$ git clone -b opencilk/v2.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/v2.1 https://github.com/OpenCilk/infrastructure
Building OpenCilk (detailed instructions)
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
If you encounter problems during the build process, see Troubleshooting for guidance on fixing common problems, or contact us via the OpenCilk issue tracker or by emailing us at contact@opencilk.org.
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++ to the build-directory path to run the OpenCilk C++
compiler.
To run 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 processor. 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 macOS, you will need a
XCode or
XCode Command Line Tools
installed 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 the system directory /opt/opencilk-2 using the following command:
$ cmake --build build --target install
Note that you may need superuser privileges to perform this installation, in order to write to the system directory.
If you don't have superuser privileges or would prefer not to install OpenCilk into a system directory, you can instead install OpenCilk locally in a directory of your choosing by running the cmake_install.cmake script in the build
directory. For example, the following command will install OpenCilk into your
home directory, specifically, under $HOME/.local/opencilk:
$ cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local/opencilk -P build/cmake_install.cmake
After either of these installation steps, you will need to add the
bin directory within the OpenCilk installation --- e.g.,
/opt/opencilk-2/bin or $HOME/.local/opencilk/bin --- to your
$PATH in order to run the OpenCilk binary executables without
specifying the path to those binaries, e.g., by simply running clang
or clang++ (or, on macOS, by running xcrun clang or xcrun clang++). To verify that clang refers to the OpenCilk compier, run
which clang and verify that the output matches the path to the
clang binary in your OpenCilk installation, e.g.,
/opt/opencilk-2/bin/clang or $HOME/.local/opencilk/bin/clang.
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.
Don't see your issue here? Please contact us via the OpenCilk issue
tracker or by
emailing us at contact@opencilk.org.