Hypervisor Makefile Options¶

The ACRN hypervisor source code provides a Makefile to build the ACRN hypervisor binary and associated components.

Assuming that you are at the top level of the acrn-hypervisor directory, you can run the make command to start the build. See Introduction to ACRN Configuration for information about required input files.

Build Options and Targets¶

The following table shows ACRN-specific command-line options:

Option	Description
`BOARD`	Required. Path to the board configuration file.
`SCENARIO`	Required. Path to the scenario configuration file.
`RELEASE`	Optional. Build a release version or a debug version. Valid values are `y` for release version or `n` for debug version. (Default is `n`.)
`ASL_COMPILER`	Optional. Specify the path to the `iasl` compiler on the development machine. (If not provided, the default value is derived from `which iasl`.)
`O`	Optional. Path to the directory where the built files will be stored. (Default is the `build` directory.)

The following table shows ACRN-specific targets. The default target (if no target is specified on the command-line) is to build the hypervisor, devicemodel, and tools.

Makefile Target	Description
`hypervisor`	Optional. Build the hypervisor.
`devicemodel`	Optional. Build the Device Model. The `tools` will also be built as a dependency.
`tools`	Optional. Build the tools.
`doc`	Optional. Build the project’s HTML documentation (using Sphinx), output to the `build/doc` folder.
`life_mngr`	Optional. Build the Lifecycle Manager daemon that runs in the User VM to manage power state transitions (S5).
`targz-pkg`	Optional. Create a compressed tarball (`acrn-$(FULL_VERSION).tar.gz`) in the build folder (default: `build`) with all the build artifacts.

Example of a command to build the debug version:

make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml

Example of a command to build the release version:

make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml RELEASE=y

Example of a command to build the release version (hypervisor only):

make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml RELEASE=y hypervisor

Example of a command to build the release version of the Device Model and tools:

make RELEASE=y devicemodel tools

Example of a command to put the built files in the specified directory (build-nuc):

make O=build-nuc BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml

Example of a command that specifies iasl compiler:

make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml ASL_COMPILER=/usr/local/bin/iasl

ACRN uses XML files to summarize board characteristics and scenario settings. The BOARD and SCENARIO variables accept board/scenario names as well as paths to XML files. When board/scenario names are given, the build system searches for XML files with the same names under misc/config_tools/data/. When paths (absolute or relative) to the XML files are given, the build system uses the files pointed at. If relative paths are used, they are considered relative to the current working directory.

Makefile Targets for Configuration¶

ACRN source also includes the following makefile targets to aid customization.

Target	Description
`hvdefconfig`	Generate configuration files (a bunch of C source files) in the build directory without building the hypervisor. This target can be used when you want to customize the configurations based on a predefined scenario.
`hvshowconfig`	Print the target `BOARD`, `SCENARIO` and build type (debug or release) of a build.
`hvdiffconfig`	After modifying the generated configuration files, you can use this target to generate a patch that shows the differences made.
`hvapplydiffconfig PATCH=/path/to/patch`	Register a patch to be applied on the generated configuration files every time they are regenerated. The `PATCH` variable specifies the path (absolute or relative to current working directory) of the patch. Multiple patches can be registered by invoking this target multiple times.

Example of hvshowconfig to query the board, scenario, and build type of an existing build:

$ make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml hypervisor
...
$ make hvshowconfig
Build directory: /path/to/acrn-hypervisor/build/hypervisor
This build directory is configured with the settings below.
- BOARD = my_board
- SCENARIO = shared
- RELEASE = n

Example of hvdefconfig to generate the configuration files in the build directory, followed by an example of editing one of the configuration files manually (scenario.xml) and then building the hypervisor:

make BOARD=nuc7i7dnb SCENARIO=shared hvdefconfig
vim build/hypervisor/.scenario.xml
#(Modify the XML file per your needs)
make

A hypervisor build remembers the board and scenario previously configured. Thus, there is no need to duplicate BOARD and SCENARIO in the second make above.

While the scenario configuration files can be changed manually, we recommend you use the ACRN Configurator tool, which provides valid options and descriptions of the configuration entries.

The targets hvdiffconfig and hvapplydiffconfig are provided for users who already have offline patches to the generated configuration files. Prior to v2.4, the generated configuration files are also in the repository. Some users may already have chosen to modify these files directly to customize the configurations.

Note

We highly recommend new users save and maintain customized configurations in XML, not in patches to generated configuration files.

Example of how to use hvdiffconfig to generate a patch and save it to config.patch:

acrn-hypervisor$ make BOARD=ehl-crb-b SCENARIO=hybrid_rt hvdefconfig
...
acrn-hypervisor$ vim build/hypervisor/configs/scenarios/hybrid_rt/pci_dev.c
(edit the file manually)
acrn-hypervisor$ make hvdiffconfig
...
Diff on generated configuration files is available at /path/to/acrn-hypervisor/build/hypervisor/config.patch.
To make a patch effective, use 'hvapplydiffconfig PATCH=/path/to/patch' to
register it to a build.
...
acrn-hypervisor$ cp build/hypervisor/config.patch config.patch

Example of how to use hvapplydiffconfig to apply config.patch to a new build:

acrn-hypervisor$ make clean
acrn-hypervisor$ make BOARD=ehl-crb-b SCENARIO=hybrid_rt hvdefconfig
...
acrn-hypervisor$ make hvapplydiffconfig PATCH=config.patch
...
/path/to/acrn-hypervisor/config.patch is registered for build directory /path/to/acrn-hypervisor/build/hypervisor.
Registered patches will be applied the next time 'make' is invoked.
To unregister a patch, remove it from /path/to/acrn-hypervisor/build/hypervisor/configs/.diffconfig.
...
acrn-hypervisor$ make hypervisor
...
Applying patch /path/to/acrn-hypervisor/config.patch:
patching file scenarios/hybrid_rt/pci_dev.c
...