diff options
Diffstat (limited to 'docs/contributing/upstream-packages.rst')
| -rw-r--r-- | docs/contributing/upstream-packages.rst | 181 |
1 files changed, 125 insertions, 56 deletions
diff --git a/docs/contributing/upstream-packages.rst b/docs/contributing/upstream-packages.rst index 78fe3745..c740b190 100644 --- a/docs/contributing/upstream-packages.rst +++ b/docs/contributing/upstream-packages.rst @@ -1,4 +1,4 @@ -:lastproofread: 2025-11-30 +:lastproofread: 2026-01-30 .. _upstream_packages: @@ -7,84 +7,153 @@ Upstream Packages ################# Many base system packages are pulled straight from Debian's ``main`` and -``contrib`` repositories, but there are exceptions. - -This page lists those exceptions and briefly describes changes made to -these packages. If you only want to build a fresh ISO image, you can skip +``contrib`` repositories, but there are exceptions. If you only want to build +a fresh ISO image, you can skip this section. This information may be useful for a deeper dive into VyOS. -``vyos-netplug`` ----------------- -VyOS uses a modified version because the upstream release sometimes causes -network interfaces to go down. +.. stop_vyoslinter + +System packages that are not directly pulled from Debian are built through a +separate build system, ``build.py`` in the `vyos-build <https://github.com/vyos/vyos-build/tree/current/scripts/package-build>`__ repository. + +.. start_vyoslinter + + +Overview +======== + +Previously, VyOS used Jenkins for building upstream packages. With the move away +from Jenkins, the build system was replaced with a Python-based solution using +``build.py`` and ``package.toml`` configuration files. + +Each package directory contains: + +- A ``package.toml`` configuration file that defines how the package is built. +- A symlink to the common ``build.py`` script in the build system. + + +Building Packages +================= + +To build a package, navigate to the package directory and execute the +build script: + +.. code-block:: console + + cd package-build/<package-name> + ./build.py + +The script will: + +1. Check out the source code from the configured repository. +2. Apply any patches defined in the configuration. +3. Execute pre-build hooks (if configured). +4. Build the package using the specified build command. +5. Generate both binary (``.deb``) packages and source tarballs. + + +Package Configuration (package.toml) +==================================== + +Each package directory contains a ``package.toml`` file that defines the build +parameters. The key configuration fields are: + +**name** + The package name (e.g., ``frr``) + +**commit_id** + The specific commit, tag, or branch to check out from the source repository + (e.g., ``stable/10.5``) + +**scm_url** + The Git URL of the upstream source repository + (e.g., ``https://github.com/FRRouting/frr.git``) + +.. stop_vyoslinter +**build_cmd** + The command to execute for building the package. This replaces what was + previously defined in the Jenkins ``Jenkinsfile``. + + Default if not specified: ``dpkg-buildpackage -uc -us -tc -F --source-option=--tar-ignore=.git --source-option=--tar-ignore=.github`` + + Example with custom build command: + + .. code-block:: toml + + build_cmd = "sudo dpkg -i ../*.deb; dpkg-buildpackage -us -uc -tc -b -Ppkg.frr.rtrlib,pkg.frr.lua" +.. start_vyoslinter + +**pre_build_hook** (Optional) + A shell command or script that executes after the repository is checked out + and before the build process begins. This allows you to perform preparatory + tasks such as: + + - Creating directories + - Copying files + - Running custom setup scripts + - Installing dependencies + + Single command example: -Source: https://github.com/vyos/vyos-netplug. + .. code-block:: toml -VyOS may switch to ``systemd`` in the future. Building the package does not -require a special procedure. + pre_build_hook = "echo 'Preparing build environment'" -``keepalived`` --------------- + Multi-line commands example: -``keepalived`` is not updated to newer feature releases between Debian releases. -VyoS builds it from source. + .. code-block:: toml -Debian maintains the package in git, but the upstream tarball was imported -without its original commit history. To allow merging new tags, we maintain -a fork with packaging files imported from -Debian: https://github.com/vyos/keepalived-upstream. + pre_build_hook = """ + mkdir -p ../hello/vyos + mkdir -p ../vyos + cp example.txt ../vyos + """ -``strongswan`` --------------- + Combined commands and scripts: -VyOS's StrongSWAN build differs from upstream: + .. code-block:: toml -- We disable the ``strongswan-nm`` package build because VyOS does not use - NetworkManager. -- We merged patches for DMVPN. + pre_build_hook = "ls -l; ./script.sh" -Source: https://github.com/vyos/vyos-strongswan +**apply_patches** (Optional) + Boolean flag to control whether patches should be applied. Defaults to + ``True``. -DMVPN patches were added in this commit: -https://github.com/vyos/vyos-strongswan/commit/1cf12b0f2f921bfc51affa3b81226 + .. code-block:: toml -VyOS's op-mode scripts use the ``python-vici`` module, which is not included -in Debian's build and is difficult to integrate. VyOS debianizes the module -manually: + apply_patches = false -1. Install ``stdeb`` from PyPI (for example: ``pip3 install stdeb``). -2. ``cd vyos-strongswan`` -3. ``./configure --enable-python-eggs`` -4. ``cd src/libcharon/plugins/vici/python`` -5. ``make`` -6. ``python3 setup.py --command-packages=stdeb.command bdist_deb`` +**prepare_package** (Optional) + Boolean flag to enable package preparation. When set to ``True``, the + ``install_data`` configuration is used. -The package is created in the ``deb_dist`` directory. +**install_data** (Optional) + Data used for package preparation when ``prepare_package`` is enabled. -``mdns-repeater`` ------------------ -This package does not exist in Debian. VyOS maintains a debianized fork at -https://github.com/vyos/mdns-repeater. +Example package.toml file +=========================== -No special build procedure is required. +Here's an example configuration for the FRRouting (FRR) package: -``udp-broadcast-relay`` ------------------------ +.. code-block:: toml -This package does not exist in Debian. VyOS maintain a debianized fork at -https://github.com/vyos/udp-broadcast-relay. + name = "frr" + commit_id = "stable/10.5" + scm_url = "https://github.com/FRRouting/frr.git" + build_cmd = "sudo dpkg -i ../*.deb; dpkg-buildpackage -us -uc -tc -b -Ppkg.frr.rtrlib,pkg.frr.lua" -No special build procedure is required. -``hvinfo`` ----------- +Build Output +============ -A fork with packaging changes for VyOS is available -at https://github.com/vyos/hvinfo. +After running ``./build.py``, the following artifacts are generated in the +package directory: -The original repository is at https://github.com/dmbaturin/hvinfo. +- ``.deb`` files - Binary Debian packages ready for installation +- ``.tar.gz`` files - Source tarballs of the checked-out repositories +- Additional build artifacts as produced by the Debian build system -It is an Ada program and requires GNAT and ``gprbuild``. Dependencies are -properly specified; follow the suggestions from ``debuild``. +The build script also creates build dependency packages (`*build-deps*.deb`), +which are automatically cleaned up after the build completes. |