summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml146
1 files changed, 73 insertions, 73 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index afd8e49c14..7f59c39f2d 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -235,10 +235,10 @@
235 235
236 <para> 236 <para>
237 To create layers that are easier to maintain and that will 237 To create layers that are easier to maintain and that will
238 not impact builds for other machines, you should consider the 238 not impact builds for other machines, you should consider the
239 information in the following sections. 239 information in the following sections.
240 </para> 240 </para>
241 241
242 <section id='avoid-overlaying-entire-recipes'> 242 <section id='avoid-overlaying-entire-recipes'>
243 <title>Avoid "Overlaying" Entire Recipes</title> 243 <title>Avoid "Overlaying" Entire Recipes</title>
244 244
@@ -270,19 +270,19 @@
270 the layer to which it originally belongs. 270 the layer to which it originally belongs.
271 If this is the case, you need to address that deficiency 271 If this is the case, you need to address that deficiency
272 instead of overlaying the include file. 272 instead of overlaying the include file.
273 For example, consider how support plugins for the Qt 4 273 For example, consider how support plug-ins for the Qt 4
274 database are configured. 274 database are configured.
275 The Source Directory does not have MySQL or PostgreSQL. 275 The Source Directory does not have MySQL or PostgreSQL.
276 However, OpenEmbedded's layer <filename>meta-oe</filename> 276 However, OpenEmbedded's layer <filename>meta-oe</filename>
277 does. 277 does.
278 Consequently, <filename>meta-oe</filename> uses 278 Consequently, <filename>meta-oe</filename> uses
279 <filename>.bbappend</filename> files to modify the 279 <filename>.bbappend</filename> files to modify the
280 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to 280 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
281 enable the appropriate plugins. 281 enable the appropriate plug-ins.
282 This variable was added to the <filename>qt4.inc</filename> 282 This variable was added to the <filename>qt4.inc</filename>
283 include file in the Source Directory specifically to allow 283 include file in the Source Directory specifically to allow
284 the <filename>meta-oe</filename> layer to be able to control 284 the <filename>meta-oe</filename> layer to be able to control
285 which plugins are built. 285 which plug-ins are built.
286 </para> 286 </para>
287 </section> 287 </section>
288 288
@@ -290,105 +290,105 @@
290 <title>Structure Your Layers</title> 290 <title>Structure Your Layers</title>
291 291
292 <para> 292 <para>
293 Proper use of overrides within append files and placement 293 Proper use of overrides within append files and placement
294 of machine-specific files within your layer can ensure that 294 of machine-specific files within your layer can ensure that
295 a build is not using the wrong Metadata and negatively 295 a build is not using the wrong Metadata and negatively
296 impacting a build for a different machine. 296 impacting a build for a different machine.
297 Following are some examples: 297 Following are some examples:
298 <itemizedlist> 298 <itemizedlist>
299 <listitem><para><emphasis>Modifying Variables to support 299 <listitem><para><emphasis>Modifying Variables to support
300 a different machine:</emphasis> 300 a different machine:</emphasis>
301 Suppose you have a layer named 301 Suppose you have a layer named
302 <filename>meta-one</filename> that adds support 302 <filename>meta-one</filename> that adds support
303 for building machine "one". 303 for building machine "one".
304 To do so, you use an append file named 304 To do so, you use an append file named
305 <filename>base-files.bbappend</filename> and 305 <filename>base-files.bbappend</filename> and
306 create a dependency on "foo" by altering the 306 create a dependency on "foo" by altering the
307 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> 307 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
308 variable: 308 variable:
309 <literallayout class='monospaced'> 309 <literallayout class='monospaced'>
310 DEPENDS = "foo" 310 DEPENDS = "foo"
311 </literallayout> 311 </literallayout>
312 The dependency is created during any build that 312 The dependency is created during any build that
313 includes the layer 313 includes the layer
314 <filename>meta-one</filename>. 314 <filename>meta-one</filename>.
315 However, you might not want this dependency 315 However, you might not want this dependency
316 for all machines. 316 for all machines.
317 For example, suppose you are building for 317 For example, suppose you are building for
318 machine "two" but your 318 machine "two" but your
319 <filename>bblayers.conf</filename> file has the 319 <filename>bblayers.conf</filename> file has the
320 <filename>meta-one</filename> layer included. 320 <filename>meta-one</filename> layer included.
321 During the build, the 321 During the build, the
322 <filename>base-files</filename> for machine 322 <filename>base-files</filename> for machine
323 "two" will also have the dependency on 323 "two" will also have the dependency on
324 <filename>foo</filename>.</para> 324 <filename>foo</filename>.</para>
325 <para>To make sure your changes apply only when 325 <para>To make sure your changes apply only when
326 building machine "one", use a machine override 326 building machine "one", use a machine override
327 with the <filename>DEPENDS</filename> statement: 327 with the <filename>DEPENDS</filename> statement:
328 <literallayout class='monospaced'> 328 <literallayout class='monospaced'>
329 DEPENDS_one = "foo" 329 DEPENDS_one = "foo"
330 </literallayout> 330 </literallayout>
331 You should follow the same strategy when using 331 You should follow the same strategy when using
332 <filename>_append</filename> and 332 <filename>_append</filename> and
333 <filename>_prepend</filename> operations: 333 <filename>_prepend</filename> operations:
334 <literallayout class='monospaced'> 334 <literallayout class='monospaced'>
335 DEPENDS_append_one = " foo" 335 DEPENDS_append_one = " foo"
336 DEPENDS_prepend_one = "foo " 336 DEPENDS_prepend_one = "foo "
337 </literallayout> 337 </literallayout>
338 <note> 338 <note>
339 Avoiding "+=" and "=+" and using 339 Avoiding "+=" and "=+" and using
340 machine-specific 340 machine-specific
341 <filename>_append</filename> 341 <filename>_append</filename>
342 and <filename>_prepend</filename> operations 342 and <filename>_prepend</filename> operations
343 is recommended as well. 343 is recommended as well.
344 </note></para></listitem> 344 </note></para></listitem>
345 <listitem><para><emphasis>Place Machine-Specific Files 345 <listitem><para><emphasis>Place Machine-Specific Files
346 in Machine-Specific Locations:</emphasis> 346 in Machine-Specific Locations:</emphasis>
347 When you have a base recipe, such as 347 When you have a base recipe, such as
348 <filename>base-files.bb</filename>, that 348 <filename>base-files.bb</filename>, that
349 contains a 349 contains a
350 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 350 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
351 statement to a file, you can use an append file 351 statement to a file, you can use an append file
352 to cause the build to use your own version of 352 to cause the build to use your own version of
353 the file. 353 the file.
354 For example, an append file in your layer at 354 For example, an append file in your layer at
355 <filename>/meta-one/recipes-core/base-files/base-files.bbappend</filename> 355 <filename>/meta-one/recipes-core/base-files/base-files.bbappend</filename>
356 could extend 356 could extend
357 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> 357 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
358 using 358 using
359 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> 359 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
360 as follows: 360 as follows:
361 <literallayout class='monospaced'> 361 <literallayout class='monospaced'>
362 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:" 362 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
363 </literallayout> 363 </literallayout>
364 The build for machine "one" will pick up your 364 The build for machine "one" will pick up your
365 machine-specific file as long as you have the 365 machine-specific file as long as you have the
366 file in 366 file in
367 <filename>/meta-one/recipes-core/base-files/base-files/</filename>. 367 <filename>/meta-one/recipes-core/base-files/base-files/</filename>.
368 However, if you are building for a different 368 However, if you are building for a different
369 machine and the 369 machine and the
370 <filename>bblayers.conf</filename> file includes 370 <filename>bblayers.conf</filename> file includes
371 the <filename>meta-one</filename> layer and 371 the <filename>meta-one</filename> layer and
372 the location of your machine-specific file is 372 the location of your machine-specific file is
373 the first location where that file is found 373 the first location where that file is found
374 according to <filename>FILESPATH</filename>, 374 according to <filename>FILESPATH</filename>,
375 builds for all machines will also use that 375 builds for all machines will also use that
376 machine-specific file.</para> 376 machine-specific file.</para>
377 <para>You can make sure that a machine-specific 377 <para>You can make sure that a machine-specific
378 file is used for a particular machine by putting 378 file is used for a particular machine by putting
379 the file in a subdirectory specific to the 379 the file in a subdirectory specific to the
380 machine. 380 machine.
381 For example, rather than placing the file in 381 For example, rather than placing the file in
382 <filename>/meta-one/recipes-core/base-files/base-files/</filename> 382 <filename>/meta-one/recipes-core/base-files/base-files/</filename>
383 as shown above, put it in 383 as shown above, put it in
384 <filename>/meta-one/recipes-core/base-files/base-files/one/</filename>. 384 <filename>/meta-one/recipes-core/base-files/base-files/one/</filename>.
385 Not only does this make sure the file is used 385 Not only does this make sure the file is used
386 only when building for machine "one" but the 386 only when building for machine "one" but the
387 build process locates the file more quickly.</para> 387 build process locates the file more quickly.</para>
388 <para>In summary, you need to place all files 388 <para>In summary, you need to place all files
389 referenced from <filename>SRC_URI</filename> 389 referenced from <filename>SRC_URI</filename>
390 in a machine-specific subdirectory within the 390 in a machine-specific subdirectory within the
391 layer in order to restrict those files to 391 layer in order to restrict those files to
392 machine-specific builds.</para></listitem> 392 machine-specific builds.</para></listitem>
393 </itemizedlist> 393 </itemizedlist>
394 </para> 394 </para>
@@ -2596,8 +2596,8 @@
2596 If you have distro-specific configuration files 2596 If you have distro-specific configuration files
2597 that are included by an existing recipe, you should 2597 that are included by an existing recipe, you should
2598 add a <filename>.bbappend</filename> for those. 2598 add a <filename>.bbappend</filename> for those.
2599 For general information and recommendations 2599 For general information and recommendations
2600 on how to add recipes to your layer, see the 2600 on how to add recipes to your layer, see the
2601 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>" 2601 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
2602 and 2602 and
2603 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>" 2603 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
@@ -3076,7 +3076,7 @@
3076 <title>Excluding Packages from an Image</title> 3076 <title>Excluding Packages from an Image</title>
3077 3077
3078 <para> 3078 <para>
3079 You might find it necessary to prevent specific packages 3079 You might find it necessary to prevent specific packages
3080 from being installed into an image. 3080 from being installed into an image.
3081 If so, you can use several variables to direct the build 3081 If so, you can use several variables to direct the build
3082 system to essentially ignore installing recommended packages 3082 system to essentially ignore installing recommended packages
@@ -3084,31 +3084,31 @@
3084 </para> 3084 </para>
3085 3085
3086 <para> 3086 <para>
3087 The following list introduces variables you can use to 3087 The following list introduces variables you can use to
3088 prevent packages from being installed into your image. 3088 prevent packages from being installed into your image.
3089 Each of these variables only works with IPK and RPM 3089 Each of these variables only works with IPK and RPM
3090 package types. 3090 package types.
3091 Support for Debian packages does not exist. 3091 Support for Debian packages does not exist.
3092 Also, you can use these variables from your 3092 Also, you can use these variables from your
3093 <filename>local.conf</filename> file or attach them to a 3093 <filename>local.conf</filename> file or attach them to a
3094 specific image recipe by using a recipe name override. 3094 specific image recipe by using a recipe name override.
3095 For more detail on the variables, see the descriptions in the 3095 For more detail on the variables, see the descriptions in the
3096 Yocto Project Reference Manual's glossary chapter. 3096 Yocto Project Reference Manual's glossary chapter.
3097 <itemizedlist> 3097 <itemizedlist>
3098 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>: 3098 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>:
3099 Use this variable to specify "recommended-only" 3099 Use this variable to specify "recommended-only"
3100 packages that you do not want installed. 3100 packages that you do not want installed.
3101 </para></listitem> 3101 </para></listitem>
3102 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>: 3102 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>:
3103 Use this variable to prevent all "recommended-only" 3103 Use this variable to prevent all "recommended-only"
3104 packages from being installed. 3104 packages from being installed.
3105 </para></listitem> 3105 </para></listitem>
3106 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>: 3106 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
3107 Use this variable to prevent specific packages from 3107 Use this variable to prevent specific packages from
3108 being installed regardless of whether they are 3108 being installed regardless of whether they are
3109 "recommended-only" or not. 3109 "recommended-only" or not.
3110 You need to realize that the build process could 3110 You need to realize that the build process could
3111 fail with an error when you 3111 fail with an error when you
3112 prevent the installation of a package whose presence 3112 prevent the installation of a package whose presence
3113 is required by an installed package. 3113 is required by an installed package.
3114 </para></listitem> 3114 </para></listitem>
@@ -3393,7 +3393,7 @@
3393 3393
3394 <para> 3394 <para>
3395 Many pieces of software split functionality into optional 3395 Many pieces of software split functionality into optional
3396 modules (or plugins) and the plugins that are built 3396 modules (or plug-ins) and the plug-ins that are built
3397 might depend on configuration options. 3397 might depend on configuration options.
3398 To avoid having to duplicate the logic that determines what 3398 To avoid having to duplicate the logic that determines what
3399 modules are available in your recipe or to avoid having 3399 modules are available in your recipe or to avoid having
@@ -4505,10 +4505,10 @@
4505 <title>Examining Builds Using the Toaster API</title> 4505 <title>Examining Builds Using the Toaster API</title>
4506 4506
4507 <para> 4507 <para>
4508 Toaster is an Application Programming Interface (API) to the 4508 Toaster is an Application Programming Interface (API) to the
4509 OpenEmbedded build system, which uses BitBake. 4509 OpenEmbedded build system, which uses BitBake.
4510 The interface is a Representational State Transfer (REST) API 4510 The interface is a Representational State Transfer (REST) API
4511 that queries for and returns build information using 4511 that queries for and returns build information using
4512 <filename>GET</filename> and <filename>JSON</filename>. 4512 <filename>GET</filename> and <filename>JSON</filename>.
4513 </para> 4513 </para>
4514 4514
@@ -4528,16 +4528,16 @@
4528 </para> 4528 </para>
4529 4529
4530 <para> 4530 <para>
4531 In summary, the search operation retrieves a set of objects from 4531 In summary, the search operation retrieves a set of objects from
4532 a data store used to collect build information. 4532 a data store used to collect build information.
4533 The result contains all the data for the objects being returned. 4533 The result contains all the data for the objects being returned.
4534 You can order the results of the search by key and the search 4534 You can order the results of the search by key and the search
4535 parameters are consistent for all object types. 4535 parameters are consistent for all object types.
4536 </para> 4536 </para>
4537 4537
4538 <para> 4538 <para>
4539 For complete information on the API and its search operation 4539 For complete information on the API and its search operation
4540 URI, parameters, and reposes, see the 4540 URI, parameters, and reposes, see the
4541 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink> 4541 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
4542 Wiki page. 4542 Wiki page.
4543 </para> 4543 </para>