From 5d6fa52b8985f8068314aba26878a1d7d5cb84e5 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 20:42:32 +0300 Subject: feat: flip swap mechanism — MD as primary, RST as override (Phase 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is the first of three phases inverting the per-page swap mechanism so MD becomes the canonical primary and RST becomes the rare override. Phase 1 — file renames + conf.py exclude_patterns flip only: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 254 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 254 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty comment-only since no pages need the RST fallback right now - conf.py exclude_patterns flipped: rst-*.rst is now excluded by default instead of md-*.md - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce these names; for now no swap script runs because overrides list is empty) Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py with inverted rename direction, delete scripts/import_myst.py + tests, and update tests/test_swap_sources.py for the new semantics. Phase 3 will be the cleanup pass and ready-for-review flip. Generated by robots https://vyos.io --- docs/contributing/upstream-packages.md | 147 +++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/contributing/upstream-packages.md (limited to 'docs/contributing/upstream-packages.md') diff --git a/docs/contributing/upstream-packages.md b/docs/contributing/upstream-packages.md new file mode 100644 index 00000000..fe01df82 --- /dev/null +++ b/docs/contributing/upstream-packages.md @@ -0,0 +1,147 @@ +--- +lastproofread: '2026-01-30' +--- + +(upstream-packages)= + +# Upstream Packages + +Many base system packages are pulled straight from Debian's `main` and +`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. + +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. + +## 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: + +```console +cd package-build/ +./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: + +```{eval-rst} +**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: + + .. code-block:: toml + + pre_build_hook = "echo 'Preparing build environment'" + + Multi-line commands example: + + .. code-block:: toml + + pre_build_hook = """ + mkdir -p ../hello/vyos + mkdir -p ../vyos + cp example.txt ../vyos + """ + + Combined commands and scripts: + + .. code-block:: toml + + pre_build_hook = "ls -l; ./script.sh" + +**apply_patches** (Optional) + Boolean flag to control whether patches should be applied. Defaults to + ``True``. + + .. code-block:: toml + + apply_patches = false + +**prepare_package** (Optional) + Boolean flag to enable package preparation. When set to ``True``, the + ``install_data`` configuration is used. + +**install_data** (Optional) + Data used for package preparation when ``prepare_package`` is enabled. +``` + +## Example package.toml file + +Here's an example configuration for the FRRouting (FRR) package: + +```toml +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" +``` + + +## Build Output + +After running `./build.py`, the following artifacts are generated in the +package directory: + +- `.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 + +The build script also creates build dependency packages (`*build-deps*.deb`), +which are automatically cleaned up after the build completes. -- cgit v1.2.3