docs/manual/adding-packages-waf.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 === Infrastructure for Waf-based packages
   5
   6 [[waf-package-tutorial]]
   7
   8 ==== +waf-package+ tutorial
   9
  10 First, let's see how to write a +.mk+ file for a Waf-based package, with
  11 an example :
  12
  13 ------------------------
  14 01: ################################################################################
  15 02: #
  16 03: # libfoo
  17 04: #
  18 05: ################################################################################
  19 06:
  20 07: LIBFOO_VERSION = 1.0
  21 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  22 09: LIBFOO_SITE = http://www.foosoftware.org/download
  23 10: LIBFOO_CONF_OPTS = --enable-bar --disable-baz
  24 11: LIBFOO_DEPENDENCIES = bar
  25 12:
  26 13: $(eval $(waf-package))
  27 ------------------------
  28
  29 On line 7, we declare the version of the package.
  30
  31 On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  32 recommended) and the location of the tarball on the Web. Buildroot
  33 will automatically download the tarball from this location.
  34
  35 On line 10, we tell Buildroot what options to enable for libfoo.
  36
  37 On line 11, we tell Buildroot the depednencies of libfoo.
  38
  39 Finally, on line line 13, we invoke the +waf-package+
  40 macro that generates all the Makefile rules that actually allows the
  41 package to be built.
  42
  43 [[waf-package-reference]]
  44
  45 ==== +waf-package+ reference
  46
  47 The main macro of the Waf package infrastructure is +waf-package+.
  48 It is similar to the +generic-package+ macro.
  49
  50 Just like the generic infrastructure, the Waf infrastructure works
  51 by defining a number of variables before calling the +waf-package+
  52 macro.
  53
  54 First, all the package metadata information variables that exist in
  55 the generic infrastructure also exist in the Waf infrastructure:
  56 +LIBFOO_VERSION+, +LIBFOO_SOURCE+, +LIBFOO_PATCH+, +LIBFOO_SITE+,
  57 +LIBFOO_SUBDIR+, +LIBFOO_DEPENDENCIES+, +LIBFOO_INSTALL_STAGING+,
  58 +LIBFOO_INSTALL_TARGET+.
  59
  60 An additional variable, specific to the Waf infrastructure, can
  61 also be defined.
  62
  63 * +LIBFOO_NEEDS_EXTERNAL_WAF+ can be set to +YES+ or +NO+ to tell
  64   Buildroot to use the bundled +waf+ executable. If set to +NO+, the
  65   default, then Buildroot will use the waf executable provided in the
  66   package source tree; if set to +YES+, then Buidlroot will download,
  67   install waf as a host tool and use it to build the package.
  68
  69 * +LIBFOO_WAF_OPTS+, to specify additional options to pass to the
  70   +waf+ script at every step of the package build process: configure,
  71   build and installation. By default, empty.
  72
  73 * +LIBFOO_CONF_OPTS+, to specify additional options to pass to the
  74   +waf+ script for the configuration step. By default, empty.
  75
  76 * +LIBFOO_BUILD_OPTS+, to specify additional options to pass to the
  77   +waf+ script during the build step. By default, empty.
  78
  79 * +LIBFOO_INSTALL_STAGING_OPTS+, to specify additional options to pass
  80   to the +waf+ script during the staging installation step.  By default,
  81   empty.
  82
  83 * +LIBFOO_INSTALL_TARGET_OPTS+, to specify additional options to pass
  84   to the +waf+ script during the target installation step.  By default,
  85   empty.