The cirros image was rebuilt against the 3.13.0-83 kernel, drivers e1000e, igbvf...

[packages/trusty/cirros-testvm.git] / cirros-testvm / src-cirros / buildroot-2015.05 / docs / manual / adding-packages-tips.txt

diff --git a/cirros-testvm/src-cirros/buildroot-2015.05/docs/manual/adding-packages-tips.txt b/cirros-testvm/src-cirros/buildroot-2015.05/docs/manual/adding-packages-tips.txt
new file mode 100644 (file)
index 0000000..6699951
--- /dev/null
+++ b/cirros-testvm/src-cirros/buildroot-2015.05/docs/manual/adding-packages-tips.txt
@@ -0,0 +1,73 @@
+// -*- 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_
+  with `.` 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. As GitHub is known to have changed download mechanisms in the
+past, the 'github' helper function should be used as shown below.
+
+------------------------
+# Use a tag or a full commit ID
+FOO_VERSION = v1.0
+FOO_SITE = $(call github,<user>,<package>,$(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.
+
+If the package you wish to add does have a release section on GitHub, the
+maintainer may have uploaded a release tarball, or the release may just point
+to the automatically generated tarball from the git tag. If there is a
+release tarball uploaded by the maintainer, we prefer to use that since it
+may be slightly different (e.g. it contains a configure script so we don't
+need to do AUTORECONF).
+
+You can see on the release page if it's an uploaded tarball or a git tag:
+
+- If there is a green download button, like
+  https://github.com/zedshaw/mongrel2/releases/tag/v1.9.1[mongrel2], then it
+  was uploaded by the maintainer and you should use the link of that button to
+  specify +FOO_SITE+, and not use the 'github' helper.
+- If there is grey download button, like
+  https://github.com/xbmc/xbmc/releases/tag/13.2-Gotham[xbmc], then it's an
+  automatically generated tarball and you should use the 'github' helper
+  function.