Working with patches

OpenWrt Buildroot integrates quilt for easy patch management. This document outlines some common patching tasks like adding a new patch or editing existing ones.

In order to let quilt create patches in OpenWrts preferred format, a configuration file .quiltrc containing common diff and patch options must be created in the local home directory.

cat > ~/.quiltrc <<EOFQUILT_DIFF_ARGS="--no-timestamps --no-index -pab --color=auto"QUILT_REFRESH_ARGS="--no-timestamps --no-index -pab"QUILT_PATCH_OPTS="--unified"QUILT_DIFF_OPTS="-p"EDITOR="nano"EOF

• EDITOR specifies the preferred editor for interactive patch editing
• The other variables control the patch format property like a/, b/ directory names and no timestamps
• FreeBSD does not support the --color=auto option and -pab must be written as -p ab

To add a completely new patch to an existing package example start with preparing the source directory:

For host-side packages, you may want to detail the make target:

This unpacks the source tarball and prepares existing patches as quilt patch series (if any). The verbose output will show where the source got extracted.

Change to the prepared source directory.

Note : It can happen that you need to go one level lower as the source is extracted in build_dir/target-*/BUILD_VARIANT/example-* . This happens when multiple build variants of a package are defined in the Makefile.

Apply all existing patches using quilt push.

Create a new, empty patch file with the quilt new command:

• The name should start with a number, followed by a hyphen and a very short description of what is changed
• The choosen number should be higher than any existing patch - use quilt series to see the list of patches
• The patch file name should be short but descriptive

After creating the empty patch, files to edit must be associated with it. The quilt add command can be used for that - once the file got added it can be edited as usual.
A shortcut for both adding a file and open it in an editor is the quilt edit command:

• src/main.c gets added to 010-main_code_fix.patch
• The file is opened in the editor specified with EDITOR in .quiltrc

Repeat that for any file that needs to be edited.

After the changes are finished, they can be reviewed with the quilt diff command.

If the diff looks okay, proceed with quilt refresh to update the 010-main_code_fix.patchfile with the changes made.

Change back to the toplevel directory of the buildroot.

To move the new patch file over to the buildroot, run update on the package:

Finally rebuild the package to test the changes:

If problems occur, the patch needs to be edited again to solve the issues.Refer to the section below to learn how to edit existing patches.

Start with preparing the source directory:

Change to the prepared source directory.

List the patches available:

Advance to the patch that needs to be edited:

• When passing a valid patch filename to push, quilt will only apply the series until it reaches the specified patch
• If unsure, use quilt series to see existing patches and quilt top to see the current position
• If the current position is beyound the desired patch, use quilt pop to remove patches in the reverse order

Edit the patched files using the quilt edit command, repeat for every file that needs changes.

Check which files are to be included in the patch:

Review the changes with quilt diff.

If the diff looks okay, proceed with quilt refresh to update the current patch with the changes made.

Change back to the toplevel diretory of the buildroot.

To move the updated patch file over to the buildroot, run update on the package:

Finally rebuild the package to test the changes:

The process for modifying kernel patches is the same as for packages, only the make targets and directories differ.
For the kernel, an additional subdirectory for patches is used, generic/ contains patches common to all architectures and platform/ contains patches specific to the current target.

To prepare the kernel tree, use:

For Attitude Adjustment, the source tree is in the linux-architecture subdirectory:

For Barrier Breaker (trunk), the source tree is in the target-architecture subdirectory (potentially with a subarch):

Moving the changes back over to the buildroot tree from the build tree is done with:

( Patches should be named with the correct prefix, platform/000-abc.patch or generic/000-abc.patch. If not the update may not work correctly.)

Afterwards, if we want to verify whether our patch is applied or not, we can go to the top level directory with

and preparing again the linux folder for some modification with

During this process all the applied patched will be shown, ours being among them, preceeded by generic/ or platform/ depending on what directory we placed the patch. Another way of retrieving the applied patches is through

as explained on the previous sections, after having made make target/linux/{clean,prepare} …

For example, gcc:

To prepare the tool tree, use:

The source tree depends on chosen lib and gcc :

Refreshing the patches is done with:

When a patched package (or kernel) is updated to a newer version, existing patches might notapply cleanly anymore and patch will report fuzz when applying them. To rebase thewhole patch series the refresh make target can be used:

For kernels, use:

When implementing new changes, it is often required to edit patches multiple times.To speed up the process, it is possible to retain the prepared source tree betweenedit operations.

1. Initially prepare the source tree as documented above
2. Change to the prepared source directory
3. Advance to the patch needing changes
4. Edit the files and refresh the patch
5. Fully apply the remaining patches using quilt push -a (if any)
6. From the toplevel directory, run make package/example/{compile,install} or make target/linux/{compile,install} for kernels
7. Test the binary
8. If further changes are needed, repeat from step 2.
9. Finally run make package/example/update or make target/linux/update for kernels to copy the changes back to buildroot

• Official quilt man page
• How To Survive With Many Patches - Introduction to Quilt (PDF) (read online here)
• Applying patches newbie doubt