If you have completed some temporary changes to the OpenEmbedded
build, as described in MakeATemporaryChangeToTheOEBuild, you may
want to preserve the changes across a
bk pull or a complete
rebuild. This is particularly the case if the changes affect other
packages - for example a change to the compiler configuration. In
that case you can only be sure that everything is correct by
rebuilding from scratch, and that will destroy temporary changes!
To store the changes you need to generate a new patch for the OpenEmbedded package which you edited and store that in the bitbake source tree - in the package directory underneath
What is a patch?
A patch, in this context, is a text file recording the difference
between your new set of sources for the package and the old set.
Conventionally the difference is recorded as the output of the
diff(1) using the -u (unified) option. This
outputs the changed lines of original and new source files along with a few adjacent lines of context. Each line is preceded by a
single flag character:
- <space character>
- The line is unchanged
- + <plus character>
- This is a new line from the new source file which does not occur in the old source file.
- - <minus character>
- This is an old line which does not occur in the new file.
Thus changed lines appear twice - once with a
- and once with a
A single patch file may contain changes for multiple source files, each source file is introduced by three lines documenting the
diff command, the original source file and the new one.
Identifying the source file
The patch itself is unambiguous - it says exactly which lines to change and the context allows for some error detection and correction. Unfortunately working out which file to patch is difficult - some conventions have to be followed to ensure that the files are identifiable.
The OpenEmbedded builds behave as though the file names in the patch file are relative to the working directory -
work/package-name. So long as the new file name is correct relative to this directory and so long as it is the name of a downloaded source file the patch will work.
Details of quilt
In the current OpenEmbedded builds patches are applied by the program
quilt. This gets built right at the start of the build. You may be more familiar with the original implementation of the program
patch by Larry Wall.
quilt, when used in the OpenEmbedded builds, seems to behave as follows:
- Identify the downloaded source subdirectory in the
work/package-name directory. This is the variable
S in the
.bb file. It should always be an immediate subdirectory of the working directory and this may be a requirement of
quilt. jbowler: I haven't confirmed this
- Copy the patch file into the
patches subdirectory of
S, the patch is automagically renamed by
quilt but the name may be specified in the
cd to the
S directory and execute the equivalent of
patch -p1 with the patch file.
If you are familiar with
patch this is probably all you need to know.
If you are not the important points are:
- The first part of the file path name is stripped off from each file name in the patch (
- The remainder is a name relative to the source directory - not the working directory!
- Even though one directory is stripped off, to be safe and to make the patch easier to understand make sure the directory is the correct, source, sub-directory!
Making a patch
These are step by step instructions assuming you have the original file (
subdir/file.orig) and that the changed file is
If you don't have the original files rename the working directory (the whole directory), remove all the package stamps and run bitbake to rebuild the package. Now the original file will be somewhere like
../../package-name/subdir/file - that's fine, you can hand edit the patch file to simplify the original names if you wish.
cd to the working directory - the parent directory of the source download (
- for each modified file execute the command (on one line):
diff >>my-new-patch -u source-subdir/subdir/file.orig source-subdir/subdir/file
- copy the file
my-new-patch into the OpenEmbedded files directory of the package. Depending on the package this might be just
openembedded/packages/package-name or it might be something like
package-name-version in the same directory.
Using a patch
.bb file for the package to include the patch. Simply add:
after the existing
SRC_URI assignment. Appending to the value rather than changing the original assignment means that:
- If a new patch is added upstream the
bk merge of this on your next
bk pull will not fail.
- Your patch will always be done after the upstream ones - it may fail after a change but that's easy to fix.
Changing the name of a patch
Sometimes bitbake makes some bad decisions about naming patches. For example the
mm1 patch for the
2.6.11 kernel source is called
2.6.11-mm1, bitbake chooses to reduce this name to
2.6. It regards the
11-mm1 as a file name extension. Since this patch comes from
ftp.kernel.org renaming it is not an option.
Instead bitbake allows the patch name to be specified with the
pname qualifier. The line for the kernel patch becomes something like