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   * CentOS 7
  20   * Yocto 2.7 (warrior)
  21
  22 1.1 About the CentOS based implementaion
  23 ----------------------------------------
  24 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.
  25
  26 .. _`StarlingX Build Guide`: https://docs.starlingx.io/developer_resources/build_guide.html
  27
  28 1.2 About the Yocto based implementation
  29 ----------------------------------------
  30
  31 The project provde wrapper scripts to pull all required Yocto/OE layers to build out the reference platform as an installable ISO image.
  32
  33 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:
  34
  35 - `Yocto dev manual`_
  36 - `OpenEmbedded wiki`_
  37
  38 .. _`Yocto dev manual`: https://www.yoctoproject.org/docs/2.6.3/dev-manual/dev-manual.html
  39 .. _`OpenEmbedded wiki`: http://www.openembedded.org/wiki/Main_Page
  40
  41
  42 2. How to build the INF project
  43 *******************************
  44
  45 2.1 How to build the CentOS based image
  46 ---------------------------------------
  47
  48 2.1.1 Prerequisite for CentOS build environment
  49 +++++++++++++++++++++++++++++++++++++++++++++++
  50 TBD
  51
  52 2.1.2 Use wrapper script build_inf_centos.sh to setup build the CentOS based image
  53 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  54
  55 ::
  56
  57   # Get the wrapper script with either curl or wget
  58   $ curl -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'
  59   $ 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'
  60
  61   $ chmod +x build_inf_centos.sh
  62   $ WORKSPACE=/path/to/workspace
  63   $ ./build_inf_centos.sh -w ${WORKSPACE}
  64
  65 If all go well, you will get the ISO image in:
  66 ${WORKSPACE}/prj_output/inf-image-centos-all-x86-64.iso
  67
  68
  69 2.2 How to build the Yocto based image
  70 --------------------------------------
  71
  72 2.2.1 Prerequisite for Yocto build environment
  73 ++++++++++++++++++++++++++++++++++++++++++++++
  74
  75 * Your host need to meet the requirements for Yocto, please refer to:
  76
  77   * `Compatible Linux Distribution`_
  78   * `Supported Linux Distributions`_
  79   * `Required Packages for the Build Host`_
  80
  81 The recommended and tested host is Ubuntu 16.04/18.04 and CentOS 7.
  82
  83 * To install the required packages for Ubuntu 16.04/18.04:
  84
  85 .. _`Compatible Linux Distribution`: https://www.yoctoproject.org/docs/2.7.3/brief-yoctoprojectqs/brief-yoctoprojectqs.html#brief-compatible-distro
  86 .. _`Supported Linux Distributions`: https://www.yoctoproject.org/docs/2.7.3/ref-manual/ref-manual.html#detailed-supported-distros
  87 .. _`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
  88
  89 ::
  90
  91   $ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
  92     build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
  93     xz-utils debianutils iputils-ping make xsltproc docbook-utils fop dblatex xmlto \
  94     python-git
  95
  96 * To install the required packages for CentOS 7:
  97
  98 ::
  99
 100   $ sudo yum install -y epel-release
 101   $ sudo yum makecache
 102   $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \
 103     diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath socat \
 104     perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-Digest-SHA \
 105     python34-pip xz which SDL-devel xterm
 106
 107 2.2.2 Use wrapper script build_inf_yocto.sh to setup build the Yocto based image
 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 109
 110 ::
 111
 112   # Get the wrapper script with either curl or wget
 113   $ 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'
 114   $ 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'
 115
 116   $ chmod +x build_inf_yocto.sh
 117   $ WORKSPACE=/path/to/workspace
 118   $ ./build_inf_yocto.sh -w ${WORKSPACE}
 119
 120 If all go well, you will get the ISO image in:
 121 ${WORKSPACE}/prj_output/inf-image-yocto-aio-x86-64.iso
 122