doc: update debian packaging documentation
Update the draft content about Debian packaging with something more user friendly and complete. I removed the version of the release.json included in the doc and instead just include the release.json file directly. I added comments about the configuration parameters directly in the release.json file, using the convention already being used there. (If we updated the json python package being used to json5, the release.json file could include comments using // convention and things would look a bit cleaner.) Tracked-On: #5022 Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
parent
288efd31b4
commit
187b552440
|
|
@ -1,128 +1,231 @@
|
||||||
.. _ubuntu_sos:
|
.. _debian_packaging:
|
||||||
|
|
||||||
ubuntu_sos
|
ACRN Installation via Debian Packages
|
||||||
##########
|
#####################################
|
||||||
|
|
||||||
Description
|
Debian packages provide a simple way to build and package a collection
|
||||||
***********
|
of ACRN configurations on a development system, based on a set of
|
||||||
this scripts show how to build acrn-hypervisor and acrn-kernel deb package
|
hardware platforms and scenario choices. You can then copy the packages
|
||||||
|
onto your target platform, select a particular configuration and reboot
|
||||||
|
the system with ACRN and an Ubuntu Service VM up and running.
|
||||||
|
|
||||||
1. setup native ubuntu 18.04
|
Follow these instructions to build Debian packages for the acrn-hypervisor and
|
||||||
=============================
|
acrn-kernel, install them on your target system, and boot running ACRN.
|
||||||
Base on GEO; config your proxy
|
|
||||||
|
|
||||||
.. code-block:: none
|
.. rst-class:: numbered-step
|
||||||
|
|
||||||
sudo apt install python3
|
Set up Pre-requisites
|
||||||
|
*********************
|
||||||
|
|
||||||
sudo su
|
Your development system should be running Ubuntu
|
||||||
|
18.04 and be connected to the internet. (You'll be installing software
|
||||||
|
with ``apt`` and from Pypi and downloading ACRN software from
|
||||||
|
GitHub.)
|
||||||
|
|
||||||
|
It's likely you've already got python3 on your system, but we can make
|
||||||
|
sure by installing it with::
|
||||||
|
|
||||||
|
sudo apt install python3
|
||||||
|
|
||||||
|
All of the Debian packaging work is handled by a script found in the
|
||||||
|
ACRN GitHub repo. If you don't have it downloaded already, clone the
|
||||||
|
ACRN repo with::
|
||||||
|
|
||||||
|
git clone https://github.com/projectacrn/acrn-hypervisor.git
|
||||||
|
|
||||||
|
All the configuration files and scripts to build the Debian packages are
|
||||||
|
in the ``misc/packaging`` folder, so let's go there::
|
||||||
|
|
||||||
|
cd acrn-hypervisor/misc/packaging
|
||||||
|
|
||||||
|
|
||||||
2. config release.json file
|
.. rst-class:: numbered-step
|
||||||
============================
|
|
||||||
below is explanation for items in release.json,please change item accordingly,if do not change means go with default value
|
|
||||||
|
|
||||||
.. code-block:: none
|
Configure Debian packaging details
|
||||||
|
**********************************
|
||||||
|
|
||||||
{
|
The build and packaging script ``install_uSoS.py`` does all the work to
|
||||||
|
build and make the Debian packages. You configure what the script does
|
||||||
|
by editing its configuration file, ``release.json``. Comments in the
|
||||||
|
JSON file document how you can adjust things to your specific needs. For
|
||||||
|
example, the default ``release.json`` file builds for all three default
|
||||||
|
ACRN configurations (industry, hybrid, and logical_partition) and for
|
||||||
|
two supported boards (nuc717dnb and whl-ipc-i5).
|
||||||
|
|
||||||
"//":"release ubuntu as sos verion",
|
.. important:: In the current implementation of this packaging script, if you
|
||||||
|
change the ``release.json`` boards configuration choices, you'll also need to
|
||||||
|
manually update the ``acrn-hypervisor.postinst`` script to match.
|
||||||
|
|
||||||
"install_package":"true",---------->this 1st time should set to true if you did not install acrn related compile package, if already install,set to false
|
Here's the default ``release.json`` configuration:
|
||||||
|
|
||||||
"gcc_version":"7.3.0",---------->gcc version should higher than 7.3.0
|
.. literalinclude:: release.json
|
||||||
|
|
||||||
"binutils":"2.27",---------->binutils version should higher than 2.27
|
|
||||||
|
|
||||||
"//":"acrn-hypervisor config",
|
|
||||||
|
|
||||||
"build_acrn":"true",---------->if you need build acrn-hypervisor set to true
|
|
||||||
|
|
||||||
"sync_acrn_code":"true",---------->if you need sync acrn-hypervisor code set to true
|
|
||||||
|
|
||||||
"acrn_repo":"https://github.com/projectacrn/acrn-hypervisor.git",---------->acrn repo
|
|
||||||
|
|
||||||
"release_version":"remotes/origin/release_2.0",---------->acrn release branch
|
|
||||||
|
|
||||||
"acrn_deb_package":"true",---------->if you need create acrn-hypervison deb set to true
|
|
||||||
|
|
||||||
"install_acrn_deb":"false",---------->if you need install acrn-hypervisor deb set to true
|
|
||||||
|
|
||||||
"build_cmd":---------->acrn-hypervisor build command must include scenario and board info and release type
|
|
||||||
|
|
||||||
{
|
|
||||||
|
|
||||||
"scenario":
|
|
||||||
|
|
||||||
{
|
|
||||||
|
|
||||||
"industry":"true",
|
|
||||||
|
|
||||||
"hybrid":"true",
|
|
||||||
|
|
||||||
"logical_partition":"true"
|
|
||||||
|
|
||||||
|
|
||||||
},
|
.. rst-class:: numbered-step
|
||||||
|
|
||||||
"board":
|
Run the package-building script
|
||||||
|
*******************************
|
||||||
|
|
||||||
{
|
The ``install_uSoS.py`` python script does all the work to install
|
||||||
|
needed tools (such as make, gnu-efi, libssl-dev, libpciaccess-dev,
|
||||||
|
uuid-dev, and more). It also verifies that tool versions (such as the
|
||||||
|
gcc compiler) are appropriate (as configured in the ``release.json``
|
||||||
|
file).
|
||||||
|
|
||||||
"nuc7i7dnb":"true",
|
The script runs without further user input, and must be run with
|
||||||
|
``sudo``::
|
||||||
|
|
||||||
"whl-ipc-i5":"true"
|
sudo python3 install_uSoS.py
|
||||||
|
|
||||||
},
|
With the default ``release.json`` configuration, this script will run
|
||||||
|
for about 30 minutes, but could take longer depending on your internet
|
||||||
|
speed (for downloading files) and overall computer performance (for
|
||||||
|
compiling the Linux kernel, ACRN hypervisor, and ACRN tools).
|
||||||
|
|
||||||
"release":"0"---------->0 means debug version,1 means release version
|
When done, it creates two Debian packages:
|
||||||
|
|
||||||
},
|
* ``acrn_deb_package.deb`` with the ACRN hypervisor and tools built
|
||||||
|
for each configuration combination, and
|
||||||
|
* ``acrn_kernel_deb_package.deb`` with the ACRN-patched Linux kernel.
|
||||||
|
|
||||||
"//":"kernel config",
|
You'll need to copy these two files onto your target system, either via
|
||||||
|
the network or simply by using a thumbdrive.
|
||||||
"build_acrn_kernel":"true",---------->if you need build acrn-kernel set to true
|
|
||||||
|
|
||||||
"sync_acrn_kernel_code":"true",---------->if you need sync acrn-kernel code set to true
|
|
||||||
|
|
||||||
"kernel_release_version":"remotes/origin/release_2.0",---------->acrn kernel release branch
|
|
||||||
|
|
||||||
|
|
||||||
"sos_kernel_repo":"https://github.com/projectacrn/acrn-kernel.git",---------->acrn kernel repo
|
.. rst-class:: numbered-step
|
||||||
|
|
||||||
|
Prepare your target system with Ubuntu 18.04
|
||||||
|
********************************************
|
||||||
|
|
||||||
|
Your target system must be one of the choices listed in the ``release.json``
|
||||||
|
file and should be running Ubuntu 18.04. Make sure it's updated using the
|
||||||
|
commands::
|
||||||
|
|
||||||
|
sudo apt update
|
||||||
|
sudo apt upgrade
|
||||||
|
|
||||||
|
Reboot your system to complete the installation.
|
||||||
|
|
||||||
|
.. rst-class:: numbered-step
|
||||||
|
|
||||||
|
Install Debian packages on your target system
|
||||||
|
*********************************************
|
||||||
|
|
||||||
|
Copy the Debian packages you created on your development system, for
|
||||||
|
example, using a thumbdrive. Then install the ACRN Debian package::
|
||||||
|
|
||||||
|
sudo dpkg -i acrn_deb_package.deb
|
||||||
|
|
||||||
|
Make your choices for scenario, board, and which disk to use,
|
||||||
|
for example, this selects the industry scenario, nuc7i7dnb board, and
|
||||||
|
installation on the NVMe drive (input is highlighted):
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
:emphasize-lines: 11, 16, 23
|
||||||
|
|
||||||
|
Selecting previously unselected package acrn-package.
|
||||||
|
(Reading database ... 163871 files and directories currently installed.)
|
||||||
|
Preparing to unpack acrn_deb_package.deb...
|
||||||
|
Unpacking acrn-package (2020-07-17) ...
|
||||||
|
Setting up acrn-package (2020-07-17) ...
|
||||||
|
please choose <scenario> ,<board> ,<disk type>
|
||||||
|
Scenario is ->
|
||||||
|
1. industry
|
||||||
|
2. hybrid
|
||||||
|
3. logical_partition
|
||||||
|
1
|
||||||
|
Scenario is industry
|
||||||
|
Board is ->
|
||||||
|
1. nuc7i7dnb
|
||||||
|
2. whl-ipc-i5
|
||||||
|
1
|
||||||
|
Board is nuc7i7dnb
|
||||||
|
Your acrn bin is ->
|
||||||
|
/boot/acrn.industry.nuc7i7dnb.bin
|
||||||
|
disk type is ->
|
||||||
|
1. nvme
|
||||||
|
2. sda
|
||||||
|
1
|
||||||
|
disk type is nvme
|
||||||
|
Sourcing file '/etc/default/grub'
|
||||||
|
Generating grub configuration file ...
|
||||||
|
Found linux image: /boot/vmlinuz-5.3.0-62-generic
|
||||||
|
Found initrd image: /boot/initrd.img-5.3.0-62-generic
|
||||||
|
Found linux image: /boot/vmlinuz-5.3.0-28-generic
|
||||||
|
Found initrd image: /boot/initrd.img-5.3.0-28-generic
|
||||||
|
Added boot menu entry for EFI firmware configuration
|
||||||
|
done
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
"acrn_kernel_deb_package":"true",---------->if you need create acrn-kernel deb set to true
|
Then install the ACRN-patched kernel package::
|
||||||
|
|
||||||
"install_acrn_kernel_deb":"false",---------->if you need install acrn-kernel deb set to true
|
sudo dpkg -i acrn_kernel_deb_package.deb
|
||||||
|
|
||||||
"//":"misc",
|
After that, you're ready to reboot.
|
||||||
|
|
||||||
"auto_reboot":"false"---------->if you need reboot set to true
|
.. rst-class:: numbered-step
|
||||||
|
|
||||||
}
|
Boot ACRN using the multiboot2 grub choice
|
||||||
|
******************************************
|
||||||
|
|
||||||
3.python3 install_uSoS.py
|
This time when you boot your target system you'll see some new options:
|
||||||
=========================
|
|
||||||
after finished , will get below two item
|
|
||||||
|
|
||||||
acrn_deb_package.deb
|
.. code-block:: console
|
||||||
|
:emphasize-lines: 4
|
||||||
|
|
||||||
acrn_kernel_deb_package.deb
|
Ubuntu
|
||||||
|
Advanced options for Ubuntu
|
||||||
|
System setup
|
||||||
|
*ACRN multiboot2
|
||||||
|
ACRN efi
|
||||||
|
|
||||||
|
If your target system has a serial port active, you can simply hit
|
||||||
|
:kbd:`return` (or wait for the timeout) to boot with this
|
||||||
|
``ACRN multiboot2`` choice.
|
||||||
|
|
||||||
|
.. important:: If you don't have an active serial port, you'll need to
|
||||||
|
edit the grub configuration a bit by pressing :kbd:`e` (for edit) and
|
||||||
|
remove the ``i915.modeset=0 video=efifb:off`` parameters at the end of
|
||||||
|
the multiboot2 grub command:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
:emphasize-lines: 8
|
||||||
|
|
||||||
|
setparams 'ACRN multiboot2 '
|
||||||
|
|
||||||
|
load_video
|
||||||
|
insmod gzio
|
||||||
|
insmod part_gpt
|
||||||
|
insmod ext2
|
||||||
|
search --no-floppy --fs-uuid --set $uuid
|
||||||
|
multiboot2 /boot/acrn.industry.nuc7i7dnb.bin root=PARTUUID="06d5265d-863a-4bc0-b469-66b5e6b8a9cb" i915.modeset=0 video=efifb:off
|
||||||
|
module2 /boot/vmlinuz-5.4.43.PKT-200203T060100Z Linux_bzImage
|
||||||
|
|
||||||
|
Then press :kbd:`F10` to continue booting
|
||||||
|
|
||||||
|
.. rst-class:: numbered-step
|
||||||
|
|
||||||
|
Verify ACRN is running
|
||||||
|
**********************
|
||||||
|
|
||||||
|
After the system boots, you can verify ACRN was detected and is running
|
||||||
|
by looking at the dmesg log:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
:emphasize-lines: 3
|
||||||
|
|
||||||
|
acrn@acrn-NUC:~$ dmesg | grep -i acrn
|
||||||
|
[ 0.000000] Linux version 5.4.43-PKT-200203T060100Z (root@acrn-NUC7i7DNHE) (gcc version 7.5.0 (Ubuntu 7.5.0-3ubuntu1~18.04)) #1 SMP PREEMPT Thu Jul 16 16:33:58 CST 2020
|
||||||
|
[ 0.000000] Hypervisor detected: ACRN
|
||||||
|
[ 2.413796] ACRNTrace: Initialized acrn trace module with 4 cpu
|
||||||
|
[ 2.413883] ACRN HVLog: Failed to init last hvlog devs, errno -19
|
||||||
|
[ 2.413884] ACRN HVLog: Initialized hvlog module with 4 cpu
|
||||||
|
|
||||||
|
|
||||||
install command
|
.. comment
|
||||||
|
|
||||||
sudo dpkg -i acrn_deb_package.deb
|
4.python3 compile_iasl.py
|
||||||
|
=========================
|
||||||
sudo dpkg -i acrn_kernel_deb_package.deb
|
this scriptrs is help compile iasl and cp to /usr/sbin
|
||||||
|
|
||||||
|
|
||||||
uninstall
|
|
||||||
|
|
||||||
sudo dpkg -r acrn-package
|
|
||||||
|
|
||||||
sudo dpkg -r acrn-kernel-package
|
|
||||||
|
|
||||||
4.python3 compile_iasl.py
|
|
||||||
=========================
|
|
||||||
this scriptrs is help compile iasl and cp to /usr/sbin
|
|
||||||
|
|
|
||||||
|
|
@ -1,38 +1,68 @@
|
||||||
{
|
{
|
||||||
"//":"release ubuntu as sos verion",
|
"//":"Configuration for packaging ACRN and Ubuntu for simple installation",
|
||||||
"install_package":"true",
|
|
||||||
"gcc_version":"7.3.0",
|
|
||||||
"binutils":"2.27",
|
|
||||||
"//":"acrn-hypervisor config",
|
|
||||||
"build_acrn":"true",
|
|
||||||
"sync_acrn_code":"true",
|
|
||||||
"acrn_repo":"https://github.com/projectacrn/acrn-hypervisor.git",
|
|
||||||
"release_version":"remotes/origin/release_2.0",
|
|
||||||
"acrn_deb_package":"true",
|
|
||||||
"install_acrn_deb":"false",
|
|
||||||
"build_cmd":
|
|
||||||
{
|
|
||||||
"scenario":
|
|
||||||
{
|
|
||||||
"industry":"true",
|
|
||||||
"hybrid":"true",
|
|
||||||
"logical_partition":"true"
|
|
||||||
|
|
||||||
},
|
"//":"if true, the script will first install all needed apps and libraries and verify gcc and binutils versions ",
|
||||||
"board":
|
"install_package":"true",
|
||||||
{
|
"gcc_version":"7.3.0",
|
||||||
"nuc7i7dnb":"true",
|
"binutils":"2.27",
|
||||||
"whl-ipc-i5":"true"
|
|
||||||
},
|
"//":"acrn-hypervisor config -------------------------------------",
|
||||||
"release":"0"
|
|
||||||
},
|
"//":"if true, uses make to build ACRN from source for the scenarios and boards specified by build_cmd below",
|
||||||
"//":"kernel config",
|
"build_acrn":"true",
|
||||||
"build_acrn_kernel":"true",
|
|
||||||
"sync_acrn_kernel_code":"true",
|
"//":"if true, (and build_acrn is true) clone a local copy of the specified release version of the ACRN hypervisor repo",
|
||||||
"kernel_release_version":"remotes/origin/release_2.0",
|
"//":"if false, assume the repo's local copy is OK",
|
||||||
"sos_kernel_repo":"https://github.com/projectacrn/acrn-kernel.git",
|
"sync_acrn_code":"true",
|
||||||
"acrn_kernel_deb_package":"true",
|
"acrn_repo":"https://github.com/projectacrn/acrn-hypervisor.git",
|
||||||
"install_acrn_kernel_deb":"false",
|
"release_version":"remotes/origin/release_2.0",
|
||||||
"//":"misc",
|
|
||||||
"auto_reboot":"false"
|
"//":"if true, build the acrn_deb_package.deb with the ACRN hypervisor and tools",
|
||||||
|
"//":"(if build_acrn is false, the package contents won't be recompiled before packaging)",
|
||||||
|
"acrn_deb_package":"true",
|
||||||
|
|
||||||
|
"//":"if true, install the acrn_deb package locally after it's built",
|
||||||
|
"//":"(normally the package is copied to the target and installed there, so default is false)",
|
||||||
|
"install_acrn_deb":"false",
|
||||||
|
|
||||||
|
"//":"This is the list of scenario and board combinations that will be built into the package",
|
||||||
|
"//":"(each scenario for each board) use release=0 for debug build, and 1 for production build",
|
||||||
|
"build_cmd":
|
||||||
|
{
|
||||||
|
"scenario":
|
||||||
|
{
|
||||||
|
"industry":"true",
|
||||||
|
"hybrid":"true",
|
||||||
|
"logical_partition":"true"
|
||||||
|
},
|
||||||
|
"board":
|
||||||
|
{
|
||||||
|
"nuc7i7dnb":"true",
|
||||||
|
"whl-ipc-i5":"true"
|
||||||
|
},
|
||||||
|
"release":"0"
|
||||||
|
},
|
||||||
|
|
||||||
|
"//":"kernel config ----------------------------------------------",
|
||||||
|
|
||||||
|
"//":"if true, uses make to build the ACRN-patched kernel from source",
|
||||||
|
"build_acrn_kernel":"true",
|
||||||
|
|
||||||
|
"//":"if true, (and build_acrn_kernel is true) clone a local copy of the specified release version of the ACRN kernel repo",
|
||||||
|
"//":"if false, assume the repo's local copy is OK",
|
||||||
|
"sync_acrn_kernel_code":"true",
|
||||||
|
"kernel_release_version":"remotes/origin/release_2.0",
|
||||||
|
"sos_kernel_repo":"https://github.com/projectacrn/acrn-kernel.git",
|
||||||
|
|
||||||
|
"//":"if true, build the acrn_kernel_deb_package.deb with the ACRN kernel",
|
||||||
|
"//":"(if build_acrn_kernel is false, the package contents won't be recompiled before packaging)",
|
||||||
|
"acrn_kernel_deb_package":"true",
|
||||||
|
|
||||||
|
"//":"if true, install the acrn_kernel_deb package locally after it's built",
|
||||||
|
"//":"(normally the package is copied to the target and installed there, so default is false)",
|
||||||
|
"install_acrn_kernel_deb":"false",
|
||||||
|
|
||||||
|
"//":"misc -------------------------------------------------------",
|
||||||
|
|
||||||
|
"auto_reboot":"false"
|
||||||
}
|
}
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue