User Tools

Site Tools


doc:devel:patches

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
doc:devel:patches [2013/04/23 22:35]
jero patch: add clarification for host packages
doc:devel:patches [2016/11/17 10:36] (current)
kevindb [Prepare quilt configuration]
Line 1: Line 1:
 +====== Working with patches ======
 +OpenWrt Buildroot integrates //​[[wp>​Quilt (software)|quilt]]//​ for easy patch management.
 +This document outlines some common patching tasks like adding a new patch or editing existing ones.
 +
 +===== Prepare quilt configuration =====
 +
 +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.
 +
 +<​code>​cat > ~/.quiltrc <<EOF
 +QUILT_DIFF_ARGS="​--no-timestamps --no-index -p ab --color=auto"​
 +QUILT_REFRESH_ARGS="​--no-timestamps --no-index -p ab"
 +QUILT_SERIES_ARGS="​--color=auto"​
 +QUILT_PATCH_OPTS="​--unified"​
 +QUILT_DIFF_OPTS="​-p"​
 +EDITOR="​nano"​
 +EOF</​code>​
 +
 +  * ''​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''​
 +  * :!: "-p ab" is working with quilt 0.63 on Linux and is documented in man page.
 +===== Adding a new patch =====
 +
 +To add a completely new patch to an existing package //example// start with preparing the source directory:
 +
 +| ''​make package///​example///​{clean,​prepare} V=s **QUILT=1**''​ |
 +
 +For host-side packages, you may want to detail the make target:
 +
 +| ''​make package///​example///​host/​{clean,​prepare} V=s **QUILT=1**''​ |
 +
 +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. ​
 +
 +| ''​cd build_dir/​target-*/​example-*''​ |
 +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//.
 +
 +| ''​quilt push -a''​ |
 +
 +
 +Create a new, empty patch file with the //quilt new// command:
 +
 +| ''​quilt new 010-main_code_fix.patch''​ |
 +
 +  * The name should start with a number, followed by a hyphen and a very short description of what is changed
 +  * The chosen 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:
 +
 +| ''​quilt edit src/​main.c''​ |
 +
 +  * ''​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.
 +
 +| ''​quilt diff''​ |
 +
 +
 +If the diff looks okay, proceed with //quilt refresh// to update the ''​010-main_code_fix.patch''​
 +file with the changes made.
 +
 +| ''​quilt refresh''​ |
 +
 +
 +Change back to the toplevel directory of the buildroot.
 +
 +| ''​cd ../​../​../''​ |
 +
 +
 +To move the new patch file over to the buildroot, run //update// on the package:
 +
 +| ''​make package///​example///​update V=s''​ |
 +
 +
 +Finally rebuild the package to test the changes:
 +
 +| ''​make package///​example///​{clean,​compile} package/​index V=s''​ |
 +
 +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.
 +
 +===== Edit an existing patch =====
 +
 +Start with preparing the source directory:
 +
 +| ''​make package///​example///​{clean,​prepare} V=s **QUILT=1**''​ |
 +
 +
 +Change to the prepared source directory.
 +
 +| ''​cd build_dir/​target-*/​example-*''​ |
 +
 +List the patches available:
 +
 +| ''​quilt series''​ |
 +
 +Advance to the patch that needs to be edited:
 +
 +| ''​quilt push 010-main_code_fix.patch''​ |
 +
 +  * 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
 +  * You can use the "​force"​ push option (e.g. ''​quilt push -f 010-main_code_fix.patch''​) to interactively apply a broken (i.e. has rejects) patch
 +
 +
 +Edit the patched files using the //quilt edit// command, repeat for every file that needs changes.
 +
 +| ''​quilt edit src/​main.c''​ |
 +
 +Check which files are to be included in the patch:
 +
 +| ''​quilt files''​ |
 +
 +Review the changes with //quilt diff//.
 +
 +| ''​quilt diff''​ |
 +
 +
 +If the diff looks okay, proceed with //quilt refresh// to update the current patch with the changes made.
 +
 +| ''​quilt refresh''​ |
 +
 +
 +Change back to the toplevel diretory of the buildroot.
 +
 +| ''​cd ../​../​../''​ |
 +
 +
 +To move the updated patch file over to the buildroot, run //update// on the package:
 +
 +| ''​make package///​example///​update V=s''​ |
 +
 +
 +Finally rebuild the package to test the changes:
 +
 +| ''​make package///​example///​{clean,​compile} package/​index V=s''​ |
 +
 +
 +
 +===== Adding or editing kernel patches =====
 +
 +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:
 +| ''​make target/​linux/​{clean,​prepare} V=s **QUILT=1**''​ |
 +
 +For Attitude Adjustment, the source tree is in the linux-//​architecture//​ subdirectory:​
 +| ''​cd build_dir/​linux-*/​linux-3.*''​ |
 +
 +For Barrier Breaker (trunk), the source tree is in the target-//​architecture//​ subdirectory (potentially with a subarch):
 +| ''​cd build_dir/​target-*/​linux-*/​linux-3.*''​ |
 +
 +Moving the changes back over to the buildroot tree from the build tree is done with ( you need to go back to trunk to do this):
 +| ''​make target/​linux/​update package/​index V=s''​ |
 +
 +(:!: 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
 +| ''​cd ../​../​../​../''​ |
 +and preparing again the //linux// folder for some modification with
 +
 +| ''​make target/​linux/​{clean,​prepare} V=s QUILT=1''​ |
 +
 +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
 +
 +| ''​quilt series''​ |
 +
 +as explained on the previous sections, after having made //make target/​linux/​{clean,​prepare} ...//
 +
 +===== Adding or editing toolchain patches =====
 +
 +For example, gcc:
 +
 +To prepare the tool tree, use:
 +| ''​make toolchain/​gcc/​{clean,​prepare} V=99 **QUILT=1**''​ |
 +
 +The source tree depends on chosen lib and gcc :
 +| ''​cd build_dir/​toolchain-mips_r2_gcc-4.3.3+cs_uClibc-0.9.30.1/​gcc-4.3.3''​ |
 +
 +Refreshing the patches is done with:
 +| ''​make toolchain/​gcc/​update V=99''​ |
 +
 +
 +===== Naming patches =====
 +
 +valid for **target/​linux/​generic** and <​arch>:​
 +<​code>​
 +The patches-* subdirectories contain the kernel patches applied for every
 +OpenWrt target. All patches should be named '​NNN-lowercase_shortname.patch'​
 +and sorted into the following categories:
 +
 +0xx - upstream backports
 +1xx - code awaiting upstream merge
 +2xx - kernel build / config / header patches
 +3xx - architecture specific patches
 +4xx - mtd related patches (subsystem and drivers)
 +5xx - filesystem related patches
 +6xx - generic network patches
 +7xx - network / phy driver patches
 +8xx - other drivers
 +9xx - uncategorized other patches
 +
 +ALL patches must be in a way that they are potentially upstreamable,​ meaning:
 +
 +- they must contain a proper subject
 +- they must contain a proper commit message explaining what they change
 +- they must contain a valid Signed-off-by line
 +</​code>​
 +from: [[https://​dev.openwrt.org/​browser/​trunk/​target/​linux/​generic/​PATCHES|PATCHES]]
 +
 +===== Refreshing patches =====
 +
 +When a patched package (or kernel) is updated to a newer version, existing patches might not
 +apply cleanly anymore and //patch// will report //fuzz// when applying them. To rebase the
 +whole patch series the //refresh// make target can be used:
 +
 +| ''​make package///​example///​refresh V=s''​ |
 +
 +For kernels, use:
 +
 +| ''​make target/​linux/​refresh V=s''​ |
 +
 +
 +===== Iteratively modify patches without cleaning the source tree  =====
 +
 +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 between
 +edit operations.
 +
 +  - Initially prepare the source tree as documented above
 +  - Change to the prepared source directory
 +  - Advance to the patch needing changes
 +  - Edit the files and refresh the patch
 +  - Fully apply the remaining patches using //quilt push -a// (if any)
 +  - From the toplevel directory, run ''​make package///​example///​{compile,​install}''​ or ''​make target/​linux/​{compile,​install}''​ for kernels
 +  - Test the binary
 +  - If further changes are needed, repeat from step 2.
 +  - Finally run ''​make package///​example///​update''​ or ''​make target/​linux/​update''​ for kernels to copy the changes back to buildroot
 +
 +
 +===== Further information =====
 +
 +  * [[http://​linux.die.net/​man/​1/​quilt|Official quilt man page]]
 +  * [[http://​git.savannah.gnu.org/​cgit/​quilt.git/​plain/​doc/​quilt.pdf|How To Survive With Many Patches - Introduction to Quilt]] (PDF) (read online [[https://​docs.google.com/​viewer?​url=http%3A%2F%2Fgit.savannah.gnu.org%2Fcgit%2Fquilt.git%2Fplain%2Fdoc%2Fquilt.pdf|here]])
 +  * [[https://​forum.openwrt.org/​viewtopic.php?​id=43039|Applying patches newbie doubt]]