docs/manual/contribute.txt

1 // -*- mode:doc; -*-
7 and fixing bugs, analyzing and fixing package build failures detected by
8 the autobuilders, testing and reviewing patches sent by other
9 developers, working on the items in our TODO list and sending your own
15 the main way of interacting with other Buildroot developers and to send
17 xref:community-resources[] for the subscription link.
21 source code tarball. Git is the easiest way to develop from and directly
22 send your patches to the mailing list. Refer to xref:getting-buildroot[]
25 === Reproducing, analyzing and fixing bugs
30 help in reproducing, analyzing and fixing reported bugs is more than
34 === Analyzing and fixing autobuild failures
36 The Buildroot autobuilders are a set of build machines that continuously
38 all architectures supported by Buildroot, with various toolchains, and
43 All build results are available at http://autobuild.buildroot.org[],
51 - Analyzing the problems. The daily summary mails do not contain details
53   open the build log and check the last output. Having someone doing
57 - Fixing a problem. When fixing autobuild failures, you should follow
61     http://git.buildroot.org/buildroot-test/tree/utils/br-reproduce-build[br-reproduce-build]
63     checkout the correct revision, download and set the right
64     configuration, and start the build.
65   . Analyze the problem and create a fix.
67     Buildroot tree and only applying your fix.
69     xref:submitting-patches[]). In case you created a patch against the
71     problem will be fixed in a later release, and the patch in Buildroot
74     reference to the build result directory, as follows:
75 ---------------------
77 ---------------------
79 === Reviewing and testing patches
83 and which ones aren't. Contributors can greatly help here by reviewing
84 and testing these patches.
88 understand the patches and make them better. Please use internet
94 approval tag below the original author's Signed-off-by line. These tags
96 xref:apply-patches-patchwork[]) and will be part of the commit log when
99 Tested-by:: Indicates that the patch has been tested successfully.
101   (compile-test on architecture X and Y, runtime test on target A,
102   ...). This additional information helps other testers and the
105 Reviewed-by:: Indicates that you code-reviewed the patch and did your
107   the area touched to provide an Acked-by tag. This means that there
110   detected, your Reviewed-by tag remains appropriate and you cannot
113 Acked-by:: Indicates that you code-reviewed the patch and you are
115   committed as-is (no additional changes required). In case it later
116   turns out that something is wrong with the patch, your Acked-by could
117   be considered inappropriate. The difference between Acked-by and
118   Reviewed-by is thus mainly that you are prepared to take the blame on
121 If you reviewed a patch and have comments on it, you should simply reply
122 to the patch stating these comments, without providing a Reviewed-by or
123 Acked-by tag. These tags should only be provided if you judge the patch
126 It is important to note that neither Reviewed-by nor Acked-by imply
127 that testing has been performed. To indicate that you both reviewed and
128 tested the patch, provide two separate tags (Reviewed/Acked-by and
129 Tested-by).
131 Note also that _any developer_ can provide Tested/Reviewed/Acked-by
132 tags, without exception, and we encourage everyone to do this. Buildroot
142 purposes. Please see xref:apply-patches-patchwork[] for more
145 [[apply-patches-patchwork]]
153 link is provided at the top of the page. Copy this link address and
156 ---------------------
157 $ git checkout -b <test-branch-name>
158 $ wget -O - <mbox-url> | git am
159 ---------------------
163 interface. Once the bundle is created and the bundle is made public,
164 you can copy the +mbox+ link for the bundle and apply the bundle
171 and you don't like any of the above topics, you can always work on items
177 [[submitting-patches]]
184 If you made some changes to Buildroot and you would like to contribute
192 and why things have changed, and to make it possible to use +git
204 * +package/pkg-generic: postpone evaluation of dependency conditions+
206 * +boot/uboot: needs host-{flex,bison}+
208 * +support/testing: add python-ubjson tests+
214 change is needed, and if necessary also give details about _how_ it
223 still possible to split them up in small patches and apply them in a
224 specific order. Small patches make it easier to review, and often
227 build is broken when only the first but not the second patch is
231 back and forth between packages, and certainly not committing things
236 https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History[in the Pro
238 +git reset --soft origin/master+ and select individual changes with
239 +git add -i+ or +git add -p+.
242 +Signed-off-by: Your Real Name <your@email.address>+ at the end of the
243 commit message. +git commit -s+ does that for you, if configured
244 properly. The +Signed-off-by+ tag means that you publish the patch
245 under the Buildroot license (i.e. GPL-2.0+, except for package patches,
246 which have the upstream license), and that you are allowed to do so.
253 +.hash+ file, any init script, and all package patches. If the package
254 has many sub-options, these are sometimes better added as separate
255 follow-up patches. The summary line should be something like
259 done to build the package, this should also be explained explicitly in
265 the +_LICENSE+ and +_LICENSE_FILES+ are still valid. The summary line
269 bump to version <new version>+ and the commit message body should show
276 If you are interested in getting notified of build failures and of
282 Buildroot provides a handy tool to check for common coding style
283 mistakes on files you created or modified, called +check-package+ (see
284 xref:check-package[] for more information).
292 ---------------------
293 $ git fetch --all --tags
295 ---------------------
301 ---------------------
302 $ git format-patch -M -n -s -o outgoing origin/master
303 ---------------------
306 automatically adding the +Signed-off-by+ line.
312 sent, called +get-developers+ (see xref:DEVELOPERS[] for more
313 information). This tool reads your patches and outputs the appropriate
314 +git send-email+ command to use:
316 ---------------------
317 $ ./utils/get-developers outgoing/*
318 ---------------------
320 Use the output of +get-developers+ to send your patches:
322 ---------------------
323 $ git send-email --to buildroot@buildroot.org --cc bob --cc alice outgoing/*
324 ---------------------
326 Alternatively, +get-developers -e+ can be used directly with the
327 +--cc-cmd+ argument to +git send-email+ to automatically CC the
330 ---------------------
331 $ git send-email --to buildroot@buildroot.org \
332       --cc-cmd './utils/get-developers -e' origin/master
333 ---------------------
337 ---------------------
339 $ git config sendemail.ccCmd "$(pwd)/utils/get-developers -e"
340 ---------------------
342 And then just do:
344 ---------------------
345 $ git send-email origin/master
346 ---------------------
349 To configure +git+, see +man git-send-email+ or google it.
351 If you do not use +git send-email+, make sure posted *patches are not
352 line-wrapped*, otherwise they cannot easily be applied. In such a case,
353 fix your e-mail client, or better yet, learn to use +git send-email+.
358 +--cover-letter+ to the +git format-patch+ command (see +man
359 git-format-patch+ for further information). This will generate a
360 template for an introduction e-mail to your patch series.
378 post-commit note specifying what branches are affected:
380 ----
383 Signed-off-by: Your Real Name <your@email.address>
384 ---
387 ----
394 should be based off the maintenance branch, and the patch subject prefix
396 This can be done with the +git format-patch+ flag +--subject-prefix+:
398 ---------------------
399 $ git format-patch --subject-prefix "PATCH 2020.02.x" \
400     -M -s -o outgoing origin/2020.02.x
401 ---------------------
403 Then send the patches with +git send-email+, as described above.
413 +git rebase -i origin/master+. Consult the git manual for more
417 editing the commit message. Below the +Signed-off-by+ section, add
418 +---+ and your changelog.
422 will automatically ignores lines below +---+ when the patch will be
428 ---------------
431 A paragraph that explains the problem, and how it manifests itself. If
441 Signed-off-by: John DOE <john.doe@example.net>
443 ---
444 Changes v2 -> v3:
445   - foo bar  (suggested by Jane)
446   - bar buz
448 Changes v1 -> v2:
449   - alpha bravo  (suggested by John)
450   - charly delta
451 ---------------
457 This can be easily handled with +git format-patch+ by using the option
458 +--subject-prefix+:
460 ---------------------
461 $ git format-patch --subject-prefix "PATCH v4" \
462     -M -s -o outgoing origin/master
463 ---------------------
465 Since git version 1.8.1, you can also use +-v <n>+ (where <n> is the
468 ---------------------
469 $ git format-patch -v4 -M -s -o outgoing origin/master
470 ---------------------
480 You can also add the +--in-reply-to <message-id>+ option when
484 *in-reply-to* is that patchwork will automatically mark the previous
487 [[reporting-bugs]]
491 xref:community-resources[the mailing list archive] whether someone has
492 already reported and/or fixed a similar problem.
495 opening a bug in the xref:community-resources[bug tracker] or by
496 xref:community-resources[sending a mail to the mailing list], there are
497 a number of details to provide in order to help people reproduce and
507 * target for which the build fails
508 * package(s) for which the build fails
509 * the command that fails and its output
513 +defconfig+; see xref:customize-store-buildroot-config[]).
517 preserve Unix-style line terminators when downloading raw pastes.
519 - https://gist.github.com/
520 - http://code.bulix.org/
524 Buildroot includes a run-time testing framework built upon Python
525 scripting and QEMU runtime execution. The goals of the framework are
528 * build a well defined Buildroot configuration
529 * optionally, verify some properties of the build output
530 * optionally, boot the build results under Qemu, and verify that a
534 +support/testing/run-tests+ tool, which has a series of options
535 documented in the tool's help '-h' description. Some common options
536 include setting the download folder, the output folder, keeping build
537 output, and for multiple test cases, you can set the JLEVEL for each.
539 Here is an example walk through of running a test case.
541 * For a first step, let us see what all the test case options are. The test
542 cases can be listed by executing +support/testing/run-tests -l+. These tests
543 can all be run individually during test development from the console. Both
544 one at a time and selectively as a group of a subset of tests.
546 ---------------------
547 $ support/testing/run-tests -l
573 ---------------------
575 * Then, to run one test case:
577 ---------------------
578 $ support/testing/run-tests -d dl -o output_folder -k tests.init.test_busybox.TestInitSystemBusybox…
584 Ran 1 test in 301.140s
587 ---------------------
589 The standard output indicates if the test is successful or not. By
590 default, the output folder for the test is deleted automatically
591 unless the option +-k+ is passed to *keep* the output directory.
593 ==== Creating a test case
596 top level in +support/testing/+ by folders of +conf+, +infra+ and +tests+.
597 All the test cases live under the +tests+ folder and are organized in various
598 folders representing the category of test.
600 The best way to get familiar with how to create a test case is to look
601 at a few of the basic file system +support/testing/tests/fs/+ and init
602 +support/testing/tests/init/+ test scripts. Those tests give good
603 examples of a basic tests that include both checking the build
604 results, and doing runtime tests. There are other more advanced cases
605 that use things like nested +br2-external+ folders to provide
606 skeletons and additional packages.
608 Creating a basic test case involves:
610 * Defining a test class that inherits from +infra.basetest.BRTest+
612 * Defining the +config+ member of the test class, to the Buildroot
613   configuration to build for this test case. It can optionally rely on
614   configuration snippets provided by the runtime test infrastructure:
616   architecture/toolchain configuration, and
617   +infra.basetest.MINIMAL_CONFIG+ to not build any filesystem. The
620   resulting image in Qemu without having to build a Linux kernel image
621   as part of the test case, therefore significant decreasing the build
622   time required for the test case.
625   actual tests to run after the build has completed. They may be tests
626   that verify the build output, by running command on the host using
629   +self.emulator+ in the test case. For example +self.emulator.boot()+
634 After creating the test script, add yourself to the +DEVELOPERS+ file to
635 be the maintainer of that test case.
637 ==== Debugging a test case
639 When a test case runs, the +output_folder+ will contain the following:
641 ---------------------
644 TestInitSystemBusyboxRw-build.log
645 TestInitSystemBusyboxRw-run.log
646 ---------------------
648 +TestInitSystemBusyboxRw/+ is the Buildroot output directory, and it
649 is preserved only if the +-k+ option is passed.
651 +TestInitSystemBusyboxRw-build.log+ is the log of the Buildroot build.
653 +TestInitSystemBusyboxRw-run.log+ is the log of the Qemu boot and
654 test. This file will only exist if the build was successful and the
655 test case involves booting under Qemu.
657 If you want to manually run Qemu to do manual tests of the build
658 result, the first few lines of +TestInitSystemBusyboxRw-run.log+
662 +output_folder+ (e.g. for debug purposes) and rerun the standard
664 the new modifications) and then rerun the test.
666 ==== Runtime tests and Gitlab CI
669 infrastructure, see .gitlab.yml and
670 https://gitlab.com/buildroot.org/buildroot/-/jobs.
672 You can also use Gitlab CI to test your new test cases, or verify that
676 project on Gitlab, and be able to push branches to your Buildroot fork
680 pipeline will be triggered or not, and for which test cases.
685 * To trigger all run-test test case jobs, push a branch that ends with
686   +-runtime-tests+:
688 ---------------------
689  $ git push gitlab HEAD:<name>-runtime-tests
690 ---------------------
692 * To trigger one or several test case jobs, push a branch that ends
693   with the complete test case name
697 ---------------------
698  $ git push gitlab HEAD:<name>-<test case name>
699 ---------------------
701 Example to run one test:
703 ---------------------
704  $ git push gitlab HEAD:foo-tests.init.test_busybox.TestInitSystemBusyboxRo
705 ---------------------
709 ---------------------
710  $ git push gitlab HEAD:foo-tests.init.test_busybox
711  $ git push gitlab HEAD:foo-tests.init
712 ---------------------