| Message ID | 1393235404-2693-3-git-send-email-eric.le.bihan.dev@free.fr |
|---|---|
| State | Superseded |
| Headers | show |
Eric, All, I think you should base this on master, since we think it would be very interesting to have it in this release. On 2014-02-24 10:50 +0100, Eric Le Bihan spake thusly: > The manual now features a new section with instructions about how to add a > virtual package. > > Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr> > --- > docs/manual/adding-packages-virtual.txt | 102 +++++++++++++++++++++++++++++++ > docs/manual/adding-packages.txt | 2 + > 2 files changed, 104 insertions(+) > create mode 100644 docs/manual/adding-packages-virtual.txt > > diff --git a/docs/manual/adding-packages-virtual.txt b/docs/manual/adding-packages-virtual.txt > new file mode 100644 > index 0000000..6cccc4e > --- /dev/null > +++ b/docs/manual/adding-packages-virtual.txt > @@ -0,0 +1,102 @@ > +// -*- mode:doc; -*- > +// vim: set syntax=asciidoc: > + > +Infrastructure for virtual packages > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +[[virtual-package-tutorial]] > + > ++virtual-package+ tutorial > +^^^^^^^^^^^^^^^^^^^^^^^^^^ 'virtual-package' is not an infrastructure [ie. you can't use: $(eval $(virtual-package)) ], so I would suggest to just use: Virtual package tutorial ^^^^^^^^^^^^^^^^^^^^^^^^ [--SNIP--] > +First, let's create the virtual package. > + > +.Virtual package +Config.in+ file > +================================= The formatting of the title is weird. Here's what I've changed: Virtual package +Config.in+ file ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (notice: no leading dot, and an empty line after the ^^^ line) > +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 > +--------------------------- > +================================= Remove this === line. > +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 +*.mk+ file > +============================ Ditto title. > +The Makefile +package/something-virtual/something-virtual.mk+ should contain: > + > +--------------------------- > +01: ################################################################################ > +02: # > +03: # something-virtual > +04: # > +05: ################################################################################ > +06: > +07: SOMETHING_VIRTUAL_SOURCE = > +08: SOMETHING_VIRTUAL_DEPENDENCIES = $(call qstrip,$(BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL)) > +09: > +10: ifeq ($(BR2_PACKAGE_HAS_SOMETHING_VIRTUAL),y) > +11: ifeq ($(SOMETHING_VIRTUAL_DEPENDENCIES),) > +12: $(error No something-virtual implementation selected. Configuration error.) > +13: endif > +14: endif > +15: > +16: $(eval $(generic-package)) > +--------------------------- > +============================ Ditto ===. > +The Makefile is quite small as it will only check if a provider for the > +virtual package has been selected. > + > +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. > + > +.Provider +Config.in+ file > +========================== Ditto title. > +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 > +--------------------------- > +========================== Ditto ===. With those changes, the manual looks better, IMHO. Regards, Yann E. MORIN.
On Mon, Feb 24, 2014 at 08:01:04PM +0100, Yann E. MORIN wrote: > > 'virtual-package' is not an infrastructure [ie. you can't use: > $(eval $(virtual-package)) ], so I would suggest to just use: > > Virtual package tutorial > ^^^^^^^^^^^^^^^^^^^^^^^^ > Understood. > > +First, let's create the virtual package. > > + > > +.Virtual package +Config.in+ file > > +================================= > > The formatting of the title is weird. Here's what I've changed: > > Virtual package +Config.in+ file > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > > (notice: no leading dot, and an empty line after the ^^^ line) This was not a title, but an example, as I used +adding-packages-generic.txt+ for inspiration. I thought it was useful to have the code snippets listed in the example section, so the user could quickly jump to them. But it is true that: 1. not all the code snippets are listed as examples. 2. the Ascidoc example syntax, mixed with a code snippet, hurts the eyes (either in text or in the generated HTML). I'll change to plain and simple titles. Best regards, ELB
On 24/02/14 20:01, Yann E. MORIN wrote: > Eric, All, > > I think you should base this on master, since we think it would be very > interesting to have it in this release. I don't think it's that important. I don't think people will be adding virtual packages for their custom stuff, so this documentation is targeted towards people that will upstream packages. And for these, we can assume that they read the documentation of master and not that of whatever release they happen to be working with. And of course, if the $(virtual-package) infrastructure gets added, then this piece of documentation has to be entirely rewritten. > > On 2014-02-24 10:50 +0100, Eric Le Bihan spake thusly: >> The manual now features a new section with instructions about how to add a >> virtual package. >> >> Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr> >> --- >> docs/manual/adding-packages-virtual.txt | 102 +++++++++++++++++++++++++++++++ >> docs/manual/adding-packages.txt | 2 + >> 2 files changed, 104 insertions(+) >> create mode 100644 docs/manual/adding-packages-virtual.txt >> >> diff --git a/docs/manual/adding-packages-virtual.txt b/docs/manual/adding-packages-virtual.txt >> new file mode 100644 >> index 0000000..6cccc4e >> --- /dev/null >> +++ b/docs/manual/adding-packages-virtual.txt >> @@ -0,0 +1,102 @@ >> +// -*- mode:doc; -*- >> +// vim: set syntax=asciidoc: >> + >> +Infrastructure for virtual packages >> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >> + >> +[[virtual-package-tutorial]] >> + >> ++virtual-package+ tutorial >> +^^^^^^^^^^^^^^^^^^^^^^^^^^ > > 'virtual-package' is not an infrastructure [ie. you can't use: > $(eval $(virtual-package)) ], Well, soon you will be able to! :-) Regards, Arnout > so I would suggest to just use: > > Virtual package tutorial > ^^^^^^^^^^^^^^^^^^^^^^^^ > > [--SNIP--] >> +First, let's create the virtual package. >> + >> +.Virtual package +Config.in+ file >> +================================= > > The formatting of the title is weird. Here's what I've changed: > > Virtual package +Config.in+ file > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > > (notice: no leading dot, and an empty line after the ^^^ line) > >> +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 >> +--------------------------- >> +================================= > > Remove this === line. > >> +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 +*.mk+ file >> +============================ > > Ditto title. > >> +The Makefile +package/something-virtual/something-virtual.mk+ should contain: >> + >> +--------------------------- >> +01: ################################################################################ >> +02: # >> +03: # something-virtual >> +04: # >> +05: ################################################################################ >> +06: >> +07: SOMETHING_VIRTUAL_SOURCE = >> +08: SOMETHING_VIRTUAL_DEPENDENCIES = $(call qstrip,$(BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL)) >> +09: >> +10: ifeq ($(BR2_PACKAGE_HAS_SOMETHING_VIRTUAL),y) >> +11: ifeq ($(SOMETHING_VIRTUAL_DEPENDENCIES),) >> +12: $(error No something-virtual implementation selected. Configuration error.) >> +13: endif >> +14: endif >> +15: >> +16: $(eval $(generic-package)) >> +--------------------------- >> +============================ > > Ditto ===. > >> +The Makefile is quite small as it will only check if a provider for the >> +virtual package has been selected. >> + >> +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. >> + >> +.Provider +Config.in+ file >> +========================== > > Ditto title. > >> +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 >> +--------------------------- >> +========================== > > Ditto ===. > > With those changes, the manual looks better, IMHO. > > Regards, > Yann E. MORIN. >
diff --git a/docs/manual/adding-packages-virtual.txt b/docs/manual/adding-packages-virtual.txt new file mode 100644 index 0000000..6cccc4e --- /dev/null +++ b/docs/manual/adding-packages-virtual.txt @@ -0,0 +1,102 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +Infrastructure for virtual packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[[virtual-package-tutorial]] + ++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 infrastructure 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. + +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 +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 +*.mk+ file +============================ +The Makefile +package/something-virtual/something-virtual.mk+ should contain: + +--------------------------- +01: ################################################################################ +02: # +03: # something-virtual +04: # +05: ################################################################################ +06: +07: SOMETHING_VIRTUAL_SOURCE = +08: SOMETHING_VIRTUAL_DEPENDENCIES = $(call qstrip,$(BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL)) +09: +10: ifeq ($(BR2_PACKAGE_HAS_SOMETHING_VIRTUAL),y) +11: ifeq ($(SOMETHING_VIRTUAL_DEPENDENCIES),) +12: $(error No something-virtual implementation selected. Configuration error.) +13: endif +14: endif +15: +16: $(eval $(generic-package)) +--------------------------- +============================ + +The Makefile is quite small as it will only check if a provider for the +virtual package has been selected. + +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. + +.Provider +Config.in+ file +========================== +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! diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt index 745e33a..dbba930 100644 --- a/docs/manual/adding-packages.txt +++ b/docs/manual/adding-packages.txt @@ -24,6 +24,8 @@ include::adding-packages-luarocks.txt[] include::adding-packages-perl.txt[] +include::adding-packages-virtual.txt[] + include::adding-packages-hooks.txt[] include::adding-packages-gettext.txt[]
The manual now features a new section with instructions about how to add a virtual package. Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr> --- docs/manual/adding-packages-virtual.txt | 102 +++++++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 104 insertions(+) create mode 100644 docs/manual/adding-packages-virtual.txt