diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/build-vyos.rst | 114 |
1 files changed, 67 insertions, 47 deletions
diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 7b3a154d..83b4c84d 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -23,7 +23,7 @@ also set up your own build machine and run a :ref:`build_native`. The source code remains public and an ISO can be built using the process outlined in this chapter. -This will guide you though the process of building a VyOS ISO using Docker_. +This will guide you through the process of building a VyOS ISO using Docker_. This process has been tested on clean installs of Debian Jessie, Stretch, and Buster. @@ -59,11 +59,11 @@ yourusername``. Build Container --------------- -The container can built by hand or by fetching the pre-built one from DockerHub. -Using the pre-built containers from the `VyOS DockerHub organisation`_ will -ensure that the container is always up-to-date. A rebuild is triggered once the -container changes (please note this will take 2-3 hours after pushing to the -vyos-build repository). +The container can be built by hand or by fetching the pre-built one from +DockerHub. Using the pre-built containers from the `VyOS DockerHub +organisation`_ will ensure that the container is always up-to-date. A rebuild +is triggered once the container changes (please note this will take 2-3 hours +after pushing to the vyos-build repository). .. note: If you are using the pre-built container, it will be automatically downloaded from DockerHub if it is not found on your local machine when @@ -88,9 +88,11 @@ The container can also be built directly from source: # For VyOS 1.2 (crux) $ git clone -b crux --single-branch https://github.com/vyos/vyos-build - # For VyOS 1.3 (equuleus, current) + # For VyOS 1.3 (equuleus) + $ git clone -b equuleus --single-branch https://github.com/vyos/vyos-build + # For VyOS 1.4 (sagitta, current) $ git clone -b current --single-branch https://github.com/vyos/vyos-build - + $ cd vyos-build $ docker build -t vyos/vyos-build:crux docker # For VyOS 1.2 $ docker build -t vyos/vyos-build:current docker # For rolling release @@ -131,10 +133,11 @@ your development containers in your current working directory. .. note:: Some VyOS packages (namely vyos-1x) come with build-time tests which verify some of the internal library calls that they work as expected. Those - tests are carried out through the Python Unittest module. If you wan't to - build the ``vyos-1x`` package (which is our main development package) you need - to start your Docker container using the following argument: - ``--sysctl net.ipv6.conf.lo.disable_ipv6=0``, otherwise those tests will fail. + tests are carried out through the Python Unittest module. If you want to + build the ``vyos-1x`` package (which is our main development package) you + need to start your Docker container using the following argument: + ``--sysctl net.ipv6.conf.lo.disable_ipv6=0``, otherwise those tests will + fail. .. _build_native: @@ -145,7 +148,8 @@ To build VyOS natively you require a properly configured build host with the following Debian versions installed: - Debian Jessie for VyOS 1.2 (crux) -- Debian Buster for VyOS 1.3 (equuleus, current) - aka the rolling release +- Debian Buster for VyOS 1.3 (equuleus) +- Debian Bullseye for VyOS 1.4 (sagitta, current) - aka the rolling release To start, clone the repository to your local machine: @@ -154,11 +158,15 @@ To start, clone the repository to your local machine: # For VyOS 1.2 (crux) $ git clone -b crux --single-branch https://github.com/vyos/vyos-build - # For VyOS 1.3 (equuleus, current) + # For VyOS 1.3 (equuleus) + $ git clone -b equuleus --single-branch https://github.com/vyos/vyos-build + + # For VyOS 1.4 (sagitta, current) $ git clone -b current --single-branch https://github.com/vyos/vyos-build + For the packages required, you can refer to the ``docker/Dockerfile`` file -in the repository_. The ``./configure`` script will also warn you if any +in the repository_. The ``./build-vyos-image`` script will also warn you if any dependencies are missing. Once you have the required dependencies installed, you may proceed with the @@ -180,7 +188,10 @@ Please note as this will differ for both `current` and `crux`. # For VyOS 1.2 (crux) $ git clone -b crux --single-branch https://github.com/vyos/vyos-build - # For VyOS 1.3 (equuleus, current) + # For VyOS 1.3 (equuleus) + $ git clone -b equuleus --single-branch https://github.com/vyos/vyos-build + + # For VyOS 1.4 (sagitta, current) $ git clone -b current --single-branch https://github.com/vyos/vyos-build Now a fresh build of the VyOS ISO can begin. Change directory to the @@ -192,9 +203,12 @@ Now a fresh build of the VyOS ISO can begin. Change directory to the # For VyOS 1.2 (crux) $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:crux bash - # For VyOS 1.3 (equuleus, current) - $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash + # For VyOS 1.3 (equuleus) + $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:equuleus bash + # For VyOS 1.4 (sagitta, current) + $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash + .. code-block:: none # For MacOS (crux, equuleus, sagitta) @@ -214,8 +228,8 @@ Start the build: .. code-block:: none - vyos_bld@d4220bb519a0:/vyos# ./configure --architecture amd64 --build-by "j.randomhacker@vyos.io" - vyos_bld@d4220bb519a0:/vyos# sudo make iso + vyos_bld@8153428c7e1f:/vyos$ sudo make clean + vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" When the build is successful, the resulting iso can be found inside the ``build`` directory as ``live-image-[architecture].hybrid.iso``. @@ -234,46 +248,52 @@ Customize ========= This ISO can be customized with the following list of configure options. -The full and current list can be generated with ``./configure --help``: +The full and current list can be generated with ``./build-vyos-image --help``: .. code-block:: none - $ ./configure --help - usage: configure [-h] [--architecture ARCHITECTURE] [--build-by BUILD_BY] - [--debian-mirror DEBIAN_MIRROR] - [--debian-security-mirror DEBIAN_SECURITY_MIRROR] - [--pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR] - [--vyos-mirror VYOS_MIRROR] [--build-type BUILD_TYPE] - [--version VERSION] [--build-comment BUILD_COMMENT] [--debug] - [--custom-apt-entry CUSTOM_APT_ENTRY] - [--custom-apt-key CUSTOM_APT_KEY] - [--custom-package CUSTOM_PACKAGE] + $ vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image --help + I: Checking if packages required for VyOS image build are installed + usage: build-vyos-image [-h] [--architecture ARCHITECTURE] + [--build-by BUILD_BY] [--debian-mirror DEBIAN_MIRROR] + [--debian-security-mirror DEBIAN_SECURITY_MIRROR] + [--pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR] + [--vyos-mirror VYOS_MIRROR] [--build-type BUILD_TYPE] + [--version VERSION] [--build-comment BUILD_COMMENT] [--debug] [--dry-run] + [--custom-apt-entry CUSTOM_APT_ENTRY] [--custom-apt-key CUSTOM_APT_KEY] + [--custom-package CUSTOM_PACKAGE] + [build_flavor] - optional arguments: + positional arguments: + build_flavor Build flavor + + optional arguments: -h, --help show this help message and exit --architecture ARCHITECTURE - Image target architecture (amd64 or i386 or armhf) + Image target architecture (amd64 or arm64) --build-by BUILD_BY Builder identifier (e.g. jrandomhacker@example.net) --debian-mirror DEBIAN_MIRROR - Debian repository mirror for ISO build + Debian repository mirror --debian-security-mirror DEBIAN_SECURITY_MIRROR - Debian security updates mirror + Debian security updates mirror --pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR - Debian repository mirror for pbuilder env bootstrap + Debian repository mirror for pbuilder env bootstrap --vyos-mirror VYOS_MIRROR - VyOS package mirror + VyOS package mirror --build-type BUILD_TYPE - Build type, release or development + Build type, release or development --version VERSION Version number (release builds only) --build-comment BUILD_COMMENT - Optional build comment + Optional build comment --debug Enable debug output + --dry-run Check build configuration and exit --custom-apt-entry CUSTOM_APT_ENTRY - Custom APT entry + Custom APT entry --custom-apt-key CUSTOM_APT_KEY - Custom APT key file + Custom APT key file --custom-package CUSTOM_PACKAGE - Custom package to install from repositories + Custom package to install from repositories + .. _iso_build_issues: @@ -304,8 +324,8 @@ more or less similar looking error message: (10:13) vyos_bld ece068908a5b:/vyos [current] # To debug the build process and gain additional information of what could be the -root cause wou need to `chroot` into the build directry. This is explained in -the following step by step procedure: +root cause, you need to use `chroot` to change into the build directry. This is +explained in the following step by step procedure: .. code-block:: none @@ -729,7 +749,7 @@ package from our GitHub organisation - this is the place to be. Any "modified" package may refer to an altered version of e.g. vyos-1x package that you would like to test before filing a pull request on GitHub. -Building an ISO with any customized package is in no way different then +Building an ISO with any customized package is in no way different than building a regular (customized or not) ISO image. Simply place your modified `*.deb` package inside the `packages` folder within `vyos-build`. The build process will then pickup your custom package and integrate it into your ISO. @@ -771,7 +791,7 @@ Virtualization Platforms QEMU ---- -Run following command after building the ISO image. +Run the following command after building the ISO image. .. code-block:: none @@ -780,7 +800,7 @@ Run following command after building the ISO image. VMware ------ -Run following command after building the QEMU image. +Run the following command after building the QEMU image. .. code-block:: none |