docs/manual/adding-packages-tips.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 === Tips and tricks
   5
   6 [[package-name-variable-relation]]
   7 ==== Package name, config entry name and makefile variable relationship
   8
   9 In Buildroot, there is some relationship between:
  10
  11 * the _package name_, which is the package directory name (and the
  12   name of the +*.mk+ file);
  13
  14 * the config entry name that is declared in the +Config.in+ file;
  15
  16 * the makefile variable prefix.
  17
  18 It is mandatory to maintain consistency between these elements,
  19 using the following rules:
  20
  21 * the package directory and the +*.mk+ name are the _package name_
  22   itself (e.g.: +package/foo-bar_boo/foo-bar_boo.mk+);
  23
  24 * the _make_ target name is the _package name_ itself (e.g.:
  25   +foo-bar_boo+);
  26
  27 * the config entry is the upper case _package name_ with `.` and `-`
  28   characters substituted with `_`, prefixed with +BR2_PACKAGE_+ (e.g.:
  29   +BR2_PACKAGE_FOO_BAR_BOO+);
  30
  31 * the +*.mk+ file variable prefix is the upper case _package name_
  32   with `.` and `-` characters substituted with `_` (e.g.:
  33   +FOO_BAR_BOO_VERSION+).
  34
  35 [[check-package]]
  36 ==== How to check the coding style
  37
  38 Buildroot provides a script in +utils/check-package+ that checks new or
  39 changed files for coding style. It is not a complete language validator,
  40 but it catches many common mistakes. It is meant to run in the actual
  41 files you created or modified, before creating the patch for submission.
  42
  43 This script can be used for packages, filesystem makefiles, Config.in
  44 files, etc. It does not check the files defining the package
  45 infrastructures and some other files containing similar common code.
  46
  47 To use it, run the +check-package+ script, by telling which files you
  48 created or changed:
  49
  50 ----
  51 $ ./utils/check-package package/new-package/*
  52 ----
  53
  54 If you have the +utils+ directory in your path you can also run:
  55
  56 ----
  57 $ cd package/new-package/
  58 $ check-package *
  59 ----
  60
  61 The tool can also be used for packages in a br2-external:
  62
  63 ----
  64 $ check-package -b /path/to/br2-ext-tree/package/my-package/*
  65 ----
  66
  67 [[testing-package]]
  68 ==== How to test your package
  69
  70 Once you have added your new package, it is important that you test it
  71 under various conditions: does it build for all architectures? Does it
  72 build with the different C libraries? Does it need threads, NPTL? And
  73 so on...
  74
  75 Buildroot runs http://autobuild.buildroot.org/[autobuilders] which
  76 continuously test random configurations. However, these only build the
  77 `master` branch of the git tree, and your new fancy package is not yet
  78 there.
  79
  80 Buildroot provides a script in +utils/test-pkg+ that uses the same base
  81 configurations as used by the autobuilders so you can test your package
  82 in the same conditions.
  83
  84 First, create a config snippet that contains all the necessary options
  85 needed to enable your package, but without any architecture or toolchain
  86 option. For example, let's create a config snippet that just enables
  87 +libcurl+, without any TLS backend:
  88
  89 ----
  90 $ cat libcurl.config
  91 BR2_PACKAGE_LIBCURL=y
  92 ----
  93
  94 If your package needs more configuration options, you can add them to the
  95 config snippet. For example, here's how you would test +libcurl+ with
  96 +openssl+ as a TLS backend and the +curl+ program:
  97
  98 ----
  99 $ cat libcurl.config
 100 BR2_PACKAGE_LIBCURL=y
 101 BR2_PACKAGE_CURL=y
 102 BR2_PACKAGE_OPENSSL=y
 103 ----
 104
 105 Then run the +test-pkg+ script, by telling it what config snippet to use
 106 and what package to test:
 107
 108 ----
 109 $ ./utils/test-pkg -c libcurl.config -p libcurl
 110 ----
 111
 112 By default, +test-pkg+ will build your package against a subset of the
 113 toolchains used by the autobuilders, which has been selected by the
 114 Buildroot developers as being the most useful and representative
 115 subset. If you want to test all toolchains, pass the +-a+ option. Note
 116 that in any case, internal toolchains are excluded as they take too
 117 long to build.
 118
 119 The output lists all toolchains that are tested and the corresponding
 120 result (excerpt, results are fake):
 121
 122 ----
 123 $ ./utils/test-pkg -c libcurl.config -p libcurl
 124                 armv5-ctng-linux-gnueabi [ 1/11]: OK
 125               armv7-ctng-linux-gnueabihf [ 2/11]: OK
 126                         br-aarch64-glibc [ 3/11]: SKIPPED
 127                            br-arcle-hs38 [ 4/11]: SKIPPED
 128                             br-arm-basic [ 5/11]: FAILED
 129                   br-arm-cortex-a9-glibc [ 6/11]: OK
 130                    br-arm-cortex-a9-musl [ 7/11]: FAILED
 131                    br-arm-cortex-m4-full [ 8/11]: OK
 132                              br-arm-full [ 9/11]: OK
 133                     br-arm-full-nothread [10/11]: FAILED
 134                       br-arm-full-static [11/11]: OK
 135 11 builds, 2 skipped, 2 build failed, 1 legal-info failed
 136 ----
 137
 138 The results mean:
 139
 140 * `OK`: the build was successful.
 141 * `SKIPPED`: one or more configuration options listed in the config
 142   snippet were not present in the final configuration. This is due to
 143   options having dependencies not satisfied by the toolchain, such as
 144   for example a package that +depends on BR2_USE_MMU+ with a noMMU
 145   toolchain. The missing options are reported in +missing.config+ in
 146   the output build directory (+~/br-test-pkg/TOOLCHAIN_NAME/+ by
 147   default).
 148 * `FAILED`: the build failed. Inspect the +logfile+ file in the output
 149   build  directory to see what went wrong:
 150 ** the actual build failed,
 151 ** the legal-info failed,
 152 ** one of the preliminary steps (downloading the config file, applying
 153    the configuration, running `dirclean` for the package) failed.
 154
 155 When there are failures, you can just re-run the script with the same
 156 options (after you fixed your package); the script will attempt to
 157 re-build the package specified with +-p+ for all toolchains, without
 158 the need to re-build all the dependencies of that package.
 159
 160 The +test-pkg+ script accepts a few options, for which you can get some
 161 help by running:
 162
 163 ----
 164 $ ./utils/test-pkg -h
 165 ----
 166
 167 [[github-download-url]]
 168 ==== How to add a package from GitHub
 169
 170 Packages on GitHub often don't have a download area with release tarballs.
 171 However, it is possible to download tarballs directly from the repository
 172 on GitHub. As GitHub is known to have changed download mechanisms in the
 173 past, the 'github' helper function should be used as shown below.
 174
 175 ------------------------
 176 # Use a tag or a full commit ID
 177 FOO_VERSION = v1.0
 178 FOO_SITE = $(call github,<user>,<package>,$(FOO_VERSION))
 179 ------------------------
 180
 181 .Notes
 182 - The FOO_VERSION can either be a tag or a commit ID.
 183 - The tarball name generated by github matches the default one from
 184   Buildroot (e.g.: +foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz+),
 185   so it is not necessary to specify it in the +.mk+ file.
 186 - When using a commit ID as version, you should use the full 40 hex characters.
 187
 188 If the package you wish to add does have a release section on GitHub, the
 189 maintainer may have uploaded a release tarball, or the release may just point
 190 to the automatically generated tarball from the git tag. If there is a
 191 release tarball uploaded by the maintainer, we prefer to use that since it
 192 may be slightly different (e.g. it contains a configure script so we don't
 193 need to do AUTORECONF).
 194
 195 You can see on the release page if it's an uploaded tarball or a git tag:
 196
 197 image::github_hash_mongrel2.png[]
 198
 199 - If it looks like the image above then it was uploaded by the
 200   maintainer and you should use that link (in that example:
 201   'mongrel2-v1.9.2.tar.bz2') to specify +FOO_SITE+, and not use the
 202   'github' helper.
 203
 204 - On the other hand, if there's is *only* the "Source code" link, then
 205   it's an automatically generated tarball and you should use the
 206   'github' helper function.