[03/10] docs/manual: document the waf-package infra

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Romain Naour <romain.naour@openwide.fr>
---
 docs/manual/adding-packages-waf.txt | 67 +++++++++++++++++++++++++++++++++++++
 docs/manual/adding-packages.txt     |  2 ++
 2 files changed, 69 insertions(+)
 create mode 100644 docs/manual/adding-packages-waf.txt

Hi Yann, All,

Le 30/10/2016 à 17:02, Yann E. MORIN a écrit :
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Romain Naour <romain.naour@openwide.fr>

Reviewed-by: Romain Naour <romain.naour@gmail.com>

Best regards,
Romain

> ---
>  docs/manual/adding-packages-waf.txt | 67 +++++++++++++++++++++++++++++++++++++
>  docs/manual/adding-packages.txt     |  2 ++
>  2 files changed, 69 insertions(+)
>  create mode 100644 docs/manual/adding-packages-waf.txt
> 
> diff --git a/docs/manual/adding-packages-waf.txt b/docs/manual/adding-packages-waf.txt
> new file mode 100644
> index 0000000..31c7167
> --- /dev/null
> +++ b/docs/manual/adding-packages-waf.txt
> @@ -0,0 +1,67 @@
> +// -*- mode:doc; -*-
> +// vim: set syntax=asciidoc:
> +
> +=== Infrastructure for Waf-based packages
> +
> +[[waf-package-tutorial]]
> +
> +==== +waf-package+ tutorial
> +
> +First, let's see how to write a +.mk+ file for a Waf-based package, with
> +an example :
> +
> +------------------------
> +01: ################################################################################
> +02: #
> +03: # libfoo
> +04: #
> +05: ################################################################################
> +06:
> +07: LIBFOO_VERSION = 1.0
> +08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
> +09: LIBFOO_SITE = http://www.foosoftware.org/download
> +10: LIBFOO_CONF_OPTS = --eanble-bar --disable-baz
> +11: LIBFOO_DEPENDENCIES = bar
> +12:
> +13: $(eval $(waf-package))
> +------------------------
> +
> +On line 7, we declare the version of the package.
> +
> +On line 8 and 9, we declare the name of the tarball (xz-ed tarball
> +recommended) and the location of the tarball on the Web. Buildroot
> +will automatically download the tarball from this location.
> +
> +On line 10, we tell Buildroot what options to enable for libfoo.
> +
> +On line 11, we tell Buildroot the depednencies of libfoo.
> +
> +Finally, on line line 13, we invoke the +waf-package+
> +macro that generates all the Makefile rules that actually allows the
> +package to be built.
> +
> +[[waf-package-reference]]
> +
> +==== +waf-package+ reference
> +
> +The main macro of the Waf package infrastructure is +waf-package+.
> +It is similar to the +generic-package+ macro.
> +
> +Just like the generic infrastructure, the Waf infrastructure works
> +by defining a number of variables before calling the +waf-package+
> +macro.
> +
> +First, all the package metadata information variables that exist in
> +the generic infrastructure also exist in the Waf infrastructure:
> ++LIBFOO_VERSION+, +LIBFOO_SOURCE+, +LIBFOO_PATCH+, +LIBFOO_SITE+,
> ++LIBFOO_SUBDIR+, +LIBFOO_DEPENDENCIES+, +LIBFOO_INSTALL_STAGING+,
> ++LIBFOO_INSTALL_TARGET+.
> +
> +An additional variable, specific to the Waf infrastructure, can
> +also be defined.
> +
> +* +LIBFOO_BUNDLED_WAF+ can be set to +YES+ or +NO+ to tell Buildroot to
> +  use the bundled +waf+ executable. If set to +YES+, the default, then
> +  Buildroot will use the waf executable in the package source tree; if
> +  set to +NO+, then Buidlroot will download and install waf as a
> +  host-tool.
> diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
> index 76f90c9..4595991 100644
> --- a/docs/manual/adding-packages.txt
> +++ b/docs/manual/adding-packages.txt
> @@ -29,6 +29,8 @@ include::adding-packages-kconfig.txt[]
>  
>  include::adding-packages-rebar.txt[]
>  
> +include::adding-packages-waf.txt[]
> +
>  include::adding-packages-kernel-module.txt[]
>  
>  include::adding-packages-asciidoc.txt[]
>

Hello,

On Sun, 30 Oct 2016 17:02:14 +0100, Yann E. MORIN wrote:

> +------------------------
> +01: ################################################################################
> +02: #
> +03: # libfoo
> +04: #
> +05: ################################################################################
> +06:
> +07: LIBFOO_VERSION = 1.0
> +08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
> +09: LIBFOO_SITE = http://www.foosoftware.org/download
> +10: LIBFOO_CONF_OPTS = --eanble-bar --disable-baz

eanble -> enable

> +On line 7, we declare the version of the package.
> +
> +On line 8 and 9, we declare the name of the tarball (xz-ed tarball
> +recommended) and the location of the tarball on the Web. Buildroot
> +will automatically download the tarball from this location.
> +
> +On line 10, we tell Buildroot what options to enable for libfoo.
> +
> +On line 11, we tell Buildroot the depednencies of libfoo.
> +
> +Finally, on line line 13, we invoke the +waf-package+
> +macro that generates all the Makefile rules that actually allows the
> +package to be built.

To be honest, I'm wondering if we shouldn't refactor the manual. This
blurb is duplicated for every package infrastructure, without adding
much value.

But clearly that's a separate matter, and your patch is good as-is.

> +* +LIBFOO_BUNDLED_WAF+ can be set to +YES+ or +NO+ to tell Buildroot to
> +  use the bundled +waf+ executable. If set to +YES+, the default, then

YES is in fact not the default :-)

> +  Buildroot will use the waf executable in the package source tree; if
> +  set to +NO+, then Buidlroot will download and install waf as a

Buildroot.

> +  host-tool.

host tool (i.e no dash in between).

No need to resend for these issues, I can fixup when applying.

Thanks,

Thomas

Thomas, All,

On 2016-11-17 00:04 +0100, Thomas Petazzoni spake thusly:
> On Sun, 30 Oct 2016 17:02:14 +0100, Yann E. MORIN wrote:
[--SNIP--]
> > +* +LIBFOO_BUNDLED_WAF+ can be set to +YES+ or +NO+ to tell Buildroot to
> > +  use the bundled +waf+ executable. If set to +YES+, the default, then
> YES is in fact not the default :-)

Well, "! NO" is the default. ;-)

> > +  Buildroot will use the waf executable in the package source tree; if
> > +  set to +NO+, then Buidlroot will download and install waf as a
> Buildroot.

I Like Buidlroot. It sounds like Beetlejuice. ;-]

> > +  host-tool.
> host tool (i.e no dash in between).
> 
> No need to resend for these issues, I can fixup when applying.

Will you address the variable name in the infra at the same time, or
do you prefer I respin with the rename (in which case I can fix the
manual) ?

Thanks! :-)

Regards,
Yann E. MORIN.

Hello,

On Thu, 17 Nov 2016 21:47:39 +0100, Yann E. MORIN wrote:
> Thomas, All,
> 
> On 2016-11-17 00:04 +0100, Thomas Petazzoni spake thusly:
> > On Sun, 30 Oct 2016 17:02:14 +0100, Yann E. MORIN wrote:  
> [--SNIP--]
> > > +* +LIBFOO_BUNDLED_WAF+ can be set to +YES+ or +NO+ to tell Buildroot to
> > > +  use the bundled +waf+ executable. If set to +YES+, the default, then  
> > YES is in fact not the default :-)  
> 
> Well, "! NO" is the default. ;-)

Nope, I think you're getting it wrong like on IRC. The default is
actually empty, which means "YES", i.e "the waf script is bundled and
there is no need to add a dependency on host-waf".

Thomas

Hello,

On Sun, 30 Oct 2016 17:02:14 +0100, Yann E. MORIN wrote:
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Romain Naour <romain.naour@openwide.fr>

Applied with a few tweaks, see below.

> +10: LIBFOO_CONF_OPTS = --eanble-bar --disable-baz

Typo fixed.

> +* +LIBFOO_BUNDLED_WAF+ can be set to +YES+ or +NO+ to tell Buildroot to
> +  use the bundled +waf+ executable. If set to +YES+, the default, then
> +  Buildroot will use the waf executable in the package source tree; if
> +  set to +NO+, then Buidlroot will download and install waf as a
> +  host-tool.

I've obviously reworded this paragraph quite a bit to take into account
the new name of the variable, LIBFOO_NEEDS_EXTERNAL_WAF.

Thanks!

Thomas