Patching
This guide covers how to create and manage patches for Garden Linux packages, following the best practices from PATCHING.MD.
When to Create Patches
Patches are needed when:
- Fixing bugs in upstream source code
- Applying security fixes from upstream to older versions
- Customizing package behavior for Garden Linux
- Updating the debian/ folder configuration
- Backporting features or fixes to a specific version
Prerequisites
To create patches, you need:
- The
package-buildtools installed locally - Git
- Access to the package repository
- Basic understanding of quilt
Step1: Prepare Your Local Sources
First, you need the complete package sources with all patches applied exactly as the GitHub Actions pipeline would do.
./package-build/build --leave-artifacts --source-only package-<package_name>This command:
- Calls the
package-build/bin/sourcescript in a container - Places the source in
package-<package_name>/output/run-<datetime>/a - Creates a copy in
package-<package_name>/output/run-<datetime>/b - Keeps the sources even if patch application fails
WARNING
If building for arm64, include --arch arm64 in the build command. Cross-build for generating sources may cause issues.
INFO
If the source build fails to apply a patch, the sources are kept in the state where the process stopped, allowing you to fix the issue.
Step2: Spawn a Patch Environment
Use the edit mode to spawn a container with quilt already configured correctly:
./package-build/build --edit package-<package_name>This starts a Debian container with the output folder from the previous step mounted. The container has quilt pre-configured according to Debian standards, which is important for maintaining compatibility with patches pulled from salsa.debian.org.
The preparation is defined in package-build/bin/patchenv-init, so you can review those settings and use your local machine if preferred.
Step3: Make Your Changes
When working on patches, keep the a directory unchanged and make all your changes in the b directory. This allows you to create a proper diff between the original and modified sources.
Using Quilt
Quilt is the recommended tool for managing patches. Key commands:
| Command | Description |
|---|---|
quilt push | Apply a single patch |
quilt push -a | Apply all patches |
quilt push -f | Force apply patches |
quilt refresh | Update patch files after manual edits |
quilt add <file> | Add a new file to be patched |
quilt remove <file> | Remove a file from the patch |
TIP
Use quilt series to see all patches in order and quilt applied to see which are already applied.
External Quilt References
- Debian Wiki: Using Quilt - Official guide
- Quilt Tutorial - Comprehensive tutorial (GNU FDL licensed)
- Refresh a patch that failed to apply - Debian guide for fixing broken patches
Step4: Create the Patch
The diff between the original a directory and your modified b directory becomes your patch.
diff -Naur a/ b/ > <name-of-your-patch>.patchTIP
If you know which file was modified, create a focused patch:
diff -Naur a/path/to/file b/path/to/file > fixes_debian/my-fix.patchStep5: Add the Patch to the Package
Depending on the type of patch, place it in the appropriate directory and update the prepare_source script.
For debian/ folder patches
Place patches in a fixes_debian directory and apply them in prepare_source:
apply_patches fixes_debianFor upstream source patches
Place patches in an upstream_patches directory and import them in prepare_source:
import_upstream_patches# upstream_patchesCreating the directory
If the directory doesn't exist, create it and add the patch:
mkdir -p fixes_debian
mv <name-of-your-patch>.patch fixes_debian/Then add the patch to the series file:
echo "<name-of-your-patch>" >> fixes_debian/seriesINFO
The series file lists all patches in the order they should be applied.
Patch Organization
Follow these conventions for patch organization:
| Patch Type | Directory | Application Method |
|---|---|---|
| debian/ folder changes | fixes_debian | apply_patches |
| upstream source changes | upstream_patches | import_upstream_patches# |
| build dependency patches | fixes_build_dep | apply_patches |
| local customization patches | gardenlinux_patches | import_upstream_patches# |