docs/developer-guide.rst

   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.
   4
   5 INF Developer Guide
   6 ===================
   7
   8 .. contents::
   9    :depth: 3
  10    :local:
  11
  12 1. About the INF project
  13 ************************
  14
  15 This project is a reference implementation of O-Cloud infrastructure which is based on StarlingX and OKD, and it supports multi-OS.
  16
  17 * Currently the following OS are supported:
  18
  19   * StarlingX
  20
  21     * Debian 11 (bullseye)
  22     * CentOS 7
  23     * Yocto 2.7 (warrior)
  24
  25   * OKD
  26
  27     * Fedora CoreOS 38
  28
  29 Notes:
  30   * Debian based is the recommended platfrom.
  31   * 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`_
  32
  33 Experimental feature:
  34 * INF project starts to support ARM64 architecture in this release as experimental feature (POC level), limited features implemented and tested.
  35
  36   * It can only be natively built on HPE RL300 Gen11 server (Ampere Altra).
  37   * AIO-SX (std kernel) tested on VM and HPE RL300 server.
  38   * AIO-DX (std kernel) tested on VM.
  39
  40 .. _`INF Installation Guide`: https://docs.o-ran-sc.org/projects/o-ran-sc-pti-rtp/en/latest/installation-guide.html
  41
  42 1.1 About the Debian based implementaion
  43 ----------------------------------------
  44 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.
  45
  46 .. _`StarlingX Debian Build Guide`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment
  47
  48 1.2 About the CentOS based implementaion
  49 ----------------------------------------
  50 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.
  51
  52 .. _`StarlingX Build Guide`: https://docs.starlingx.io/developer_resources/build_guide.html
  53
  54 1.3 About the Yocto based implementation
  55 ----------------------------------------
  56
  57 The project provde wrapper scripts to pull all required Yocto/OE layers to build out the reference platform as an installable ISO image.
  58
  59 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:
  60
  61 - `Yocto dev manual`_
  62 - `OpenEmbedded wiki`_
  63
  64 .. _`Yocto dev manual`: https://www.yoctoproject.org/docs/2.6.3/dev-manual/dev-manual.html
  65 .. _`OpenEmbedded wiki`: http://www.openembedded.org/wiki/Main_Page
  66
  67 1.4 About the Fedora CoreOS / OKD based implementation
  68 ------------------------------------------------------
  69 Deployment automation and documentation for OKD / Fedora CoreOS 38 can be found under the 'okd' directory in the `pti/rtp`_ repository.
  70
  71 .. _`pti/rtp`: https://gerrit.o-ran-sc.org/r/admin/repos/pti/rtp
  72
  73 2. How to build the INF project
  74 *******************************
  75
  76 2.1 How to build the Debian based image
  77 ---------------------------------------
  78
  79 2.1.1 Prerequisite for Debian build environment
  80 +++++++++++++++++++++++++++++++++++++++++++++++
  81
  82 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.
  83
  84 * Refer to `Install docker on ubuntu`_ or `Install docker on centos`_ to install docker.
  85 * Refer to `Configure_Debian_build_environment`_ to install prerequisite packges and configure for Debian build environment.
  86
  87 .. _`Install docker on ubuntu`: https://docs.docker.com/engine/install/ubuntu/
  88 .. _`Install docker on centos`: https://docs.docker.com/engine/install/centos/
  89 .. _`Configure_Debian_build_environment`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment#Configure_build_environment
  90
  91 2.1.2 Use wrapper script build_inf_debian.sh to build the Debian based image
  92 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  93
  94 ::
  95
  96   # Get the wrapper script to build the debian image
  97   $ 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'
  98
  99   $ chmod +x build_inf_debian.sh
 100   $ WORKSPACE=/path/to/workspace
 101   $ ./build_inf_debian.sh -w ${WORKSPACE}
 102
 103 If all go well, you will get the ISO image in:
 104 ${WORKSPACE}/prj_output/inf-image-debian-all-x86-64.iso
 105
 106 2.2 How to build the CentOS based image
 107 ---------------------------------------
 108
 109 NOTE: This only supports build on CentOS 7 which will be EOL 30 Jun 2024.
 110
 111 2.2.1 Prerequisite for CentOS build environment
 112 +++++++++++++++++++++++++++++++++++++++++++++++
 113
 114 NOTE: This step needs the user has sudo permission.
 115
 116 ::
 117
 118   # Get the wrapper script for preparing the build environment
 119   $ 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
 120
 121   $ chmod +x build_inf_prepare.sh
 122   $ WORKSPACE=/path/to/workspace
 123   $ ./build_inf_prepare.sh -w ${WORKSPACE}
 124
 125 2.2.2 Use wrapper script build_inf_centos.sh to build the CentOS based image
 126 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 127
 128 ::
 129
 130   # Get the wrapper script to build the centos image
 131   $ 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'
 132
 133   $ chmod +x build_inf_centos.sh
 134   $ WORKSPACE=/path/to/workspace
 135   $ ./build_inf_centos.sh -w ${WORKSPACE}
 136
 137 If all go well, you will get the ISO image in:
 138 ${WORKSPACE}/prj_output/inf-image-centos-all-x86-64.iso
 139
 140
 141 2.3 How to build the Yocto based image
 142 --------------------------------------
 143
 144 2.3.1 Prerequisite for Yocto build environment
 145 ++++++++++++++++++++++++++++++++++++++++++++++
 146
 147 * Your host need to meet the requirements for Yocto, please refer to:
 148
 149   * `Compatible Linux Distribution`_
 150   * `Supported Linux Distributions`_
 151   * `Required Packages for the Build Host`_
 152
 153 The recommended and tested host is Ubuntu 16.04/18.04 and CentOS 7.
 154
 155 * To install the required packages for Ubuntu 16.04/18.04:
 156
 157 .. _`Compatible Linux Distribution`: https://docs.yoctoproject.org/2.7.4/brief-yoctoprojectqs/brief-yoctoprojectqs.html#brief-compatible-distro
 158 .. _`Supported Linux Distributions`: https://docs.yoctoproject.org/2.7.4/ref-manual/ref-manual.html#detailed-supported-distros
 159 .. _`Required Packages for the Build Host`: https://docs.yoctoproject.org/2.7.4/ref-manual/ref-manual.html#required-packages-for-the-build-host
 160
 161 ::
 162
 163   $ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
 164     build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
 165     xz-utils debianutils iputils-ping make xsltproc docbook-utils fop dblatex xmlto \
 166     python-git
 167
 168 * To install the required packages for CentOS 7:
 169
 170 ::
 171
 172   $ sudo yum install -y epel-release
 173   $ sudo yum makecache
 174   $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \
 175     diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath socat \
 176     perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-Digest-SHA \
 177     python34-pip xz which SDL-devel xterm
 178
 179 2.3.2 Use wrapper script build_inf_yocto.sh to setup build the Yocto based image
 180 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 181
 182 ::
 183
 184   # Get the wrapper script with either curl or wget
 185   $ 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'
 186   $ 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'
 187
 188   $ chmod +x build_inf_yocto.sh
 189   $ WORKSPACE=/path/to/workspace
 190   $ ./build_inf_yocto.sh -w ${WORKSPACE}
 191
 192 If all go well, you will get the ISO image in:
 193 ${WORKSPACE}/prj_output/inf-image-yocto-aio-x86-64.iso
 194
 195 2.4 How to build the Debian based image for ARM64 arch
 196 ------------------------------------------------------
 197
 198 2.4.1 Prerequisite for Debian build environment
 199 +++++++++++++++++++++++++++++++++++++++++++++++
 200
 201 NOTE:
 202   * The build env only tested on HPE RL300 server (Ampere Altra).
 203   * 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.
 204
 205 * Refer to `Install docker on ubuntu`_ or `Install docker on centos`_ to install docker.
 206 * Refer to `Configure_Debian_build_environment`_ to install prerequisite packges and configure for Debian build environment.
 207
 208 .. _`Install docker on debian`: https://docs.docker.com/engine/install/debian/
 209 .. _`Configure_Debian_build_environment`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment#Configure_build_environment
 210
 211 2.4.2 Use wrapper script build_stx_debian.sh to build the Debian based image
 212 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 213
 214 ::
 215
 216   # Get the wrapper script to build the debian image
 217   $ 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'
 218
 219   $ chmod +x build_stx_debian.sh
 220   $ WORKSPACE=/path/to/workspace
 221   $ ./build_stx_debian.sh -w ${WORKSPACE} -a arm64
 222
 223
 224 The build-image will always fail for now, do the following workaround after build-image fails:
 225
 226 ::
 227
 228   cd ${WORKSPACE}
 229   source env.prj-stx-deb
 230   cd src/stx-tools
 231   source import-stx
 232
 233   stx shell --container lat
 234
 235   # inside the LAT pod
 236   cd /localdisk
 237   . /opt/LAT/SDK/environment-setup-cortexa57-wrs-linux
 238   appsdk --log-dir log genimage lat.yaml
 239
 240 If all go well, you will get the ISO image in:
 241 ${WORKSPACE}/localdisk/deploy/starlingx-qemuarm64-cd.iso