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