1.. _hypervisor-make-options:
2
3Hypervisor Makefile Options
4###########################
5
6The ACRN hypervisor source code provides a ``Makefile`` to build the ACRN
7hypervisor binary and associated components.
8
9Assuming that you are at the top level of the ``acrn-hypervisor`` directory,
10you can run the ``make`` command to start the build. See
11:ref:`acrn_configuration_tool` for information about required input files.
12
13Build Options and Targets
14**************************
15
16The following table shows ACRN-specific command-line options:
17
18.. list-table::
19   :widths: 33 77
20   :header-rows: 1
21
22   * - Option
23     - Description
24
25   * - ``BOARD``
26     - Required. Path to the board configuration file.
27
28   * - ``SCENARIO``
29     - Required. Path to the scenario configuration file.
30
31   * - ``RELEASE``
32     - Optional. Build a release version or a debug version. Valid values
33       are ``y`` for release version or ``n`` for debug version. (Default
34       is ``n``.)
35
36   * - ``ASL_COMPILER``
37     - Optional. Specify the path to the ``iasl`` compiler on the development machine.
38       (If not provided, the default value is derived from ``which iasl``.)
39
40   * - ``O``
41     - Optional. Path to the directory where the built files will be stored.
42       (Default is the ``build`` directory.)
43
44The 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``.
45
46.. list-table::
47   :widths: 33 77
48   :header-rows: 1
49
50   * - Makefile Target
51     - Description
52
53   * - ``hypervisor``
54     - Optional. Build the hypervisor.
55
56   * - ``devicemodel``
57     - Optional. Build the Device Model. The ``tools`` will also be built as
58       a dependency.
59
60   * - ``tools``
61     - Optional. Build the tools.
62
63   * - ``doc``
64     - Optional. Build the project's HTML documentation (using Sphinx), output
65       to the ``build/doc`` folder.
66
67   * - ``life_mngr``
68     - Optional. Build the Lifecycle Manager daemon that runs in the User VM
69       to manage power state transitions (S5).
70
71   * - ``targz-pkg``
72     - Optional. Create a compressed tarball (``acrn-$(FULL_VERSION).tar.gz``)
73       in the build folder (default: ``build``) with all the build artifacts.
74
75Example of a command to build the debug version:
76
77.. code-block:: none
78
79   make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml
80
81Example of a command to build the release version:
82
83.. code-block:: none
84
85   make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml RELEASE=y
86
87Example of a command to build the release version (hypervisor only):
88
89.. code-block:: none
90
91   make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml RELEASE=y hypervisor
92
93Example of a command to build the release version of the Device Model and tools:
94
95.. code-block:: none
96
97   make RELEASE=y devicemodel tools
98
99Example of a command to put the built files in the specified directory
100(``build-nuc``):
101
102.. code-block:: none
103
104   make O=build-nuc BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml
105
106Example of a command that specifies ``iasl`` compiler:
107
108.. code-block:: none
109
110   make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml ASL_COMPILER=/usr/local/bin/iasl
111
112ACRN uses XML files to summarize board characteristics and scenario settings.
113The ``BOARD`` and ``SCENARIO`` variables accept board/scenario names as well
114as paths to XML files. When board/scenario names are given, the build system
115searches for XML files with the same names under ``misc/config_tools/data/``.
116When paths (absolute or relative) to the XML files are given, the build system
117uses the files pointed at. If relative paths are used, they are considered
118relative to the current working directory.
119
120.. _acrn_makefile_targets:
121
122Makefile Targets for Configuration
123***********************************
124
125ACRN source also includes the following makefile targets to aid customization.
126
127.. list-table::
128   :widths: 33 77
129   :header-rows: 1
130
131   * - Target
132     - Description
133
134   * - ``hvdefconfig``
135     - Generate configuration files (a bunch of C source files) in the build
136       directory without building the hypervisor. This target can be used when
137       you want to customize the configurations based on a predefined scenario.
138
139   * - ``hvshowconfig``
140     - Print the target ``BOARD``, ``SCENARIO`` and build type (debug or
141       release) of a build.
142
143   * - ``hvdiffconfig``
144     - After modifying the generated configuration files, you can use this
145       target to generate a patch that shows the differences made.
146
147   * - ``hvapplydiffconfig PATCH=/path/to/patch``
148     - Register a patch to be applied on the generated configuration files
149       every time they are regenerated. The ``PATCH`` variable specifies the
150       path (absolute or relative to current working directory) of the patch.
151       Multiple patches can be registered by invoking this target multiple
152       times.
153
154Example of ``hvshowconfig`` to query the board, scenario, and build
155type of an existing build:
156
157.. code-block:: none
158
159   $ make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml hypervisor
160   ...
161   $ make hvshowconfig
162   Build directory: /path/to/acrn-hypervisor/build/hypervisor
163   This build directory is configured with the settings below.
164   - BOARD = my_board
165   - SCENARIO = shared
166   - RELEASE = n
167
168Example of ``hvdefconfig`` to generate the configuration files in the
169build directory, followed by an example of editing one of the configuration
170files manually (``scenario.xml``) and then building the hypervisor:
171
172.. code-block:: none
173
174   make BOARD=nuc7i7dnb SCENARIO=shared hvdefconfig
175   vim build/hypervisor/.scenario.xml
176   #(Modify the XML file per your needs)
177   make
178
179A hypervisor build remembers the board and scenario previously configured.
180Thus, there is no need to duplicate ``BOARD`` and ``SCENARIO`` in the second
181``make`` above.
182
183While the scenario configuration files can be changed manually, we recommend
184you use the :ref:`ACRN Configurator tool <acrn_configurator_tool>`, which
185provides valid options and descriptions of the configuration entries.
186
187The targets ``hvdiffconfig`` and ``hvapplydiffconfig`` are provided for users
188who already have offline patches to the generated configuration files. Prior to
189v2.4, the generated configuration files are also in the repository. Some users
190may already have chosen to modify these files directly to customize the
191configurations.
192
193.. note::
194
195   We highly recommend new users save and maintain customized configurations in
196   XML, not in patches to generated configuration files.
197
198Example of how to use ``hvdiffconfig`` to generate a patch and save
199it to ``config.patch``:
200
201.. code-block:: console
202
203   acrn-hypervisor$ make BOARD=ehl-crb-b SCENARIO=hybrid_rt hvdefconfig
204   ...
205   acrn-hypervisor$ vim build/hypervisor/configs/scenarios/hybrid_rt/pci_dev.c
206   (edit the file manually)
207   acrn-hypervisor$ make hvdiffconfig
208   ...
209   Diff on generated configuration files is available at /path/to/acrn-hypervisor/build/hypervisor/config.patch.
210   To make a patch effective, use 'hvapplydiffconfig PATCH=/path/to/patch' to
211   register it to a build.
212   ...
213   acrn-hypervisor$ cp build/hypervisor/config.patch config.patch
214
215Example of how to use ``hvapplydiffconfig`` to apply
216``config.patch`` to a new build:
217
218.. code-block:: console
219
220   acrn-hypervisor$ make clean
221   acrn-hypervisor$ make BOARD=ehl-crb-b SCENARIO=hybrid_rt hvdefconfig
222   ...
223   acrn-hypervisor$ make hvapplydiffconfig PATCH=config.patch
224   ...
225   /path/to/acrn-hypervisor/config.patch is registered for build directory /path/to/acrn-hypervisor/build/hypervisor.
226   Registered patches will be applied the next time 'make' is invoked.
227   To unregister a patch, remove it from /path/to/acrn-hypervisor/build/hypervisor/configs/.diffconfig.
228   ...
229   acrn-hypervisor$ make hypervisor
230   ...
231   Applying patch /path/to/acrn-hypervisor/config.patch:
232   patching file scenarios/hybrid_rt/pci_dev.c
233   ...
234