[Buildroot] [PATCH 6/9 v2] docs/manual: document the new forges we support: github and gitorious

Yann E. MORIN yann.morin.1998 at free.fr
Sat Dec 6 11:13:56 UTC 2014


Signed-off-by: "Yann E. MORIN" <yann.morin.1998 at free.fr>
---
 docs/manual/adding-packages-generic.txt | 15 ++++++++--
 docs/manual/adding-packages-tips.txt    | 50 +++++++++++++++++++++++++--------
 2 files changed, 51 insertions(+), 14 deletions(-)

diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
index 69d1cfa..260144b 100644
--- a/docs/manual/adding-packages-generic.txt
+++ b/docs/manual/adding-packages-generic.txt
@@ -239,9 +239,7 @@ not have to set +LIBFOO_UPSTREAM_SOURCE+.
   URL or a local filesystem path. HTTP, FTP and SCP are supported URL
   types for retrieving package tarballs. Git, Subversion, Mercurial,
   and Bazaar are supported URL types for retrieving packages directly
-  from source code management systems. There is a helper function to make
-  it easier to download source tarballs from GitHub (refer to
-  xref:github-download-url[] for details). A filesystem path may be used
+  from source code management systems. A filesystem path may be used
   to specify either a tarball or a directory containing the package
   source code. See +LIBFOO_SITE_METHOD+ below for more details on how
   retrieval works. +
@@ -258,6 +256,17 @@ not have to set +LIBFOO_UPSTREAM_SOURCE+.
     +LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
     +LIBFOO_SITE=$(TOPDIR)/../src/libfoo/+
 
+* +LIBFOO_FORGE+ and +LIBFOO_FORGE_PATH+ may be used instead of
+  +LIBFOO_SITE+, when +libfoo+ is hosted to a well known forge:
+  GitHub of Gitorious. In such a case, +LIBFOO_VERSION+,
+  +LIBFOO_UPSTREAM_SOURCE+ and +LIBFOO_SITE+ must be set to special
+  values. This is conveniently done with +LIBFOO_FORGE+.
+  +LIBFOO_FORGE+ should be set to the lowercase name of the forge,
+  while +LIBFOO_FORGE_PATH+ should be set to the +/+-separated tuple
+  +USER/REPOS+. If +LIBFOO_FORGE+ is set, then +LIBFOO_SITE+ must
+  *not* be used. See xref:forge-download[] for the known forges, and
+  special cases for when to use it or not.
+
 * +LIBFOO_EXTRA_DOWNLOADS+ lists a number of additional files that
   Buildroot should download from +LIBFOO_SITE+ in addition to the main
   +LIBFOO_SOURCE+ (which usually is a tarball). Buildroot will not do
diff --git a/docs/manual/adding-packages-tips.txt b/docs/manual/adding-packages-tips.txt
index 6f5e785..71a3330 100644
--- a/docs/manual/adding-packages-tips.txt
+++ b/docs/manual/adding-packages-tips.txt
@@ -33,40 +33,68 @@ using the following rules:
   +FOO_BAR_BOO_VERSION+).
 
 
-[[github-download-url]]
-==== How to add a package from GitHub
+[[forge-download]]
+==== How to add a package from a forge
+
+===== 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.
+past, the 'github' forge should be used as shown below.
 
 ------------------------
-FOO_VERSION = v1.0 # tag or full commit ID
-FOO_SITE = $(call github,<user>,<package>,$(FOO_VERSION))
+FOO_VERSION = v1.0
+FOO_FORGE = github
+FOO_FORGE_PATH = user/foo
 ------------------------
 
-.Notes
-- The FOO_VERSION can either be a tag or a commit ID.
+.Note
+- The +FOO_VERSION+ can be either 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.
+- 'user' is the name of the GitHub user to whom the 'foo' repository belongs.
 
 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).
+need to do AUTORECONF), and thus you should not use +FOO_FORGE+ in that case.
 
 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.
+  specify +FOO_SITE+, and not use the 'github' forge.
 - 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.
+  automatically generated tarball and you should use the 'github' forge.
+
+===== Gitorious
+
+Gitorious does not offer a download area for packages to put their
+releases on. However, it offers a way to download tarballs from any
+tag or sha1 changeset, but the naming scheme it uses for the tarballs'
+basename does not contain the package name, only the version string.
+
+Buildroot allows you to easily specify that a package should be
+downloaded from Gitorious. Like for GitHub (above), we recognise
+'gitorious' as a forge; it should be used as shown below.
+
+----
+FOO_VERSION = v1.0
+FOO_FORGE = gitorious
+FOO_FORGE_PATH = user/foo
+----
+
+.Note
+- The +FOO_VERSION+ can be either a tag or a commit ID.
+- The tarball name generated by gitorious 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.
+- 'user' is the name of the Gitorious user to whom the 'foo' repository belongs.
-- 
1.9.1




More information about the buildroot mailing list