[Buildroot] [PATCH v2 1/1] manual: add virtual package tutorial.

[Buildroot] [PATCH v2 1/1] manual: add virtual package tutorial.

[Eric Le Bihan]

The 'Tips and Tricks' section now features instructions about how to add a
virtual package.

Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr>
---
Changes v1 -> v2:
  - correct grammar errors (reported by ThomasDS).
---
 docs/manual/adding-packages-tips.txt |   83 ++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/docs/manual/adding-packages-tips.txt b/docs/manual/adding-packages-tips.txt
index 73c25be..5992860 100644
--- a/docs/manual/adding-packages-tips.txt
+++ b/docs/manual/adding-packages-tips.txt
@@ -55,3 +55,86 @@ FOO_SITE = $(call github,<user>,<package>,$(FOO_VERSION))
   Buildroot (e.g.: +foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz+),
   so it is not necessary to specify it in the +.mk+ file.
 - When using a commit ID as version, you should use the full 40 hex characters.
+
+[[virtual-package-tutorial]]
+How to add a virtual package
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Buildroot, a virtual package is a package whose functionalities are
+provided by one or more packages, referred to as 'providers'.
+
+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 +Config.in+ file
+=================================
+The +Config.in+ file of virtual package 'foo' should contain:
+
+---------------------------
+01: config BR2_PACKAGE_HAS_FOO
+02:	bool
+03:
+04: config BR2_PACKAGE_PROVIDES_FOO
+05:	depends on BR2_PACKAGE_HAS_FOO
+06:	string
+---------------------------
+=================================
+
+On line 1, we declare the option +BR2_PACKAGE_HAS_FOO+, which will be selected
+by the provider. On line 4, we declare the option +BR2_PACKAGE_PROVIDES_FOO+
+whose value will be set to the name of the provider, by the provider.
+
+.Virtual package +*.mk+ file
+============================
+The Makefile +package/foo/foo.mk+ should contain:
+
+---------------------------
+01: ################################################################################
+02: #
+03: # foo
+04: #
+05: ################################################################################
+06:
+07: FOO_SOURCE =
+08: FOO_DEPENDENCIES = $(call qstrip,$(BR2_PACKAGE_PROVIDES_FOO))
+09:
+10: ifeq ($(FOO_DEPENDENCIES),)
+11: define FOO_CONFIGURE_CMDS
+12:	$(error No Foo implementation selected. Configuration error)
+13:	exit 1
+14: endef
+15: endif
+---------------------------
+============================
+
+The Makefile is quite small as it will only check if a provider for the
+virtual package has been selected.
+
+.Provider +Config.in+ file
+==========================
+The +Config.in+ file of the package 'libbaz', which provides the functionalities
+of 'foo', should contain:
+
+---------------------------
+01: config BR2_PACKAGE_LIBBAZ
+02:	bool "libbaz"
+03:	select BR2_PACKAGE_HAS_FOO
+04:	help
+05:	  This is a comment that explains what libbaz is.
+06:
+07:	  http://bazsoftware.org/libbaz/
+08:
+09: if BR2_PACKAGE_LIBBAZ
+10: config BR2_PACKAGE_PROVIDES_FOO
+11:	default "libbaz"
+12: endif
+---------------------------
+==========================
+
+On line 3, we select +BR2_PACKAGE_HAS_FOO+, and on line 11, we set the value
+of +BR2_PACKAGE_PROVIDES_FOO+ to the name of the provider, but only if it is
+selected.
+
+No modifications to +package/libbaz/libbaz.mk+ are required.
--
1.7.9.5

[Buildroot] [PATCH v2 1/1] manual: add virtual package tutorial.

[Arnout Vandecappelle]

On 14/02/14 16:11, Eric Le Bihan wrote:
> The 'Tips and Tricks' section now features instructions about how to add a
> virtual package.

 Good plan!

> 
> Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr>
> ---
> Changes v1 -> v2:
>   - correct grammar errors (reported by ThomasDS).
> ---
>  docs/manual/adding-packages-tips.txt |   83 ++++++++++++++++++++++++++++++++++
>  1 file changed, 83 insertions(+)
> 
> diff --git a/docs/manual/adding-packages-tips.txt b/docs/manual/adding-packages-tips.txt
> index 73c25be..5992860 100644
> --- a/docs/manual/adding-packages-tips.txt
> +++ b/docs/manual/adding-packages-tips.txt
> @@ -55,3 +55,86 @@ FOO_SITE = $(call github,<user>,<package>,$(FOO_VERSION))
>    Buildroot (e.g.: +foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz+),
>    so it is not necessary to specify it in the +.mk+ file.
>  - When using a commit ID as version, you should use the full 40 hex characters.
> +
> +[[virtual-package-tutorial]]
> +How to add a virtual package
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In Buildroot, a virtual package is a package whose functionalities are
> +provided by one or more packages, referred to as 'providers'.
> +
> +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 +Config.in+ file
> +=================================
> +The +Config.in+ file of virtual package 'foo' should contain:
> +
> +---------------------------
> +01: config BR2_PACKAGE_HAS_FOO
> +02:	bool
> +03:
> +04: config BR2_PACKAGE_PROVIDES_FOO
> +05:	depends on BR2_PACKAGE_HAS_FOO
> +06:	string
> +---------------------------
> +=================================

 I haven't checked, but isn't this === line redundant?

> +
> +On line 1, we declare the option +BR2_PACKAGE_HAS_FOO+, which will be selected
> +by the provider. On line 4, we declare the option +BR2_PACKAGE_PROVIDES_FOO+
> +whose value will be set to the name of the provider, by the provider.

 I think an example would be better here. All those providers are a bit
confusing. So it would be nice if you could make a complete example with
Config.in and *.mk fragments for the virtual package and for a provider.

 To make it easier for the reader to distinguish between them, perhaps it
would be better to the virtual package V and the provider package P.

> +
> +.Virtual package +*.mk+ file
> +============================
> +The Makefile +package/foo/foo.mk+ should contain:
> +
> +---------------------------
> +01: ################################################################################
> +02: #
> +03: # foo
> +04: #
> +05: ################################################################################
> +06:
> +07: FOO_SOURCE =
> +08: FOO_DEPENDENCIES = $(call qstrip,$(BR2_PACKAGE_PROVIDES_FOO))
> +09:
> +10: ifeq ($(FOO_DEPENDENCIES),)
> +11: define FOO_CONFIGURE_CMDS
> +12:	$(error No Foo implementation selected. Configuration error)
> +13:	exit 1
> +14: endef
> +15: endif

 This is missing an $(eval $(generic-package))

> +---------------------------
> +============================

 Again, isn't this redundant?

> +
> +The Makefile is quite small as it will only check if a provider for the
> +virtual package has been selected.
> +
> +.Provider +Config.in+ file
> +==========================
> +The +Config.in+ file of the package 'libbaz', which provides the functionalities
> +of 'foo', should contain:
> +
> +---------------------------
> +01: config BR2_PACKAGE_LIBBAZ
> +02:	bool "libbaz"
> +03:	select BR2_PACKAGE_HAS_FOO
> +04:	help
> +05:	  This is a comment that explains what libbaz is.
> +06:
> +07:	  http://bazsoftware.org/libbaz/
> +08:
> +09: if BR2_PACKAGE_LIBBAZ
> +10: config BR2_PACKAGE_PROVIDES_FOO
> +11:	default "libbaz"
> +12: endif
> +---------------------------
> +==========================

 Redundant

> +
> +On line 3, we select +BR2_PACKAGE_HAS_FOO+, and on line 11, we set the value
> +of +BR2_PACKAGE_PROVIDES_FOO+ to the name of the provider, but only if it is
> +selected.
> +
> +No modifications to +package/libbaz/libbaz.mk+ are required.

 ... when you add a provider package.

(Just making things a little more explicit.)

 Thanks!

 Regards,
 Arnout

> --
> 1.7.9.5
> 
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
> 


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F

[Buildroot] [PATCH v2 1/1] manual: add virtual package tutorial.

[Eric Le Bihan]

Hi!

On Mon, Feb 17, 2014 at 06:19:51PM +0100, Arnout Vandecappelle wrote:
> On 14/02/14 16:11, Eric Le Bihan wrote:
[...]
> > +.Virtual package +Config.in+ file
> > +=================================
> > +The +Config.in+ file of virtual package 'foo' should contain:
> > +
> > +---------------------------
> > +01: config BR2_PACKAGE_HAS_FOO
> > +02:	bool
> > +03:
> > +04: config BR2_PACKAGE_PROVIDES_FOO
> > +05:	depends on BR2_PACKAGE_HAS_FOO
> > +06:	string
> > +---------------------------
> > +=================================
>
>  I haven't checked, but isn't this === line redundant?
>
No. I used docs/manual/adding-packages-generic.txt as example.
According to the Asciidoc reference, the text of an example should be
delimited using === (http://www.methods.co.nz/asciidoc/userguide.html#X48).
As our example is a code listing, the code should be delimited with ---
(http://www.methods.co.nz/asciidoc/userguide.html#_listing_blocks).

Removing either one messes up the layout.
> > +
> > +On line 1, we declare the option +BR2_PACKAGE_HAS_FOO+, which will be selected
> > +by the provider. On line 4, we declare the option +BR2_PACKAGE_PROVIDES_FOO+
> > +whose value will be set to the name of the provider, by the provider.
>
>  I think an example would be better here. All those providers are a bit
> confusing. So it would be nice if you could make a complete example with
> Config.in and *.mk fragments for the virtual package and for a provider.
>
So, instead of adding this tutorial to 'adding-packages-tips.txt', maybe it
would be better to add it in a new file named 'adding-packages-virtual.txt'?
A complete example takes more room than a tip.

I'll update the text to whack the 'provider' repetitions.
>  To make it easier for the reader to distinguish between them, perhaps it
> would be better to the virtual package V and the provider package P.
Do you mean using BR2_PACKAGE_HAS_V instead of BR2_PACKAGE_HAS_FOO and so on?
FOO and BAR/BAZ are already used in other parts of the manual and single
letter package names look strange to me. They also make a better distinction
between the prefix of the symbol and the name of the package.

Thanks for the review!

Best regards,
ELB

[Buildroot] [PATCH v2 1/1] manual: add virtual package tutorial.

[Arnout Vandecappelle]

On 18/02/14 12:44, Eric Le Bihan wrote:
>>  To make it easier for the reader to distinguish between them, perhaps it
>> > would be better to the virtual package V and the provider package P.
> Do you mean using BR2_PACKAGE_HAS_V instead of BR2_PACKAGE_HAS_FOO and so on?
> FOO and BAR/BAZ are already used in other parts of the manual and single
> letter package names look strange to me. They also make a better distinction
> between the prefix of the symbol and the name of the package.

 FOO BAR BAZ are OK to use when the names are meaningless. Here it would
be better if the package name would embed the role that the package plays
in the explanation. But I admit that V and P are a bit short. I wanted to
avoid VIRTUAL and PROVIDER because that sounds too much as if that prefix
is part of the infrastructure.

 Maybe something-virtual and some-provider.

 Regards,
 Arnout

-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F

[Buildroot] [PATCH v2 1/1] manual: add virtual package tutorial.

[Samuel Martin]

Hi Eric,

On Fri, Feb 14, 2014 at 4:11 PM, Eric Le Bihan
<eric.le.bihan.dev@free.fr> wrote:
> The 'Tips and Tricks' section now features instructions about how to add a
> virtual package.
>
> Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr>
> ---
> Changes v1 -> v2:
>   - correct grammar errors (reported by ThomasDS).
> ---
>  docs/manual/adding-packages-tips.txt |   83 ++++++++++++++++++++++++++++++++++
>  1 file changed, 83 insertions(+)
>
> diff --git a/docs/manual/adding-packages-tips.txt b/docs/manual/adding-packages-tips.txt
> index 73c25be..5992860 100644
> --- a/docs/manual/adding-packages-tips.txt
> +++ b/docs/manual/adding-packages-tips.txt
> @@ -55,3 +55,86 @@ FOO_SITE = $(call github,<user>,<package>,$(FOO_VERSION))
>    Buildroot (e.g.: +foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz+),
>    so it is not necessary to specify it in the +.mk+ file.
>  - When using a commit ID as version, you should use the full 40 hex characters.
> +
> +[[virtual-package-tutorial]]
> +How to add a virtual package
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In Buildroot, a virtual package is a package whose functionalities are
> +provided by one or more packages, referred to as 'providers'.
> +
> +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.

The generic way of presenting the virtual/provider "infra" in Buildroot is:
we want to use the virtual/provider infrastructure when there is one
API, but several packages implementing this API, so we want an
extensible mechanism allowing to choose what implementation we want in
the target rootfs.

The example is good btw.

> +
> +.Virtual package +Config.in+ file
> +=================================
> +The +Config.in+ file of virtual package 'foo' should contain:
> +
> +---------------------------
> +01: config BR2_PACKAGE_HAS_FOO
> +02:    bool
> +03:
> +04: config BR2_PACKAGE_PROVIDES_FOO
> +05:    depends on BR2_PACKAGE_HAS_FOO
> +06:    string
> +---------------------------
> +=================================
> +
> +On line 1, we declare the option +BR2_PACKAGE_HAS_FOO+, which will be selected
> +by the provider. On line 4, we declare the option +BR2_PACKAGE_PROVIDES_FOO+
> +whose value will be set to the name of the provider, by the provider.
> +
> +.Virtual package +*.mk+ file
> +============================
> +The Makefile +package/foo/foo.mk+ should contain:
> +
> +---------------------------
> +01: ################################################################################
> +02: #
> +03: # foo
> +04: #
> +05: ################################################################################
> +06:
> +07: FOO_SOURCE =
> +08: FOO_DEPENDENCIES = $(call qstrip,$(BR2_PACKAGE_PROVIDES_FOO))
> +09:
> +10: ifeq ($(FOO_DEPENDENCIES),)
> +11: define FOO_CONFIGURE_CMDS
> +12:    $(error No Foo implementation selected. Configuration error)
> +13:    exit 1

I think the "exit 1" here is not needed, "$(error ...)" will stop make anyway.
Someone can confirm?

> +14: endef
> +15: endif
> +---------------------------
> +============================
> +
> +The Makefile is quite small as it will only check if a provider for the
> +virtual package has been selected.
> +
> +.Provider +Config.in+ file
> +==========================
> +The +Config.in+ file of the package 'libbaz', which provides the functionalities
> +of 'foo', should contain:
> +
> +---------------------------
> +01: config BR2_PACKAGE_LIBBAZ
> +02:    bool "libbaz"
> +03:    select BR2_PACKAGE_HAS_FOO
> +04:    help
> +05:      This is a comment that explains what libbaz is.
> +06:
> +07:      http://bazsoftware.org/libbaz/
> +08:
> +09: if BR2_PACKAGE_LIBBAZ
> +10: config BR2_PACKAGE_PROVIDES_FOO
> +11:    default "libbaz"
> +12: endif
> +---------------------------
> +==========================
> +
> +On line 3, we select +BR2_PACKAGE_HAS_FOO+, and on line 11, we set the value
> +of +BR2_PACKAGE_PROVIDES_FOO+ to the name of the provider, but only if it is
> +selected.
> +
> +No modifications to +package/libbaz/libbaz.mk+ are required.

I would move this line at the beginning of the "Provider" section,
telling that (and emphasizing that) only the Config.in of the provider
needs  few changes, the *.mk follows the buildroot infrastructure with
no change at all.


Regards,

-- 
Samuel

[Buildroot] [PATCH v2 1/1] manual: add virtual package tutorial.

[Eric Le Bihan]

Hi!

On Tue, Feb 18, 2014 at 09:34:41PM +0100, Samuel Martin wrote:
[...]
> > +[[virtual-package-tutorial]]
> > +How to add a virtual package
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +In Buildroot, a virtual package is a package whose functionalities are
> > +provided by one or more packages, referred to as 'providers'.
> > +
> > +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.
>
> The generic way of presenting the virtual/provider "infra" in Buildroot is:
> we want to use the virtual/provider infrastructure when there is one
> API, but several packages implementing this API, so we want an
> extensible mechanism allowing to choose what implementation we want in
> the target rootfs.
I will update the text in order to put emphasis on this idea.

> > +07: FOO_SOURCE =
> > +08: FOO_DEPENDENCIES = $(call qstrip,$(BR2_PACKAGE_PROVIDES_FOO))
> > +09:
> > +10: ifeq ($(FOO_DEPENDENCIES),)
> > +11: define FOO_CONFIGURE_CMDS
> > +12:    $(error No Foo implementation selected. Configuration error)
> > +13:    exit 1
>
> I think the "exit 1" here is not needed, "$(error ...)" will stop make anyway.
> Someone can confirm?
I performed a stupid substitution, which ended up with a mash-up of shell
script and make control functions (D'Oh!). $(error ...) will indeed stop, so
the exit is not needed.

But, following suggestions from ThomasP, I chose a pure 'make' version, which
gets rid of <foo>_CONFIGURE_CMDS:

  ifeq ($(BR2_PACKAGE_HAS_FOO),y)
  ifeq ($(FOO_DEPENDENCIES),)
  $(error No foo implementation selected. Configuration error.)
  endif
  endif

With this method, the user gets the error message earlier, with less cruft.
I will provide a patch to update all the virtual packages.

[...]
> > +No modifications to +package/libbaz/libbaz.mk+ are required.
>
> I would move this line at the beginning of the "Provider" section,
> telling that (and emphasizing that) only the Config.in of the provider
> needs  few changes, the *.mk follows the buildroot infrastructure with
> no change at all.
Good idea.

Thanks for your comments!

Best regards,
ELB

[Buildroot] [PATCH v2 1/1] manual: add virtual package tutorial.

[Yann E. MORIN]

Eric, All,

On 2014-02-19 15:19 +0100, Eric Le Bihan spake thusly:
> On Tue, Feb 18, 2014 at 09:34:41PM +0100, Samuel Martin wrote:
> [...]
> > > +[[virtual-package-tutorial]]
> > > +How to add a virtual package
> > > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > +
> > > +In Buildroot, a virtual package is a package whose functionalities are
> > > +provided by one or more packages, referred to as 'providers'.
> > > +
> > > +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.
> >
> > The generic way of presenting the virtual/provider "infra" in Buildroot is:
> > we want to use the virtual/provider infrastructure when there is one
> > API, but several packages implementing this API, so we want an
> > extensible mechanism allowing to choose what implementation we want in
> > the target rootfs.
> I will update the text in order to put emphasis on this idea.

How are your changes going?

There are quite a few improvements to the manual being upstreamed. Your
changes would make for another nice addition.

Do you think you could resubmit sometime next week, so this has a chance
to go in before the release?

Thanks for your work on this! :-)

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH v2 1/1] manual: add virtual package tutorial.

[Eric Le Bihan]

Yann, All,

On Sun, Feb 23, 2014 at 08:04:07PM +0100, Yann E. MORIN wrote:
> Eric, All,
>
> On 2014-02-19 15:19 +0100, Eric Le Bihan spake thusly:
> > On Tue, Feb 18, 2014 at 09:34:41PM +0100, Samuel Martin wrote:
> > [...]
> > > > +[[virtual-package-tutorial]]
> > > > +How to add a virtual package
> > > > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > > +
> > > > +In Buildroot, a virtual package is a package whose functionalities are
> > > > +provided by one or more packages, referred to as 'providers'.
> > > > +
> > > > +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.
> > >
> > > The generic way of presenting the virtual/provider "infra" in Buildroot is:
> > > we want to use the virtual/provider infrastructure when there is one
> > > API, but several packages implementing this API, so we want an
> > > extensible mechanism allowing to choose what implementation we want in
> > > the target rootfs.
> > I will update the text in order to put emphasis on this idea.
>
> How are your changes going?
>
> There are quite a few improvements to the manual being upstreamed. Your
> changes would make for another nice addition.
>
> Do you think you could resubmit sometime next week, so this has a chance
> to go in before the release?
I sent a patch series intended for the next branch, which features:

- a new version of the dependency check in the virtual package infra (less
  shell script, more make functions). All the virtual packages have been
  updated.
- a new version of the tutorial, which includes the fixes.

But I can provide a version of the tutorial for the current version of virtual
infra for current branch if needed.

Best regards,
ELB