The main use of Buildroot’s Patchwork website for a developer is for pulling in patches into their local git repository for testing purposes.

When browsing patches in the patchwork management interface, an mbox link is provided at the top of the page. Copy this link address and run the following commands:

Another option for applying patches is to create a bundle. A bundle is a set of patches that you can group together using the patchwork interface. Once the bundle is created and the bundle is made public, you can copy the mbox link for the bundle and apply the bundle using the above commands.

We expect patches to be formatted in a specific way. This is necessary to make it easy to review patches, to be able to apply them easily to the git repository, to make it easy to find back in the history how and why things have changed, and to make it possible to use git bisect to locate the origin of a problem.

First of all, it is essential that the patch has a good commit message. The commit message should start with a separate line with a brief summary of the change, prefixed by the area touched by the patch. A few examples of good commit titles:

The description that follows the prefix should start with a lower case letter (i.e "bump", "needs", "postpone", "add" in the above examples).

Second, the body of the commit message should describe why this change is needed, and if necessary also give details about how it was done. When writing the commit message, think of how the reviewers will read it, but also think about how you will read it when you look at this change again a few years down the line.

Third, the patch itself should do only one change, but do it completely. Two unrelated or weakly related changes should usually be done in two separate patches. This usually means that a patch affects only a single package. If several changes are related, it is often still possible to split them up in small patches and apply them in a specific order. Small patches make it easier to review, and often make it easier to understand afterwards why a change was done. However, each patch must be complete. It is not allowed that the build is broken when only the first but not the second patch is applied. This is necessary to be able to use git bisect afterwards.

Of course, while you’re doing your development, you’re probably going back and forth between packages, and certainly not committing things immediately in a way that is clean enough for submission. So most developers rewrite the history of commits to produce a clean set of commits that is appropriate for submission. To do this, you need to use interactive rebasing. You can learn about it in the Pro Git book. Sometimes, it is even easier to discard you history with git reset --soft origin/master and select individual changes with git add -i or git add -p.

Finally, the patch should be signed off. This is done by adding Signed-off-by: Your Real Name <your@email.address> at the end of the commit message. git commit -s does that for you, if configured properly. The Signed-off-by tag means that you publish the patch under the Buildroot license (i.e. GPL-2.0+, except for package patches, which have the upstream license), and that you are allowed to do so. See the Developer Certificate of Origin for details.

When adding new packages, you should submit every package in a separate patch. This patch should have the update to package/Config.in, the package Config.in file, the .mk file, the .hash file, any init script, and all package patches. If the package has many sub-options, these are sometimes better added as separate follow-up patches. The summary line should be something like <packagename>: new package. The body of the commit message can be empty for simple packages, or it can contain the description of the package (like the Config.in help text). If anything special has to be done to build the package, this should also be explained explicitly in the commit message body.

When you bump a package to a new version, you should also submit a separate patch for each package. Don’t forget to update the .hash file, or add it if it doesn’t exist yet. Also don’t forget to check if the _LICENSE and _LICENSE_FILES are still valid. The summary line should be something like <packagename>: bump to version <new version>. If the new version only contains security updates compared to the existing one, the summary should be <packagename>: security bump to version <new version> and the commit message body should show the CVE numbers that are fixed. If some package patches can be removed in the new version, it should be explained explicitly why they can be removed, preferably with the upstream commit ID. Also any other required changes should be explained explicitly, like configure options that no longer exist or are no longer needed.

If you are interested in getting notified of build failures and of further changes in the packages you added or modified, please add yourself to the DEVELOPERS file. This should be done in the same patch creating or modifying the package. See the DEVELOPERS file for more information.

Buildroot provides a handy tool to check for common coding style mistakes on files you created or modified, called check-package (see [check-package] for more information).

Starting from the changes committed in your local git view, rebase your development branch on top of the upstream tree before generating a patch set. To do so, run:

Now, you are ready to generate then submit your patch set.

To generate it, run:

This will generate patch files in the outgoing subdirectory, automatically adding the Signed-off-by line.

Once patch files are generated, you can review/edit the commit message before submitting them, using your favorite text editor.

Buildroot provides a handy tool to know to whom your patches should be sent, called get-developers (see [DEVELOPERS] for more information). This tool reads your patches and outputs the appropriate git send-email command to use:

Use the output of get-developers to send your patches:

Alternatively, get-developers -e can be used directly with the --cc-cmd argument to git send-email to automatically CC the affected developers:

git can be configured to automatically do this out of the box with:

And then just do:

Note that git should be configured to use your mail account. To configure git, see man git-send-email or google it.

If you do not use git send-email, make sure posted patches are not line-wrapped, otherwise they cannot easily be applied. In such a case, fix your e-mail client, or better yet, learn to use git send-email.

If you want to present the whole patch set in a separate mail, add --cover-letter to the git format-patch command (see man git-format-patch for further information). This will generate a template for an introduction e-mail to your patch series.

A 'cover letter' may be useful to introduce the changes you propose in the following cases:

When fixing bugs on a maintenance branch, bugs should be fixed on the master branch first. The commit log for such a patch may then contain a post-commit note specifying what branches are affected:

Those changes will then be backported by a maintainer to the affected branches.

However, some bugs may apply only to a specific release, for example because it is using an older version of a package. In that case, patches should be based off the maintenance branch, and the patch subject prefix must include the maintenance branch name (for example "[PATCH 2020.02.x]"). This can be done with the git format-patch flag --subject-prefix:

Then send the patches with git send-email, as described above.

When improvements are requested, the new revision of each commit should include a changelog of the modifications between each submission. Note that when your patch series is introduced by a cover letter, an overall changelog may be added to the cover letter in addition to the changelog in the individual commits. The best thing to rework a patch series is by interactive rebasing: git rebase -i origin/master. Consult the git manual for more information.

When added to the individual commits, this changelog is added when editing the commit message. Below the Signed-off-by section, add --- and your changelog.

Although the changelog will be visible for the reviewers in the mail thread, as well as in patchwork, git will automatically ignores lines below --- when the patch will be merged. This is the intended behavior: the changelog is not meant to be preserved forever in the git history of the project.

Hereafter the recommended layout:

Any patch revision should include the version number. The version number is simply composed of the letter v followed by an integer greater or equal to two (i.e. "PATCH v2", "PATCH v3" …​).

This can be easily handled with git format-patch by using the option --subject-prefix:

Since git version 1.8.1, you can also use -v <n> (where <n> is the version number):

When you provide a new version of a patch, please mark the old one as superseded in patchwork. You need to create an account on patchwork to be able to modify the status of your patches. Note that you can only change the status of patches you submitted yourself, which means the email address you register in patchwork should match the one you use for sending patches to the mailing list.

You can also add the --in-reply-to <message-id> option when submitting a patch to the mailing list. The id of the mail to reply to can be found under the "Message Id" tag on patchwork. The advantage of in-reply-to is that patchwork will automatically mark the previous version of the patch as superseded.

Within the Buildroot repository, the testing framework is organized at the top level in support/testing/ by folders of conf, infra and tests. All the test cases live under the tests folder and are organized in various folders representing the category of test.

The best way to get familiar with how to create a test case is to look at a few of the basic file system support/testing/tests/fs/ and init support/testing/tests/init/ test scripts. Those tests give good examples of a basic tests that include both checking the build results, and doing runtime tests. There are other more advanced cases that use things like nested br2-external folders to provide skeletons and additional packages.

Creating a basic test case involves:

After creating the test script, add yourself to the DEVELOPERS file to be the maintainer of that test case.

When a test case runs, the output_folder will contain the following:

TestInitSystemBusyboxRw/ is the Buildroot output directory, and it is preserved only if the -k option is passed.

TestInitSystemBusyboxRw-build.log is the log of the Buildroot build.

TestInitSystemBusyboxRw-run.log is the log of the Qemu boot and test. This file will only exist if the build was successful and the test case involves booting under Qemu.

If you want to manually run Qemu to do manual tests of the build result, the first few lines of TestInitSystemBusyboxRw-run.log contain the Qemu command line to use.

You can also make modifications to the current sources inside the output_folder (e.g. for debug purposes) and rerun the standard Buildroot make targets (in order to regenerate the complete image with the new modifications) and then rerun the test.

All runtime tests are regularly executed by Buildroot Gitlab CI infrastructure, see .gitlab.yml and https://gitlab.com/buildroot.org/buildroot/-/jobs.

You can also use Gitlab CI to test your new test cases, or verify that existing tests continue to work after making changes in Buildroot.

In order to achieve this, you need to create a fork of the Buildroot project on Gitlab, and be able to push branches to your Buildroot fork on Gitlab.

The name of the branch that you push will determine if a Gitlab CI pipeline will be triggered or not, and for which test cases.

In the examples below, the <name> component of the branch name is an arbitrary string you choose.

Example to run one test:

Examples to run several tests part of the same group: