cirros-testvm/src-cirros/buildroot-2015.05/build/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 See xref:virtual-package-list[] for the symbols to select if you implement
  87 a new provider for an existing virtual package.
  88
  89 ==== Provider's +.mk+ file
  90
  91 The +.mk+ file should also declare an additional variable
  92 +SOME_PROVIDER_PROVIDES+ to contain the names of all the virtual
  93 packages it is an implementation of:
  94
  95 ---------------------------
  96 01: SOME_PROVIDER_PROVIDES = something-virtual
  97 ---------------------------
  98
  99 Of course, do not forget to add the proper build and runtime dependencies for
 100 this package!
 101
 102 See xref:virtual-package-list[] for the names of virtual packages to provide
 103 if you implement a new provider for an existing virtual package.
 104
 105 ==== Notes on depending on a virtual package
 106
 107 When adding a package that requires a certain +FEATURE+ provided by a virtual
 108 package, you have to use +depends on BR2_PACKAGE_HAS_FEATURE+, like so:
 109
 110 ---------------------------
 111 config BR2_PACKAGE_HAS_FEATURE
 112     bool
 113
 114 config BR2_PACKAGE_FOO
 115     bool "foo"
 116     depends on BR2_PACKAGE_HAS_FEATURE
 117 ---------------------------
 118
 119 ==== Notes on depending on a specific provider
 120
 121 If your package really requires a specific provider, then you'll have to
 122 make your package +depends on+ this provider; you can _not_ +select+ a
 123 provider.
 124
 125 Let's take an example with two providers for a +FEATURE+:
 126
 127 ---------------------------
 128 config BR2_PACKAGE_HAS_FEATURE
 129     bool
 130
 131 config BR2_PACKAGE_FOO
 132     bool "foo"
 133     select BR2_PACKAGE_HAS_FEATURE
 134
 135 config BR2_PACKAGE_BAR
 136     bool "bar"
 137     select BR2_PACKAGE_HAS_FEATURE
 138 ---------------------------
 139
 140 And you are adding a package that needs +FEATURE+ as provided by +foo+,
 141 but not as provided by +bar+.
 142
 143 If you were to use +select BR2_PACKAGE_FOO+, then the user would still
 144 be able to select +BR2_PACKAGE_BAR+ in the menuconfig. This would create
 145 a configuration inconsistency, whereby two providers of the same +FEATURE+
 146 would be enabled at once, one explicitly set by the user, the other
 147 implicitly by your +select+.
 148
 149 Instead, you have to use +depends on BR2_PACKAGE_FOO+, which avoids any
 150 implicit configuration inconsistency.