summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/concepts-manual/concepts-manual-concepts.xml63
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml125
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 @@
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