[[PageOutline]]

= Patching OpenWrt =

The OpenWrt Linux distribution like most other distributions consists of a build system that fetches, prepares, patches, compiles, and creates packages for various kernel and userspace components.  Often patches are necessary to upstream source to either make it appropriate for embedded systems, OpenWrt in general, or to simply add a feature or fix a bug that you need.

The patch process is fairly straight-forward but does take some getting used to and can differ between kernel, out-of-tree kernel-modules, and userspace packages slightly.

== Patching a Package ==
For this example we will patch busybox

Steps:
 * shell1 cd to the OpenWrt trunk and prepare the package for development using quilt to track patches:
{{{
make package/busybox/{clean,prepare} QUILT=1 V=s
}}}
 * open a new shell2 into the package build directory (this differs depending on the target you are working with and the package name/version):
{{{
cd build_dir/target-arm_v6k_uClibc-0.9.33.2_eabi/busybox-1.19.4
}}}
 * understand the current patches:
{{{
quilt series ;# show all patches in series
quilt top ;# show current patch in series
quilt files ;# show files in the current patch
quilt diff ;# show the current patch
quilt refresh ;# update current patch
}}}
 * tell quilt you want to make a new patch
{{{
quilt new 999-fix_foo.patch
}}}
 * add/edit files to patch (using 'quilt edit' is a good way to avoid forgetting to add a file to a patch):
{{{
quilt edit foo/foo.c
}}}
 * in shell1 rebuild and test your package - repeat this edit/rebuild process until you are satisfied with your changes:
{{{
make package/busybox/{compile,install} V=s  ;# build
make package/index ;# rebuild package indexes if you are using opkg to update/test modules
make -j8 V=s ;# rebuild entire image if you are using that to test your changes
}}}
 * when satisfied update the patches in the kernel tree
{{{
make target/busybox/update ;# copy patches from build dir back to package dir
ls package/busybox/patches ;# notice your patch
}}}

== Patching the Kernel ==
OpenWrt kernel patching differs from package patching in the following ways:
 * quilt is always enabled in the kernel tree
 * there are 2 sets of patches:
  * generic - from target/linux/generic/patches* that apply to the kernel in general
  * platform - from target/linux/<target>/patches* that apply to the target platform only

Steps:
 * shell1 cd to the OpenWrt trunk and prepare the kernel for development using quilt to track patches:
{{{
make target/linux/{clean,prepare} V=s
}}}
 * open a new shell2 into the kernel build directory (this differs depending on the target/kernel you are working with):
{{{
cd build_dir/target-arm_v6k_uClibc-0.9.33.2_eabi/linux-cns3xxx/linux-3.8.6/
}}}
 * understand the current patches:
{{{
quilt series ;# show all patches in series
quilt top ;# show current patch in series
quilt files ;# show files in the current patch
quilt diff ;# show the current patch
quilt refresh ;# update current patch
}}}
 * tell quilt you want to make a new patch
{{{
quilt new platform/999-fix_foo.patch
}}}
 * add/edit files to patch (using 'quilt edit' is a good way to avoid forgetting to add a file to a patch):
{{{
quilt edit drivers/foo/foo.c
}}}
 * in shell1 rebuild and test your package - repeat this edit/rebuild process until you are satisfied with your changes:
{{{
make target/linux/{compile,install} V=s  ;# build kernel and modules
make package/index ;# rebuild package indexes if you are using opkg to update/test modules
make -j8 V=s ;# rebuild entire image if you are using that to test your kernel/modules
}}}
 * when satisfied update the patches in the kernel tree
{{{
make target/linux/update
}}}

== Pushing patches upstream ==
It is highly recommended that you push your patches upstream so that you don't have to maintain them in the future.  This can be tricky as it is required that you apply/test/format your patch on the latest upstream OpenWrt.  You will have to decide if this is appropriate for you.  If you do not push your patch upstream you will need to maintain it in your build directory manually.  You can look at the scripts/makepatch script that Gateworks uses to maintain our patches against OpenWrt.  We strive to continually push our patches upstream. 

== Applying a .patch file to build ==
If a .patch file is acquired from somewhere, this is how you would apply it to a build of OpenWrt.
 1. Place the .patch file in the trunk directory
 2. Depending on the structure of the patch, do a dry run:
  1. 
{{{
patch -p0 --dry-run < ath10kpatch.patch
}}}
 3. If the patch looks good, then apply the patch, knowing you will modify the code:
  1. 
{{{ 
patch -p0 < ath10kpatch.patch 
}}}
 4. Rebuild using make -j8 v=99 in the working directory now.