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 9In 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 18It is mandatory to maintain consistency between these elements, 19using 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 38Buildroot provides a script in +utils/check-package+ that checks new or 39changed files for coding style. It is not a complete language validator, 40but it catches many common mistakes. It is meant to run in the actual 41files you created or modified, before creating the patch for submission. 42 43This script can be used for packages, filesystem makefiles, Config.in 44files, etc. It does not check the files defining the package 45infrastructures and some other files containing similar common code. 46 47To use it, run the +check-package+ script, by telling which files you 48created or changed: 49 50---- 51$ ./utils/check-package package/new-package/* 52---- 53 54If you have the +utils+ directory in your path you can also run: 55 56---- 57$ cd package/new-package/ 58$ check-package * 59---- 60 61The 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 70Once you have added your new package, it is important that you test it 71under various conditions: does it build for all architectures? Does it 72build with the different C libraries? Does it need threads, NPTL? And 73so on... 74 75Buildroot runs http://autobuild.buildroot.org/[autobuilders] which 76continuously test random configurations. However, these only build the 77`master` branch of the git tree, and your new fancy package is not yet 78there. 79 80Buildroot provides a script in +utils/test-pkg+ that uses the same base 81configurations as used by the autobuilders so you can test your package 82in the same conditions. 83 84First, create a config snippet that contains all the necessary options 85needed to enable your package, but without any architecture or toolchain 86option. For example, let's create a config snippet that just enables 87+libcurl+, without any TLS backend: 88 89---- 90$ cat libcurl.config 91BR2_PACKAGE_LIBCURL=y 92---- 93 94If your package needs more configuration options, you can add them to the 95config 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 100BR2_PACKAGE_LIBCURL=y 101BR2_PACKAGE_LIBCURL_CURL=y 102BR2_PACKAGE_OPENSSL=y 103---- 104 105Then run the +test-pkg+ script, by telling it what config snippet to use 106and what package to test: 107 108---- 109$ ./utils/test-pkg -c libcurl.config -p libcurl 110---- 111 112By default, +test-pkg+ will build your package against a subset of the 113toolchains used by the autobuilders, which has been selected by the 114Buildroot developers as being the most useful and representative 115subset. If you want to test all toolchains, pass the +-a+ option. Note 116that in any case, internal toolchains are excluded as they take too 117long to build. 118 119The output lists all toolchains that are tested and the corresponding 120result (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 13511 builds, 2 skipped, 2 build failed, 1 legal-info failed 136---- 137 138The 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 155When there are failures, you can just re-run the script with the same 156options (after you fixed your package); the script will attempt to 157re-build the package specified with +-p+ for all toolchains, without 158the need to re-build all the dependencies of that package. 159 160The +test-pkg+ script accepts a few options, for which you can get some 161help by running: 162 163---- 164$ ./utils/test-pkg -h 165---- 166 167[[github-download-url]] 168==== How to add a package from GitHub 169 170Packages on GitHub often don't have a download area with release tarballs. 171However, it is possible to download tarballs directly from the repository 172on GitHub. As GitHub is known to have changed download mechanisms in the 173past, the 'github' helper function should be used as shown below. 174 175------------------------ 176# Use a tag or a full commit ID 177FOO_VERSION = 1.0 178FOO_SITE = $(call github,<user>,<package>,v$(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- When the tag contains a prefix such as +v+ in +v1.0+, then the 188 +VERSION+ variable should contain just +1.0+, and the +v+ should be 189 added directly in the +SITE+ variable, as illustrated above. This 190 ensures that the +VERSION+ variable value can be used to match 191 against http://www.release-monitoring.org/[release-monitoring.org] 192 results. 193 194If the package you wish to add does have a release section on GitHub, the 195maintainer may have uploaded a release tarball, or the release may just point 196to the automatically generated tarball from the git tag. If there is a 197release tarball uploaded by the maintainer, we prefer to use that since it 198may be slightly different (e.g. it contains a configure script so we don't 199need to do AUTORECONF). 200 201You can see on the release page if it's an uploaded tarball or a git tag: 202 203image::github_hash_mongrel2.png[] 204 205- If it looks like the image above then it was uploaded by the 206 maintainer and you should use that link (in that example: 207 'mongrel2-v1.9.2.tar.bz2') to specify +FOO_SITE+, and not use the 208 'github' helper. 209 210- On the other hand, if there's is *only* the "Source code" link, then 211 it's an automatically generated tarball and you should use the 212 'github' helper function. 213 214[[gitlab-download-url]] 215==== How to add a package from Gitlab 216 217In a similar way to the +github+ macro described in 218xref:github-download-url[], Buildroot also provides the +gitlab+ macro 219to download from Gitlab repositories. It can be used to download 220auto-generated tarballs produced by Gitlab, either for specific tags 221or commits: 222 223------------------------ 224# Use a tag or a full commit ID 225FOO_VERSION = 1.0 226FOO_SITE = $(call gitlab,<user>,<package>,v$(FOO_VERSION)) 227------------------------ 228 229By default, it will use a +.tar.gz+ tarball, but Gitlab also provides 230+.tar.bz2+ tarballs, so by adding a +<pkg>_SOURCE+ variable, this 231+.tar.bz2+ tarball can be used: 232 233------------------------ 234# Use a tag or a full commit ID 235FOO_VERSION = 1.0 236FOO_SITE = $(call gitlab,<user>,<package>,v$(FOO_VERSION)) 237FOO_SOURCE = foo-$(FOO_VERSION).tar.bz2 238------------------------ 239 240If there is a specific tarball uploaded by the upstream developers in 241+https://gitlab.com/<project>/releases/+, do not use this macro, but 242rather use directly the link to the tarball. 243
