docs/templates/build-instructions.rst

   1 :Authors: Jonas Bjurel (Ericsson)
   2 :Version: 0.1
   3
   4 ================================================================
   5 OPNFV Build instructions for - < Component denomination >
   6 ================================================================
   7
   8 Abstract
   9 ========
  10
  11 This document describes how to build <Component>, build system dependencies and required system resources.
  12
  13 License
  14 =======
  15 <WORK'S NAME> (c) by <AUTHOR'S NAME>
  16
  17 <WORK'S NAME> is licensed under a Creative Commons Attribution 4.0 International License.
  18 You should have received a copy of the license along with this.
  19 If not, see <http://creativecommons.org/licenses/by/4.0/>.
  20
  21
  22 **Contents**
  23
  24 1   Version history
  25
  26 2   Introduction
  27
  28 3   Requirements
  29
  30 4   Building
  31
  32 5   Artifacts
  33
  34
  35 1   Version history
  36 ===================
  37
  38 +--------------------+--------------------+--------------------+--------------------+
  39 | **Date**           | **Ver.**           | **Author**         | **Comment**        |
  40 |                    |                    |                    |                    |
  41 +--------------------+--------------------+--------------------+--------------------+
  42 | 2015-04-14         | 0.1.0              | Jonas Bjurel       | First draft        |
  43 |                    |                    |                    |                    |
  44 +--------------------+--------------------+--------------------+--------------------+
  45 |                    | 0.1.1              |                    |                    |
  46 |                    |                    |                    |                    |
  47 +--------------------+--------------------+--------------------+--------------------+
  48 |                    | 1.0                |                    |                    |
  49 |                    |                    |                    |                    |
  50 |                    |                    |                    |                    |
  51 +--------------------+--------------------+--------------------+--------------------+
  52
  53 2   Introduction
  54 ================
  55 <INTRODUCTION TO THE SCOPE AND INTENTION OF THIS DOCUMENT>
  56
  57 <EXAMPLE>:
  58
  59 This document describes build system used to build Fuel@OPNFV,
  60 required dependencies and minimum requirements on the host to be used for the buildsystem.
  61
  62 The Fuel build system is desigened around Docker containers such that dependencies
  63 outside of the build system can be kept to a minimum.
  64 It also shields the host from any potential dangerous operations performed by the build system.
  65
  66 The audience of this document is assumed to have good knowledge in network and Unix/Linux administration.
  67
  68 3   Requirements
  69 ================
  70 <PROVIDE A LIST OF MINIMUM HARDWARE AND SOFTWARE REQUIREMENTS FOR THE BUILD>
  71
  72 3.1 Minimum Hardware Requirements
  73 ---------------------------------
  74 <EXAMPLE>:
  75
  76 - An x86_64 host (Bare-metal or VM) with Ubuntu 14.04 LTS installed
  77
  78 - ~30 GB available disc
  79
  80 - 4 GB RAM
  81
  82 3.2 Minimum Software Requirements
  83 ---------------------------------
  84 <EXAMPLE>:
  85 The build host should run Ubuntu 14.04 operating system.
  86
  87 On the host, the following packages must be installed:
  88
  89 - docker - see https://docs.docker.com/installation/ubuntulinux/ for installation notes for Ubuntu 14.04.
  90   Note: only use the Ubuntu stock distro of Docker (docker.io)
  91
  92 - git (simply available through sudo apt-get install git)
  93
  94 - make (simply available through sudo apt-get install make)
  95
  96 - curl (simply available through sudo apt-get install curl)
  97
  98 3.3 Preparations
  99 ----------------
 100 <EXAMPLE>:
 101
 102 3.3.1 Setting up the Docker build container
 103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 104 After having installed Docker, add yourself to the docker group:
 105
 106 <usermod -a -G docker [userid]>
 107
 108 Also make sure to define relevant DNS servers part of the global dns chain in
 109 in your </etc/default/docker> configuration file, eg.
 110
 111 <DOCKER_OPTS=" --dns=8.8.8.8 --dns=8.8.8.4">
 112
 113 Then restart docker:
 114
 115 <sudo service docker.io restart>
 116
 117 3.3.2 Setting up OPNFV Gerrit in order to being able to clone the code
 118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 119
 120 - Start setting up OPNFV gerrit by creating a SSH key (unless you don't already have one),
 121   create one with ssh-keygen
 122
 123 - Add your generated public key in OPNFV Gerrit <https://gerrit.opnfv.org/>
 124   (this requires a linuxfoundation account, create one if you do not already have one)
 125
 126 - Select "SSH Public Keys" to the left and then "Add Key" and paste your public key in.
 127
 128 3.3.3 Clone the OPNFV code git repository
 129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 130 Now it is time to clone the code repository:
 131
 132 <git clone ssh://Linux foundation user@gerrit.opnfv.org:29418/genesis>
 133
 134 Now you should have the OPNFV genesis repository with Fuel@OPNFV stored locally on your build host.
 135
 136 4   Building
 137 ============
 138 <DESCRIBE THE FULL PROCEDURES FOR THE BUILD OF THE OPNFV COMPONENT ARTIFACTS>
 139
 140 <EXAMPLE>:
 141
 142 There are two methods available for building Fuel@OPNFV:
 143
 144 - A low level method using Make
 145
 146 - An abstracted method using build.sh
 147
 148 4.1  Configure your build environment
 149 -------------------------------------
 150
 151 Select the versions of the components you want to build by editing the fuel/build/config.mk file.
 152 Note if you want to build with OpenDaylight SDN controller you need to uncomment the lines starting
 153 with odl-main and java-main
 154
 155 4.2  Low level build method using make
 156 --------------------------------------
 157
 158 The low level method is based on Make:
 159
 160 From the <fuel/build directory> invoke <make [target]>
 161
 162 Following targets exist:
 163
 164 - none/all -  this will:
 165
 166   - If not allready existing, initialize the docker build environment
 167
 168   - If not already done, build OpenDaylight from upstream (as defined by fuel-build config-spec)
 169
 170   - If not already done, build fuel from upstream (as defined by fuel-build/config-spec)
 171
 172   - Build the defined additions to fuel (as defined by the structure of this framework)
 173
 174   - Apply changes and patches to fuel (as defined by the structure of this framework)
 175
 176   - Reconstruct a fuel .iso image
 177
 178 - clean - this will remove all artifacts from earlier builds.
 179
 180 If the build is successful, you will find the generated ISO file in the <fuel/build/release> subdirectory!
 181
 182 4.3  Abstracted build method using build.sh
 183 ===========================================
 184 The abstracted build method useses the <fuel/ci/build.sh> script which allows you to:
 185
 186 - Create and use a build cache - significantly speeding up the buildtime if upstream repositories have not changed.
 187
 188 - push/pull cache and artifacts to an arbitrary URI (http(s):, file:, ftp:)
 189
 190 For more info type <fuel/ci/build.sh -h>.
 191
 192 5   Artifacts
 193 =============
 194 <DESCRIBE WHAT ARE THE PRODUCED ARTIFACTS AND WHERE THOSE CAN BE FOUND>
 195
 196 <EXAMPLES>:
 197
 198 The artifacts produced are:
 199
 200 - <OPNFV_XXXX.iso> - Which represents the bootable Fuel@OPNFV image,
 201   XXXX is replaced with the build identity provided to the build system
 202
 203 - <OPNFV_XXXX.iso.txt> - Which holds version metadata.
 204
 205 6  References
 206 =============
 207 <PROVIDE NEEDED/USEFUL REFERENCES>