docs/sphinx/featuremap_example.txt

   1
   2 The Waf features are names linked to specific functions by the decorator
   3 :py:func:`waflib.TaskGen.feature`. The functions
   4 are mapped to the class :py:class:`waflib.TaskGen.task_gen` as methods.
   5
   6 The association between feature names and methods is *many-to-many*, which means
   7 that a method may be involved in several features, and that a feature may be bound
   8 to several methods.
   9
  10 Here is how to create and use a new feature named **foo**::
  11
  12         from waflib.TaskGen import feature
  13         @feature('foo')
  14         def print_hello(self):
  15                 print("Hello, World!")
  16
  17 The function *print_hello* is now associated with the :py:class:`waflib.TaskGen.task_gen` class, which means
  18 that it may be used directly::
  19
  20         def build(bld):
  21                 tg = bld()
  22                 tg.print_hello()
  23
  24 The method may be called directly, and several times. If a method creates task, the same tasks will be created
  25 more than once, which may cause build errors. The *feature* attribute is used to have the associated
  26 methods called *exactly once* before the build starts::
  27
  28         def build(bld):
  29                 bld(features='foo')
  30
  31 Here is a more complete example with two methods::
  32
  33         from waflib.TaskGen import feature, after_method
  34
  35         @feature('foo')
  36         @after_method('print_bar')
  37         def print_hello(self):
  38                 print("Hello, Foo!")
  39
  40         @feature('bar')
  41         def print_bar(self):
  42                 print("Hello, Bar!")
  43
  44         def build(bld):
  45                 bld(features='foo bar')
  46
  47 The order of method execution is unrelated to the order of the features given. For instance,
  48 this example will print "Hello, Bar!" then "Hello, Foo!". The decorators
  49 :py:func:`waflib.TaskGen.after` and :py:func:`waflib.TaskGen.before` are
  50 enforcing partial order constraints on the methods to execute.
  51
  52 The following maps represent the associations betwen feature methods (represented in yellow) and
  53 methods associated to other feature names.
  54