aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAlexandru Avadanii <Alexandru.Avadanii@enea.com>2016-05-11 15:46:09 +0200
committerAlexandru Avadanii <Alexandru.Avadanii@enea.com>2016-05-11 19:51:34 +0000
commit50986a8592ecad642452e0cf13bf5b51a628a5d5 (patch)
treeeda4d3b09cabcd119d18c8cb63782cb53199058d
parent54b6ac34045381804cb4670816f9e3cf1f4e4e18 (diff)
docs/build-instruction.rst: Cleanup, refactor tags.
Add missing bash (console) code-block tags to commands and preformatted output / configuration sections. While we're at it, fix git clone URL for https, and clarify a few paragraphs. Change-Id: Ifb1ef0a8a9befa57e68255354957e094a124ab7e (cherry picked from commit 6c90cb7ead70605a3daf5df6a37357b01f17d3b2)
-rw-r--r--docs/build-instruction.rst108
1 files changed, 71 insertions, 37 deletions
diff --git a/docs/build-instruction.rst b/docs/build-instruction.rst
index 32883c9..c1119c7 100644
--- a/docs/build-instruction.rst
+++ b/docs/build-instruction.rst
@@ -55,19 +55,31 @@ On the host, the following packages must be installed:
- An x86_64 host (Bare-metal or VM) with Ubuntu 14.04 LTS installed
- - A kernel equal- or later than 3.19 (Vivid) (simply available through sudo apt-get install linux-generic-lts-vivid)
-
- **Note:** Builds on Wily (Ubuntu 15.x) are currently not supported
-- docker - see https://docs.docker.com/engine/installation/ubuntulinux/ for installation notes for Ubuntu 14.04. Tested against version 1.9.x and greater
+ - A kernel equal- or later than 3.19 (Vivid), simply available through:
+
+.. code-block:: bash
+
+ $ sudo apt-get install linux-generic-lts-vivid
+
+- docker - see https://docs.docker.com/engine/installation/ubuntulinux/ for
+ installation notes for Ubuntu 14.04. Tested against version 1.9.x and greater
+
+- git
-- git (simply available through $ sudo apt-get install git)
+- make
-- make (simply available through $ sudo apt-get install make)
+- curl
-- curl (simply available through $ sudo apt-get install curl)
+- fuseiso
-- fuseiso (simply available through $ sudo apt-get install fuseiso)
+Apart from docker, all other package requirements listed above are
+simply available through:
+
+.. code-block:: bash
+
+ $ sudo apt-get install git make curl fuseiso
Preparations
============
@@ -76,7 +88,9 @@ Setting up the Docker build container
-------------------------------------
After having installed Docker, add yourself to the docker group:
-$ sudo usermod -a -G docker [userid]
+.. code-block:: bash
+
+ $ sudo usermod -a -G docker [userid]
Also make sure to define relevant DNS servers part of the global
DNS chain in your </etc/default/docker> configuration file.
@@ -84,11 +98,13 @@ Uncomment, and modify the values appropriately.
For example:
-<DOCKER_OPTS=" --dns=8.8.8.8 --dns=8.8.8.4">
+.. code-block:: bash
+
+ DOCKER_OPTS=" --dns=8.8.8.8 --dns=8.8.8.4"
Then restart docker:
-.. code-block:: console
+.. code-block:: bash
$ sudo service docker restart
@@ -97,7 +113,7 @@ Setting up OPNFV Gerrit in order to being able to clone the code
- Start setting up OPNFV gerrit by creating a SSH key (unless you
don't already have one), create one with ssh-keygen
-- Add your generated public key in OPNFV Gerrit <https://gerrit.opnfv.org/>
+- Add your generated public key in OPNFV Gerrit (https://gerrit.opnfv.org/)
(this requires a Linux foundation account, create one if you do not
already have one)
@@ -108,20 +124,27 @@ Clone the armband@OPNFV code Git repository with your SSH key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now it is time to clone the code repository:
-$ git clone ssh://<Linux foundation user>@gerrit.opnfv.org:29418/armband
+.. code-block:: bash
+
+ $ git clone ssh://<Linux foundation user>@gerrit.opnfv.org:29418/armband
Now you should have the OPNFV ARMBAND repository with its
directories stored locally on your build host.
Check out the Brahmaputra release:
-$ cd armband
-$ git checkout brahmaputra.3.0
+
+.. code-block:: bash
+
+ $ cd armband
+ $ git checkout brahmaputra.3.0
Clone the armband@OPNFV code Git repository without a SSH key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can also opt to clone the code repository without a SSH key:
-$ git clone https://gerrit.opnfv.org:29418/gerrit/armband
+.. code-block:: bash
+
+ $ git clone https://gerrit.opnfv.org/gerrit/armband
Make sure to checkout the release tag as described above.
@@ -132,8 +155,7 @@ The build system is able to make use of a web proxy setup if the
http_proxy, https_proxy, no_proxy (if needed) and RSYNC_PROXY or
RSYNC_CONNECT_PROG environment variables have been set before invoking make.
-The proxy setup must permit port 80 (http), 443 (https) and 873
-(rsync).
+The proxy setup must permit port 80 (http), 443 (https) and 873 (rsync).
Important note about the host Docker daemon settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -143,9 +165,11 @@ for it to be able to pull the base Ubuntu 14.04 image from the Docker
registry before invoking make! In Ubuntu this is done by adding a line
like:
-export http_proxy="http://10.0.0.1:8888/"
+.. code-block:: bash
-to /etc/default/docker and restarting the Docker daemon.
+ export http_proxy="http://10.0.0.1:8888/"
+
+to </etc/default/docker> and restarting the Docker daemon.
Setting proxy environment variables prior to build
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -154,19 +178,23 @@ The build system will make use the following environment variables
that needs to be exported to subshells by using export (bash) or
setenv (csh/tcsh).
-| http_proxy (or HTTP_PROXY)
-| https_proxy (or HTTP_PROXY)
-| no_proxy (or NO_PROXY)
-| RSYNC_PROXY
-| RSYNC_CONNECT_PROG
+.. code-block:: bash
+
+ http_proxy (or HTTP_PROXY)
+ https_proxy (or HTTP_PROXY)
+ no_proxy (or NO_PROXY)
+ RSYNC_PROXY
+ RSYNC_CONNECT_PROG
As an example, these are the settings that were put in the user's
.bashrc when verifying the proxy build functionality:
-| export RSYNC_PROXY=10.0.0.1:8888
-| export http_proxy=http://10.0.0.1:8888
-| export https_proxy=http://10.0.0.1:8888
-| export no_proxy=localhost,127.0.0.1,.consultron.com,.sock
+.. code-block:: bash
+
+ export RSYNC_PROXY=10.0.0.1:8888
+ export http_proxy=http://10.0.0.1:8888
+ export https_proxy=http://10.0.0.1:8888
+ export no_proxy=localhost,127.0.0.1,.consultron.com,.sock
Using a ssh proxy for the rsync connection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -192,8 +220,8 @@ of this process rsync is used.
If neither of the two available methods for proxying rsync are
available, the last resort is to turn off the caching of the Ubuntu
packages in the build system. This is done by removing the
-"f_repobuild" from SUBDIRS in the beginning of
-the armband/upstream/fuel/build/f_isoroot/Makefile.
+"f_repobuild" from SUBDIRS in the beginning of the
+<armband/upstream/fuel/build/f_isoroot/Makefile>.
Note! Doing this will require the Fuel master node to have Internet
access when installing the ISO artifact built as no Ubuntu package
@@ -203,8 +231,11 @@ Note! Armband build system uses git submodules to track fuel and
other upstream repos, so in order to apply the above change, one
should first initialize the submodules and apply armband patches
(only needed once):
-$ make submodules-init
-$ make patches-import
+
+.. code-block:: bash
+
+ $ make submodules-init
+ $ make patches-import
Configure your build environment
--------------------------------
@@ -213,10 +244,13 @@ Configure your build environment
standard Brahmaputra release **
Select the versions of the components you want to build by editing the
-armband/upstream/fuel/build/config.mk file.
+<armband/upstream/fuel/build/config.mk> file.
Note! The same observation as above, before altering Makefile, run:
-$ make submodules-init patches-import
+
+.. code-block:: bash
+
+ $ make submodules-init patches-import
Non official build: Selecting which plugins to build
----------------------------------------------------
@@ -226,7 +260,7 @@ build (if any) can be done by environment variable
"BUILD_FUEL_PLUGINS" prior to building.
Only the plugin targets from
-armband/upstream/fuel/build/f_isoroot/Makefile that are
+<armband/upstream/fuel/build/f_isoroot/Makefile> that are
specified in the environment variable will then be built. In order to
completely disable the building of plugins, the environment variable
is set to " ". When using this functionality, the resulting iso file
@@ -295,8 +329,8 @@ Artifacts
The artifacts produced are:
-- <OPNFV_XXXX.iso> - Which represents the bootable Fuel for AArch64 image,
- XXXX is replaced with the build identity provided to the build system
+- <OPNFV_XXXX.iso> - Which represents the bootable (x86_64) Fuel for AArch64
+ image, XXXX is replaced with the build identity provided to the build system
- <OPNFV_XXXX.iso.txt> - Which holds version metadata.