// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

Infrastructure for virtual packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[[virtual-package-tutorial]]

In Buildroot, a virtual package is a package whose functionalities are
provided by one or more packages, referred to as 'providers'. The virtual
package management is an extensible mechanism allowing the user to choose
the provider used in the rootfs.

For example, 'OpenGL ES' is an API for 2D and 3D graphics on embedded systems.
The implementation of this API is different for the 'Allwinner Tech Sunxi' and
the 'Texas Instruments OMAP35xx' plaftorms. So +libgles+ will be a virtual
package and +sunxi-mali+ and +ti-gfx+ will be the providers.

+virtual-package+ tutorial
^^^^^^^^^^^^^^^^^^^^^^^^^^

In the following example, we will explain how to add a new virtual package
('something-virtual') and a provider for it ('some-provider').

First, let's create the virtual package.

Virtual package's +Config.in+ file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The +Config.in+ file of virtual package 'something-virtual' should contain:

---------------------------
01: config BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
02:	bool
03:
04: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
05:	depends on BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
06:	string
---------------------------

In this file, we declare two options, +BR2_PACKAGE_HAS_SOMETHING_VIRTUAL+ and
+BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL+, whose values will be used by the
providers.

Virtual package's +*.mk+ file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The +.mk+ for the virtual package should just evaluate the +virtual-package+ macro:

---------------------------
01: ################################################################################
02: #
03: # something-virtual
04: #
05: ################################################################################
06:
07: $(eval $(virtual-package))
---------------------------

The ability to have target and host packages is also available, with the
+host-virtual-package+ macro.

Provider's +Config.in+ file
^^^^^^^^^^^^^^^^^^^^^^^^^^^

When adding a package as a provider, only the +Config.in+ file requires some
modifications. The +*.mk+ file should follow the Buildroot infrastructure with
no change at all.

The +Config.in+ file of the package 'some-provider', which provides the
functionalities of 'something-virtual', should contain:

---------------------------
01: config BR2_PACKAGE_SOME_PROVIDER
02:	bool "some-provider"
03:	select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
04:	help
05:	  This is a comment that explains what some-provider is.
06:
07:	  http://foosoftware.org/some-provider/
08:
09: if BR2_PACKAGE_SOME_PROVIDER
10: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
11:	default "some-provider"
12: endif
---------------------------

On line 3, we select +BR2_PACKAGE_HAS_SOMETHING_VIRTUAL+, and on line 11, we
set the value of +BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL+ to the name of the
provider, but only if it is selected.

Of course, do not forget to add the proper build and runtime dependencies for
this package!