adding-packages-tips.txt 7.3 KB

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