kumquat-buildroot/docs/manual/adding-packages-waf.txt
Lionel Orry 0496a6a842 package/pkg-waf: add support for <pkg>_SUBDIR
In the Buildroot manual, it is specified that the Waf-based
infrastructure supports the <pkg>_SUBDIR variable, which was not true.

This patch:
* makes use of this variable by changing to the given sub-directory
  before executing waf commands,
* documents the usage of <pkg>_SUBDIR in the waf-specific section of
  the manual.

Signed-off-by: Lionel Orry <lionel.orry@gmail.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2019-02-06 17:21:25 +01:00

92 lines
3.2 KiB
Plaintext

// -*- 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 = --enable-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_SUBDIR+ may contain the name of a subdirectory inside the
package that contains the main wscript file. This is useful,
if for example, the main wscript file is not at the root of
the tree extracted by the tarball. If +HOST_LIBFOO_SUBDIR+ is not
specified, it defaults to +LIBFOO_SUBDIR+.
* +LIBFOO_NEEDS_EXTERNAL_WAF+ can be set to +YES+ or +NO+ to tell
Buildroot to use the bundled +waf+ executable. If set to +NO+, the
default, then Buildroot will use the waf executable provided in the
package source tree; if set to +YES+, then Buildroot will download,
install waf as a host tool and use it to build the package.
* +LIBFOO_WAF_OPTS+, to specify additional options to pass to the
+waf+ script at every step of the package build process: configure,
build and installation. By default, empty.
* +LIBFOO_CONF_OPTS+, to specify additional options to pass to the
+waf+ script for the configuration step. By default, empty.
* +LIBFOO_BUILD_OPTS+, to specify additional options to pass to the
+waf+ script during the build step. By default, empty.
* +LIBFOO_INSTALL_STAGING_OPTS+, to specify additional options to pass
to the +waf+ script during the staging installation step. By default,
empty.
* +LIBFOO_INSTALL_TARGET_OPTS+, to specify additional options to pass
to the +waf+ script during the target installation step. By default,
empty.