[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