[Buildroot] [PATCH 0/3] Document use of local sources for packages

[Buildroot] [PATCH 0/3] Document use of local sources for packages

[Nathan Lynch]

Since the 2011.11 release Buildroot has supported building packages
from local sources, but the manual has not reflected this well.  This
series is an attempt to address that.  I relied on Thomas Petazzoni's
description of the "file" and "local" methods here:

http://free-electrons.com/blog/buildroot-2011-11/

Nathan Lynch (3):
  docs: update LIBFOO_SITE to describe use of filesystem paths
  docs: rework LIBFOO_SITE_METHOD documentation
  docs: describe "file" and "local" methods in LIBFOO_SITE_METHOD

 docs/manual/adding-packages-gentargets.txt |   77 +++++++++++++++++++---------
 1 file changed, 52 insertions(+), 25 deletions(-)

-- 
1.7.10.2

[Buildroot] [PATCH 1/3] docs: update LIBFOO_SITE to describe use of filesystem paths

[Nathan Lynch]

Buildroot supports the use of local filesystem paths in LIBFOO_SITE
since the 2011.11 release, but this is not documented in the manual.
Fix this and slightly reword the surrounding doucmentation
accordingly.

Signed-off-by: Nathan Lynch <ntl@pobox.com>
---
 docs/manual/adding-packages-gentargets.txt |   21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/docs/manual/adding-packages-gentargets.txt b/docs/manual/adding-packages-gentargets.txt
index cfcee8c..918580e 100644
--- a/docs/manual/adding-packages-gentargets.txt
+++ b/docs/manual/adding-packages-gentargets.txt
@@ -156,13 +156,18 @@ The list of variables that can be set in a +.mk+ file to give metadata
   package directory inside Buildroot will be applied to the package
   after extraction.
 
-* +LIBFOO_SITE+ may contain the Internet location of the package. It
-  can either be the HTTP, FTP or SCP location of a tarball, or the URL
-  of a Git, Subversion, Mercurial or Bazaar repository (see
-  +LIBFOO_SITE_METHOD+ below). +
-  SCP URLs should be of the form +scp://[user@]host:filepath+. Note
-  that filepath is relative to the user's home directory, so you may want
-  to prepend the path with a slash for absolute paths:
+* +LIBFOO_SITE+ provides the location of the package, which can be a
+  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. 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. +
+  Note that SCP URLs should be of the form
+  +scp://[user@]host:filepath+, and that filepath is relative to the
+  user's home directory, so you may want to prepend the path with a
+  slash for absolute paths:
   +scp://[user@]host:/absolutepath+. +
   If +HOST_LIBFOO_SITE+ is not specified, it defaults to
   +LIBFOO_SITE+. If none are specified, then the location is assumed
@@ -172,6 +177,8 @@ The list of variables that can be set in a +.mk+ file to give metadata
     +LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
     +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor/+ +
     +LIBFOO_SITE=git://github.com/kergoth/tslib.git+
+    +LIBFOO_SITE=/opt/software/libfoo.tar.gz+
+    +LIBFOO_SITE=$(TOPDIR)/../src/libfoo/+
 
 * +LIBFOO_SITE_METHOD+ may contain the method to fetch the package
   source code. It can either be +wget+ (for normal FTP/HTTP downloads
-- 
1.7.10.2

[Buildroot] [PATCH 2/3] docs: rework LIBFOO_SITE_METHOD documentation

[Nathan Lynch]

The current structure of the LIBFOO_SITE_METHOD paragraph would make
it difficult to add documentation for the "file" and "local" methods.
There are enough possible values for LIBFOO_SITE_METHOD that
describing them in a sub-list seems to work well, which makes it
easier to add documentation for new methods.

Signed-off-by: Nathan Lynch <ntl@pobox.com>
---
 docs/manual/adding-packages-gentargets.txt |   46 ++++++++++++++++++----------
 1 file changed, 29 insertions(+), 17 deletions(-)

diff --git a/docs/manual/adding-packages-gentargets.txt b/docs/manual/adding-packages-gentargets.txt
index 918580e..b296ac4 100644
--- a/docs/manual/adding-packages-gentargets.txt
+++ b/docs/manual/adding-packages-gentargets.txt
@@ -180,23 +180,35 @@ The list of variables that can be set in a +.mk+ file to give metadata
     +LIBFOO_SITE=/opt/software/libfoo.tar.gz+
     +LIBFOO_SITE=$(TOPDIR)/../src/libfoo/+
 
-* +LIBFOO_SITE_METHOD+ may contain the method to fetch the package
-  source code. It can either be +wget+ (for normal FTP/HTTP downloads
-  of tarballs), +scp+ (for downloads over SSH with scp), +svn+, +git+,
-  +hg+ or +bzr+.  When not specified, it is guessed from the URL given
-  in +LIBFOO_SITE+: +scp://+, +svn://+, +git://+ and
-  +bzr://+ URLs will use the +scp+, +svn+, +git+ and +bzr+ methods
-  respectively. All other URL-types will use the +wget+ method. So for
-  example, in the case of a package whose source code is available
-  through a Subversion repository on HTTP, one 'must' specifiy
-  +LIBFOO_SITE_METHOD=svn+. Similarly, for Mercurial repositories, one
-  'must' specify +LIBFOO_SITE_METHOD=hg+. For +svn+, +git+, +hg+ and
-  +bzr+ methods, what Buildroot does is a checkout/clone of the repository
-  which is then tarballed and stored into the download cache. Next
-  builds will not checkout/clone again, but will use the tarball directly.
-  When +HOST_LIBFOO_SITE_METHOD+ is not specified, it defaults to the value
-  of +LIBFOO_SITE_METHOD+. See +package/multimedia/tremor/+ for an
-  example.
+* +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the
+  package source code. In many cases, Buildroot guesses the method
+  from the contents of +LIBFOO_SITE+ and setting +LIBFOO_SITE_METHOD+
+  is unnecessary. When +HOST_LIBFOO_SITE_METHOD+ is not specified, it
+  defaults to the value of +LIBFOO_SITE_METHOD+. +
+  The possible values of +LIBFOO_SITE_METHOD+ are:
+  ** +wget+ for normal FTP/HTTP downloads of tarballs.  Used by
+     default when +LIBFOO_SITE+ begins with +http://+, +https://+ or
+     +ftp://+.
+  ** +scp+ for downloads of tarballs over SSH with scp.  Used by
+     default when +LIBFOO_SITE+ begins with +scp://+.
+  ** +svn+ for retrieving source code from a Subversion repository.
+     Used by default when +LIBFOO_SITE+ begins with +svn://+.  When a
+     +http://+ Subversion repository URL is specified in
+     +LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+.
+     Buildroot performs a checkout which is preserved as a tarball in
+     the download cache; subsequent builds use the tarball instead of
+     performing another checkout.
+  ** +git+ for retrieving source code from a Git repository.  Used by
+     default when +LIBFOO_SITE+ begins with +git://+. The downloaded
+     source code is cached as with the +svn+
+     method.
+  ** +hg+ for retrieving source code from a Mercurial repository. One
+     'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+
+     contains a Mercurial repository URL. The downloaded source code
+     is cached as with the +svn+ method.
+  ** +bzr+ for retrieving source code from a Bazaar repository. Used
+     by default when +LIBFOO_SITE+ begins with +bzr://+. The
+     downloaded source code is cached as with the +svn+ method.
 
 * +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package
   name) that are required for the current target package to
-- 
1.7.10.2

[Buildroot] [PATCH 3/3] docs: describe "file" and "local" methods in LIBFOO_SITE_METHOD

[Nathan Lynch]

Based on description by Thomas Petazzoni at:
http://free-electrons.com/blog/buildroot-2011-11/

Signed-off-by: Nathan Lynch <ntl@pobox.com>
---
 docs/manual/adding-packages-gentargets.txt |    8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/manual/adding-packages-gentargets.txt b/docs/manual/adding-packages-gentargets.txt
index b296ac4..84cf06b 100644
--- a/docs/manual/adding-packages-gentargets.txt
+++ b/docs/manual/adding-packages-gentargets.txt
@@ -209,6 +209,14 @@ The list of variables that can be set in a +.mk+ file to give metadata
   ** +bzr+ for retrieving source code from a Bazaar repository. Used
      by default when +LIBFOO_SITE+ begins with +bzr://+. The
      downloaded source code is cached as with the +svn+ method.
+  ** +file+ for a local tarball.  One should use this when
+     +LIBFOO_SITE+ specifies a package tarball as a local filename.
+     Useful for software that isn't available publicly or in version
+     control.
+  ** +local+ for a local source code directory.  One should use this
+     when +LIBFOO_SITE+ specifies a local directory path containing
+     the package source code.  Buildroot copies the contents of the
+     source directory into the package's build directory.
 
 * +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package
   name) that are required for the current target package to
-- 
1.7.10.2

[Buildroot] [PATCH 0/3] Document use of local sources for packages

[Thomas Petazzoni]

Le Sun, 17 Jun 2012 16:53:58 -0500,
Nathan Lynch <ntl@pobox.com> a ?crit :

> Since the 2011.11 release Buildroot has supported building packages
> from local sources, but the manual has not reflected this well.  This
> series is an attempt to address that.  I relied on Thomas Petazzoni's
> description of the "file" and "local" methods here:
> 
> http://free-electrons.com/blog/buildroot-2011-11/
> 
> Nathan Lynch (3):
>   docs: update LIBFOO_SITE to describe use of filesystem paths
>   docs: rework LIBFOO_SITE_METHOD documentation
>   docs: describe "file" and "local" methods in LIBFOO_SITE_METHOD
> 
>  docs/manual/adding-packages-gentargets.txt |   77 +++++++++++++++++++---------
>  1 file changed, 52 insertions(+), 25 deletions(-)

Acked-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

for the three patches.

Thomas
-- 
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com

[Buildroot] [PATCH 0/3] Document use of local sources for packages

[Arnout Vandecappelle]

On 06/18/12 08:50, Thomas Petazzoni wrote:
> Le Sun, 17 Jun 2012 16:53:58 -0500,
> Nathan Lynch<ntl@pobox.com>  a ?crit :
>
>> Since the 2011.11 release Buildroot has supported building packages
>> from local sources, but the manual has not reflected this well.  This
>> series is an attempt to address that.  I relied on Thomas Petazzoni's
>> description of the "file" and "local" methods here:
>>
>> http://free-electrons.com/blog/buildroot-2011-11/
>>
>> Nathan Lynch (3):
>>    docs: update LIBFOO_SITE to describe use of filesystem paths
>>    docs: rework LIBFOO_SITE_METHOD documentation
>>    docs: describe "file" and "local" methods in LIBFOO_SITE_METHOD
>>
>>   docs/manual/adding-packages-gentargets.txt |   77 +++++++++++++++++++---------
>>   1 file changed, 52 insertions(+), 25 deletions(-)
>
> Acked-by: Thomas Petazzoni<thomas.petazzoni@free-electrons.com>
>
> for the three patches.

Acked-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
for the three patches.

  I would like to see documentation updates get merged more easily. It's likely
they create conflicts with other documentation updates, so other documentation
updates are basically stalled until they are merged.  And the risk of breaking
things is rather small.

  Regards,
  Arnout
-- 
Arnout Vandecappelle                               arnout at mind be
Senior Embedded Software Architect                 +32-16-286540
Essensium/Mind                                     http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium                BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F

[Buildroot] [PATCH 0/3] Document use of local sources for packages

[Peter Korsgaard]

>>>>> "Nathan" == Nathan Lynch <ntl@pobox.com> writes:

 Nathan> Since the 2011.11 release Buildroot has supported building packages
 Nathan> from local sources, but the manual has not reflected this well.  This
 Nathan> series is an attempt to address that.  I relied on Thomas Petazzoni's
 Nathan> description of the "file" and "local" methods here:

 Nathan> http://free-electrons.com/blog/buildroot-2011-11/

Committed all 3, thanks.

-- 
Bye, Peter Korsgaard