docs/manual/adding-packages-virtual.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 === Infrastructure for virtual packages
   5
   6 [[virtual-package-tutorial]]
   7
   8 In Buildroot, a virtual package is a package whose functionalities are
   9 provided by one or more packages, referred to as 'providers'. The virtual
  10 package management is an extensible mechanism allowing the user to choose
  11 the provider used in the rootfs.
  12
  13 For example, 'OpenGL ES' is an API for 2D and 3D graphics on embedded systems.
  14 The implementation of this API is different for the 'Allwinner Tech Sunxi' and
  15 the 'Texas Instruments OMAP35xx' platforms. So +libgles+ will be a virtual
  16 package and +sunxi-mali+ and +ti-gfx+ will be the providers.
  17
  18 ==== +virtual-package+ tutorial
  19
  20 In the following example, we will explain how to add a new virtual package
  21 ('something-virtual') and a provider for it ('some-provider').
  22
  23 First, let's create the virtual package.
  24
  25 ==== Virtual package's +Config.in+ file
  26
  27 The +Config.in+ file of virtual package 'something-virtual' should contain:
  28
  29 ---------------------------
  30 01: config BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  31 02:     bool
  32 03:
  33 04: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
  34 05:     depends on BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  35 06:     string
  36 ---------------------------
  37
  38 In this file, we declare two options, +BR2_PACKAGE_HAS_SOMETHING_VIRTUAL+ and
  39 +BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL+, whose values will be used by the
  40 providers.
  41
  42 ==== Virtual package's +.mk+ file
  43
  44 The +.mk+ for the virtual package should just evaluate the +virtual-package+ macro:
  45
  46 ---------------------------
  47 01: ################################################################################
  48 02: #
  49 03: # something-virtual
  50 04: #
  51 05: ################################################################################
  52 06:
  53 07: $(eval $(virtual-package))
  54 ---------------------------
  55
  56 The ability to have target and host packages is also available, with the
  57 +host-virtual-package+ macro.
  58
  59 ==== Provider's +Config.in+ file
  60
  61 When adding a package as a provider, only the +Config.in+ file requires some
  62 modifications.
  63
  64 The +Config.in+ file of the package 'some-provider', which provides the
  65 functionalities of 'something-virtual', should contain:
  66
  67 ---------------------------
  68 01: config BR2_PACKAGE_SOME_PROVIDER
  69 02:     bool "some-provider"
  70 03:     select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  71 04:     help
  72 05:       This is a comment that explains what some-provider is.
  73 06:
  74 07:       http://foosoftware.org/some-provider/
  75 08:
  76 09: if BR2_PACKAGE_SOME_PROVIDER
  77 10: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
  78 11:     default "some-provider"
  79 12: endif
  80 ---------------------------
  81
  82 On line 3, we select +BR2_PACKAGE_HAS_SOMETHING_VIRTUAL+, and on line 11, we
  83 set the value of +BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL+ to the name of the
  84 provider, but only if it is selected.
  85
  86 ==== Provider's +.mk+ file
  87
  88 The +.mk+ file should also declare an additional variable
  89 +SOME_PROVIDER_PROVIDES+ to contain the names of all the virtual
  90 packages it is an implementation of:
  91
  92 ---------------------------
  93 01: SOME_PROVIDER_PROVIDES = something-virtual
  94 ---------------------------
  95
  96 Of course, do not forget to add the proper build and runtime dependencies for
  97 this package!
  98
  99 ==== Notes on depending on a virtual package
 100
 101 When adding a package that requires a certain +FEATURE+ provided by a virtual
 102 package, you have to use +depends on BR2_PACKAGE_HAS_FEATURE+, like so:
 103
 104 ---------------------------
 105 config BR2_PACKAGE_HAS_FEATURE
 106     bool
 107
 108 config BR2_PACKAGE_FOO
 109     bool "foo"
 110     depends on BR2_PACKAGE_HAS_FEATURE
 111 ---------------------------
 112
 113 ==== Notes on depending on a specific provider
 114
 115 If your package really requires a specific provider, then you'll have to
 116 make your package +depends on+ this provider; you can _not_ +select+ a
 117 provider.
 118
 119 Let's take an example with two providers for a +FEATURE+:
 120
 121 ---------------------------
 122 config BR2_PACKAGE_HAS_FEATURE
 123     bool
 124
 125 config BR2_PACKAGE_FOO
 126     bool "foo"
 127     select BR2_PACKAGE_HAS_FEATURE
 128
 129 config BR2_PACKAGE_BAR
 130     bool "bar"
 131     select BR2_PACKAGE_HAS_FEATURE
 132 ---------------------------
 133
 134 And you are adding a package that needs +FEATURE+ as provided by +foo+,
 135 but not as provided by +bar+.
 136
 137 If you were to use +select BR2_PACKAGE_FOO+, then the user would still
 138 be able to select +BR2_PACKAGE_BAR+ in the menuconfig. This would create
 139 a configuration inconsistency, whereby two providers of the same +FEATURE+
 140 would be enabled at once, one explicitly set by the user, the other
 141 implicitly by your +select+.
 142
 143 Instead, you have to use +depends on BR2_PACKAGE_FOO+, which avoids any
 144 implicit configuration inconsistency.