.. SPDX-License-Identifier: CC-BY-4.0
.. Copyright (C) 2019 Wind River Systems, Inc.
-Developer-Guide
-===============
+INF Developer Guide
+===================
.. contents::
:depth: 3
:local:
+1. About the INF project
+************************
-This project implements a real time platform to deploy the O-CU and O-DU and it's based on Yocto/OpenEmbedded.
+This project is a reference implementation of O-Cloud infrastructure which is based on StarlingX, and it supports multi-OS.
-This includes a Yocto/OpenEmbedded compatible layer meta-oran and wrapper scripts
-to pull all required Yocto/OE layers to build out the reference platform.
+* Currently the following OS are supported:
+
+ * Debian 11 (bullseye)
+ * CentOS 7
+ * Yocto 2.7 (warrior)
+
+Notes:
+ * Debian based is the recommended platfrom.
+ * The intended audiences of this guide are the developers who want to develop/integrate apps in INF platform, if you just want to install and deploy INF platform, you can ignore this guide and read the `INF Installation Guide`_
+
+Experimental feature:
+* INF project starts to support ARM64 architecture in this release as experimental feature (POC level), limited features implemented and tested.
+
+ * It can only be natively built on HPE RL300 Gen11 server (Ampere Altra).
+ * AIO-SX (std kernel) tested on VM and HPE RL300 server.
+ * AIO-DX (std kernel) tested on VM.
+
+.. _`INF Installation Guide`: https://docs.o-ran-sc.org/projects/o-ran-sc-pti-rtp/en/latest/installation-guide.html
+
+1.1 About the Debian based implementaion
+----------------------------------------
+The project provde wrapper scripts to automate all the steps of `StarlingX Debian Build Guide`_ to build out the reference platform as an installable ISO image.
+
+.. _`StarlingX Debian Build Guide`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment
+
+1.2 About the CentOS based implementaion
+----------------------------------------
+The project provde wrapper scripts to automate all the steps of `StarlingX Build Guide`_ to build out the reference platform as an installable ISO image.
+
+.. _`StarlingX Build Guide`: https://docs.starlingx.io/developer_resources/build_guide.html
+
+1.3 About the Yocto based implementation
+----------------------------------------
+
+The project provde wrapper scripts to pull all required Yocto/OE layers to build out the reference platform as an installable ISO image.
To contribute on this project, basic knowledge of Yocto/OpenEmbedded is needed, please refer to the following docs if you want to learn about how to develop with Yocto/OpenEmbedded:
.. _`OpenEmbedded wiki`: http://www.openembedded.org/wiki/Main_Page
+2. How to build the INF project
+*******************************
+
+2.1 How to build the Debian based image
+---------------------------------------
+
+2.1.1 Prerequisite for Debian build environment
++++++++++++++++++++++++++++++++++++++++++++++++
+
+NOTE: The build system for Debian requires a Linux system with Docker and python 3.x installed. The the following steps have been tested on CentOS 7 and Ubuntu 20.04.
-1. Prerequisite for build environment
--------------------------------------
+* Refer to `Install docker on ubuntu`_ or `Install docker on centos`_ to install docker.
+* Refer to `Configure_Debian_build_environment`_ to install prerequisite packges and configure for Debian build environment.
+
+.. _`Install docker on ubuntu`: https://docs.docker.com/engine/install/ubuntu/
+.. _`Install docker on centos`: https://docs.docker.com/engine/install/centos/
+.. _`Configure_Debian_build_environment`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment#Configure_build_environment
+
+2.1.2 Use wrapper script build_inf_debian.sh to build the Debian based image
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+::
+
+ # Get the wrapper script to build the debian image
+ $ wget -O build_inf_debian.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_inf_debian/build_inf_debian.sh;hb=HEAD'
+
+ $ chmod +x build_inf_debian.sh
+ $ WORKSPACE=/path/to/workspace
+ $ ./build_inf_debian.sh -w ${WORKSPACE}
+
+If all go well, you will get the ISO image in:
+${WORKSPACE}/prj_output/inf-image-debian-all-x86-64.iso
+
+2.2 How to build the CentOS based image
+---------------------------------------
+
+NOTE: This only supports build on CentOS 7 which will be EOL 30 Jun 2024.
+
+2.2.1 Prerequisite for CentOS build environment
++++++++++++++++++++++++++++++++++++++++++++++++
+
+NOTE: This step needs the user has sudo permission.
+
+::
+
+ # Get the wrapper script for preparing the build environment
+ $ wget -O build_inf_prepare.sh https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_inf_centos/build_inf_prepare_jenkins.sh;hb=HEAD
+
+ $ chmod +x build_inf_prepare.sh
+ $ WORKSPACE=/path/to/workspace
+ $ ./build_inf_prepare.sh -w ${WORKSPACE}
+
+2.2.2 Use wrapper script build_inf_centos.sh to build the CentOS based image
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+::
+
+ # Get the wrapper script to build the centos image
+ $ wget -O build_inf_centos.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_inf_centos/build_inf_centos.sh;hb=HEAD'
+
+ $ chmod +x build_inf_centos.sh
+ $ WORKSPACE=/path/to/workspace
+ $ ./build_inf_centos.sh -w ${WORKSPACE}
+
+If all go well, you will get the ISO image in:
+${WORKSPACE}/prj_output/inf-image-centos-all-x86-64.iso
+
+
+2.3 How to build the Yocto based image
+--------------------------------------
+
+2.3.1 Prerequisite for Yocto build environment
+++++++++++++++++++++++++++++++++++++++++++++++
* Your host need to meet the requirements for Yocto, please refer to:
* `Supported Linux Distributions`_
* `Required Packages for the Build Host`_
-* The recommended and tested host is Ubuntu 16.04/18.04 and CentOS 7.
+The recommended and tested host is Ubuntu 16.04/18.04 and CentOS 7.
- * To install the required packages for Ubuntu 16.04/18.04:
+* To install the required packages for Ubuntu 16.04/18.04:
-.. _`Compatible Linux Distribution`: https://www.yoctoproject.org/docs/2.6.3/brief-yoctoprojectqs/brief-yoctoprojectqs.html#brief-compatible-distro
-.. _`Supported Linux Distributions`: https://www.yoctoproject.org/docs/2.6.3/ref-manual/ref-manual.html#detailed-supported-distros
-.. _`Required Packages for the Build Host`: https://www.yoctoproject.org/docs/2.6.3/ref-manual/ref-manual.html#required-packages-for-the-build-host
+.. _`Compatible Linux Distribution`: https://docs.yoctoproject.org/2.7.4/brief-yoctoprojectqs/brief-yoctoprojectqs.html#brief-compatible-distro
+.. _`Supported Linux Distributions`: https://docs.yoctoproject.org/2.7.4/ref-manual/ref-manual.html#detailed-supported-distros
+.. _`Required Packages for the Build Host`: https://docs.yoctoproject.org/2.7.4/ref-manual/ref-manual.html#required-packages-for-the-build-host
::
xz-utils debianutils iputils-ping make xsltproc docbook-utils fop dblatex xmlto \
python-git
- * To install the required packages for CentOS 7:
+* To install the required packages for CentOS 7:
::
perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-Digest-SHA \
python34-pip xz which SDL-devel xterm
-
-2. Use wrapper script build_inf.sh to setup build env and build the INF AIO x86 image
--------------------------------------------------------------------------------------
+2.3.2 Use wrapper script build_inf_yocto.sh to setup build the Yocto based image
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
::
# Get the wrapper script with either curl or wget
- $ curl -o build_inf.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_inf.sh;hb=HEAD'
- $ wget -O build_inf.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_inf.sh;hb=HEAD'
+ $ curl -o build_inf_yocto.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_inf_yocto/build_inf_yocto.sh;hb=HEAD'
+ $ wget -O build_inf_yocto.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_inf_yocto/build_inf_yocto.sh;hb=HEAD'
- $ chmod +x build_inf.sh
+ $ chmod +x build_inf_yocto.sh
$ WORKSPACE=/path/to/workspace
- $ ./build_inf.sh -w ${WORKSPACE}
+ $ ./build_inf_yocto.sh -w ${WORKSPACE}
If all go well, you will get the ISO image in:
-${WORKSPACE}/prj_oran_inf_anaconda/tmp-glibc/deploy/images/intel-corei7-64/inf-image-aio-installer-intel-corei7-64.iso
+${WORKSPACE}/prj_output/inf-image-yocto-aio-x86-64.iso
-3. (Optional) Use wrapper script build_oran.sh to setup build env and build the lagecy x86 image
-------------------------------------------------------------------------------------------------
+2.4 How to build the Debian based image for ARM64 arch
+------------------------------------------------------
-Note: The lagecy image is the Kubernetes Cluster image as the same one in Amber (1.0) release.
+2.4.1 Prerequisite for Debian build environment
++++++++++++++++++++++++++++++++++++++++++++++++
-::
+NOTE:
+ * The build env only tested on HPE RL300 server (Ampere Altra).
+ * The build system for Debian requires a Linux system with Docker and python 3.x installed. The the following steps have been tested on Debian 11.
- # Get the wrapper script with either curl or wget
- $ curl -o build_oran.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_oran.sh;hb=HEAD'
- $ wget -O build_oran.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_oran.sh;hb=HEAD'
+* Refer to `Install docker on ubuntu`_ or `Install docker on centos`_ to install docker.
+* Refer to `Configure_Debian_build_environment`_ to install prerequisite packges and configure for Debian build environment.
- $ chmod +x build_oran.sh
- $ WORKSPACE=/path/to/workspace_lagecy
- $ ./build_oran.sh -w ${WORKSPACE}
+.. _`Install docker on debian`: https://docs.docker.com/engine/install/debian/
+.. _`Configure_Debian_build_environment`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment#Configure_build_environment
-If all go well, you will get the ISO image in:
-${WORKSPACE}/prj_oran_inf/tmp-glibc/deploy/images/intel-x86-64/oran-image-inf-host-intel-x86-64.iso
+2.4.2 Use wrapper script build_stx_debian.sh to build the Debian based image
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-4. (Optional) Use wrapper script build_oran.sh to setup build env and build the ARM Kubernetes Cluster image
-------------------------------------------------------------------------------------------------------------
+::
-Note:
- * the ARM Kubernetes Cluster image only supports the BSP nxp-lx2xxx and is verified with the board NXP LX2160ARDB
- * The ISO image is supported yet.
+ # Get the wrapper script to build the debian image
+ $ wget -O build_stx_debian.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_inf_debian/build_stx_debian.sh;hb=HEAD'
-::
+ $ chmod +x build_stx_debian.sh
+ $ WORKSPACE=/path/to/workspace
+ $ ./build_stx_debian.sh -w ${WORKSPACE} -a arm64
- # Get the wrapper script with either curl or wget
- $ curl -o build_oran.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_oran.sh;hb=HEAD'
- $ wget -O build_oran.sh 'https://gerrit.o-ran-sc.org/r/gitweb?p=pti/rtp.git;a=blob_plain;f=scripts/build_oran.sh;hb=HEAD'
- $ chmod +x build_oran.sh
- $ WORKSPACE=/path/to/workspace_arm
- $ ./build_oran.sh -w ${WORKSPACE} -b nxp-lx2xxx
+The build-image will always fail for now, do the following workaround after build-image fails:
+
+::
+
+ cd ${WORKSPACE}
+ source env.prj-stx-deb
+ cd src/stx-tools
+ source import-stx
+
+ stx shell --container lat
+
+ # inside the LAT pod
+ cd /localdisk
+ . /opt/LAT/SDK/environment-setup-cortexa57-wrs-linux
+ appsdk --log-dir log genimage lat.yaml
-If all go well, you will get the rootfs image in:
-${WORKSPACE}/prj_oran_inf/tmp-glibc/deploy/images/nxp-lx2xxx/oran-image-inf-host-nxp-lx2xxx.tar.bz2
+If all go well, you will get the ISO image in:
+${WORKSPACE}/localdisk/deploy/starlingx-qemuarm64-cd.iso
Code Review / pti / rtp.git / blobdiff