From 792617899e4f2f82fe1bc2dde71d62cee1ac5d4c Mon Sep 17 00:00:00 2001 From: Christian Breunig Date: Sat, 7 Nov 2026 07:38:37 +0100 Subject: docs: build-vyos: document build.py kernel build wrapper build-kernel.sh only builds the kernel. The build.py wrapper in scripts/package-build/linux-kernel installs the build dependencies, fetches and verifies the kernel source, builds the kernel and all firmware and out-of-tree modules defined in package.toml. - Document build.py usage and its --packages and --install-dependencies options. - Update paths from packages/linux-kernel to scripts/package-build/linux-kernel and from data/defaults.json to data/defaults.toml; drop references to the removed Jenkinsfile. - Update the out-of-tree module list to match package.toml. - Drop the per-module build instructions which referenced renamed or removed helper scripts, and the no longer existing ADD_FW_FILES. --- docs/contributing/build-vyos.md | 151 ++++++++++++++-------------------------- 1 file changed, 54 insertions(+), 97 deletions(-) (limited to 'docs') diff --git a/docs/contributing/build-vyos.md b/docs/contributing/build-vyos.md index ab8875a5..6c061a53 100644 --- a/docs/contributing/build-vyos.md +++ b/docs/contributing/build-vyos.md @@ -255,21 +255,25 @@ package during the ISO build. ### Linux Kernel The Linux kernel used by VyOS is heavily tied to the ISO build process. The -file `data/defaults.json` hosts a JSON definition of the kernel version used -`kernel_version` and the `kernel_flavor` of the kernel which represents the -kernel's LOCAL_VERSION. Both together form the kernel version variable in the -system: +file `data/defaults.toml` defines the kernel version (`kernel_version`) and +the `kernel_flavor`, which represents the kernel's LOCALVERSION. Together they +form the kernel release string of the system: ```none vyos@vyos:~$ uname -r 6.18.60-vyos ``` -VyOS ships the following out-of-tree kernel modules: +In addition to the kernel itself, VyOS ships firmware and out-of-tree kernel +modules that must be built against the exact same kernel: +- Linux firmware (`vyos-linux-firmware`) - Accel-PPP -- Intel NIC drivers +- Intel NIC drivers (igb, ixgbe, ixgbevf, i40e, ice, iavf) - Intel QAT +- Mellanox OFED +- Realtek NIC drivers (r8126, r8152) +- Jool, ipt-netflow and the RTSP NAT helper Each of those modules holds a dependency on the kernel version and if you are lucky enough to receive an ISO build error which sounds like: @@ -286,128 +290,81 @@ The most obvious reasons could be: - `vyos-build` repo is outdated, please `git pull` to update to the latest release kernel version from us. - You have your own custom kernel `*.deb` packages in the `packages` folder but - neglected to create all required out-of tree modules like Accel-PPP, Intel - QAT or Intel NIC drivers + neglected to build all required out-of-tree modules listed above. #### Building The Kernel -The kernel build is quite easy, most of the required steps can be found in the -`vyos-build/packages/linux-kernel/Jenkinsfile` but we will walk you through -it. +All kernel related build scripts live in +`vyos-build/scripts/package-build/linux-kernel`. The package list, the +pinned versions of all out-of-tree modules and the required build +dependencies are defined in `package.toml` in the same directory. -Clone the kernel source to `vyos-build/packages/linux-kernel/`: +Use the `build.py` wrapper to build the kernel. It performs all required +steps in one go: -```none -$ cd vyos-build/packages/linux-kernel/ -$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git -``` +1. Installs the Debian build dependencies listed in `package.toml`. +2. Downloads the kernel source for `kernel_version` from kernel.org and + verifies its signature, unless a `linux` source directory already exists. +3. Calls `build-kernel.sh`, which applies the patches from the `patches` + folder, generates the kernel configuration and builds the Debian + packages. +4. Builds the firmware package and all out-of-tree modules from + `package.toml` against the freshly built kernel. -Check out the required kernel version - see `vyos-build/data/defaults.json` -file (example uses kernel 6.18.60): +Run it from within the build container: ```none -$ cd linux -$ git checkout v6.18.60 +$ cd vyos-build/scripts/package-build/linux-kernel +$ ./build.py ``` -Now you can use the helper script `build-kernel.sh`, which completes all -the necessary steps: applying required patches from the -`vyos-build/packages/linux-kernel/patches` folder, copying the kernel -configuration `x86_64_vyos_defconfig` to the correct location, and building -the Debian packages. - :::{note} Building the kernel will take some time depending on the speed and quantity of your CPU/cores and disk speed. Expect 20 minutes (or even longer) on lower end hardware. ::: -```none -(18:59) vyos_bld 412374ca36b8:/vyos/vyos-build/packages/linux-kernel [rolling] # ./build-kernel.sh -``` - -When complete, you will have kernel binary packages to use in your custom ISO -build. Place all `*.deb` files in the `vyos-build/packages` folder, where -the build process will use them automatically. - -##### Firmware - -If you upgrade your kernel or include new drivers you may need new firmware. -This builds a new `vyos-linux-firmware` package using the included helper -scripts. - -```none -$ cd vyos-build/packages/linux-kernel -$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git -$ ./build-linux-firmware.sh -$ cp vyos-linux-firmware_*.deb ../ -``` - -The script automatically detects which firmware blobs are needed based on the -built drivers. If detection fails, you can manually add files to -`vyos-build/packages/linux-kernel/build-linux-firmware.sh`: - -```bash -ADD_FW_FILES="iwlwifi* ath11k/QCA6390/*/*.bin" -``` - - -#### Building Out-Of-Tree Modules - -Building the kernel is one step. You must also build required out-of-tree -modules so the ABIs match. -Refer to `vyos-build/packages/linux-kernel/Jenkinsfile` -for all required modules and their versions. We show you how to build the -currently required modules. - -##### Accel-PPP - -First, clone the source code and check out the appropriate version: +To build only selected packages, pass their names as listed in +`package.toml`. The kernel must be built first, as all other packages +depend on it: ```none -$ cd vyos-build/packages/linux-kernel -$ git clone https://github.com/accel-ppp/accel-ppp.git +$ ./build.py --packages linux-kernel linux-firmware igb ixgbe ``` -Use the helper script and patches to build the package. Run the following -command: +To only install the build dependencies, run `./build.py --install-dependencies`. -```none -$ ./build-accel-ppp.sh -``` - -After compiling the packages you will find yourself the newly generated `*.deb` -binaries in `vyos-build/packages/linux-kernel` from which you can copy them -to the `vyos-build/packages` folder for inclusion during the ISO build. - -##### Intel NIC +:::{note} +`build-kernel.sh` only builds the kernel itself. It does not install +dependencies or build firmware and out-of-tree modules, and it expects the +`KERNEL_FLAVOR` environment variable which `build.py` passes from +`data/defaults.toml`. Always prefer `build.py`. + +`build-kernel.sh` runs `git reset --hard` and `git clean -fdx` in the +`linux` directory. Copy any local modifications out of that directory +before you start a build. +::: -The Intel NIC drivers do not come from a Git repository. VyOS fetches the -tarballs from a mirror and compiles them. Use the following wrapper script -to build all driver modules: +When complete, you will find all generated `*.deb` files in the +`linux-kernel` directory. Copy them to the `vyos-build/packages` folder, +where the ISO build will use them automatically: ```none -./build-intel-drivers.sh +$ cp *.deb ../../../packages/ ``` -After compilation, find the generated `*.deb` binaries in -`vyos-build/packages/linux-kernel`. Copy them to the `vyos-build/packages` -folder for inclusion in the ISO build. - -##### Intel QAT +##### Firmware -The Intel QAT (Quick Assist Technology) drivers do not come from a Git -repository. VyOS fetches the tarballs from `01.org`, Intel's open-source -website. -Use the following wrapper script to build all driver modules: +If you upgrade your kernel or include new drivers you may need new firmware. +`build.py` builds the `vyos-linux-firmware` package from the +`linux-firmware` repository at the version pinned in `package.toml`: ```none -$ ./build-intel-qat.sh +$ ./build.py --packages linux-firmware ``` -After compiling the packages you will find yourself the newly generated `*.deb` -binaries in `vyos-build/packages/linux-kernel` from which you can copy them -to the `vyos-build/packages` folder for inclusion during the ISO build. +The firmware blobs are selected automatically from the network drivers of +the kernel built in the previous step, so build the kernel first. ### Troubleshooting -- cgit v1.2.3