xref: /cloud-hypervisor/docs/building.md (revision 6f8bd27cf7629733582d930519e98d19e90afb16) 
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 build-essential, git, and qemu-utils
28$ sudo apt install git build-essential qemu-utils
29# Install rust tool chain
30$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
31# If you want to build statically linked binary please add musl target
32$ rustup target add x86_64-unknown-linux-musl
33```
34
35## Clone and build
36
37First you need to clone and build the Cloud Hypervisor repository:
38
39```shell
40$ pushd $CLOUDH
41$ git clone https://github.com/cloud-hypervisor/cloud-hypervisor.git
42$ cd cloud-hypervisor
43$ cargo build --release
44
45# We need to give the cloud-hypervisor binary the NET_ADMIN capabilities for it to set TAP interfaces up on the host.
46$ sudo setcap cap_net_admin+ep ./target/release/cloud-hypervisor
47
48# If you want to build statically linked binary
49$ cargo build --release --target=x86_64-unknown-linux-musl --all
50$ popd
51```
52
53This will build a `cloud-hypervisor` binary under
54`$CLOUDH/cloud-hypervisor/target/release/cloud-hypervisor`.
55
56### Containerized builds and tests
57
58If you want to build and test Cloud Hypervisor without having to install all the
59required dependencies (The rust toolchain, cargo tools, etc), you can also use
60Cloud Hypervisor's development script: `dev_cli.sh`. Please note that upon its
61first invocation, this script will pull a fairly large container image.
62
63For example, to build the Cloud Hypervisor release binary:
64
65```shell
66$ pushd $CLOUDH
67$ cd cloud-hypervisor
68$ ./scripts/dev_cli.sh build --release
69```
70
71With `dev_cli.sh`, one can also run the Cloud Hypervisor CI locally. This can be
72very convenient for debugging CI errors without having to fully rely on the
73Cloud Hypervisor CI infrastructure.
74
75For example, to run the Cloud Hypervisor unit tests:
76
77```shell
78$ ./scripts/dev_cli.sh tests --unit
79```
80
81Run the `./scripts/dev_cli.sh --help` command to view all the supported
82development script commands and their related options.
83