X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Fdeveloper-guide.rst;h=41e1391a1b9c45fac54e44757050cf0adc493d45;hb=4774a0dcbd593e34f6c9e653a460f7bf18327907;hp=fb7c9121e1a6bf85628ef66baaaf2a946a7608d7;hpb=4ea6c305c910add58abd7b9d74c1da14e226adef;p=pti%2Frtp.git diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index fb7c912..41e1391 100755 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -2,18 +2,53 @@ .. 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: @@ -24,11 +59,79 @@ To contribute on this project, basic knowledge of Yocto/OpenEmbedded is needed, .. _`OpenEmbedded wiki`: http://www.openembedded.org/wiki/Main_Page -Processes ---------- +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. + +* 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 ++++++++++++++++++++++++++++++++++++++++++++++++ -1. Prerequisite for 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: @@ -36,13 +139,13 @@ Processes * `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 :: @@ -51,7 +154,7 @@ Processes 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: :: @@ -62,56 +165,66 @@ Processes 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 + +2.4 How to build the Debian based image for ARM64 arch +------------------------------------------------------ + +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. + +* 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. -3. (Optional) Use wrapper script build_oran.sh to setup build env and build the lagecy x86 image -```````````````````````````````````````````````````````````````````````````````````````````````` +.. _`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 -Note: The lagecy image is the Kubernetes Cluster image as the same one in Amber (1.0) release. +2.4.2 Use wrapper script build_stx_debian.sh to build the Debian based image +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ :: - # 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' + # 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_oran.sh - $ WORKSPACE=/path/to/workspace_lagecy - $ ./build_oran.sh -w ${WORKSPACE} + $ chmod +x build_stx_debian.sh + $ WORKSPACE=/path/to/workspace + $ ./build_stx_debian.sh -w ${WORKSPACE} -a arm64 -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 -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. +The build-image will always fail for now, do the following workaround after build-image fails: :: - # 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 + 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