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