This is not for the faint of heart, yet it is easy to make relatively small changes safely and it is just as easy to make relatively major changes unsafely.

Because the changes are made in the bitkeeper source tree it is easy to remove them, and bitkeeper will help you to both remove them (when everything goes wrong) and keep them when changes are made in the parent archive (that's the bk: repository you cloned originally.)

The manual at http://www.bitkeeper.com/UG/ is fairly good as is the built in help bk help, but you need to know how to use the bitkeeper commands within the bitbake environment. To make a small change you will first need to find the problem package, it's all in the directory openembedded/packages/name-of-package.

Changing a package

Having found the package directory you can safely change any of the files by making them writable with:

Then simply change the file and rebuild. To ensure a rebuild happens go into the temporary directory and locate the stamps sub-directory (it will be in the same place as work, deploy, staging and cross). Remove all the stamp files for the package you changed and repeat the bitbake build. It doesn't do any harm to remove extra stamps, it just takes extra time. Here's a safe way:

Check the result, you may need to be more specific with the package name (e.g. you will often find that both package and package-native exist, removing package* removes some of the tools used in the build itself, which wastes time). When satisfied:

If in doubt remove the entire temporary directory and rebuild from scratch (overnight!)

Saving, or discarding, your changes

When you've finished hacking either discard your changes:

This loses the changes for ever. Alternatively keep them:

If you've hacked a lot of stuff just go into the top (openembedded) directory and execute:

BitKeeper will find everything that you have changed in the openembedded directory and all sub-directories, then give you neat window with all the changes (yes, you need to be running a Window System to do this). You should use this command on a regular basis to make sure you haven't left cruft lying around from previous hacks, you will be teased mercilessly if you complain about the bugs which result from this.

The last command allows you to check in or discard every change. Notice that this is just a change to your local repository - you can't harm anyone elses work by doing this. At the bottom of the window is a weird coloured item for a commit comment. The second you enter text into the sub-window for this the checkin button changes to commit. There's no harm in this either, indeed you must do this before you next execute bk pull!

Handling remote changes

When you pull BitKeeper tries very hard to merge in all the changes from the parent repository. However, if it finds a writable file (because you did a bk edit but then didn't check the result in) or if it finds a checked in change which has not been committed is this correct? it gives up on the pull. You then have start the pull again, after getting rid of (commit or discard) the problem.

[-jbowler: There must be a way of restarting from the PENDING changesets but I haven't found it yet.-]

When a remote change overlaps with one of your own you will end up running bk resolve. If you get scared at this point choose the option to discard the local change - the one you made - then go and remove all the associated changes. You will probably want to find out about changesets while doing this.

Tricks for hacking specific things

It's easy to change the bitbake files stored under bitkeeper and that's the only thing that can be permanently changed, but normally those files are patches to a remote source distribution. Hacking a patch file is neither fun nor a good idea.

Instead you probably want to MakeATemporaryChangeToTheOEBuild in the temporary bitbake working directory for the package and GenerateANewPatchForTheOEBuild. This can then be added to the files subdirectory of the package, using bk new, and incorporated into the bitbake build by editing the corresponding package-version.bb file. To do that simply add something like:

after the SRC_URI which already exists in the .bb file. Doing it this way (using +=) avoids merge problems when you pull a change to the .bb.

Incidentally the =1 in the patch qualifier is ignored, it doesn't make any difference to anything what you put there. There are some directives which the patch program, quilt does read (for example to change the name quilt uses for the patch). Unfortunately there is no page saying HowToMakeAPatchWorkWithQuilt? anywhere in the bitbake manual or the OE wiki.