contribution: build: add section about building packages

This is copied from the vyos-build README.md with some changes and updates.

1 files changed, 102 insertions, 0 deletions

diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst
index bc113750..d158594e 100644
--- a/docs/contributing/build-vyos.rst
+++ b/docs/contributing/build-vyos.rst
@@ -121,6 +121,108 @@ Good luck!
    or ``rolling`` image. Make sure to choose the matching container for the
    version of VyOS that is being built.
 
+.. _build_packages:
+
+Build packages
+--------------
+
+VyOS requires a bunch of packages which are VyOS specific and thus can not be
+found in any Debian Upstream mirrror. Those packages can be found at the VyOS
+GitHub project (https://github.com/vyos) and there is a nice helper script
+available to build and list those individual packages.
+
+`scripts/build-packages` provides an easy interface to automate the process 
+of building all VyOS related packages that are not part of the upstream Debian 
+version. Execute it in the root of the `vyos-build` directory to start
+compilation.
+
+.. code-block:: none
+
+  $  scripts/build-packages -h
+  usage: build-packages [-h] [-c | -k | -f] [-v] [-l] [-b BUILD [BUILD ...]]
+                        [-p] [--blacklist BLACKLIST [BLACKLIST ...]]
+  
+  optional arguments:
+    -h, --help            show this help message and exit
+    -c, --clean           Re-clone required Git repositories
+    -k, --keep            Keep modified Git repositories
+    -f, --fetch           Fetch sources only, no build
+    -v, --verbose         Increase logging verbosity for each occurance
+    -l, --list-packages   List all packages to build
+    -b BUILD [BUILD ...], --build BUILD [BUILD ...]
+                          Whitespace separated list of packages to build
+    -p, --parallel        Build on all CPUs
+    --blacklist BLACKLIST [BLACKLIST ...]
+                          Do not build/report packages when calling --list
+
+Git repositoriers are automatically fetched and build on demand. If you want to
+work offline you can fetch all source code first with the `-f` option.
+
+The easiest way to compile is with the above mentioned Docker
+container, it includes all dependencies for compiling supported packages.
+
+.. code-block:: none
+
+  $ docker run --rm -it -v $(pwd):/vyos -w /vyos \
+               --sysctl net.ipv6.conf.lo.disable_ipv6=0 \
+               vyos-builder scripts/build-packages
+
+.. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is required to build the
+   `vyos-strongswan` package
+
+.. note::  Prior to executing this script you need to create or build the Docker
+   container and checkout all packages you want to compile.
+
+Building single package(s)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To build a single package use the same script as above but specify packages with
+`-b`:
+
+Executed from the root of `vyos-build`
+
+.. code-block:: none
+
+  $ docker run --rm -it -v $(pwd):/vyos -w /vyos/packages/PACKAGENAME \
+               --sysctl net.ipv6.conf.lo.disable_ipv6=0 \
+               vyos-builder scripts/build-packages -b <package>
+
+.. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is only needed when
+   building `vyos-strongswan` and can be ignored on other packages.
+
+.. note:: `vyos-strongswan` will only compile on a Linux system, running on
+   macOS or Windows might result in a unittest deadlock (it never exits).
+
+Building single packages from your own repositories
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also build packages that are not from the default git repositories,
+for example from your own forks of the official vyos repositories.
+
+First create a directory "packages" at the top level of the vyos-build
+repository and clone your package into it (creating a subdirectory with the
+package contents). Then checkout the correct branch or commit you want to build
+before building the package.
+
+Example using `git@github.com:myname/vyos-1x.git` repository to build vyos-1x:
+
+.. code-block:: none
+
+  $ mkdir packages
+  $ cd packages
+  $ git clone git@github.com:myname/vyos-1x.git
+  $ cd ..
+  $ docker run --rm -it -v $(pwd):/vyos -w /vyos/packages/PACKAGENAME \
+               --sysctl net.ipv6.conf.lo.disable_ipv6=0 \
+               vyos-builder scripts/build-packages -b vyos-1x
+
+.. note:: You need to git pull manually after you commit to the remote and
+   before rebuilding, the local repository won't be updated automatically.
+
+.. warning:: Any packages in the packages directory will be added to the iso
+   during build, replacing the upstream ones. Make sure you delete them (both
+   the source directories and built deb packages) if you want to build an iso
+   from purely upstream packages.
 
 
 .. _upstream_packages: