xref: /cloud-hypervisor/docs/building.md (revision aaf67c9ae4ae5249ae05247f060fd98f3ded5b7f) 
1- [Building Cloud Hypervisor](#building-cloud-hypervisor)
2  - [Preparation](#preparation)
3  - [Install prerequisites](#install-prerequisites)
4  - [Clone and build](#clone-and-build)
5    - [Containerized builds and tests](#containerized-builds-and-tests)
6
7# Building Cloud Hypervisor
8
9We recommend users use the pre-built binaries that are mentioned in the README.md file in the root of the repository. Building from source is only necessary if you wish to make modifications.
10
11## Preparation
12
13We create a folder to build and run `cloud-hypervisor` at `$HOME/cloud-hypervisor`
14
15```shell
16$ export CLOUDH=$HOME/cloud-hypervisor
17$ mkdir $CLOUDH
18```
19
20## Install prerequisites
21
22You need to install some prerequisite packages in order to build and test Cloud
23Hypervisor. Here, all the steps are based on Ubuntu, for other Linux
24distributions please replace the package manager and package name.
25
26```shell
27# Install basic packages needed. For a package list targeting for more
28# functionalities for example the test, please see resources/Dockerfile.
29$ sudo apt-get update
30$ sudo apt install git build-essential m4 bison flex uuid-dev qemu-utils musl-tools
31# Install rust tool chain
32$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
33# If you want to build statically linked binary please add musl target
34$ rustup target add x86_64-unknown-linux-musl  # x86-64
35$ rustup target add aarch64-unknown-linux-musl # AArch64
36```
37
38## Clone and build
39
40First you need to clone and build the Cloud Hypervisor repository:
41
42```shell
43$ pushd $CLOUDH
44$ git clone https://github.com/cloud-hypervisor/cloud-hypervisor.git
45$ cd cloud-hypervisor
46$ cargo build --release
47
48# We need to give the cloud-hypervisor binary the NET_ADMIN capabilities for it to set TAP interfaces up on the host.
49$ sudo setcap cap_net_admin+ep ./target/release/cloud-hypervisor
50
51# If you want to build statically linked binary
52$ cargo build --release --target=x86_64-unknown-linux-musl --all  # x86-64
53$ cargo build --release --target=aarch64-unknown-linux-musl --all # AArch64
54$ popd
55```
56
57This will build a `cloud-hypervisor` binary under
58`$CLOUDH/cloud-hypervisor/target/release/cloud-hypervisor`.
59
60### Containerized builds and tests
61
62If you want to build and test Cloud Hypervisor without having to install all the
63required dependencies (The rust toolchain, cargo tools, etc), you can also use
64Cloud Hypervisor's development script: `dev_cli.sh`. Please note that upon its
65first invocation, this script will pull a fairly large container image.
66
67For example, to build the Cloud Hypervisor release binary:
68
69```shell
70$ pushd $CLOUDH
71$ cd cloud-hypervisor
72$ ./scripts/dev_cli.sh build --release
73```
74
75With `dev_cli.sh`, one can also run the Cloud Hypervisor CI locally. This can be
76very convenient for debugging CI errors without having to fully rely on the
77Cloud Hypervisor CI infrastructure.
78
79For example, to run the Cloud Hypervisor unit tests:
80
81```shell
82$ ./scripts/dev_cli.sh tests --unit
83```
84
85Run the `./scripts/dev_cli.sh --help` command to view all the supported
86development script commands and their related options.
87