Skip to content

DOC: Remove outdated upstream package documentation #1746

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dmbaturin merged 3 commits into from
Jan 30, 2026
+125 −56
Merged

DOC: Remove outdated upstream package documentation #1746

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d5f8b33
Remove outdated upstream package documentation
teslazonda Jan 27, 2026
4e368a4
Add build.py details to upstream-packages.rst
teslazonda Jan 30, 2026
f530280
Fix line length lint errors
teslazonda Jan 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 125 additions & 56 deletions docs/contributing/upstream-packages.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
:lastproofread: 2025-11-30
:lastproofread: 2026-01-30

.. _upstream_packages:

Expand All @@ -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.
Loading