concepts-manual, dev-manual: Moved the virtual providers to dev-manual

This topic was deemed unfit for concepts so I moved it to the dev-manual and rewrote it to be "Using Virtual Providers". (From yocto-docs rev: df7d48ac4fcf7ece75681ccf0bbb5699f7ff5ea6) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
author: Scott Rifenbark <srifenbark@gmail.com> 2018-02-23 16:51:18 -0800
committer: Richard Purdie <richard.purdie@linuxfoundation.org> 2018-03-03 08:35:25 +0000
commit: c6f2b40f1d50d0772f2c78f0e4046628ffc1aaea (patch)
tree: 3ad3914df3470d567423b470a41e769bfdf8da33 /documentation
parent: bb4ab5a65305b5bafdbdfe2ebf907dbde19368bf (diff)
download: poky-c6f2b40f1d50d0772f2c78f0e4046628ffc1aaea.tar.gz
2 files changed, 125 insertions, 63 deletions
diff --git a/documentation/concepts-manual/concepts-manual-concepts.xml b/documentation/concepts-manual/concepts-manual-concepts.xml
index fb02e2b512..0d01372c2e 100644
--- a/documentation/concepts-manual/concepts-manual-concepts.xml
+++ b/documentation/concepts-manual/concepts-manual-concepts.xml
@@ -153,67 +153,6 @@
            </para>
        </section>
-        <section id='metadata-virtual-providers'>
-            <title>Metadata (Virtual Providers)</title>
-            <para>
-                Prior to the build, if you know that several different recipes
-                provide the same functionality, you can use a virtual provider
-                (i.e. <filename>virtual/*</filename>) as a placeholder for the
-                actual provider.
-                The actual provider would be determined at build time.
-                In this case, you should add <filename>virtual/*</filename>
-                to
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
-                rather than listing the specified provider.
-                You would select the actual provider by setting the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
-                variable (i.e.
-                <filename>PREFERRED_PROVIDER_virtual/*</filename>)
-                in the build's configuration file (e.g.
-                <filename>poky/build/conf/local.conf</filename>).
-                <note>
-                    Any recipe that
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
-                    a <filename>virtual/*</filename> item that is ultimately
-                    not selected through
-                    <filename>PREFERRED_PROVIDER</filename> does not get built.
-                    Preventing these recipes from building is usually the
-                    desired behavior since this mechanism's purpose is to
-                    select between mutually exclusive alternative providers.
-                </note>
-            </para>
-            <para>
-                The following lists specific examples of virtual providers:
-                <itemizedlist>
-                    <listitem><para>
-                        <filename>virtual/mesa</filename>:
-                        Provides <filename>gbm.pc</filename>.
-                        </para></listitem>
-                    <listitem><para>
-                        <filename>virtual/egl</filename>:
-                        Provides <filename>egl.pc</filename> and possibly
-                        <filename>wayland-egl.pc</filename>.
-                        </para></listitem>
-                    <listitem><para>
-                        <filename>virtual/libgl</filename>:
-                        Provides <filename>gl.pc</filename> (i.e. libGL).
-                        </para></listitem>
-                    <listitem><para>
-                        <filename>virtual/libgles1</filename>:
-                        Provides <filename>glesv1_cm.pc</filename>
-                        (i.e. libGLESv1_CM).
-                        </para></listitem>
-                    <listitem><para>
-                        <filename>virtual/libgles2</filename>:
-                        Provides <filename>glesv2.pc</filename>
-                        (i.e. libGLESv2).
-                        </para></listitem>
-                </itemizedlist>
-            </para>
-        </section>
        <section id='concepts-components-classes'>
            <title>Classes</title>
@@ -248,8 +187,6 @@
        </section>
    </section>
    <section id="development-concepts">
        <title>Development Concepts</title>
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 20a38322b1..4cb99639b8 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2898,6 +2898,131 @@
            </para>
        </section>
+        <section id='metadata-virtual-providers'>
+            <title>Using Virtual Providers</title>
+            <para>
+                Prior to a build, if you know that several different recipes
+                provide the same functionality, you can use a virtual provider
+                (i.e. <filename>virtual/*</filename>) as a placeholder for the
+                actual provider.
+                The actual provider is determined at build-time.
+            </para>
+            <para>
+                A common scenario where a virtual provider is used would be
+                for the kernel recipe.
+                Suppose you have three kernel recipes whose
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
+                values map to <filename>kernel-big</filename>,
+                <filename>kernel-mid</filename>, and
+                <filename>kernel-small</filename>.
+                Furthermore, each of these recipes in some way uses a
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
+                statement that essentially identifies itself as being able
+                to provide <filename>virtual/kernel</filename>.
+                Here is one way through the
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-kernel'><filename>kernel</filename></ulink>
+                class:
+                <literallayout class='monospaced'>
+     PROVIDES += "${@ "virtual/kernel" if (d.getVar("KERNEL_PACKAGE_NAME") == "kernel") else "" }"
+                </literallayout>
+                Any recipe that inherits the <filename>kernel</filename> class
+                is going to utilize a <filename>PROVIDES</filename> statement
+                that identifies that recipe as being able to provide the
+                <filename>virtual/kernel</filename> item.
+            </para>
+            <para>
+                Now comes the time to actually build an image and you need a
+                kernel recipe, but which one?
+                You can configure your build to call out the kernel recipe
+                you want by using the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
+                variable.
+                As an example, consider the
+                <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/x86-base.inc'><filename>x86-base.inc</filename></ulink>
+                include file.
+                This include file is the reason all x86-based machines use the
+                <filename>linux-yocto</filename> kernel.
+                Here are the relevant lines from the include file:
+                <literallayout class='monospaced'>
+     PREFERRED_PROVIDER_virtual/kernel ??= "linux-yocto"
+     PREFERRED_VERSION_linux-yocto ??= "4.15%"
+                </literallayout>
+            </para>
+            <para>
+                When you use a virtual provider, you do not have to
+                "hard code" a recipe name as a build dependency.
+                You can use the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+                variable to state the build is dependent on
+                <filename>virtual/kernel</filename> for example:
+                <literallayout class='monospaced'>
+     DEPENDS = "virtual/kernel"
+                </literallayout>
+                During the build, the OpenEmbedded build system picks
+                the correct recipe needed for the
+                <filename>virtual/kernel</filename> dependency based on the
+                <filename>PREFERRED_PROVIDER</filename> variable.
+                If you want to use the small kernel mentioned at the beginning
+                of this section, configure your build as follows:
+                <literallayout class='monospaced'>
+     PREFERRED_PROVIDER_virtual/kernel ??= "kernel-small"
+                </literallayout>
+                <note>
+                    Any recipe that
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
+                    a <filename>virtual/*</filename> item that is ultimately
+                    not selected through
+                    <filename>PREFERRED_PROVIDER</filename> does not get built.
+                    Preventing these recipes from building is usually the
+                    desired behavior since this mechanism's purpose is to
+                    select between mutually exclusive alternative providers.
+                </note>
+            </para>
+            <para>
+                The following lists specific examples of virtual providers:
+                <itemizedlist>
+                    <listitem><para>
+                        <filename>virtual/kernel</filename>:
+                        Provides the name of the kernel recipe to use when
+                        building a kernel image.
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>virtual/bootloader</filename>:
+                        Provides the name of the bootloader to use when
+                        building an image.
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>virtual/mesa</filename>:
+                        Provides <filename>gbm.pc</filename>.
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>virtual/egl</filename>:
+                        Provides <filename>egl.pc</filename> and possibly
+                        <filename>wayland-egl.pc</filename>.
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>virtual/libgl</filename>:
+                        Provides <filename>gl.pc</filename> (i.e. libGL).
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>virtual/libgles1</filename>:
+                        Provides <filename>glesv1_cm.pc</filename>
+                        (i.e. libGLESv1_CM).
+                        </para></listitem>
+                    <listitem><para>
+                        <filename>virtual/libgles2</filename>:
+                        Provides <filename>glesv2.pc</filename>
+                        (i.e. libGLESv2).
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
        <section id='properly-versioning-pre-release-recipes'>
            <title>Properly Versioning Pre-Release Recipes</title>
author	Scott Rifenbark <srifenbark@gmail.com>	2018-02-23 16:51:18 -0800
committer	Richard Purdie <richard.purdie@linuxfoundation.org>	2018-03-03 08:35:25 +0000
commit	c6f2b40f1d50d0772f2c78f0e4046628ffc1aaea (patch)
tree	3ad3914df3470d567423b470a41e769bfdf8da33 /documentation
parent	bb4ab5a65305b5bafdbdfe2ebf907dbde19368bf (diff)
download	poky-c6f2b40f1d50d0772f2c78f0e4046628ffc1aaea.tar.gz

diff --git a/documentation/concepts-manual/concepts-manual-concepts.xml b/documentation/concepts-manual/concepts-manual-concepts.xml index fb02e2b512..0d01372c2e 100644 --- a/documentation/concepts-manual/concepts-manual-concepts.xml +++ b/documentation/concepts-manual/concepts-manual-concepts.xml
@@ -153,67 +153,6 @@
153	</para>	153	</para>
154	</section>	154	</section>
155		155
156	<section id='metadata-virtual-providers'>
157	<title>Metadata (Virtual Providers)</title>
158
159	<para>
160	Prior to the build, if you know that several different recipes
161	provide the same functionality, you can use a virtual provider
162	(i.e. <filename>virtual/*</filename>) as a placeholder for the
163	actual provider.
164	The actual provider would be determined at build time.
165	In this case, you should add <filename>virtual/*</filename>
166	to
167	<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
168	rather than listing the specified provider.
169	You would select the actual provider by setting the
170	<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
171	variable (i.e.
172	<filename>PREFERRED_PROVIDER_virtual/*</filename>)
173	in the build's configuration file (e.g.
174	<filename>poky/build/conf/local.conf</filename>).
175	<note>
176	Any recipe that
177	<ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
178	a <filename>virtual/*</filename> item that is ultimately
179	not selected through
180	<filename>PREFERRED_PROVIDER</filename> does not get built.
181	Preventing these recipes from building is usually the
182	desired behavior since this mechanism's purpose is to
183	select between mutually exclusive alternative providers.
184	</note>
185	</para>
186
187	<para>
188	The following lists specific examples of virtual providers:
189	<itemizedlist>
190	<listitem><para>
191	<filename>virtual/mesa</filename>:
192	Provides <filename>gbm.pc</filename>.
193	</para></listitem>
194	<listitem><para>
195	<filename>virtual/egl</filename>:
196	Provides <filename>egl.pc</filename> and possibly
197	<filename>wayland-egl.pc</filename>.
198	</para></listitem>
199	<listitem><para>
200	<filename>virtual/libgl</filename>:
201	Provides <filename>gl.pc</filename> (i.e. libGL).
202	</para></listitem>
203	<listitem><para>
204	<filename>virtual/libgles1</filename>:
205	Provides <filename>glesv1_cm.pc</filename>
206	(i.e. libGLESv1_CM).
207	</para></listitem>
208	<listitem><para>
209	<filename>virtual/libgles2</filename>:
210	Provides <filename>glesv2.pc</filename>
211	(i.e. libGLESv2).
212	</para></listitem>
213	</itemizedlist>
214	</para>
215	</section>
216
217	<section id='concepts-components-classes'>	156	<section id='concepts-components-classes'>
218	<title>Classes</title>	157	<title>Classes</title>
219		158
@@ -248,8 +187,6 @@
248	</section>	187	</section>
249	</section>	188	</section>
250		189
251
252
253	<section id="development-concepts">	190	<section id="development-concepts">
254	<title>Development Concepts</title>	191	<title>Development Concepts</title>
255		192


diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 20a38322b1..4cb99639b8 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2898,6 +2898,131 @@
2898	</para>	2898	</para>
2899	</section>	2899	</section>
2900		2900
		2901	<section id='metadata-virtual-providers'>
		2902	<title>Using Virtual Providers</title>
		2903
		2904	<para>
		2905	Prior to a build, if you know that several different recipes
		2906	provide the same functionality, you can use a virtual provider
		2907	(i.e. <filename>virtual/*</filename>) as a placeholder for the
		2908	actual provider.
		2909	The actual provider is determined at build-time.
		2910	</para>
		2911
		2912	<para>
		2913	A common scenario where a virtual provider is used would be
		2914	for the kernel recipe.
		2915	Suppose you have three kernel recipes whose
		2916	<ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
		2917	values map to <filename>kernel-big</filename>,
		2918	<filename>kernel-mid</filename>, and
		2919	<filename>kernel-small</filename>.
		2920	Furthermore, each of these recipes in some way uses a
		2921	<ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
		2922	statement that essentially identifies itself as being able
		2923	to provide <filename>virtual/kernel</filename>.
		2924	Here is one way through the
		2925	<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-kernel'><filename>kernel</filename></ulink>
		2926	class:
		2927	<literallayout class='monospaced'>
		2928	PROVIDES += "${@ "virtual/kernel" if (d.getVar("KERNEL_PACKAGE_NAME") == "kernel") else "" }"
		2929	</literallayout>
		2930	Any recipe that inherits the <filename>kernel</filename> class
		2931	is going to utilize a <filename>PROVIDES</filename> statement
		2932	that identifies that recipe as being able to provide the
		2933	<filename>virtual/kernel</filename> item.
		2934	</para>
		2935
		2936	<para>
		2937	Now comes the time to actually build an image and you need a
		2938	kernel recipe, but which one?
		2939	You can configure your build to call out the kernel recipe
		2940	you want by using the
		2941	<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
		2942	variable.
		2943	As an example, consider the
		2944	<ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/x86-base.inc'><filename>x86-base.inc</filename></ulink>
		2945	include file.
		2946	This include file is the reason all x86-based machines use the
		2947	<filename>linux-yocto</filename> kernel.
		2948	Here are the relevant lines from the include file:
		2949	<literallayout class='monospaced'>
		2950	PREFERRED_PROVIDER_virtual/kernel ??= "linux-yocto"
		2951	PREFERRED_VERSION_linux-yocto ??= "4.15%"
		2952	</literallayout>
		2953	</para>
		2954
		2955	<para>
		2956	When you use a virtual provider, you do not have to
		2957	"hard code" a recipe name as a build dependency.
		2958	You can use the
		2959	<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
		2960	variable to state the build is dependent on
		2961	<filename>virtual/kernel</filename> for example:
		2962	<literallayout class='monospaced'>
		2963	DEPENDS = "virtual/kernel"
		2964	</literallayout>
		2965	During the build, the OpenEmbedded build system picks
		2966	the correct recipe needed for the
		2967	<filename>virtual/kernel</filename> dependency based on the
		2968	<filename>PREFERRED_PROVIDER</filename> variable.
		2969	If you want to use the small kernel mentioned at the beginning
		2970	of this section, configure your build as follows:
		2971	<literallayout class='monospaced'>
		2972	PREFERRED_PROVIDER_virtual/kernel ??= "kernel-small"
		2973	</literallayout>
		2974	<note>
		2975	Any recipe that
		2976	<ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
		2977	a <filename>virtual/*</filename> item that is ultimately
		2978	not selected through
		2979	<filename>PREFERRED_PROVIDER</filename> does not get built.
		2980	Preventing these recipes from building is usually the
		2981	desired behavior since this mechanism's purpose is to
		2982	select between mutually exclusive alternative providers.
		2983	</note>
		2984	</para>
		2985
		2986	<para>
		2987	The following lists specific examples of virtual providers:
		2988	<itemizedlist>
		2989	<listitem><para>
		2990	<filename>virtual/kernel</filename>:
		2991	Provides the name of the kernel recipe to use when
		2992	building a kernel image.
		2993	</para></listitem>
		2994	<listitem><para>
		2995	<filename>virtual/bootloader</filename>:
		2996	Provides the name of the bootloader to use when
		2997	building an image.
		2998	</para></listitem>
		2999	<listitem><para>
		3000	<filename>virtual/mesa</filename>:
		3001	Provides <filename>gbm.pc</filename>.
		3002	</para></listitem>
		3003	<listitem><para>
		3004	<filename>virtual/egl</filename>:
		3005	Provides <filename>egl.pc</filename> and possibly
		3006	<filename>wayland-egl.pc</filename>.
		3007	</para></listitem>
		3008	<listitem><para>
		3009	<filename>virtual/libgl</filename>:
		3010	Provides <filename>gl.pc</filename> (i.e. libGL).
		3011	</para></listitem>
		3012	<listitem><para>
		3013	<filename>virtual/libgles1</filename>:
		3014	Provides <filename>glesv1_cm.pc</filename>
		3015	(i.e. libGLESv1_CM).
		3016	</para></listitem>
		3017	<listitem><para>
		3018	<filename>virtual/libgles2</filename>:
		3019	Provides <filename>glesv2.pc</filename>
		3020	(i.e. libGLESv2).
		3021	</para></listitem>
		3022	</itemizedlist>
		3023	</para>
		3024	</section>
		3025
2901	<section id='properly-versioning-pre-release-recipes'>	3026	<section id='properly-versioning-pre-release-recipes'>
2902	<title>Properly Versioning Pre-Release Recipes</title>	3027	<title>Properly Versioning Pre-Release Recipes</title>
2903		3028