This document describes how to install the necessary tools and dependencies to build the Hash compiler from source.
The Rust Programming language and cargo are required to build the Hash
compiler. The easiest way to install Rust is using rustup.
Note: This section is only necessary if you want to build the LLVM backend of the Hash compiler. If you want to build the compiler without LLVM support, see 3. Building without LLVM.
One of the Hash compiler code generation backends is LLVM, so you will need to install LLVM on your system. Currently, the compiler uses LLVM 20.1.8.
We provide instructions for installing LLVM 20 on macOS, Linux, and Windows.
On macOS, you can install LLVM 20 using Homebrew:
brew install llvm@20
After installation, you need to set the following environment variables, replacing
$PATH_TO_LLVM with the actual path where Homebrew installed LLVM (you can
find it by running brew --prefix llvm@20):
Add the path to your shell profile file (e.g., ~/.zprofile, ~/.bash_profile, etc.):
export LLVM_SYS_201_PREFIX=$(brew --prefix llvm@20)
export PATH="$PATH:$LLVM_SYS_201_PREFIX/bin"
set -x LLVM_SYS_201_PREFIX (brew --prefix llvm@20)
set -x PATH $PATH $LLVM_SYS_201_PREFIX/bin
You can download this version of LLVM from
here for
your specific OS. Additionally, you need to install zstd (which can be
acquired using a package manager or from
here).
Once LLVM 20.1.8 and zstd are installed, you need to set the following
environment variables, replacing $PATH_TO_LLVM and $PATH_TO_ZSTD
appropriately for your system depending on your installation:
# hashc-related
export LIBRARY_PATH="$LIBRARY_PATH:$PATH_TO_ZSTD/lib"
export DYLD_LIBRARY_PATH="$DYLD_LIBRARY_PATH:$PATH_TO_LLVM/lib"
export LDFLAGS="-L$PATH_TO_LLVM/lib"
export CPPFLAGS="-I$PATH_TO_LLVM/include"
export PATH="$PATH:$PATH_TO_LLVM/bin"
export LLVM_SYS_201_PREFIX="$PATH_TO_LLVM"
This can be put in your shell script startup file
(.zprofile/.bash_profile/etc), or in a shell script and you can source it
whenever you want to use hashc (the former is recommended).
Now, you should be able to run cargo build on hashc and it should work.
To install on Windows, the simplest way to install it is using Chocolatey:
choco install llvm --version 20.1.8
Alternatively, you can download the pre-built binaries from the LLVM website.
Once LLVM is installed, verify that $LLVM_SYS_201_PREFIX/bin is in your PATH and the variable itslef is set.
After which, we may proceed to build the project using cargo build.
cargo build
We all know that LLVM is a huge and bulky dependency, which isn’t always easy to install on a local machine. Therefore, this project provides a way to build the compiler without LLVM. To do so, you can simply build the main package in the following way:
cargo build -p hashc --no-default-features
This will build the compiler without the llvm feature, and hence you won’t have the LLVM backend available.
To verify that everything is working correctly, you can create a simple “Hello, World!” program in Hash.
mkdir examples/
echo 'main := () => { println("Hello, World!"); }' > examples/hello.hash
target/debug/hashc -i examples/hello.hash --stage exe
Hello, World!
:tada: Yes! You’ve successfully built and run the Hash compiler from source.
hashc globallyTo install hashc globally on your system, you can use Cargo’s install command:
cargo install --path .