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
  36 [[github-download-url]]
  37 ==== How to add a package from GitHub
  38
  39 Packages on GitHub often don't have a download area with release tarballs.
  40 However, it is possible to download tarballs directly from the repository
  41 on GitHub. As GitHub is known to have changed download mechanisms in the
  42 past, the 'github' helper function should be used as shown below.
  43
  44 ------------------------
  45 # Use a tag or a full commit ID
  46 FOO_VERSION = v1.0
  47 FOO_SITE = $(call github,<user>,<package>,$(FOO_VERSION))
  48 ------------------------
  49
  50 .Notes
  51 - The FOO_VERSION can either be a tag or a commit ID.
  52 - The tarball name generated by github matches the default one from
  53   Buildroot (e.g.: +foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz+),
  54   so it is not necessary to specify it in the +.mk+ file.
  55 - When using a commit ID as version, you should use the full 40 hex characters.
  56
  57 If the package you wish to add does have a release section on GitHub, the
  58 maintainer may have uploaded a release tarball, or the release may just point
  59 to the automatically generated tarball from the git tag. If there is a
  60 release tarball uploaded by the maintainer, we prefer to use that since it
  61 may be slightly different (e.g. it contains a configure script so we don't
  62 need to do AUTORECONF).
  63
  64 You can see on the release page if it's an uploaded tarball or a git tag:
  65
  66 image::github_hash_mongrel2.png[]
  67
  68 - If it looks like the image above then it was uploaded by the
  69   maintainer and you should use that link (in that example:
  70   'mongrel2-v1.9.2.tar.bz2') to specify +FOO_SITE+, and not use the
  71   'github' helper.
  72
  73 - On the other hand, if there's is *only* the "Source code" link, then
  74   it's an automatically generated tarball and you should use the
  75   'github' helper function.