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 it supports multi-OS.
  16
  17 * Currently the following OS are supported:
  18
  19   * Debian 11 (bullseye)
  20   * CentOS 7
  21   * Yocto 2.7 (warrior)
  22
  23 Notes:
  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`_
  26
  27 .. _`INF Installation Guide`: https://docs.o-ran-sc.org/projects/o-ran-sc-pti-rtp/en/latest/installation-guide.html
  28
  29 1.1 About the Debian based implementaion
  30 ----------------------------------------
  31 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.
  32
  33 .. _`StarlingX Debian Build Guide`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment
  34
  35 1.2 About the CentOS based implementaion
  36 ----------------------------------------
  37 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.
  38
  39 .. _`StarlingX Build Guide`: https://docs.starlingx.io/developer_resources/build_guide.html
  40
  41 1.3 About the Yocto based implementation
  42 ----------------------------------------
  43
  44 The project provde wrapper scripts to pull all required Yocto/OE layers to build out the reference platform as an installable ISO image.
  45
  46 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:
  47
  48 - `Yocto dev manual`_
  49 - `OpenEmbedded wiki`_
  50
  51 .. _`Yocto dev manual`: https://www.yoctoproject.org/docs/2.6.3/dev-manual/dev-manual.html
  52 .. _`OpenEmbedded wiki`: http://www.openembedded.org/wiki/Main_Page
  53
  54
  55 2. How to build the INF project
  56 *******************************
  57
  58 2.1 How to build the Debian based image
  59 ---------------------------------------
  60
  61 2.1.1 Prerequisite for Debian build environment
  62 +++++++++++++++++++++++++++++++++++++++++++++++
  63
  64 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.
  65
  66 * Refer to `Install docker on ubuntu`_ or `Install docker on centos`_ to install docker.
  67 * Refer to `Configure_Debian_build_environment`_ to install prerequisite packges and configure for Debian build environment.
  68
  69 .. _`Install docker on ubuntu`: https://docs.docker.com/engine/install/ubuntu/
  70 .. _`Install docker on centos`: https://docs.docker.com/engine/install/centos/
  71 .. _`Configure_Debian_build_environment`: https://wiki.openstack.org/wiki/StarlingX/DebianBuildEnvironment#Configure_build_environment
  72
  73 2.1.2 Use wrapper script build_inf_debian.sh to build the Debian based image
  74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  75
  76 ::
  77
  78   # Get the wrapper script to build the debian image
  79   $ 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'
  80
  81   $ chmod +x build_inf_debian.sh
  82   $ WORKSPACE=/path/to/workspace
  83   $ ./build_inf_debian.sh -w ${WORKSPACE}
  84
  85 If all go well, you will get the ISO image in:
  86 ${WORKSPACE}/prj_output/inf-image-debian-all-x86-64.iso
  87
  88 2.2 How to build the CentOS based image
  89 ---------------------------------------
  90
  91 NOTE: This only supports build on CentOS 7 which will be EOL 30 Jun 2024.
  92
  93 2.2.1 Prerequisite for CentOS build environment
  94 +++++++++++++++++++++++++++++++++++++++++++++++
  95
  96 NOTE: This step needs the user has sudo permission.
  97
  98 ::
  99
 100   # Get the wrapper script for preparing the build environment
 101   $ 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
 102
 103   $ chmod +x build_inf_prepare.sh
 104   $ WORKSPACE=/path/to/workspace
 105   $ ./build_inf_prepare.sh -w ${WORKSPACE}
 106
 107 2.2.2 Use wrapper script build_inf_centos.sh to build the CentOS based image
 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 109
 110 ::
 111
 112   # Get the wrapper script to build the centos image
 113   $ 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'
 114
 115   $ chmod +x build_inf_centos.sh
 116   $ WORKSPACE=/path/to/workspace
 117   $ ./build_inf_centos.sh -w ${WORKSPACE}
 118
 119 If all go well, you will get the ISO image in:
 120 ${WORKSPACE}/prj_output/inf-image-centos-all-x86-64.iso
 121
 122
 123 2.3 How to build the Yocto based image
 124 --------------------------------------
 125
 126 2.3.1 Prerequisite for Yocto build environment
 127 ++++++++++++++++++++++++++++++++++++++++++++++
 128
 129 * Your host need to meet the requirements for Yocto, please refer to:
 130
 131   * `Compatible Linux Distribution`_
 132   * `Supported Linux Distributions`_
 133   * `Required Packages for the Build Host`_
 134
 135 The recommended and tested host is Ubuntu 16.04/18.04 and CentOS 7.
 136
 137 * To install the required packages for Ubuntu 16.04/18.04:
 138
 139 .. _`Compatible Linux Distribution`: https://www.yoctoproject.org/docs/2.7.3/brief-yoctoprojectqs/brief-yoctoprojectqs.html#brief-compatible-distro
 140 .. _`Supported Linux Distributions`: https://www.yoctoproject.org/docs/2.7.3/ref-manual/ref-manual.html#detailed-supported-distros
 141 .. _`Required Packages for the Build Host`: https://www.yoctoproject.org/docs/2.7.3/ref-manual/ref-manual.html#required-packages-for-the-build-host
 142
 143 ::
 144
 145   $ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
 146     build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
 147     xz-utils debianutils iputils-ping make xsltproc docbook-utils fop dblatex xmlto \
 148     python-git
 149
 150 * To install the required packages for CentOS 7:
 151
 152 ::
 153
 154   $ sudo yum install -y epel-release
 155   $ sudo yum makecache
 156   $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \
 157     diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath socat \
 158     perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-Digest-SHA \
 159     python34-pip xz which SDL-devel xterm
 160
 161 2.3.2 Use wrapper script build_inf_yocto.sh to setup build the Yocto based image
 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 163
 164 ::
 165
 166   # Get the wrapper script with either curl or wget
 167   $ 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'
 168   $ 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'
 169
 170   $ chmod +x build_inf_yocto.sh
 171   $ WORKSPACE=/path/to/workspace
 172   $ ./build_inf_yocto.sh -w ${WORKSPACE}
 173
 174 If all go well, you will get the ISO image in:
 175 ${WORKSPACE}/prj_output/inf-image-yocto-aio-x86-64.iso
 176