diff options
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 146 |
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> |