docs/manual/adding-packages-tips.txt

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

Tips and tricks
~~~~~~~~~~~~~~~

[[package-name-variable-relation]]
Package name, config entry name and makefile variable relationship
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In Buildroot, there is some relationship between:

* the _package name_, which is the package directory name (and the
  name of the +*.mk+ file);

* the config entry name that is declared in the +Config.in+ file;

* the makefile variable prefix.

It is mandatory to maintain consistency between these elements,
using the following rules:

* the package directory and the +*.mk+ name are the _package name_
  itself (e.g.: +package/foo-bar_boo/foo-bar_boo.mk+);

* the _make_ target name is the _package name_ itself (e.g.:
  +foo-bar_boo+);

* the config entry is the upper case _package name_ with `.` and `-`
  characters substituted with `_`, prefixed with +BR2_PACKAGE_+ (e.g.:
  +BR2_PACKAGE_FOO_BAR_BOO+);

* the +*.mk+ file variable prefix is the upper case _package name_
  `.` and `-` characters substituted with `_` (e.g.:
  +FOO_BAR_BOO_VERSION+).


[[github-download-url]]
How to add a package from github
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Packages on github often don't have a download area with release tarballs.
However, it is possible to download tarballs directly from the repository
on github.

------------------------
FOO_VERSION = v1.0 # tag or full commit ID
FOO_SITE = http://github.com/<user>/<package>/tarball/$(FOO_VERSION)
------------------------

.Notes
- The FOO_VERSION can either be a tag or a commit ID.
- The tarball name generated by github matches the default one from
  Buildroot (e.g.: +foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz+),
  so it is not necessary to specify it in the +.mk+ file.
- When using a commit ID as version, you should use the full 40 hex characters.