mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-08-03 01:06:53 +00:00
Documentation: split the build instructions into its own guide
Split the build instructions, and the hypervisor configuration instructions into its own separate document. Tracked-On: #2154 Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This commit is contained in:
Geoffroy Van Cutsem
David Kinder
parent
c358d29c89
commit
9c97f6bec5
@ -353,249 +353,3 @@ Set up Reference UOS
|
|||||||
:align: center
|
:align: center
|
||||||
:name: gsg-successful-boot
|
:name: gsg-successful-boot
|
||||||
|
|
||||||
|
|
||||||
Build ACRN from Source
|
|
||||||
**********************
|
|
||||||
|
|
||||||
If you would like to build ACRN hypervisor and device model from source,
|
|
||||||
follow these steps.
|
|
||||||
|
|
||||||
Install build tools and dependencies
|
|
||||||
====================================
|
|
||||||
|
|
||||||
ARCN development is supported on popular Linux distributions,
|
|
||||||
each with their own way to install development tools:
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
ACRN uses ``menuconfig``, a python3 text-based user interface (TUI) for
|
|
||||||
configuring hypervisor options and using python's ``kconfiglib`` library.
|
|
||||||
|
|
||||||
* On a Clear Linux development system, install the necessary tools:
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ sudo swupd bundle-add os-clr-on-clr os-core-dev python3-basic
|
|
||||||
$ pip3 install --user kconfiglib
|
|
||||||
|
|
||||||
* On a Ubuntu/Debian development system:
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ sudo apt install gcc \
|
|
||||||
git \
|
|
||||||
make \
|
|
||||||
gnu-efi \
|
|
||||||
libssl-dev \
|
|
||||||
libpciaccess-dev \
|
|
||||||
uuid-dev \
|
|
||||||
libsystemd-dev \
|
|
||||||
libevent-dev \
|
|
||||||
libxml2-dev \
|
|
||||||
libusb-1.0-0-dev \
|
|
||||||
python3 \
|
|
||||||
python3-pip \
|
|
||||||
libblkid-dev \
|
|
||||||
e2fslibs-dev
|
|
||||||
$ sudo pip3 install kconfiglib
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
You need to use ``gcc`` version 7.3.* or higher else you will run into issue
|
|
||||||
`#1396 <https://github.com/projectacrn/acrn-hypervisor/issues/1396>`_. Follow
|
|
||||||
these instructions to install the ``gcc-7`` package on Ubuntu 16.04:
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
|
|
||||||
$ sudo apt update
|
|
||||||
$ sudo apt install g++-7 -y
|
|
||||||
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 60 \
|
|
||||||
--slave /usr/bin/g++ g++ /usr/bin/g++-7
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
Ubuntu 14.04 requires ``libsystemd-journal-dev`` instead of ``libsystemd-dev``
|
|
||||||
as indicated above.
|
|
||||||
|
|
||||||
* On a Fedora/Redhat development system:
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ sudo dnf install gcc \
|
|
||||||
git \
|
|
||||||
make \
|
|
||||||
findutils \
|
|
||||||
gnu-efi-devel \
|
|
||||||
libuuid-devel \
|
|
||||||
openssl-devel \
|
|
||||||
libpciaccess-devel \
|
|
||||||
systemd-devel \
|
|
||||||
libxml2-devel \
|
|
||||||
libevent-devel \
|
|
||||||
libusbx-devel \
|
|
||||||
python3 \
|
|
||||||
python3-pip \
|
|
||||||
libblkid-devel \
|
|
||||||
e2fsprogs-devel
|
|
||||||
$ sudo pip3 install kconfiglib
|
|
||||||
|
|
||||||
|
|
||||||
* On a CentOS development system:
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ sudo yum install gcc \
|
|
||||||
git \
|
|
||||||
make \
|
|
||||||
gnu-efi-devel \
|
|
||||||
libuuid-devel \
|
|
||||||
openssl-devel \
|
|
||||||
libpciaccess-devel \
|
|
||||||
systemd-devel \
|
|
||||||
libxml2-devel \
|
|
||||||
libevent-devel \
|
|
||||||
libusbx-devel \
|
|
||||||
python34 \
|
|
||||||
python34-pip \
|
|
||||||
libblkid-devel \
|
|
||||||
e2fsprogs-devel
|
|
||||||
$ sudo pip3 install kconfiglib
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
You may need to install `EPEL <https://fedoraproject.org/wiki/EPEL>`_ for
|
|
||||||
installing python3 via yum for CentOS 7. For CentOS 6 you need to install
|
|
||||||
pip manually. Please refer to https://pip.pypa.io/en/stable/installing for
|
|
||||||
details.
|
|
||||||
|
|
||||||
|
|
||||||
Build the hypervisor, device model and tools
|
|
||||||
============================================
|
|
||||||
|
|
||||||
The `acrn-hypervisor <https://github.com/projectacrn/acrn-hypervisor/>`_
|
|
||||||
repository has three main components in it:
|
|
||||||
|
|
||||||
1. The ACRN hypervisor code located in the ``hypervisor`` directory
|
|
||||||
#. The ACRN devicemodel code located in the ``devicemodel`` directory
|
|
||||||
#. The ACRN tools source code located in the ``tools`` directory
|
|
||||||
|
|
||||||
You can build all these components in one go as follows:
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ git clone https://github.com/projectacrn/acrn-hypervisor
|
|
||||||
$ cd acrn-hypervisor
|
|
||||||
$ make
|
|
||||||
|
|
||||||
The build results are found in the ``build`` directory.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
if you wish to use a different target folder for the build
|
|
||||||
artefacts, set the ``O`` (that is capital letter 'O') to the
|
|
||||||
desired value. Example: ``make O=build-nuc BOARD=nuc6cayh``.
|
|
||||||
|
|
||||||
Generating the documentation is described in details in the :ref:`acrn_doc`
|
|
||||||
tutorial.
|
|
||||||
|
|
||||||
You can also build these components individually. The following
|
|
||||||
steps assume that you have already cloned the ``acrn-hypervisor`` repository
|
|
||||||
and are using it as the current working directory.
|
|
||||||
|
|
||||||
#. Build the ACRN hypervisor.
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ cd hypervisor
|
|
||||||
$ make BOARD=nuc6cayh
|
|
||||||
|
|
||||||
The build results are found in the ``build`` directory.
|
|
||||||
|
|
||||||
#. Build the ACRN device model (included in the acrn-hypervisor repo):
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ cd ../devicemodel
|
|
||||||
$ make
|
|
||||||
|
|
||||||
The build results are found in the ``build`` directory.
|
|
||||||
|
|
||||||
#. Build the ACRN tools (included in the acrn-hypervisor repo):
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ cd ../tools
|
|
||||||
$ for d in */; do make -C "$d"; done
|
|
||||||
|
|
||||||
Follow the same instructions to boot and test the images you created
|
|
||||||
from your build.
|
|
||||||
|
|
||||||
Generate the hypervisor configurations
|
|
||||||
======================================
|
|
||||||
|
|
||||||
The ACRN hypervisor leverages Kconfig to manage configurations, powered by
|
|
||||||
Kconfiglib. A default configuration is generated based on the board you have
|
|
||||||
selected via the ``BOARD=`` command line parameter. You can make further
|
|
||||||
changes to that default configuration to adjust to your specific
|
|
||||||
requirements.
|
|
||||||
|
|
||||||
To generate hypervisor configurations, you need to build the hypervisor
|
|
||||||
individually. The following steps generate a default but complete configuration,
|
|
||||||
based on the platform selected, assuming that you are under the top-level
|
|
||||||
directory of acrn-hypervisor. The configuration file, named ``.config``, can be
|
|
||||||
found under the target folder of your build.
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ cd hypervisor
|
|
||||||
$ make defconfig BOARD=nuc6cayh
|
|
||||||
|
|
||||||
The BOARD specified is used to select a defconfig under
|
|
||||||
``arch/x86/configs/``. The other command-line based options (e.g. ``RELEASE``)
|
|
||||||
take no effects when generating a defconfig.
|
|
||||||
|
|
||||||
Modify the hypervisor configurations
|
|
||||||
====================================
|
|
||||||
|
|
||||||
To modify the hypervisor configurations, you can either edit ``.config``
|
|
||||||
manually, or invoke a TUI-based menuconfig, powered by kconfiglib, by executing
|
|
||||||
``make menuconfig``. As an example, the following commands, assuming that you
|
|
||||||
are under the top-level directory of acrn-hypervisor, generate a default
|
|
||||||
configuration file for UEFI, allow you to modify some configurations and build
|
|
||||||
the hypervisor using the updated ``.config``.
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ cd hypervisor
|
|
||||||
$ make defconfig BOARD=nuc6cayh
|
|
||||||
$ make menuconfig # Modify the configurations per your needs
|
|
||||||
$ make # Build the hypervisor with the new .config
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
Menuconfig is python3 only.
|
|
||||||
|
|
||||||
Refer to the help on menuconfig for a detailed guide on the interface.
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ pydoc3 menuconfig
|
|
||||||
|
|
||||||
Create a new default configuration
|
|
||||||
==================================
|
|
||||||
|
|
||||||
Currently the ACRN hypervisor looks for default configurations under
|
|
||||||
``hypervisor/arch/x86/configs/<BOARD>.config``, where ``<BOARD>`` is the
|
|
||||||
specified platform. The following steps allow you to create a defconfig for
|
|
||||||
another platform based on a current one.
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ cd hypervisor
|
|
||||||
$ make defconfig BOARD=nuc6cayh
|
|
||||||
$ make menuconfig # Modify the configurations
|
|
||||||
$ make savedefconfig # The minimized config reside at build/defconfig
|
|
||||||
$ cp build/defconfig arch/x86/configs/xxx.config
|
|
||||||
|
|
||||||
Then you can re-use that configuration by passing the name (``xxx`` in the
|
|
||||||
example above) to 'BOARD=':
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
$ make defconfig BOARD=xxx
|
|
||||||
|
|
||||||
|
|||||||
221
doc/getting-started/building-from-source.rst
Normal file
221
doc/getting-started/building-from-source.rst
Normal file
@ -0,0 +1,221 @@
|
|||||||
|
.. _getting-started-building:
|
||||||
|
|
||||||
|
Build ACRN from Source
|
||||||
|
######################
|
||||||
|
|
||||||
|
If you would like to build the ACRN hypervisor, device model, and tools from
|
||||||
|
source, follow these steps.
|
||||||
|
|
||||||
|
Install build tools and dependencies
|
||||||
|
************************************
|
||||||
|
|
||||||
|
ARCN development is supported on popular Linux distributions,
|
||||||
|
each with their own way to install development tools:
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
ACRN uses ``menuconfig``, a python3 text-based user interface (TUI) for
|
||||||
|
configuring hypervisor options and using python's ``kconfiglib`` library.
|
||||||
|
|
||||||
|
* On a Clear Linux development system, install the necessary tools:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ sudo swupd bundle-add os-clr-on-clr os-core-dev python3-basic
|
||||||
|
$ pip3 install --user kconfiglib
|
||||||
|
|
||||||
|
* On a Ubuntu/Debian development system:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ sudo apt install gcc \
|
||||||
|
git \
|
||||||
|
make \
|
||||||
|
gnu-efi \
|
||||||
|
libssl-dev \
|
||||||
|
libpciaccess-dev \
|
||||||
|
uuid-dev \
|
||||||
|
libsystemd-dev \
|
||||||
|
libevent-dev \
|
||||||
|
libxml2-dev \
|
||||||
|
libusb-1.0-0-dev \
|
||||||
|
python3 \
|
||||||
|
python3-pip \
|
||||||
|
libblkid-dev \
|
||||||
|
e2fslibs-dev
|
||||||
|
$ sudo pip3 install kconfiglib
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
You need to use ``gcc`` version 7.3.* or higher else you will run into issue
|
||||||
|
`#1396 <https://github.com/projectacrn/acrn-hypervisor/issues/1396>`_. Follow
|
||||||
|
these instructions to install the ``gcc-7`` package on Ubuntu 16.04:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
|
||||||
|
$ sudo apt update
|
||||||
|
$ sudo apt install g++-7 -y
|
||||||
|
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 60 \
|
||||||
|
--slave /usr/bin/g++ g++ /usr/bin/g++-7
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
Ubuntu 14.04 requires ``libsystemd-journal-dev`` instead of ``libsystemd-dev``
|
||||||
|
as indicated above.
|
||||||
|
|
||||||
|
* On a Fedora/Redhat development system:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ sudo dnf install gcc \
|
||||||
|
git \
|
||||||
|
make \
|
||||||
|
findutils \
|
||||||
|
gnu-efi-devel \
|
||||||
|
libuuid-devel \
|
||||||
|
openssl-devel \
|
||||||
|
libpciaccess-devel \
|
||||||
|
systemd-devel \
|
||||||
|
libxml2-devel \
|
||||||
|
libevent-devel \
|
||||||
|
libusbx-devel \
|
||||||
|
python3 \
|
||||||
|
python3-pip \
|
||||||
|
libblkid-devel \
|
||||||
|
e2fsprogs-devel
|
||||||
|
$ sudo pip3 install kconfiglib
|
||||||
|
|
||||||
|
|
||||||
|
* On a CentOS development system:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ sudo yum install gcc \
|
||||||
|
git \
|
||||||
|
make \
|
||||||
|
gnu-efi-devel \
|
||||||
|
libuuid-devel \
|
||||||
|
openssl-devel \
|
||||||
|
libpciaccess-devel \
|
||||||
|
systemd-devel \
|
||||||
|
libxml2-devel \
|
||||||
|
libevent-devel \
|
||||||
|
libusbx-devel \
|
||||||
|
python34 \
|
||||||
|
python34-pip \
|
||||||
|
libblkid-devel \
|
||||||
|
e2fsprogs-devel
|
||||||
|
$ sudo pip3 install kconfiglib
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
You may need to install `EPEL <https://fedoraproject.org/wiki/EPEL>`_ for
|
||||||
|
installing python3 via yum for CentOS 7. For CentOS 6 you need to install
|
||||||
|
pip manually. Please refer to https://pip.pypa.io/en/stable/installing for
|
||||||
|
details.
|
||||||
|
|
||||||
|
|
||||||
|
Build the hypervisor, device model and tools
|
||||||
|
********************************************
|
||||||
|
|
||||||
|
The `acrn-hypervisor <https://github.com/projectacrn/acrn-hypervisor/>`_
|
||||||
|
repository has four main components in it:
|
||||||
|
|
||||||
|
1. The ACRN hypervisor code located in the ``hypervisor`` directory
|
||||||
|
#. The EFI stub code located in the ``efi-stub`` directory
|
||||||
|
#. The ACRN devicemodel code located in the ``devicemodel`` directory
|
||||||
|
#. The ACRN tools source code located in the ``tools`` directory
|
||||||
|
|
||||||
|
You can build all these components in one go as follows:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ git clone https://github.com/projectacrn/acrn-hypervisor
|
||||||
|
$ cd acrn-hypervisor
|
||||||
|
$ make
|
||||||
|
|
||||||
|
The build results are found in the ``build`` directory.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
if you wish to use a different target folder for the build
|
||||||
|
artefacts, set the ``O`` (that is capital letter 'O') to the
|
||||||
|
desired value. Example: ``make O=build-nuc BOARD=nuc6cayh``.
|
||||||
|
|
||||||
|
Generating the documentation is described in details in the :ref:`acrn_doc`
|
||||||
|
tutorial.
|
||||||
|
|
||||||
|
Follow the same instructions to boot and test the images you created
|
||||||
|
from your build.
|
||||||
|
|
||||||
|
.. _getting-started-hypervisor-configuration:
|
||||||
|
|
||||||
|
Configuring the hypervisor
|
||||||
|
**************************
|
||||||
|
|
||||||
|
The ACRN hypervisor leverages Kconfig to manage configurations, powered by
|
||||||
|
Kconfiglib. A default configuration is generated based on the board you have
|
||||||
|
selected via the ``BOARD=`` command line parameter. You can make further
|
||||||
|
changes to that default configuration to adjust to your specific
|
||||||
|
requirements.
|
||||||
|
|
||||||
|
To generate hypervisor configurations, you need to build the hypervisor
|
||||||
|
individually. The following steps generate a default but complete configuration,
|
||||||
|
based on the platform selected, assuming that you are under the top-level
|
||||||
|
directory of acrn-hypervisor. The configuration file, named ``.config``, can be
|
||||||
|
found under the target folder of your build.
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ cd hypervisor
|
||||||
|
$ make defconfig BOARD=nuc6cayh
|
||||||
|
|
||||||
|
The BOARD specified is used to select a defconfig under
|
||||||
|
``arch/x86/configs/``. The other command-line based options (e.g. ``RELEASE``)
|
||||||
|
take no effects when generating a defconfig.
|
||||||
|
|
||||||
|
Modify the hypervisor configurations
|
||||||
|
************************************
|
||||||
|
|
||||||
|
To modify the hypervisor configurations, you can either edit ``.config``
|
||||||
|
manually, or invoke a TUI-based menuconfig, powered by kconfiglib, by executing
|
||||||
|
``make menuconfig``. As an example, the following commands, assuming that you
|
||||||
|
are under the top-level directory of acrn-hypervisor, generate a default
|
||||||
|
configuration file for UEFI, allow you to modify some configurations and build
|
||||||
|
the hypervisor using the updated ``.config``.
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ cd hypervisor
|
||||||
|
$ make defconfig BOARD=nuc6cayh
|
||||||
|
$ make menuconfig # Modify the configurations per your needs
|
||||||
|
$ make # Build the hypervisor with the new .config
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
Menuconfig is python3 only.
|
||||||
|
|
||||||
|
Refer to the help on menuconfig for a detailed guide on the interface.
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ pydoc3 menuconfig
|
||||||
|
|
||||||
|
Create a new default configuration
|
||||||
|
**********************************
|
||||||
|
|
||||||
|
Currently the ACRN hypervisor looks for default configurations under
|
||||||
|
``hypervisor/arch/x86/configs/<BOARD>.config``, where ``<BOARD>`` is the
|
||||||
|
specified platform. The following steps allow you to create a defconfig for
|
||||||
|
another platform based on a current one.
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ cd hypervisor
|
||||||
|
$ make defconfig BOARD=nuc6cayh
|
||||||
|
$ make menuconfig # Modify the configurations
|
||||||
|
$ make savedefconfig # The minimized config reside at build/defconfig
|
||||||
|
$ cp build/defconfig arch/x86/configs/xxx.config
|
||||||
|
|
||||||
|
Then you can re-use that configuration by passing the name (``xxx`` in the
|
||||||
|
example above) to 'BOARD=':
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
$ make defconfig BOARD=xxx
|
||||||
|
|
||||||
@ -19,3 +19,4 @@ described in :ref:`hardware`. Follow the setup guides listed here:
|
|||||||
|
|
||||||
apl-nuc.rst
|
apl-nuc.rst
|
||||||
up2.rst
|
up2.rst
|
||||||
|
building-from-source.rst
|
||||||
|
|||||||
@ -159,6 +159,11 @@ Enable partition mode in ACRN hypervisor
|
|||||||
.. figure:: images/menuconfig-partition-mode.png
|
.. figure:: images/menuconfig-partition-mode.png
|
||||||
:align: center
|
:align: center
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Refer to the :ref:`getting-started-building` for more information on how
|
||||||
|
to install all the ACRN build dependencies.
|
||||||
|
|
||||||
#. Configure the PCI device info for each VM
|
#. Configure the PCI device info for each VM
|
||||||
|
|
||||||
PCI devices that are available to the privileged VMs
|
PCI devices that are available to the privileged VMs
|
||||||
|
|||||||
@ -43,7 +43,7 @@ the source code, build it, and install it on your device.
|
|||||||
|
|
||||||
1. Install the build tools and dependencies
|
1. Install the build tools and dependencies
|
||||||
|
|
||||||
Follow the instructions found in the :ref:`getting-started-apl-nuc` to
|
Follow the instructions found in the :ref:`getting-started-building` to
|
||||||
install all the build tools and dependencies on your system.
|
install all the build tools and dependencies on your system.
|
||||||
|
|
||||||
#. Clone the `Project ACRN <https://github.com/projectacrn/acrn-hypervisor>`_
|
#. Clone the `Project ACRN <https://github.com/projectacrn/acrn-hypervisor>`_
|
||||||
@ -70,7 +70,7 @@ the source code, build it, and install it on your device.
|
|||||||
make PLATFORM=uefi
|
make PLATFORM=uefi
|
||||||
sudo make install
|
sudo make install
|
||||||
|
|
||||||
For more details, please refer to the :ref:`getting-started-apl-nuc`.
|
For more details, please refer to the :ref:`getting-started-building`.
|
||||||
|
|
||||||
#. Install the hypervisor
|
#. Install the hypervisor
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user