roc/BUILDING_FROM_SOURCE.md

Building the Roc compiler from source

If you run into any problems getting Roc built from source, please ask for help in the #beginners channel on Roc Zulip (the fastest way), or create an issue in this repo!

Using Nix

On MacOS and Linux, we highly recommend Using nix to quickly install all dependencies necessary to build roc.

⚠️ If you tried to run cargo in the repo folder before installing nix, make sure to execute cargo clean first. To prevent you from executing cargo outside of nix, tools like direnv and lorri can put you in a nix shell automatically when you cd into the directory.

On Linux x86_64 or MacOS aarch64/arm64/x86_64

Install

If you are running ArchLinux or a derivative like Manjaro, you'll need to run sudo sysctl -w kernel.unprivileged_userns_clone=1 before installing nix.

Install nix (not necessary on NixOS):

• If you are using WSL (Windows subsystem for Linux):

sh <(curl -L https://nixos.org/nix/install) --no-daemon

• For everything else:

sh <(curl -L https://nixos.org/nix/install) --daemon

Open a new terminal and edit either ~/.config/nix/nix.conf or /etc/nix/nix.conf and add:

experimental-features = nix-command flakes

If Nix was installed in multi-user mode, make sure to restart the nix-daemon. If you don't know how to do this, restarting your computer will also do the job.

Usage

Now with nix set up, you just need to run one command from the roc project root directory:

nix develop

You should be in a shell with everything needed to build already installed. Use cargo run help to see all subcommands. To use the repl subcommand, execute cargo run repl. Use cargo build to build the whole project.

Read the instructions here to make nix work well with your development tools (vscode, vim, rust-analyzer...)

Extra tips

If you want to load all dependencies automatically whenever you cd into roc, check out direnv. Then you will no longer need to execute nix develop first.

Troubleshooting

Create an issue if you run into problems not listed here. That will help us improve this document for everyone who reads it in the future!

Manual Install

To build the compiler, you need these installed:

• Zig, see below for version
• On Debian/Ubuntu sudo apt-get install pkg-config
• LLVM, see below for version
• rust

To run the test suite (via cargo test), you additionally need to install:

• valgrind (needs special treatment to install on macOS Alternatively, you can use cargo test --no-fail-fast or cargo test -p specific_tests to skip over the valgrind failures & tests.

For debugging LLVM IR, we use DebugIR. This dependency is only required to build with the --debug flag, and for normal development you should be fine without it.

libxcb libraries

You may see an error like this during builds:

/usr/bin/ld: cannot find -lxcb-render
/usr/bin/ld: cannot find -lxcb-shape
/usr/bin/ld: cannot find -lxcb-xfixes

If so, you can fix it like so:

sudo apt-get install libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev

Zig

version: 0.11.0

For any OS, you can use zigup to manage zig installations.

If you prefer a package manager, you can try the following:

• MacOS: brew install zig@0.11.0
• Systems with snap (such as Ubuntu): snap install zig --classic --beta
• Other systems: refer to the zig documentation

If you want to install it manually, you can download the binary and place it on your PATH. Apart from the binary, the archive contains a lib folder, which needs to be copied next to the binary.

WINDOWS NOTE: when you unpack the Zig archive on windows, the result is nested in an extra directory. The instructions on the zig website will seem to not work. So, double-check that the path to zig executable does not include the same directory name twice.

LLVM

version: 16.0.x

See below for operating system specific installation instructions.

Building

Use cargo build to build the whole project. Use cargo run help to see all subcommands. To use the repl subcommand, execute cargo run repl.

The default is a developer build. For an optimized build, use:

cargo build --release --bin roc

LLVM installation on Linux

For Ubuntu and Debian:

sudo apt -y install lsb-release software-properties-common gnupg
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
./llvm.sh 16

If you use this script, you'll need to add clang to your PATH. By default, the script installs it as clang-16. You can address this with symlinks like so:

sudo ln -s /usr/bin/clang-16 /usr/bin/clang

There are also alternative installation options at http://releases.llvm.org/download.html

Troubleshooting

For Fedora:

sudo dnf install llvm16 llvm16-devel

LLVM Linux troubleshooting

On some Linux systems we've seen the error "failed to run custom build command for x11". On Ubuntu, running sudo apt install pkg-config cmake libx11-dev fixed this.

If you encounter cannot find -lz run sudo apt install zlib1g-dev.

If you encounter:

error: No suitable version of LLVM was found system-wide or pointed
       to by LLVM_SYS_160_PREFIX.

Add export LLVM_SYS_160_PREFIX=/usr/lib/llvm-16 to your ~/.bashrc or equivalent file for your shell.

LLVM installation on MacOS

For macOS, you can install LLVM 16 using brew install llvm@16 and then adding $(brew --prefix llvm@16)/bin to your PATH. You can confirm this worked by running llc --version - it should mention "LLVM version 16.0.x" at the top. You may also need to manually specify a prefix env var like so:

export LLVM_SYS_160_PREFIX=$(brew --prefix llvm@16)

LLVM MacOS troubleshooting

If installing LLVM fails, it might help to run sudo xcode-select -r before installing again.

It might also be useful to add these exports to your shell:

export LDFLAGS="-L/usr/local/opt/llvm/lib -Wl,-rpath,/usr/local/opt/llvm/lib"
export CPPFLAGS="-I/usr/local/opt/llvm/include"

LLVM installation on Windows

Warning While cargo build works on windows, linking roc programs does not yet, see issue #2608. This also means the repl, and many tests will not work on windows. The official LLVM pre-built binaries for Windows lack features that roc needs. Instead:

1. Download the custom LLVM 7z archive here.
2. Download 7-zip to be able to extract this archive.
3. Extract the 7z file to where you want to permanently keep the folder. We recommend you pick a path without any spaces in it.
4. In powershell, set the LLVM_SYS_160_PREFIX environment variable (check here to make this a permanent environment variable):

<# ! Replace YOUR_USERNAME ! #>
$env:LLVM_SYS_160_PREFIX = 'C:\Users\YOUR_USERNAME\Downloads\LLVM-16.0.6-win64'

Once all that was done, cargo build ran successfully for Roc!

LLVM Windows troubleshooting

If you see the build failing because some internal file is not available, it might be your anti-virus program. Cargo's behavior is kind of similar to a virus (downloading files from the internet, creating many files), and this has been known to cause problems.

Build speed on WSL/WSL2

If your Roc project folder is in the Windows filesystem but you're compiling from Linux, rebuilds may be as much as 20x slower than they should be! Disk access during linking seems to be the bottleneck. It's recommended to move your folder to the Linux filesystem.

Use LLD for the linker

Using lld for Rust's linker makes build times a lot faster, and I highly recommend it.

Create ~/.cargo/config.toml if it does not exist and add this to it:

[build]
# Link with lld, per https://github.com/rust-lang/rust/issues/39915#issuecomment-538049306
# Use target-cpu=native, per https://deterministic.space/high-performance-rust.html
rustflags = ["-C", "link-arg=-fuse-ld=lld", "-C", "target-cpu=native"]

Then install lld version 16 (e.g. with $ sudo apt-get install lld-16) and add make sure there's a ld.lld executable on your PATH which is symlinked to lld-16.

That's it! Enjoy the faster builds.