From 9c97f6bec5352d58775a3a6635b7ccf198a691e8 Mon Sep 17 00:00:00 2001 From: Geoffroy Van Cutsem Date: Fri, 21 Dec 2018 17:00:13 +0100 Subject: [PATCH] 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 --- doc/getting-started/apl-nuc.rst | 246 ------------------ doc/getting-started/building-from-source.rst | 221 ++++++++++++++++ doc/getting-started/index.rst | 1 + doc/tutorials/using_partition_mode_on_up2.rst | 5 + doc/tutorials/using_ubuntu_as_sos.rst | 4 +- 5 files changed, 229 insertions(+), 248 deletions(-) create mode 100644 doc/getting-started/building-from-source.rst diff --git a/doc/getting-started/apl-nuc.rst b/doc/getting-started/apl-nuc.rst index dd40e99a9..3c6e16af9 100644 --- a/doc/getting-started/apl-nuc.rst +++ b/doc/getting-started/apl-nuc.rst @@ -353,249 +353,3 @@ Set up Reference UOS :align: center :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 `_. 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 `_ 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 `_ -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/.config``, where ```` 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 - diff --git a/doc/getting-started/building-from-source.rst b/doc/getting-started/building-from-source.rst new file mode 100644 index 000000000..9d487f39d --- /dev/null +++ b/doc/getting-started/building-from-source.rst @@ -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 `_. 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 `_ 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 `_ +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/.config``, where ```` 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 + diff --git a/doc/getting-started/index.rst b/doc/getting-started/index.rst index 41207f479..3137aea4e 100644 --- a/doc/getting-started/index.rst +++ b/doc/getting-started/index.rst @@ -19,3 +19,4 @@ described in :ref:`hardware`. Follow the setup guides listed here: apl-nuc.rst up2.rst + building-from-source.rst diff --git a/doc/tutorials/using_partition_mode_on_up2.rst b/doc/tutorials/using_partition_mode_on_up2.rst index 13a007420..e672f5243 100644 --- a/doc/tutorials/using_partition_mode_on_up2.rst +++ b/doc/tutorials/using_partition_mode_on_up2.rst @@ -159,6 +159,11 @@ Enable partition mode in ACRN hypervisor .. figure:: images/menuconfig-partition-mode.png :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 PCI devices that are available to the privileged VMs diff --git a/doc/tutorials/using_ubuntu_as_sos.rst b/doc/tutorials/using_ubuntu_as_sos.rst index 3a3350a22..9183ef3ab 100644 --- a/doc/tutorials/using_ubuntu_as_sos.rst +++ b/doc/tutorials/using_ubuntu_as_sos.rst @@ -43,7 +43,7 @@ the source code, build it, and install it on your device. 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. #. Clone the `Project ACRN `_ @@ -70,7 +70,7 @@ the source code, build it, and install it on your device. make PLATFORM=uefi 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