roc/BUILDING_FROM_SOURCE.md

Building the Roc compiler from source

Installing LLVM

To build the compiler, you need a particular version of LLVM installed on your system.

To see which version of LLVM you need, take a look at Cargo.toml, in particular the branch section of the inkwell dependency. It should have something like llvmX-Y where X and Y are the major and minor revisions of LLVM you need.

For Ubuntu and Debian, you can use the Automatic installation script at apt.llvm.org:

sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"

But there are plenty of alternative options at http://releases.llvm.org/download.html

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!

LLVM installation on Linux

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

LLVM installation on Windows

Installing LLVM's prebuilt binaries doesn't seem to be enough for the llvm-sys crate that Roc depends on, so I had to build LLVM from source on Windows. After lots of help from @IanMacKenzie (thank you, Ian!), here's what worked for me:

1. I downloaded and installed Build Tools for Visual Studio 2019 (a full Visual Studio install should work tool; the Build Tools are just the CLI tools, which is all I wanted)
2. In the installation configuration, under "additional components" I had to check both "C++ ATL for latest v142 build tools (x86 & x64)" and also "C++/CLI support for v142 build tools"
3. I launched the "x64 Native Tools Command Prompt for Visual Studio 2019" application (note: not the similarly-named "x86" one!)
4. I followed most of the steps under LLVM's building from source instructions up to the cmake -G ... command, which didn't work for me. Instead, at that point I did the following step.
5. I ran cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release ../llvm to generate a NMake makefile.
6. Once that completed, I ran nmake to build LLVM. (This took about 2 hours on my laptop.)
7. Finally, I set an environment variable LLVM_SYS_100_PREFIX to point to the build directory where I ran the cmake command.

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

Use LLD for the linker

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

Create ~/.config/cargo 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 9 (e.g. with $ sudo apt-get install lld-9) and add make sure there's a ld.lld executable on your PATH which is symlinked to lld-9.

That's it! Enjoy the faster builds.