mirror of
https://github.com/urbit/vere.git
synced 2024-09-11 11:55:31 +03:00
152 lines
5.1 KiB
Markdown
152 lines
5.1 KiB
Markdown
# Building Vere
|
|
|
|
We use [`bazel`][bazel][^1] 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`][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`][bazel-install][^1] 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:
|
|
|
|
```console
|
|
brew install automake libtool
|
|
```
|
|
|
|
### Linux
|
|
|
|
After installing `automake` and `libtool`, you need to install the [musl libc] toolchain. We use [musl libc][musl libc] instead of [glibc][glibc] on Linux, which enables us to generate statically linked binaries. As a prerequisite, you need to install the [musl libc][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:
|
|
```console
|
|
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:
|
|
```console
|
|
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:
|
|
```console
|
|
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`:
|
|
```console
|
|
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.
|
|
```console
|
|
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`][copt] or [`--linkopt`][linkopt], respectively:
|
|
```console
|
|
bazel build --copt='-Wall' :urbit
|
|
```
|
|
|
|
Note [`--copt`][copt] can be used to specify arbitrary C compiler
|
|
optimizations. They're passed directly to the compiler commands generated by
|
|
bazel.
|
|
|
|
Additionally, [`--copt`][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`][per_file_copt] like so:
|
|
|
|
```console
|
|
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:
|
|
```console
|
|
bazel test --build_tests_only ...
|
|
```
|
|
|
|
If you want to run a specific test, say
|
|
[`pkg/noun/hashtable_tests.c`](pkg/noun/hashtable_tests.c), run:
|
|
```console
|
|
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:
|
|
```console
|
|
echo "build --copt='-O0'" >> .user.bazelrc
|
|
bazel build :urbit
|
|
```
|
|
|
|
For more information on Bazel configuration files, consult the
|
|
[Bazel docs][bazel-config].
|
|
|
|
## 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`](WORKSPACE.bazel),
|
|
[`BUILD.bazel`](BUILD.bazel), [`bazel/`](bazel), and the multiple
|
|
`BUILD.bazel` files in [`pkg/`](pkg).
|
|
|
|
[bazel]: https://bazel.build
|
|
[bazel-config]: https://bazel.build/run/bazelrc
|
|
[bazel-install]: https://bazel.build/install
|
|
[copt]: https://bazel.build/docs/user-manual#copt
|
|
[per_file_copt]: https://bazel.build/docs/user-manual#per-file-copt
|
|
[glibc]: https://www.gnu.org/software/libc
|
|
[linkopt]: https://bazel.build/docs/user-manual#linkopt
|
|
[musl libc]: https://musl.libc.org
|