Skip to content

Latest commit

 

History

History
151 lines (116 loc) · 5.16 KB

INSTALL.md

File metadata and controls

151 lines (116 loc) · 5.16 KB

Building Vere

We use bazel1 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 bazel1 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, autoconf-archive, pkg-config, 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 dbg as the compilation_mode:

bazel build --compilation_mode=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 specifying the cpu_dbg and/or the mem_dbg build config.

bazel build --config=cpu_dbg --config=mem_dbg :urbit

Note that ships booted from builds with one or both of these configs specified are incompatible with builds of vere without them and vice versa.

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

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

Note --copt can be used to specify arbitrary C compiler optimizations. They're passed directly to the compiler commands generated by bazel.

Additionally, --copt is propagated to all dependencies. This has the undesirable side effect of considerably slowing down build times when you're switching between different copts (say the inclusion or exclusion of some macro define with --copt='-DMACRO') since all dependencies will be rebuilt. If you want only to pass the copt to the compiler commands invoked to build :urbit, you can pass them with --per_file_copt like so:

bazel build --per_file_copt='pkg/.*@-DMACRO'

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.

Footnotes

  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/. ↩ ↩2