1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. SPDX-License-Identifier: CC-BY-4.0
3 .. Copyright (C) 2019 Wind River Systems, Inc.
12 1. About the INF project
13 ************************
15 This project is a reference implementation of O-Cloud infrastructure which is based on StarlingX, and it supports multi-OS.
17 * Currently the following OS are supported:
19 * Debian 11 (bullseye)
24 * Debian based is the recommended platfrom.
25 * 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`_
28 * INF project starts to support ARM64 architecture in this release as experimental feature (POC level), limited features implemented and tested.
30 * It can only be natively built on HPE RL300 Gen11 server (Ampere Altra).
31 * AIO-SX (std kernel) tested on VM and HPE RL300 server.
32 * AIO-DX (std kernel) tested on VM.
34 .. _`INF Installation Guide`: https://docs.o-ran-sc.org/projects/o-ran-sc-pti-rtp/en/latest/installation-guide.html
36 1.1 About the Debian based implementaion
37 ----------------------------------------
38 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.
40 .. _`StarlingX Debian Build Guide`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment
42 1.2 About the CentOS based implementaion
43 ----------------------------------------
44 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.
46 .. _`StarlingX Build Guide`: https://docs.starlingx.io/developer_resources/build_guide.html
48 1.3 About the Yocto based implementation
49 ----------------------------------------
51 The project provde wrapper scripts to pull all required Yocto/OE layers to build out the reference platform as an installable ISO image.
53 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:
56 - `OpenEmbedded wiki`_
58 .. _`Yocto dev manual`: https://www.yoctoproject.org/docs/2.6.3/dev-manual/dev-manual.html
59 .. _`OpenEmbedded wiki`: http://www.openembedded.org/wiki/Main_Page
62 2. How to build the INF project
63 *******************************
65 2.1 How to build the Debian based image
66 ---------------------------------------
68 2.1.1 Prerequisite for Debian build environment
69 +++++++++++++++++++++++++++++++++++++++++++++++
71 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.
73 * Refer to `Install docker on ubuntu`_ or `Install docker on centos`_ to install docker.
74 * Refer to `Configure_Debian_build_environment`_ to install prerequisite packges and configure for Debian build environment.
76 .. _`Install docker on ubuntu`: https://docs.docker.com/engine/install/ubuntu/
77 .. _`Install docker on centos`: https://docs.docker.com/engine/install/centos/
78 .. _`Configure_Debian_build_environment`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment#Configure_build_environment
80 2.1.2 Use wrapper script build_inf_debian.sh to build the Debian based image
81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
85 # Get the wrapper script to build the debian image
86 $ 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'
88 $ chmod +x build_inf_debian.sh
89 $ WORKSPACE=/path/to/workspace
90 $ ./build_inf_debian.sh -w ${WORKSPACE}
92 If all go well, you will get the ISO image in:
93 ${WORKSPACE}/prj_output/inf-image-debian-all-x86-64.iso
95 2.2 How to build the CentOS based image
96 ---------------------------------------
98 NOTE: This only supports build on CentOS 7 which will be EOL 30 Jun 2024.
100 2.2.1 Prerequisite for CentOS build environment
101 +++++++++++++++++++++++++++++++++++++++++++++++
103 NOTE: This step needs the user has sudo permission.
107 # Get the wrapper script for preparing the build environment
108 $ 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
110 $ chmod +x build_inf_prepare.sh
111 $ WORKSPACE=/path/to/workspace
112 $ ./build_inf_prepare.sh -w ${WORKSPACE}
114 2.2.2 Use wrapper script build_inf_centos.sh to build the CentOS based image
115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
119 # Get the wrapper script to build the centos image
120 $ 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'
122 $ chmod +x build_inf_centos.sh
123 $ WORKSPACE=/path/to/workspace
124 $ ./build_inf_centos.sh -w ${WORKSPACE}
126 If all go well, you will get the ISO image in:
127 ${WORKSPACE}/prj_output/inf-image-centos-all-x86-64.iso
130 2.3 How to build the Yocto based image
131 --------------------------------------
133 2.3.1 Prerequisite for Yocto build environment
134 ++++++++++++++++++++++++++++++++++++++++++++++
136 * Your host need to meet the requirements for Yocto, please refer to:
138 * `Compatible Linux Distribution`_
139 * `Supported Linux Distributions`_
140 * `Required Packages for the Build Host`_
142 The recommended and tested host is Ubuntu 16.04/18.04 and CentOS 7.
144 * To install the required packages for Ubuntu 16.04/18.04:
146 .. _`Compatible Linux Distribution`: https://docs.yoctoproject.org/2.7.4/brief-yoctoprojectqs/brief-yoctoprojectqs.html#brief-compatible-distro
147 .. _`Supported Linux Distributions`: https://docs.yoctoproject.org/2.7.4/ref-manual/ref-manual.html#detailed-supported-distros
148 .. _`Required Packages for the Build Host`: https://docs.yoctoproject.org/2.7.4/ref-manual/ref-manual.html#required-packages-for-the-build-host
152 $ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
153 build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
154 xz-utils debianutils iputils-ping make xsltproc docbook-utils fop dblatex xmlto \
157 * To install the required packages for CentOS 7:
161 $ sudo yum install -y epel-release
163 $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \
164 diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath socat \
165 perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-Digest-SHA \
166 python34-pip xz which SDL-devel xterm
168 2.3.2 Use wrapper script build_inf_yocto.sh to setup build the Yocto based image
169 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
173 # Get the wrapper script with either curl or wget
174 $ 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'
175 $ 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'
177 $ chmod +x build_inf_yocto.sh
178 $ WORKSPACE=/path/to/workspace
179 $ ./build_inf_yocto.sh -w ${WORKSPACE}
181 If all go well, you will get the ISO image in:
182 ${WORKSPACE}/prj_output/inf-image-yocto-aio-x86-64.iso
184 2.4 How to build the Debian based image for ARM64 arch
185 ------------------------------------------------------
187 2.4.1 Prerequisite for Debian build environment
188 +++++++++++++++++++++++++++++++++++++++++++++++
191 * The build env only tested on HPE RL300 server (Ampere Altra).
192 * 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.
194 * Refer to `Install docker on ubuntu`_ or `Install docker on centos`_ to install docker.
195 * Refer to `Configure_Debian_build_environment`_ to install prerequisite packges and configure for Debian build environment.
197 .. _`Install docker on debian`: https://docs.docker.com/engine/install/debian/
198 .. _`Configure_Debian_build_environment`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment#Configure_build_environment
200 2.4.2 Use wrapper script build_stx_debian.sh to build the Debian based image
201 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
205 # Get the wrapper script to build the debian image
206 $ 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'
208 $ chmod +x build_stx_debian.sh
209 $ WORKSPACE=/path/to/workspace
210 $ ./build_stx_debian.sh -w ${WORKSPACE} -a arm64
213 The build-image will always fail for now, do the following workaround after build-image fails:
218 source env.prj-stx-deb
222 stx shell --container lat
226 . /opt/LAT/SDK/environment-setup-cortexa57-wrs-linux
227 appsdk --log-dir log genimage lat.yaml
229 If all go well, you will get the ISO image in:
230 ${WORKSPACE}/localdisk/deploy/starlingx-qemuarm64-cd.iso