vere/INSTALL.md

Building Vere

We use bazel¹ to build Vere, which is packaged as a single binary, urbit. We support the following (host, target) pairs, where the host platform is where bazel runs and the target platform is where urbit will run:

Host Platform	Target Platform
linux-aarch64	linux-aarch64
linux-x86_64	linux-x86_64
macos-aarch64	macos-aarch64
macos-x86_64	macos-x86_64

Prerequisites

The first step is to install bazel using the instructions found on the bazel¹ site.

All platforms require the automake and libtool suite of tools installed in order to build Vere. Before going any further, install them using your package manager. For example, on macOS:

brew install automake libtool

Linux

After installing automake and libtool, you need to install the musl libc toolchain. We use musl libc instead of glibc on Linux, which enables us to generate statically linked binaries. As a prerequisite, you need to install the musl libc toolchain appropriate for your target platform.

x86_64

To install the x86_64-linux-musl-gcc toolchain at /usr/local/x86_64-linux-musl-gcc, run:

bazel run //bazel/toolchain:x86_64-linux-musl-gcc

This will take a few minutes.

aarch64

To install the aarch64-linux-musl-gcc toolchain at /usr/local/aarch64-linux-musl-gcc, run:

bazel run //bazel/toolchain:aarch64-linux-musl-gcc

This will take a few minutes.

macOS

After installing automake and libtool, you're ready to build Vere.

Build Commands

Once you install the prerequisites, you're ready to build:

bazel build :urbit

If you want a debug build, which changes the optimization level from -O3 to -O0 and includes more debugging information, specify the dbg configuration:

bazel build --config=dbg :urbit

Note that you cannot change the optimization level for third party dependencies--those targets specified in bazel/third_party--from the command line.

You can turn on CPU and memory debugging by defining U3_CPU_DEBUG and U3_MEMORY_DEBUG, respectively:

bazel build --copt='-DU3_CPU_DEBUG' --copt='-DU3_MEMORY_DEBUG' :urbit

Note that defining these two debug symbols will produce ships that are incompatible with binaries without these two debug symbols defined.

If you need to specify arbitrary C compiler or linker options, use --copt or --linkopt, respectively:

bazel build --copt='-O0' :urbit

Note --copt can be used to specify any C compiler options, not just optimization levels.

Test Commands

You can build and run unit tests only on native builds. If you have a native build and want to run all unit tests, run:

bazel test --build_tests_only ...

If you want to run a specific test, say pkg/noun/hashtable_tests.c, run:

bazel test //pkg/noun:hashtable_tests

Build Configuration File

Any options you specify at the command line can instead be specified in .user.bazelrc if you find yourself using the same options over and over. This file is not tracked by git, so whatever you add to it will not affect anyone else. As an example, if you want to change the optimization level but don't want type --copt='-O0' each time, you can do the following:

echo "build --copt='-O0'" >> .user.bazelrc
bazel build :urbit

For more information on Bazel configuration files, consult the Bazel docs.

Common Issues

If bazel build or bazel test generates an undeclared inclusion(s) in rule error on macOS, the version of clang expected by the build system likely doesn't match the version of clang installed on your system. To address this, run clang --version and pass the version number via --clang_version="<version_string>" to the failing command.

---

1. If you're interested in digging into the details of the build system, check out WORKSPACE.bazel, BUILD.bazel, bazel/, and the multiple BUILD.bazel files in pkg/. ↩︎