diff options
author | Richard Purdie <richard.purdie@linuxfoundation.org> | 2020-09-13 22:03:26 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2020-09-17 10:09:35 +0100 |
commit | 688e49bb5e6e61b5c0dbbe6b2c3bdf1c5a4bef8d (patch) | |
tree | 4c2141ae1261735f6ee2383ab016a602232b309e | |
parent | 292598164a304a3da3288e6fb8963f13045d1e7f (diff) | |
download | poky-688e49bb5e6e61b5c0dbbe6b2c3bdf1c5a4bef8d.tar.gz |
sphinx: dev-manual: Various URL, code block and other fixes to imported data
(From yocto-docs rev: 8e73d870e9dc2df416f5c5cf5b10ef552be0aa6d)
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.rst | 4263 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual-intro.rst | 13 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual-qemu.rst | 139 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual-start.rst | 325 |
4 files changed, 3200 insertions, 1540 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst index c9b8a834cf..05060bb053 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.rst +++ b/documentation/dev-manual/dev-manual-common-tasks.rst | |||
@@ -17,9 +17,9 @@ The OpenEmbedded build system supports organizing | |||
17 | :term:`Metadata` into multiple layers. | 17 | :term:`Metadata` into multiple layers. |
18 | Layers allow you to isolate different types of customizations from each | 18 | Layers allow you to isolate different types of customizations from each |
19 | other. For introductory information on the Yocto Project Layer Model, | 19 | other. For introductory information on the Yocto Project Layer Model, |
20 | see the "`The Yocto Project Layer | 20 | see the |
21 | Model <&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model>`__" section in | 21 | ":ref:`overview-manual/overview-manual-yp-intro:the yocto project layer model`" |
22 | the Yocto Project Overview and Concepts Manual. | 22 | section in the Yocto Project Overview and Concepts Manual. |
23 | 23 | ||
24 | Creating Your Own Layer | 24 | Creating Your Own Layer |
25 | ----------------------- | 25 | ----------------------- |
@@ -28,12 +28,10 @@ It is very easy to create your own layers to use with the OpenEmbedded | |||
28 | build system. The Yocto Project ships with tools that speed up creating | 28 | build system. The Yocto Project ships with tools that speed up creating |
29 | layers. This section describes the steps you perform by hand to create | 29 | layers. This section describes the steps you perform by hand to create |
30 | layers so that you can better understand them. For information about the | 30 | layers so that you can better understand them. For information about the |
31 | layer-creation tools, see the "`Creating a New BSP Layer Using the | 31 | layer-creation tools, see the |
32 | ``bitbake-layers`` | 32 | ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" |
33 | Script <&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script>`__" | ||
34 | section in the Yocto Project Board Support Package (BSP) Developer's | 33 | section in the Yocto Project Board Support Package (BSP) Developer's |
35 | Guide and the "`Creating a General Layer Using the ``bitbake-layers`` | 34 | Guide and the ":ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" |
36 | Script <#creating-a-general-layer-using-the-bitbake-layers-script>`__" | ||
37 | section further down in this manual. | 35 | section further down in this manual. |
38 | 36 | ||
39 | Follow these general steps to create your layer without using tools: | 37 | Follow these general steps to create your layer without using tools: |
@@ -49,13 +47,22 @@ Follow these general steps to create your layer without using tools: | |||
49 | 2. *Create a Directory:* Create the directory for your layer. When you | 47 | 2. *Create a Directory:* Create the directory for your layer. When you |
50 | create the layer, be sure to create the directory in an area not | 48 | create the layer, be sure to create the directory in an area not |
51 | associated with the Yocto Project :term:`Source Directory` | 49 | associated with the Yocto Project :term:`Source Directory` |
52 | (e.g. the cloned | 50 | (e.g. the cloned ``poky`` repository). |
53 | ``poky`` repository). | ||
54 | 51 | ||
55 | While not strictly required, prepend the name of the directory with | 52 | While not strictly required, prepend the name of the directory with |
56 | the string "meta-". For example: meta-mylayer meta-GUI_xyz | 53 | the string "meta-". For example: |
57 | meta-mymachine With rare exceptions, a layer's name follows this | 54 | :: |
58 | form: meta-root_name Following this layer naming convention can save | 55 | |
56 | meta-mylayer | ||
57 | meta-GUI_xyz | ||
58 | meta-mymachine | ||
59 | |||
60 | With rare exceptions, a layer's name follows this form: | ||
61 | :: | ||
62 | |||
63 | meta-root_name | ||
64 | |||
65 | Following this layer naming convention can save | ||
59 | you trouble later when tools, components, or variables "assume" your | 66 | you trouble later when tools, components, or variables "assume" your |
60 | layer name begins with "meta-". A notable example is in configuration | 67 | layer name begins with "meta-". A notable example is in configuration |
61 | files as shown in the following step where layer names without the | 68 | files as shown in the following step where layer names without the |
@@ -71,14 +78,23 @@ Follow these general steps to create your layer without using tools: | |||
71 | :yocto_git:`Source Repositories </cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf>` | 78 | :yocto_git:`Source Repositories </cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf>` |
72 | demonstrates the required syntax. For your layer, you need to replace | 79 | demonstrates the required syntax. For your layer, you need to replace |
73 | "yoctobsp" with a unique identifier for your layer (e.g. "machinexyz" | 80 | "yoctobsp" with a unique identifier for your layer (e.g. "machinexyz" |
74 | for a layer named "meta-machinexyz"): # We have a conf and classes | 81 | for a layer named "meta-machinexyz"): |
75 | directory, add to BBPATH BBPATH .= ":${LAYERDIR}" # We have | 82 | :: |
76 | recipes-\* directories, add to BBFILES BBFILES += | 83 | |
77 | "${LAYERDIR}/recipes-*/*/*.bb \\ ${LAYERDIR}/recipes-*/*/*.bbappend" | 84 | # We have a conf and classes directory, add to BBPATH |
78 | BBFILE_COLLECTIONS += "yoctobsp" BBFILE_PATTERN_yoctobsp = | 85 | BBPATH .= ":${LAYERDIR}" |
79 | "^${LAYERDIR}/" BBFILE_PRIORITY_yoctobsp = "5" LAYERVERSION_yoctobsp | 86 | |
80 | = "4" LAYERSERIES_COMPAT_yoctobsp = "DISTRO_NAME_NO_CAP" Following is | 87 | # We have recipes-\* directories, add to BBFILES |
81 | an explanation of the layer configuration file: | 88 | BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ |
89 | ${LAYERDIR}/recipes-*/*/*.bbappend" | ||
90 | |||
91 | BBFILE_COLLECTIONS += "yoctobsp" | ||
92 | BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" | ||
93 | BBFILE_PRIORITY_yoctobsp = "5" | ||
94 | LAYERVERSION_yoctobsp = "4" | ||
95 | LAYERSERIES_COMPAT_yoctobsp = "dunfell" | ||
96 | |||
97 | Following is an explanation of the layer configuration file: | ||
82 | 98 | ||
83 | - :term:`BBPATH`: Adds the layer's | 99 | - :term:`BBPATH`: Adds the layer's |
84 | root directory to BitBake's search path. Through the use of the | 100 | root directory to BitBake's search path. Through the use of the |
@@ -184,7 +200,12 @@ following list: | |||
184 | machine "one". To do so, you use an append file named | 200 | machine "one". To do so, you use an append file named |
185 | ``base-files.bbappend`` and create a dependency on "foo" by | 201 | ``base-files.bbappend`` and create a dependency on "foo" by |
186 | altering the :term:`DEPENDS` | 202 | altering the :term:`DEPENDS` |
187 | variable: DEPENDS = "foo" The dependency is created during any | 203 | variable: |
204 | :: | ||
205 | |||
206 | DEPENDS = "foo" | ||
207 | |||
208 | The dependency is created during any | ||
188 | build that includes the layer ``meta-one``. However, you might not | 209 | build that includes the layer ``meta-one``. However, you might not |
189 | want this dependency for all machines. For example, suppose you | 210 | want this dependency for all machines. For example, suppose you |
190 | are building for machine "two" but your ``bblayers.conf`` file has | 211 | are building for machine "two" but your ``bblayers.conf`` file has |
@@ -195,20 +216,31 @@ following list: | |||
195 | To make sure your changes apply only when building machine "one", | 216 | To make sure your changes apply only when building machine "one", |
196 | use a machine override with the ``DEPENDS`` statement: DEPENDS_one | 217 | use a machine override with the ``DEPENDS`` statement: DEPENDS_one |
197 | = "foo" You should follow the same strategy when using ``_append`` | 218 | = "foo" You should follow the same strategy when using ``_append`` |
198 | and ``_prepend`` operations: DEPENDS_append_one = " foo" | 219 | and ``_prepend`` operations: |
199 | DEPENDS_prepend_one = "foo " As an actual example, here's a | 220 | :: |
221 | |||
222 | DEPENDS_append_one = " foo" | ||
223 | DEPENDS_prepend_one = "foo " | ||
224 | |||
225 | As an actual example, here's a | ||
200 | snippet from the generic kernel include file ``linux-yocto.inc``, | 226 | snippet from the generic kernel include file ``linux-yocto.inc``, |
201 | wherein the kernel compile and link options are adjusted in the | 227 | wherein the kernel compile and link options are adjusted in the |
202 | case of a subset of the supported architectures: | 228 | case of a subset of the supported architectures: |
203 | DEPENDS_append_aarch64 = " libgcc" KERNEL_CC_append_aarch64 = " | 229 | :: |
204 | ${TOOLCHAIN_OPTIONS}" KERNEL_LD_append_aarch64 = " | 230 | |
205 | ${TOOLCHAIN_OPTIONS}" DEPENDS_append_nios2 = " libgcc" | 231 | DEPENDS_append_aarch64 = " libgcc" |
206 | KERNEL_CC_append_nios2 = " ${TOOLCHAIN_OPTIONS}" | 232 | KERNEL_CC_append_aarch64 = " ${TOOLCHAIN_OPTIONS}" |
207 | KERNEL_LD_append_nios2 = " ${TOOLCHAIN_OPTIONS}" | 233 | KERNEL_LD_append_aarch64 = " ${TOOLCHAIN_OPTIONS}" |
208 | DEPENDS_append_arc = " libgcc" KERNEL_CC_append_arc = " | 234 | |
209 | ${TOOLCHAIN_OPTIONS}" KERNEL_LD_append_arc = " | 235 | DEPENDS_append_nios2 = " libgcc" |
210 | ${TOOLCHAIN_OPTIONS}" KERNEL_FEATURES_append_qemuall=" | 236 | KERNEL_CC_append_nios2 = " ${TOOLCHAIN_OPTIONS}" |
211 | features/debug/printk.scc" | 237 | KERNEL_LD_append_nios2 = " ${TOOLCHAIN_OPTIONS}" |
238 | |||
239 | DEPENDS_append_arc = " libgcc" | ||
240 | KERNEL_CC_append_arc = " ${TOOLCHAIN_OPTIONS}" | ||
241 | KERNEL_LD_append_arc = " ${TOOLCHAIN_OPTIONS}" | ||
242 | |||
243 | KERNEL_FEATURES_append_qemuall=" features/debug/printk.scc" | ||
212 | 244 | ||
213 | .. note:: | 245 | .. note:: |
214 | 246 | ||
@@ -349,8 +381,13 @@ the COMMON and DISTRO related tests. Furthermore, if your layer is a BSP | |||
349 | layer, the layer must pass the COMMON and BSP set of tests. | 381 | layer, the layer must pass the COMMON and BSP set of tests. |
350 | 382 | ||
351 | To execute the script, enter the following commands from your build | 383 | To execute the script, enter the following commands from your build |
352 | directory: $ source oe-init-build-env $ yocto-check-layer | 384 | directory: |
353 | your_layer_directory Be sure to provide the actual directory for your | 385 | :: |
386 | |||
387 | $ source oe-init-build-env | ||
388 | $ yocto-check-layer your_layer_directory | ||
389 | |||
390 | Be sure to provide the actual directory for your | ||
354 | layer as part of the command. | 391 | layer as part of the command. |
355 | 392 | ||
356 | Entering the command causes the script to determine the type of layer | 393 | Entering the command causes the script to determine the type of layer |
@@ -401,11 +438,20 @@ enable it. To enable your layer, simply add your layer's path to the | |||
401 | ``BBLAYERS`` variable in your ``conf/bblayers.conf`` file, which is | 438 | ``BBLAYERS`` variable in your ``conf/bblayers.conf`` file, which is |
402 | found in the :term:`Build Directory`. | 439 | found in the :term:`Build Directory`. |
403 | The following example shows how to enable a layer named | 440 | The following example shows how to enable a layer named |
404 | ``meta-mylayer``: # POKY_BBLAYERS_CONF_VERSION is increased each time | 441 | ``meta-mylayer``: |
405 | build/conf/bblayers.conf # changes incompatibly | 442 | :: |
406 | POKY_BBLAYERS_CONF_VERSION = "2" BBPATH = "${TOPDIR}" BBFILES ?= "" | 443 | |
407 | BBLAYERS ?= " \\ /home/user/poky/meta \\ /home/user/poky/meta-poky \\ | 444 | # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf |
408 | /home/user/poky/meta-yocto-bsp \\ /home/user/poky/meta-mylayer \\ " | 445 | # changes incompatibly |
446 | POKY_BBLAYERS_CONF_VERSION = "2" | ||
447 | BBPATH = "${TOPDIR}" | ||
448 | BBFILES ?= "" | ||
449 | BBLAYERS ?= " \ | ||
450 | /home/user/poky/meta \ | ||
451 | /home/user/poky/meta-poky \ | ||
452 | /home/user/poky/meta-yocto-bsp \ | ||
453 | /home/user/poky/meta-mylayer \ | ||
454 | " | ||
409 | 455 | ||
410 | BitBake parses each ``conf/layer.conf`` file from the top down as | 456 | BitBake parses each ``conf/layer.conf`` file from the top down as |
411 | specified in the ``BBLAYERS`` variable within the ``conf/bblayers.conf`` | 457 | specified in the ``BBLAYERS`` variable within the ``conf/bblayers.conf`` |
@@ -450,24 +496,40 @@ As an example, consider the main formfactor recipe and a corresponding | |||
450 | formfactor append file both from the :term:`Source Directory`. | 496 | formfactor append file both from the :term:`Source Directory`. |
451 | Here is the main | 497 | Here is the main |
452 | formfactor recipe, which is named ``formfactor_0.0.bb`` and located in | 498 | formfactor recipe, which is named ``formfactor_0.0.bb`` and located in |
453 | the "meta" layer at ``meta/recipes-bsp/formfactor``: SUMMARY = "Device | 499 | the "meta" layer at ``meta/recipes-bsp/formfactor``: |
454 | formfactor information" SECTION = "base" LICENSE = "MIT" | 500 | :: |
455 | LIC_FILES_CHKSUM = | 501 | |
456 | "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" | 502 | SUMMARY = "Device formfactor information" |
457 | PR = "r45" SRC_URI = "file://config file://machconfig" S = "${WORKDIR}" | 503 | SECTION = "base" |
458 | PACKAGE_ARCH = "${MACHINE_ARCH}" INHIBIT_DEFAULT_DEPS = "1" do_install() | 504 | LICENSE = "MIT" |
459 | { # Install file only if it has contents install -d | 505 | LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" |
460 | ${D}${sysconfdir}/formfactor/ install -m 0644 ${S}/config | 506 | PR = "r45" |
461 | ${D}${sysconfdir}/formfactor/ if [ -s "${S}/machconfig" ]; then install | 507 | |
462 | -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ fi } In the main | 508 | SRC_URI = "file://config file://machconfig" |
463 | recipe, note the :term:`SRC_URI` | 509 | S = "${WORKDIR}" |
510 | |||
511 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
512 | INHIBIT_DEFAULT_DEPS = "1" | ||
513 | |||
514 | do_install() { | ||
515 | # Install file only if it has contents | ||
516 | install -d ${D}${sysconfdir}/formfactor/ | ||
517 | install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ | ||
518 | if [ -s "${S}/machconfig" ]; then | ||
519 | install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ | ||
520 | fi | ||
521 | } | ||
522 | |||
523 | In the main recipe, note the :term:`SRC_URI` | ||
464 | variable, which tells the OpenEmbedded build system where to find files | 524 | variable, which tells the OpenEmbedded build system where to find files |
465 | during the build. | 525 | during the build. |
466 | 526 | ||
467 | Following is the append file, which is named ``formfactor_0.0.bbappend`` | 527 | Following is the append file, which is named ``formfactor_0.0.bbappend`` |
468 | and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The | 528 | and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The |
469 | file is in the layer at ``recipes-bsp/formfactor``: | 529 | file is in the layer at ``recipes-bsp/formfactor``: |
470 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 530 | :: |
531 | |||
532 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
471 | 533 | ||
472 | By default, the build system uses the | 534 | By default, the build system uses the |
473 | :term:`FILESPATH` variable to | 535 | :term:`FILESPATH` variable to |
@@ -513,7 +575,10 @@ build system to calculate it based on the layer's dependencies. | |||
513 | 575 | ||
514 | To specify the layer's priority manually, use the | 576 | To specify the layer's priority manually, use the |
515 | :term:`BBFILE_PRIORITY` | 577 | :term:`BBFILE_PRIORITY` |
516 | variable and append the layer's root name: BBFILE_PRIORITY_mylayer = "1" | 578 | variable and append the layer's root name: |
579 | :: | ||
580 | |||
581 | BBFILE_PRIORITY_mylayer = "1" | ||
517 | 582 | ||
518 | .. note:: | 583 | .. note:: |
519 | 584 | ||
@@ -535,50 +600,68 @@ with their paths and priorities and on ``.bbappend`` files and their | |||
535 | applicable recipes can help to reveal potential problems. | 600 | applicable recipes can help to reveal potential problems. |
536 | 601 | ||
537 | For help on the BitBake layer management tool, use the following | 602 | For help on the BitBake layer management tool, use the following |
538 | command: $ bitbake-layers --help NOTE: Starting bitbake server... usage: | 603 | command: |
539 | bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ... | 604 | :: |
540 | BitBake layers utility optional arguments: -d, --debug Enable debug | 605 | |
541 | output -q, --quiet Print only errors -F, --force Force add without | 606 | $ bitbake-layers --help NOTE: Starting bitbake server... usage: |
542 | recipe parse verification --color COLOR Colorize output (where COLOR is | 607 | NOTE: Starting bitbake server... |
543 | auto, always, never) -h, --help show this help message and exit | 608 | usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ... |
544 | subcommands: <subcommand> show-layers show current configured layers. | 609 | |
545 | show-overlayed list overlayed recipes (where the same recipe exists in | 610 | BitBake layers utility |
546 | another layer) show-recipes list available recipes, showing the layer | 611 | |
547 | they are provided by show-appends list bbappend files and recipe files | 612 | optional arguments: |
548 | they apply to show-cross-depends Show dependencies between recipes that | 613 | -d, --debug Enable debug output |
549 | cross layer boundaries. add-layer Add one or more layers to | 614 | -q, --quiet Print only errors |
550 | bblayers.conf. remove-layer Remove one or more layers from | 615 | -F, --force Force add without recipe parse verification |
551 | bblayers.conf. flatten flatten layer configuration into a separate | 616 | --color COLOR Colorize output (where COLOR is auto, always, never) |
552 | output directory. layerindex-fetch Fetches a layer from a layer index | 617 | -h, --help show this help message and exit |
553 | along with its dependent layers, and adds them to conf/bblayers.conf. | 618 | |
554 | layerindex-show-depends Find layer dependencies from layer index. | 619 | subcommands: |
555 | create-layer Create a basic layer Use bitbake-layers <subcommand> --help | 620 | <subcommand> |
556 | to get help on a specific command | 621 | layerindex-fetch Fetches a layer from a layer index along with its |
622 | dependent layers, and adds them to conf/bblayers.conf. | ||
623 | layerindex-show-depends | ||
624 | Find layer dependencies from layer index. | ||
625 | add-layer Add one or more layers to bblayers.conf. | ||
626 | remove-layer Remove one or more layers from bblayers.conf. | ||
627 | flatten flatten layer configuration into a separate output | ||
628 | directory. | ||
629 | show-layers show current configured layers. | ||
630 | show-overlayed list overlayed recipes (where the same recipe exists | ||
631 | in another layer) | ||
632 | show-recipes list available recipes, showing the layer they are | ||
633 | provided by | ||
634 | show-appends list bbappend files and recipe files they apply to | ||
635 | show-cross-depends Show dependencies between recipes that cross layer | ||
636 | boundaries. | ||
637 | create-layer Create a basic layer | ||
638 | |||
639 | Use bitbake-layers <subcommand> --help to get help on a specific command | ||
557 | 640 | ||
558 | The following list describes the available commands: | 641 | The following list describes the available commands: |
559 | 642 | ||
560 | - *``help:``* Displays general help or help on a specified command. | 643 | - ``help:`` Displays general help or help on a specified command. |
561 | 644 | ||
562 | - *``show-layers:``* Shows the current configured layers. | 645 | - ``show-layers:`` Shows the current configured layers. |
563 | 646 | ||
564 | - *``show-overlayed:``* Lists overlayed recipes. A recipe is overlayed | 647 | - ``show-overlayed:`` Lists overlayed recipes. A recipe is overlayed |
565 | when a recipe with the same name exists in another layer that has a | 648 | when a recipe with the same name exists in another layer that has a |
566 | higher layer priority. | 649 | higher layer priority. |
567 | 650 | ||
568 | - *``show-recipes:``* Lists available recipes and the layers that | 651 | - ``show-recipes:`` Lists available recipes and the layers that |
569 | provide them. | 652 | provide them. |
570 | 653 | ||
571 | - *``show-appends:``* Lists ``.bbappend`` files and the recipe files to | 654 | - ``show-appends:`` Lists ``.bbappend`` files and the recipe files to |
572 | which they apply. | 655 | which they apply. |
573 | 656 | ||
574 | - *``show-cross-depends:``* Lists dependency relationships between | 657 | - ``show-cross-depends:`` Lists dependency relationships between |
575 | recipes that cross layer boundaries. | 658 | recipes that cross layer boundaries. |
576 | 659 | ||
577 | - *``add-layer:``* Adds a layer to ``bblayers.conf``. | 660 | - ``add-layer:`` Adds a layer to ``bblayers.conf``. |
578 | 661 | ||
579 | - *``remove-layer:``* Removes a layer from ``bblayers.conf`` | 662 | - ``remove-layer:`` Removes a layer from ``bblayers.conf`` |
580 | 663 | ||
581 | - *``flatten:``* Flattens the layer configuration into a separate | 664 | - ``flatten:`` Flattens the layer configuration into a separate |
582 | output directory. Flattening your layer configuration builds a | 665 | output directory. Flattening your layer configuration builds a |
583 | "flattened" directory that contains the contents of all layers, with | 666 | "flattened" directory that contains the contents of all layers, with |
584 | any overlayed recipes removed and any ``.bbappend`` files appended to | 667 | any overlayed recipes removed and any ``.bbappend`` files appended to |
@@ -598,22 +681,38 @@ The following list describes the available commands: | |||
598 | variable values, you need to tidy these up yourself. Consider the | 681 | variable values, you need to tidy these up yourself. Consider the |
599 | following example. Here, the ``bitbake-layers`` command adds the | 682 | following example. Here, the ``bitbake-layers`` command adds the |
600 | line ``#### bbappended ...`` so that you know where the following | 683 | line ``#### bbappended ...`` so that you know where the following |
601 | lines originate: ... DESCRIPTION = "A useful utility" ... | 684 | lines originate: |
602 | EXTRA_OECONF = "--enable-something" ... #### bbappended from | 685 | :: |
603 | meta-anotherlayer #### DESCRIPTION = "Customized utility" | 686 | |
604 | EXTRA_OECONF += "--enable-somethingelse" Ideally, you would tidy | 687 | ... |
605 | up these utilities as follows: ... DESCRIPTION = "Customized | 688 | DESCRIPTION = "A useful utility" |
606 | utility" ... EXTRA_OECONF = "--enable-something | 689 | ... |
607 | --enable-somethingelse" ... | 690 | EXTRA_OECONF = "--enable-something" |
608 | 691 | ... | |
609 | - *``layerindex-fetch``:* Fetches a layer from a layer index, along | 692 | |
693 | #### bbappended from meta-anotherlayer #### | ||
694 | |||
695 | DESCRIPTION = "Customized utility" | ||
696 | EXTRA_OECONF += "--enable-somethingelse" | ||
697 | |||
698 | |||
699 | Ideally, you would tidy up these utilities as follows: | ||
700 | :: | ||
701 | |||
702 | ... | ||
703 | DESCRIPTION = "Customized utility" | ||
704 | ... | ||
705 | EXTRA_OECONF = "--enable-something --enable-somethingelse" | ||
706 | ... | ||
707 | |||
708 | - ``layerindex-fetch``: Fetches a layer from a layer index, along | ||
610 | with its dependent layers, and adds the layers to the | 709 | with its dependent layers, and adds the layers to the |
611 | ``conf/bblayers.conf`` file. | 710 | ``conf/bblayers.conf`` file. |
612 | 711 | ||
613 | - *``layerindex-show-depends``:* Finds layer dependencies from the | 712 | - ``layerindex-show-depends``: Finds layer dependencies from the |
614 | layer index. | 713 | layer index. |
615 | 714 | ||
616 | - *``create-layer``:* Creates a basic layer. | 715 | - ``create-layer``: Creates a basic layer. |
617 | 716 | ||
618 | Creating a General Layer Using the ``bitbake-layers`` Script | 717 | Creating a General Layer Using the ``bitbake-layers`` Script |
619 | ------------------------------------------------------------ | 718 | ------------------------------------------------------------ |
@@ -623,14 +722,13 @@ simplifies creating a new general layer. | |||
623 | 722 | ||
624 | .. note:: | 723 | .. note:: |
625 | 724 | ||
626 | - For information on BSP layers, see the "`BSP | 725 | - For information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" |
627 | Layers <&YOCTO_DOCS_BSP_URL;#bsp-layers>`__" section in the Yocto | 726 | section in the Yocto |
628 | Project Board Specific (BSP) Developer's Guide. | 727 | Project Board Specific (BSP) Developer's Guide. |
629 | 728 | ||
630 | - In order to use a layer with the OpenEmbedded build system, you | 729 | - In order to use a layer with the OpenEmbedded build system, you |
631 | need to add the layer to your ``bblayers.conf`` configuration | 730 | need to add the layer to your ``bblayers.conf`` configuration |
632 | file. See the "`Adding a Layer Using the ``bitbake-layers`` | 731 | file. See the ":ref:`dev-manual/dev-manual-common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`" |
633 | Script <#adding-a-layer-using-the-bitbake-layers-script>`__" | ||
634 | section for more information. | 732 | section for more information. |
635 | 733 | ||
636 | The default mode of the script's operation with this subcommand is to | 734 | The default mode of the script's operation with this subcommand is to |
@@ -655,10 +753,13 @@ In its simplest form, you can use the following command form to create a | |||
655 | layer. The command creates a layer whose name corresponds to | 753 | layer. The command creates a layer whose name corresponds to |
656 | your_layer_name in the current directory: $ bitbake-layers create-layer | 754 | your_layer_name in the current directory: $ bitbake-layers create-layer |
657 | your_layer_name As an example, the following command creates a layer | 755 | your_layer_name As an example, the following command creates a layer |
658 | named ``meta-scottrif`` in your home directory: $ cd /usr/home $ | 756 | named ``meta-scottrif`` in your home directory: |
659 | bitbake-layers create-layer meta-scottrif NOTE: Starting bitbake | 757 | :: |
660 | server... Add your new layer with 'bitbake-layers add-layer | 758 | |
661 | meta-scottrif' | 759 | $ cd /usr/home |
760 | $ bitbake-layers create-layer meta-scottrif | ||
761 | NOTE: Starting bitbake server... | ||
762 | Add your new layer with 'bitbake-layers add-layer meta-scottrif' | ||
662 | 763 | ||
663 | If you want to set the priority of the layer to other than the default | 764 | If you want to set the priority of the layer to other than the default |
664 | value of "6", you can either use the ``DASHDASHpriority`` option or you | 765 | value of "6", you can either use the ``DASHDASHpriority`` option or you |
@@ -670,14 +771,26 @@ default, you can use the ``DASHDASHexample-recipe-name`` option. | |||
670 | 771 | ||
671 | The easiest way to see how the ``bitbake-layers create-layer`` command | 772 | The easiest way to see how the ``bitbake-layers create-layer`` command |
672 | works is to experiment with the script. You can also read the usage | 773 | works is to experiment with the script. You can also read the usage |
673 | information by entering the following: $ bitbake-layers create-layer | 774 | information by entering the following: |
674 | --help NOTE: Starting bitbake server... usage: bitbake-layers | 775 | :: |
675 | create-layer [-h] [--priority PRIORITY] [--example-recipe-name | 776 | |
676 | EXAMPLERECIPE] layerdir Create a basic layer positional arguments: | 777 | $ bitbake-layers create-layer --help |
677 | layerdir Layer directory to create optional arguments: -h, --help show | 778 | NOTE: Starting bitbake server... |
678 | this help message and exit --priority PRIORITY, -p PRIORITY Layer | 779 | usage: bitbake-layers create-layer [-h] [--priority PRIORITY] |
679 | directory to create --example-recipe-name EXAMPLERECIPE, -e | 780 | [--example-recipe-name EXAMPLERECIPE] |
680 | EXAMPLERECIPE Filename of the example recipe | 781 | layerdir |
782 | |||
783 | Create a basic layer | ||
784 | |||
785 | positional arguments: | ||
786 | layerdir Layer directory to create | ||
787 | |||
788 | optional arguments: | ||
789 | -h, --help show this help message and exit | ||
790 | --priority PRIORITY, -p PRIORITY | ||
791 | Layer directory to create | ||
792 | --example-recipe-name EXAMPLERECIPE, -e EXAMPLERECIPE | ||
793 | Filename of the example recipe | ||
681 | 794 | ||
682 | Adding a Layer Using the ``bitbake-layers`` Script | 795 | Adding a Layer Using the ``bitbake-layers`` Script |
683 | -------------------------------------------------- | 796 | -------------------------------------------------- |
@@ -687,22 +800,33 @@ Once you create your general layer, you must add it to your | |||
687 | makes the OpenEmbedded build system aware of your layer so that it can | 800 | makes the OpenEmbedded build system aware of your layer so that it can |
688 | search it for metadata. | 801 | search it for metadata. |
689 | 802 | ||
690 | Add your layer by using the ``bitbake-layers add-layer`` command: $ | 803 | Add your layer by using the ``bitbake-layers add-layer`` command: |
691 | bitbake-layers add-layer your_layer_name Here is an example that adds a | 804 | :: |
805 | |||
806 | $ bitbake-layers add-layer your_layer_name | ||
807 | |||
808 | Here is an example that adds a | ||
692 | layer named ``meta-scottrif`` to the configuration file. Following the | 809 | layer named ``meta-scottrif`` to the configuration file. Following the |
693 | command that adds the layer is another ``bitbake-layers`` command that | 810 | command that adds the layer is another ``bitbake-layers`` command that |
694 | shows the layers that are in your ``bblayers.conf`` file: $ | 811 | shows the layers that are in your ``bblayers.conf`` file: |
695 | bitbake-layers add-layer meta-scottrif NOTE: Starting bitbake server... | 812 | :: |
696 | Parsing recipes: 100% | 813 | |
697 | \|##########################################################\| Time: | 814 | $ bitbake-layers add-layer meta-scottrif |
698 | 0:00:49 Parsing of 1441 .bb files complete (0 cached, 1441 parsed). 2055 | 815 | NOTE: Starting bitbake server... |
699 | targets, 56 skipped, 0 masked, 0 errors. $ bitbake-layers show-layers | 816 | Parsing recipes: 100% |##########################################################| Time: 0:00:49 |
700 | NOTE: Starting bitbake server... layer path priority | 817 | Parsing of 1441 .bb files complete (0 cached, 1441 parsed). 2055 targets, 56 skipped, 0 masked, 0 errors. |
701 | ========================================================================== | 818 | $ bitbake-layers show-layers |
702 | meta /home/scottrif/poky/meta 5 meta-poky /home/scottrif/poky/meta-poky | 819 | NOTE: Starting bitbake server... |
703 | 5 meta-yocto-bsp /home/scottrif/poky/meta-yocto-bsp 5 workspace | 820 | layer path priority |
704 | /home/scottrif/poky/build/workspace 99 meta-scottrif | 821 | ========================================================================== |
705 | /home/scottrif/poky/build/meta-scottrif 6 Adding the layer to this file | 822 | meta /home/scottrif/poky/meta 5 |
823 | meta-poky /home/scottrif/poky/meta-poky 5 | ||
824 | meta-yocto-bsp /home/scottrif/poky/meta-yocto-bsp 5 | ||
825 | workspace /home/scottrif/poky/build/workspace 99 | ||
826 | meta-scottrif /home/scottrif/poky/build/meta-scottrif 6 | ||
827 | |||
828 | |||
829 | Adding the layer to this file | ||
706 | enables the build system to locate the layer during the build. | 830 | enables the build system to locate the layer during the build. |
707 | 831 | ||
708 | .. note:: | 832 | .. note:: |
@@ -733,7 +857,11 @@ all images, which might not be what you require. | |||
733 | 857 | ||
734 | To add a package to your image using the local configuration file, use | 858 | To add a package to your image using the local configuration file, use |
735 | the ``IMAGE_INSTALL`` variable with the ``_append`` operator: | 859 | the ``IMAGE_INSTALL`` variable with the ``_append`` operator: |
736 | IMAGE_INSTALL_append = " strace" Use of the syntax is important - | 860 | :: |
861 | |||
862 | IMAGE_INSTALL_append = " strace" | ||
863 | |||
864 | Use of the syntax is important - | ||
737 | specifically, the space between the quote and the package name, which is | 865 | specifically, the space between the quote and the package name, which is |
738 | ``strace`` in this example. This space is required since the ``_append`` | 866 | ``strace`` in this example. This space is required since the ``_append`` |
739 | operator does not add the space. | 867 | operator does not add the space. |
@@ -821,8 +949,11 @@ Customizing Images Using Custom .bb Files | |||
821 | 949 | ||
822 | You can also customize an image by creating a custom recipe that defines | 950 | You can also customize an image by creating a custom recipe that defines |
823 | additional software as part of the image. The following example shows | 951 | additional software as part of the image. The following example shows |
824 | the form for the two lines you need: IMAGE_INSTALL = | 952 | the form for the two lines you need: |
825 | "packagegroup-core-x11-base package1 package2" inherit core-image | 953 | :: |
954 | |||
955 | IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2" | ||
956 | inherit core-image | ||
826 | 957 | ||
827 | Defining the software using a custom recipe gives you total control over | 958 | Defining the software using a custom recipe gives you total control over |
828 | the contents of the image. It is important to use the correct names of | 959 | the contents of the image. It is important to use the correct names of |
@@ -834,8 +965,10 @@ The other method for creating a custom image is to base it on an | |||
834 | existing image. For example, if you want to create an image based on | 965 | existing image. For example, if you want to create an image based on |
835 | ``core-image-sato`` but add the additional package ``strace`` to the | 966 | ``core-image-sato`` but add the additional package ``strace`` to the |
836 | image, copy the ``meta/recipes-sato/images/core-image-sato.bb`` to a new | 967 | image, copy the ``meta/recipes-sato/images/core-image-sato.bb`` to a new |
837 | ``.bb`` and add the following line to the end of the copy: IMAGE_INSTALL | 968 | ``.bb`` and add the following line to the end of the copy: |
838 | += "strace" | 969 | :: |
970 | |||
971 | IMAGE_INSTALL += "strace" | ||
839 | 972 | ||
840 | .. _usingpoky-extend-customimage-customtasks: | 973 | .. _usingpoky-extend-customimage-customtasks: |
841 | 974 | ||
@@ -870,11 +1003,30 @@ in the ``packagegroup-base.bb`` recipe. | |||
870 | Here is a short, fabricated example showing the same basic pieces for a | 1003 | Here is a short, fabricated example showing the same basic pieces for a |
871 | hypothetical packagegroup defined in ``packagegroup-custom.bb``, where | 1004 | hypothetical packagegroup defined in ``packagegroup-custom.bb``, where |
872 | the variable ``PN`` is the standard way to abbreviate the reference to | 1005 | the variable ``PN`` is the standard way to abbreviate the reference to |
873 | the full packagegroup name ``packagegroup-custom``: DESCRIPTION = "My | 1006 | the full packagegroup name ``packagegroup-custom``: |
874 | Custom Package Groups" inherit packagegroup PACKAGES = "\\ ${PN}-apps \\ | 1007 | :: |
875 | ${PN}-tools \\ " RDEPENDS_${PN}-apps = "\\ dropbear \\ portmap \\ | 1008 | |
876 | psplash" RDEPENDS_${PN}-tools = "\\ oprofile \\ oprofileui-server \\ | 1009 | DESCRIPTION = "My Custom Package Groups" |
877 | lttng-tools" RRECOMMENDS_${PN}-tools = "\\ kernel-module-oprofile" | 1010 | |
1011 | inherit packagegroup | ||
1012 | |||
1013 | PACKAGES = "\ | ||
1014 | ${PN}-apps \ | ||
1015 | ${PN}-tools \ | ||
1016 | " | ||
1017 | |||
1018 | RDEPENDS_${PN}-apps = "\ | ||
1019 | dropbear \ | ||
1020 | portmap \ | ||
1021 | psplash" | ||
1022 | |||
1023 | RDEPENDS_${PN}-tools = "\ | ||
1024 | oprofile \ | ||
1025 | oprofileui-server \ | ||
1026 | lttng-tools" | ||
1027 | |||
1028 | RRECOMMENDS_${PN}-tools = "\ | ||
1029 | kernel-module-oprofile" | ||
878 | 1030 | ||
879 | In the previous example, two package group packages are created with | 1031 | In the previous example, two package group packages are created with |
880 | their dependencies and their recommended package dependencies listed: | 1032 | their dependencies and their recommended package dependencies listed: |
@@ -897,8 +1049,14 @@ configured hostname written to ``/etc/hostname`` is "qemux86". | |||
897 | You can customize this name by altering the value of the "hostname" | 1049 | You can customize this name by altering the value of the "hostname" |
898 | variable in the ``base-files`` recipe using either an append file or a | 1050 | variable in the ``base-files`` recipe using either an append file or a |
899 | configuration file. Use the following in an append file: | 1051 | configuration file. Use the following in an append file: |
900 | hostname="myhostname" Use the following in a configuration file: | 1052 | :: |
901 | hostname_pn-base-files = "myhostname" | 1053 | |
1054 | hostname = "myhostname" | ||
1055 | |||
1056 | Use the following in a configuration file: | ||
1057 | :: | ||
1058 | |||
1059 | hostname_pn-base-files = "myhostname" | ||
902 | 1060 | ||
903 | Changing the default value of the variable "hostname" can be useful in | 1061 | Changing the default value of the variable "hostname" can be useful in |
904 | certain situations. For example, suppose you need to do extensive | 1062 | certain situations. For example, suppose you need to do extensive |
@@ -911,7 +1069,11 @@ you can easily reset the default hostname. | |||
911 | 1069 | ||
912 | Another point of interest is that if you unset the variable, the image | 1070 | Another point of interest is that if you unset the variable, the image |
913 | will have no default hostname in the filesystem. Here is an example that | 1071 | will have no default hostname in the filesystem. Here is an example that |
914 | unsets the variable in a configuration file: hostname_pn-base-files = "" | 1072 | unsets the variable in a configuration file: |
1073 | :: | ||
1074 | |||
1075 | hostname_pn-base-files = "" | ||
1076 | |||
915 | Having no default hostname in the filesystem is suitable for | 1077 | Having no default hostname in the filesystem is suitable for |
916 | environments that use dynamic hostnames such as virtual machines. | 1078 | environments that use dynamic hostnames such as virtual machines. |
917 | 1079 | ||
@@ -951,10 +1113,10 @@ Locate or Automatically Create a Base Recipe | |||
951 | You can always write a recipe from scratch. However, three choices exist | 1113 | You can always write a recipe from scratch. However, three choices exist |
952 | that can help you quickly get a start on a new recipe: | 1114 | that can help you quickly get a start on a new recipe: |
953 | 1115 | ||
954 | - *``devtool add``:* A command that assists in creating a recipe and an | 1116 | - ``devtool add``: A command that assists in creating a recipe and an |
955 | environment conducive to development. | 1117 | environment conducive to development. |
956 | 1118 | ||
957 | - *``recipetool create``:* A command provided by the Yocto Project that | 1119 | - ``recipetool create``: A command provided by the Yocto Project that |
958 | automates creation of a base recipe based on the source files. | 1120 | automates creation of a base recipe based on the source files. |
959 | 1121 | ||
960 | - *Existing Recipes:* Location and modification of an existing recipe | 1122 | - *Existing Recipes:* Location and modification of an existing recipe |
@@ -979,8 +1141,7 @@ necessary when adding a recipe to build a new piece of software to be | |||
979 | included in a build. | 1141 | included in a build. |
980 | 1142 | ||
981 | You can find a complete description of the ``devtool add`` command in | 1143 | You can find a complete description of the ``devtool add`` command in |
982 | the "`A Closer Look at ``devtool`` | 1144 | the ":ref:`sdk-a-closer-look-at-devtool-add`" section |
983 | add <&YOCTO_DOCS_SDK_URL;#sdk-a-closer-look-at-devtool-add>`__" section | ||
984 | in the Yocto Project Application Development and the Extensible Software | 1145 | in the Yocto Project Application Development and the Extensible Software |
985 | Development Kit (eSDK) manual. | 1146 | Development Kit (eSDK) manual. |
986 | 1147 | ||
@@ -1000,33 +1161,55 @@ license requirements, and checksums configured. | |||
1000 | To run the tool, you just need to be in your | 1161 | To run the tool, you just need to be in your |
1001 | :term:`Build Directory` and have sourced the | 1162 | :term:`Build Directory` and have sourced the |
1002 | build environment setup script (i.e. | 1163 | build environment setup script (i.e. |
1003 | ```oe-init-build-env`` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__). | 1164 | `:ref:`structure-core-script`). |
1004 | To get help on the tool, use the following command: $ recipetool -h | 1165 | To get help on the tool, use the following command: |
1005 | NOTE: Starting bitbake server... usage: recipetool [-d] [-q] [--color | 1166 | :: |
1006 | COLOR] [-h] <subcommand> ... OpenEmbedded recipe tool options: -d, | 1167 | |
1007 | --debug Enable debug output -q, --quiet Print only errors --color COLOR | 1168 | $ recipetool -h |
1008 | Colorize output (where COLOR is auto, always, never) -h, --help show | 1169 | NOTE: Starting bitbake server... |
1009 | this help message and exit subcommands: create Create a new recipe | 1170 | usage: recipetool [-d] [-q] [--color COLOR] [-h] <subcommand> ... |
1010 | newappend Create a bbappend for the specified target in the specified | 1171 | |
1011 | layer setvar Set a variable within a recipe appendfile Create/update a | 1172 | OpenEmbedded recipe tool |
1012 | bbappend to replace a target file appendsrcfiles Create/update a | 1173 | |
1013 | bbappend to add or replace source files appendsrcfile Create/update a | 1174 | options: |
1014 | bbappend to add or replace a source file Use recipetool <subcommand> | 1175 | -d, --debug Enable debug output |
1015 | --help to get help on a specific command | 1176 | -q, --quiet Print only errors |
1177 | --color COLOR Colorize output (where COLOR is auto, always, never) | ||
1178 | -h, --help show this help message and exit | ||
1179 | |||
1180 | subcommands: | ||
1181 | create Create a new recipe | ||
1182 | newappend Create a bbappend for the specified target in the specified | ||
1183 | layer | ||
1184 | setvar Set a variable within a recipe | ||
1185 | appendfile Create/update a bbappend to replace a target file | ||
1186 | appendsrcfiles Create/update a bbappend to add or replace source files | ||
1187 | appendsrcfile Create/update a bbappend to add or replace a source file | ||
1188 | Use recipetool <subcommand> --help to get help on a specific command | ||
1016 | 1189 | ||
1017 | Running ``recipetool create -o`` OUTFILE creates the base recipe and | 1190 | Running ``recipetool create -o`` OUTFILE creates the base recipe and |
1018 | locates it properly in the layer that contains your source files. | 1191 | locates it properly in the layer that contains your source files. |
1019 | Following are some syntax examples: | 1192 | Following are some syntax examples: |
1020 | 1193 | ||
1021 | Use this syntax to generate a recipe based on source. Once generated, | 1194 | Use this syntax to generate a recipe based on source. Once generated, |
1022 | the recipe resides in the existing source code layer: recipetool create | 1195 | the recipe resides in the existing source code layer: |
1023 | -o OUTFILE source Use this syntax to generate a recipe using code that | 1196 | :: |
1197 | |||
1198 | recipetool create -o OUTFILE source | ||
1199 | |||
1200 | Use this syntax to generate a recipe using code that | ||
1024 | you extract from source. The extracted code is placed in its own layer | 1201 | you extract from source. The extracted code is placed in its own layer |
1025 | defined by EXTERNALSRC. recipetool create -o OUTFILE -x EXTERNALSRC | 1202 | defined by EXTERNALSRC. |
1026 | source Use this syntax to generate a recipe based on source. The options | 1203 | :: |
1204 | |||
1205 | recipetool create -o OUTFILE -x EXTERNALSRC source | ||
1206 | |||
1207 | Use this syntax to generate a recipe based on source. The options | ||
1027 | direct ``recipetool`` to generate debugging information. Once generated, | 1208 | direct ``recipetool`` to generate debugging information. Once generated, |
1028 | the recipe resides in the existing source code layer: recipetool create | 1209 | the recipe resides in the existing source code layer: |
1029 | -d -o OUTFILE source | 1210 | :: |
1211 | |||
1212 | recipetool create -d -o OUTFILE source | ||
1030 | 1213 | ||
1031 | .. _new-recipe-locating-and-using-a-similar-recipe: | 1214 | .. _new-recipe-locating-and-using-a-similar-recipe: |
1032 | 1215 | ||
@@ -1058,8 +1241,16 @@ get started. Here are some points on both methods: | |||
1058 | you do not want to use ``recipetool`` and you cannot find an existing | 1241 | you do not want to use ``recipetool`` and you cannot find an existing |
1059 | recipe that is close to meeting your needs, you can use the following | 1242 | recipe that is close to meeting your needs, you can use the following |
1060 | structure to provide the fundamental areas of a new recipe. | 1243 | structure to provide the fundamental areas of a new recipe. |
1061 | DESCRIPTION = "" HOMEPAGE = "" LICENSE = "" SECTION = "" DEPENDS = "" | 1244 | :: |
1062 | LIC_FILES_CHKSUM = "" SRC_URI = "" | 1245 | |
1246 | DESCRIPTION = "" | ||
1247 | HOMEPAGE = "" | ||
1248 | LICENSE = "" | ||
1249 | SECTION = "" | ||
1250 | DEPENDS = "" | ||
1251 | LIC_FILES_CHKSUM = "" | ||
1252 | |||
1253 | SRC_URI = "" | ||
1063 | 1254 | ||
1064 | .. _new-recipe-storing-and-naming-the-recipe: | 1255 | .. _new-recipe-storing-and-naming-the-recipe: |
1065 | 1256 | ||
@@ -1075,8 +1266,12 @@ the recipe. | |||
1075 | recipe through the layer's ``conf/layer.conf`` file and the | 1266 | recipe through the layer's ``conf/layer.conf`` file and the |
1076 | :term:`BBFILES` variable. This | 1267 | :term:`BBFILES` variable. This |
1077 | variable sets up a path from which the build system can locate | 1268 | variable sets up a path from which the build system can locate |
1078 | recipes. Here is the typical use: BBFILES += | 1269 | recipes. Here is the typical use: |
1079 | "${LAYERDIR}/recipes-*/*/*.bb \\ ${LAYERDIR}/recipes-*/*/*.bbappend" | 1270 | :: |
1271 | |||
1272 | BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ | ||
1273 | ${LAYERDIR}/recipes-*/*/*.bbappend" | ||
1274 | |||
1080 | Consequently, you need to be sure you locate your new recipe inside | 1275 | Consequently, you need to be sure you locate your new recipe inside |
1081 | your layer such that it can be found. | 1276 | your layer such that it can be found. |
1082 | 1277 | ||
@@ -1089,7 +1284,12 @@ the recipe. | |||
1089 | characters and do not include the reserved suffixes ``-native``, | 1284 | characters and do not include the reserved suffixes ``-native``, |
1090 | ``-cross``, ``-initial``, or ``-dev`` casually (i.e. do not use them | 1285 | ``-cross``, ``-initial``, or ``-dev`` casually (i.e. do not use them |
1091 | as part of your recipe name unless the string applies). Here are some | 1286 | as part of your recipe name unless the string applies). Here are some |
1092 | examples: cups_1.7.0.bb gawk_4.0.2.bb irssi_0.8.16-rc1.bb | 1287 | examples: |
1288 | :: | ||
1289 | |||
1290 | cups_1.7.0.bb | ||
1291 | gawk_4.0.2.bb | ||
1292 | irssi_0.8.16-rc1.bb | ||
1093 | 1293 | ||
1094 | .. _new-recipe-running-a-build-on-the-recipe: | 1294 | .. _new-recipe-running-a-build-on-the-recipe: |
1095 | 1295 | ||
@@ -1101,11 +1301,13 @@ using BitBake to process the recipe multiple times in order to | |||
1101 | progressively discover and add information to the recipe file. | 1301 | progressively discover and add information to the recipe file. |
1102 | 1302 | ||
1103 | Assuming you have sourced the build environment setup script (i.e. | 1303 | Assuming you have sourced the build environment setup script (i.e. |
1104 | ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__) and you are in | 1304 | :ref:`structure-core-script`) and you are in |
1105 | the :term:`Build Directory`, use | 1305 | the :term:`Build Directory`, use |
1106 | BitBake to process your recipe. All you need to provide is the | 1306 | BitBake to process your recipe. All you need to provide is the |
1107 | ``basename`` of the recipe as described in the previous section: $ | 1307 | ``basename`` of the recipe as described in the previous section: |
1108 | bitbake basename | 1308 | :: |
1309 | |||
1310 | $ bitbake basename | ||
1109 | 1311 | ||
1110 | During the build, the OpenEmbedded build system creates a temporary work | 1312 | During the build, the OpenEmbedded build system creates a temporary work |
1111 | directory for each recipe | 1313 | directory for each recipe |
@@ -1115,8 +1317,12 @@ compilation and packaging files, and so forth. | |||
1115 | 1317 | ||
1116 | The path to the per-recipe temporary work directory depends on the | 1318 | The path to the per-recipe temporary work directory depends on the |
1117 | context in which it is being built. The quickest way to find this path | 1319 | context in which it is being built. The quickest way to find this path |
1118 | is to have BitBake return it by running the following: $ bitbake -e | 1320 | is to have BitBake return it by running the following: |
1119 | basename \| grep ^WORKDIR= As an example, assume a Source Directory | 1321 | :: |
1322 | |||
1323 | $ bitbake -e basename \| grep ^WORKDIR= | ||
1324 | |||
1325 | As an example, assume a Source Directory | ||
1120 | top-level folder named ``poky``, a default Build Directory at | 1326 | top-level folder named ``poky``, a default Build Directory at |
1121 | ``poky/build``, and a ``qemux86-poky-linux`` machine target system. | 1327 | ``poky/build``, and a ``qemux86-poky-linux`` machine target system. |
1122 | Furthermore, suppose your recipe is named ``foo_1.3.0.bb``. In this | 1328 | Furthermore, suppose your recipe is named ``foo_1.3.0.bb``. In this |
@@ -1143,9 +1349,8 @@ to determine how well the build went. | |||
1143 | log.do_compile | 1349 | log.do_compile |
1144 | ). | 1350 | ). |
1145 | 1351 | ||
1146 | You can find more information about the build process in "`The Yocto | 1352 | You can find more information about the build process in |
1147 | Project Development | 1353 | ":doc:`../overview-manual/overview-manual-development-environment`" |
1148 | Environment <&YOCTO_DOCS_OM_URL;#overview-development-environment>`__" | ||
1149 | chapter of the Yocto Project Overview and Concepts Manual. | 1354 | chapter of the Yocto Project Overview and Concepts Manual. |
1150 | 1355 | ||
1151 | .. _new-recipe-fetching-code: | 1356 | .. _new-recipe-fetching-code: |
@@ -1158,7 +1363,7 @@ files. Fetching is controlled mainly through the | |||
1158 | :term:`SRC_URI` variable. Your recipe | 1363 | :term:`SRC_URI` variable. Your recipe |
1159 | must have a ``SRC_URI`` variable that points to where the source is | 1364 | must have a ``SRC_URI`` variable that points to where the source is |
1160 | located. For a graphical representation of source locations, see the | 1365 | located. For a graphical representation of source locations, see the |
1161 | "`Sources <&YOCTO_DOCS_OM_URL;#sources-dev-environment>`__" section in | 1366 | ":ref:`sources-dev-environment`" section in |
1162 | the Yocto Project Overview and Concepts Manual. | 1367 | the Yocto Project Overview and Concepts Manual. |
1163 | 1368 | ||
1164 | The :ref:`ref-tasks-fetch` task uses | 1369 | The :ref:`ref-tasks-fetch` task uses |
@@ -1183,8 +1388,10 @@ recipe to match the new version. | |||
1183 | Here is a simple example from the | 1388 | Here is a simple example from the |
1184 | ``meta/recipes-devtools/strace/strace_5.5.bb`` recipe where the source | 1389 | ``meta/recipes-devtools/strace/strace_5.5.bb`` recipe where the source |
1185 | comes from a single tarball. Notice the use of the | 1390 | comes from a single tarball. Notice the use of the |
1186 | :term:`PV` variable: SRC_URI = | 1391 | :term:`PV` variable: |
1187 | "https://strace.io/files/${PV}/strace-${PV}.tar.xz \\ | 1392 | :: |
1393 | |||
1394 | SRC_URI = "https://strace.io/files/${PV}/strace-${PV}.tar.xz \\ | ||
1188 | 1395 | ||
1189 | Files mentioned in ``SRC_URI`` whose names end in a typical archive | 1396 | Files mentioned in ``SRC_URI`` whose names end in a typical archive |
1190 | extension (e.g. ``.tar``, ``.tar.gz``, ``.tar.bz2``, ``.zip``, and so | 1397 | extension (e.g. ``.tar``, ``.tar.gz``, ``.tar.bz2``, ``.zip``, and so |
@@ -1198,10 +1405,16 @@ you must specify :term:`SRCREV` and | |||
1198 | you should specify :term:`PV` to include | 1405 | you should specify :term:`PV` to include |
1199 | the revision with :term:`SRCPV`. Here | 1406 | the revision with :term:`SRCPV`. Here |
1200 | is an example from the recipe | 1407 | is an example from the recipe |
1201 | ``meta/recipes-kernel/blktrace/blktrace_git.bb``: SRCREV = | 1408 | ``meta/recipes-kernel/blktrace/blktrace_git.bb``: |
1202 | "d6918c8832793b4205ed3bfede78c2f915c23385" PR = "r6" PV = | 1409 | :: |
1203 | "1.0.5+git${SRCPV}" SRC_URI = "git://git.kernel.dk/blktrace.git \\ | 1410 | |
1204 | file://ldflags.patch" | 1411 | SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385" |
1412 | |||
1413 | PR = "r6" | ||
1414 | PV = "1.0.5+git${SRCPV}" | ||
1415 | |||
1416 | SRC_URI = "git://git.kernel.dk/blktrace.git \ | ||
1417 | file://ldflags.patch" | ||
1205 | 1418 | ||
1206 | If your ``SRC_URI`` statement includes URLs pointing to individual files | 1419 | If your ``SRC_URI`` statement includes URLs pointing to individual files |
1207 | fetched from a remote server other than a version control system, | 1420 | fetched from a remote server other than a version control system, |
@@ -1215,15 +1428,16 @@ SCM URLs), you need to provide the ``md5`` and ``sha256`` checksums for | |||
1215 | each URL. For these cases, you provide a name for each URL as part of | 1428 | each URL. For these cases, you provide a name for each URL as part of |
1216 | the ``SRC_URI`` and then reference that name in the subsequent checksum | 1429 | the ``SRC_URI`` and then reference that name in the subsequent checksum |
1217 | statements. Here is an example combining lines from the files | 1430 | statements. Here is an example combining lines from the files |
1218 | ``git.inc`` and ``git_2.24.1.bb``: SRC_URI = | 1431 | ``git.inc`` and ``git_2.24.1.bb``: |
1219 | "${KERNELORG_MIRROR}/software/scm/git/git-${PV}.tar.gz;name=tarball \\ | 1432 | :: |
1220 | ${KERNELORG_MIRROR}/software/scm/git/git-manpages-${PV}.tar.gz;name=manpages" | 1433 | |
1221 | SRC_URI[tarball.md5sum] = "166bde96adbbc11c8843d4f8f4f9811b" | 1434 | SRC_URI = "${KERNELORG_MIRROR}/software/scm/git/git-${PV}.tar.gz;name=tarball \ |
1222 | SRC_URI[tarball.sha256sum] = | 1435 | ${KERNELORG_MIRROR}/software/scm/git/git-manpages-${PV}.tar.gz;name=manpages" |
1223 | "ad5334956301c86841eb1e5b1bb20884a6bad89a10a6762c958220c7cf64da02" | 1436 | |
1224 | SRC_URI[manpages.md5sum] = "31c2272a8979022497ba3d4202df145d" | 1437 | SRC_URI[tarball.md5sum] = "166bde96adbbc11c8843d4f8f4f9811b" |
1225 | SRC_URI[manpages.sha256sum] = | 1438 | SRC_URI[tarball.sha256sum] = "ad5334956301c86841eb1e5b1bb20884a6bad89a10a6762c958220c7cf64da02" |
1226 | "9a7ae3a093bea39770eb96ca3e5b40bff7af0b9f6123f089d7821d0e5b8e1230" | 1439 | SRC_URI[manpages.md5sum] = "31c2272a8979022497ba3d4202df145d" |
1440 | SRC_URI[manpages.sha256sum] = "9a7ae3a093bea39770eb96ca3e5b40bff7af0b9f6123f089d7821d0e5b8e1230" | ||
1227 | 1441 | ||
1228 | Proper values for ``md5`` and ``sha256`` checksums might be available | 1442 | Proper values for ``md5`` and ``sha256`` checksums might be available |
1229 | with other signatures on the download page for the upstream source (e.g. | 1443 | with other signatures on the download page for the upstream source (e.g. |
@@ -1249,9 +1463,13 @@ This final example is a bit more complicated and is from the | |||
1249 | ``meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb`` recipe. The | 1463 | ``meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb`` recipe. The |
1250 | example's ``SRC_URI`` statement identifies multiple files as the source | 1464 | example's ``SRC_URI`` statement identifies multiple files as the source |
1251 | files for the recipe: a tarball, a patch file, a desktop file, and an | 1465 | files for the recipe: a tarball, a patch file, a desktop file, and an |
1252 | icon. SRC_URI = | 1466 | icon. |
1253 | "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \\ | 1467 | :: |
1254 | file://xwc.patch \\ file://rxvt.desktop \\ file://rxvt.png" | 1468 | |
1469 | SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \ | ||
1470 | file://xwc.patch \ | ||
1471 | file://rxvt.desktop \ | ||
1472 | file://rxvt.png" | ||
1255 | 1473 | ||
1256 | When you specify local files using the ``file://`` URI protocol, the | 1474 | When you specify local files using the ``file://`` URI protocol, the |
1257 | build system fetches files from the local machine. The path is relative | 1475 | build system fetches files from the local machine. The path is relative |
@@ -1330,15 +1548,17 @@ Your recipe needs to have both the | |||
1330 | :term:`LIC_FILES_CHKSUM` | 1548 | :term:`LIC_FILES_CHKSUM` |
1331 | variables: | 1549 | variables: |
1332 | 1550 | ||
1333 | - *``LICENSE``:* This variable specifies the license for the software. | 1551 | - ``LICENSE``: This variable specifies the license for the software. |
1334 | If you do not know the license under which the software you are | 1552 | If you do not know the license under which the software you are |
1335 | building is distributed, you should go to the source code and look | 1553 | building is distributed, you should go to the source code and look |
1336 | for that information. Typical files containing this information | 1554 | for that information. Typical files containing this information |
1337 | include ``COPYING``, ``LICENSE``, and ``README`` files. You could | 1555 | include ``COPYING``, ``LICENSE``, and ``README`` files. You could |
1338 | also find the information near the top of a source file. For example, | 1556 | also find the information near the top of a source file. For example, |
1339 | given a piece of software licensed under the GNU General Public | 1557 | given a piece of software licensed under the GNU General Public |
1340 | License version 2, you would set ``LICENSE`` as follows: LICENSE = | 1558 | License version 2, you would set ``LICENSE`` as follows: |
1341 | "GPLv2" | 1559 | :: |
1560 | |||
1561 | LICENSE = "GPLv2" | ||
1342 | 1562 | ||
1343 | The licenses you specify within ``LICENSE`` can have any name as long | 1563 | The licenses you specify within ``LICENSE`` can have any name as long |
1344 | as you do not use spaces, since spaces are used as separators between | 1564 | as you do not use spaces, since spaces are used as separators between |
@@ -1346,7 +1566,7 @@ variables: | |||
1346 | ``meta/files/common-licenses/`` or the ``SPDXLICENSEMAP`` flag names | 1566 | ``meta/files/common-licenses/`` or the ``SPDXLICENSEMAP`` flag names |
1347 | defined in ``meta/conf/licenses.conf``. | 1567 | defined in ``meta/conf/licenses.conf``. |
1348 | 1568 | ||
1349 | - *``LIC_FILES_CHKSUM``:* The OpenEmbedded build system uses this | 1569 | - ``LIC_FILES_CHKSUM``: The OpenEmbedded build system uses this |
1350 | variable to make sure the license text has not changed. If it has, | 1570 | variable to make sure the license text has not changed. If it has, |
1351 | the build produces an error and it affords you the chance to figure | 1571 | the build produces an error and it affords you the chance to figure |
1352 | it out and correct the problem. | 1572 | it out and correct the problem. |
@@ -1367,7 +1587,11 @@ variables: | |||
1367 | additional information. | 1587 | additional information. |
1368 | 1588 | ||
1369 | Here is an example that assumes the software has a ``COPYING`` file: | 1589 | Here is an example that assumes the software has a ``COPYING`` file: |
1370 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxx" When you try to build the | 1590 | :: |
1591 | |||
1592 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxx" | ||
1593 | |||
1594 | When you try to build the | ||
1371 | software, the build system will produce an error and give you the | 1595 | software, the build system will produce an error and give you the |
1372 | correct string that you can substitute into the recipe file for a | 1596 | correct string that you can substitute into the recipe file for a |
1373 | subsequent build. | 1597 | subsequent build. |
@@ -1424,8 +1648,8 @@ These dependencies include any shared library dependencies (i.e. if a | |||
1424 | package "example" contains "libexample" and another package "mypackage" | 1648 | package "example" contains "libexample" and another package "mypackage" |
1425 | contains a binary that links to "libexample" then the OpenEmbedded build | 1649 | contains a binary that links to "libexample" then the OpenEmbedded build |
1426 | system will automatically add a runtime dependency to "mypackage" on | 1650 | system will automatically add a runtime dependency to "mypackage" on |
1427 | "example"). See the "`Automatically Added Runtime | 1651 | "example"). See the |
1428 | Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__" | 1652 | ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" |
1429 | section in the Yocto Project Overview and Concepts Manual for further | 1653 | section in the Yocto Project Overview and Concepts Manual for further |
1430 | details. | 1654 | details. |
1431 | 1655 | ||
@@ -1595,7 +1819,9 @@ When you use custom kernel headers you need to get them from | |||
1595 | :term:`STAGING_KERNEL_DIR`, | 1819 | :term:`STAGING_KERNEL_DIR`, |
1596 | which is the directory with kernel headers that are required to build | 1820 | which is the directory with kernel headers that are required to build |
1597 | out-of-tree modules. Your recipe will also need the following: | 1821 | out-of-tree modules. Your recipe will also need the following: |
1598 | do_configure[depends] += "virtual/kernel:do_shared_workdir" | 1822 | :: |
1823 | |||
1824 | do_configure[depends] += "virtual/kernel:do_shared_workdir" | ||
1599 | 1825 | ||
1600 | .. _new-recipe-compilation: | 1826 | .. _new-recipe-compilation: |
1601 | 1827 | ||
@@ -1629,9 +1855,10 @@ Here are some common issues that cause failures. | |||
1629 | 1855 | ||
1630 | To fix the problem, you need to either satisfy the missing dependency | 1856 | To fix the problem, you need to either satisfy the missing dependency |
1631 | in the Makefile or whatever script produced the Makefile, or (as a | 1857 | in the Makefile or whatever script produced the Makefile, or (as a |
1632 | workaround) set | 1858 | workaround) set :term:`PARALLEL_MAKE` to an empty string: |
1633 | :term:`PARALLEL_MAKE` to an | 1859 | :: |
1634 | empty string: PARALLEL_MAKE = "" | 1860 | |
1861 | PARALLEL_MAKE = "" | ||
1635 | 1862 | ||
1636 | For information on parallel Makefile issues, see the "`Debugging | 1863 | For information on parallel Makefile issues, see the "`Debugging |
1637 | Parallel Make Races <#debugging-parallel-make-races>`__" section. | 1864 | Parallel Make Races <#debugging-parallel-make-races>`__" section. |
@@ -1694,7 +1921,7 @@ the software being built: | |||
1694 | ``do_install_append`` function using the install command as described | 1921 | ``do_install_append`` function using the install command as described |
1695 | in the "Manual" bulleted item later in this list. | 1922 | in the "Manual" bulleted item later in this list. |
1696 | 1923 | ||
1697 | - *Other (using ``make install``):* You need to define a ``do_install`` | 1924 | - Other (using ``make install``): You need to define a ``do_install`` |
1698 | function in your recipe. The function should call | 1925 | function in your recipe. The function should call |
1699 | ``oe_runmake install`` and will likely need to pass in the | 1926 | ``oe_runmake install`` and will likely need to pass in the |
1700 | destination directory as well. How you pass that path is dependent on | 1927 | destination directory as well. How you pass that path is dependent on |
@@ -1827,9 +2054,8 @@ take. The following list describes the process: | |||
1827 | of common problems that show up during runtime. For information on | 2054 | of common problems that show up during runtime. For information on |
1828 | these checks, see the | 2055 | these checks, see the |
1829 | :ref:`insane <ref-classes-insane>` class and | 2056 | :ref:`insane <ref-classes-insane>` class and |
1830 | the "`QA Error and Warning | 2057 | the ":ref:`ref-manual/ref-qa-checks:qa error and warning messages`" |
1831 | Messages <&YOCTO_DOCS_REF_URL;#ref-qa-checks>`__" chapter in the | 2058 | chapter in the Yocto Project Reference Manual. |
1832 | Yocto Project Reference Manual. | ||
1833 | 2059 | ||
1834 | - *Hand-Checking Your Packages*: After you build your software, you | 2060 | - *Hand-Checking Your Packages*: After you build your software, you |
1835 | need to be sure your packages are correct. Examine the | 2061 | need to be sure your packages are correct. Examine the |
@@ -1862,14 +2088,21 @@ take. The following list describes the process: | |||
1862 | :term:`MACHINE` value is passed | 2088 | :term:`MACHINE` value is passed |
1863 | into the configure script or a patch is applied only for a particular | 2089 | into the configure script or a patch is applied only for a particular |
1864 | machine), you should mark them as such by adding the following to the | 2090 | machine), you should mark them as such by adding the following to the |
1865 | recipe: PACKAGE_ARCH = "${MACHINE_ARCH}" | 2091 | recipe: |
2092 | :: | ||
2093 | |||
2094 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
1866 | 2095 | ||
1867 | On the other hand, if the recipe produces packages that do not | 2096 | On the other hand, if the recipe produces packages that do not |
1868 | contain anything specific to the target machine or architecture at | 2097 | contain anything specific to the target machine or architecture at |
1869 | all (e.g. recipes that simply package script files or configuration | 2098 | all (e.g. recipes that simply package script files or configuration |
1870 | files), you should use the | 2099 | files), you should use the |
1871 | :ref:`allarch <ref-classes-allarch>` class to | 2100 | :ref:`allarch <ref-classes-allarch>` class to |
1872 | do this for you by adding this to your recipe: inherit allarch | 2101 | do this for you by adding this to your recipe: |
2102 | :: | ||
2103 | |||
2104 | inherit allarch | ||
2105 | |||
1873 | Ensuring that the package architecture is correct is not critical | 2106 | Ensuring that the package architecture is correct is not critical |
1874 | while you are doing the first few builds of your recipe. However, it | 2107 | while you are doing the first few builds of your recipe. However, it |
1875 | is important in order to ensure that your recipe rebuilds (or does | 2108 | is important in order to ensure that your recipe rebuilds (or does |
@@ -1917,7 +2150,10 @@ task as defined by the the | |||
1917 | automatically populate the sysroot. It is possible to modify the list of | 2150 | automatically populate the sysroot. It is possible to modify the list of |
1918 | directories that populate the sysroot. The following example shows how | 2151 | directories that populate the sysroot. The following example shows how |
1919 | you could add the ``/opt`` directory to the list of directories within a | 2152 | you could add the ``/opt`` directory to the list of directories within a |
1920 | recipe: SYSROOT_DIRS += "/opt" | 2153 | recipe: |
2154 | :: | ||
2155 | |||
2156 | SYSROOT_DIRS += "/opt" | ||
1921 | 2157 | ||
1922 | For a more complete description of the | 2158 | For a more complete description of the |
1923 | :ref:`ref-tasks-populate_sysroot` | 2159 | :ref:`ref-tasks-populate_sysroot` |
@@ -1941,9 +2177,12 @@ kernel recipe. Suppose you have three kernel recipes whose | |||
1941 | in some way uses a :term:`PROVIDES` | 2177 | in some way uses a :term:`PROVIDES` |
1942 | statement that essentially identifies itself as being able to provide | 2178 | statement that essentially identifies itself as being able to provide |
1943 | ``virtual/kernel``. Here is one way through the | 2179 | ``virtual/kernel``. Here is one way through the |
1944 | :ref:`kernel <ref-classes-kernel>` class: PROVIDES | 2180 | :ref:`kernel <ref-classes-kernel>` class: |
1945 | += "${@ "virtual/kernel" if (d.getVar("KERNEL_PACKAGE_NAME") == | 2181 | :: |
1946 | "kernel") else "" }" Any recipe that inherits the ``kernel`` class is | 2182 | |
2183 | PROVIDES += "${@ "virtual/kernel" if (d.getVar("KERNEL_PACKAGE_NAME") == "kernel") else "" }" | ||
2184 | |||
2185 | Any recipe that inherits the ``kernel`` class is | ||
1947 | going to utilize a ``PROVIDES`` statement that identifies that recipe as | 2186 | going to utilize a ``PROVIDES`` statement that identifies that recipe as |
1948 | being able to provide the ``virtual/kernel`` item. | 2187 | being able to provide the ``virtual/kernel`` item. |
1949 | 2188 | ||
@@ -1952,13 +2191,16 @@ recipe, but which one? You can configure your build to call out the | |||
1952 | kernel recipe you want by using the | 2191 | kernel recipe you want by using the |
1953 | :term:`PREFERRED_PROVIDER` | 2192 | :term:`PREFERRED_PROVIDER` |
1954 | variable. As an example, consider the | 2193 | variable. As an example, consider the |
1955 | ```x86-base.inc`https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/x86-base.inc | 2194 | `x86-base.inc <https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/x86-base.inc>`_ |
1956 | include file, which is a machine (i.e. | 2195 | include file, which is a machine (i.e. |
1957 | :term:`MACHINE`) configuration file. | 2196 | :term:`MACHINE`) configuration file. |
1958 | This include file is the reason all x86-based machines use the | 2197 | This include file is the reason all x86-based machines use the |
1959 | ``linux-yocto`` kernel. Here are the relevant lines from the include | 2198 | ``linux-yocto`` kernel. Here are the relevant lines from the include |
1960 | file: PREFERRED_PROVIDER_virtual/kernel ??= "linux-yocto" | 2199 | file: |
1961 | PREFERRED_VERSION_linux-yocto ??= "4.15%" | 2200 | :: |
2201 | |||
2202 | PREFERRED_PROVIDER_virtual/kernel ??= "linux-yocto" | ||
2203 | PREFERRED_VERSION_linux-yocto ??= "4.15%" | ||
1962 | 2204 | ||
1963 | When you use a virtual provider, you do not have to "hard code" a recipe | 2205 | When you use a virtual provider, you do not have to "hard code" a recipe |
1964 | name as a build dependency. You can use the | 2206 | name as a build dependency. You can use the |
@@ -2018,7 +2260,11 @@ In order to ensure the versions compare properly, the recommended | |||
2018 | convention is to set :term:`PV` within the | 2260 | convention is to set :term:`PV` within the |
2019 | recipe to "previous_version+current_version". You can use an additional | 2261 | recipe to "previous_version+current_version". You can use an additional |
2020 | variable so that you can use the current version elsewhere. Here is an | 2262 | variable so that you can use the current version elsewhere. Here is an |
2021 | example: REALPV = "0.8.16-rc1" PV = "0.8.15+${REALPV}" | 2263 | example: |
2264 | :: | ||
2265 | |||
2266 | REALPV = "0.8.16-rc1" | ||
2267 | PV = "0.8.15+${REALPV}" | ||
2022 | 2268 | ||
2023 | .. _new-recipe-post-installation-scripts: | 2269 | .. _new-recipe-post-installation-scripts: |
2024 | 2270 | ||
@@ -2128,12 +2374,26 @@ under ``files``) requires a recipe that has the file listed in the | |||
2128 | ``do_compile`` and ``do_install`` tasks. The ``S`` variable defines the | 2374 | ``do_compile`` and ``do_install`` tasks. The ``S`` variable defines the |
2129 | directory containing the source code, which is set to | 2375 | directory containing the source code, which is set to |
2130 | :term:`WORKDIR` in this case - the | 2376 | :term:`WORKDIR` in this case - the |
2131 | directory BitBake uses for the build. SUMMARY = "Simple helloworld | 2377 | directory BitBake uses for the build. |
2132 | application" SECTION = "examples" LICENSE = "MIT" LIC_FILES_CHKSUM = | 2378 | :: |
2133 | "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" | 2379 | |
2134 | SRC_URI = "file://helloworld.c" S = "${WORKDIR}" do_compile() { ${CC} | 2380 | SUMMARY = "Simple helloworld application" |
2135 | helloworld.c -o helloworld } do_install() { install -d ${D}${bindir} | 2381 | SECTION = "examples" |
2136 | install -m 0755 helloworld ${D}${bindir} } | 2382 | LICENSE = "MIT" |
2383 | LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" | ||
2384 | |||
2385 | SRC_URI = "file://helloworld.c" | ||
2386 | |||
2387 | S = "${WORKDIR}" | ||
2388 | |||
2389 | do_compile() { | ||
2390 | ${CC} helloworld.c -o helloworld | ||
2391 | } | ||
2392 | |||
2393 | do_install() { | ||
2394 | install -d ${D}${bindir} | ||
2395 | install -m 0755 helloworld ${D}${bindir} | ||
2396 | } | ||
2137 | 2397 | ||
2138 | By default, the ``helloworld``, ``helloworld-dbg``, and | 2398 | By default, the ``helloworld``, ``helloworld-dbg``, and |
2139 | ``helloworld-dev`` packages are built. For information on how to | 2399 | ``helloworld-dev`` packages are built. For information on how to |
@@ -2154,10 +2414,17 @@ which contains the definitions of all the steps needed to build an | |||
2154 | Autotool-based application. The result of the build is automatically | 2414 | Autotool-based application. The result of the build is automatically |
2155 | packaged. And, if the application uses NLS for localization, packages | 2415 | packaged. And, if the application uses NLS for localization, packages |
2156 | with local information are generated (one package per language). | 2416 | with local information are generated (one package per language). |
2157 | Following is one example: (``hello_2.3.bb``) SUMMARY = "GNU Helloworld | 2417 | Following is one example: (``hello_2.3.bb``) |
2158 | application" SECTION = "examples" LICENSE = "GPLv2+" LIC_FILES_CHKSUM = | 2418 | :: |
2159 | "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" SRC_URI = | 2419 | |
2160 | "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" inherit autotools gettext | 2420 | SUMMARY = "GNU Helloworld application" |
2421 | SECTION = "examples" | ||
2422 | LICENSE = "GPLv2+" | ||
2423 | LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" | ||
2424 | |||
2425 | SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" | ||
2426 | |||
2427 | inherit autotools gettext | ||
2161 | 2428 | ||
2162 | The variable ``LIC_FILES_CHKSUM`` is used to track source license | 2429 | The variable ``LIC_FILES_CHKSUM`` is used to track source license |
2163 | changes as described in the "`Tracking License | 2430 | changes as described in the "`Tracking License |
@@ -2184,30 +2451,38 @@ Otherwise, BitBake runs an empty ``do_install`` task by default. | |||
2184 | Some applications might require extra parameters to be passed to the | 2451 | Some applications might require extra parameters to be passed to the |
2185 | compiler. For example, the application might need an additional header | 2452 | compiler. For example, the application might need an additional header |
2186 | path. You can accomplish this by adding to the ``CFLAGS`` variable. The | 2453 | path. You can accomplish this by adding to the ``CFLAGS`` variable. The |
2187 | following example shows this: CFLAGS_prepend = "-I ${S}/include " | 2454 | following example shows this: |
2455 | :: | ||
2456 | |||
2457 | CFLAGS_prepend = "-I ${S}/include " | ||
2188 | 2458 | ||
2189 | In the following example, ``mtd-utils`` is a makefile-based package: | 2459 | In the following example, ``mtd-utils`` is a makefile-based package: |
2190 | SUMMARY = "Tools for managing memory technology devices" SECTION = | 2460 | :: |
2191 | "base" DEPENDS = "zlib lzo e2fsprogs util-linux" HOMEPAGE = | 2461 | |
2192 | "http://www.linux-mtd.infradead.org/" LICENSE = "GPLv2+" | 2462 | SUMMARY = "Tools for managing memory technology devices" |
2193 | LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 | 2463 | SECTION = "base" |
2194 | \\ | 2464 | DEPENDS = "zlib lzo e2fsprogs util-linux" |
2195 | file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" | 2465 | HOMEPAGE = "http://www.linux-mtd.infradead.org/" |
2196 | # Use the latest version at 26 Oct, 2013 SRCREV = | 2466 | LICENSE = "GPLv2+" |
2197 | "9f107132a6a073cce37434ca9cda6917dd8d866b" SRC_URI = | 2467 | LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ |
2198 | "git://git.infradead.org/mtd-utils.git \\ | 2468 | file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" |
2199 | file://add-exclusion-to-mkfs-jffs2-git-2.patch \\ " PV = | 2469 | # Use the latest version at 26 Oct, 2013 |
2200 | "1.5.1+git${SRCPV}" S = "${WORKDIR}/git" EXTRA_OEMAKE = "'CC=${CC}' | 2470 | SRCREV = "9f107132a6a073cce37434ca9cda6917dd8d866b" |
2201 | 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include | 2471 | SRC_URI = "git://git.infradead.org/mtd-utils.git \ |
2202 | -DWITHOUT_XATTR' 'BUILDDIR=${S}'" do_install () { oe_runmake install | 2472 | file://add-exclusion-to-mkfs-jffs2-git-2.patch \ |
2203 | DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} | 2473 | " |
2204 | INCLUDEDIR=${includedir} } PACKAGES =+ "mtd-utils-jffs2 mtd-utils-ubifs | 2474 | PV = "1.5.1+git${SRCPV}" |
2205 | mtd-utils-misc" FILES_mtd-utils-jffs2 = "${sbindir}/mkfs.jffs2 | 2475 | S = "${WORKDIR}/git" |
2206 | ${sbindir}/jffs2dump ${sbindir}/jffs2reader ${sbindir}/sumtool" | 2476 | EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'" |
2207 | FILES_mtd-utils-ubifs = "${sbindir}/mkfs.ubifs ${sbindir}/ubi*" | 2477 | do_install () { |
2208 | FILES_mtd-utils-misc = "${sbindir}/nftl\* ${sbindir}/ftl\* | 2478 | oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} INCLUDEDIR=${includedir} |
2209 | ${sbindir}/rfd\* ${sbindir}/doc\* ${sbindir}/serve_image | 2479 | } |
2210 | ${sbindir}/recv_image" PARALLEL_MAKE = "" BBCLASSEXTEND = "native" | 2480 | PACKAGES =+ "mtd-utils-jffs2 mtd-utils-ubifs mtd-utils-misc" |
2481 | FILES_mtd-utils-jffs2 = "${sbindir}/mkfs.jffs2 ${sbindir}/jffs2dump ${sbindir}/jffs2reader ${sbindir}/sumtool" | ||
2482 | FILES_mtd-utils-ubifs = "${sbindir}/mkfs.ubifs ${sbindir}/ubi*" | ||
2483 | FILES_mtd-utils-misc = "${sbindir}/nftl* ${sbindir}/ftl* ${sbindir}/rfd* ${sbindir}/doc* ${sbindir}/serve_image ${sbindir}/recv_image" | ||
2484 | PARALLEL_MAKE = "" | ||
2485 | BBCLASSEXTEND = "native" | ||
2211 | 2486 | ||
2212 | Splitting an Application into Multiple Packages | 2487 | Splitting an Application into Multiple Packages |
2213 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 2488 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
@@ -2218,11 +2493,19 @@ application into multiple packages. | |||
2218 | Following is an example that uses the ``libxpm`` recipe. By default, | 2493 | Following is an example that uses the ``libxpm`` recipe. By default, |
2219 | this recipe generates a single package that contains the library along | 2494 | this recipe generates a single package that contains the library along |
2220 | with a few binaries. You can modify the recipe to split the binaries | 2495 | with a few binaries. You can modify the recipe to split the binaries |
2221 | into separate packages: require xorg-lib-common.inc SUMMARY = "Xpm: X | 2496 | into separate packages: |
2222 | Pixmap extension library" LICENSE = "BSD" LIC_FILES_CHKSUM = | 2497 | :: |
2223 | "file://COPYING;md5=51f4270b012ecd4ab1a164f5f4ed6cf7" DEPENDS += | 2498 | |
2224 | "libxext libsm libxt" PE = "1" XORG_PN = "libXpm" PACKAGES =+ "sxpm | 2499 | require xorg-lib-common.inc |
2225 | cxpm" FILES_cxpm = "${bindir}/cxpm" FILES_sxpm = "${bindir}/sxpm" | 2500 | SUMMARY = "Xpm: X Pixmap extension library" |
2501 | LICENSE = "BSD" | ||
2502 | LIC_FILES_CHKSUM = "file://COPYING;md5=51f4270b012ecd4ab1a164f5f4ed6cf7" | ||
2503 | DEPENDS += "libxext libsm libxt" | ||
2504 | PE = "1" | ||
2505 | XORG_PN = "libXpm" | ||
2506 | PACKAGES =+ "sxpm cxpm" | ||
2507 | FILES_cxpm = "${bindir}/cxpm" | ||
2508 | FILES_sxpm = "${bindir}/sxpm" | ||
2226 | 2509 | ||
2227 | In the previous example, we want to ship the ``sxpm`` and ``cxpm`` | 2510 | In the previous example, we want to ship the ``sxpm`` and ``cxpm`` |
2228 | binaries in separate packages. Since ``bindir`` would be packaged into | 2511 | binaries in separate packages. Since ``bindir`` would be packaged into |
@@ -2282,9 +2565,8 @@ Reference Manual's variable glossary. | |||
2282 | linking. | 2565 | linking. |
2283 | 2566 | ||
2284 | - Using ``DEPENDS`` also allows runtime dependencies between | 2567 | - Using ``DEPENDS`` also allows runtime dependencies between |
2285 | packages to be added automatically. See the "`Automatically Added | 2568 | packages to be added automatically. See the |
2286 | Runtime | 2569 | ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" |
2287 | Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__" | ||
2288 | section in the Yocto Project Overview and Concepts Manual for more | 2570 | section in the Yocto Project Overview and Concepts Manual for more |
2289 | information. | 2571 | information. |
2290 | 2572 | ||
@@ -2303,8 +2585,13 @@ doing the following: | |||
2303 | that replaces ``do_configure`` and ``do_compile`` with custom | 2585 | that replaces ``do_configure`` and ``do_compile`` with custom |
2304 | versions, then you can use the | 2586 | versions, then you can use the |
2305 | ``[``\ :ref:`noexec <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` | 2587 | ``[``\ :ref:`noexec <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` |
2306 | flag to turn the tasks into no-ops, as follows: do_configure[noexec] | 2588 | flag to turn the tasks into no-ops, as follows: |
2307 | = "1" do_compile[noexec] = "1" Unlike | 2589 | :: |
2590 | |||
2591 | do_configure[noexec] = "1" | ||
2592 | do_compile[noexec] = "1" | ||
2593 | |||
2594 | Unlike | ||
2308 | :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:deleting a task`, | 2595 | :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:deleting a task`, |
2309 | using the flag preserves the dependency chain from the | 2596 | using the flag preserves the dependency chain from the |
2310 | :ref:`ref-tasks-fetch`, | 2597 | :ref:`ref-tasks-fetch`, |
@@ -2352,8 +2639,12 @@ chapter of the BitBake User Manual. | |||
2352 | supported. | 2639 | supported. |
2353 | 2640 | ||
2354 | The following example shows some of the ways you can use variables in | 2641 | The following example shows some of the ways you can use variables in |
2355 | recipes: S = "${WORKDIR}/postfix-${PV}" CFLAGS += "-DNO_ASM" | 2642 | recipes: |
2356 | SRC_URI_append = " file://fixup.patch" | 2643 | :: |
2644 | |||
2645 | S = "${WORKDIR}/postfix-${PV}" | ||
2646 | CFLAGS += "-DNO_ASM" | ||
2647 | SRC_URI_append = " file://fixup.patch" | ||
2357 | 2648 | ||
2358 | - *Functions:* Functions provide a series of actions to be performed. | 2649 | - *Functions:* Functions provide a series of actions to be performed. |
2359 | You usually use functions to override the default implementation of a | 2650 | You usually use functions to override the default implementation of a |
@@ -2363,8 +2654,16 @@ chapter of the BitBake User Manual. | |||
2363 | methods are also available. | 2654 | methods are also available. |
2364 | 2655 | ||
2365 | The following is an example function from the ``sed`` recipe: | 2656 | The following is an example function from the ``sed`` recipe: |
2366 | do_install () { autotools_do_install install -d ${D}${base_bindir} mv | 2657 | :: |
2367 | ${D}${bindir}/sed ${D}${base_bindir}/sed rmdir ${D}${bindir}/ } It is | 2658 | |
2659 | do_install () { | ||
2660 | autotools_do_install | ||
2661 | install -d ${D}${base_bindir} | ||
2662 | mv ${D}${bindir}/sed ${D}${base_bindir}/sed | ||
2663 | rmdir ${D}${bindir}/ | ||
2664 | } | ||
2665 | |||
2666 | It is | ||
2368 | also possible to implement new functions that are called between | 2667 | also possible to implement new functions that are called between |
2369 | existing tasks as long as the new functions are not replacing or | 2668 | existing tasks as long as the new functions are not replacing or |
2370 | complementing the default functions. You can implement functions in | 2669 | complementing the default functions. You can implement functions in |
@@ -2376,12 +2675,18 @@ chapter of the BitBake User Manual. | |||
2376 | from other files (``include`` and ``require``) and export variables | 2675 | from other files (``include`` and ``require``) and export variables |
2377 | to the environment (``export``). | 2676 | to the environment (``export``). |
2378 | 2677 | ||
2379 | The following example shows the use of some of these keywords: export | 2678 | The following example shows the use of some of these keywords: |
2380 | POSTCONF = "${STAGING_BINDIR}/postconf" inherit autoconf require | 2679 | :: |
2381 | otherfile.inc | 2680 | |
2681 | export POSTCONF = "${STAGING_BINDIR}/postconf" | ||
2682 | inherit autoconf | ||
2683 | require otherfile.inc | ||
2382 | 2684 | ||
2383 | - *Comments (#):* Any lines that begin with the hash character (``#``) | 2685 | - *Comments (#):* Any lines that begin with the hash character (``#``) |
2384 | are treated as comment lines and are ignored: # This is a comment | 2686 | are treated as comment lines and are ignored: |
2687 | :: | ||
2688 | |||
2689 | # This is a comment | ||
2385 | 2690 | ||
2386 | This next list summarizes the most important and most commonly used | 2691 | This next list summarizes the most important and most commonly used |
2387 | parts of the recipe syntax. For more information on these parts of the | 2692 | parts of the recipe syntax. For more information on these parts of the |
@@ -2391,8 +2696,11 @@ in the BitBake User Manual. | |||
2391 | 2696 | ||
2392 | - *Line Continuation (\):* Use the backward slash (``\``) character to | 2697 | - *Line Continuation (\):* Use the backward slash (``\``) character to |
2393 | split a statement over multiple lines. Place the slash character at | 2698 | split a statement over multiple lines. Place the slash character at |
2394 | the end of the line that is to be continued on the next line: VAR = | 2699 | the end of the line that is to be continued on the next line: |
2395 | "A really long \\ line" | 2700 | :: |
2701 | |||
2702 | VAR = "A really long \ | ||
2703 | line" | ||
2396 | 2704 | ||
2397 | .. note:: | 2705 | .. note:: |
2398 | 2706 | ||
@@ -2400,8 +2708,10 @@ in the BitBake User Manual. | |||
2400 | slash character. | 2708 | slash character. |
2401 | 2709 | ||
2402 | - *Using Variables (${VARNAME}):* Use the ``${VARNAME}`` syntax to | 2710 | - *Using Variables (${VARNAME}):* Use the ``${VARNAME}`` syntax to |
2403 | access the contents of a variable: SRC_URI = | 2711 | access the contents of a variable: |
2404 | "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" | 2712 | :: |
2713 | |||
2714 | SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" | ||
2405 | 2715 | ||
2406 | .. note:: | 2716 | .. note:: |
2407 | 2717 | ||
@@ -2420,7 +2730,10 @@ in the BitBake User Manual. | |||
2420 | 2730 | ||
2421 | - *Quote All Assignments ("value"):* Use double quotes around values in | 2731 | - *Quote All Assignments ("value"):* Use double quotes around values in |
2422 | all variable assignments (e.g. ``"value"``). Following is an example: | 2732 | all variable assignments (e.g. ``"value"``). Following is an example: |
2423 | VAR1 = "${OTHERVAR}" VAR2 = "The version is ${PV}" | 2733 | :: |
2734 | |||
2735 | VAR1 = "${OTHERVAR}" | ||
2736 | VAR2 = "The version is ${PV}" | ||
2424 | 2737 | ||
2425 | - *Conditional Assignment (?=):* Conditional assignment is used to | 2738 | - *Conditional Assignment (?=):* Conditional assignment is used to |
2426 | assign a value to a variable, but only when the variable is currently | 2739 | assign a value to a variable, but only when the variable is currently |
@@ -2432,8 +2745,11 @@ in the BitBake User Manual. | |||
2432 | Here is an example where ``VAR1`` is set to "New value" if it is | 2745 | Here is an example where ``VAR1`` is set to "New value" if it is |
2433 | currently empty. However, if ``VAR1`` has already been set, it | 2746 | currently empty. However, if ``VAR1`` has already been set, it |
2434 | remains unchanged: VAR1 ?= "New value" In this next example, ``VAR1`` | 2747 | remains unchanged: VAR1 ?= "New value" In this next example, ``VAR1`` |
2435 | is left with the value "Original value": VAR1 = "Original value" VAR1 | 2748 | is left with the value "Original value": |
2436 | ?= "New value" | 2749 | :: |
2750 | |||
2751 | VAR1 = "Original value" | ||
2752 | VAR1 ?= "New value" | ||
2437 | 2753 | ||
2438 | - *Appending (+=):* Use the plus character followed by the equals sign | 2754 | - *Appending (+=):* Use the plus character followed by the equals sign |
2439 | (``+=``) to append values to existing variables. | 2755 | (``+=``) to append values to existing variables. |
@@ -2443,7 +2759,10 @@ in the BitBake User Manual. | |||
2443 | This operator adds a space between the existing content of the | 2759 | This operator adds a space between the existing content of the |
2444 | variable and the new content. | 2760 | variable and the new content. |
2445 | 2761 | ||
2446 | Here is an example: SRC_URI += "file://fix-makefile.patch" | 2762 | Here is an example: |
2763 | :: | ||
2764 | |||
2765 | SRC_URI += "file://fix-makefile.patch" | ||
2447 | 2766 | ||
2448 | - *Prepending (=+):* Use the equals sign followed by the plus character | 2767 | - *Prepending (=+):* Use the equals sign followed by the plus character |
2449 | (``=+``) to prepend values to existing variables. | 2768 | (``=+``) to prepend values to existing variables. |
@@ -2453,7 +2772,10 @@ in the BitBake User Manual. | |||
2453 | This operator adds a space between the new content and the | 2772 | This operator adds a space between the new content and the |
2454 | existing content of the variable. | 2773 | existing content of the variable. |
2455 | 2774 | ||
2456 | Here is an example: VAR =+ "Starts" | 2775 | Here is an example: |
2776 | :: | ||
2777 | |||
2778 | VAR =+ "Starts" | ||
2457 | 2779 | ||
2458 | - *Appending (_append):* Use the ``_append`` operator to append values | 2780 | - *Appending (_append):* Use the ``_append`` operator to append values |
2459 | to existing variables. This operator does not add any additional | 2781 | to existing variables. This operator does not add any additional |
@@ -2463,10 +2785,17 @@ in the BitBake User Manual. | |||
2463 | 2785 | ||
2464 | The following example shows the space being explicitly added to the | 2786 | The following example shows the space being explicitly added to the |
2465 | start to ensure the appended value is not merged with the existing | 2787 | start to ensure the appended value is not merged with the existing |
2466 | value: SRC_URI_append = " file://fix-makefile.patch" You can also use | 2788 | value: |
2789 | :: | ||
2790 | |||
2791 | SRC_URI_append = " file://fix-makefile.patch" | ||
2792 | |||
2793 | You can also use | ||
2467 | the ``_append`` operator with overrides, which results in the actions | 2794 | the ``_append`` operator with overrides, which results in the actions |
2468 | only being performed for the specified target or machine: | 2795 | only being performed for the specified target or machine: |
2469 | SRC_URI_append_sh4 = " file://fix-makefile.patch" | 2796 | :: |
2797 | |||
2798 | SRC_URI_append_sh4 = " file://fix-makefile.patch" | ||
2470 | 2799 | ||
2471 | - *Prepending (_prepend):* Use the ``_prepend`` operator to prepend | 2800 | - *Prepending (_prepend):* Use the ``_prepend`` operator to prepend |
2472 | values to existing variables. This operator does not add any | 2801 | values to existing variables. This operator does not add any |
@@ -2476,10 +2805,17 @@ in the BitBake User Manual. | |||
2476 | 2805 | ||
2477 | The following example shows the space being explicitly added to the | 2806 | The following example shows the space being explicitly added to the |
2478 | end to ensure the prepended value is not merged with the existing | 2807 | end to ensure the prepended value is not merged with the existing |
2479 | value: CFLAGS_prepend = "-I${S}/myincludes " You can also use the | 2808 | value: |
2809 | :: | ||
2810 | |||
2811 | CFLAGS_prepend = "-I${S}/myincludes " | ||
2812 | |||
2813 | You can also use the | ||
2480 | ``_prepend`` operator with overrides, which results in the actions | 2814 | ``_prepend`` operator with overrides, which results in the actions |
2481 | only being performed for the specified target or machine: | 2815 | only being performed for the specified target or machine: |
2482 | CFLAGS_prepend_sh4 = "-I${S}/myincludes " | 2816 | :: |
2817 | |||
2818 | CFLAGS_prepend_sh4 = "-I${S}/myincludes " | ||
2483 | 2819 | ||
2484 | - *Overrides:* You can use overrides to set a value conditionally, | 2820 | - *Overrides:* You can use overrides to set a value conditionally, |
2485 | typically based on how the recipe is being built. For example, to set | 2821 | typically based on how the recipe is being built. For example, to set |
@@ -2487,8 +2823,13 @@ in the BitBake User Manual. | |||
2487 | value to "standard/base" for any target | 2823 | value to "standard/base" for any target |
2488 | :term:`MACHINE`, except for | 2824 | :term:`MACHINE`, except for |
2489 | qemuarm where it should be set to "standard/arm-versatile-926ejs", | 2825 | qemuarm where it should be set to "standard/arm-versatile-926ejs", |
2490 | you would do the following: KBRANCH = "standard/base" KBRANCH_qemuarm | 2826 | you would do the following: |
2491 | = "standard/arm-versatile-926ejs" Overrides are also used to separate | 2827 | :: |
2828 | |||
2829 | KBRANCH = "standard/base" | ||
2830 | KBRANCH_qemuarm = "standard/arm-versatile-926ejs" | ||
2831 | |||
2832 | Overrides are also used to separate | ||
2492 | alternate values of a variable in other situations. For example, when | 2833 | alternate values of a variable in other situations. For example, when |
2493 | setting variables such as | 2834 | setting variables such as |
2494 | :term:`FILES` and | 2835 | :term:`FILES` and |
@@ -2506,9 +2847,10 @@ in the BitBake User Manual. | |||
2506 | search and replacement on a variable). | 2847 | search and replacement on a variable). |
2507 | 2848 | ||
2508 | You indicate Python code using the ``${@python_code}`` syntax for the | 2849 | You indicate Python code using the ``${@python_code}`` syntax for the |
2509 | variable assignment: SRC_URI = | 2850 | variable assignment: |
2510 | "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', | 2851 | :: |
2511 | '')}.tgz | 2852 | |
2853 | SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz | ||
2512 | 2854 | ||
2513 | - *Shell Function Syntax:* Write shell functions as if you were writing | 2855 | - *Shell Function Syntax:* Write shell functions as if you were writing |
2514 | a shell script when you describe a list of actions to take. You | 2856 | a shell script when you describe a list of actions to take. You |
@@ -2537,8 +2879,7 @@ that the Yocto Project already supports. | |||
2537 | manual. | 2879 | manual. |
2538 | 2880 | ||
2539 | For a complete example that shows how to add a new machine, see the | 2881 | For a complete example that shows how to add a new machine, see the |
2540 | "`Creating a New BSP Layer Using the ``bitbake-layers`` | 2882 | ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" |
2541 | Script <&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script>`__" | ||
2542 | section in the Yocto Project Board Support Package (BSP) Developer's | 2883 | section in the Yocto Project Board Support Package (BSP) Developer's |
2543 | Guide. | 2884 | Guide. |
2544 | 2885 | ||
@@ -2604,9 +2945,13 @@ of adding a suitable ``defconfig`` file. The file needs to be added into | |||
2604 | a location similar to ``defconfig`` files used for other machines in a | 2945 | a location similar to ``defconfig`` files used for other machines in a |
2605 | given kernel recipe. A possible way to do this is by listing the file in | 2946 | given kernel recipe. A possible way to do this is by listing the file in |
2606 | the ``SRC_URI`` and adding the machine to the expression in | 2947 | the ``SRC_URI`` and adding the machine to the expression in |
2607 | ``COMPATIBLE_MACHINE``: COMPATIBLE_MACHINE = '(qemux86|qemumips)' For | 2948 | ``COMPATIBLE_MACHINE``: |
2608 | more information on ``defconfig`` files, see the "`Changing the | 2949 | :: |
2609 | Configuration <&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration>`__" | 2950 | |
2951 | COMPATIBLE_MACHINE = '(qemux86|qemumips)' | ||
2952 | |||
2953 | For more information on ``defconfig`` files, see the | ||
2954 | ":ref:`kernel-dev/kernel-dev-common:changing the configuration`" | ||
2610 | section in the Yocto Project Linux Kernel Development Manual. | 2955 | section in the Yocto Project Linux Kernel Development Manual. |
2611 | 2956 | ||
2612 | .. _platdev-newmachine-formfactor: | 2957 | .. _platdev-newmachine-formfactor: |
@@ -2630,10 +2975,18 @@ contains directories for specific machines such as ``qemuarm`` and | |||
2630 | defaults, see the ``meta/recipes-bsp/formfactor/files/config`` file | 2975 | defaults, see the ``meta/recipes-bsp/formfactor/files/config`` file |
2631 | found in the same area. | 2976 | found in the same area. |
2632 | 2977 | ||
2633 | Following is an example for "qemuarm" machine: HAVE_TOUCHSCREEN=1 | 2978 | Following is an example for "qemuarm" machine: |
2634 | HAVE_KEYBOARD=1 DISPLAY_CAN_ROTATE=0 DISPLAY_ORIENTATION=0 | 2979 | :: |
2635 | #DISPLAY_WIDTH_PIXELS=640 #DISPLAY_HEIGHT_PIXELS=480 #DISPLAY_BPP=16 | 2980 | |
2636 | DISPLAY_DPI=150 DISPLAY_SUBPIXEL_ORDER=vrgb | 2981 | HAVE_TOUCHSCREEN=1 |
2982 | HAVE_KEYBOARD=1 | ||
2983 | DISPLAY_CAN_ROTATE=0 | ||
2984 | DISPLAY_ORIENTATION=0 | ||
2985 | #DISPLAY_WIDTH_PIXELS=640 | ||
2986 | #DISPLAY_HEIGHT_PIXELS=480 | ||
2987 | #DISPLAY_BPP=16 | ||
2988 | DISPLAY_DPI=150 | ||
2989 | DISPLAY_SUBPIXEL_ORDER=vrgb | ||
2637 | 2990 | ||
2638 | .. _gs-upgrading-recipes: | 2991 | .. _gs-upgrading-recipes: |
2639 | 2992 | ||
@@ -2646,9 +2999,8 @@ upstream version releases. | |||
2646 | 2999 | ||
2647 | While several methods exist that allow you upgrade a recipe, you might | 3000 | While several methods exist that allow you upgrade a recipe, you might |
2648 | consider checking on the upgrade status of a recipe first. You can do so | 3001 | consider checking on the upgrade status of a recipe first. You can do so |
2649 | using the ``devtool check-upgrade-status`` command. See the "`Checking | 3002 | using the ``devtool check-upgrade-status`` command. See the |
2650 | on the Upgrade Status of a | 3003 | ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" |
2651 | Recipe <&YOCTO_DOCS_REF_URL;#devtool-checking-on-the-upgrade-status-of-a-recipe>`__" | ||
2652 | section in the Yocto Project Reference Manual for more information. | 3004 | section in the Yocto Project Reference Manual for more information. |
2653 | 3005 | ||
2654 | The remainder of this section describes three ways you can upgrade a | 3006 | The remainder of this section describes three ways you can upgrade a |
@@ -2700,27 +3052,42 @@ The following steps describe how to set up the AUH utility: | |||
2700 | 2. *Make Sure Git is Configured:* The AUH utility requires Git to be | 3052 | 2. *Make Sure Git is Configured:* The AUH utility requires Git to be |
2701 | configured because AUH uses Git to save upgrades. Thus, you must have | 3053 | configured because AUH uses Git to save upgrades. Thus, you must have |
2702 | Git user and email configured. The following command shows your | 3054 | Git user and email configured. The following command shows your |
2703 | configurations: $ git config --list If you do not have the user and | 3055 | configurations: |
2704 | email configured, you can use the following commands to do so: $ git | 3056 | |
2705 | config --global user.name some_name $ git config --global user.email | 3057 | $ git config --list |
2706 | username@domain.com | 3058 | |
3059 | If you do not have the user and | ||
3060 | email configured, you can use the following commands to do so: | ||
3061 | :: | ||
3062 | |||
3063 | $ git config --global user.name some_name | ||
3064 | $ git config --global user.email username@domain.com | ||
2707 | 3065 | ||
2708 | 3. *Clone the AUH Repository:* To use AUH, you must clone the repository | 3066 | 3. *Clone the AUH Repository:* To use AUH, you must clone the repository |
2709 | onto your development host. The following command uses Git to create | 3067 | onto your development host. The following command uses Git to create |
2710 | a local copy of the repository on your system: $ git clone | 3068 | a local copy of the repository on your system: |
2711 | git://git.yoctoproject.org/auto-upgrade-helper Cloning into | 3069 | :: |
2712 | 'auto-upgrade-helper'... remote: Counting objects: 768, done. remote: | 3070 | |
2713 | Compressing objects: 100% (300/300), done. remote: Total 768 (delta | 3071 | $ git clone git://git.yoctoproject.org/auto-upgrade-helper |
2714 | 499), reused 703 (delta 434) Receiving objects: 100% (768/768), | 3072 | Cloning into 'auto-upgrade-helper'... remote: Counting objects: 768, done. |
2715 | 191.47 KiB \| 98.00 KiB/s, done. Resolving deltas: 100% (499/499), | 3073 | remote: Compressing objects: 100% (300/300), done. |
2716 | done. Checking connectivity... done. AUH is not part of the | 3074 | remote: Total 768 (delta 499), reused 703 (delta 434) |
2717 | :term:`OpenEmbedded-Core (OE-Core)` or | 3075 | Receiving objects: 100% (768/768), 191.47 KiB | 98.00 KiB/s, done. |
2718 | `Poky <&YOCTO_DOCS_REF_URL;#poky>`__ repositories. | 3076 | Resolving deltas: 100% (499/499), done. |
3077 | Checking connectivity... done. | ||
3078 | |||
3079 | AUH is not part of the :term:`OpenEmbedded-Core (OE-Core)` or | ||
3080 | :term:`Poky` repositories. | ||
2719 | 3081 | ||
2720 | 4. *Create a Dedicated Build Directory:* Run the | 3082 | 4. *Create a Dedicated Build Directory:* Run the |
2721 | ```oe-init-build-env`` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ | 3083 | :ref:`structure-core-script` |
2722 | script to create a fresh build directory that you use exclusively for | 3084 | script to create a fresh build directory that you use exclusively for |
2723 | running the AUH utility: $ cd ~/poky $ source oe-init-build-env | 3085 | running the AUH utility: |
3086 | :: | ||
3087 | |||
3088 | $ cd ~/poky | ||
3089 | $ source oe-init-build-env | ||
3090 | |||
2724 | your_AUH_build_directory Re-using an existing build directory and its | 3091 | your_AUH_build_directory Re-using an existing build directory and its |
2725 | configurations is not recommended as existing settings could cause | 3092 | configurations is not recommended as existing settings could cause |
2726 | AUH to fail or behave undesirably. | 3093 | AUH to fail or behave undesirably. |
@@ -2730,11 +3097,16 @@ The following steps describe how to set up the AUH utility: | |||
2730 | directory you just created for AUH. Make these following | 3097 | directory you just created for AUH. Make these following |
2731 | configurations: | 3098 | configurations: |
2732 | 3099 | ||
2733 | - If you want to enable `Build | 3100 | - If you want to enable :ref:`Build |
2734 | History <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__, | 3101 | History <dev-manual/dev-manual-common-tasks:maintaining build output quality>`, |
2735 | which is optional, you need the following lines in the | 3102 | which is optional, you need the following lines in the |
2736 | ``conf/local.conf`` file: INHERIT =+ "buildhistory" | 3103 | ``conf/local.conf`` file: |
2737 | BUILDHISTORY_COMMIT = "1" With this configuration and a successful | 3104 | :: |
3105 | |||
3106 | INHERIT =+ "buildhistory" | ||
3107 | BUILDHISTORY_COMMIT = "1" | ||
3108 | |||
3109 | With this configuration and a successful | ||
2738 | upgrade, a build history "diff" file appears in the | 3110 | upgrade, a build history "diff" file appears in the |
2739 | ``upgrade-helper/work/recipe/buildhistory-diff.txt`` file found in | 3111 | ``upgrade-helper/work/recipe/buildhistory-diff.txt`` file found in |
2740 | your build directory. | 3112 | your build directory. |
@@ -2753,11 +3125,14 @@ The following steps describe how to set up the AUH utility: | |||
2753 | :: | 3125 | :: |
2754 | 3126 | ||
2755 | DISTRO_FEATURES_append = " ptest" | 3127 | DISTRO_FEATURES_append = " ptest" |
2756 | 3128 | ||
2757 | 3129 | ||
2758 | 6. *Optionally Start a vncserver:* If you are running in a server | 3130 | 6. *Optionally Start a vncserver:* If you are running in a server |
2759 | without an X11 session, you need to start a vncserver: $ vncserver :1 | 3131 | without an X11 session, you need to start a vncserver: |
2760 | $ export DISPLAY=:1 | 3132 | :: |
3133 | |||
3134 | $ vncserver :1 | ||
3135 | $ export DISPLAY=:1 | ||
2761 | 3136 | ||
2762 | 7. *Create and Edit an AUH Configuration File:* You need to have the | 3137 | 7. *Create and Edit an AUH Configuration File:* You need to have the |
2763 | ``upgrade-helper/upgrade-helper.conf`` configuration file in your | 3138 | ``upgrade-helper/upgrade-helper.conf`` configuration file in your |
@@ -2780,33 +3155,47 @@ This next set of examples describes how to use the AUH: | |||
2780 | 3155 | ||
2781 | - *Upgrading a Specific Recipe:* To upgrade a specific recipe, use the | 3156 | - *Upgrading a Specific Recipe:* To upgrade a specific recipe, use the |
2782 | following form: $ upgrade-helper.py recipe_name For example, this | 3157 | following form: $ upgrade-helper.py recipe_name For example, this |
2783 | command upgrades the ``xmodmap`` recipe: $ upgrade-helper.py xmodmap | 3158 | command upgrades the ``xmodmap`` recipe: |
3159 | :: | ||
3160 | |||
3161 | $ upgrade-helper.py xmodmap | ||
2784 | 3162 | ||
2785 | - *Upgrading a Specific Recipe to a Particular Version:* To upgrade a | 3163 | - *Upgrading a Specific Recipe to a Particular Version:* To upgrade a |
2786 | specific recipe to a particular version, use the following form: $ | 3164 | specific recipe to a particular version, use the following form: $ |
2787 | upgrade-helper.py recipe_name -t version For example, this command | 3165 | upgrade-helper.py recipe_name -t version For example, this command |
2788 | upgrades the ``xmodmap`` recipe to version 1.2.3: $ upgrade-helper.py | 3166 | upgrades the ``xmodmap`` recipe to version 1.2.3: |
2789 | xmodmap -t 1.2.3 | 3167 | :: |
3168 | |||
3169 | $ upgrade-helper.py xmodmap -t 1.2.3 | ||
2790 | 3170 | ||
2791 | - *Upgrading all Recipes to the Latest Versions and Suppressing Email | 3171 | - *Upgrading all Recipes to the Latest Versions and Suppressing Email |
2792 | Notifications:* To upgrade all recipes to their most recent versions | 3172 | Notifications:* To upgrade all recipes to their most recent versions |
2793 | and suppress the email notifications, use the following command: $ | 3173 | and suppress the email notifications, use the following command: |
2794 | upgrade-helper.py all | 3174 | :: |
3175 | |||
3176 | $ upgrade-helper.py all | ||
2795 | 3177 | ||
2796 | - *Upgrading all Recipes to the Latest Versions and Send Email | 3178 | - *Upgrading all Recipes to the Latest Versions and Send Email |
2797 | Notifications:* To upgrade all recipes to their most recent versions | 3179 | Notifications:* To upgrade all recipes to their most recent versions |
2798 | and send email messages to maintainers for each attempted recipe as | 3180 | and send email messages to maintainers for each attempted recipe as |
2799 | well as a status email, use the following command: $ | 3181 | well as a status email, use the following command: |
2800 | upgrade-helper.py -e all | 3182 | :: |
3183 | |||
3184 | $ upgrade-helper.py -e all | ||
2801 | 3185 | ||
2802 | Once you have run the AUH utility, you can find the results in the AUH | 3186 | Once you have run the AUH utility, you can find the results in the AUH |
2803 | build directory: ${BUILDDIR}/upgrade-helper/timestamp The AUH utility | 3187 | build directory: |
3188 | :: | ||
3189 | |||
3190 | ${BUILDDIR}/upgrade-helper/timestamp | ||
3191 | |||
3192 | The AUH utility | ||
2804 | also creates recipe update commits from successful upgrade attempts in | 3193 | also creates recipe update commits from successful upgrade attempts in |
2805 | the layer tree. | 3194 | the layer tree. |
2806 | 3195 | ||
2807 | You can easily set up to run the AUH utility on a regular basis by using | 3196 | You can easily set up to run the AUH utility on a regular basis by using |
2808 | a cron job. See the | 3197 | a cron job. See the |
2809 | ```weeklyjob.sh`http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/tree/weeklyjob.sh | 3198 | `weeklyjob.sh <http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/tree/weeklyjob.sh>`_ |
2810 | file distributed with the utility for an example. | 3199 | file distributed with the utility for an example. |
2811 | 3200 | ||
2812 | .. _gs-using-devtool-upgrade: | 3201 | .. _gs-using-devtool-upgrade: |
@@ -2816,20 +3205,24 @@ Using ``devtool upgrade`` | |||
2816 | 3205 | ||
2817 | As mentioned earlier, an alternative method for upgrading recipes to | 3206 | As mentioned earlier, an alternative method for upgrading recipes to |
2818 | newer versions is to use | 3207 | newer versions is to use |
2819 | ```devtool upgrade`` <&YOCTO_DOCS_REF_URL;#ref-devtool-reference>`__. | 3208 | :doc:`devtool upgrade <../ref-manual/ref-devtool-reference>`. |
2820 | You can read about ``devtool upgrade`` in general in the "`Use | 3209 | You can read about ``devtool upgrade`` in general in the |
2821 | ``devtool upgrade`` to Create a Version of the Recipe that Supports a | 3210 | ":ref:`sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software`" |
2822 | Newer Version of the | ||
2823 | Software <&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software>`__" | ||
2824 | section in the Yocto Project Application Development and the Extensible | 3211 | section in the Yocto Project Application Development and the Extensible |
2825 | Software Development Kit (eSDK) Manual. | 3212 | Software Development Kit (eSDK) Manual. |
2826 | 3213 | ||
2827 | To see all the command-line options available with ``devtool upgrade``, | 3214 | To see all the command-line options available with ``devtool upgrade``, |
2828 | use the following help command: $ devtool upgrade -h | 3215 | use the following help command: |
3216 | :: | ||
3217 | |||
3218 | $ devtool upgrade -h | ||
2829 | 3219 | ||
2830 | If you want to find out what version a recipe is currently at upstream | 3220 | If you want to find out what version a recipe is currently at upstream |
2831 | without any attempt to upgrade your local version of the recipe, you can | 3221 | without any attempt to upgrade your local version of the recipe, you can |
2832 | use the following command: $ devtool latest-version recipe_name | 3222 | use the following command: |
3223 | :: | ||
3224 | |||
3225 | $ devtool latest-version recipe_name | ||
2833 | 3226 | ||
2834 | As mentioned in the previous section describing AUH, ``devtool upgrade`` | 3227 | As mentioned in the previous section describing AUH, ``devtool upgrade`` |
2835 | works in a less-automated manner than AUH. Specifically, | 3228 | works in a less-automated manner than AUH. Specifically, |
@@ -2853,23 +3246,29 @@ repository that you use during build operations. Because you are (or | |||
2853 | have) built the recipe in the past, the layer is likely added to your | 3246 | have) built the recipe in the past, the layer is likely added to your |
2854 | configuration already. If for some reason, the layer is not added, you | 3247 | configuration already. If for some reason, the layer is not added, you |
2855 | could add it easily using the | 3248 | could add it easily using the |
2856 | ```bitbake-layers`` <&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script>`__ | 3249 | ":ref:`bitbake-layers <bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script>`" |
2857 | script. For example, suppose you use the ``nano.bb`` recipe from the | 3250 | script. For example, suppose you use the ``nano.bb`` recipe from the |
2858 | ``meta-oe`` layer in the ``meta-openembedded`` repository. For this | 3251 | ``meta-oe`` layer in the ``meta-openembedded`` repository. For this |
2859 | example, assume that the layer has been cloned into following area: | 3252 | example, assume that the layer has been cloned into following area: |
2860 | /home/scottrif/meta-openembedded The following command from your | 3253 | :: |
3254 | |||
3255 | /home/scottrif/meta-openembedded | ||
3256 | |||
3257 | The following command from your | ||
2861 | :term:`Build Directory` adds the layer to | 3258 | :term:`Build Directory` adds the layer to |
2862 | your build configuration (i.e. ``${BUILDDIR}/conf/bblayers.conf``): $ | 3259 | your build configuration (i.e. ``${BUILDDIR}/conf/bblayers.conf``): |
2863 | bitbake-layers add-layer /home/scottrif/meta-openembedded/meta-oe NOTE: | 3260 | :: |
2864 | Starting bitbake server... Parsing recipes: 100% | 3261 | |
2865 | \|##########################################\| Time: 0:00:55 Parsing of | 3262 | $ bitbake-layers add-layer /home/scottrif/meta-openembedded/meta-oe |
2866 | 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 | 3263 | NOTE: Starting bitbake server... |
2867 | skipped, 0 masked, 0 errors. Removing 12 recipes from the x86_64 | 3264 | Parsing recipes: 100% |##########################################| Time: 0:00:55 |
2868 | sysroot: 100% \|##############\| Time: 0:00:00 Removing 1 recipes from | 3265 | Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors. |
2869 | the x86_64_i586 sysroot: 100% \|##########\| Time: 0:00:00 Removing 5 | 3266 | Removing 12 recipes from the x86_64 sysroot: 100% |##############| Time: 0:00:00 |
2870 | recipes from the i586 sysroot: 100% \|#################\| Time: 0:00:00 | 3267 | Removing 1 recipes from the x86_64_i586 sysroot: 100% |##########| Time: 0:00:00 |
2871 | Removing 5 recipes from the qemux86 sysroot: 100% \|##############\| | 3268 | Removing 5 recipes from the i586 sysroot: 100% |#################| Time: 0:00:00 |
2872 | Time: 0:00:00 For this example, assume that the ``nano.bb`` recipe that | 3269 | Removing 5 recipes from the qemux86 sysroot: 100% |##############| Time: 0:00:00 |
3270 | |||
3271 | For this example, assume that the ``nano.bb`` recipe that | ||
2873 | is upstream has a 2.9.3 version number. However, the version in the | 3272 | is upstream has a 2.9.3 version number. However, the version in the |
2874 | local repository is 2.7.4. The following command from your build | 3273 | local repository is 2.7.4. The following command from your build |
2875 | directory automatically upgrades the recipe for you: | 3274 | directory automatically upgrades the recipe for you: |
@@ -2882,33 +3281,45 @@ directory automatically upgrades the recipe for you: | |||
2882 | devtool upgrade | 3281 | devtool upgrade |
2883 | to upgrade the recipe to the most recent version. | 3282 | to upgrade the recipe to the most recent version. |
2884 | 3283 | ||
2885 | $ devtool upgrade nano -V 2.9.3 NOTE: Starting bitbake server... NOTE: | 3284 | :: |
2886 | Creating workspace layer in /home/scottrif/poky/build/workspace Parsing | 3285 | |
2887 | recipes: 100% \|##########################################\| Time: | 3286 | $ devtool upgrade nano -V 2.9.3 |
2888 | 0:00:46 Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 | 3287 | NOTE: Starting bitbake server... |
2889 | targets, 56 skipped, 0 masked, 0 errors. NOTE: Extracting current | 3288 | NOTE: Creating workspace layer in /home/scottrif/poky/build/workspace |
2890 | version source... NOTE: Resolving any missing task queue dependencies . | 3289 | Parsing recipes: 100% |##########################################| Time: 0:00:46 |
2891 | . . NOTE: Executing SetScene Tasks NOTE: Executing RunQueue Tasks NOTE: | 3290 | Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors. |
2892 | Tasks Summary: Attempted 74 tasks of which 72 didn't need to be rerun | 3291 | NOTE: Extracting current version source... |
2893 | and all succeeded. Adding changed files: 100% | 3292 | NOTE: Resolving any missing task queue dependencies |
2894 | \|#####################################\| Time: 0:00:00 NOTE: Upgraded | 3293 | . |
2895 | source extracted to /home/scottrif/poky/build/workspace/sources/nano | 3294 | . |
2896 | NOTE: New recipe is | 3295 | . |
2897 | /home/scottrif/poky/build/workspace/recipes/nano/nano_2.9.3.bb | 3296 | NOTE: Executing SetScene Tasks |
3297 | NOTE: Executing RunQueue Tasks | ||
3298 | NOTE: Tasks Summary: Attempted 74 tasks of which 72 didn't need to be rerun and all succeeded. | ||
3299 | Adding changed files: 100% |#####################################| Time: 0:00:00 | ||
3300 | NOTE: Upgraded source extracted to /home/scottrif/poky/build/workspace/sources/nano | ||
3301 | NOTE: New recipe is /home/scottrif/poky/build/workspace/recipes/nano/nano_2.9.3.bb | ||
3302 | |||
2898 | Continuing with this example, you can use ``devtool build`` to build the | 3303 | Continuing with this example, you can use ``devtool build`` to build the |
2899 | newly upgraded recipe: $ devtool build nano NOTE: Starting bitbake | 3304 | newly upgraded recipe: |
2900 | server... Loading cache: 100% | 3305 | :: |
2901 | \|################################################################################################\| | 3306 | |
2902 | Time: 0:00:01 Loaded 2040 entries from dependency cache. Parsing | 3307 | $ devtool build nano |
2903 | recipes: 100% | 3308 | NOTE: Starting bitbake server... |
2904 | \|##############################################################################################\| | 3309 | Loading cache: 100% |################################################################################################| Time: 0:00:01 |
2905 | Time: 0:00:00 Parsing of 1432 .bb files complete (1431 cached, 1 | 3310 | Loaded 2040 entries from dependency cache. |
2906 | parsed). 2041 targets, 56 skipped, 0 masked, 0 errors. NOTE: Resolving | 3311 | Parsing recipes: 100% |##############################################################################################| Time: 0:00:00 |
2907 | any missing task queue dependencies . . . NOTE: Executing SetScene Tasks | 3312 | Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors. |
2908 | NOTE: Executing RunQueue Tasks NOTE: nano: compiling from external | 3313 | NOTE: Resolving any missing task queue dependencies |
2909 | source tree /home/scottrif/poky/build/workspace/sources/nano NOTE: Tasks | 3314 | . |
2910 | Summary: Attempted 520 tasks of which 304 didn't need to be rerun and | 3315 | . |
2911 | all succeeded. Within the ``devtool upgrade`` workflow, opportunity | 3316 | . |
3317 | NOTE: Executing SetScene Tasks | ||
3318 | NOTE: Executing RunQueue Tasks | ||
3319 | NOTE: nano: compiling from external source tree /home/scottrif/poky/build/workspace/sources/nano | ||
3320 | NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded. | ||
3321 | |||
3322 | Within the ``devtool upgrade`` workflow, opportunity | ||
2912 | exists to deploy and test your rebuilt software. For this example, | 3323 | exists to deploy and test your rebuilt software. For this example, |
2913 | however, running ``devtool finish`` cleans up the workspace once the | 3324 | however, running ``devtool finish`` cleans up the workspace once the |
2914 | source in your workspace is clean. This usually means using Git to stage | 3325 | source in your workspace is clean. This usually means using Git to stage |
@@ -2916,22 +3327,23 @@ and submit commits for the changes generated by the upgrade process. | |||
2916 | 3327 | ||
2917 | Once the tree is clean, you can clean things up in this example with the | 3328 | Once the tree is clean, you can clean things up in this example with the |
2918 | following command from the ``${BUILDDIR}/workspace/sources/nano`` | 3329 | following command from the ``${BUILDDIR}/workspace/sources/nano`` |
2919 | directory: $ devtool finish nano meta-oe NOTE: Starting bitbake | 3330 | directory: |
2920 | server... Loading cache: 100% | 3331 | :: |
2921 | \|################################################################################################\| | 3332 | |
2922 | Time: 0:00:00 Loaded 2040 entries from dependency cache. Parsing | 3333 | $ devtool finish nano meta-oe |
2923 | recipes: 100% | 3334 | NOTE: Starting bitbake server... |
2924 | \|##############################################################################################\| | 3335 | Loading cache: 100% |################################################################################################| Time: 0:00:00 |
2925 | Time: 0:00:01 Parsing of 1432 .bb files complete (1431 cached, 1 | 3336 | Loaded 2040 entries from dependency cache. |
2926 | parsed). 2041 targets, 56 skipped, 0 masked, 0 errors. NOTE: Adding new | 3337 | Parsing recipes: 100% |##############################################################################################| Time: 0:00:01 |
2927 | patch 0001-nano.bb-Stuff-I-changed-when-upgrading-nano.bb.patch NOTE: | 3338 | Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors. |
2928 | Updating recipe nano_2.9.3.bb NOTE: Removing file | 3339 | NOTE: Adding new patch 0001-nano.bb-Stuff-I-changed-when-upgrading-nano.bb.patch |
2929 | /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb | 3340 | NOTE: Updating recipe nano_2.9.3.bb |
2930 | NOTE: Moving recipe file to | 3341 | NOTE: Removing file /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb |
2931 | /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano NOTE: | 3342 | NOTE: Moving recipe file to /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano |
2932 | Leaving source tree /home/scottrif/poky/build/workspace/sources/nano | 3343 | NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/nano as-is; if you no longer need it then please delete it manually |
2933 | as-is; if you no longer need it then please delete it manually Using the | 3344 | |
2934 | ``devtool finish`` command cleans up the workspace and creates a patch | 3345 | |
3346 | Using the ``devtool finish`` command cleans up the workspace and creates a patch | ||
2935 | file based on your commits. The tool puts all patch files back into the | 3347 | file based on your commits. The tool puts all patch files back into the |
2936 | source directory in a sub-directory named ``nano`` in this case. | 3348 | source directory in a sub-directory named ``nano`` in this case. |
2937 | 3349 | ||
@@ -2961,7 +3373,7 @@ To manually upgrade recipe versions, follow these general steps: | |||
2961 | changes appropriately. If the version is not part of the recipe name, | 3373 | changes appropriately. If the version is not part of the recipe name, |
2962 | change the value as it is set for ``PV`` within the recipe itself. | 3374 | change the value as it is set for ``PV`` within the recipe itself. |
2963 | 3375 | ||
2964 | 2. *Update ``SRCREV`` if Needed:* If the source code your recipe builds | 3376 | 2. Update ``SRCREV`` if Needed: If the source code your recipe builds |
2965 | is fetched from Git or some other version control system, update | 3377 | is fetched from Git or some other version control system, update |
2966 | :term:`SRCREV` to point to the | 3378 | :term:`SRCREV` to point to the |
2967 | commit hash that matches the new version. | 3379 | commit hash that matches the new version. |
@@ -3026,8 +3438,12 @@ build packages is available in the Build Directory as defined by the | |||
3026 | :term:`S` variable. Below is the default | 3438 | :term:`S` variable. Below is the default |
3027 | value for the ``S`` variable as defined in the | 3439 | value for the ``S`` variable as defined in the |
3028 | ``meta/conf/bitbake.conf`` configuration file in the | 3440 | ``meta/conf/bitbake.conf`` configuration file in the |
3029 | :term:`Source Directory`: S = | 3441 | :term:`Source Directory`: |
3030 | "${WORKDIR}/${BP}" You should be aware that many recipes override the | 3442 | :: |
3443 | |||
3444 | S = "${WORKDIR}/${BP}" | ||
3445 | |||
3446 | You should be aware that many recipes override the | ||
3031 | ``S`` variable. For example, recipes that fetch their source from Git | 3447 | ``S`` variable. For example, recipes that fetch their source from Git |
3032 | usually set ``S`` to ``${WORKDIR}/git``. | 3448 | usually set ``S`` to ``${WORKDIR}/git``. |
3033 | 3449 | ||
@@ -3040,7 +3456,7 @@ usually set ``S`` to ``${WORKDIR}/git``. | |||
3040 | :: | 3456 | :: |
3041 | 3457 | ||
3042 | BP = "${BPN}-${PV}" | 3458 | BP = "${BPN}-${PV}" |
3043 | 3459 | ||
3044 | 3460 | ||
3045 | The path to the work directory for the recipe | 3461 | The path to the work directory for the recipe |
3046 | (:term:`WORKDIR`) is defined as | 3462 | (:term:`WORKDIR`) is defined as |
@@ -3069,7 +3485,9 @@ As an example, assume a Source Directory top-level folder named | |||
3069 | ``qemux86-poky-linux`` machine target system. Furthermore, suppose your | 3485 | ``qemux86-poky-linux`` machine target system. Furthermore, suppose your |
3070 | recipe is named ``foo_1.3.0.bb``. In this case, the work directory the | 3486 | recipe is named ``foo_1.3.0.bb``. In this case, the work directory the |
3071 | build system uses to build the package would be as follows: | 3487 | build system uses to build the package would be as follows: |
3072 | poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 | 3488 | :: |
3489 | |||
3490 | poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 | ||
3073 | 3491 | ||
3074 | .. _using-a-quilt-workflow: | 3492 | .. _using-a-quilt-workflow: |
3075 | 3493 | ||
@@ -3110,20 +3528,29 @@ Follow these general steps: | |||
3110 | 3528 | ||
3111 | 3. *Create a New Patch:* Before modifying source code, you need to | 3529 | 3. *Create a New Patch:* Before modifying source code, you need to |
3112 | create a new patch. To create a new patch file, use ``quilt new`` as | 3530 | create a new patch. To create a new patch file, use ``quilt new`` as |
3113 | below: $ quilt new my_changes.patch | 3531 | below: |
3532 | :; | ||
3533 | |||
3534 | $ quilt new my_changes.patch | ||
3114 | 3535 | ||
3115 | 4. *Notify Quilt and Add Files:* After creating the patch, you need to | 3536 | 4. *Notify Quilt and Add Files:* After creating the patch, you need to |
3116 | notify Quilt about the files you plan to edit. You notify Quilt by | 3537 | notify Quilt about the files you plan to edit. You notify Quilt by |
3117 | adding the files to the patch you just created: $ quilt add file1.c | 3538 | adding the files to the patch you just created: |
3118 | file2.c file3.c | 3539 | :: |
3540 | |||
3541 | $ quilt add file1.c file2.c file3.c | ||
3119 | 3542 | ||
3120 | 5. *Edit the Files:* Make your changes in the source code to the files | 3543 | 5. *Edit the Files:* Make your changes in the source code to the files |
3121 | you added to the patch. | 3544 | you added to the patch. |
3122 | 3545 | ||
3123 | 6. *Test Your Changes:* Once you have modified the source code, the | 3546 | 6. *Test Your Changes:* Once you have modified the source code, the |
3124 | easiest way to test your changes is by calling the ``do_compile`` | 3547 | easiest way to test your changes is by calling the ``do_compile`` |
3125 | task as shown in the following example: $ bitbake -c compile -f | 3548 | task as shown in the following example: |
3126 | package The ``-f`` or ``--force`` option forces the specified task to | 3549 | :: |
3550 | |||
3551 | $ bitbake -c compile -f package | ||
3552 | |||
3553 | The ``-f`` or ``--force`` option forces the specified task to | ||
3127 | execute. If you find problems with your code, you can just keep | 3554 | execute. If you find problems with your code, you can just keep |
3128 | editing and re-testing iteratively until things work as expected. | 3555 | editing and re-testing iteratively until things work as expected. |
3129 | 3556 | ||
@@ -3148,7 +3575,12 @@ Follow these general steps: | |||
3148 | 3575 | ||
3149 | 7. *Generate the Patch:* Once your changes work as expected, you need to | 3576 | 7. *Generate the Patch:* Once your changes work as expected, you need to |
3150 | use Quilt to generate the final patch that contains all your | 3577 | use Quilt to generate the final patch that contains all your |
3151 | modifications. $ quilt refresh At this point, the | 3578 | modifications. |
3579 | :: | ||
3580 | |||
3581 | $ quilt refresh | ||
3582 | |||
3583 | At this point, the | ||
3152 | ``my_changes.patch`` file has all your edits made to the ``file1.c``, | 3584 | ``my_changes.patch`` file has all your edits made to the ``file1.c``, |
3153 | ``file2.c``, and ``file3.c`` files. | 3585 | ``file2.c``, and ``file3.c`` files. |
3154 | 3586 | ||
@@ -3160,8 +3592,10 @@ Follow these general steps: | |||
3160 | that holds the recipe (``.bb``) file or the append (``.bbappend``) | 3592 | that holds the recipe (``.bb``) file or the append (``.bbappend``) |
3161 | file. Placing the patch here guarantees that the OpenEmbedded build | 3593 | file. Placing the patch here guarantees that the OpenEmbedded build |
3162 | system will find the patch. Next, add the patch into the ``SRC_URI`` | 3594 | system will find the patch. Next, add the patch into the ``SRC_URI`` |
3163 | of the recipe. Here is an example: SRC_URI += | 3595 | of the recipe. Here is an example: |
3164 | "file://my_changes.patch" | 3596 | :: |
3597 | |||
3598 | SRC_URI += "file://my_changes.patch" | ||
3165 | 3599 | ||
3166 | .. _platdev-appdev-devshell: | 3600 | .. _platdev-appdev-devshell: |
3167 | 3601 | ||
@@ -3182,7 +3616,10 @@ this way can be helpful when debugging a build or preparing software to | |||
3182 | be used with the OpenEmbedded build system. | 3616 | be used with the OpenEmbedded build system. |
3183 | 3617 | ||
3184 | Following is an example that uses ``devshell`` on a target named | 3618 | Following is an example that uses ``devshell`` on a target named |
3185 | ``matchbox-desktop``: $ bitbake matchbox-desktop -c devshell | 3619 | ``matchbox-desktop``: |
3620 | :: | ||
3621 | |||
3622 | $ bitbake matchbox-desktop -c devshell | ||
3186 | 3623 | ||
3187 | This command spawns a terminal with a shell prompt within the | 3624 | This command spawns a terminal with a shell prompt within the |
3188 | OpenEmbedded build environment. The | 3625 | OpenEmbedded build environment. The |
@@ -3209,7 +3646,10 @@ corresponding ``run.*`` script in the | |||
3209 | directory (e.g., ``run.do_configure.``\ pid). If a task's script does | 3646 | directory (e.g., ``run.do_configure.``\ pid). If a task's script does |
3210 | not exist, which would be the case if the task was skipped by way of the | 3647 | not exist, which would be the case if the task was skipped by way of the |
3211 | sstate cache, you can create the task by first running it outside of the | 3648 | sstate cache, you can create the task by first running it outside of the |
3212 | ``devshell``: $ bitbake -c task | 3649 | ``devshell``: |
3650 | :: | ||
3651 | |||
3652 | $ bitbake -c task | ||
3213 | 3653 | ||
3214 | .. note:: | 3654 | .. note:: |
3215 | 3655 | ||
@@ -3256,18 +3696,31 @@ specified target. Then a new terminal is opened. Additionally, key | |||
3256 | Python objects and code are available in the same way they are to | 3696 | Python objects and code are available in the same way they are to |
3257 | BitBake tasks, in particular, the data store 'd'. So, commands such as | 3697 | BitBake tasks, in particular, the data store 'd'. So, commands such as |
3258 | the following are useful when exploring the data store and running | 3698 | the following are useful when exploring the data store and running |
3259 | functions: pydevshell> d.getVar("STAGING_DIR") | 3699 | functions: |
3260 | '/media/build1/poky/build/tmp/sysroots' pydevshell> | 3700 | :: |
3261 | d.getVar("STAGING_DIR") '${TMPDIR}/sysroots' pydevshell> d.setVar("FOO", | 3701 | |
3262 | "bar") pydevshell> d.getVar("FOO") 'bar' pydevshell> d.delVar("FOO") | 3702 | pydevshell> d.getVar("STAGING_DIR") |
3263 | pydevshell> d.getVar("FOO") pydevshell> bb.build.exec_func("do_unpack", | 3703 | '/media/build1/poky/build/tmp/sysroots' |
3264 | d) pydevshell> The commands execute just as if the OpenEmbedded build | 3704 | pydevshell> d.getVar("STAGING_DIR") |
3705 | '${TMPDIR}/sysroots' | ||
3706 | pydevshell> d.setVar("FOO", "bar") | ||
3707 | pydevshell> d.getVar("FOO") | ||
3708 | 'bar' | ||
3709 | pydevshell> d.delVar("FOO") | ||
3710 | pydevshell> d.getVar("FOO") | ||
3711 | pydevshell> bb.build.exec_func("do_unpack", d) | ||
3712 | pydevshell> | ||
3713 | |||
3714 | The commands execute just as if the OpenEmbedded build | ||
3265 | system were executing them. Consequently, working this way can be | 3715 | system were executing them. Consequently, working this way can be |
3266 | helpful when debugging a build or preparing software to be used with the | 3716 | helpful when debugging a build or preparing software to be used with the |
3267 | OpenEmbedded build system. | 3717 | OpenEmbedded build system. |
3268 | 3718 | ||
3269 | Following is an example that uses ``devpyshell`` on a target named | 3719 | Following is an example that uses ``devpyshell`` on a target named |
3270 | ``matchbox-desktop``: $ bitbake matchbox-desktop -c devpyshell | 3720 | ``matchbox-desktop``: |
3721 | :: | ||
3722 | |||
3723 | $ bitbake matchbox-desktop -c devpyshell | ||
3271 | 3724 | ||
3272 | This command spawns a terminal and places you in an interactive Python | 3725 | This command spawns a terminal and places you in an interactive Python |
3273 | interpreter within the OpenEmbedded build environment. The | 3726 | interpreter within the OpenEmbedded build environment. The |
@@ -3301,25 +3754,22 @@ build host running Linux. | |||
3301 | .. note:: | 3754 | .. note:: |
3302 | 3755 | ||
3303 | - For information on how to build an image using | 3756 | - For information on how to build an image using |
3304 | `Toaster <&YOCTO_DOCS_REF_URL;#toaster-term>`__, see the `Toaster | 3757 | :term:`Toaster`, see the |
3305 | User Manual <&YOCTO_DOCS_TOAST_URL;>`__. | 3758 | :doc:`../toaster-manual/toaster-manual`. |
3306 | 3759 | ||
3307 | - For information on how to use ``devtool`` to build images, see the | 3760 | - For information on how to use ``devtool`` to build images, see the |
3308 | "`Using ``devtool`` in Your SDK | 3761 | ":ref:`sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow`" |
3309 | Workflow <&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow>`__" | ||
3310 | section in the Yocto Project Application Development and the | 3762 | section in the Yocto Project Application Development and the |
3311 | Extensible Software Development Kit (eSDK) manual. | 3763 | Extensible Software Development Kit (eSDK) manual. |
3312 | 3764 | ||
3313 | - For a quick example on how to build an image using the | 3765 | - For a quick example on how to build an image using the |
3314 | OpenEmbedded build system, see the `Yocto Project Quick | 3766 | OpenEmbedded build system, see the |
3315 | Build <&YOCTO_DOCS_BRIEF_URL;>`__ document. | 3767 | :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. |
3316 | 3768 | ||
3317 | The build process creates an entire Linux distribution from source and | 3769 | The build process creates an entire Linux distribution from source and |
3318 | places it in your | 3770 | places it in your :term:`Build Directory` under |
3319 | :term:`Build Directory` under | ||
3320 | ``tmp/deploy/images``. For detailed information on the build process | 3771 | ``tmp/deploy/images``. For detailed information on the build process |
3321 | using BitBake, see the | 3772 | using BitBake, see the ":ref:`images-dev-environment`" section in the |
3322 | "`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" section in the | ||
3323 | Yocto Project Overview and Concepts Manual. | 3773 | Yocto Project Overview and Concepts Manual. |
3324 | 3774 | ||
3325 | The following figure and list overviews the build process: | 3775 | The following figure and list overviews the build process: |
@@ -3334,8 +3784,10 @@ The following figure and list overviews the build process: | |||
3334 | 3784 | ||
3335 | 2. *Initialize the Build Environment:* Initialize the build environment | 3785 | 2. *Initialize the Build Environment:* Initialize the build environment |
3336 | by sourcing the build environment script (i.e. | 3786 | by sourcing the build environment script (i.e. |
3337 | ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__): $ source | 3787 | :ref:`structure-core-script`): |
3338 | OE_INIT_FILE [build_dir] | 3788 | :: |
3789 | |||
3790 | $ source oe-init-build-env [build_dir] | ||
3339 | 3791 | ||
3340 | When you use the initialization script, the OpenEmbedded build system | 3792 | When you use the initialization script, the OpenEmbedded build system |
3341 | uses ``build`` as the default Build Directory in your current work | 3793 | uses ``build`` as the default Build Directory in your current work |
@@ -3355,7 +3807,7 @@ The following figure and list overviews the build process: | |||
3355 | qemuarm | 3807 | qemuarm |
3356 | target. | 3808 | target. |
3357 | 3809 | ||
3358 | 3. *Make Sure Your ``local.conf`` File is Correct:* Ensure the | 3810 | 3. Make Sure Your ``local.conf`` File is Correct: Ensure the |
3359 | ``conf/local.conf`` configuration file, which is found in the Build | 3811 | ``conf/local.conf`` configuration file, which is found in the Build |
3360 | Directory, is set up how you want it. This file defines many aspects | 3812 | Directory, is set up how you want it. This file defines many aspects |
3361 | of the build environment including the target machine architecture | 3813 | of the build environment including the target machine architecture |
@@ -3365,8 +3817,10 @@ The following figure and list overviews the build process: | |||
3365 | and a centralized tarball download directory through the | 3817 | and a centralized tarball download directory through the |
3366 | :term:`DL_DIR` variable. | 3818 | :term:`DL_DIR` variable. |
3367 | 3819 | ||
3368 | 4. *Build the Image:* Build the image using the ``bitbake`` command: $ | 3820 | 4. *Build the Image:* Build the image using the ``bitbake`` command: |
3369 | bitbake target | 3821 | :: |
3822 | |||
3823 | $ bitbake target | ||
3370 | 3824 | ||
3371 | .. note:: | 3825 | .. note:: |
3372 | 3826 | ||
@@ -3385,13 +3839,17 @@ The following figure and list overviews the build process: | |||
3385 | Project Reference Manual. | 3839 | Project Reference Manual. |
3386 | 3840 | ||
3387 | As an example, the following command builds the | 3841 | As an example, the following command builds the |
3388 | ``core-image-minimal`` image: $ bitbake core-image-minimal Once an | 3842 | ``core-image-minimal`` image: |
3843 | :: | ||
3844 | |||
3845 | $ bitbake core-image-minimal | ||
3846 | |||
3847 | Once an | ||
3389 | image has been built, it often needs to be installed. The images and | 3848 | image has been built, it often needs to be installed. The images and |
3390 | kernels built by the OpenEmbedded build system are placed in the | 3849 | kernels built by the OpenEmbedded build system are placed in the |
3391 | Build Directory in ``tmp/deploy/images``. For information on how to | 3850 | Build Directory in ``tmp/deploy/images``. For information on how to |
3392 | run pre-built images such as ``qemux86`` and ``qemuarm``, see the | 3851 | run pre-built images such as ``qemux86`` and ``qemuarm``, see the |
3393 | `Yocto Project Application Development and the Extensible Software | 3852 | :doc:`../sdk-manual/sdk-manual` manual. For |
3394 | Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual. For | ||
3395 | information about how to install these images, see the documentation | 3853 | information about how to install these images, see the documentation |
3396 | for your particular board or machine. | 3854 | for your particular board or machine. |
3397 | 3855 | ||
@@ -3438,8 +3896,11 @@ Follow these steps to set up and execute multiple configuration builds: | |||
3438 | 3896 | ||
3439 | Here is an example showing the minimal statements needed in a | 3897 | Here is an example showing the minimal statements needed in a |
3440 | configuration file for a "qemux86" target whose temporary build | 3898 | configuration file for a "qemux86" target whose temporary build |
3441 | directory is ``tmpmultix86``: MACHINE="qemux86" | 3899 | directory is ``tmpmultix86``: |
3442 | TMPDIR="${TOPDIR}/tmpmultix86" | 3900 | :: |
3901 | |||
3902 | MACHINE = "qemux86" | ||
3903 | TMPDIR = "${TOPDIR}/tmpmultix86" | ||
3443 | 3904 | ||
3444 | The location for these multiconfig configuration files is specific. | 3905 | The location for these multiconfig configuration files is specific. |
3445 | They must reside in the current build directory in a sub-directory of | 3906 | They must reside in the current build directory in a sub-directory of |
@@ -3462,7 +3923,9 @@ Follow these steps to set up and execute multiple configuration builds: | |||
3462 | each multiconfig. Continuing with the example from the previous | 3923 | each multiconfig. Continuing with the example from the previous |
3463 | figure, the ``BBMULTICONFIG`` variable needs to enable two | 3924 | figure, the ``BBMULTICONFIG`` variable needs to enable two |
3464 | multiconfigs: "x86" and "arm" by specifying each configuration file: | 3925 | multiconfigs: "x86" and "arm" by specifying each configuration file: |
3465 | BBMULTICONFIG = "x86 arm" | 3926 | :: |
3927 | |||
3928 | BBMULTICONFIG = "x86 arm" | ||
3466 | 3929 | ||
3467 | .. note:: | 3930 | .. note:: |
3468 | 3931 | ||
@@ -3475,10 +3938,16 @@ Follow these steps to set up and execute multiple configuration builds: | |||
3475 | with "". | 3938 | with "". |
3476 | 3939 | ||
3477 | - *Launch BitBake*: Use the following BitBake command form to launch | 3940 | - *Launch BitBake*: Use the following BitBake command form to launch |
3478 | the multiple configuration build: $ bitbake | 3941 | the multiple configuration build: |
3479 | [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ] For | 3942 | :: |
3480 | the example in this section, the following command applies: $ bitbake | 3943 | |
3481 | mc:x86:core-image-minimal mc:arm:core-image-sato mc::core-image-base | 3944 | $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ] |
3945 | |||
3946 | For the example in this section, the following command applies: | ||
3947 | :: | ||
3948 | |||
3949 | $ bitbake mc:x86:core-image-minimal mc:arm:core-image-sato mc::core-image-base | ||
3950 | |||
3482 | The previous BitBake command builds a ``core-image-minimal`` image | 3951 | The previous BitBake command builds a ``core-image-minimal`` image |
3483 | that is configured through the ``x86.conf`` configuration file, a | 3952 | that is configured through the ``x86.conf`` configuration file, a |
3484 | ``core-image-sato`` image that is configured through the ``arm.conf`` | 3953 | ``core-image-sato`` image that is configured through the ``arm.conf`` |
@@ -3512,19 +3981,29 @@ essentially that the | |||
3512 | 3981 | ||
3513 | To enable dependencies in a multiple configuration build, you must | 3982 | To enable dependencies in a multiple configuration build, you must |
3514 | declare the dependencies in the recipe using the following statement | 3983 | declare the dependencies in the recipe using the following statement |
3515 | form: task_or_package[mcdepends] = | 3984 | form: |
3516 | "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" | 3985 | :: |
3986 | |||
3987 | task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" | ||
3988 | |||
3517 | To better show how to use this statement, consider the example scenario | 3989 | To better show how to use this statement, consider the example scenario |
3518 | from the first paragraph of this section. The following statement needs | 3990 | from the first paragraph of this section. The following statement needs |
3519 | to be added to the recipe that builds the ``core-image-sato`` image: | 3991 | to be added to the recipe that builds the ``core-image-sato`` image: |
3520 | do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs" In this | 3992 | :: |
3521 | example, the from_multiconfig is "x86". The to_multiconfig is "arm". The | 3993 | |
3994 | do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs" | ||
3995 | |||
3996 | In this example, the from_multiconfig is "x86". The to_multiconfig is "arm". The | ||
3522 | task on which the ``do_image`` task in the recipe depends is the | 3997 | task on which the ``do_image`` task in the recipe depends is the |
3523 | ``do_rootfs`` task from the ``core-image-minimal`` recipe associated | 3998 | ``do_rootfs`` task from the ``core-image-minimal`` recipe associated |
3524 | with the "arm" multiconfig. | 3999 | with the "arm" multiconfig. |
3525 | 4000 | ||
3526 | Once you set up this dependency, you can build the "x86" multiconfig | 4001 | Once you set up this dependency, you can build the "x86" multiconfig |
3527 | using a BitBake command as follows: $ bitbake mc:x86:core-image-sato | 4002 | using a BitBake command as follows: |
4003 | :: | ||
4004 | |||
4005 | $ bitbake mc:x86:core-image-sato | ||
4006 | |||
3528 | This command executes all the tasks needed to create the | 4007 | This command executes all the tasks needed to create the |
3529 | ``core-image-sato`` image for the "x86" multiconfig. Because of the | 4008 | ``core-image-sato`` image for the "x86" multiconfig. Because of the |
3530 | dependency, BitBake also executes through the ``do_rootfs`` task for the | 4009 | dependency, BitBake also executes through the ``do_rootfs`` task for the |
@@ -3532,8 +4011,12 @@ dependency, BitBake also executes through the ``do_rootfs`` task for the | |||
3532 | 4011 | ||
3533 | Having a recipe depend on the root filesystem of another build might not | 4012 | Having a recipe depend on the root filesystem of another build might not |
3534 | seem that useful. Consider this change to the statement in the | 4013 | seem that useful. Consider this change to the statement in the |
3535 | ``core-image-sato`` recipe: do_image[mcdepends] = | 4014 | ``core-image-sato`` recipe: |
3536 | "mc:x86:arm:core-image-minimal:do_image" In this case, BitBake must | 4015 | :: |
4016 | |||
4017 | do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image" | ||
4018 | |||
4019 | In this case, BitBake must | ||
3537 | create the ``core-image-minimal`` image for the "arm" build since the | 4020 | create the ``core-image-minimal`` image for the "arm" build since the |
3538 | "x86" build depends on it. | 4021 | "x86" build depends on it. |
3539 | 4022 | ||
@@ -3642,8 +4125,8 @@ Yocto Project. | |||
3642 | 4125 | ||
3643 | .. _tiny-system-overview: | 4126 | .. _tiny-system-overview: |
3644 | 4127 | ||
3645 | Overview | 4128 | Tiny System Overview |
3646 | ~~~~~~~~ | 4129 | ~~~~~~~~~~~~~~~~~~~~ |
3647 | 4130 | ||
3648 | The following list presents the overall steps you need to consider and | 4131 | The following list presents the overall steps you need to consider and |
3649 | perform to create distributions with smaller root filesystems, achieve | 4132 | perform to create distributions with smaller root filesystems, achieve |
@@ -3746,9 +4229,8 @@ view file dependencies in a human-readable form: | |||
3746 | ``linux-yocto-3.8``, and so forth) in the ``scripts/kconfig`` | 4229 | ``linux-yocto-3.8``, and so forth) in the ``scripts/kconfig`` |
3747 | directory. | 4230 | directory. |
3748 | 4231 | ||
3749 | For more information on configuration fragments, see the "`Creating | 4232 | For more information on configuration fragments, see the |
3750 | Configuration | 4233 | ":ref:`creating-config-fragments`" |
3751 | Fragments <&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments>`__" | ||
3752 | section in the Yocto Project Linux Kernel Development Manual. | 4234 | section in the Yocto Project Linux Kernel Development Manual. |
3753 | 4235 | ||
3754 | - ``bitbake -u taskexp -g bitbake_target``: Using the BitBake command | 4236 | - ``bitbake -u taskexp -g bitbake_target``: Using the BitBake command |
@@ -3766,9 +4248,14 @@ happens, which changes the way you build them. You can also modify the | |||
3766 | filesystem itself or select a different filesystem. | 4248 | filesystem itself or select a different filesystem. |
3767 | 4249 | ||
3768 | First, find out what is hogging your root filesystem by running the | 4250 | First, find out what is hogging your root filesystem by running the |
3769 | ``dirsize.py`` script from your root directory: $ cd | 4251 | ``dirsize.py`` script from your root directory: |
3770 | root-directory-of-image $ dirsize.py 100000 > dirsize-100k.log $ cat | 4252 | :: |
3771 | dirsize-100k.log You can apply a filter to the script to ignore files | 4253 | |
4254 | $ cd root-directory-of-image | ||
4255 | $ dirsize.py 100000 > dirsize-100k.log | ||
4256 | $ cat dirsize-100k.log | ||
4257 | |||
4258 | You can apply a filter to the script to ignore files | ||
3772 | under a certain size. The previous example filters out any files below | 4259 | under a certain size. The previous example filters out any files below |
3773 | 100 Kbytes. The sizes reported by the tool are uncompressed, and thus | 4260 | 100 Kbytes. The sizes reported by the tool are uncompressed, and thus |
3774 | will be smaller by a relatively constant factor in a compressed root | 4261 | will be smaller by a relatively constant factor in a compressed root |
@@ -3777,8 +4264,13 @@ the root filesystem that take up large amounts of memory. | |||
3777 | 4264 | ||
3778 | You need to be sure that what you eliminate does not cripple the | 4265 | You need to be sure that what you eliminate does not cripple the |
3779 | functionality you need. One way to see how packages relate to each other | 4266 | functionality you need. One way to see how packages relate to each other |
3780 | is by using the Dependency Explorer UI with the BitBake command: $ cd | 4267 | is by using the Dependency Explorer UI with the BitBake command: |
3781 | image-directory $ bitbake -u taskexp -g image Use the interface to | 4268 | :: |
4269 | |||
4270 | $ cd image-directory | ||
4271 | $ bitbake -u taskexp -g image | ||
4272 | |||
4273 | Use the interface to | ||
3782 | select potential packages you wish to eliminate and see their dependency | 4274 | select potential packages you wish to eliminate and see their dependency |
3783 | relationships. | 4275 | relationships. |
3784 | 4276 | ||
@@ -3789,7 +4281,10 @@ instead of ``udev``. | |||
3789 | 4281 | ||
3790 | Use your ``local.conf`` file to make changes. For example, to eliminate | 4282 | Use your ``local.conf`` file to make changes. For example, to eliminate |
3791 | ``udev`` and ``glib``, set the following in the local configuration | 4283 | ``udev`` and ``glib``, set the following in the local configuration |
3792 | file: VIRTUAL-RUNTIME_dev_manager = "" | 4284 | file: |
4285 | :: | ||
4286 | |||
4287 | VIRTUAL-RUNTIME_dev_manager = "" | ||
3793 | 4288 | ||
3794 | Finally, you should consider exactly the type of root filesystem you | 4289 | Finally, you should consider exactly the type of root filesystem you |
3795 | need to meet your needs while also reducing its size. For example, | 4290 | need to meet your needs while also reducing its size. For example, |
@@ -3815,8 +4310,13 @@ building? Which drivers do you build by default? | |||
3815 | You can modify the kernel source if you want to help with boot time. | 4310 | You can modify the kernel source if you want to help with boot time. |
3816 | 4311 | ||
3817 | Run the ``ksize.py`` script from the top-level Linux build directory to | 4312 | Run the ``ksize.py`` script from the top-level Linux build directory to |
3818 | get an idea of what is making up the kernel: $ cd | 4313 | get an idea of what is making up the kernel: |
3819 | top-level-linux-build-directory $ ksize.py > ksize.log $ cat ksize.log | 4314 | :: |
4315 | |||
4316 | $ cd top-level-linux-build-directory | ||
4317 | $ ksize.py > ksize.log | ||
4318 | $ cat ksize.log | ||
4319 | |||
3820 | When you examine the log, you will see how much space is taken up with | 4320 | When you examine the log, you will see how much space is taken up with |
3821 | the built-in ``.o`` files for drivers, networking, core kernel files, | 4321 | the built-in ``.o`` files for drivers, networking, core kernel files, |
3822 | filesystem, sound, and so forth. The sizes reported by the tool are | 4322 | filesystem, sound, and so forth. The sizes reported by the tool are |
@@ -3825,7 +4325,12 @@ in a compressed kernel image. Look to reduce the areas that are large | |||
3825 | and taking up around the "90% rule." | 4325 | and taking up around the "90% rule." |
3826 | 4326 | ||
3827 | To examine, or drill down, into any particular area, use the ``-d`` | 4327 | To examine, or drill down, into any particular area, use the ``-d`` |
3828 | option with the script: $ ksize.py -d > ksize.log Using this option | 4328 | option with the script: |
4329 | :: | ||
4330 | |||
4331 | $ ksize.py -d > ksize.log | ||
4332 | |||
4333 | Using this option | ||
3829 | breaks out the individual file information for each area of the kernel | 4334 | breaks out the individual file information for each area of the kernel |
3830 | (e.g. drivers, networking, and so forth). | 4335 | (e.g. drivers, networking, and so forth). |
3831 | 4336 | ||
@@ -3975,12 +4480,19 @@ your tunings to best consider build times and package feed maintenance. | |||
3975 | machine-architecture dependent, make sure your recipe enables the | 4480 | machine-architecture dependent, make sure your recipe enables the |
3976 | "machine" package architecture through the | 4481 | "machine" package architecture through the |
3977 | :term:`MACHINE_ARCH` | 4482 | :term:`MACHINE_ARCH` |
3978 | variable: PACKAGE_ARCH = "${MACHINE_ARCH}" When you do not | 4483 | variable: |
4484 | :: | ||
4485 | |||
4486 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
4487 | |||
4488 | When you do not | ||
3979 | specifically enable a package architecture through the | 4489 | specifically enable a package architecture through the |
3980 | :term:`PACKAGE_ARCH`, The | 4490 | :term:`PACKAGE_ARCH`, The |
3981 | OpenEmbedded build system defaults to the | 4491 | OpenEmbedded build system defaults to the |
3982 | :term:`TUNE_PKGARCH` setting: | 4492 | :term:`TUNE_PKGARCH` setting: |
3983 | PACKAGE_ARCH = "${TUNE_PKGARCH}" | 4493 | :: |
4494 | |||
4495 | PACKAGE_ARCH = "${TUNE_PKGARCH}" | ||
3984 | 4496 | ||
3985 | - *Choose a Generic Tuning File if Possible:* Some tunes are more | 4497 | - *Choose a Generic Tuning File if Possible:* Some tunes are more |
3986 | generic and can run on multiple targets (e.g. an ``armv5`` set of | 4498 | generic and can run on multiple targets (e.g. an ``armv5`` set of |
@@ -4043,7 +4555,7 @@ your tunings to best consider build times and package feed maintenance. | |||
4043 | For such cases, you can use some tools to help you sort out the | 4555 | For such cases, you can use some tools to help you sort out the |
4044 | situation: | 4556 | situation: |
4045 | 4557 | ||
4046 | - *``sstate-diff-machines.sh``:* You can find this tool in the | 4558 | - *sstate-diff-machines.sh:* You can find this tool in the |
4047 | ``scripts`` directory of the Source Repositories. See the comments | 4559 | ``scripts`` directory of the Source Repositories. See the comments |
4048 | in the script for information on how to use the tool. | 4560 | in the script for information on how to use the tool. |
4049 | 4561 | ||
@@ -4078,12 +4590,18 @@ to do is inherit the | |||
4078 | and then set the | 4590 | and then set the |
4079 | :term:`EXTERNALSRC` variable to | 4591 | :term:`EXTERNALSRC` variable to |
4080 | point to your external source code. Here are the statements to put in | 4592 | point to your external source code. Here are the statements to put in |
4081 | your ``local.conf`` file: INHERIT += "externalsrc" | 4593 | your ``local.conf`` file: |
4082 | EXTERNALSRC_pn-myrecipe = "path-to-your-source-tree" | 4594 | :: |
4595 | |||
4596 | INHERIT += "externalsrc" | ||
4597 | EXTERNALSRC_pn-myrecipe = "path-to-your-source-tree" | ||
4083 | 4598 | ||
4084 | This next example shows how to accomplish the same thing by setting | 4599 | This next example shows how to accomplish the same thing by setting |
4085 | ``EXTERNALSRC`` in the recipe itself or in the recipe's append file: | 4600 | ``EXTERNALSRC`` in the recipe itself or in the recipe's append file: |
4086 | EXTERNALSRC = "path" EXTERNALSRC_BUILD = "path" | 4601 | :: |
4602 | |||
4603 | EXTERNALSRC = "path" | ||
4604 | EXTERNALSRC_BUILD = "path" | ||
4087 | 4605 | ||
4088 | .. note:: | 4606 | .. note:: |
4089 | 4607 | ||
@@ -4098,8 +4616,10 @@ directory separate from the external source directory as specified by | |||
4098 | to have the source built in the same directory in which it resides, or | 4616 | to have the source built in the same directory in which it resides, or |
4099 | some other nominated directory, you can set | 4617 | some other nominated directory, you can set |
4100 | :term:`EXTERNALSRC_BUILD` | 4618 | :term:`EXTERNALSRC_BUILD` |
4101 | to point to that directory: EXTERNALSRC_BUILD_pn-myrecipe = | 4619 | to point to that directory: |
4102 | "path-to-your-source-tree" | 4620 | :: |
4621 | |||
4622 | EXTERNALSRC_BUILD_pn-myrecipe = "path-to-your-source-tree" | ||
4103 | 4623 | ||
4104 | Replicating a Build Offline | 4624 | Replicating a Build Offline |
4105 | --------------------------- | 4625 | --------------------------- |
@@ -4120,8 +4640,13 @@ Follow these steps to populate your Downloads directory: | |||
4120 | an empty location or one that does not yet exist. | 4640 | an empty location or one that does not yet exist. |
4121 | 4641 | ||
4122 | 2. *Generate Tarballs of the Source Git Repositories:* Edit your | 4642 | 2. *Generate Tarballs of the Source Git Repositories:* Edit your |
4123 | ``local.conf`` configuration file as follows: DL_DIR = | 4643 | ``local.conf`` configuration file as follows: |
4124 | "/home/your-download-dir/" BB_GENERATE_MIRROR_TARBALLS = "1" During | 4644 | :: |
4645 | |||
4646 | DL_DIR = "/home/your-download-dir/" | ||
4647 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
4648 | |||
4649 | During | ||
4125 | the fetch process in the next step, BitBake gathers the source files | 4650 | the fetch process in the next step, BitBake gathers the source files |
4126 | and creates tarballs in the directory pointed to by ``DL_DIR``. See | 4651 | and creates tarballs in the directory pointed to by ``DL_DIR``. See |
4127 | the | 4652 | the |
@@ -4129,8 +4654,12 @@ Follow these steps to populate your Downloads directory: | |||
4129 | variable for more information. | 4654 | variable for more information. |
4130 | 4655 | ||
4131 | 3. *Populate Your Downloads Directory Without Building:* Use BitBake to | 4656 | 3. *Populate Your Downloads Directory Without Building:* Use BitBake to |
4132 | fetch your sources but inhibit the build: $ bitbake target | 4657 | fetch your sources but inhibit the build: |
4133 | --runonly=fetch The downloads directory (i.e. ``${DL_DIR}``) now has | 4658 | :: |
4659 | |||
4660 | $ bitbake target --runonly=fetch | ||
4661 | |||
4662 | The downloads directory (i.e. ``${DL_DIR}``) now has | ||
4134 | a "snapshot" of the source files in the form of tarballs, which can | 4663 | a "snapshot" of the source files in the form of tarballs, which can |
4135 | be used for the build. | 4664 | be used for the build. |
4136 | 4665 | ||
@@ -4154,9 +4683,14 @@ directory: | |||
4154 | :ref:`own-mirrors <ref-classes-own-mirrors>` | 4683 | :ref:`own-mirrors <ref-classes-own-mirrors>` |
4155 | class, and use the | 4684 | class, and use the |
4156 | :term:`bitbake:BB_NO_NETWORK` | 4685 | :term:`bitbake:BB_NO_NETWORK` |
4157 | variable to your ``local.conf``. SOURCE_MIRROR_URL ?= | 4686 | variable to your ``local.conf``. |
4158 | "file:///home/your-download-dir/" INHERIT += "own-mirrors" | 4687 | :: |
4159 | BB_NO_NETWORK = "1" The ``SOURCE_MIRROR_URL`` and ``own-mirror`` | 4688 | |
4689 | SOURCE_MIRROR_URL ?= "file:///home/your-download-dir/" | ||
4690 | INHERIT += "own-mirrors" | ||
4691 | BB_NO_NETWORK = "1" | ||
4692 | |||
4693 | The ``SOURCE_MIRROR_URL`` and ``own-mirror`` | ||
4160 | class set up the system to use the downloads directory as your "own | 4694 | class set up the system to use the downloads directory as your "own |
4161 | mirror". Using the ``BB_NO_NETWORK`` variable makes sure that | 4695 | mirror". Using the ``BB_NO_NETWORK`` variable makes sure that |
4162 | BitBake's fetching process in step 3 stays local, which means files | 4696 | BitBake's fetching process in step 3 stays local, which means files |
@@ -4167,8 +4701,12 @@ directory: | |||
4167 | ``${``\ :term:`TMPDIR`\ ``}`` | 4701 | ``${``\ :term:`TMPDIR`\ ``}`` |
4168 | directory or using a new :term:`Build Directory`. | 4702 | directory or using a new :term:`Build Directory`. |
4169 | 4703 | ||
4170 | 3. *Build Your Target:* Use BitBake to build your target: $ bitbake | 4704 | 3. *Build Your Target:* Use BitBake to build your target: |
4171 | target The build completes using the known local "snapshot" of source | 4705 | :: |
4706 | |||
4707 | $ bitbake target | ||
4708 | |||
4709 | The build completes using the known local "snapshot" of source | ||
4172 | files from your mirror. The resulting tarballs for your "snapshot" of | 4710 | files from your mirror. The resulting tarballs for your "snapshot" of |
4173 | source files are in the downloads directory. | 4711 | source files are in the downloads directory. |
4174 | 4712 | ||
@@ -4293,8 +4831,12 @@ that can help you speed up the build: | |||
4293 | - Disable static library generation for recipes derived from | 4831 | - Disable static library generation for recipes derived from |
4294 | ``autoconf`` or ``libtool``: Following is an example showing how to | 4832 | ``autoconf`` or ``libtool``: Following is an example showing how to |
4295 | disable static libraries and still provide an override to handle | 4833 | disable static libraries and still provide an override to handle |
4296 | exceptions: STATICLIBCONF = "--disable-static" | 4834 | exceptions: |
4297 | STATICLIBCONF_sqlite3-native = "" EXTRA_OECONF += "${STATICLIBCONF}" | 4835 | :: |
4836 | |||
4837 | STATICLIBCONF = "--disable-static" | ||
4838 | STATICLIBCONF_sqlite3-native = "" | ||
4839 | EXTRA_OECONF += "${STATICLIBCONF}" | ||
4298 | 4840 | ||
4299 | .. note:: | 4841 | .. note:: |
4300 | 4842 | ||
@@ -4349,28 +4891,42 @@ library files. | |||
4349 | . | 4891 | . |
4350 | 4892 | ||
4351 | Following is part of the BitBake configuration file, where you can see | 4893 | Following is part of the BitBake configuration file, where you can see |
4352 | how the static library files are defined: PACKAGE_BEFORE_PN ?= "" | 4894 | how the static library files are defined: |
4353 | PACKAGES = "${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale | 4895 | :: |
4354 | ${PACKAGE_BEFORE_PN} ${PN}" PACKAGES_DYNAMIC = "^${PN}-locale-.*" FILES | 4896 | |
4355 | = "" FILES_${PN} = "${bindir}/\* ${sbindir}/\* ${libexecdir}/\* | 4897 | PACKAGE_BEFORE_PN ?= "" |
4356 | ${libdir}/lib*${SOLIBS} \\ ${sysconfdir} ${sharedstatedir} | 4898 | PACKAGES = "${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}" |
4357 | ${localstatedir} \\ ${base_bindir}/\* ${base_sbindir}/\* \\ | 4899 | PACKAGES_DYNAMIC = "^${PN}-locale-.*" |
4358 | ${base_libdir}/*${SOLIBS} \\ ${base_prefix}/lib/udev/rules.d | 4900 | FILES = "" |
4359 | ${prefix}/lib/udev/rules.d \\ ${datadir}/${BPN} ${libdir}/${BPN}/\* \\ | 4901 | |
4360 | ${datadir}/pixmaps ${datadir}/applications \\ ${datadir}/idl | 4902 | FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \ |
4361 | ${datadir}/omf ${datadir}/sounds \\ ${libdir}/bonobo/servers" | 4903 | ${sysconfdir} ${sharedstatedir} ${localstatedir} \ |
4362 | FILES_${PN}-bin = "${bindir}/\* ${sbindir}/*" FILES_${PN}-doc = | 4904 | ${base_bindir}/* ${base_sbindir}/* \ |
4363 | "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \\ | 4905 | ${base_libdir}/*${SOLIBS} \ |
4364 | ${datadir}/gnome/help" SECTION_${PN}-doc = "doc" FILES_SOLIBSDEV ?= | 4906 | ${base_prefix}/lib/udev/rules.d ${prefix}/lib/udev/rules.d \ |
4365 | "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" | 4907 | ${datadir}/${BPN} ${libdir}/${BPN}/* \ |
4366 | FILES_${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \\ | 4908 | ${datadir}/pixmaps ${datadir}/applications \ |
4367 | ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \\ | 4909 | ${datadir}/idl ${datadir}/omf ${datadir}/sounds \ |
4368 | ${datadir}/aclocal ${base_libdir}/*.o \\ ${libdir}/${BPN}/*.la | 4910 | ${libdir}/bonobo/servers" |
4369 | ${base_libdir}/*.la" SECTION_${PN}-dev = "devel" ALLOW_EMPTY_${PN}-dev = | 4911 | |
4370 | "1" RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})" FILES_${PN}-staticdev | 4912 | FILES_${PN}-bin = "${bindir}/* ${sbindir}/*" |
4371 | = "${libdir}/*.a ${base_libdir}/*.a ${libdir}/${BPN}/*.a" | 4913 | |
4372 | SECTION_${PN}-staticdev = "devel" RDEPENDS_${PN}-staticdev = "${PN}-dev | 4914 | FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ |
4373 | (= ${EXTENDPKGV})" | 4915 | ${datadir}/gnome/help" |
4916 | SECTION_${PN}-doc = "doc" | ||
4917 | |||
4918 | FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" | ||
4919 | FILES_${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \ | ||
4920 | ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ | ||
4921 | ${datadir}/aclocal ${base_libdir}/*.o \ | ||
4922 | ${libdir}/${BPN}/*.la ${base_libdir}/*.la" | ||
4923 | SECTION_${PN}-dev = "devel" | ||
4924 | ALLOW_EMPTY_${PN}-dev = "1" | ||
4925 | RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})" | ||
4926 | |||
4927 | FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a ${libdir}/${BPN}/*.a" | ||
4928 | SECTION_${PN}-staticdev = "devel" | ||
4929 | RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})" | ||
4374 | 4930 | ||
4375 | .. _combining-multiple-versions-library-files-into-one-image: | 4931 | .. _combining-multiple-versions-library-files-into-one-image: |
4376 | 4932 | ||
@@ -4444,10 +5000,16 @@ After you have set up the recipes, you need to define the actual | |||
4444 | combination of multiple libraries you want to build. You accomplish this | 5000 | combination of multiple libraries you want to build. You accomplish this |
4445 | through your ``local.conf`` configuration file in the | 5001 | through your ``local.conf`` configuration file in the |
4446 | :term:`Build Directory`. An example | 5002 | :term:`Build Directory`. An example |
4447 | configuration would be as follows: MACHINE = "qemux86-64" require | 5003 | configuration would be as follows: |
4448 | conf/multilib.conf MULTILIBS = "multilib:lib32" | 5004 | :: |
4449 | DEFAULTTUNE_virtclass-multilib-lib32 = "x86" IMAGE_INSTALL_append = " | 5005 | |
4450 | lib32-glib-2.0" This example enables an additional library named | 5006 | MACHINE = "qemux86-64" |
5007 | require conf/multilib.conf | ||
5008 | MULTILIBS = "multilib:lib32" | ||
5009 | DEFAULTTUNE_virtclass-multilib-lib32 = "x86" | ||
5010 | IMAGE_INSTALL_append = "lib32-glib-2.0" | ||
5011 | |||
5012 | This example enables an additional library named | ||
4451 | ``lib32`` alongside the normal target packages. When combining these | 5013 | ``lib32`` alongside the normal target packages. When combining these |
4452 | "lib32" alternatives, the example uses "x86" for tuning. For information | 5014 | "lib32" alternatives, the example uses "x86" for tuning. For information |
4453 | on this particular tuning, see | 5015 | on this particular tuning, see |
@@ -4455,9 +5017,16 @@ on this particular tuning, see | |||
4455 | 5017 | ||
4456 | The example then includes ``lib32-glib-2.0`` in all the images, which | 5018 | The example then includes ``lib32-glib-2.0`` in all the images, which |
4457 | illustrates one method of including a multiple library dependency. You | 5019 | illustrates one method of including a multiple library dependency. You |
4458 | can use a normal image build to include this dependency, for example: $ | 5020 | can use a normal image build to include this dependency, for example: |
4459 | bitbake core-image-sato You can also build Multilib packages | 5021 | :: |
4460 | specifically with a command like this: $ bitbake lib32-glib-2.0 | 5022 | |
5023 | $ bitbake core-image-sato | ||
5024 | |||
5025 | You can also build Multilib packages | ||
5026 | specifically with a command like this: | ||
5027 | :: | ||
5028 | |||
5029 | $ bitbake lib32-glib-2.0 | ||
4461 | 5030 | ||
4462 | Additional Implementation Details | 5031 | Additional Implementation Details |
4463 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 5032 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
@@ -4538,12 +5107,21 @@ single recipe that loads one version of a library (e.g. ``clutter``), | |||
4538 | you provide multiple recipes that result in different versions of the | 5107 | you provide multiple recipes that result in different versions of the |
4539 | libraries you want. As an example, the following two recipes would allow | 5108 | libraries you want. As an example, the following two recipes would allow |
4540 | the two separate versions of the ``clutter`` library to co-exist on the | 5109 | the two separate versions of the ``clutter`` library to co-exist on the |
4541 | same system: clutter-1.6_1.6.20.bb clutter-1.8_1.8.4.bb Additionally, if | 5110 | same system: |
5111 | :: | ||
5112 | |||
5113 | clutter-1.6_1.6.20.bb | ||
5114 | clutter-1.8_1.8.4.bb | ||
5115 | |||
5116 | Additionally, if | ||
4542 | you have other recipes that depend on a given library, you need to use | 5117 | you have other recipes that depend on a given library, you need to use |
4543 | the :term:`DEPENDS` variable to | 5118 | the :term:`DEPENDS` variable to |
4544 | create the dependency. Continuing with the same example, if you want to | 5119 | create the dependency. Continuing with the same example, if you want to |
4545 | have a recipe depend on the 1.8 version of the ``clutter`` library, use | 5120 | have a recipe depend on the 1.8 version of the ``clutter`` library, use |
4546 | the following in your recipe: DEPENDS = "clutter-1.8" | 5121 | the following in your recipe: |
5122 | :: | ||
5123 | |||
5124 | DEPENDS = "clutter-1.8" | ||
4547 | 5125 | ||
4548 | Using x32 psABI | 5126 | Using x32 psABI |
4549 | =============== | 5127 | =============== |
@@ -4584,11 +5162,20 @@ follows: | |||
4584 | - Support for large images exists. | 5162 | - Support for large images exists. |
4585 | 5163 | ||
4586 | To use the x32 psABI, you need to edit your ``conf/local.conf`` | 5164 | To use the x32 psABI, you need to edit your ``conf/local.conf`` |
4587 | configuration file as follows: MACHINE = "qemux86-64" DEFAULTTUNE = | 5165 | configuration file as follows: |
4588 | "x86-64-x32" baselib = "${@d.getVar('BASE_LIB_tune-' + | 5166 | :: |
4589 | (d.getVar('DEFAULTTUNE') \\ or 'INVALID')) or 'lib'}" Once you have set | 5167 | |
5168 | MACHINE = "qemux86-64" | ||
5169 | DEFAULTTUNE = "x86-64-x32" | ||
5170 | baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE') \ | ||
5171 | or 'INVALID')) or 'lib'}" | ||
5172 | |||
5173 | Once you have set | ||
4590 | up your configuration file, use BitBake to build an image that supports | 5174 | up your configuration file, use BitBake to build an image that supports |
4591 | the x32 psABI. Here is an example: $ bitbake core-image-sato | 5175 | the x32 psABI. Here is an example: |
5176 | :: | ||
5177 | |||
5178 | $ bitbake core-image-sato | ||
4592 | 5179 | ||
4593 | Enabling GObject Introspection Support | 5180 | Enabling GObject Introspection Support |
4594 | ====================================== | 5181 | ====================================== |
@@ -4645,7 +5232,10 @@ library package involves the following: | |||
4645 | 3. Try to build the recipe. If you encounter build errors that look like | 5232 | 3. Try to build the recipe. If you encounter build errors that look like |
4646 | something is unable to find ``.so`` libraries, check where these | 5233 | something is unable to find ``.so`` libraries, check where these |
4647 | libraries are located in the source tree and add the following to the | 5234 | libraries are located in the source tree and add the following to the |
4648 | recipe: GIR_EXTRA_LIBS_PATH = "${B}/something/.libs" | 5235 | recipe: |
5236 | :: | ||
5237 | |||
5238 | GIR_EXTRA_LIBS_PATH = "${B}/something/.libs" | ||
4649 | 5239 | ||
4650 | .. note:: | 5240 | .. note:: |
4651 | 5241 | ||
@@ -4659,8 +5249,8 @@ library package involves the following: | |||
4659 | support in a package is not entirely standard, and thus breaks down | 5249 | support in a package is not entirely standard, and thus breaks down |
4660 | in a cross-compilation environment. For such cases, custom-made fixes | 5250 | in a cross-compilation environment. For such cases, custom-made fixes |
4661 | are needed. A good place to ask and receive help in these cases is | 5251 | are needed. A good place to ask and receive help in these cases is |
4662 | the `Yocto Project mailing | 5252 | the :ref:`Yocto Project mailing |
4663 | lists <&YOCTO_DOCS_REF_URL;#resources-mailinglist>`__. | 5253 | lists <resources-mailinglist>`. |
4664 | 5254 | ||
4665 | .. note:: | 5255 | .. note:: |
4666 | 5256 | ||
@@ -4677,14 +5267,20 @@ combination. If so, you can use either of the following methods to | |||
4677 | disable GIR file generations: | 5267 | disable GIR file generations: |
4678 | 5268 | ||
4679 | - Add the following to your distro configuration: | 5269 | - Add the following to your distro configuration: |
4680 | DISTRO_FEATURES_BACKFILL_CONSIDERED = "gobject-introspection-data" | 5270 | :: |
5271 | |||
5272 | DISTRO_FEATURES_BACKFILL_CONSIDERED = "gobject-introspection-data" | ||
5273 | |||
4681 | Adding this statement disables generating introspection data using | 5274 | Adding this statement disables generating introspection data using |
4682 | QEMU but will still enable building introspection tools and libraries | 5275 | QEMU but will still enable building introspection tools and libraries |
4683 | (i.e. building them does not require the use of QEMU). | 5276 | (i.e. building them does not require the use of QEMU). |
4684 | 5277 | ||
4685 | - Add the following to your machine configuration: | 5278 | - Add the following to your machine configuration: |
4686 | MACHINE_FEATURES_BACKFILL_CONSIDERED = "qemu-usermode" Adding this | 5279 | :: |
4687 | statement disables the use of QEMU when building packages for your | 5280 | |
5281 | MACHINE_FEATURES_BACKFILL_CONSIDERED = "qemu-usermode" | ||
5282 | |||
5283 | Adding this statement disables the use of QEMU when building packages for your | ||
4688 | machine. Currently, this feature is used only by introspection | 5284 | machine. Currently, this feature is used only by introspection |
4689 | recipes and has the same effect as the previously described option. | 5285 | recipes and has the same effect as the previously described option. |
4690 | 5286 | ||
@@ -4713,10 +5309,13 @@ working in an image: | |||
4713 | 5309 | ||
4714 | 3. Launch a Terminal and then start Python in the terminal. | 5310 | 3. Launch a Terminal and then start Python in the terminal. |
4715 | 5311 | ||
4716 | 4. Enter the following in the terminal: >>> from gi.repository import | 5312 | 4. Enter the following in the terminal: |
4717 | GLib >>> GLib.get_host_name() | 5313 | :: |
4718 | 5314 | ||
4719 | 5. For something a little more advanced, enter the following: | 5315 | >>> from gi.repository import GLib |
5316 | >>> GLib.get_host_name() | ||
5317 | |||
5318 | 5. For something a little more advanced, enter the following see: | ||
4720 | http://python-gtk-3-tutorial.readthedocs.org/en/latest/introduction.html | 5319 | http://python-gtk-3-tutorial.readthedocs.org/en/latest/introduction.html |
4721 | 5320 | ||
4722 | Known Issues | 5321 | Known Issues |
@@ -4848,8 +5447,7 @@ In order to use the Wic utility with the OpenEmbedded Build system, your | |||
4848 | system needs to meet the following requirements: | 5447 | system needs to meet the following requirements: |
4849 | 5448 | ||
4850 | - The Linux distribution on your development host must support the | 5449 | - The Linux distribution on your development host must support the |
4851 | Yocto Project. See the "`Supported Linux | 5450 | Yocto Project. See the ":ref:`detailed-supported-distros`" |
4852 | Distributions <&YOCTO_DOCS_REF_URL;#detailed-supported-distros>`__" | ||
4853 | section in the Yocto Project Reference Manual for the list of | 5451 | section in the Yocto Project Reference Manual for the list of |
4854 | distributions that support the Yocto Project. | 5452 | distributions that support the Yocto Project. |
4855 | 5453 | ||
@@ -4857,7 +5455,7 @@ system needs to meet the following requirements: | |||
4857 | your development host system. | 5455 | your development host system. |
4858 | 5456 | ||
4859 | - You must have sourced the build environment setup script (i.e. | 5457 | - You must have sourced the build environment setup script (i.e. |
4860 | ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__) found in the | 5458 | :ref:`structure-core-script`) found in the |
4861 | :term:`Build Directory`. | 5459 | :term:`Build Directory`. |
4862 | 5460 | ||
4863 | - You need to have the build artifacts already available, which | 5461 | - You need to have the build artifacts already available, which |
@@ -4874,10 +5472,8 @@ system needs to meet the following requirements: | |||
4874 | :term:`IMAGE_FSTYPES` | 5472 | :term:`IMAGE_FSTYPES` |
4875 | variable. | 5473 | variable. |
4876 | 5474 | ||
4877 | - Include the name of the `wic kickstart | 5475 | - Include the name of the :ref:`wic kickstart file <openembedded-kickstart-wks-reference>` |
4878 | file <&YOCTO_DOCS_REF_URL;#openembedded-kickstart-wks-reference>`__ | 5476 | as part of the :term:`WKS_FILE` variable |
4879 | as part of the :term:`WKS_FILE` | ||
4880 | variable | ||
4881 | 5477 | ||
4882 | .. _wic-getting-help: | 5478 | .. _wic-getting-help: |
4883 | 5479 | ||
@@ -4886,37 +5482,66 @@ Getting Help | |||
4886 | 5482 | ||
4887 | You can get general help for the ``wic`` command by entering the ``wic`` | 5483 | You can get general help for the ``wic`` command by entering the ``wic`` |
4888 | command by itself or by entering the command with a help argument as | 5484 | command by itself or by entering the command with a help argument as |
4889 | follows: $ wic -h $ wic --help $ wic help | 5485 | follows: |
5486 | :: | ||
5487 | |||
5488 | $ wic -h | ||
5489 | $ wic --help | ||
5490 | $ wic help | ||
4890 | 5491 | ||
4891 | Currently, Wic supports seven commands: ``cp``, ``create``, ``help``, | 5492 | Currently, Wic supports seven commands: ``cp``, ``create``, ``help``, |
4892 | ``list``, ``ls``, ``rm``, and ``write``. You can get help for all these | 5493 | ``list``, ``ls``, ``rm``, and ``write``. You can get help for all these |
4893 | commands except "help" by using the following form: $ wic help command | 5494 | commands except "help" by using the following form: |
5495 | :: | ||
5496 | |||
5497 | $ wic help command | ||
5498 | |||
4894 | For example, the following command returns help for the ``write`` | 5499 | For example, the following command returns help for the ``write`` |
4895 | command: $ wic help write | 5500 | command: |
5501 | :: | ||
5502 | |||
5503 | $ wic help write | ||
4896 | 5504 | ||
4897 | Wic supports help for three topics: ``overview``, ``plugins``, and | 5505 | Wic supports help for three topics: ``overview``, ``plugins``, and |
4898 | ``kickstart``. You can get help for any topic using the following form: | 5506 | ``kickstart``. You can get help for any topic using the following form: |
4899 | $ wic help topic For example, the following returns overview help for | 5507 | :: |
4900 | Wic: $ wic help overview | 5508 | |
5509 | $ wic help topic | ||
5510 | |||
5511 | For example, the following returns overview help for Wic: | ||
5512 | :: | ||
5513 | |||
5514 | $ wic help overview | ||
4901 | 5515 | ||
4902 | One additional level of help exists for Wic. You can get help on | 5516 | One additional level of help exists for Wic. You can get help on |
4903 | individual images through the ``list`` command. You can use the ``list`` | 5517 | individual images through the ``list`` command. You can use the ``list`` |
4904 | command to return the available Wic images as follows: $ wic list images | 5518 | command to return the available Wic images as follows: |
4905 | genericx86 Create an EFI disk image for genericx86\* beaglebone-yocto | 5519 | :: |
4906 | Create SD card image for Beaglebone edgerouter Create SD card image for | 5520 | |
4907 | Edgerouter qemux86-directdisk Create a qemu machine 'pcbios' direct disk | 5521 | $ wic list images |
4908 | image directdisk-gpt Create a 'pcbios' direct disk image mkefidisk | 5522 | genericx86 Create an EFI disk image for genericx86* |
4909 | Create an EFI disk image directdisk Create a 'pcbios' direct disk image | 5523 | beaglebone-yocto Create SD card image for Beaglebone |
4910 | systemd-bootdisk Create an EFI disk image with systemd-boot mkhybridiso | 5524 | edgerouter Create SD card image for Edgerouter |
4911 | Create a hybrid ISO image sdimage-bootpart Create SD card image with a | 5525 | qemux86-directdisk Create a qemu machine 'pcbios' direct disk image |
4912 | boot partition directdisk-multi-rootfs Create multi rootfs image using | 5526 | directdisk-gpt Create a 'pcbios' direct disk image |
4913 | rootfs plugin directdisk-bootloader-config Create a 'pcbios' direct disk | 5527 | mkefidisk Create an EFI disk image |
4914 | image with custom bootloader config Once you know the list of available | 5528 | directdisk Create a 'pcbios' direct disk image |
5529 | systemd-bootdisk Create an EFI disk image with systemd-boot | ||
5530 | mkhybridiso Create a hybrid ISO image | ||
5531 | sdimage-bootpart Create SD card image with a boot partition | ||
5532 | directdisk-multi-rootfs Create multi rootfs image using rootfs plugin | ||
5533 | directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config | ||
5534 | |||
5535 | Once you know the list of available | ||
4915 | Wic images, you can use ``help`` with the command to get help on a | 5536 | Wic images, you can use ``help`` with the command to get help on a |
4916 | particular image. For example, the following command returns help on the | 5537 | particular image. For example, the following command returns help on the |
4917 | "beaglebone-yocto" image: $ wic list beaglebone-yocto help Creates a | 5538 | "beaglebone-yocto" image: |
4918 | partitioned SD card image for Beaglebone. Boot files are located in the | 5539 | :: |
4919 | first vfat partition. | 5540 | |
5541 | $ wic list beaglebone-yocto help | ||
5542 | |||
5543 | Creates a partitioned SD card image for Beaglebone. | ||
5544 | Boot files are located in the first vfat partition. | ||
4920 | 5545 | ||
4921 | Operational Modes | 5546 | Operational Modes |
4922 | ----------------- | 5547 | ----------------- |
@@ -4948,26 +5573,49 @@ can point to arbitrary kernel, root filesystem locations, and so forth. | |||
4948 | Contrast this behavior with cooked mode where Wic looks in the Build | 5573 | Contrast this behavior with cooked mode where Wic looks in the Build |
4949 | Directory (e.g. ``tmp/deploy/images/``\ machine). | 5574 | Directory (e.g. ``tmp/deploy/images/``\ machine). |
4950 | 5575 | ||
4951 | The general form of the ``wic`` command in raw mode is: $ wic create | 5576 | The general form of the ``wic`` command in raw mode is: |
4952 | wks_file options ... Where: wks_file: An OpenEmbedded kickstart file. | 5577 | :: |
4953 | You can provide your own custom file or use a file from a set of | 5578 | |
4954 | existing files as described by further options. optional arguments: -h, | 5579 | $ wic create wks_file options ... |
4955 | --help show this help message and exit -o OUTDIR, --outdir OUTDIR name | 5580 | |
4956 | of directory to create image in -e IMAGE_NAME, --image-name IMAGE_NAME | 5581 | Where: |
4957 | name of the image to use the artifacts from e.g. core- image-sato -r | 5582 | |
4958 | ROOTFS_DIR, --rootfs-dir ROOTFS_DIR path to the /rootfs dir to use as | 5583 | wks_file: |
4959 | the .wks rootfs source -b BOOTIMG_DIR, --bootimg-dir BOOTIMG_DIR path to | 5584 | An OpenEmbedded kickstart file. You can provide |
4960 | the dir containing the boot artifacts (e.g. /EFI or /syslinux dirs) to | 5585 | your own custom file or use a file from a set of |
4961 | use as the .wks bootimg source -k KERNEL_DIR, --kernel-dir KERNEL_DIR | 5586 | existing files as described by further options. |
4962 | path to the dir containing the kernel to use in the .wks bootimg -n | 5587 | |
4963 | NATIVE_SYSROOT, --native-sysroot NATIVE_SYSROOT path to the native | 5588 | optional arguments: |
4964 | sysroot containing the tools to use to build the image -s, | 5589 | -h, --help show this help message and exit |
4965 | --skip-build-check skip the build check -f, --build-rootfs build rootfs | 5590 | -o OUTDIR, --outdir OUTDIR |
4966 | -c {gzip,bzip2,xz}, --compress-with {gzip,bzip2,xz} compress image with | 5591 | name of directory to create image in |
4967 | specified compressor -m, --bmap generate .bmap --no-fstab-update Do not | 5592 | -e IMAGE_NAME, --image-name IMAGE_NAME |
4968 | change fstab file. -v VARS_DIR, --vars VARS_DIR directory with | 5593 | name of the image to use the artifacts from e.g. core- |
4969 | <image>.env files that store bitbake variables -D, --debug output debug | 5594 | image-sato |
4970 | information | 5595 | -r ROOTFS_DIR, --rootfs-dir ROOTFS_DIR |
5596 | path to the /rootfs dir to use as the .wks rootfs | ||
5597 | source | ||
5598 | -b BOOTIMG_DIR, --bootimg-dir BOOTIMG_DIR | ||
5599 | path to the dir containing the boot artifacts (e.g. | ||
5600 | /EFI or /syslinux dirs) to use as the .wks bootimg | ||
5601 | source | ||
5602 | -k KERNEL_DIR, --kernel-dir KERNEL_DIR | ||
5603 | path to the dir containing the kernel to use in the | ||
5604 | .wks bootimg | ||
5605 | -n NATIVE_SYSROOT, --native-sysroot NATIVE_SYSROOT | ||
5606 | path to the native sysroot containing the tools to use | ||
5607 | to build the image | ||
5608 | -s, --skip-build-check | ||
5609 | skip the build check | ||
5610 | -f, --build-rootfs build rootfs | ||
5611 | -c {gzip,bzip2,xz}, --compress-with {gzip,bzip2,xz} | ||
5612 | compress image with specified compressor | ||
5613 | -m, --bmap generate .bmap | ||
5614 | --no-fstab-update Do not change fstab file. | ||
5615 | -v VARS_DIR, --vars VARS_DIR | ||
5616 | directory with <image>.env files that store bitbake | ||
5617 | variables | ||
5618 | -D, --debug output debug information | ||
4971 | 5619 | ||
4972 | .. note:: | 5620 | .. note:: |
4973 | 5621 | ||
@@ -4985,11 +5633,22 @@ by using the "-e" option. Wic looks in the Build Directory (e.g. | |||
4985 | ``tmp/deploy/images/``\ machine) for artifacts. | 5633 | ``tmp/deploy/images/``\ machine) for artifacts. |
4986 | 5634 | ||
4987 | The general form of the ``wic`` command using Cooked Mode is as follows: | 5635 | The general form of the ``wic`` command using Cooked Mode is as follows: |
4988 | $ wic create wks_file -e IMAGE_NAME Where: wks_file: An OpenEmbedded | 5636 | :: |
4989 | kickstart file. You can provide your own custom file or use a file from | 5637 | |
4990 | a set of existing files provided with the Yocto Project release. | 5638 | $ wic create wks_file -e IMAGE_NAME |
4991 | required argument: -e IMAGE_NAME, --image-name IMAGE_NAME name of the | 5639 | |
4992 | image to use the artifacts from e.g. core- image-sato | 5640 | Where: |
5641 | |||
5642 | wks_file: | ||
5643 | An OpenEmbedded kickstart file. You can provide | ||
5644 | your own custom file or use a file from a set of | ||
5645 | existing files provided with the Yocto Project | ||
5646 | release. | ||
5647 | |||
5648 | required argument: | ||
5649 | -e IMAGE_NAME, --image-name IMAGE_NAME | ||
5650 | name of the image to use the artifacts from e.g. core- | ||
5651 | image-sato | ||
4993 | 5652 | ||
4994 | .. _using-a-provided-kickstart-file: | 5653 | .. _using-a-provided-kickstart-file: |
4995 | 5654 | ||
@@ -4998,34 +5657,49 @@ Using an Existing Kickstart File | |||
4998 | 5657 | ||
4999 | If you do not want to create your own kickstart file, you can use an | 5658 | If you do not want to create your own kickstart file, you can use an |
5000 | existing file provided by the Wic installation. As shipped, kickstart | 5659 | existing file provided by the Wic installation. As shipped, kickstart |
5001 | files can be found in the Yocto Project `Source | 5660 | files can be found in the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories` in the |
5002 | Repositories <&YOCTO_DOCS_OM_URL;#source-repositories>`__ in the | 5661 | following two locations: |
5003 | following two locations: poky/meta-yocto-bsp/wic | 5662 | :: |
5004 | poky/scripts/lib/wic/canned-wks Use the following command to list the | 5663 | |
5005 | available kickstart files: $ wic list images genericx86 Create an EFI | 5664 | poky/meta-yocto-bsp/wic |
5006 | disk image for genericx86\* beaglebone-yocto Create SD card image for | 5665 | poky/scripts/lib/wic/canned-wks |
5007 | Beaglebone edgerouter Create SD card image for Edgerouter | 5666 | |
5008 | qemux86-directdisk Create a qemu machine 'pcbios' direct disk image | 5667 | Use the following command to list the available kickstart files: |
5009 | directdisk-gpt Create a 'pcbios' direct disk image mkefidisk Create an | 5668 | :: |
5010 | EFI disk image directdisk Create a 'pcbios' direct disk image | 5669 | |
5011 | systemd-bootdisk Create an EFI disk image with systemd-boot mkhybridiso | 5670 | $ wic list images |
5012 | Create a hybrid ISO image sdimage-bootpart Create SD card image with a | 5671 | genericx86 Create an EFI disk image for genericx86* |
5013 | boot partition directdisk-multi-rootfs Create multi rootfs image using | 5672 | beaglebone-yocto Create SD card image for Beaglebone |
5014 | rootfs plugin directdisk-bootloader-config Create a 'pcbios' direct disk | 5673 | edgerouter Create SD card image for Edgerouter |
5015 | image with custom bootloader config When you use an existing file, you | 5674 | qemux86-directdisk Create a qemu machine 'pcbios' direct disk image |
5675 | directdisk-gpt Create a 'pcbios' direct disk image | ||
5676 | mkefidisk Create an EFI disk image | ||
5677 | directdisk Create a 'pcbios' direct disk image | ||
5678 | systemd-bootdisk Create an EFI disk image with systemd-boot | ||
5679 | mkhybridiso Create a hybrid ISO image | ||
5680 | sdimage-bootpart Create SD card image with a boot partition | ||
5681 | directdisk-multi-rootfs Create multi rootfs image using rootfs plugin | ||
5682 | directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config | ||
5683 | |||
5684 | When you use an existing file, you | ||
5016 | do not have to use the ``.wks`` extension. Here is an example in Raw | 5685 | do not have to use the ``.wks`` extension. Here is an example in Raw |
5017 | Mode that uses the ``directdisk`` file: $ wic create directdisk -r | 5686 | Mode that uses the ``directdisk`` file: |
5018 | rootfs_dir -b bootimg_dir \\ -k kernel_dir -n native_sysroot | 5687 | :: |
5688 | |||
5689 | $ wic create directdisk -r rootfs_dir -b bootimg_dir \ | ||
5690 | -k kernel_dir -n native_sysroot | ||
5019 | 5691 | ||
5020 | Here are the actual partition language commands used in the | 5692 | Here are the actual partition language commands used in the |
5021 | ``genericx86.wks`` file to generate an image: # short-description: | 5693 | ``genericx86.wks`` file to generate an image: |
5022 | Create an EFI disk image for genericx86\* # long-description: Creates a | 5694 | :: |
5023 | partitioned EFI disk image for genericx86\* machines part /boot --source | 5695 | |
5024 | bootimg-efi --sourceparams="loader=grub-efi" --ondisk sda --label msdos | 5696 | # short-description: Create an EFI disk image for genericx86* |
5025 | --active --align 1024 part / --source rootfs --ondisk sda --fstype=ext4 | 5697 | # long-description: Creates a partitioned EFI disk image for genericx86* machines |
5026 | --label platform --align 1024 --use-uuid part swap --ondisk sda --size | 5698 | part /boot --source bootimg-efi --sourceparams="loader=grub-efi" --ondisk sda --label msdos --active --align 1024 |
5027 | 44 --label swap1 --fstype=swap bootloader --ptable gpt --timeout=5 | 5699 | part / --source rootfs --ondisk sda --fstype=ext4 --label platform --align 1024 --use-uuid |
5028 | --append="rootfstype=ext4 console=ttyS0,115200 console=tty0" | 5700 | part swap --ondisk sda --size 44 --label swap1 --fstype=swap |
5701 | |||
5702 | bootloader --ptable gpt --timeout=5 --append="rootfstype=ext4 console=ttyS0,115200 console=tty0" | ||
5029 | 5703 | ||
5030 | .. _wic-using-the-wic-plugin-interface: | 5704 | .. _wic-using-the-wic-plugin-interface: |
5031 | 5705 | ||
@@ -5078,22 +5752,47 @@ When the Wic implementation needs to invoke a partition-specific | |||
5078 | implementation, it looks for the plugin with the same name as the | 5752 | implementation, it looks for the plugin with the same name as the |
5079 | ``--source`` parameter used in the kickstart file given to that | 5753 | ``--source`` parameter used in the kickstart file given to that |
5080 | partition. For example, if the partition is set up using the following | 5754 | partition. For example, if the partition is set up using the following |
5081 | command in a kickstart file: part /boot --source bootimg-pcbios --ondisk | 5755 | command in a kickstart file: |
5082 | sda --label boot --active --align 1024 The methods defined as class | 5756 | :: |
5757 | |||
5758 | part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024 | ||
5759 | |||
5760 | The methods defined as class | ||
5083 | members of the matching source plugin (i.e. ``bootimg-pcbios``) in the | 5761 | members of the matching source plugin (i.e. ``bootimg-pcbios``) in the |
5084 | ``bootimg-pcbios.py`` plugin file are used. | 5762 | ``bootimg-pcbios.py`` plugin file are used. |
5085 | 5763 | ||
5086 | To be more concrete, here is the corresponding plugin definition from | 5764 | To be more concrete, here is the corresponding plugin definition from |
5087 | the ``bootimg-pcbios.py`` file for the previous command along with an | 5765 | the ``bootimg-pcbios.py`` file for the previous command along with an |
5088 | example method called by the Wic implementation when it needs to prepare | 5766 | example method called by the Wic implementation when it needs to prepare |
5089 | a partition using an implementation-specific function: . . . class | 5767 | a partition using an implementation-specific function: |
5090 | BootimgPcbiosPlugin(SourcePlugin): """ Create MBR boot partition and | 5768 | :: |
5091 | install syslinux on it. """ name = 'bootimg-pcbios' . . . @classmethod | 5769 | |
5092 | def do_prepare_partition(cls, part, source_params, creator, cr_workdir, | 5770 | . |
5093 | oe_builddir, bootimg_dir, kernel_dir, rootfs_dir, native_sysroot): """ | 5771 | . |
5094 | Called to do the actual content population for a partition i.e. it | 5772 | . |
5095 | 'prepares' the partition to be incorporated into the image. In this | 5773 | class BootimgPcbiosPlugin(SourcePlugin): |
5096 | case, prepare content for legacy bios boot partition. """ . . . If a | 5774 | """ |
5775 | Create MBR boot partition and install syslinux on it. | ||
5776 | """ | ||
5777 | |||
5778 | name = 'bootimg-pcbios' | ||
5779 | . | ||
5780 | . | ||
5781 | . | ||
5782 | @classmethod | ||
5783 | def do_prepare_partition(cls, part, source_params, creator, cr_workdir, | ||
5784 | oe_builddir, bootimg_dir, kernel_dir, | ||
5785 | rootfs_dir, native_sysroot): | ||
5786 | """ | ||
5787 | Called to do the actual content population for a partition i.e. it | ||
5788 | 'prepares' the partition to be incorporated into the image. | ||
5789 | In this case, prepare content for legacy bios boot partition. | ||
5790 | """ | ||
5791 | . | ||
5792 | . | ||
5793 | . | ||
5794 | |||
5795 | If a | ||
5097 | subclass (plugin) itself does not implement a particular function, Wic | 5796 | subclass (plugin) itself does not implement a particular function, Wic |
5098 | locates and uses the default version in the superclass. It is for this | 5797 | locates and uses the default version in the superclass. It is for this |
5099 | reason that all source plugins are derived from the ``SourcePlugin`` | 5798 | reason that all source plugins are derived from the ``SourcePlugin`` |
@@ -5109,19 +5808,19 @@ class in the ``pluginbase.py`` file for details: | |||
5109 | The following list describes the methods implemented in the | 5808 | The following list describes the methods implemented in the |
5110 | ``SourcePlugin`` class: | 5809 | ``SourcePlugin`` class: |
5111 | 5810 | ||
5112 | - *``do_prepare_partition()``:* Called to populate a partition with | 5811 | - ``do_prepare_partition()``: Called to populate a partition with |
5113 | actual content. In other words, the method prepares the final | 5812 | actual content. In other words, the method prepares the final |
5114 | partition image that is incorporated into the disk image. | 5813 | partition image that is incorporated into the disk image. |
5115 | 5814 | ||
5116 | - *``do_configure_partition()``:* Called before | 5815 | - ``do_configure_partition()``: Called before |
5117 | ``do_prepare_partition()`` to create custom configuration files for a | 5816 | ``do_prepare_partition()`` to create custom configuration files for a |
5118 | partition (e.g. syslinux or grub configuration files). | 5817 | partition (e.g. syslinux or grub configuration files). |
5119 | 5818 | ||
5120 | - *``do_install_disk()``:* Called after all partitions have been | 5819 | - ``do_install_disk()``: Called after all partitions have been |
5121 | prepared and assembled into a disk image. This method provides a hook | 5820 | prepared and assembled into a disk image. This method provides a hook |
5122 | to allow finalization of a disk image (e.g. writing an MBR). | 5821 | to allow finalization of a disk image (e.g. writing an MBR). |
5123 | 5822 | ||
5124 | - *``do_stage_partition()``:* Special content-staging hook called | 5823 | - ``do_stage_partition()``: Special content-staging hook called |
5125 | before ``do_prepare_partition()``. This method is normally empty. | 5824 | before ``do_prepare_partition()``. This method is normally empty. |
5126 | 5825 | ||
5127 | Typically, a partition just uses the passed-in parameters (e.g. the | 5826 | Typically, a partition just uses the passed-in parameters (e.g. the |
@@ -5147,8 +5846,8 @@ See the Wic implementation for examples and details. | |||
5147 | 5846 | ||
5148 | .. _wic-usage-examples: | 5847 | .. _wic-usage-examples: |
5149 | 5848 | ||
5150 | Examples | 5849 | Wic Examples |
5151 | -------- | 5850 | ------------ |
5152 | 5851 | ||
5153 | This section provides several examples that show how to use the Wic | 5852 | This section provides several examples that show how to use the Wic |
5154 | utility. All the examples assume the list of requirements in the | 5853 | utility. All the examples assume the list of requirements in the |
@@ -5162,19 +5861,26 @@ Generate an Image using an Existing Kickstart File | |||
5162 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 5861 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
5163 | 5862 | ||
5164 | This example runs in Cooked Mode and uses the ``mkefidisk`` kickstart | 5863 | This example runs in Cooked Mode and uses the ``mkefidisk`` kickstart |
5165 | file: $ wic create mkefidisk -e core-image-minimal INFO: Building | 5864 | file: |
5166 | wic-tools... . . . INFO: The new image(s) can be found here: | 5865 | :: |
5167 | ./mkefidisk-201804191017-sda.direct The following build artifacts were | 5866 | |
5168 | used to create the image(s): ROOTFS_DIR: | 5867 | $ wic create mkefidisk -e core-image-minimal |
5169 | /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs | 5868 | INFO: Building wic-tools... |
5170 | BOOTIMG_DIR: | 5869 | . |
5171 | /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share | 5870 | . |
5172 | KERNEL_DIR: | 5871 | . |
5173 | /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86 | 5872 | INFO: The new image(s) can be found here: |
5174 | NATIVE_SYSROOT: | 5873 | ./mkefidisk-201804191017-sda.direct |
5175 | /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native | 5874 | |
5176 | INFO: The image(s) were created using OE kickstart file: | 5875 | The following build artifacts were used to create the image(s): |
5177 | /home/stephano/build/master/openembedded-core/scripts/lib/wic/canned-wks/mkefidisk.wks | 5876 | ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs |
5877 | BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share | ||
5878 | KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86 | ||
5879 | NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native | ||
5880 | |||
5881 | INFO: The image(s) were created using OE kickstart file: | ||
5882 | /home/stephano/build/master/openembedded-core/scripts/lib/wic/canned-wks/mkefidisk.wks | ||
5883 | |||
5178 | The previous example shows the easiest way to create an image by running | 5884 | The previous example shows the easiest way to create an image by running |
5179 | in cooked mode and supplying a kickstart file and the "-e" option to | 5885 | in cooked mode and supplying a kickstart file and the "-e" option to |
5180 | point to the existing build artifacts. Your ``local.conf`` file needs to | 5886 | point to the existing build artifacts. Your ``local.conf`` file needs to |
@@ -5192,9 +5898,14 @@ and kickstart file information. | |||
5192 | Continuing with the example, you can now write the image from the Build | 5898 | Continuing with the example, you can now write the image from the Build |
5193 | Directory onto a USB stick, or whatever media for which you built your | 5899 | Directory onto a USB stick, or whatever media for which you built your |
5194 | image, and boot from the media. You can write the image by using | 5900 | image, and boot from the media. You can write the image by using |
5195 | ``bmaptool`` or ``dd``: $ oe-run-native bmaptool copy | 5901 | ``bmaptool`` or ``dd``: |
5196 | mkefidisk-201804191017-sda.direct /dev/sdX or $ sudo dd | 5902 | :: |
5197 | if=mkefidisk-201804191017-sda.direct of=/dev/sdX | 5903 | |
5904 | $ oe-run-native bmaptool copy mkefidisk-201804191017-sda.direct /dev/sdX | ||
5905 | |||
5906 | or :: | ||
5907 | |||
5908 | $ sudo dd if=mkefidisk-201804191017-sda.direct of=/dev/sdX | ||
5198 | 5909 | ||
5199 | .. note:: | 5910 | .. note:: |
5200 | 5911 | ||
@@ -5229,41 +5940,61 @@ will need to boot from ``sdb`` instead of ``sda``, which is what the | |||
5229 | 5940 | ||
5230 | The example begins by making a copy of the ``directdisk-gpt.wks`` file | 5941 | The example begins by making a copy of the ``directdisk-gpt.wks`` file |
5231 | in the ``scripts/lib/image/canned-wks`` directory and then by changing | 5942 | in the ``scripts/lib/image/canned-wks`` directory and then by changing |
5232 | the lines that specify the target disk from which to boot. $ cp | 5943 | the lines that specify the target disk from which to boot. |
5233 | /home/stephano/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \\ | 5944 | :: |
5234 | /home/stephano/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks | 5945 | |
5946 | $ cp /home/stephano/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \ | ||
5947 | /home/stephano/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks | ||
5948 | |||
5235 | Next, the example modifies the ``directdisksdb-gpt.wks`` file and | 5949 | Next, the example modifies the ``directdisksdb-gpt.wks`` file and |
5236 | changes all instances of "``--ondisk sda``" to "``--ondisk sdb``". The | 5950 | changes all instances of "``--ondisk sda``" to "``--ondisk sdb``". The |
5237 | example changes the following two lines and leaves the remaining lines | 5951 | example changes the following two lines and leaves the remaining lines |
5238 | untouched: part /boot --source bootimg-pcbios --ondisk sdb --label boot | 5952 | untouched: |
5239 | --active --align 1024 part / --source rootfs --ondisk sdb --fstype=ext4 | 5953 | :: |
5240 | --label platform --align 1024 --use-uuid Once the lines are changed, the | 5954 | |
5955 | part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024 | ||
5956 | part / --source rootfs --ondisk sdb --fstype=ext4 --label platform --align 1024 --use-uuid | ||
5957 | |||
5958 | Once the lines are changed, the | ||
5241 | example generates the ``directdisksdb-gpt`` image. The command points | 5959 | example generates the ``directdisksdb-gpt`` image. The command points |
5242 | the process at the ``core-image-minimal`` artifacts for the Next Unit of | 5960 | the process at the ``core-image-minimal`` artifacts for the Next Unit of |
5243 | Computing (nuc) :term:`MACHINE` the | 5961 | Computing (nuc) :term:`MACHINE` the |
5244 | ``local.conf``. $ wic create directdisksdb-gpt -e core-image-minimal | 5962 | ``local.conf``. |
5245 | INFO: Building wic-tools... . . . Initialising tasks: 100% | 5963 | :: |
5246 | \|#######################################\| Time: 0:00:01 NOTE: | 5964 | |
5247 | Executing SetScene Tasks NOTE: Executing RunQueue Tasks NOTE: Tasks | 5965 | $ wic create directdisksdb-gpt -e core-image-minimal |
5248 | Summary: Attempted 1161 tasks of which 1157 didn't need to be rerun and | 5966 | INFO: Building wic-tools... |
5249 | all succeeded. INFO: Creating image(s)... INFO: The new image(s) can be | 5967 | . |
5250 | found here: ./directdisksdb-gpt-201710090938-sdb.direct The following | 5968 | . |
5251 | build artifacts were used to create the image(s): ROOTFS_DIR: | 5969 | . |
5252 | /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs | 5970 | Initialising tasks: 100% |#######################################| Time: 0:00:01 |
5253 | BOOTIMG_DIR: | 5971 | NOTE: Executing SetScene Tasks |
5254 | /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share | 5972 | NOTE: Executing RunQueue Tasks |
5255 | KERNEL_DIR: | 5973 | NOTE: Tasks Summary: Attempted 1161 tasks of which 1157 didn't need to be rerun and all succeeded. |
5256 | /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86 | 5974 | INFO: Creating image(s)... |
5257 | NATIVE_SYSROOT: | 5975 | |
5258 | /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native | 5976 | INFO: The new image(s) can be found here: |
5259 | INFO: The image(s) were created using OE kickstart file: | 5977 | ./directdisksdb-gpt-201710090938-sdb.direct |
5260 | /home/stephano/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks | 5978 | |
5979 | The following build artifacts were used to create the image(s): | ||
5980 | ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs | ||
5981 | BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share | ||
5982 | KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86 | ||
5983 | NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native | ||
5984 | |||
5985 | INFO: The image(s) were created using OE kickstart file: | ||
5986 | /home/stephano/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks | ||
5987 | |||
5261 | Continuing with the example, you can now directly ``dd`` the image to a | 5988 | Continuing with the example, you can now directly ``dd`` the image to a |
5262 | USB stick, or whatever media for which you built your image, and boot | 5989 | USB stick, or whatever media for which you built your image, and boot |
5263 | the resulting media: $ sudo dd | 5990 | the resulting media: |
5264 | if=directdisksdb-gpt-201710090938-sdb.direct of=/dev/sdb 140966+0 | 5991 | :: |
5265 | records in 140966+0 records out 72174592 bytes (72 MB, 69 MiB) copied, | 5992 | |
5266 | 78.0282 s, 925 kB/s $ sudo eject /dev/sdb | 5993 | $ sudo dd if=directdisksdb-gpt-201710090938-sdb.direct of=/dev/sdb |
5994 | 140966+0 records in | ||
5995 | 140966+0 records out | ||
5996 | 72174592 bytes (72 MB, 69 MiB) copied, 78.0282 s, 925 kB/s | ||
5997 | $ sudo eject /dev/sdb | ||
5267 | 5998 | ||
5268 | Using a Modified Kickstart File and Running in Raw Mode | 5999 | Using a Modified Kickstart File and Running in Raw Mode |
5269 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 6000 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
@@ -5271,28 +6002,30 @@ Using a Modified Kickstart File and Running in Raw Mode | |||
5271 | This next example manually specifies each build artifact (runs in Raw | 6002 | This next example manually specifies each build artifact (runs in Raw |
5272 | Mode) and uses a modified kickstart file. The example also uses the | 6003 | Mode) and uses a modified kickstart file. The example also uses the |
5273 | ``-o`` option to cause Wic to create the output somewhere other than the | 6004 | ``-o`` option to cause Wic to create the output somewhere other than the |
5274 | default output directory, which is the current directory: $ wic create | 6005 | default output directory, which is the current directory: |
5275 | /home/stephano/my_yocto/test.wks -o /home/stephano/testwic \\ | 6006 | :: |
5276 | --rootfs-dir | 6007 | |
5277 | /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs | 6008 | $ wic create /home/stephano/my_yocto/test.wks -o /home/stephano/testwic \ |
5278 | \\ --bootimg-dir | 6009 | --rootfs-dir /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \ |
5279 | /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share | 6010 | --bootimg-dir /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \ |
5280 | \\ --kernel-dir | 6011 | --kernel-dir /home/stephano/build/master/build/tmp/deploy/images/qemux86 \ |
5281 | /home/stephano/build/master/build/tmp/deploy/images/qemux86 \\ | 6012 | --native-sysroot /home/stephano/build/master/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native |
5282 | --native-sysroot | 6013 | |
5283 | /home/stephano/build/master/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native | 6014 | INFO: Creating image(s)... |
5284 | INFO: Creating image(s)... INFO: The new image(s) can be found here: | 6015 | |
5285 | /home/stephano/testwic/test-201710091445-sdb.direct The following build | 6016 | INFO: The new image(s) can be found here: |
5286 | artifacts were used to create the image(s): ROOTFS_DIR: | 6017 | /home/stephano/testwic/test-201710091445-sdb.direct |
5287 | /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs | 6018 | |
5288 | BOOTIMG_DIR: | 6019 | The following build artifacts were used to create the image(s): |
5289 | /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share | 6020 | ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs |
5290 | KERNEL_DIR: | 6021 | BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share |
5291 | /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86 | 6022 | KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86 |
5292 | NATIVE_SYSROOT: | 6023 | NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native |
5293 | /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native | 6024 | |
5294 | INFO: The image(s) were created using OE kickstart file: | 6025 | INFO: The image(s) were created using OE kickstart file: |
5295 | /home/stephano/my_yocto/test.wks For this example, | 6026 | /home/stephano/my_yocto/test.wks |
6027 | |||
6028 | For this example, | ||
5296 | :term:`MACHINE` did not have to be | 6029 | :term:`MACHINE` did not have to be |
5297 | specified in the ``local.conf`` file since the artifact is manually | 6030 | specified in the ``local.conf`` file since the artifact is manually |
5298 | specified. | 6031 | specified. |
@@ -5317,10 +6050,15 @@ The following example examines the contents of the Wic image, deletes | |||
5317 | the existing kernel, and then inserts a new kernel: | 6050 | the existing kernel, and then inserts a new kernel: |
5318 | 6051 | ||
5319 | 1. *List the Partitions:* Use the ``wic ls`` command to list all the | 6052 | 1. *List the Partitions:* Use the ``wic ls`` command to list all the |
5320 | partitions in the Wic image: $ wic ls | 6053 | partitions in the Wic image: |
5321 | tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic Num Start | 6054 | :: |
5322 | End Size Fstype 1 1048576 25041919 23993344 fat16 2 25165824 72157183 | 6055 | |
5323 | 46991360 ext4 The previous output shows two partitions in the | 6056 | $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic |
6057 | Num Start End Size Fstype | ||
6058 | 1 1048576 25041919 23993344 fat16 | ||
6059 | 2 25165824 72157183 46991360 ext4 | ||
6060 | |||
6061 | The previous output shows two partitions in the | ||
5324 | ``core-image-minimal-qemux86.wic`` image. | 6062 | ``core-image-minimal-qemux86.wic`` image. |
5325 | 6063 | ||
5326 | 2. *Examine a Particular Partition:* Use the ``wic ls`` command again | 6064 | 2. *Examine a Particular Partition:* Use the ``wic ls`` command again |
@@ -5333,7 +6071,7 @@ the existing kernel, and then inserts a new kernel: | |||
5333 | :: | 6071 | :: |
5334 | 6072 | ||
5335 | $ wic help command | 6073 | $ wic help command |
5336 | 6074 | ||
5337 | 6075 | ||
5338 | For example, the following command shows you the various ways to | 6076 | For example, the following command shows you the various ways to |
5339 | use the | 6077 | use the |
@@ -5342,15 +6080,25 @@ the existing kernel, and then inserts a new kernel: | |||
5342 | :: | 6080 | :: |
5343 | 6081 | ||
5344 | $ wic help ls | 6082 | $ wic help ls |
5345 | 6083 | ||
5346 | 6084 | ||
5347 | The following command shows what is in Partition one: $ wic ls | 6085 | The following command shows what is in Partition one: |
5348 | tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1 Volume in | 6086 | :: |
5349 | drive : is boot Volume Serial Number is E894-1809 Directory for ::/ | 6087 | |
5350 | libcom32 c32 186500 2017-10-09 16:06 libutil c32 24148 2017-10-09 | 6088 | $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1 |
5351 | 16:06 syslinux cfg 220 2017-10-09 16:06 vesamenu c32 27104 2017-10-09 | 6089 | Volume in drive : is boot |
5352 | 16:06 vmlinuz 6904608 2017-10-09 16:06 5 files 7 142 580 bytes 16 582 | 6090 | Volume Serial Number is E894-1809 |
5353 | 656 bytes free The previous output shows five files, with the | 6091 | Directory for ::/ |
6092 | |||
6093 | libcom32 c32 186500 2017-10-09 16:06 | ||
6094 | libutil c32 24148 2017-10-09 16:06 | ||
6095 | syslinux cfg 220 2017-10-09 16:06 | ||
6096 | vesamenu c32 27104 2017-10-09 16:06 | ||
6097 | vmlinuz 6904608 2017-10-09 16:06 | ||
6098 | 5 files 7 142 580 bytes | ||
6099 | 16 582 656 bytes free | ||
6100 | |||
6101 | The previous output shows five files, with the | ||
5354 | ``vmlinuz`` being the kernel. | 6102 | ``vmlinuz`` being the kernel. |
5355 | 6103 | ||
5356 | .. note:: | 6104 | .. note:: |
@@ -5364,11 +6112,13 @@ the existing kernel, and then inserts a new kernel: | |||
5364 | ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0 | 6112 | ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0 |
5365 | output: Total number of sectors (47824) not a multiple of sectors per track (32)! | 6113 | output: Total number of sectors (47824) not a multiple of sectors per track (32)! |
5366 | Add mtools_skip_check=1 to your .mtoolsrc file to skip this test | 6114 | Add mtools_skip_check=1 to your .mtoolsrc file to skip this test |
5367 | 6115 | ||
5368 | 6116 | ||
5369 | 3. *Remove the Old Kernel:* Use the ``wic rm`` command to remove the | 6117 | 3. *Remove the Old Kernel:* Use the ``wic rm`` command to remove the |
5370 | ``vmlinuz`` file (kernel): $ wic rm | 6118 | ``vmlinuz`` file (kernel): |
5371 | tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz | 6119 | :: |
6120 | |||
6121 | $ wic rm tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz | ||
5372 | 6122 | ||
5373 | 4. *Add In the New Kernel:* Use the ``wic cp`` command to add the | 6123 | 4. *Add In the New Kernel:* Use the ``wic cp`` command to add the |
5374 | updated kernel to the Wic image. Depending on how you built your | 6124 | updated kernel to the Wic image. Depending on how you built your |
@@ -5378,10 +6128,12 @@ the existing kernel, and then inserts a new kernel: | |||
5378 | kernel will be in the ``workspace/sources`` area. | 6128 | kernel will be in the ``workspace/sources`` area. |
5379 | 6129 | ||
5380 | The following example assumes ``devtool`` was used to build the | 6130 | The following example assumes ``devtool`` was used to build the |
5381 | kernel: cp | 6131 | kernel: |
5382 | ~/poky_sdk/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+git999-r0/linux-yocto-4.12.12+git999/arch/x86/boot/bzImage | 6132 | :: |
5383 | \\ | 6133 | |
5384 | ~/poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz | 6134 | cp ~/poky_sdk/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+git999-r0/linux-yocto-4.12.12+git999/arch/x86/boot/bzImage \ |
6135 | ~/poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz | ||
6136 | |||
5385 | Once the new kernel is added back into the image, you can use the | 6137 | Once the new kernel is added back into the image, you can use the |
5386 | ``dd`` command or ```bmaptool`` <#flashing-images-using-bmaptool>`__ | 6138 | ``dd`` command or ```bmaptool`` <#flashing-images-using-bmaptool>`__ |
5387 | to flash your wic image onto an SD card or USB stick and test your | 6139 | to flash your wic image onto an SD card or USB stick and test your |
@@ -5420,30 +6172,39 @@ Following, is an example that shows how to flash a Wic image. Realize | |||
5420 | that while this example uses a Wic image, you can use Bmaptool to flash | 6172 | that while this example uses a Wic image, you can use Bmaptool to flash |
5421 | any type of image. Use these steps to flash an image using Bmaptool: | 6173 | any type of image. Use these steps to flash an image using Bmaptool: |
5422 | 6174 | ||
5423 | 1. *Update your ``local.conf`` File:* You need to have the following set | 6175 | 1. *Update your local.conf File:* You need to have the following set |
5424 | in your ``local.conf`` file before building your image: IMAGE_FSTYPES | 6176 | in your ``local.conf`` file before building your image: |
5425 | += "wic wic.bmap" | 6177 | :: |
6178 | |||
6179 | IMAGE_FSTYPES += "wic wic.bmap" | ||
5426 | 6180 | ||
5427 | 2. *Get Your Image:* Either have your image ready (pre-built with the | 6181 | 2. *Get Your Image:* Either have your image ready (pre-built with the |
5428 | :term:`IMAGE_FSTYPES` | 6182 | :term:`IMAGE_FSTYPES` |
5429 | setting previously mentioned) or take the step to build the image: $ | 6183 | setting previously mentioned) or take the step to build the image: |
5430 | bitbake image | 6184 | :: |
6185 | |||
6186 | $ bitbake image | ||
5431 | 6187 | ||
5432 | 3. *Flash the Device:* Flash the device with the image by using Bmaptool | 6188 | 3. *Flash the Device:* Flash the device with the image by using Bmaptool |
5433 | depending on your particular setup. The following commands assume the | 6189 | depending on your particular setup. The following commands assume the |
5434 | image resides in the Build Directory's ``deploy/images/`` area: | 6190 | image resides in the Build Directory's ``deploy/images/`` area: |
5435 | 6191 | ||
5436 | - If you have write access to the media, use this command form: $ | 6192 | - If you have write access to the media, use this command form: |
5437 | oe-run-native bmap-tools-native bmaptool copy | 6193 | :: |
5438 | build-directory/tmp/deploy/images/machine/image.wic /dev/sdX | 6194 | |
6195 | $ oe-run-native bmap-tools-native bmaptool copy build-directory/tmp/deploy/images/machine/image.wic /dev/sdX | ||
5439 | 6196 | ||
5440 | - If you do not have write access to the media, set your permissions | 6197 | - If you do not have write access to the media, set your permissions |
5441 | first and then use the same command form: $ sudo chmod 666 | 6198 | first and then use the same command form: |
5442 | /dev/sdX $ oe-run-native bmap-tools-native bmaptool copy | 6199 | :: |
5443 | build-directory/tmp/deploy/images/machine/image.wic /dev/sdX | ||
5444 | 6200 | ||
5445 | For help on the ``bmaptool`` command, use the following command: $ | 6201 | $ sudo chmod 666 /dev/sdX |
5446 | bmaptool --help | 6202 | $ oe-run-native bmap-tools-native bmaptool copy build-directory/tmp/deploy/images/machine/image.wic /dev/sdX |
6203 | |||
6204 | For help on the ``bmaptool`` command, use the following command: | ||
6205 | :: | ||
6206 | |||
6207 | $ bmaptool --help | ||
5447 | 6208 | ||
5448 | Making Images More Secure | 6209 | Making Images More Secure |
5449 | ========================= | 6210 | ========================= |
@@ -5536,8 +6297,10 @@ your build output more secure. The security flags are in the | |||
5536 | 6297 | ||
5537 | Use the following line in your ``local.conf`` file or in your custom | 6298 | Use the following line in your ``local.conf`` file or in your custom |
5538 | distribution configuration file to enable the security compiler and | 6299 | distribution configuration file to enable the security compiler and |
5539 | linker flags for your build: require | 6300 | linker flags for your build: |
5540 | conf/distro/include/security_flags.inc | 6301 | :: |
6302 | |||
6303 | require conf/distro/include/security_flags.inc | ||
5541 | 6304 | ||
5542 | Considerations Specific to the OpenEmbedded Build System | 6305 | Considerations Specific to the OpenEmbedded Build System |
5543 | -------------------------------------------------------- | 6306 | -------------------------------------------------------- |
@@ -5550,8 +6313,12 @@ system to make your images more secure: | |||
5550 | When creating a new project, the default is to provide you with an | 6313 | When creating a new project, the default is to provide you with an |
5551 | initial ``local.conf`` file that enables this feature using the | 6314 | initial ``local.conf`` file that enables this feature using the |
5552 | :term:`EXTRA_IMAGE_FEATURES` | 6315 | :term:`EXTRA_IMAGE_FEATURES` |
5553 | variable with the line: EXTRA_IMAGE_FEATURES = "debug-tweaks" To | 6316 | variable with the line: |
5554 | disable that feature, simply comment out that line in your | 6317 | :: |
6318 | |||
6319 | EXTRA_IMAGE_FEATURES = "debug-tweaks" | ||
6320 | |||
6321 | To disable that feature, simply comment out that line in your | ||
5555 | ``local.conf`` file, or make sure ``IMAGE_FEATURES`` does not contain | 6322 | ``local.conf`` file, or make sure ``IMAGE_FEATURES`` does not contain |
5556 | "debug-tweaks" before producing your final image. Among other things, | 6323 | "debug-tweaks" before producing your final image. Among other things, |
5557 | leaving this in place sets the root password as blank, which makes | 6324 | leaving this in place sets the root password as blank, which makes |
@@ -5583,7 +6350,7 @@ system to make your images more secure: | |||
5583 | - Consider enabling a Mandatory Access Control (MAC) framework such as | 6350 | - Consider enabling a Mandatory Access Control (MAC) framework such as |
5584 | SMACK or SELinux and tuning it appropriately for your device's usage. | 6351 | SMACK or SELinux and tuning it appropriately for your device's usage. |
5585 | You can find more information in the | 6352 | You can find more information in the |
5586 | ```meta-selinux`http://git.yoctoproject.org/cgit/cgit.cgi/meta-selinux/ | 6353 | `meta-selinux <http://git.yoctoproject.org/cgit/cgit.cgi/meta-selinux/>`__ |
5587 | layer. | 6354 | layer. |
5588 | 6355 | ||
5589 | Tools for Hardening Your Image | 6356 | Tools for Hardening Your Image |
@@ -5613,9 +6380,8 @@ layer. The following steps provide some more detail: | |||
5613 | layer for configuration and code. Using your own layer as compared to | 6380 | layer for configuration and code. Using your own layer as compared to |
5614 | just placing configurations in a ``local.conf`` configuration file | 6381 | just placing configurations in a ``local.conf`` configuration file |
5615 | makes it easier to reproduce the same build configuration when using | 6382 | makes it easier to reproduce the same build configuration when using |
5616 | multiple build machines. See the "`Creating a General Layer Using the | 6383 | multiple build machines. See the |
5617 | ``bitbake-layers`` | 6384 | ":ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" |
5618 | Script <#creating-a-general-layer-using-the-bitbake-layers-script>`__" | ||
5619 | section for information on how to quickly set up a layer. | 6385 | section for information on how to quickly set up a layer. |
5620 | 6386 | ||
5621 | - *Create the distribution configuration file:* The distribution | 6387 | - *Create the distribution configuration file:* The distribution |
@@ -5639,14 +6405,22 @@ layer. The following steps provide some more detail: | |||
5639 | desired version and revisions for individual recipes. | 6405 | desired version and revisions for individual recipes. |
5640 | 6406 | ||
5641 | Your configuration file needs to set the following required | 6407 | Your configuration file needs to set the following required |
5642 | variables: :term:`DISTRO_NAME` | 6408 | variables: |
5643 | :term:`DISTRO_VERSION` | 6409 | |
6410 | - :term:`DISTRO_NAME` | ||
6411 | |||
6412 | - :term:`DISTRO_VERSION` | ||
6413 | |||
5644 | These following variables are optional and you typically set them | 6414 | These following variables are optional and you typically set them |
5645 | from the distribution configuration file: | 6415 | from the distribution configuration file: |
5646 | :term:`DISTRO_FEATURES` | 6416 | |
5647 | :term:`DISTRO_EXTRA_RDEPENDS` | 6417 | - :term:`DISTRO_FEATURES` |
5648 | :term:`DISTRO_EXTRA_RRECOMMENDS` | 6418 | |
5649 | :term:`TCLIBC` | 6419 | - :term:`DISTRO_EXTRA_RDEPENDS` |
6420 | |||
6421 | - :term:`DISTRO_EXTRA_RRECOMMENDS` | ||
6422 | |||
6423 | - :term:`TCLIBC` | ||
5650 | 6424 | ||
5651 | .. tip:: | 6425 | .. tip:: |
5652 | 6426 | ||
@@ -5674,7 +6448,10 @@ layer. The following steps provide some more detail: | |||
5674 | :term:`DISTRO` variable to point to | 6448 | :term:`DISTRO` variable to point to |
5675 | your distribution's configuration file. For example, if your | 6449 | your distribution's configuration file. For example, if your |
5676 | distribution's configuration file is named ``mydistro.conf``, then | 6450 | distribution's configuration file is named ``mydistro.conf``, then |
5677 | you point to it as follows: DISTRO = "mydistro" | 6451 | you point to it as follows: |
6452 | :: | ||
6453 | |||
6454 | DISTRO = "mydistro" | ||
5678 | 6455 | ||
5679 | - *Add more to the layer if necessary:* Use your layer to hold other | 6456 | - *Add more to the layer if necessary:* Use your layer to hold other |
5680 | information needed for the distribution: | 6457 | information needed for the distribution: |
@@ -5713,7 +6490,12 @@ The OpenEmbedded build system uses the environment variable | |||
5713 | configuration information that ultimately ends up in the | 6490 | configuration information that ultimately ends up in the |
5714 | :term:`Build Directory` ``conf`` directory. | 6491 | :term:`Build Directory` ``conf`` directory. |
5715 | By default, ``TEMPLATECONF`` is set as follows in the ``poky`` | 6492 | By default, ``TEMPLATECONF`` is set as follows in the ``poky`` |
5716 | repository: TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf} This is the | 6493 | repository: |
6494 | :: | ||
6495 | |||
6496 | TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf} | ||
6497 | |||
6498 | This is the | ||
5717 | directory used by the build system to find templates from which to build | 6499 | directory used by the build system to find templates from which to build |
5718 | some key configuration files. If you look at this directory, you will | 6500 | some key configuration files. If you look at this directory, you will |
5719 | see the ``bblayers.conf.sample``, ``local.conf.sample``, and | 6501 | see the ``bblayers.conf.sample``, ``local.conf.sample``, and |
@@ -5738,20 +6520,29 @@ system to look in your directory and base its configuration files on the | |||
5738 | ``*.sample`` configuration files it finds. The final configuration files | 6520 | ``*.sample`` configuration files it finds. The final configuration files |
5739 | (i.e. ``local.conf`` and ``bblayers.conf`` ultimately still end up in | 6521 | (i.e. ``local.conf`` and ``bblayers.conf`` ultimately still end up in |
5740 | your Build Directory, but they are based on your ``*.sample`` files. | 6522 | your Build Directory, but they are based on your ``*.sample`` files. |
5741 | TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} | 6523 | :: |
6524 | |||
6525 | TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} | ||
5742 | 6526 | ||
5743 | Aside from the ``*.sample`` configuration files, the ``conf-notes.txt`` | 6527 | Aside from the ``*.sample`` configuration files, the ``conf-notes.txt`` |
5744 | also resides in the default ``meta-poky/conf`` directory. The script | 6528 | also resides in the default ``meta-poky/conf`` directory. The script |
5745 | that sets up the build environment (i.e. | 6529 | that sets up the build environment (i.e. |
5746 | ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__) uses this file to | 6530 | :ref:`structure-core-script`) uses this file to |
5747 | display BitBake targets as part of the script output. Customizing this | 6531 | display BitBake targets as part of the script output. Customizing this |
5748 | ``conf-notes.txt`` file is a good way to make sure your list of custom | 6532 | ``conf-notes.txt`` file is a good way to make sure your list of custom |
5749 | targets appears as part of the script's output. | 6533 | targets appears as part of the script's output. |
5750 | 6534 | ||
5751 | Here is the default list of targets displayed as a result of running | 6535 | Here is the default list of targets displayed as a result of running |
5752 | either of the setup scripts: You can now run 'bitbake <target>' Common | 6536 | either of the setup scripts: |
5753 | targets are: core-image-minimal core-image-sato meta-toolchain | 6537 | :: |
5754 | meta-ide-support | 6538 | |
6539 | You can now run 'bitbake <target>' | ||
6540 | |||
6541 | Common targets are: | ||
6542 | core-image-minimal | ||
6543 | core-image-sato | ||
6544 | meta-toolchain | ||
6545 | meta-ide-support | ||
5755 | 6546 | ||
5756 | Changing the listed common targets is as easy as editing your version of | 6547 | Changing the listed common targets is as easy as editing your version of |
5757 | ``conf-notes.txt`` in your custom template configuration directory and | 6548 | ``conf-notes.txt`` in your custom template configuration directory and |
@@ -5764,8 +6555,12 @@ Conserving Disk Space During Builds | |||
5764 | 6555 | ||
5765 | To help conserve disk space during builds, you can add the following | 6556 | To help conserve disk space during builds, you can add the following |
5766 | statement to your project's ``local.conf`` configuration file found in | 6557 | statement to your project's ``local.conf`` configuration file found in |
5767 | the :term:`Build Directory`: INHERIT | 6558 | the :term:`Build Directory`: |
5768 | += "rm_work" Adding this statement deletes the work directory used for | 6559 | :: |
6560 | |||
6561 | INHERIT += "rm_work" | ||
6562 | |||
6563 | Adding this statement deletes the work directory used for | ||
5769 | building a recipe once the recipe is built. For more information on | 6564 | building a recipe once the recipe is built. For more information on |
5770 | "rm_work", see the | 6565 | "rm_work", see the |
5771 | :ref:`rm_work <ref-classes-rm-work>` class in the | 6566 | :ref:`rm_work <ref-classes-rm-work>` class in the |
@@ -5925,7 +6720,7 @@ revision, respectively). The values are highly dependent on the policies | |||
5925 | and procedures of a given distribution and package feed. | 6720 | and procedures of a given distribution and package feed. |
5926 | 6721 | ||
5927 | Because the OpenEmbedded build system uses | 6722 | Because the OpenEmbedded build system uses |
5928 | "`signatures <&YOCTO_DOCS_OM_URL;#overview-checksums>`__", which are | 6723 | ":ref:`signatures <overview-checksums>`", which are |
5929 | unique to a given build, the build system knows when to rebuild | 6724 | unique to a given build, the build system knows when to rebuild |
5930 | packages. All the inputs into a given task are represented by a | 6725 | packages. All the inputs into a given task are represented by a |
5931 | signature, which can trigger a rebuild when different. Thus, the build | 6726 | signature, which can trigger a rebuild when different. Thus, the build |
@@ -5953,8 +6748,12 @@ The simplest form for a PR Service is for it to exist for a single host | |||
5953 | development system that builds the package feed (building system). For | 6748 | development system that builds the package feed (building system). For |
5954 | this scenario, you can enable a local PR Service by setting | 6749 | this scenario, you can enable a local PR Service by setting |
5955 | :term:`PRSERV_HOST` in your | 6750 | :term:`PRSERV_HOST` in your |
5956 | ``local.conf`` file in the :term:`Build Directory`: PRSERV_HOST = | 6751 | ``local.conf`` file in the :term:`Build Directory`: |
5957 | "localhost:0" Once the service is started, packages will automatically | 6752 | :: |
6753 | |||
6754 | PRSERV_HOST = "localhost:0" | ||
6755 | |||
6756 | Once the service is started, packages will automatically | ||
5958 | get increasing ``PR`` values and BitBake takes care of starting and | 6757 | get increasing ``PR`` values and BitBake takes care of starting and |
5959 | stopping the server. | 6758 | stopping the server. |
5960 | 6759 | ||
@@ -5962,7 +6761,11 @@ If you have a more complex setup where multiple host development systems | |||
5962 | work against a common, shared package feed, you have a single PR Service | 6761 | work against a common, shared package feed, you have a single PR Service |
5963 | running and it is connected to each building system. For this scenario, | 6762 | running and it is connected to each building system. For this scenario, |
5964 | you need to start the PR Service using the ``bitbake-prserv`` command: | 6763 | you need to start the PR Service using the ``bitbake-prserv`` command: |
5965 | bitbake-prserv --host ip --port port --start In addition to | 6764 | :: |
6765 | |||
6766 | bitbake-prserv --host ip --port port --start | ||
6767 | |||
6768 | In addition to | ||
5966 | hand-starting the service, you need to update the ``local.conf`` file of | 6769 | hand-starting the service, you need to update the ``local.conf`` file of |
5967 | each building system as described earlier so each system points to the | 6770 | each building system as described earlier so each system points to the |
5968 | server and port. | 6771 | server and port. |
@@ -5970,9 +6773,14 @@ server and port. | |||
5970 | It is also recommended you use build history, which adds some sanity | 6773 | It is also recommended you use build history, which adds some sanity |
5971 | checks to binary package versions, in conjunction with the server that | 6774 | checks to binary package versions, in conjunction with the server that |
5972 | is running the PR Service. To enable build history, add the following to | 6775 | is running the PR Service. To enable build history, add the following to |
5973 | each building system's ``local.conf`` file: # It is recommended to | 6776 | each building system's ``local.conf`` file: |
5974 | activate "buildhistory" for testing the PR service INHERIT += | 6777 | :: |
5975 | "buildhistory" BUILDHISTORY_COMMIT = "1" For information on build | 6778 | |
6779 | # It is recommended to activate "buildhistory" for testing the PR service | ||
6780 | INHERIT += "buildhistory" | ||
6781 | BUILDHISTORY_COMMIT = "1" | ||
6782 | |||
6783 | For information on build | ||
5976 | history, see the "`Maintaining Build Output | 6784 | history, see the "`Maintaining Build Output |
5977 | Quality <#maintaining-build-output-quality>`__" section. | 6785 | Quality <#maintaining-build-output-quality>`__" section. |
5978 | 6786 | ||
@@ -5985,9 +6793,9 @@ Quality <#maintaining-build-output-quality>`__" section. | |||
5985 | run a PR Service on any of your building systems. Having some systems | 6793 | run a PR Service on any of your building systems. Having some systems |
5986 | use a PR Service while others do not leads to obvious problems. | 6794 | use a PR Service while others do not leads to obvious problems. |
5987 | 6795 | ||
5988 | For more information on shared state, see the "`Shared State | 6796 | For more information on shared state, see the |
5989 | Cache <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__" section in the | 6797 | ":ref:`overview-manual/overview-manual-concepts:shared state cache`" |
5990 | Yocto Project Overview and Concepts Manual. | 6798 | section in the Yocto Project Overview and Concepts Manual. |
5991 | 6799 | ||
5992 | Manually Bumping PR | 6800 | Manually Bumping PR |
5993 | ~~~~~~~~~~~~~~~~~~~ | 6801 | ~~~~~~~~~~~~~~~~~~~ |
@@ -6037,28 +6845,45 @@ the specific source code revision from which to build. You set the | |||
6037 | ``SRCREV`` variable to | 6845 | ``SRCREV`` variable to |
6038 | :term:`AUTOREV` to cause the | 6846 | :term:`AUTOREV` to cause the |
6039 | OpenEmbedded build system to automatically use the latest revision of | 6847 | OpenEmbedded build system to automatically use the latest revision of |
6040 | the software: SRCREV = "${AUTOREV}" | 6848 | the software: |
6849 | :: | ||
6850 | |||
6851 | SRCREV = "${AUTOREV}" | ||
6041 | 6852 | ||
6042 | Furthermore, you need to reference ``SRCPV`` in ``PV`` in order to | 6853 | Furthermore, you need to reference ``SRCPV`` in ``PV`` in order to |
6043 | automatically update the version whenever the revision of the source | 6854 | automatically update the version whenever the revision of the source |
6044 | code changes. Here is an example: PV = "1.0+git${SRCPV}" The | 6855 | code changes. Here is an example: |
6045 | OpenEmbedded build system substitutes ``SRCPV`` with the following: | 6856 | :: |
6046 | AUTOINC+source_code_revision The build system replaces the ``AUTOINC`` | 6857 | |
6858 | PV = "1.0+git${SRCPV}" | ||
6859 | |||
6860 | The OpenEmbedded build system substitutes ``SRCPV`` with the following: | ||
6861 | :: | ||
6862 | |||
6863 | AUTOINC+source_code_revision | ||
6864 | |||
6865 | The build system replaces the ``AUTOINC`` | ||
6047 | with a number. The number used depends on the state of the PR Service: | 6866 | with a number. The number used depends on the state of the PR Service: |
6048 | 6867 | ||
6049 | - If PR Service is enabled, the build system increments the number, | 6868 | - If PR Service is enabled, the build system increments the number, |
6050 | which is similar to the behavior of | 6869 | which is similar to the behavior of |
6051 | :term:`PR`. This behavior results in | 6870 | :term:`PR`. This behavior results in |
6052 | linearly increasing package versions, which is desirable. Here is an | 6871 | linearly increasing package versions, which is desirable. Here is an |
6053 | example: hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk | 6872 | example: |
6054 | hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk | 6873 | :: |
6874 | |||
6875 | hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk | ||
6876 | hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk | ||
6055 | 6877 | ||
6056 | - If PR Service is not enabled, the build system replaces the | 6878 | - If PR Service is not enabled, the build system replaces the |
6057 | ``AUTOINC`` placeholder with zero (i.e. "0"). This results in | 6879 | ``AUTOINC`` placeholder with zero (i.e. "0"). This results in |
6058 | changing the package version since the source revision is included. | 6880 | changing the package version since the source revision is included. |
6059 | However, package versions are not increased linearly. Here is an | 6881 | However, package versions are not increased linearly. Here is an |
6060 | example: hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk | 6882 | example: |
6061 | hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk | 6883 | :: |
6884 | |||
6885 | hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk | ||
6886 | hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk | ||
6062 | 6887 | ||
6063 | In summary, the OpenEmbedded build system does not track the history of | 6888 | In summary, the OpenEmbedded build system does not track the history of |
6064 | binary package versions for this purpose. ``AUTOINC``, in this case, is | 6889 | binary package versions for this purpose. ``AUTOINC``, in this case, is |
@@ -6095,11 +6920,17 @@ package for each one it finds by appending to the | |||
6095 | :term:`PACKAGES` variable and | 6920 | :term:`PACKAGES` variable and |
6096 | setting the appropriate values for ``FILES_packagename``, | 6921 | setting the appropriate values for ``FILES_packagename``, |
6097 | ``RDEPENDS_packagename``, ``DESCRIPTION_packagename``, and so forth. | 6922 | ``RDEPENDS_packagename``, ``DESCRIPTION_packagename``, and so forth. |
6098 | Here is an example from the ``lighttpd`` recipe: python | 6923 | Here is an example from the ``lighttpd`` recipe: |
6099 | populate_packages_prepend () { lighttpd_libdir = d.expand('${libdir}') | 6924 | :: |
6100 | do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$', | 6925 | |
6101 | 'lighttpd-module-%s', 'Lighttpd module for %s', extra_depends='') } The | 6926 | python populate_packages_prepend () { |
6102 | previous example specifies a number of things in the call to | 6927 | lighttpd_libdir = d.expand('${libdir}') |
6928 | do_split_packages(d, lighttpd_libdir, '^mod_(.*).so$', | ||
6929 | 'lighttpd-module-%s', 'Lighttpd module for %s', | ||
6930 | extra_depends='') | ||
6931 | } | ||
6932 | |||
6933 | The previous example specifies a number of things in the call to | ||
6103 | ``do_split_packages``. | 6934 | ``do_split_packages``. |
6104 | 6935 | ||
6105 | - A directory within the files installed by your recipe through | 6936 | - A directory within the files installed by your recipe through |
@@ -6129,40 +6960,90 @@ multiple times if you have more than one set of modules to package. | |||
6129 | 6960 | ||
6130 | For more examples that show how to use ``do_split_packages``, see the | 6961 | For more examples that show how to use ``do_split_packages``, see the |
6131 | ``connman.inc`` file in the ``meta/recipes-connectivity/connman/`` | 6962 | ``connman.inc`` file in the ``meta/recipes-connectivity/connman/`` |
6132 | directory of the ``poky`` `source | 6963 | directory of the ``poky`` :ref:`source repository <yocto-project-repositories>`. You can |
6133 | repository <&YOCTO_DOCS_OM_URL;#yocto-project-repositories>`__. You can | ||
6134 | also find examples in ``meta/classes/kernel.bbclass``. | 6964 | also find examples in ``meta/classes/kernel.bbclass``. |
6135 | 6965 | ||
6136 | Following is a reference that shows ``do_split_packages`` mandatory and | 6966 | Following is a reference that shows ``do_split_packages`` mandatory and |
6137 | optional arguments: Mandatory arguments root The path in which to search | 6967 | optional arguments: |
6138 | file_regex Regular expression to match searched files. Use parentheses | 6968 | :: |
6139 | () to mark the part of this expression that should be used to derive the | 6969 | |
6140 | module name (to be substituted where %s is used in other function | 6970 | Mandatory arguments |
6141 | arguments as noted below) output_pattern Pattern to use for the package | 6971 | |
6142 | names. Must include %s. description Description to set for each package. | 6972 | root |
6143 | Must include %s. Optional arguments postinst Postinstall script to use | 6973 | The path in which to search |
6144 | for all packages (as a string) recursive True to perform a recursive | 6974 | file_regex |
6145 | search - default False hook A hook function to be called for every | 6975 | Regular expression to match searched files. |
6146 | match. The function will be called with the following arguments (in the | 6976 | Use parentheses () to mark the part of this |
6147 | order listed): f Full path to the file/directory match pkg The package | 6977 | expression that should be used to derive the |
6148 | name file_regex As above output_pattern As above modulename The module | 6978 | module name (to be substituted where %s is |
6149 | name derived using file_regex extra_depends Extra runtime dependencies | 6979 | used in other function arguments as noted below) |
6150 | (RDEPENDS) to be set for all packages. The default value of None causes | 6980 | output_pattern |
6151 | a dependency on the main package (${PN}) - if you do not want this, pass | 6981 | Pattern to use for the package names. Must |
6152 | empty string '' for this parameter. aux_files_pattern Extra item(s) to | 6982 | include %s. |
6153 | be added to FILES for each package. Can be a single string item or a | 6983 | description |
6154 | list of strings for multiple items. Must include %s. postrm postrm | 6984 | Description to set for each package. Must |
6155 | script to use for all packages (as a string) allow_dirs True to allow | 6985 | include %s. |
6156 | directories to be matched - default False prepend If True, prepend | 6986 | |
6157 | created packages to PACKAGES instead of the default False which appends | 6987 | Optional arguments |
6158 | them match_path match file_regex on the whole relative path to the root | 6988 | |
6159 | rather than just the file name aux_files_pattern_verbatim Extra item(s) | 6989 | postinst |
6160 | to be added to FILES for each package, using the actual derived module | 6990 | Postinstall script to use for all packages |
6161 | name rather than converting it to something legal for a package name. | 6991 | (as a string) |
6162 | Can be a single string item or a list of strings for multiple items. | 6992 | recursive |
6163 | Must include %s. allow_links True to allow symlinks to be matched - | 6993 | True to perform a recursive search - default |
6164 | default False summary Summary to set for each package. Must include %s; | 6994 | False |
6165 | defaults to description if not set. | 6995 | hook |
6996 | A hook function to be called for every match. | ||
6997 | The function will be called with the following | ||
6998 | arguments (in the order listed): | ||
6999 | |||
7000 | f | ||
7001 | Full path to the file/directory match | ||
7002 | pkg | ||
7003 | The package name | ||
7004 | file_regex | ||
7005 | As above | ||
7006 | output_pattern | ||
7007 | As above | ||
7008 | modulename | ||
7009 | The module name derived using file_regex | ||
7010 | extra_depends | ||
7011 | Extra runtime dependencies (RDEPENDS) to be | ||
7012 | set for all packages. The default value of None | ||
7013 | causes a dependency on the main package | ||
7014 | (${PN}) - if you do not want this, pass empty | ||
7015 | string '' for this parameter. | ||
7016 | aux_files_pattern | ||
7017 | Extra item(s) to be added to FILES for each | ||
7018 | package. Can be a single string item or a list | ||
7019 | of strings for multiple items. Must include %s. | ||
7020 | postrm | ||
7021 | postrm script to use for all packages (as a | ||
7022 | string) | ||
7023 | allow_dirs | ||
7024 | True to allow directories to be matched - | ||
7025 | default False | ||
7026 | prepend | ||
7027 | If True, prepend created packages to PACKAGES | ||
7028 | instead of the default False which appends them | ||
7029 | match_path | ||
7030 | match file_regex on the whole relative path to | ||
7031 | the root rather than just the file name | ||
7032 | aux_files_pattern_verbatim | ||
7033 | Extra item(s) to be added to FILES for each | ||
7034 | package, using the actual derived module name | ||
7035 | rather than converting it to something legal | ||
7036 | for a package name. Can be a single string item | ||
7037 | or a list of strings for multiple items. Must | ||
7038 | include %s. | ||
7039 | allow_links | ||
7040 | True to allow symlinks to be matched - default | ||
7041 | False | ||
7042 | summary | ||
7043 | Summary to set for each package. Must include %s; | ||
7044 | defaults to description if not set. | ||
7045 | |||
7046 | |||
6166 | 7047 | ||
6167 | Satisfying Dependencies | 7048 | Satisfying Dependencies |
6168 | ~~~~~~~~~~~~~~~~~~~~~~~ | 7049 | ~~~~~~~~~~~~~~~~~~~~~~~ |
@@ -6172,7 +7053,12 @@ any dependencies on optional modules from other recipes are satisfied by | |||
6172 | your recipe. You can be sure these dependencies are satisfied by using | 7053 | your recipe. You can be sure these dependencies are satisfied by using |
6173 | the :term:`PACKAGES_DYNAMIC` | 7054 | the :term:`PACKAGES_DYNAMIC` |
6174 | variable. Here is an example that continues with the ``lighttpd`` recipe | 7055 | variable. Here is an example that continues with the ``lighttpd`` recipe |
6175 | shown earlier: PACKAGES_DYNAMIC = "lighttpd-module-.*" The name | 7056 | shown earlier: |
7057 | :: | ||
7058 | |||
7059 | PACKAGES_DYNAMIC = "lighttpd-module-.*" | ||
7060 | |||
7061 | The name | ||
6176 | specified in the regular expression can of course be anything. In this | 7062 | specified in the regular expression can of course be anything. In this |
6177 | example, it is ``lighttpd-module-`` and is specified as the prefix to | 7063 | example, it is ``lighttpd-module-`` and is specified as the prefix to |
6178 | ensure that any :term:`RDEPENDS` and | 7064 | ensure that any :term:`RDEPENDS` and |
@@ -6262,8 +7148,12 @@ variable to specify the format: | |||
6262 | :term:`Build Directory` (e.g. | 7148 | :term:`Build Directory` (e.g. |
6263 | ``~/poky/build/conf/local.conf``). | 7149 | ``~/poky/build/conf/local.conf``). |
6264 | 7150 | ||
6265 | 2. Select the desired package format as follows: PACKAGE_CLASSES ?= | 7151 | 2. Select the desired package format as follows: |
6266 | “package_packageformat” where packageformat can be "ipk", "rpm", | 7152 | :: |
7153 | |||
7154 | PACKAGE_CLASSES ?= “package_packageformat” | ||
7155 | |||
7156 | where packageformat can be "ipk", "rpm", | ||
6267 | "deb", or "tar" which are the supported package formats. | 7157 | "deb", or "tar" which are the supported package formats. |
6268 | 7158 | ||
6269 | .. note:: | 7159 | .. note:: |
@@ -6293,9 +7183,19 @@ target's package database(s) later once your image is up and running. | |||
6293 | Whenever you perform any sort of build step that can potentially | 7183 | Whenever you perform any sort of build step that can potentially |
6294 | generate a package or modify existing package, it is always a good idea | 7184 | generate a package or modify existing package, it is always a good idea |
6295 | to re-generate the package index after the build by using the following | 7185 | to re-generate the package index after the build by using the following |
6296 | command: $ bitbake package-index It might be tempting to build the | 7186 | command: |
7187 | :: | ||
7188 | |||
7189 | $ bitbake package-index | ||
7190 | |||
7191 | It might be tempting to build the | ||
6297 | package and the package index at the same time with a command such as | 7192 | package and the package index at the same time with a command such as |
6298 | the following: $ bitbake some-package package-index Do not do this as | 7193 | the following: |
7194 | :: | ||
7195 | |||
7196 | $ bitbake some-package package-index | ||
7197 | |||
7198 | Do not do this as | ||
6299 | BitBake does not schedule the package index for after the completion of | 7199 | BitBake does not schedule the package index for after the completion of |
6300 | the package you are building. Consequently, you cannot be sure of the | 7200 | the package you are building. Consequently, you cannot be sure of the |
6301 | package index including information for the package you just built. | 7201 | package index including information for the package you just built. |
@@ -6341,8 +7241,11 @@ your packaging choice (i.e. the | |||
6341 | :term:`PACKAGE_CLASSES` | 7241 | :term:`PACKAGE_CLASSES` |
6342 | setting), simply start the server. The following example assumes a build | 7242 | setting), simply start the server. The following example assumes a build |
6343 | directory of ``~/poky/build/tmp/deploy/rpm`` and a ``PACKAGE_CLASSES`` | 7243 | directory of ``~/poky/build/tmp/deploy/rpm`` and a ``PACKAGE_CLASSES`` |
6344 | setting of "package_rpm": $ cd ~/poky/build/tmp/deploy/rpm $ python -m | 7244 | setting of "package_rpm": |
6345 | SimpleHTTPServer | 7245 | :: |
7246 | |||
7247 | $ cd ~/poky/build/tmp/deploy/rpm | ||
7248 | $ python -m SimpleHTTPServer | ||
6346 | 7249 | ||
6347 | .. _runtime-package-management-target: | 7250 | .. _runtime-package-management-target: |
6348 | 7251 | ||
@@ -6369,9 +7272,7 @@ the steps in this section if you want to use runtime package management. | |||
6369 | 7272 | ||
6370 | .. note:: | 7273 | .. note:: |
6371 | 7274 | ||
6372 | For information on the | 7275 | For information on the PACKAGE_FEED_* variables, see |
6373 | PACKAGE_FEED_\* | ||
6374 | variables, see | ||
6375 | PACKAGE_FEED_ARCHS | 7276 | PACKAGE_FEED_ARCHS |
6376 | , | 7277 | , |
6377 | PACKAGE_FEED_BASE_PATHS | 7278 | PACKAGE_FEED_BASE_PATHS |
@@ -6407,19 +7308,33 @@ for all architectures. You cannot do both: | |||
6407 | 7308 | ||
6408 | - *Create an Explicit List of Architectures:* Define individual base | 7309 | - *Create an Explicit List of Architectures:* Define individual base |
6409 | URLs to identify where each package database is located: | 7310 | URLs to identify where each package database is located: |
6410 | [oe-packages] baseurl=http://my.server/rpm/i586 | 7311 | :: |
6411 | http://my.server/rpm/qemux86 http://my.server/rpm/all This example | 7312 | |
7313 | [oe-packages] | ||
7314 | baseurl=http://my.server/rpm/i586 http://my.server/rpm/qemux86 http://my.server/rpm/all | ||
7315 | |||
7316 | This example | ||
6412 | informs DNF about individual package databases for all three | 7317 | informs DNF about individual package databases for all three |
6413 | architectures. | 7318 | architectures. |
6414 | 7319 | ||
6415 | - *Create a Single (Full) Package Index:* Define a single base URL that | 7320 | - *Create a Single (Full) Package Index:* Define a single base URL that |
6416 | identifies where a full package database is located: [oe-packages] | 7321 | identifies where a full package database is located: |
6417 | baseurl=http://my.server/rpm This example informs DNF about a single | 7322 | :: |
7323 | |||
7324 | [oe-packages] | ||
7325 | baseurl=http://my.server/rpm | ||
7326 | |||
7327 | This example informs DNF about a single | ||
6418 | package database that contains all the package index information for | 7328 | package database that contains all the package index information for |
6419 | all supported architectures. | 7329 | all supported architectures. |
6420 | 7330 | ||
6421 | Once you have informed DNF where to find the package databases, you need | 7331 | Once you have informed DNF where to find the package databases, you need |
6422 | to fetch them: # dnf makecache DNF is now able to find, install, and | 7332 | to fetch them: |
7333 | :: | ||
7334 | |||
7335 | # dnf makecache | ||
7336 | |||
7337 | DNF is now able to find, install, and | ||
6423 | upgrade packages from the specified repository or repositories. | 7338 | upgrade packages from the specified repository or repositories. |
6424 | 7339 | ||
6425 | .. note:: | 7340 | .. note:: |
@@ -6452,9 +7367,14 @@ As an example, suppose you are serving packages from a ``ipk/`` | |||
6452 | directory containing the ``i586``, ``all``, and ``qemux86`` databases | 7367 | directory containing the ``i586``, ``all``, and ``qemux86`` databases |
6453 | through an HTTP server named ``my.server``. On the target, create a | 7368 | through an HTTP server named ``my.server``. On the target, create a |
6454 | configuration file (e.g. ``my_repo.conf``) inside the ``/etc/opkg/`` | 7369 | configuration file (e.g. ``my_repo.conf``) inside the ``/etc/opkg/`` |
6455 | directory containing the following: src/gz all http://my.server/ipk/all | 7370 | directory containing the following: |
6456 | src/gz i586 http://my.server/ipk/i586 src/gz qemux86 | 7371 | :: |
6457 | http://my.server/ipk/qemux86 Next, instruct ``opkg`` to fetch the | 7372 | |
7373 | src/gz all http://my.server/ipk/all | ||
7374 | src/gz i586 http://my.server/ipk/i586 | ||
7375 | src/gz qemux86 http://my.server/ipk/qemux86 | ||
7376 | |||
7377 | Next, instruct ``opkg`` to fetch the | ||
6458 | repository information: # opkg update The ``opkg`` application is now | 7378 | repository information: # opkg update The ``opkg`` application is now |
6459 | able to find, install, and upgrade packages from the specified | 7379 | able to find, install, and upgrade packages from the specified |
6460 | repository. | 7380 | repository. |
@@ -6480,10 +7400,20 @@ list file (e.g. ``my_repo.list``) inside the | |||
6480 | ``/etc/apt/sources.list.d/`` directory. As an example, suppose you are | 7400 | ``/etc/apt/sources.list.d/`` directory. As an example, suppose you are |
6481 | serving packages from a ``deb/`` directory containing the ``i586``, | 7401 | serving packages from a ``deb/`` directory containing the ``i586``, |
6482 | ``all``, and ``qemux86`` databases through an HTTP server named | 7402 | ``all``, and ``qemux86`` databases through an HTTP server named |
6483 | ``my.server``. The list file should contain: deb | 7403 | ``my.server``. The list file should contain: |
6484 | http://my.server/deb/all ./ deb http://my.server/deb/i586 ./ deb | 7404 | :: |
6485 | http://my.server/deb/qemux86 ./ Next, instruct the ``apt`` application | 7405 | |
6486 | to fetch the repository information: # apt-get update After this step, | 7406 | deb http://my.server/deb/all ./ |
7407 | deb http://my.server/deb/i586 ./ | ||
7408 | deb http://my.server/deb/qemux86 ./ | ||
7409 | |||
7410 | Next, instruct the ``apt`` application | ||
7411 | to fetch the repository information: | ||
7412 | :: | ||
7413 | |||
7414 | # apt-get update | ||
7415 | |||
7416 | After this step, | ||
6487 | ``apt`` is able to find, install, and upgrade packages from the | 7417 | ``apt`` is able to find, install, and upgrade packages from the |
6488 | specified repository. | 7418 | specified repository. |
6489 | 7419 | ||
@@ -6503,10 +7433,15 @@ Signing RPM Packages | |||
6503 | 7433 | ||
6504 | To enable signing RPM packages, you must set up the following | 7434 | To enable signing RPM packages, you must set up the following |
6505 | configurations in either your ``local.config`` or ``distro.config`` | 7435 | configurations in either your ``local.config`` or ``distro.config`` |
6506 | file: # Inherit sign_rpm.bbclass to enable signing functionality INHERIT | 7436 | file: |
6507 | += " sign_rpm" # Define the GPG key that will be used for signing. | 7437 | :: |
6508 | RPM_GPG_NAME = "key_name" # Provide passphrase for the key | 7438 | |
6509 | RPM_GPG_PASSPHRASE = "passphrase" | 7439 | # Inherit sign_rpm.bbclass to enable signing functionality |
7440 | INHERIT += " sign_rpm" | ||
7441 | # Define the GPG key that will be used for signing. | ||
7442 | RPM_GPG_NAME = "key_name" | ||
7443 | # Provide passphrase for the key | ||
7444 | RPM_GPG_PASSPHRASE = "passphrase" | ||
6510 | 7445 | ||
6511 | .. note:: | 7446 | .. note:: |
6512 | 7447 | ||
@@ -6518,10 +7453,10 @@ RPM_GPG_PASSPHRASE = "passphrase" | |||
6518 | Aside from the ``RPM_GPG_NAME`` and ``RPM_GPG_PASSPHRASE`` variables in | 7453 | Aside from the ``RPM_GPG_NAME`` and ``RPM_GPG_PASSPHRASE`` variables in |
6519 | the previous example, two optional variables related to signing exist: | 7454 | the previous example, two optional variables related to signing exist: |
6520 | 7455 | ||
6521 | - *``GPG_BIN``:* Specifies a ``gpg`` binary/wrapper that is executed | 7456 | - *GPG_BIN:* Specifies a ``gpg`` binary/wrapper that is executed |
6522 | when the package is signed. | 7457 | when the package is signed. |
6523 | 7458 | ||
6524 | - *``GPG_PATH``:* Specifies the ``gpg`` home directory used when the | 7459 | - *GPG_PATH:* Specifies the ``gpg`` home directory used when the |
6525 | package is signed. | 7460 | package is signed. |
6526 | 7461 | ||
6527 | Processing Package Feeds | 7462 | Processing Package Feeds |
@@ -6532,9 +7467,13 @@ signed package feeds for IPK and RPM packages. | |||
6532 | 7467 | ||
6533 | The steps you need to take to enable signed package feed use are similar | 7468 | The steps you need to take to enable signed package feed use are similar |
6534 | to the steps used to sign RPM packages. You must define the following in | 7469 | to the steps used to sign RPM packages. You must define the following in |
6535 | your ``local.config`` or ``distro.config`` file: INHERIT += | 7470 | your ``local.config`` or ``distro.config`` file: |
6536 | "sign_package_feed" PACKAGE_FEED_GPG_NAME = "key_name" | 7471 | :: |
6537 | PACKAGE_FEED_GPG_PASSPHRASE_FILE = "path_to_file_containing_passphrase" | 7472 | |
7473 | INHERIT += "sign_package_feed" | ||
7474 | PACKAGE_FEED_GPG_NAME = "key_name" | ||
7475 | PACKAGE_FEED_GPG_PASSPHRASE_FILE = "path_to_file_containing_passphrase" | ||
7476 | |||
6538 | For signed package feeds, the passphrase must exist in a separate file, | 7477 | For signed package feeds, the passphrase must exist in a separate file, |
6539 | which is pointed to by the ``PACKAGE_FEED_GPG_PASSPHRASE_FILE`` | 7478 | which is pointed to by the ``PACKAGE_FEED_GPG_PASSPHRASE_FILE`` |
6540 | variable. Regarding security, keeping a plain text passphrase out of the | 7479 | variable. Regarding security, keeping a plain text passphrase out of the |
@@ -6544,13 +7483,13 @@ Aside from the ``PACKAGE_FEED_GPG_NAME`` and | |||
6544 | ``PACKAGE_FEED_GPG_PASSPHRASE_FILE`` variables, three optional variables | 7483 | ``PACKAGE_FEED_GPG_PASSPHRASE_FILE`` variables, three optional variables |
6545 | related to signed package feeds exist: | 7484 | related to signed package feeds exist: |
6546 | 7485 | ||
6547 | - *``GPG_BIN``:* Specifies a ``gpg`` binary/wrapper that is executed | 7486 | - *GPG_BIN* Specifies a ``gpg`` binary/wrapper that is executed |
6548 | when the package is signed. | 7487 | when the package is signed. |
6549 | 7488 | ||
6550 | - *``GPG_PATH``:* Specifies the ``gpg`` home directory used when the | 7489 | - *GPG_PATH:* Specifies the ``gpg`` home directory used when the |
6551 | package is signed. | 7490 | package is signed. |
6552 | 7491 | ||
6553 | - *``PACKAGE_FEED_GPG_SIGNATURE_TYPE``:* Specifies the type of ``gpg`` | 7492 | - *PACKAGE_FEED_GPG_SIGNATURE_TYPE:* Specifies the type of ``gpg`` |
6554 | signature. This variable applies only to RPM and IPK package feeds. | 7493 | signature. This variable applies only to RPM and IPK package feeds. |
6555 | Allowable values for the ``PACKAGE_FEED_GPG_SIGNATURE_TYPE`` are | 7494 | Allowable values for the ``PACKAGE_FEED_GPG_SIGNATURE_TYPE`` are |
6556 | "ASC", which is the default and specifies ascii armored, and "BIN", | 7495 | "ASC", which is the default and specifies ascii armored, and "BIN", |
@@ -6568,8 +7507,12 @@ hand, the test can be anything from a simple shell script that runs a | |||
6568 | binary and checks the output to an elaborate system of test binaries and | 7507 | binary and checks the output to an elaborate system of test binaries and |
6569 | data files. | 7508 | data files. |
6570 | 7509 | ||
6571 | The test generates output in the format used by Automake: result: | 7510 | The test generates output in the format used by Automake: |
6572 | testname where the result can be ``PASS``, ``FAIL``, or ``SKIP``, and | 7511 | :: |
7512 | |||
7513 | result: testname | ||
7514 | |||
7515 | where the result can be ``PASS``, ``FAIL``, or ``SKIP``, and | ||
6573 | the testname can be any identifying string. | 7516 | the testname can be any identifying string. |
6574 | 7517 | ||
6575 | For a list of Yocto Project recipes that are already enabled with ptest, | 7518 | For a list of Yocto Project recipes that are already enabled with ptest, |
@@ -6589,7 +7532,11 @@ To add package testing to your build, add the | |||
6589 | :term:`EXTRA_IMAGE_FEATURES` | 7532 | :term:`EXTRA_IMAGE_FEATURES` |
6590 | variables to your ``local.conf`` file, which is found in the | 7533 | variables to your ``local.conf`` file, which is found in the |
6591 | :term:`Build Directory`: | 7534 | :term:`Build Directory`: |
6592 | DISTRO_FEATURES_append = " ptest" EXTRA_IMAGE_FEATURES += "ptest-pkgs" | 7535 | :: |
7536 | |||
7537 | DISTRO_FEATURES_append = " ptest" | ||
7538 | EXTRA_IMAGE_FEATURES += "ptest-pkgs" | ||
7539 | |||
6593 | Once your build is complete, the ptest files are installed into the | 7540 | Once your build is complete, the ptest files are installed into the |
6594 | ``/usr/lib/package/ptest`` directory within the image, where ``package`` | 7541 | ``/usr/lib/package/ptest`` directory within the image, where ``package`` |
6595 | is the name of the package. | 7542 | is the name of the package. |
@@ -6610,13 +7557,20 @@ test. Here is what you have to do for each recipe: | |||
6610 | 7557 | ||
6611 | - *Be sure the recipe inherits | 7558 | - *Be sure the recipe inherits |
6612 | the*\ :ref:`ptest <ref-classes-ptest>`\ *class:* | 7559 | the*\ :ref:`ptest <ref-classes-ptest>`\ *class:* |
6613 | Include the following line in each recipe: inherit ptest | 7560 | Include the following line in each recipe: |
7561 | :: | ||
7562 | |||
7563 | inherit ptest | ||
6614 | 7564 | ||
6615 | - *Create ``run-ptest``:* This script starts your test. Locate the | 7565 | - *Create run-ptest:* This script starts your test. Locate the |
6616 | script where you will refer to it using | 7566 | script where you will refer to it using |
6617 | :term:`SRC_URI`. Here is an | 7567 | :term:`SRC_URI`. Here is an |
6618 | example that starts a test for ``dbus``: #!/bin/sh cd test make -k | 7568 | example that starts a test for ``dbus``: |
6619 | runtest-TESTS | 7569 | :: |
7570 | |||
7571 | #!/bin/sh | ||
7572 | cd test | ||
7573 | make -k runtest-TESTS | ||
6620 | 7574 | ||
6621 | - *Ensure dependencies are met:* If the test adds build or runtime | 7575 | - *Ensure dependencies are met:* If the test adds build or runtime |
6622 | dependencies that normally do not exist for the package (such as | 7576 | dependencies that normally do not exist for the package (such as |
@@ -6625,7 +7579,9 @@ test. Here is what you have to do for each recipe: | |||
6625 | :term:`RDEPENDS` variables in | 7579 | :term:`RDEPENDS` variables in |
6626 | your recipe in order for the package to meet the dependencies. Here | 7580 | your recipe in order for the package to meet the dependencies. Here |
6627 | is an example where the package has a runtime dependency on "make": | 7581 | is an example where the package has a runtime dependency on "make": |
6628 | RDEPENDS_${PN}-ptest += "make" | 7582 | :: |
7583 | |||
7584 | RDEPENDS_${PN}-ptest += "make" | ||
6629 | 7585 | ||
6630 | - *Add a function to build the test suite:* Not many packages support | 7586 | - *Add a function to build the test suite:* Not many packages support |
6631 | cross-compilation of their test suites. Consequently, you usually | 7587 | cross-compilation of their test suites. Consequently, you usually |
@@ -6644,7 +7600,12 @@ test. Here is what you have to do for each recipe: | |||
6644 | 7600 | ||
6645 | Regardless, you still must add a ``do_compile_ptest`` function to | 7601 | Regardless, you still must add a ``do_compile_ptest`` function to |
6646 | build the test suite. Add a function similar to the following to your | 7602 | build the test suite. Add a function similar to the following to your |
6647 | recipe: do_compile_ptest() { oe_runmake buildtest-TESTS } | 7603 | recipe: |
7604 | :: | ||
7605 | |||
7606 | do_compile_ptest() { | ||
7607 | oe_runmake buildtest-TESTS | ||
7608 | } | ||
6648 | 7609 | ||
6649 | - *Ensure special configurations are set:* If the package requires | 7610 | - *Ensure special configurations are set:* If the package requires |
6650 | special configurations prior to compiling the test code, you must | 7611 | special configurations prior to compiling the test code, you must |
@@ -6663,7 +7624,7 @@ Creating Node Package Manager (NPM) Packages | |||
6663 | manager for the JavaScript programming language. The Yocto Project | 7624 | manager for the JavaScript programming language. The Yocto Project |
6664 | supports the NPM :ref:`fetcher <bitbake:bb-fetchers>`. You can | 7625 | supports the NPM :ref:`fetcher <bitbake:bb-fetchers>`. You can |
6665 | use this fetcher in combination with | 7626 | use this fetcher in combination with |
6666 | ```devtool`` <&YOCTO_DOCS_REF_URL;#ref-devtool-reference>`__ to create | 7627 | :doc:```devtool`` <../ref-manual/ref-devtool-reference>` to create |
6667 | recipes that produce NPM packages. | 7628 | recipes that produce NPM packages. |
6668 | 7629 | ||
6669 | Two workflows exist that allow you to create NPM packages using | 7630 | Two workflows exist that allow you to create NPM packages using |
@@ -6690,11 +7651,11 @@ NPM packages: | |||
6690 | packages, the registry approach is slightly simpler. However, you | 7651 | packages, the registry approach is slightly simpler. However, you |
6691 | might consider the project approach because you do not have to | 7652 | might consider the project approach because you do not have to |
6692 | publish your module in the NPM registry | 7653 | publish your module in the NPM registry |
6693 | (```npm-registry`https://docs.npmjs.com/misc/registry), which | 7654 | (`npm-registry <https://docs.npmjs.com/misc/registry>`_), which |
6694 | is NPM's public registry. | 7655 | is NPM's public registry. |
6695 | 7656 | ||
6696 | - Be familiar with | 7657 | - Be familiar with |
6697 | ```devtool`` <&YOCTO_DOCS_REF_URL;#ref-devtool-reference>`__. | 7658 | :doc:```devtool`` <../ref-manual/ref-devtool-reference>`. |
6698 | 7659 | ||
6699 | - The NPM host tools need the native ``nodejs-npm`` package, which is | 7660 | - The NPM host tools need the native ``nodejs-npm`` package, which is |
6700 | part of the OpenEmbedded environment. You need to get the package by | 7661 | part of the OpenEmbedded environment. You need to get the package by |
@@ -6729,8 +7690,12 @@ which is a file browser web application. | |||
6729 | module version. | 7690 | module version. |
6730 | 7691 | ||
6731 | The first thing you need to do is use ``devtool`` and the NPM fetcher to | 7692 | The first thing you need to do is use ``devtool`` and the NPM fetcher to |
6732 | create the recipe: $ devtool add | 7693 | create the recipe: |
6733 | "npm://registry.npmjs.org;package=cute-files;version=1.0.2" The | 7694 | :: |
7695 | |||
7696 | $ devtool add "npm://registry.npmjs.org;package=cute-files;version=1.0.2" | ||
7697 | |||
7698 | The | ||
6734 | ``devtool add`` command runs ``recipetool create`` and uses the same | 7699 | ``devtool add`` command runs ``recipetool create`` and uses the same |
6735 | fetch URI to download each dependency and capture license details where | 7700 | fetch URI to download each dependency and capture license details where |
6736 | possible. The result is a generated recipe. | 7701 | possible. The result is a generated recipe. |
@@ -6755,19 +7720,27 @@ runs. | |||
6755 | represented in the license manifest of the image. | 7720 | represented in the license manifest of the image. |
6756 | 7721 | ||
6757 | The ``devtool edit-recipe`` command lets you take a look at the recipe: | 7722 | The ``devtool edit-recipe`` command lets you take a look at the recipe: |
6758 | $ devtool edit-recipe cute-files SUMMARY = "Turn any folder on your | 7723 | :: |
6759 | computer into a cute file browser, available on the local network." | 7724 | |
6760 | LICENSE = "MIT & ISC & Unknown" LIC_FILES_CHKSUM = | 7725 | $ devtool edit-recipe cute-files |
6761 | "file://LICENSE;md5=71d98c0a1db42956787b1909c74a86ca \\ | 7726 | SUMMARY = "Turn any folder on your computer into a cute file browser, available on the local network." |
6762 | file://node_modules/toidentifier/LICENSE;md5=1a261071a044d02eb6f2bb47f51a3502 | 7727 | LICENSE = "MIT & ISC & Unknown" |
6763 | \\ | 7728 | LIC_FILES_CHKSUM = "file://LICENSE;md5=71d98c0a1db42956787b1909c74a86ca \ |
6764 | file://node_modules/debug/LICENSE;md5=ddd815a475e7338b0be7a14d8ee35a99 | 7729 | file://node_modules/toidentifier/LICENSE;md5=1a261071a044d02eb6f2bb47f51a3502 \ |
6765 | \\ ... SRC_URI = " \\ | 7730 | file://node_modules/debug/LICENSE;md5=ddd815a475e7338b0be7a14d8ee35a99 \ |
6766 | npm://registry.npmjs.org/;package=cute-files;version=${PV} \\ | 7731 | ... |
6767 | npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \\ " S = "${WORKDIR}/npm" | 7732 | SRC_URI = " \ |
6768 | inherit npm LICENSE_${PN} = "MIT" LICENSE_${PN}-accepts = "MIT" | 7733 | npm://registry.npmjs.org/;package=cute-files;version=${PV} \ |
6769 | LICENSE_${PN}-array-flatten = "MIT" ... LICENSE_${PN}-vary = "MIT" Three | 7734 | npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \ |
6770 | key points exist in the previous example: | 7735 | " |
7736 | S = "${WORKDIR}/npm" | ||
7737 | inherit npm LICENSE_${PN} = "MIT" | ||
7738 | LICENSE_${PN}-accepts = "MIT" | ||
7739 | LICENSE_${PN}-array-flatten = "MIT" | ||
7740 | ... | ||
7741 | LICENSE_${PN}-vary = "MIT" | ||
7742 | |||
7743 | Three key points exist in the previous example: | ||
6771 | 7744 | ||
6772 | - :term:`SRC_URI` uses the NPM | 7745 | - :term:`SRC_URI` uses the NPM |
6773 | scheme so that the NPM fetcher is used. | 7746 | scheme so that the NPM fetcher is used. |
@@ -6780,13 +7753,21 @@ key points exist in the previous example: | |||
6780 | :ref:`npm <ref-classes-npm>` class to package | 7753 | :ref:`npm <ref-classes-npm>` class to package |
6781 | up all the modules. | 7754 | up all the modules. |
6782 | 7755 | ||
6783 | You can run the following command to build the ``cute-files`` package: $ | 7756 | You can run the following command to build the ``cute-files`` package: |
6784 | devtool build cute-files Remember that ``nodejs`` must be installed on | 7757 | :: |
7758 | |||
7759 | $ devtool build cute-files | ||
7760 | |||
7761 | Remember that ``nodejs`` must be installed on | ||
6785 | the target before your package. | 7762 | the target before your package. |
6786 | 7763 | ||
6787 | Assuming 192.168.7.2 for the target's IP address, use the following | 7764 | Assuming 192.168.7.2 for the target's IP address, use the following |
6788 | command to deploy your package: $ devtool deploy-target -s cute-files | 7765 | command to deploy your package: |
6789 | root@192.168.7.2 Once the package is installed on the target, you can | 7766 | :: |
7767 | |||
7768 | $ devtool deploy-target -s cute-files root@192.168.7.2 | ||
7769 | |||
7770 | Once the package is installed on the target, you can | ||
6790 | test the application: | 7771 | test the application: |
6791 | 7772 | ||
6792 | .. note:: | 7773 | .. note:: |
@@ -6797,7 +7778,12 @@ test the application: | |||
6797 | npm install | 7778 | npm install |
6798 | . | 7779 | . |
6799 | 7780 | ||
6800 | $ cd /usr/lib/node_modules/cute-files $ node cute-files.js On a browser, | 7781 | :: |
7782 | |||
7783 | $ cd /usr/lib/node_modules/cute-files | ||
7784 | $ node cute-files.js | ||
7785 | |||
7786 | On a browser, | ||
6801 | go to ``http://192.168.7.2:3000`` and you see the following: | 7787 | go to ``http://192.168.7.2:3000`` and you see the following: |
6802 | 7788 | ||
6803 | .. image:: figures/cute-files-npm-example.png | 7789 | .. image:: figures/cute-files-npm-example.png |
@@ -6821,11 +7807,22 @@ projects method, you provide ``devtool`` with an URL that points to the | |||
6821 | source files. | 7807 | source files. |
6822 | 7808 | ||
6823 | Replicating the same example, (i.e. ``cute-files``) use the following | 7809 | Replicating the same example, (i.e. ``cute-files``) use the following |
6824 | command: $ devtool add https://github.com/martinaglv/cute-files.git The | 7810 | command: |
7811 | :: | ||
7812 | |||
7813 | $ devtool add https://github.com/martinaglv/cute-files.git | ||
7814 | |||
7815 | The | ||
6825 | recipe this command generates is very similar to the recipe created in | 7816 | recipe this command generates is very similar to the recipe created in |
6826 | the previous section. However, the ``SRC_URI`` looks like the following: | 7817 | the previous section. However, the ``SRC_URI`` looks like the following: |
6827 | SRC_URI = " \\ git://github.com/martinaglv/cute-files.git;protocol=https | 7818 | :: |
6828 | \\ npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \\ " In this example, | 7819 | |
7820 | SRC_URI = " \ | ||
7821 | git://github.com/martinaglv/cute-files.git;protocol=https \ | ||
7822 | npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \ | ||
7823 | " | ||
7824 | |||
7825 | In this example, | ||
6829 | the main module is taken from the Git repository and dependents are | 7826 | the main module is taken from the Git repository and dependents are |
6830 | taken from the NPM registry. Other than those differences, the recipe is | 7827 | taken from the NPM registry. Other than those differences, the recipe is |
6831 | basically the same between the two methods. You can build and deploy the | 7828 | basically the same between the two methods. You can build and deploy the |
@@ -6900,8 +7897,12 @@ checks local directories first for existing tarballs before checking the | |||
6900 | Internet. | 7897 | Internet. |
6901 | 7898 | ||
6902 | Here is an efficient way to set it up in your ``local.conf`` file: | 7899 | Here is an efficient way to set it up in your ``local.conf`` file: |
6903 | SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/" INHERIT += | 7900 | :: |
6904 | "own-mirrors" BB_GENERATE_MIRROR_TARBALLS = "1" # BB_NO_NETWORK = "1" | 7901 | |
7902 | SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/" | ||
7903 | INHERIT += "own-mirrors" | ||
7904 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
7905 | # BB_NO_NETWORK = "1" | ||
6905 | 7906 | ||
6906 | In the previous example, the | 7907 | In the previous example, the |
6907 | :term:`BB_GENERATE_MIRROR_TARBALLS` | 7908 | :term:`BB_GENERATE_MIRROR_TARBALLS` |
@@ -6923,12 +7924,16 @@ Another technique you can use to ready yourself for a successive string | |||
6923 | of build operations, is to pre-fetch all the source files without | 7924 | of build operations, is to pre-fetch all the source files without |
6924 | actually starting a build. This technique lets you work through any | 7925 | actually starting a build. This technique lets you work through any |
6925 | download issues and ultimately gathers all the source files into your | 7926 | download issues and ultimately gathers all the source files into your |
6926 | download directory | 7927 | download directory :ref:`structure-build-downloads`, |
6927 | ```build/downloads`` <&YOCTO_DOCS_REF_URL;#structure-build-downloads>`__, | ||
6928 | which is located with :term:`DL_DIR`. | 7928 | which is located with :term:`DL_DIR`. |
6929 | 7929 | ||
6930 | Use the following BitBake command form to fetch all the necessary | 7930 | Use the following BitBake command form to fetch all the necessary |
6931 | sources without starting the build: $ bitbake target --runall=fetch This | 7931 | sources without starting the build: |
7932 | :: | ||
7933 | |||
7934 | $ bitbake target --runall=fetch | ||
7935 | |||
7936 | This | ||
6932 | variation of the BitBake command guarantees that you have all the | 7937 | variation of the BitBake command guarantees that you have all the |
6933 | sources for that BitBake target should you disconnect from the Internet | 7938 | sources for that BitBake target should you disconnect from the Internet |
6934 | and want to do the build later offline. | 7939 | and want to do the build later offline. |
@@ -6972,14 +7977,25 @@ Using systemd Exclusively | |||
6972 | ------------------------- | 7977 | ------------------------- |
6973 | 7978 | ||
6974 | Set these variables in your distribution configuration file as follows: | 7979 | Set these variables in your distribution configuration file as follows: |
6975 | DISTRO_FEATURES_append = " systemd" VIRTUAL-RUNTIME_init_manager = | 7980 | :: |
6976 | "systemd" You can also prevent the SysVinit distribution feature from | 7981 | |
7982 | DISTRO_FEATURES_append = " systemd" | ||
7983 | VIRTUAL-RUNTIME_init_manager = "systemd" | ||
7984 | |||
7985 | You can also prevent the SysVinit distribution feature from | ||
6977 | being automatically enabled as follows: | 7986 | being automatically enabled as follows: |
6978 | DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit" Doing so removes any | 7987 | :: |
7988 | |||
7989 | DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit" | ||
7990 | |||
7991 | Doing so removes any | ||
6979 | redundant SysVinit scripts. | 7992 | redundant SysVinit scripts. |
6980 | 7993 | ||
6981 | To remove initscripts from your image altogether, set this variable | 7994 | To remove initscripts from your image altogether, set this variable |
6982 | also: VIRTUAL-RUNTIME_initscripts = "" | 7995 | also: |
7996 | :: | ||
7997 | |||
7998 | VIRTUAL-RUNTIME_initscripts = "" | ||
6983 | 7999 | ||
6984 | For information on the backfill variable, see | 8000 | For information on the backfill variable, see |
6985 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. | 8001 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. |
@@ -6988,8 +8004,12 @@ Using systemd for the Main Image and Using SysVinit for the Rescue Image | |||
6988 | ------------------------------------------------------------------------ | 8004 | ------------------------------------------------------------------------ |
6989 | 8005 | ||
6990 | Set these variables in your distribution configuration file as follows: | 8006 | Set these variables in your distribution configuration file as follows: |
6991 | DISTRO_FEATURES_append = " systemd" VIRTUAL-RUNTIME_init_manager = | 8007 | :: |
6992 | "systemd" Doing so causes your main image to use the | 8008 | |
8009 | DISTRO_FEATURES_append = " systemd" | ||
8010 | VIRTUAL-RUNTIME_init_manager = "systemd" | ||
8011 | |||
8012 | Doing so causes your main image to use the | ||
6993 | ``packagegroup-core-boot.bb`` recipe and systemd. The rescue/minimal | 8013 | ``packagegroup-core-boot.bb`` recipe and systemd. The rescue/minimal |
6994 | image cannot use this package group. However, it can install SysVinit | 8014 | image cannot use this package group. However, it can install SysVinit |
6995 | and the appropriate packages will have support for both systemd and | 8015 | and the appropriate packages will have support for both systemd and |
@@ -7003,11 +8023,11 @@ Selecting a Device Manager | |||
7003 | The Yocto Project provides multiple ways to manage the device manager | 8023 | The Yocto Project provides multiple ways to manage the device manager |
7004 | (``/dev``): | 8024 | (``/dev``): |
7005 | 8025 | ||
7006 | - *Persistent and Pre-Populated\ ``/dev``:* For this case, the ``/dev`` | 8026 | - Persistent and Pre-Populated\ ``/dev``: For this case, the ``/dev`` |
7007 | directory is persistent and the required device nodes are created | 8027 | directory is persistent and the required device nodes are created |
7008 | during the build. | 8028 | during the build. |
7009 | 8029 | ||
7010 | - *Use ``devtmpfs`` with a Device Manager:* For this case, the ``/dev`` | 8030 | - Use ``devtmpfs`` with a Device Manager: For this case, the ``/dev`` |
7011 | directory is provided by the kernel as an in-memory file system and | 8031 | directory is provided by the kernel as an in-memory file system and |
7012 | is automatically populated by the kernel at runtime. Additional | 8032 | is automatically populated by the kernel at runtime. Additional |
7013 | configuration of device nodes is done in user space by a device | 8033 | configuration of device nodes is done in user space by a device |
@@ -7020,7 +8040,10 @@ Using Persistent and Pre-Populated\ ``/dev`` | |||
7020 | 8040 | ||
7021 | To use the static method for device population, you need to set the | 8041 | To use the static method for device population, you need to set the |
7022 | :term:`USE_DEVFS` variable to "0" | 8042 | :term:`USE_DEVFS` variable to "0" |
7023 | as follows: USE_DEVFS = "0" | 8043 | as follows: |
8044 | :: | ||
8045 | |||
8046 | USE_DEVFS = "0" | ||
7024 | 8047 | ||
7025 | The content of the resulting ``/dev`` directory is defined in a Device | 8048 | The content of the resulting ``/dev`` directory is defined in a Device |
7026 | Table file. The | 8049 | Table file. The |
@@ -7030,8 +8053,10 @@ machine or distro configuration file. Alternatively, you can set this | |||
7030 | variable in your ``local.conf`` configuration file. | 8053 | variable in your ``local.conf`` configuration file. |
7031 | 8054 | ||
7032 | If you do not define the ``IMAGE_DEVICE_TABLES`` variable, the default | 8055 | If you do not define the ``IMAGE_DEVICE_TABLES`` variable, the default |
7033 | ``device_table-minimal.txt`` is used: IMAGE_DEVICE_TABLES = | 8056 | ``device_table-minimal.txt`` is used: |
7034 | "device_table-mymachine.txt" | 8057 | :: |
8058 | |||
8059 | IMAGE_DEVICE_TABLES = "device_table-mymachine.txt" | ||
7035 | 8060 | ||
7036 | The population is handled by the ``makedevs`` utility during image | 8061 | The population is handled by the ``makedevs`` utility during image |
7037 | creation: | 8062 | creation: |
@@ -7043,7 +8068,12 @@ Using ``devtmpfs`` and a Device Manager | |||
7043 | 8068 | ||
7044 | To use the dynamic method for device population, you need to use (or be | 8069 | To use the dynamic method for device population, you need to use (or be |
7045 | sure to set) the :term:`USE_DEVFS` | 8070 | sure to set) the :term:`USE_DEVFS` |
7046 | variable to "1", which is the default: USE_DEVFS = "1" With this | 8071 | variable to "1", which is the default: |
8072 | :: | ||
8073 | |||
8074 | USE_DEVFS = "1" | ||
8075 | |||
8076 | With this | ||
7047 | setting, the resulting ``/dev`` directory is populated by the kernel | 8077 | setting, the resulting ``/dev`` directory is populated by the kernel |
7048 | using ``devtmpfs``. Make sure the corresponding kernel configuration | 8078 | using ``devtmpfs``. Make sure the corresponding kernel configuration |
7049 | variable ``CONFIG_DEVTMPFS`` is set when building you build a Linux | 8079 | variable ``CONFIG_DEVTMPFS`` is set when building you build a Linux |
@@ -7056,9 +8086,14 @@ To have more control over the device nodes, you can use a device manager | |||
7056 | like ``udev`` or ``busybox-mdev``. You choose the device manager by | 8086 | like ``udev`` or ``busybox-mdev``. You choose the device manager by |
7057 | defining the ``VIRTUAL-RUNTIME_dev_manager`` variable in your machine or | 8087 | defining the ``VIRTUAL-RUNTIME_dev_manager`` variable in your machine or |
7058 | distro configuration file. Alternatively, you can set this variable in | 8088 | distro configuration file. Alternatively, you can set this variable in |
7059 | your ``local.conf`` configuration file: VIRTUAL-RUNTIME_dev_manager = | 8089 | your ``local.conf`` configuration file: |
7060 | "udev" # Some alternative values # VIRTUAL-RUNTIME_dev_manager = | 8090 | :: |
7061 | "busybox-mdev" # VIRTUAL-RUNTIME_dev_manager = "systemd" | 8091 | |
8092 | VIRTUAL-RUNTIME_dev_manager = "udev" | ||
8093 | |||
8094 | # Some alternative values | ||
8095 | # VIRTUAL-RUNTIME_dev_manager = "busybox-mdev" | ||
8096 | # VIRTUAL-RUNTIME_dev_manager = "systemd" | ||
7062 | 8097 | ||
7063 | .. _platdev-appdev-srcrev: | 8098 | .. _platdev-appdev-srcrev: |
7064 | 8099 | ||
@@ -7075,31 +8110,55 @@ Subversion (SVN), Git, and Bazaar (BZR) repositories. | |||
7075 | 8110 | ||
7076 | To enable this behavior, the :term:`PV` of | 8111 | To enable this behavior, the :term:`PV` of |
7077 | the recipe needs to reference | 8112 | the recipe needs to reference |
7078 | :term:`SRCPV`. Here is an example: PV = | 8113 | :term:`SRCPV`. Here is an example: |
7079 | "1.2.3+git${SRCPV}" Then, you can add the following to your | 8114 | :: |
7080 | ``local.conf``: SRCREV_pn-PN = "${AUTOREV}" | 8115 | |
8116 | PV = "1.2.3+git${SRCPV}" | ||
8117 | |||
8118 | Then, you can add the following to your | ||
8119 | ``local.conf``: | ||
8120 | :: | ||
8121 | |||
8122 | SRCREV_pn-PN = "${AUTOREV}" | ||
8123 | |||
7081 | :term:`PN` is the name of the recipe for | 8124 | :term:`PN` is the name of the recipe for |
7082 | which you want to enable automatic source revision updating. | 8125 | which you want to enable automatic source revision updating. |
7083 | 8126 | ||
7084 | If you do not want to update your local configuration file, you can add | 8127 | If you do not want to update your local configuration file, you can add |
7085 | the following directly to the recipe to finish enabling the feature: | 8128 | the following directly to the recipe to finish enabling the feature: |
7086 | SRCREV = "${AUTOREV}" | 8129 | :: |
8130 | |||
8131 | SRCREV = "${AUTOREV}" | ||
7087 | 8132 | ||
7088 | The Yocto Project provides a distribution named ``poky-bleeding``, whose | 8133 | The Yocto Project provides a distribution named ``poky-bleeding``, whose |
7089 | configuration file contains the line: require | 8134 | configuration file contains the line: |
7090 | conf/distro/include/poky-floating-revisions.inc This line pulls in the | 8135 | :: |
8136 | |||
8137 | require conf/distro/include/poky-floating-revisions.inc | ||
8138 | |||
8139 | This line pulls in the | ||
7091 | listed include file that contains numerous lines of exactly that form: | 8140 | listed include file that contains numerous lines of exactly that form: |
7092 | #SRCREV_pn-opkg-native ?= "${AUTOREV}" #SRCREV_pn-opkg-sdk ?= | 8141 | :: |
7093 | "${AUTOREV}" #SRCREV_pn-opkg ?= "${AUTOREV}" | 8142 | |
7094 | #SRCREV_pn-opkg-utils-native ?= "${AUTOREV}" #SRCREV_pn-opkg-utils ?= | 8143 | #SRCREV_pn-opkg-native ?= "${AUTOREV}" |
7095 | "${AUTOREV}" SRCREV_pn-gconf-dbus ?= "${AUTOREV}" | 8144 | #SRCREV_pn-opkg-sdk ?= "${AUTOREV}" |
7096 | SRCREV_pn-matchbox-common ?= "${AUTOREV}" SRCREV_pn-matchbox-config-gtk | 8145 | #SRCREV_pn-opkg ?= "${AUTOREV}" |
7097 | ?= "${AUTOREV}" SRCREV_pn-matchbox-desktop ?= "${AUTOREV}" | 8146 | #SRCREV_pn-opkg-utils-native ?= "${AUTOREV}" |
7098 | SRCREV_pn-matchbox-keyboard ?= "${AUTOREV}" SRCREV_pn-matchbox-panel-2 | 8147 | #SRCREV_pn-opkg-utils ?= "${AUTOREV}" |
7099 | ?= "${AUTOREV}" SRCREV_pn-matchbox-themes-extra ?= "${AUTOREV}" | 8148 | SRCREV_pn-gconf-dbus ?= "${AUTOREV}" |
7100 | SRCREV_pn-matchbox-terminal ?= "${AUTOREV}" SRCREV_pn-matchbox-wm ?= | 8149 | SRCREV_pn-matchbox-common ?= "${AUTOREV}" |
7101 | "${AUTOREV}" SRCREV_pn-settings-daemon ?= "${AUTOREV}" | 8150 | SRCREV_pn-matchbox-config-gtk ?= "${AUTOREV}" |
7102 | SRCREV_pn-screenshot ?= "${AUTOREV}" . . . These lines allow you to | 8151 | SRCREV_pn-matchbox-desktop ?= "${AUTOREV}" |
8152 | SRCREV_pn-matchbox-keyboard ?= "${AUTOREV}" | ||
8153 | SRCREV_pn-matchbox-panel-2 ?= "${AUTOREV}" | ||
8154 | SRCREV_pn-matchbox-themes-extra ?= "${AUTOREV}" | ||
8155 | SRCREV_pn-matchbox-terminal ?= "${AUTOREV}" | ||
8156 | SRCREV_pn-matchbox-wm ?= "${AUTOREV}" | ||
8157 | SRCREV_pn-settings-daemon ?= "${AUTOREV}" | ||
8158 | SRCREV_pn-screenshot ?= "${AUTOREV}" | ||
8159 | . . . | ||
8160 | |||
8161 | These lines allow you to | ||
7103 | experiment with building a distribution that tracks the latest | 8162 | experiment with building a distribution that tracks the latest |
7104 | development source for numerous packages. | 8163 | development source for numerous packages. |
7105 | 8164 | ||
@@ -7133,21 +8192,26 @@ Creating the Root Filesystem | |||
7133 | To create the read-only root filesystem, simply add the | 8192 | To create the read-only root filesystem, simply add the |
7134 | "read-only-rootfs" feature to your image, normally in one of two ways. | 8193 | "read-only-rootfs" feature to your image, normally in one of two ways. |
7135 | The first way is to add the "read-only-rootfs" image feature in the | 8194 | The first way is to add the "read-only-rootfs" image feature in the |
7136 | image's recipe file via the ``IMAGE_FEATURES`` variable: IMAGE_FEATURES | 8195 | image's recipe file via the ``IMAGE_FEATURES`` variable: |
7137 | += "read-only-rootfs" As an alternative, you can add the same feature | 8196 | :: |
8197 | |||
8198 | IMAGE_FEATURES += "read-only-rootfs" | ||
8199 | |||
8200 | As an alternative, you can add the same feature | ||
7138 | from within your build directory's ``local.conf`` file with the | 8201 | from within your build directory's ``local.conf`` file with the |
7139 | associated ``EXTRA_IMAGE_FEATURES`` variable, as in: | 8202 | associated ``EXTRA_IMAGE_FEATURES`` variable, as in: |
7140 | EXTRA_IMAGE_FEATURES = "read-only-rootfs" | 8203 | :: |
8204 | |||
8205 | EXTRA_IMAGE_FEATURES = "read-only-rootfs" | ||
7141 | 8206 | ||
7142 | For more information on how to use these variables, see the | 8207 | For more information on how to use these variables, see the |
7143 | "`Customizing Images Using Custom ``IMAGE_FEATURES`` and | 8208 | ":ref:`usingpoky-extend-customimage-imagefeatures`" |
7144 | ``EXTRA_IMAGE_FEATURES`` <#usingpoky-extend-customimage-imagefeatures>`__" | ||
7145 | section. For information on the variables, see | 8209 | section. For information on the variables, see |
7146 | :term:`IMAGE_FEATURES` and | 8210 | :term:`IMAGE_FEATURES` and |
7147 | :term:`EXTRA_IMAGE_FEATURES`. | 8211 | :term:`EXTRA_IMAGE_FEATURES`. |
7148 | 8212 | ||
7149 | Post-Installation Scripts | 8213 | Post-Installation Scripts and Read-Only Root Filesystem |
7150 | ------------------------- | 8214 | ------------------------------------------------------- |
7151 | 8215 | ||
7152 | It is very important that you make sure all post-Installation | 8216 | It is very important that you make sure all post-Installation |
7153 | (``pkg_postinst``) scripts for packages that are installed into the | 8217 | (``pkg_postinst``) scripts for packages that are installed into the |
@@ -7234,11 +8298,16 @@ Build history is disabled by default. To enable it, add the following | |||
7234 | ``INHERIT`` statement and set the | 8298 | ``INHERIT`` statement and set the |
7235 | :term:`BUILDHISTORY_COMMIT` | 8299 | :term:`BUILDHISTORY_COMMIT` |
7236 | variable to "1" at the end of your ``conf/local.conf`` file found in the | 8300 | variable to "1" at the end of your ``conf/local.conf`` file found in the |
7237 | :term:`Build Directory`: INHERIT += | 8301 | :term:`Build Directory`: |
7238 | "buildhistory" BUILDHISTORY_COMMIT = "1" Enabling build history as | 8302 | :: |
8303 | |||
8304 | INHERIT += "buildhistory" | ||
8305 | BUILDHISTORY_COMMIT = "1" | ||
8306 | |||
8307 | Enabling build history as | ||
7239 | previously described causes the OpenEmbedded build system to collect | 8308 | previously described causes the OpenEmbedded build system to collect |
7240 | build output information and commit it as a single commit to a local | 8309 | build output information and commit it as a single commit to a local |
7241 | `Git <&YOCTO_DOCS_OM_URL;#git>`__ repository. | 8310 | :ref:`overview-manual/overview-manual-development-environment:git` repository. |
7242 | 8311 | ||
7243 | .. note:: | 8312 | .. note:: |
7244 | 8313 | ||
@@ -7273,29 +8342,41 @@ Build History Package Information | |||
7273 | The history for each package contains a text file that has name-value | 8342 | The history for each package contains a text file that has name-value |
7274 | pairs with information about the package. For example, | 8343 | pairs with information about the package. For example, |
7275 | ``buildhistory/packages/i586-poky-linux/busybox/busybox/latest`` | 8344 | ``buildhistory/packages/i586-poky-linux/busybox/busybox/latest`` |
7276 | contains the following: PV = 1.22.1 PR = r32 RPROVIDES = RDEPENDS = | 8345 | contains the following: |
7277 | glibc (>= 2.20) update-alternatives-opkg RRECOMMENDS = busybox-syslog | 8346 | :: |
7278 | busybox-udhcpc update-rc.d PKGSIZE = 540168 FILES = /usr/bin/\* | 8347 | |
7279 | /usr/sbin/\* /usr/lib/busybox/\* /usr/lib/lib*.so.\* \\ /etc /com /var | 8348 | PV = 1.22.1 |
7280 | /bin/\* /sbin/\* /lib/*.so.\* /lib/udev/rules.d \\ /usr/lib/udev/rules.d | 8349 | PR = r32 |
7281 | /usr/share/busybox /usr/lib/busybox/\* \\ /usr/share/pixmaps | 8350 | RPROVIDES = |
7282 | /usr/share/applications /usr/share/idl \\ /usr/share/omf | 8351 | RDEPENDS = glibc (>= 2.20) update-alternatives-opkg |
7283 | /usr/share/sounds /usr/lib/bonobo/servers FILELIST = /bin/busybox | 8352 | RRECOMMENDS = busybox-syslog busybox-udhcpc update-rc.d |
7284 | /bin/busybox.nosuid /bin/busybox.suid /bin/sh \\ | 8353 | PKGSIZE = 540168 |
7285 | /etc/busybox.links.nosuid /etc/busybox.links.suid Most of these | 8354 | FILES = /usr/bin/* /usr/sbin/* /usr/lib/busybox/* /usr/lib/lib*.so.* \ |
8355 | /etc /com /var /bin/* /sbin/* /lib/*.so.* /lib/udev/rules.d \ | ||
8356 | /usr/lib/udev/rules.d /usr/share/busybox /usr/lib/busybox/* \ | ||
8357 | /usr/share/pixmaps /usr/share/applications /usr/share/idl \ | ||
8358 | /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers | ||
8359 | FILELIST = /bin/busybox /bin/busybox.nosuid /bin/busybox.suid /bin/sh \ | ||
8360 | /etc/busybox.links.nosuid /etc/busybox.links.suid | ||
8361 | |||
8362 | Most of these | ||
7286 | name-value pairs correspond to variables used to produce the package. | 8363 | name-value pairs correspond to variables used to produce the package. |
7287 | The exceptions are ``FILELIST``, which is the actual list of files in | 8364 | The exceptions are ``FILELIST``, which is the actual list of files in |
7288 | the package, and ``PKGSIZE``, which is the total size of files in the | 8365 | the package, and ``PKGSIZE``, which is the total size of files in the |
7289 | package in bytes. | 8366 | package in bytes. |
7290 | 8367 | ||
7291 | A file also exists that corresponds to the recipe from which the package | 8368 | A file also exists that corresponds to the recipe from which the package |
7292 | came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``): PV | 8369 | came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``): |
7293 | = 1.22.1 PR = r32 DEPENDS = initscripts kern-tools-native | 8370 | :: |
7294 | update-rc.d-native \\ virtual/i586-poky-linux-compilerlibs | 8371 | |
7295 | virtual/i586-poky-linux-gcc \\ virtual/libc virtual/update-alternatives | 8372 | PV = 1.22.1 |
7296 | PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \\ | 8373 | PR = r32 |
7297 | busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \\ | 8374 | DEPENDS = initscripts kern-tools-native update-rc.d-native \ |
7298 | busybox-staticdev busybox-dev busybox-doc busybox-locale busybox | 8375 | virtual/i586-poky-linux-compilerlibs virtual/i586-poky-linux-gcc \ |
8376 | virtual/libc virtual/update-alternatives | ||
8377 | PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \ | ||
8378 | busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \ | ||
8379 | busybox-staticdev busybox-dev busybox-doc busybox-locale busybox | ||
7299 | 8380 | ||
7300 | Finally, for those recipes fetched from a version control system (e.g., | 8381 | Finally, for those recipes fetched from a version control system (e.g., |
7301 | Git), a file exists that lists source revisions that are specified in | 8382 | Git), a file exists that lists source revisions that are specified in |
@@ -7305,37 +8386,43 @@ and actual revisions might differ when | |||
7305 | ${:term:`AUTOREV`}. Here is an | 8386 | ${:term:`AUTOREV`}. Here is an |
7306 | example assuming | 8387 | example assuming |
7307 | ``buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev``): | 8388 | ``buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev``): |
7308 | # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" | 8389 | :: |
7309 | SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" # | 8390 | |
7310 | SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f" SRCREV_meta = | 8391 | # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" |
7311 | "a227f20eff056e511d504b2e490f3774ab260d6f" You can use the | 8392 | SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" |
8393 | # SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f" | ||
8394 | SRCREV_meta ="a227f20eff056e511d504b2e490f3774ab260d6f" | ||
8395 | |||
8396 | You can use the | ||
7312 | ``buildhistory-collect-srcrevs`` command with the ``-a`` option to | 8397 | ``buildhistory-collect-srcrevs`` command with the ``-a`` option to |
7313 | collect the stored ``SRCREV`` values from build history and report them | 8398 | collect the stored ``SRCREV`` values from build history and report them |
7314 | in a format suitable for use in global configuration (e.g., | 8399 | in a format suitable for use in global configuration (e.g., |
7315 | ``local.conf`` or a distro include file) to override floating | 8400 | ``local.conf`` or a distro include file) to override floating |
7316 | ``AUTOREV`` values to a fixed set of revisions. Here is some example | 8401 | ``AUTOREV`` values to a fixed set of revisions. Here is some example |
7317 | output from this command: $ buildhistory-collect-srcrevs -a # | 8402 | output from this command: |
7318 | i586-poky-linux SRCREV_pn-glibc = | 8403 | :: |
7319 | "b8079dd0d360648e4e8de48656c5c38972621072" SRCREV_pn-glibc-initial = | 8404 | |
7320 | "b8079dd0d360648e4e8de48656c5c38972621072" SRCREV_pn-opkg-utils = | 8405 | $ buildhistory-collect-srcrevs -a |
7321 | "53274f087565fd45d8452c5367997ba6a682a37a" SRCREV_pn-kmod = | 8406 | # i586-poky-linux |
7322 | "fd56638aed3fe147015bfa10ed4a5f7491303cb4" # x86_64-linux | 8407 | SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072" |
7323 | SRCREV_pn-gtk-doc-stub-native = | 8408 | SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072" |
7324 | "1dea266593edb766d6d898c79451ef193eb17cfa" SRCREV_pn-dtc-native = | 8409 | SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a" |
7325 | "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf" SRCREV_pn-update-rc.d-native | 8410 | SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4" |
7326 | = "eca680ddf28d024954895f59a241a622dd575c11" | 8411 | # x86_64-linux |
7327 | SRCREV_glibc_pn-cross-localedef-native = | 8412 | SRCREV_pn-gtk-doc-stub-native = "1dea266593edb766d6d898c79451ef193eb17cfa" |
7328 | "b8079dd0d360648e4e8de48656c5c38972621072" | 8413 | SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf" |
7329 | SRCREV_localedef_pn-cross-localedef-native = | 8414 | SRCREV_pn-update-rc.d-native = "eca680ddf28d024954895f59a241a622dd575c11" |
7330 | "c833367348d39dad7ba018990bfdaffaec8e9ed3" SRCREV_pn-prelink-native = | 8415 | SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072" |
7331 | "faa069deec99bf61418d0bab831c83d7c1b797ca" SRCREV_pn-opkg-utils-native = | 8416 | SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3" |
7332 | "53274f087565fd45d8452c5367997ba6a682a37a" SRCREV_pn-kern-tools-native = | 8417 | SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca" |
7333 | "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff" SRCREV_pn-kmod-native = | 8418 | SRCREV_pn-opkg-utils-native = "53274f087565fd45d8452c5367997ba6a682a37a" |
7334 | "fd56638aed3fe147015bfa10ed4a5f7491303cb4" # qemux86-poky-linux | 8419 | SRCREV_pn-kern-tools-native = "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff" |
7335 | SRCREV_machine_pn-linux-yocto = | 8420 | SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4" |
7336 | "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" SRCREV_meta_pn-linux-yocto = | 8421 | # qemux86-poky-linux |
7337 | "a227f20eff056e511d504b2e490f3774ab260d6f" # all-poky-linux | 8422 | SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" |
7338 | SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11" | 8423 | SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f" |
8424 | # all-poky-linux | ||
8425 | SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11" | ||
7339 | 8426 | ||
7340 | .. note:: | 8427 | .. note:: |
7341 | 8428 | ||
@@ -7394,17 +8481,27 @@ The files produced for each image are as follows: | |||
7394 | Installed package information is able to be gathered and produced | 8481 | Installed package information is able to be gathered and produced |
7395 | even if package management is disabled for the final image. | 8482 | even if package management is disabled for the final image. |
7396 | 8483 | ||
7397 | Here is an example of ``image-info.txt``: DISTRO = poky DISTRO_VERSION = | 8484 | Here is an example of ``image-info.txt``: |
7398 | 1.7 USER_CLASSES = buildstats image-mklibs image-prelink IMAGE_CLASSES = | 8485 | :: |
7399 | image_types IMAGE_FEATURES = debug-tweaks IMAGE_LINGUAS = IMAGE_INSTALL | 8486 | |
7400 | = packagegroup-core-boot run-postinsts BAD_RECOMMENDATIONS = | 8487 | DISTRO = poky |
7401 | NO_RECOMMENDATIONS = PACKAGE_EXCLUDE = ROOTFS_POSTPROCESS_COMMAND = | 8488 | DISTRO_VERSION = 1.7 |
7402 | write_package_manifest; license_create_manifest; \\ write_image_manifest | 8489 | USER_CLASSES = buildstats image-mklibs image-prelink |
7403 | ; buildhistory_list_installed_image ; \\ | 8490 | IMAGE_CLASSES = image_types |
7404 | buildhistory_get_image_installed ; ssh_allow_empty_password; \\ | 8491 | IMAGE_FEATURES = debug-tweaks |
7405 | postinst_enable_logging; rootfs_update_timestamp ; | 8492 | IMAGE_LINGUAS = |
7406 | ssh_disable_dns_lookup ; IMAGE_POSTPROCESS_COMMAND = | 8493 | IMAGE_INSTALL = packagegroup-core-boot run-postinsts |
7407 | buildhistory_get_imageinfo ; IMAGESIZE = 6900 Other than ``IMAGESIZE``, | 8494 | BAD_RECOMMENDATIONS = |
8495 | NO_RECOMMENDATIONS = | ||
8496 | PACKAGE_EXCLUDE = | ||
8497 | ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \ | ||
8498 | write_image_manifest ; buildhistory_list_installed_image ; \ | ||
8499 | buildhistory_get_image_installed ; ssh_allow_empty_password; \ | ||
8500 | postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ; | ||
8501 | IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; | ||
8502 | IMAGESIZE = 6900 | ||
8503 | |||
8504 | Other than ``IMAGESIZE``, | ||
7408 | which is the total size of the files in the image in Kbytes, the | 8505 | which is the total size of the files in the image in Kbytes, the |
7409 | name-value pairs are variables that may have influenced the content of | 8506 | name-value pairs are variables that may have influenced the content of |
7410 | the image. This information is often useful when you are trying to | 8507 | the image. This information is often useful when you are trying to |
@@ -7419,8 +8516,13 @@ image. If you are just interested in this information and not interested | |||
7419 | in collecting specific package or SDK information, you can enable | 8516 | in collecting specific package or SDK information, you can enable |
7420 | writing only image information without any history by adding the | 8517 | writing only image information without any history by adding the |
7421 | following to your ``conf/local.conf`` file found in the | 8518 | following to your ``conf/local.conf`` file found in the |
7422 | :term:`Build Directory`: INHERIT += | 8519 | :term:`Build Directory`: |
7423 | "buildhistory" BUILDHISTORY_COMMIT = "0" BUILDHISTORY_FEATURES = "image" | 8520 | :: |
8521 | |||
8522 | INHERIT += "buildhistory" | ||
8523 | BUILDHISTORY_COMMIT = "0" | ||
8524 | BUILDHISTORY_FEATURES = "image" | ||
8525 | |||
7424 | Here, you set the | 8526 | Here, you set the |
7425 | :term:`BUILDHISTORY_FEATURES` | 8527 | :term:`BUILDHISTORY_FEATURES` |
7426 | variable to use the image feature only. | 8528 | variable to use the image feature only. |
@@ -7486,10 +8588,19 @@ The following list shows the files produced for SDKs: | |||
7486 | - ``installed-packages.txt:`` A list of installed packages with full | 8588 | - ``installed-packages.txt:`` A list of installed packages with full |
7487 | package filenames. | 8589 | package filenames. |
7488 | 8590 | ||
7489 | Here is an example of ``sdk-info.txt``: DISTRO = poky DISTRO_VERSION = | 8591 | Here is an example of ``sdk-info.txt``: |
7490 | 1.3+snapshot-20130327 SDK_NAME = poky-glibc-i686-arm SDK_VERSION = | 8592 | :: |
7491 | 1.3+snapshot SDKMACHINE = SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs | 8593 | |
7492 | BAD_RECOMMENDATIONS = SDKSIZE = 352712 Other than ``SDKSIZE``, which is | 8594 | DISTRO = poky |
8595 | DISTRO_VERSION = 1.3+snapshot-20130327 | ||
8596 | SDK_NAME = poky-glibc-i686-arm | ||
8597 | SDK_VERSION = 1.3+snapshot | ||
8598 | SDKMACHINE = | ||
8599 | SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs | ||
8600 | BAD_RECOMMENDATIONS = | ||
8601 | SDKSIZE = 352712 | ||
8602 | |||
8603 | Other than ``SDKSIZE``, which is | ||
7493 | the total size of the files in the SDK in Kbytes, the name-value pairs | 8604 | the total size of the files in the SDK in Kbytes, the name-value pairs |
7494 | are variables that might have influenced the content of the SDK. This | 8605 | are variables that might have influenced the content of the SDK. This |
7495 | information is often useful when you are trying to determine why a | 8606 | information is often useful when you are trying to determine why a |
@@ -7502,26 +8613,36 @@ You can examine build history output from the command line or from a web | |||
7502 | interface. | 8613 | interface. |
7503 | 8614 | ||
7504 | To see any changes that have occurred (assuming you have | 8615 | To see any changes that have occurred (assuming you have |
7505 | :term:`BUILDHISTORY_COMMIT`\ `` = "1"``), | 8616 | :term:`BUILDHISTORY_COMMIT` = "1"), |
7506 | you can simply use any Git command that allows you to view the history | 8617 | you can simply use any Git command that allows you to view the history |
7507 | of a repository. Here is one method: $ git log -p You need to realize, | 8618 | of a repository. Here is one method: |
8619 | :: | ||
8620 | |||
8621 | $ git log -p | ||
8622 | |||
8623 | You need to realize, | ||
7508 | however, that this method does show changes that are not significant | 8624 | however, that this method does show changes that are not significant |
7509 | (e.g. a package's size changing by a few bytes). | 8625 | (e.g. a package's size changing by a few bytes). |
7510 | 8626 | ||
7511 | A command-line tool called ``buildhistory-diff`` does exist, though, | 8627 | A command-line tool called ``buildhistory-diff`` does exist, though, |
7512 | that queries the Git repository and prints just the differences that | 8628 | that queries the Git repository and prints just the differences that |
7513 | might be significant in human-readable form. Here is an example: $ | 8629 | might be significant in human-readable form. Here is an example: |
7514 | ~/poky/poky/scripts/buildhistory-diff . HEAD^ Changes to | 8630 | :: |
7515 | images/qemux86_64/glibc/core-image-minimal (files-in-image.txt): | 8631 | |
7516 | /etc/anotherpkg.conf was added /sbin/anotherpkg was added \* | 8632 | $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ |
7517 | (installed-package-names.txt): \* anotherpkg was added Changes to | 8633 | Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt): |
7518 | images/qemux86_64/glibc/core-image-minimal | 8634 | /etc/anotherpkg.conf was added |
7519 | (installed-package-names.txt): anotherpkg was added | 8635 | /sbin/anotherpkg was added |
7520 | packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras" \* PR | 8636 | * (installed-package-names.txt): |
7521 | changed from "r0" to "r1" \* PV changed from "0.1.10" to "0.1.12" | 8637 | * anotherpkg was added |
7522 | packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to | 8638 | Changes to images/qemux86_64/glibc/core-image-minimal (installed-package-names.txt): |
7523 | 144381 (+30%) \* PR changed from "r0" to "r1" \* PV changed from | 8639 | anotherpkg was added |
7524 | "0.1.10" to "0.1.12" | 8640 | packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras" |
8641 | * PR changed from "r0" to "r1" | ||
8642 | * PV changed from "0.1.10" to "0.1.12" | ||
8643 | packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%) | ||
8644 | * PR changed from "r0" to "r1" | ||
8645 | * PV changed from "0.1.10" to "0.1.12" | ||
7525 | 8646 | ||
7526 | .. note:: | 8647 | .. note:: |
7527 | 8648 | ||
@@ -7533,7 +8654,7 @@ packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to | |||
7533 | :: | 8654 | :: |
7534 | 8655 | ||
7535 | $ pip3 install GitPython --user | 8656 | $ pip3 install GitPython --user |
7536 | 8657 | ||
7537 | 8658 | ||
7538 | Alternatively, you can install | 8659 | Alternatively, you can install |
7539 | python3-git | 8660 | python3-git |
@@ -7566,8 +8687,7 @@ you set up the environment to use these tests, run available tests, and | |||
7566 | write and add your own tests. | 8687 | write and add your own tests. |
7567 | 8688 | ||
7568 | For information on the test and QA infrastructure available within the | 8689 | For information on the test and QA infrastructure available within the |
7569 | Yocto Project, see the "`Testing and Quality | 8690 | Yocto Project, see the ":ref:`ref-manual/ref-release-process:testing and quality assurance`" |
7570 | Assurance <&YOCTO_DOCS_REF_URL;#testing-and-quality-assurance>`__" | ||
7571 | section in the Yocto Project Reference Manual. | 8691 | section in the Yocto Project Reference Manual. |
7572 | 8692 | ||
7573 | Enabling Tests | 8693 | Enabling Tests |
@@ -7585,7 +8705,7 @@ Enabling Runtime Tests on QEMU | |||
7585 | 8705 | ||
7586 | In order to run tests, you need to do the following: | 8706 | In order to run tests, you need to do the following: |
7587 | 8707 | ||
7588 | - *Set up to avoid interaction with ``sudo`` for networking:* To | 8708 | - *Set up to avoid interaction with sudo for networking:* To |
7589 | accomplish this, you must do one of the following: | 8709 | accomplish this, you must do one of the following: |
7590 | 8710 | ||
7591 | - Add ``NOPASSWD`` for your user in ``/etc/sudoers`` either for all | 8711 | - Add ``NOPASSWD`` for your user in ``/etc/sudoers`` either for all |
@@ -7615,7 +8735,7 @@ In order to run tests, you need to do the following: | |||
7615 | this script. Build the package using the following command: | 8735 | this script. Build the package using the following command: |
7616 | $ bitbake qemu-helper-native | 8736 | $ bitbake qemu-helper-native |
7617 | 8737 | ||
7618 | - *Set the ``DISPLAY`` variable:* You need to set this variable so that | 8738 | - *Set the DISPLAY variable:* You need to set this variable so that |
7619 | you have an X server available (e.g. start ``vncserver`` for a | 8739 | you have an X server available (e.g. start ``vncserver`` for a |
7620 | headless machine). | 8740 | headless machine). |
7621 | 8741 | ||
@@ -7748,8 +8868,10 @@ not need any information in this section. You can skip down to the | |||
7748 | If you did set ``TEST_TARGET`` to "SystemdbootTarget", you also need to | 8868 | If you did set ``TEST_TARGET`` to "SystemdbootTarget", you also need to |
7749 | perform a one-time setup of your master image by doing the following: | 8869 | perform a one-time setup of your master image by doing the following: |
7750 | 8870 | ||
7751 | 1. *Set ``EFI_PROVIDER``:* Be sure that ``EFI_PROVIDER`` is as follows: | 8871 | 1. *Set EFI_PROVIDER:* Be sure that ``EFI_PROVIDER`` is as follows: |
7752 | EFI_PROVIDER = "systemd-boot" | 8872 | :: |
8873 | |||
8874 | EFI_PROVIDER = "systemd-boot" | ||
7753 | 8875 | ||
7754 | 2. *Build the master image:* Build the ``core-image-testmaster`` image. | 8876 | 2. *Build the master image:* Build the ``core-image-testmaster`` image. |
7755 | The ``core-image-testmaster`` recipe is provided as an example for a | 8877 | The ``core-image-testmaster`` recipe is provided as an example for a |
@@ -7784,13 +8906,19 @@ perform a one-time setup of your master image by doing the following: | |||
7784 | The final thing you need to do when setting ``TEST_TARGET`` to | 8906 | The final thing you need to do when setting ``TEST_TARGET`` to |
7785 | "SystemdbootTarget" is to set up the test image: | 8907 | "SystemdbootTarget" is to set up the test image: |
7786 | 8908 | ||
7787 | 1. *Set up your ``local.conf`` file:* Make sure you have the following | 8909 | 1. *Set up your local.conf file:* Make sure you have the following |
7788 | statements in your ``local.conf`` file: IMAGE_FSTYPES += "tar.gz" | 8910 | statements in your ``local.conf`` file: |
7789 | INHERIT += "testimage" TEST_TARGET = "SystemdbootTarget" | 8911 | :: |
7790 | TEST_TARGET_IP = "192.168.2.3" | 8912 | |
8913 | IMAGE_FSTYPES += "tar.gz" | ||
8914 | INHERIT += "testimage" | ||
8915 | TEST_TARGET = "SystemdbootTarget" | ||
8916 | TEST_TARGET_IP = "192.168.2.3" | ||
7791 | 8917 | ||
7792 | 2. *Build your test image:* Use BitBake to build the image: $ bitbake | 8918 | 2. *Build your test image:* Use BitBake to build the image: |
7793 | core-image-sato | 8919 | :: |
8920 | |||
8921 | $ bitbake core-image-sato | ||
7794 | 8922 | ||
7795 | Power Control | 8923 | Power Control |
7796 | ~~~~~~~~~~~~~ | 8924 | ~~~~~~~~~~~~~ |
@@ -7802,10 +8930,18 @@ power: | |||
7802 | ``TEST_POWERCONTROL_EXTRA_ARGS`` as a command that runs on the host | 8930 | ``TEST_POWERCONTROL_EXTRA_ARGS`` as a command that runs on the host |
7803 | and does power cycling. The test code passes one argument to that | 8931 | and does power cycling. The test code passes one argument to that |
7804 | command: off, on or cycle (off then on). Here is an example that | 8932 | command: off, on or cycle (off then on). Here is an example that |
7805 | could appear in your ``local.conf`` file: TEST_POWERCONTROL_CMD = | 8933 | could appear in your ``local.conf`` file: |
7806 | "powercontrol.exp test 10.11.12.1 nuc1" In this example, the expect | 8934 | :: |
7807 | script does the following: ssh test@10.11.12.1 "pyctl nuc1 arg" It | 8935 | |
7808 | then runs a Python script that controls power for a label called | 8936 | TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1" |
8937 | |||
8938 | In this example, the expect | ||
8939 | script does the following: | ||
8940 | :: | ||
8941 | |||
8942 | ssh test@10.11.12.1 "pyctl nuc1 arg" | ||
8943 | |||
8944 | It then runs a Python script that controls power for a label called | ||
7809 | ``nuc1``. | 8945 | ``nuc1``. |
7810 | 8946 | ||
7811 | .. note:: | 8947 | .. note:: |
@@ -7830,8 +8966,10 @@ dialog-power-control script that shows a dialog prompting you to perform | |||
7830 | the required power action. This script requires either KDialog or Zenity | 8966 | the required power action. This script requires either KDialog or Zenity |
7831 | to be installed. To use this script, set the | 8967 | to be installed. To use this script, set the |
7832 | :term:`TEST_POWERCONTROL_CMD` | 8968 | :term:`TEST_POWERCONTROL_CMD` |
7833 | variable as follows: TEST_POWERCONTROL_CMD = | 8969 | variable as follows: |
7834 | "${COREBASE}/scripts/contrib/dialog-power-control" | 8970 | :: |
8971 | |||
8972 | TEST_POWERCONTROL_CMD = "${COREBASE}/scripts/contrib/dialog-power-control" | ||
7835 | 8973 | ||
7836 | Serial Console Connection | 8974 | Serial Console Connection |
7837 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | 8975 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
@@ -7852,12 +8990,18 @@ command simply needs to connect to the serial console and forward that | |||
7852 | connection to standard input and output as any normal terminal program | 8990 | connection to standard input and output as any normal terminal program |
7853 | does. For example, to use the picocom terminal program on serial device | 8991 | does. For example, to use the picocom terminal program on serial device |
7854 | ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: | 8992 | ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: |
7855 | TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" For local | 8993 | :: |
8994 | |||
8995 | TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" | ||
8996 | |||
8997 | For local | ||
7856 | devices where the serial port device disappears when the device reboots, | 8998 | devices where the serial port device disappears when the device reboots, |
7857 | an additional "serdevtry" wrapper script is provided. To use this | 8999 | an additional "serdevtry" wrapper script is provided. To use this |
7858 | wrapper, simply prefix the terminal command with | 9000 | wrapper, simply prefix the terminal command with |
7859 | ``${COREBASE}/scripts/contrib/serdevtry``: TEST_SERIALCONTROL_CMD = | 9001 | ``${COREBASE}/scripts/contrib/serdevtry``: |
7860 | "${COREBASE}/scripts/contrib/serdevtry picocom -b 115200 /dev/ttyUSB0" | 9002 | :: |
9003 | |||
9004 | TEST_SERIALCONTROL_CMD = "${COREBASE}/scripts/contrib/serdevtry picocom -b 115200 /dev/ttyUSB0" | ||
7861 | 9005 | ||
7862 | .. _qemu-image-running-tests: | 9006 | .. _qemu-image-running-tests: |
7863 | 9007 | ||
@@ -7871,15 +9015,29 @@ You can start the tests automatically or manually: | |||
7871 | set the | 9015 | set the |
7872 | :term:`TESTIMAGE_AUTO` | 9016 | :term:`TESTIMAGE_AUTO` |
7873 | variable to "1" in your ``local.conf`` file in the | 9017 | variable to "1" in your ``local.conf`` file in the |
7874 | :term:`Build Directory`: TESTIMAGE_AUTO = | 9018 | :term:`Build Directory`: |
7875 | "1" Next, build your image. If the image successfully builds, the | 9019 | :: |
7876 | tests run: bitbake core-image-sato | 9020 | |
9021 | TESTIMAGE_AUTO = "1" | ||
9022 | |||
9023 | Next, build your image. If the image successfully builds, the | ||
9024 | tests run: | ||
9025 | :: | ||
9026 | |||
9027 | bitbake core-image-sato | ||
7877 | 9028 | ||
7878 | - *Manually running tests:* To manually run the tests, first globally | 9029 | - *Manually running tests:* To manually run the tests, first globally |
7879 | inherit the | 9030 | inherit the |
7880 | :ref:`testimage <ref-classes-testimage*>` class | 9031 | :ref:`testimage <ref-classes-testimage*>` class |
7881 | by editing your ``local.conf`` file: INHERIT += "testimage" Next, use | 9032 | by editing your ``local.conf`` file: |
7882 | BitBake to run the tests: bitbake -c testimage image | 9033 | :: |
9034 | |||
9035 | INHERIT += "testimage" | ||
9036 | |||
9037 | Next, use BitBake to run the tests: | ||
9038 | :: | ||
9039 | |||
9040 | bitbake -c testimage image | ||
7883 | 9041 | ||
7884 | All test files reside in ``meta/lib/oeqa/runtime`` in the | 9042 | All test files reside in ``meta/lib/oeqa/runtime`` in the |
7885 | :term:`Source Directory`. A test name maps | 9043 | :term:`Source Directory`. A test name maps |
@@ -7925,11 +9083,14 @@ handling. | |||
7925 | Here are some things to keep in mind when running tests: | 9083 | Here are some things to keep in mind when running tests: |
7926 | 9084 | ||
7927 | - The default tests for the image are defined as: | 9085 | - The default tests for the image are defined as: |
7928 | DEFAULT_TEST_SUITES_pn-image = "ping ssh df connman syslog xorg scp | 9086 | :: |
7929 | vnc date rpm dnf dmesg" | 9087 | |
9088 | DEFAULT_TEST_SUITES_pn-image = "ping ssh df connman syslog xorg scp vnc date rpm dnf dmesg" | ||
7930 | 9089 | ||
7931 | - Add your own test to the list of the by using the following: | 9090 | - Add your own test to the list of the by using the following: |
7932 | TEST_SUITES_append = " mytest" | 9091 | :: |
9092 | |||
9093 | TEST_SUITES_append = " mytest" | ||
7933 | 9094 | ||
7934 | - Run a specific list of tests as follows: TEST_SUITES = "test1 test2 | 9095 | - Run a specific list of tests as follows: TEST_SUITES = "test1 test2 |
7935 | test3" Remember, order is important. Be sure to place a test that is | 9096 | test3" Remember, order is important. Be sure to place a test that is |
@@ -7944,24 +9105,49 @@ test execution off to a scheduler. You can only export tests that are | |||
7944 | defined in :term:`TEST_SUITES`. | 9105 | defined in :term:`TEST_SUITES`. |
7945 | 9106 | ||
7946 | If your image is already built, make sure the following are set in your | 9107 | If your image is already built, make sure the following are set in your |
7947 | ``local.conf`` file: INHERIT +="testexport" TEST_TARGET_IP = | 9108 | ``local.conf`` file: |
7948 | "IP-address-for-the-test-target" TEST_SERVER_IP = | 9109 | :: |
7949 | "IP-address-for-the-test-server" You can then export the tests with the | 9110 | |
7950 | following BitBake command form: $ bitbake image -c testexport Exporting | 9111 | INHERIT +="testexport" |
7951 | the tests places them in the | 9112 | TEST_TARGET_IP = "IP-address-for-the-test-target" |
9113 | TEST_SERVER_IP = "IP-address-for-the-test-server" | ||
9114 | |||
9115 | You can then export the tests with the | ||
9116 | following BitBake command form: | ||
9117 | :: | ||
9118 | |||
9119 | $ bitbake image -c testexport | ||
9120 | |||
9121 | Exporting the tests places them in the | ||
7952 | :term:`Build Directory` in | 9122 | :term:`Build Directory` in |
7953 | ``tmp/testexport/``\ image, which is controlled by the | 9123 | ``tmp/testexport/``\ image, which is controlled by the |
7954 | ``TEST_EXPORT_DIR`` variable. | 9124 | ``TEST_EXPORT_DIR`` variable. |
7955 | 9125 | ||
7956 | You can now run the tests outside of the build environment: $ cd | 9126 | You can now run the tests outside of the build environment: |
7957 | tmp/testexport/image $ ./runexported.py testdata.json | 9127 | :: |
9128 | |||
9129 | $ cd tmp/testexport/image | ||
9130 | $ ./runexported.py testdata.json | ||
7958 | 9131 | ||
7959 | Here is a complete example that shows IP addresses and uses the | 9132 | Here is a complete example that shows IP addresses and uses the |
7960 | ``core-image-sato`` image: INHERIT +="testexport" TEST_TARGET_IP = | 9133 | ``core-image-sato`` image: |
7961 | "192.168.7.2" TEST_SERVER_IP = "192.168.7.1" Use BitBake to export the | 9134 | :: |
7962 | tests: $ bitbake core-image-sato -c testexport Run the tests outside of | 9135 | |
7963 | the build environment using the following: $ cd | 9136 | INHERIT +="testexport" |
7964 | tmp/testexport/core-image-sato $ ./runexported.py testdata.json | 9137 | TEST_TARGET_IP = "192.168.7.2" |
9138 | TEST_SERVER_IP = "192.168.7.1" | ||
9139 | |||
9140 | Use BitBake to export the tests: | ||
9141 | :: | ||
9142 | |||
9143 | $ bitbake core-image-sato -c testexport | ||
9144 | |||
9145 | Run the tests outside of | ||
9146 | the build environment using the following: | ||
9147 | :: | ||
9148 | |||
9149 | $ cd tmp/testexport/core-image-sato | ||
9150 | $ ./runexported.py testdata.json | ||
7965 | 9151 | ||
7966 | .. _qemu-image-writing-new-tests: | 9152 | .. _qemu-image-writing-new-tests: |
7967 | 9153 | ||
@@ -8007,11 +9193,11 @@ Class Methods | |||
8007 | 9193 | ||
8008 | Class methods are as follows: | 9194 | Class methods are as follows: |
8009 | 9195 | ||
8010 | - *``hasPackage(pkg)``:* Returns "True" if ``pkg`` is in the installed | 9196 | - *hasPackage(pkg):* Returns "True" if ``pkg`` is in the installed |
8011 | package list of the image, which is based on the manifest file that | 9197 | package list of the image, which is based on the manifest file that |
8012 | is generated during the ``do_rootfs`` task. | 9198 | is generated during the ``do_rootfs`` task. |
8013 | 9199 | ||
8014 | - *``hasFeature(feature)``:* Returns "True" if the feature is in | 9200 | - *hasFeature(feature):* Returns "True" if the feature is in |
8015 | :term:`IMAGE_FEATURES` or | 9201 | :term:`IMAGE_FEATURES` or |
8016 | :term:`DISTRO_FEATURES`. | 9202 | :term:`DISTRO_FEATURES`. |
8017 | 9203 | ||
@@ -8022,33 +9208,33 @@ Class Attributes | |||
8022 | 9208 | ||
8023 | Class attributes are as follows: | 9209 | Class attributes are as follows: |
8024 | 9210 | ||
8025 | - *``pscmd``:* Equals "ps -ef" if ``procps`` is installed in the image. | 9211 | - *pscmd:* Equals "ps -ef" if ``procps`` is installed in the image. |
8026 | Otherwise, ``pscmd`` equals "ps" (busybox). | 9212 | Otherwise, ``pscmd`` equals "ps" (busybox). |
8027 | 9213 | ||
8028 | - *``tc``:* The called test context, which gives access to the | 9214 | - *tc:* The called test context, which gives access to the |
8029 | following attributes: | 9215 | following attributes: |
8030 | 9216 | ||
8031 | - *``d``:* The BitBake datastore, which allows you to use stuff such | 9217 | - *d:* The BitBake datastore, which allows you to use stuff such |
8032 | as ``oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")``. | 9218 | as ``oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")``. |
8033 | 9219 | ||
8034 | - *``testslist`` and ``testsrequired``:* Used internally. The tests | 9220 | - *testslist and testsrequired:* Used internally. The tests |
8035 | do not need these. | 9221 | do not need these. |
8036 | 9222 | ||
8037 | - *``filesdir``:* The absolute path to | 9223 | - *filesdir:* The absolute path to |
8038 | ``meta/lib/oeqa/runtime/files``, which contains helper files for | 9224 | ``meta/lib/oeqa/runtime/files``, which contains helper files for |
8039 | tests meant for copying on the target such as small files written | 9225 | tests meant for copying on the target such as small files written |
8040 | in C for compilation. | 9226 | in C for compilation. |
8041 | 9227 | ||
8042 | - *``target``:* The target controller object used to deploy and | 9228 | - *target:* The target controller object used to deploy and |
8043 | start an image on a particular target (e.g. Qemu, SimpleRemote, | 9229 | start an image on a particular target (e.g. Qemu, SimpleRemote, |
8044 | and SystemdbootTarget). Tests usually use the following: | 9230 | and SystemdbootTarget). Tests usually use the following: |
8045 | 9231 | ||
8046 | - *``ip``:* The target's IP address. | 9232 | - *ip:* The target's IP address. |
8047 | 9233 | ||
8048 | - *``server_ip``:* The host's IP address, which is usually used | 9234 | - *server_ip:* The host's IP address, which is usually used |
8049 | by the DNF test suite. | 9235 | by the DNF test suite. |
8050 | 9236 | ||
8051 | - *``run(cmd, timeout=None)``:* The single, most used method. | 9237 | - *run(cmd, timeout=None):* The single, most used method. |
8052 | This command is a wrapper for: ``ssh root@host "cmd"``. The | 9238 | This command is a wrapper for: ``ssh root@host "cmd"``. The |
8053 | command returns a tuple: (status, output), which are what their | 9239 | command returns a tuple: (status, output), which are what their |
8054 | names imply - the return code of "cmd" and whatever output it | 9240 | names imply - the return code of "cmd" and whatever output it |
@@ -8058,10 +9244,10 @@ Class attributes are as follows: | |||
8058 | timeout period, which is 300 seconds. If the argument is "0", | 9244 | timeout period, which is 300 seconds. If the argument is "0", |
8059 | the test runs until the command returns. | 9245 | the test runs until the command returns. |
8060 | 9246 | ||
8061 | - *``copy_to(localpath, remotepath)``:* | 9247 | - *copy_to(localpath, remotepath):* |
8062 | ``scp localpath root@ip:remotepath``. | 9248 | ``scp localpath root@ip:remotepath``. |
8063 | 9249 | ||
8064 | - *``copy_from(remotepath, localpath)``:* | 9250 | - *copy_from(remotepath, localpath):* |
8065 | ``scp root@host:remotepath localpath``. | 9251 | ``scp root@host:remotepath localpath``. |
8066 | 9252 | ||
8067 | .. _qemu-image-writing-tests-instance-attributes: | 9253 | .. _qemu-image-writing-tests-instance-attributes: |
@@ -8114,9 +9300,24 @@ data: | |||
8114 | 9300 | ||
8115 | Following is an example JSON file that handles test "foo" installing | 9301 | Following is an example JSON file that handles test "foo" installing |
8116 | package "bar" and test "foobar" installing packages "foo" and "bar". | 9302 | package "bar" and test "foobar" installing packages "foo" and "bar". |
8117 | Once the test is complete, the packages are removed from the DUT. { | 9303 | Once the test is complete, the packages are removed from the DUT. |
8118 | "foo": { "pkg": "bar" }, "foobar": [ { "pkg": "foo", "rm": true }, { | 9304 | :: |
8119 | "pkg": "bar", "rm": true } ] } | 9305 | |
9306 | { | ||
9307 | "foo": { | ||
9308 | "pkg": "bar" | ||
9309 | }, | ||
9310 | "foobar": [ | ||
9311 | { | ||
9312 | "pkg": "foo", | ||
9313 | "rm": true | ||
9314 | }, | ||
9315 | { | ||
9316 | "pkg": "bar", | ||
9317 | "rm": true | ||
9318 | } | ||
9319 | ] | ||
9320 | } | ||
8120 | 9321 | ||
8121 | .. _usingpoky-debugging-tools-and-techniques: | 9322 | .. _usingpoky-debugging-tools-and-techniques: |
8122 | 9323 | ||
@@ -8158,8 +9359,7 @@ section: | |||
8158 | use the BitBake ``-e`` option to examine variable values after a | 9359 | use the BitBake ``-e`` option to examine variable values after a |
8159 | recipe has been parsed. | 9360 | recipe has been parsed. |
8160 | 9361 | ||
8161 | - "`Viewing Package Information with | 9362 | - ":ref:`dev-manual/dev-manual-common-tasks:viewing package information with \`\`oe-pkgdata-util\`\``" |
8162 | ``oe-pkgdata-util`` <#viewing-package-information-with-oe-pkgdata-util>`__" | ||
8163 | describes how to use the ``oe-pkgdata-util`` utility to query | 9363 | describes how to use the ``oe-pkgdata-util`` utility to query |
8164 | :term:`PKGDATA_DIR` and | 9364 | :term:`PKGDATA_DIR` and |
8165 | display package-related information for built packages. | 9365 | display package-related information for built packages. |
@@ -8246,10 +9446,16 @@ variables>` did not work out as expected. | |||
8246 | BitBake's ``-e`` option is used to display variable values after | 9446 | BitBake's ``-e`` option is used to display variable values after |
8247 | parsing. The following command displays the variable values after the | 9447 | parsing. The following command displays the variable values after the |
8248 | configuration files (i.e. ``local.conf``, ``bblayers.conf``, | 9448 | configuration files (i.e. ``local.conf``, ``bblayers.conf``, |
8249 | ``bitbake.conf`` and so forth) have been parsed: $ bitbake -e The | 9449 | ``bitbake.conf`` and so forth) have been parsed: |
8250 | following command displays variable values after a specific recipe has | 9450 | :: |
9451 | |||
9452 | $ bitbake -e | ||
9453 | |||
9454 | The following command displays variable values after a specific recipe has | ||
8251 | been parsed. The variables include those from the configuration as well: | 9455 | been parsed. The variables include those from the configuration as well: |
8252 | $ bitbake -e recipename | 9456 | :: |
9457 | |||
9458 | $ bitbake -e recipename | ||
8253 | 9459 | ||
8254 | .. note:: | 9460 | .. note:: |
8255 | 9461 | ||
@@ -8271,8 +9477,9 @@ helpful during debugging. | |||
8271 | 9477 | ||
8272 | Variables that are exported to the environment are preceded by | 9478 | Variables that are exported to the environment are preceded by |
8273 | ``export`` in the output of ``bitbake -e``. See the following example: | 9479 | ``export`` in the output of ``bitbake -e``. See the following example: |
8274 | export CC="i586-poky-linux-gcc -m32 -march=i586 | 9480 | :: |
8275 | --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86" | 9481 | |
9482 | export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86" | ||
8276 | 9483 | ||
8277 | In addition to variable values, the output of the ``bitbake -e`` and | 9484 | In addition to variable values, the output of the ``bitbake -e`` and |
8278 | ``bitbake -e`` recipe commands includes the following information: | 9485 | ``bitbake -e`` recipe commands includes the following information: |
@@ -8280,8 +9487,7 @@ In addition to variable values, the output of the ``bitbake -e`` and | |||
8280 | - The output starts with a tree listing all configuration files and | 9487 | - The output starts with a tree listing all configuration files and |
8281 | classes included globally, recursively listing the files they include | 9488 | classes included globally, recursively listing the files they include |
8282 | or inherit in turn. Much of the behavior of the OpenEmbedded build | 9489 | or inherit in turn. Much of the behavior of the OpenEmbedded build |
8283 | system (including the behavior of the `normal recipe build | 9490 | system (including the behavior of the :ref:`ref-manual/ref-tasks:normal recipe build tasks`) is |
8284 | tasks <&YOCTO_DOCS_REF_URL;#normal-recipe-build-tasks>`__) is | ||
8285 | implemented in the | 9491 | implemented in the |
8286 | :ref:`base <ref-classes-base>` class and the | 9492 | :ref:`base <ref-classes-base>` class and the |
8287 | classes it inherits, rather than being built into BitBake itself. | 9493 | classes it inherits, rather than being built into BitBake itself. |
@@ -8307,11 +9513,11 @@ Following are a few of the available ``oe-pkgdata-util`` subcommands. | |||
8307 | You can use the standard \* and ? globbing wildcards as part of | 9513 | You can use the standard \* and ? globbing wildcards as part of |
8308 | package names and paths. | 9514 | package names and paths. |
8309 | 9515 | ||
8310 | - ``oe-pkgdata-util list-pkgs [``\ pattern\ ``]``: Lists all packages | 9516 | - ``oe-pkgdata-util list-pkgs [pattern]``: Lists all packages |
8311 | that have been built, optionally limiting the match to packages that | 9517 | that have been built, optionally limiting the match to packages that |
8312 | match pattern. | 9518 | match pattern. |
8313 | 9519 | ||
8314 | - ``oe-pkgdata-util list-pkg-files ``\ package\ `` ...``: Lists the | 9520 | - ``oe-pkgdata-util list-pkg-files package ...``: Lists the |
8315 | files and directories contained in the given packages. | 9521 | files and directories contained in the given packages. |
8316 | 9522 | ||
8317 | .. note:: | 9523 | .. note:: |
@@ -8330,18 +9536,23 @@ Following are a few of the available ``oe-pkgdata-util`` subcommands. | |||
8330 | :ref:`rm_work <ref-classes-rm-work>` is not | 9536 | :ref:`rm_work <ref-classes-rm-work>` is not |
8331 | enabled when you build the recipe. | 9537 | enabled when you build the recipe. |
8332 | 9538 | ||
8333 | - ``oe-pkgdata-util find-path ``\ path\ `` ...``: Lists the names of | 9539 | - ``oe-pkgdata-util find-path path ...``: Lists the names of |
8334 | the packages that contain the given paths. For example, the following | 9540 | the packages that contain the given paths. For example, the following |
8335 | tells us that ``/usr/share/man/man1/make.1`` is contained in the | 9541 | tells us that ``/usr/share/man/man1/make.1`` is contained in the |
8336 | ``make-doc`` package: $ oe-pkgdata-util find-path | 9542 | ``make-doc`` package: |
8337 | /usr/share/man/man1/make.1 make-doc: /usr/share/man/man1/make.1 | 9543 | :: |
8338 | 9544 | ||
8339 | - ``oe-pkgdata-util lookup-recipe ``\ package\ `` ...``: Lists the name | 9545 | $ oe-pkgdata-util find-path /usr/share/man/man1/make.1 make-doc: /usr/share/man/man1/make.1 |
9546 | |||
9547 | - ``oe-pkgdata-util lookup-recipe package ...``: Lists the name | ||
8340 | of the recipes that produce the given packages. | 9548 | of the recipes that produce the given packages. |
8341 | 9549 | ||
8342 | For more information on the ``oe-pkgdata-util`` command, use the help | 9550 | For more information on the ``oe-pkgdata-util`` command, use the help |
8343 | facility: $ oe-pkgdata-util DASHDASHhelp $ oe-pkgdata-util subcommand | 9551 | facility: |
8344 | --help | 9552 | :: |
9553 | |||
9554 | $ oe-pkgdata-util DASHDASHhelp | ||
9555 | $ oe-pkgdata-util subcommand --help | ||
8345 | 9556 | ||
8346 | .. _dev-viewing-dependencies-between-recipes-and-tasks: | 9557 | .. _dev-viewing-dependencies-between-recipes-and-tasks: |
8347 | 9558 | ||
@@ -8353,8 +9564,12 @@ before the one you have specified. Dependency information can help you | |||
8353 | understand why a recipe is built. | 9564 | understand why a recipe is built. |
8354 | 9565 | ||
8355 | To generate dependency information for a recipe, run the following | 9566 | To generate dependency information for a recipe, run the following |
8356 | command: $ bitbake -g recipename This command writes the following files | 9567 | command: |
8357 | in the current directory: | 9568 | :: |
9569 | |||
9570 | $ bitbake -g recipename | ||
9571 | |||
9572 | This command writes the following files in the current directory: | ||
8358 | 9573 | ||
8359 | - ``pn-buildlist``: A list of recipes/targets involved in building | 9574 | - ``pn-buildlist``: A list of recipes/targets involved in building |
8360 | recipename. "Involved" here means that at least one task from the | 9575 | recipename. "Involved" here means that at least one task from the |
@@ -8380,9 +9595,12 @@ format and can be converted to images (e.g. using the ``dot`` tool from | |||
8380 | provide useful information. | 9595 | provide useful information. |
8381 | 9596 | ||
8382 | As an example, the ``task-depends.dot`` file contains lines such | 9597 | As an example, the ``task-depends.dot`` file contains lines such |
8383 | as the following: "libxslt.do_configure" -> | 9598 | as the following: |
8384 | "libxml2.do_populate_sysroot" The above example line reveals that | 9599 | :: |
8385 | the | 9600 | |
9601 | "libxslt.do_configure" -> "libxml2.do_populate_sysroot" | ||
9602 | |||
9603 | The above example line reveals that the | ||
8386 | :ref:`ref-tasks-configure` | 9604 | :ref:`ref-tasks-configure` |
8387 | task in ``libxslt`` depends on the | 9605 | task in ``libxslt`` depends on the |
8388 | :ref:`ref-tasks-populate_sysroot` | 9606 | :ref:`ref-tasks-populate_sysroot` |
@@ -8395,7 +9613,12 @@ format and can be converted to images (e.g. using the ``dot`` tool from | |||
8395 | displays paths between graph nodes. | 9613 | displays paths between graph nodes. |
8396 | 9614 | ||
8397 | You can use a different method to view dependency information by using | 9615 | You can use a different method to view dependency information by using |
8398 | the following command: $ bitbake -g -u taskexp recipename This command | 9616 | the following command: |
9617 | :: | ||
9618 | |||
9619 | $ bitbake -g -u taskexp recipename | ||
9620 | |||
9621 | This command | ||
8399 | displays a GUI window from which you can view build-time and runtime | 9622 | displays a GUI window from which you can view build-time and runtime |
8400 | dependencies for the recipes involved in building recipename. | 9623 | dependencies for the recipes involved in building recipename. |
8401 | 9624 | ||
@@ -8419,7 +9642,10 @@ If you are unsure whether a variable dependency is being picked up | |||
8419 | automatically for a given task, you can list the variable dependencies | 9642 | automatically for a given task, you can list the variable dependencies |
8420 | BitBake has determined by doing the following: | 9643 | BitBake has determined by doing the following: |
8421 | 9644 | ||
8422 | 1. Build the recipe containing the task: $ bitbake recipename | 9645 | 1. Build the recipe containing the task: |
9646 | :: | ||
9647 | |||
9648 | $ bitbake recipename | ||
8423 | 9649 | ||
8424 | 2. Inside the :term:`STAMPS_DIR` | 9650 | 2. Inside the :term:`STAMPS_DIR` |
8425 | directory, find the signature data (``sigdata``) file that | 9651 | directory, find the signature data (``sigdata``) file that |
@@ -8429,23 +9655,30 @@ BitBake has determined by doing the following: | |||
8429 | :ref:`ref-tasks-fetch` task of the | 9655 | :ref:`ref-tasks-fetch` task of the |
8430 | ``db`` recipe, the ``sigdata`` file might be found in the following | 9656 | ``db`` recipe, the ``sigdata`` file might be found in the following |
8431 | location: | 9657 | location: |
8432 | ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 | 9658 | :: |
9659 | |||
9660 | ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 | ||
9661 | |||
8433 | For tasks that are accelerated through the shared state | 9662 | For tasks that are accelerated through the shared state |
8434 | (`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__) cache, an | 9663 | (:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache, an |
8435 | additional ``siginfo`` file is written into | 9664 | additional ``siginfo`` file is written into |
8436 | :term:`SSTATE_DIR` along with | 9665 | :term:`SSTATE_DIR` along with |
8437 | the cached task output. The ``siginfo`` files contain exactly the | 9666 | the cached task output. The ``siginfo`` files contain exactly the |
8438 | same information as ``sigdata`` files. | 9667 | same information as ``sigdata`` files. |
8439 | 9668 | ||
8440 | 3. Run ``bitbake-dumpsig`` on the ``sigdata`` or ``siginfo`` file. Here | 9669 | 3. Run ``bitbake-dumpsig`` on the ``sigdata`` or ``siginfo`` file. Here |
8441 | is an example: $ bitbake-dumpsig | 9670 | is an example: |
8442 | ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 | 9671 | :: |
9672 | |||
9673 | $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 | ||
9674 | |||
8443 | In the output of the above command, you will find a line like the | 9675 | In the output of the above command, you will find a line like the |
8444 | following, which lists all the (inferred) variable dependencies for | 9676 | following, which lists all the (inferred) variable dependencies for |
8445 | the task. This list also includes indirect dependencies from | 9677 | the task. This list also includes indirect dependencies from |
8446 | variables depending on other variables, recursively. Task | 9678 | variables depending on other variables, recursively. |
8447 | dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', | 9679 | :: |
8448 | 'SRC_URI[sha256sum]', 'base_do_fetch'] | 9680 | |
9681 | Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch'] | ||
8449 | 9682 | ||
8450 | .. note:: | 9683 | .. note:: |
8451 | 9684 | ||
@@ -8467,8 +9700,12 @@ call ``bitbake-diffsigs`` with just one file, the command behaves like | |||
8467 | 9700 | ||
8468 | You can also use BitBake to dump out the signature construction | 9701 | You can also use BitBake to dump out the signature construction |
8469 | information without executing tasks by using either of the following | 9702 | information without executing tasks by using either of the following |
8470 | BitBake command-line options: DASHDASHdump-signatures=SIGNATURE_HANDLER | 9703 | BitBake command-line options: |
8471 | -S SIGNATURE_HANDLER | 9704 | :: |
9705 | |||
9706 | ‐‐dump-signatures=SIGNATURE_HANDLER | ||
9707 | -S SIGNATURE_HANDLER | ||
9708 | |||
8472 | 9709 | ||
8473 | .. note:: | 9710 | .. note:: |
8474 | 9711 | ||
@@ -8494,9 +9731,9 @@ information on how to view and interpret information in ``siginfo`` | |||
8494 | files, see the "`Viewing Task Variable | 9731 | files, see the "`Viewing Task Variable |
8495 | Dependencies <#dev-viewing-task-variable-dependencies>`__" section. | 9732 | Dependencies <#dev-viewing-task-variable-dependencies>`__" section. |
8496 | 9733 | ||
8497 | For conceptual information on shared state, see the "`Shared | 9734 | For conceptual information on shared state, see the |
8498 | State <&YOCTO_DOCS_OM_URL;#shared-state>`__" section in the Yocto | 9735 | ":ref:`overview-manual/overview-manual-concepts:shared state`" |
8499 | Project Overview and Concepts Manual. | 9736 | section in the Yocto Project Overview and Concepts Manual. |
8500 | 9737 | ||
8501 | .. _dev-invalidating-shared-state-to-force-a-task-to-run: | 9738 | .. _dev-invalidating-shared-state-to-force-a-task-to-run: |
8502 | 9739 | ||
@@ -8504,8 +9741,8 @@ Invalidating Shared State to Force a Task to Run | |||
8504 | ------------------------------------------------ | 9741 | ------------------------------------------------ |
8505 | 9742 | ||
8506 | The OpenEmbedded build system uses | 9743 | The OpenEmbedded build system uses |
8507 | `checksums <&YOCTO_DOCS_OM_URL;#overview-checksums>`__ and `shared | 9744 | :ref:`checksums <overview-checksums>` and |
8508 | state <&YOCTO_DOCS_OM_URL;#shared-state>`__ cache to avoid unnecessarily | 9745 | :ref:`overview-manual/overview-manual-concepts:shared state` cache to avoid unnecessarily |
8509 | rebuilding tasks. Collectively, this scheme is known as "shared state | 9746 | rebuilding tasks. Collectively, this scheme is known as "shared state |
8510 | code." | 9747 | code." |
8511 | 9748 | ||
@@ -8559,15 +9796,17 @@ behavior in most cases is: ``do_fetch``, ``do_unpack``, ``do_patch``, | |||
8559 | ``do_build`` and any tasks on which it depends build first. Some tasks, | 9796 | ``do_build`` and any tasks on which it depends build first. Some tasks, |
8560 | such as ``do_devshell``, are not part of the default build chain. If you | 9797 | such as ``do_devshell``, are not part of the default build chain. If you |
8561 | wish to run a task that is not part of the default build chain, you can | 9798 | wish to run a task that is not part of the default build chain, you can |
8562 | use the ``-c`` option in BitBake. Here is an example: $ bitbake | 9799 | use the ``-c`` option in BitBake. Here is an example: |
8563 | matchbox-desktop -c devshell | 9800 | :: |
9801 | |||
9802 | $ bitbake matchbox-desktop -c devshell | ||
8564 | 9803 | ||
8565 | The ``-c`` option respects task dependencies, which means that all other | 9804 | The ``-c`` option respects task dependencies, which means that all other |
8566 | tasks (including tasks from other recipes) that the specified task | 9805 | tasks (including tasks from other recipes) that the specified task |
8567 | depends on will be run before the task. Even when you manually specify a | 9806 | depends on will be run before the task. Even when you manually specify a |
8568 | task to run with ``-c``, BitBake will only run the task if it considers | 9807 | task to run with ``-c``, BitBake will only run the task if it considers |
8569 | it "out of date". See the "`Stamp Files and the Rerunning of | 9808 | it "out of date". See the |
8570 | Tasks <&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks>`__" | 9809 | ":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`" |
8571 | section in the Yocto Project Overview and Concepts Manual for how | 9810 | section in the Yocto Project Overview and Concepts Manual for how |
8572 | BitBake determines whether a task is "out of date". | 9811 | BitBake determines whether a task is "out of date". |
8573 | 9812 | ||
@@ -8588,19 +9827,26 @@ out), then you can use the ``-f`` option. | |||
8588 | ] | 9827 | ] |
8589 | variable flag is already set for the task. | 9828 | variable flag is already set for the task. |
8590 | 9829 | ||
8591 | The following example shows one way you can use the ``-f`` option: $ | 9830 | The following example shows one way you can use the ``-f`` option: |
8592 | bitbake matchbox-desktop . . make some changes to the source code in the | 9831 | :: |
8593 | work directory . . $ bitbake matchbox-desktop -c compile -f $ bitbake | 9832 | |
8594 | matchbox-desktop | 9833 | $ bitbake matchbox-desktop |
9834 | . | ||
9835 | . | ||
9836 | make some changes to the source code in the work directory | ||
9837 | . | ||
9838 | . | ||
9839 | $ bitbake matchbox-desktop -c compile -f | ||
9840 | $ bitbake matchbox-desktop | ||
8595 | 9841 | ||
8596 | This sequence first builds and then recompiles ``matchbox-desktop``. The | 9842 | This sequence first builds and then recompiles ``matchbox-desktop``. The |
8597 | last command reruns all tasks (basically the packaging tasks) after the | 9843 | last command reruns all tasks (basically the packaging tasks) after the |
8598 | compile. BitBake recognizes that the ``do_compile`` task was rerun and | 9844 | compile. BitBake recognizes that the ``do_compile`` task was rerun and |
8599 | therefore understands that the other tasks also need to be run again. | 9845 | therefore understands that the other tasks also need to be run again. |
8600 | 9846 | ||
8601 | Another, shorter way to rerun a task and all `normal recipe build | 9847 | Another, shorter way to rerun a task and all |
8602 | tasks <&YOCTO_DOCS_REF_URL;#normal-recipe-build-tasks>`__ that depend on | 9848 | :ref:`ref-manual/ref-tasks:normal recipe build tasks` |
8603 | it is to use the ``-C`` option. | 9849 | that depend on it is to use the ``-C`` option. |
8604 | 9850 | ||
8605 | .. note:: | 9851 | .. note:: |
8606 | 9852 | ||
@@ -8612,7 +9858,11 @@ Using this option invalidates the given task and then runs the | |||
8612 | :ref:`ref-tasks-build` task, which is | 9858 | :ref:`ref-tasks-build` task, which is |
8613 | the default task if no task is given, and the tasks on which it depends. | 9859 | the default task if no task is given, and the tasks on which it depends. |
8614 | You could replace the final two commands in the previous example with | 9860 | You could replace the final two commands in the previous example with |
8615 | the following single command: $ bitbake matchbox-desktop -C compile | 9861 | the following single command: |
9862 | :: | ||
9863 | |||
9864 | $ bitbake matchbox-desktop -C compile | ||
9865 | |||
8616 | Internally, the ``-f`` and ``-C`` options work by tainting (modifying) | 9866 | Internally, the ``-f`` and ``-C`` options work by tainting (modifying) |
8617 | the input checksum of the specified task. This tainting indirectly | 9867 | the input checksum of the specified task. This tainting indirectly |
8618 | causes the task and its dependent tasks to be rerun through the normal | 9868 | causes the task and its dependent tasks to be rerun through the normal |
@@ -8625,8 +9875,8 @@ task dependency mechanisms. | |||
8625 | builds involving such tasks: | 9875 | builds involving such tasks: |
8626 | :: | 9876 | :: |
8627 | 9877 | ||
8628 | WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run | 9878 | WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run |
8629 | 9879 | ||
8630 | 9880 | ||
8631 | The purpose of the warning is to let you know that the work directory | 9881 | The purpose of the warning is to let you know that the work directory |
8632 | and build output might not be in the clean state they would be in for | 9882 | and build output might not be in the clean state they would be in for |
@@ -8635,13 +9885,17 @@ task dependency mechanisms. | |||
8635 | recipe, as follows: | 9885 | recipe, as follows: |
8636 | :: | 9886 | :: |
8637 | 9887 | ||
8638 | $ bitbake matchbox-desktop -c clean | 9888 | $ bitbake matchbox-desktop -c clean |
8639 | $ bitbake matchbox-desktop | 9889 | $ bitbake matchbox-desktop |
8640 | 9890 | ||
8641 | 9891 | ||
8642 | You can view a list of tasks in a given package by running the | 9892 | You can view a list of tasks in a given package by running the |
8643 | ``do_listtasks`` task as follows: $ bitbake matchbox-desktop -c | 9893 | ``do_listtasks`` task as follows: |
8644 | listtasks The results appear as output to the console and are also in | 9894 | :: |
9895 | |||
9896 | $ bitbake matchbox-desktop -c listtasks | ||
9897 | |||
9898 | The results appear as output to the console and are also in | ||
8645 | the file ``${WORKDIR}/temp/log.do_listtasks``. | 9899 | the file ``${WORKDIR}/temp/log.do_listtasks``. |
8646 | 9900 | ||
8647 | .. _dev-debugging-bitbake: | 9901 | .. _dev-debugging-bitbake: |
@@ -8665,7 +9919,12 @@ Building with No Dependencies | |||
8665 | ----------------------------- | 9919 | ----------------------------- |
8666 | 9920 | ||
8667 | To build a specific recipe (``.bb`` file), you can use the following | 9921 | To build a specific recipe (``.bb`` file), you can use the following |
8668 | command form: $ bitbake -b somepath/somerecipe.bb This command form does | 9922 | command form: |
9923 | :: | ||
9924 | |||
9925 | $ bitbake -b somepath/somerecipe.bb | ||
9926 | |||
9927 | This command form does | ||
8669 | not check for dependencies. Consequently, you should use it only when | 9928 | not check for dependencies. Consequently, you should use it only when |
8670 | you know existing dependencies have been met. | 9929 | you know existing dependencies have been met. |
8671 | 9930 | ||
@@ -8683,21 +9942,21 @@ functions, the following logging functions exist. All of these functions | |||
8683 | log to ``${T}/log.do_``\ task, and can also log to standard output | 9942 | log to ``${T}/log.do_``\ task, and can also log to standard output |
8684 | (stdout) with the right settings: | 9943 | (stdout) with the right settings: |
8685 | 9944 | ||
8686 | - ``bb.plain(``\ msg\ ``)``: Writes msg as is to the log while also | 9945 | - ``bb.plain(msg)``: Writes msg as is to the log while also |
8687 | logging to stdout. | 9946 | logging to stdout. |
8688 | 9947 | ||
8689 | - ``bb.note(``\ msg\ ``)``: Writes "NOTE: msg" to the log. Also logs to | 9948 | - ``bb.note(msg)``: Writes "NOTE: msg" to the log. Also logs to |
8690 | stdout if BitBake is called with "-v". | 9949 | stdout if BitBake is called with "-v". |
8691 | 9950 | ||
8692 | - ``bb.debug(``\ level\ ``, ``\ msg\ ``)``: Writes "DEBUG: msg" to the | 9951 | - ``bb.debug(level, msg)``: Writes "DEBUG: msg" to the |
8693 | log. Also logs to stdout if the log level is greater than or equal to | 9952 | log. Also logs to stdout if the log level is greater than or equal to |
8694 | level. See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option | 9953 | level. See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option |
8695 | in the BitBake User Manual for more information. | 9954 | in the BitBake User Manual for more information. |
8696 | 9955 | ||
8697 | - ``bb.warn(``\ msg\ ``)``: Writes "WARNING: msg" to the log while also | 9956 | - ``bb.warn(msg)``: Writes "WARNING: msg" to the log while also |
8698 | logging to stdout. | 9957 | logging to stdout. |
8699 | 9958 | ||
8700 | - ``bb.error(``\ msg\ ``)``: Writes "ERROR: msg" to the log while also | 9959 | - ``bb.error(msg)``: Writes "ERROR: msg" to the log while also |
8701 | logging to standard out (stdout). | 9960 | logging to standard out (stdout). |
8702 | 9961 | ||
8703 | .. note:: | 9962 | .. note:: |
@@ -8731,14 +9990,23 @@ in the log, use the "debug" loglevel. | |||
8731 | Following is an example written in Python. The code handles logging for | 9990 | Following is an example written in Python. The code handles logging for |
8732 | a function that determines the number of tasks needed to be run. See the | 9991 | a function that determines the number of tasks needed to be run. See the |
8733 | ":ref:`ref-tasks-listtasks`" | 9992 | ":ref:`ref-tasks-listtasks`" |
8734 | section for additional information: python do_listtasks() { bb.debug(2, | 9993 | section for additional information: |
8735 | "Starting to figure out the task list") if noteworthy_condition: | 9994 | :: |
8736 | bb.note("There are 47 tasks to run") bb.debug(2, "Got to point xyz") if | 9995 | |
8737 | warning_trigger: bb.warn("Detected warning_trigger, this might be a | 9996 | python do_listtasks() { |
8738 | problem later.") if recoverable_error: bb.error("Hit recoverable_error, | 9997 | bb.debug(2, "Starting to figure out the task list") |
8739 | you really need to fix this!") if fatal_error: bb.fatal("fatal_error | 9998 | if noteworthy_condition: |
8740 | detected, unable to print the task list") bb.plain("The tasks present | 9999 | bb.note("There are 47 tasks to run") |
8741 | are abc") bb.debug(2, "Finished figuring out the tasklist") } | 10000 | bb.debug(2, "Got to point xyz") |
10001 | if warning_trigger: | ||
10002 | bb.warn("Detected warning_trigger, this might be a problem later.") | ||
10003 | if recoverable_error: | ||
10004 | bb.error("Hit recoverable_error, you really need to fix this!") | ||
10005 | if fatal_error: | ||
10006 | bb.fatal("fatal_error detected, unable to print the task list") | ||
10007 | bb.plain("The tasks present are abc") | ||
10008 | bb.debug(2, "Finished figuring out the tasklist") | ||
10009 | } | ||
8742 | 10010 | ||
8743 | Logging With Bash | 10011 | Logging With Bash |
8744 | ~~~~~~~~~~~~~~~~~ | 10012 | ~~~~~~~~~~~~~~~~~ |
@@ -8749,13 +10017,27 @@ The syntax you use for recipes written in Bash is similar to that of | |||
8749 | recipes written in Python described in the previous section. | 10017 | recipes written in Python described in the previous section. |
8750 | 10018 | ||
8751 | Following is an example written in Bash. The code logs the progress of | 10019 | Following is an example written in Bash. The code logs the progress of |
8752 | the ``do_my_function`` function. do_my_function() { bbdebug 2 "Running | 10020 | the ``do_my_function`` function. |
8753 | do_my_function" if [ exceptional_condition ]; then bbnote "Hit | 10021 | :: |
8754 | exceptional_condition" fi bbdebug 2 "Got to point xyz" if [ | 10022 | |
8755 | warning_trigger ]; then bbwarn "Detected warning_trigger, this might | 10023 | do_my_function() { |
8756 | cause a problem later." fi if [ recoverable_error ]; then bberror "Hit | 10024 | bbdebug 2 "Running do_my_function" |
8757 | recoverable_error, correcting" fi if [ fatal_error ]; then bbfatal | 10025 | if [ exceptional_condition ]; then |
8758 | "fatal_error detected" fi bbdebug 2 "Completed do_my_function" } | 10026 | bbnote "Hit exceptional_condition" |
10027 | fi | ||
10028 | bbdebug 2 "Got to point xyz" | ||
10029 | if [ warning_trigger ]; then | ||
10030 | bbwarn "Detected warning_trigger, this might cause a problem later." | ||
10031 | fi | ||
10032 | if [ recoverable_error ]; then | ||
10033 | bberror "Hit recoverable_error, correcting" | ||
10034 | fi | ||
10035 | if [ fatal_error ]; then | ||
10036 | bbfatal "fatal_error detected" | ||
10037 | fi | ||
10038 | bbdebug 2 "Completed do_my_function" | ||
10039 | } | ||
10040 | |||
8759 | 10041 | ||
8760 | Debugging Parallel Make Races | 10042 | Debugging Parallel Make Races |
8761 | ----------------------------- | 10043 | ----------------------------- |
@@ -8792,66 +10074,73 @@ and creates the following output. | |||
8792 | the listing easier to read. | 10074 | the listing easier to read. |
8793 | 10075 | ||
8794 | If you examine the output or the log file, you see the failure during | 10076 | If you examine the output or the log file, you see the failure during |
8795 | ``make``: \| DEBUG: SITE files ['endian-little', 'bit-32', | 10077 | ``make``: |
8796 | 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common'] | 10078 | :: |
8797 | \| DEBUG: Executing shell function do_compile \| NOTE: make -j 16 \| | 10079 | |
8798 | make --no-print-directory all-am \| /bin/mkdir -p include/near \| | 10080 | | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common'] |
8799 | /bin/mkdir -p include/near \| /bin/mkdir -p include/near \| ln -s | 10081 | | DEBUG: Executing shell function do_compile |
8800 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10082 | | NOTE: make -j 16 |
8801 | 0.14-r0/neard-0.14/include/types.h include/near/types.h \| ln -s | 10083 | | make --no-print-directory all-am |
8802 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10084 | | /bin/mkdir -p include/near |
8803 | 0.14-r0/neard-0.14/include/log.h include/near/log.h \| ln -s | 10085 | | /bin/mkdir -p include/near |
8804 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10086 | | /bin/mkdir -p include/near |
8805 | 0.14-r0/neard-0.14/include/plugin.h include/near/plugin.h \| /bin/mkdir | 10087 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8806 | -p include/near \| /bin/mkdir -p include/near \| /bin/mkdir -p | 10088 | 0.14-r0/neard-0.14/include/types.h include/near/types.h |
8807 | include/near \| ln -s | 10089 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8808 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10090 | 0.14-r0/neard-0.14/include/log.h include/near/log.h |
8809 | 0.14-r0/neard-0.14/include/tag.h include/near/tag.h \| /bin/mkdir -p | 10091 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8810 | include/near \| ln -s | 10092 | 0.14-r0/neard-0.14/include/plugin.h include/near/plugin.h |
8811 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10093 | | /bin/mkdir -p include/near |
8812 | 0.14-r0/neard-0.14/include/adapter.h include/near/adapter.h \| | 10094 | | /bin/mkdir -p include/near |
8813 | /bin/mkdir -p include/near \| ln -s | 10095 | | /bin/mkdir -p include/near |
8814 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10096 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8815 | 0.14-r0/neard-0.14/include/ndef.h include/near/ndef.h \| ln -s | 10097 | 0.14-r0/neard-0.14/include/tag.h include/near/tag.h |
8816 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10098 | | /bin/mkdir -p include/near |
8817 | 0.14-r0/neard-0.14/include/tlv.h include/near/tlv.h \| /bin/mkdir -p | 10099 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8818 | include/near \| /bin/mkdir -p include/near \| ln -s | 10100 | 0.14-r0/neard-0.14/include/adapter.h include/near/adapter.h |
8819 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10101 | | /bin/mkdir -p include/near |
8820 | 0.14-r0/neard-0.14/include/setting.h include/near/setting.h \| | 10102 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8821 | /bin/mkdir -p include/near \| /bin/mkdir -p include/near \| /bin/mkdir | 10103 | 0.14-r0/neard-0.14/include/ndef.h include/near/ndef.h |
8822 | -p include/near \| ln -s | 10104 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8823 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10105 | 0.14-r0/neard-0.14/include/tlv.h include/near/tlv.h |
8824 | 0.14-r0/neard-0.14/include/device.h include/near/device.h \| ln -s | 10106 | | /bin/mkdir -p include/near |
8825 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10107 | | /bin/mkdir -p include/near |
8826 | 0.14-r0/neard-0.14/include/nfc_copy.h include/near/nfc_copy.h \| ln -s | 10108 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8827 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10109 | 0.14-r0/neard-0.14/include/setting.h include/near/setting.h |
8828 | 0.14-r0/neard-0.14/include/snep.h include/near/snep.h \| ln -s | 10110 | | /bin/mkdir -p include/near |
8829 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10111 | | /bin/mkdir -p include/near |
8830 | 0.14-r0/neard-0.14/include/version.h include/near/version.h \| ln -s | 10112 | | /bin/mkdir -p include/near |
8831 | /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | 10113 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8832 | 0.14-r0/neard-0.14/include/dbus.h include/near/dbus.h \| | 10114 | 0.14-r0/neard-0.14/include/device.h include/near/device.h |
8833 | ./src/genbuiltin nfctype1 nfctype2 nfctype3 nfctype4 p2p > src/builtin.h | 10115 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8834 | \| i586-poky-linux-gcc -m32 -march=i586 | 10116 | 0.14-r0/neard-0.14/include/nfc_copy.h include/near/nfc_copy.h |
8835 | --sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/ | 10117 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8836 | build/build/tmp/sysroots/qemux86 -DHAVE_CONFIG_H -I. -I./include -I./src | 10118 | 0.14-r0/neard-0.14/include/snep.h include/near/snep.h |
8837 | -I./gdbus -I/home/pokybuild/ | 10119 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8838 | yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/glib-2.0 | 10120 | 0.14-r0/neard-0.14/include/version.h include/near/version.h |
8839 | -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/ | 10121 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ |
8840 | lib/glib-2.0/include | 10122 | 0.14-r0/neard-0.14/include/dbus.h include/near/dbus.h |
8841 | -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/ | 10123 | | ./src/genbuiltin nfctype1 nfctype2 nfctype3 nfctype4 p2p > src/builtin.h |
8842 | tmp/sysroots/qemux86/usr/include/dbus-1.0 | 10124 | | i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/ |
8843 | -I/home/pokybuild/yocto-autobuilder/yocto-slave/ | 10125 | build/build/tmp/sysroots/qemux86 -DHAVE_CONFIG_H -I. -I./include -I./src -I./gdbus -I/home/pokybuild/ |
8844 | nightly-x86/build/build/tmp/sysroots/qemux86/usr/lib/dbus-1.0/include | 10126 | yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/glib-2.0 |
8845 | -I/home/pokybuild/yocto-autobuilder/ | 10127 | -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/ |
8846 | yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/libnl3 | 10128 | lib/glib-2.0/include -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/ |
8847 | -DNEAR_PLUGIN_BUILTIN -DPLUGINDIR=\""/usr/lib/near/plugins"\" | 10129 | tmp/sysroots/qemux86/usr/include/dbus-1.0 -I/home/pokybuild/yocto-autobuilder/yocto-slave/ |
8848 | -DCONFIGDIR=\""/etc/neard\"" -O2 -pipe -g -feliminate-unused-debug-types | 10130 | nightly-x86/build/build/tmp/sysroots/qemux86/usr/lib/dbus-1.0/include -I/home/pokybuild/yocto-autobuilder/ |
8849 | -c -o tools/snep-send.o tools/snep-send.c \| In file included from | 10131 | yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/libnl3 |
8850 | tools/snep-send.c:16:0: \| tools/../src/near.h:41:23: fatal error: | 10132 | -DNEAR_PLUGIN_BUILTIN -DPLUGINDIR=\""/usr/lib/near/plugins"\" |
8851 | near/dbus.h: No such file or directory \| #include <near/dbus.h> \| ^ \| | 10133 | -DCONFIGDIR=\""/etc/neard\"" -O2 -pipe -g -feliminate-unused-debug-types -c |
8852 | compilation terminated. \| make[1]: \**\* [tools/snep-send.o] Error 1 \| | 10134 | -o tools/snep-send.o tools/snep-send.c |
8853 | make[1]: \**\* Waiting for unfinished jobs.... \| make: \**\* [all] | 10135 | | In file included from tools/snep-send.c:16:0: |
8854 | Error 2 \| ERROR: oe_runmake failed | 10136 | | tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory |
10137 | | #include <near/dbus.h> | ||
10138 | | ^ | ||
10139 | | compilation terminated. | ||
10140 | | make[1]: *** [tools/snep-send.o] Error 1 | ||
10141 | | make[1]: *** Waiting for unfinished jobs.... | ||
10142 | | make: *** [all] Error 2 | ||
10143 | | ERROR: oe_runmake failed | ||
8855 | 10144 | ||
8856 | Reproducing the Error | 10145 | Reproducing the Error |
8857 | ~~~~~~~~~~~~~~~~~~~~~ | 10146 | ~~~~~~~~~~~~~~~~~~~~~ |
@@ -8867,66 +10156,121 @@ build, set the | |||
8867 | :term:`PARALLEL_MAKE` variable | 10156 | :term:`PARALLEL_MAKE` variable |
8868 | in your ``local.conf`` file to a high number (e.g. "-j 20"). Using a | 10157 | in your ``local.conf`` file to a high number (e.g. "-j 20"). Using a |
8869 | high value for ``PARALLEL_MAKE`` increases the chances of the race | 10158 | high value for ``PARALLEL_MAKE`` increases the chances of the race |
8870 | condition showing up: $ bitbake neard | 10159 | condition showing up: |
10160 | :: | ||
10161 | |||
10162 | $ bitbake neard | ||
8871 | 10163 | ||
8872 | Once the local build for "neard" completes, start a ``devshell`` build: | 10164 | Once the local build for "neard" completes, start a ``devshell`` build: |
8873 | $ bitbake neard -c devshell For information on how to use a | 10165 | :: |
10166 | |||
10167 | $ bitbake neard -c devshell | ||
10168 | |||
10169 | For information on how to use a | ||
8874 | ``devshell``, see the "`Using a Development | 10170 | ``devshell``, see the "`Using a Development |
8875 | Shell <#platdev-appdev-devshell>`__" section. | 10171 | Shell <#platdev-appdev-devshell>`__" section. |
8876 | 10172 | ||
8877 | In the ``devshell``, do the following: $ make clean $ make | 10173 | In the ``devshell``, do the following: |
8878 | tools/snep-send.o The ``devshell`` commands cause the failure to clearly | 10174 | :: |
10175 | |||
10176 | $ make clean | ||
10177 | $ make tools/snep-send.o | ||
10178 | |||
10179 | The ``devshell`` commands cause the failure to clearly | ||
8879 | be visible. In this case, a missing dependency exists for the "neard" | 10180 | be visible. In this case, a missing dependency exists for the "neard" |
8880 | Makefile target. Here is some abbreviated, sample output with the | 10181 | Makefile target. Here is some abbreviated, sample output with the |
8881 | missing dependency clearly visible at the end: i586-poky-linux-gcc -m32 | 10182 | missing dependency clearly visible at the end: |
8882 | -march=i586 --sysroot=/home/scott-lenovo/...... . . . tools/snep-send.c | 10183 | :: |
8883 | In file included from tools/snep-send.c:16:0: tools/../src/near.h:41:23: | 10184 | |
8884 | fatal error: near/dbus.h: No such file or directory #include | 10185 | i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/...... |
8885 | <near/dbus.h> ^ compilation terminated. make: \**\* [tools/snep-send.o] | 10186 | . |
8886 | Error 1 $ | 10187 | . |
10188 | . | ||
10189 | tools/snep-send.c | ||
10190 | In file included from tools/snep-send.c:16:0: | ||
10191 | tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory | ||
10192 | #include <near/dbus.h> | ||
10193 | ^ | ||
10194 | compilation terminated. | ||
10195 | make: *** [tools/snep-send.o] Error 1 | ||
10196 | $ | ||
10197 | |||
8887 | 10198 | ||
8888 | Creating a Patch for the Fix | 10199 | Creating a Patch for the Fix |
8889 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 10200 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
8890 | 10201 | ||
8891 | Because there is a missing dependency for the Makefile target, you need | 10202 | Because there is a missing dependency for the Makefile target, you need |
8892 | to patch the ``Makefile.am`` file, which is generated from | 10203 | to patch the ``Makefile.am`` file, which is generated from |
8893 | ``Makefile.in``. You can use Quilt to create the patch: $ quilt new | 10204 | ``Makefile.in``. You can use Quilt to create the patch: |
8894 | parallelmake.patch Patch patches/parallelmake.patch is now on top $ | 10205 | :: |
8895 | quilt add Makefile.am File Makefile.am added to patch | 10206 | |
8896 | patches/parallelmake.patch For more information on using Quilt, see the | 10207 | $ quilt new parallelmake.patch |
10208 | Patch patches/parallelmake.patch is now on top | ||
10209 | $ quilt add Makefile.am | ||
10210 | File Makefile.am added to patch patches/parallelmake.patch | ||
10211 | |||
10212 | For more information on using Quilt, see the | ||
8897 | "`Using Quilt in Your Workflow <#using-a-quilt-workflow>`__" section. | 10213 | "`Using Quilt in Your Workflow <#using-a-quilt-workflow>`__" section. |
8898 | 10214 | ||
8899 | At this point you need to make the edits to ``Makefile.am`` to add the | 10215 | At this point you need to make the edits to ``Makefile.am`` to add the |
8900 | missing dependency. For our example, you have to add the following line | 10216 | missing dependency. For our example, you have to add the following line |
8901 | to the file: tools/snep-send.$(OBJEXT): include/near/dbus.h | 10217 | to the file: |
10218 | :: | ||
10219 | |||
10220 | tools/snep-send.$(OBJEXT): include/near/dbus.h | ||
8902 | 10221 | ||
8903 | Once you have edited the file, use the ``refresh`` command to create the | 10222 | Once you have edited the file, use the ``refresh`` command to create the |
8904 | patch: $ quilt refresh Refreshed patch patches/parallelmake.patch Once | 10223 | patch: |
10224 | :: | ||
10225 | |||
10226 | $ quilt refresh | ||
10227 | Refreshed patch patches/parallelmake.patch | ||
10228 | |||
10229 | Once | ||
8905 | the patch file exists, you need to add it back to the originating recipe | 10230 | the patch file exists, you need to add it back to the originating recipe |
8906 | folder. Here is an example assuming a top-level | 10231 | folder. Here is an example assuming a top-level |
8907 | :term:`Source Directory` named ``poky``: $ | 10232 | :term:`Source Directory` named ``poky``: |
8908 | cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard | 10233 | :: |
10234 | |||
10235 | $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard | ||
10236 | |||
8909 | The final thing you need to do to implement the fix in the build is to | 10237 | The final thing you need to do to implement the fix in the build is to |
8910 | update the "neard" recipe (i.e. ``neard-0.14.bb``) so that the | 10238 | update the "neard" recipe (i.e. ``neard-0.14.bb``) so that the |
8911 | :term:`SRC_URI` statement includes | 10239 | :term:`SRC_URI` statement includes |
8912 | the patch file. The recipe file is in the folder above the patch. Here | 10240 | the patch file. The recipe file is in the folder above the patch. Here |
8913 | is what the edited ``SRC_URI`` statement would look like: SRC_URI = | 10241 | is what the edited ``SRC_URI`` statement would look like: |
8914 | "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \\ | 10242 | :: |
8915 | file://neard.in \\ file://neard.service.in \\ file://parallelmake.patch | 10243 | |
8916 | \\ " | 10244 | SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \ |
10245 | file://neard.in \ | ||
10246 | file://neard.service.in \ | ||
10247 | file://parallelmake.patch \ | ||
10248 | " | ||
8917 | 10249 | ||
8918 | With the patch complete and moved to the correct folder and the | 10250 | With the patch complete and moved to the correct folder and the |
8919 | ``SRC_URI`` statement updated, you can exit the ``devshell``: $ exit | 10251 | ``SRC_URI`` statement updated, you can exit the ``devshell``: |
10252 | :: | ||
10253 | |||
10254 | $ exit | ||
8920 | 10255 | ||
8921 | Testing the Build | 10256 | Testing the Build |
8922 | ~~~~~~~~~~~~~~~~~ | 10257 | ~~~~~~~~~~~~~~~~~ |
8923 | 10258 | ||
8924 | With everything in place, you can get back to trying the build again | 10259 | With everything in place, you can get back to trying the build again |
8925 | locally: $ bitbake neard This build should succeed. | 10260 | locally: |
10261 | :: | ||
10262 | |||
10263 | $ bitbake neard This build should succeed. | ||
8926 | 10264 | ||
8927 | Now you can open up a ``devshell`` again and repeat the clean and make | 10265 | Now you can open up a ``devshell`` again and repeat the clean and make |
8928 | operations as follows: $ bitbake neard -c devshell $ make clean $ make | 10266 | operations as follows: |
8929 | tools/snep-send.o The build should work without issue. | 10267 | :: |
10268 | |||
10269 | $ bitbake neard -c devshell | ||
10270 | $ make clean | ||
10271 | $ make tools/snep-send.o | ||
10272 | |||
10273 | The build should work without issue. | ||
8930 | 10274 | ||
8931 | As with all solved problems, if they originated upstream, you need to | 10275 | As with all solved problems, if they originated upstream, you need to |
8932 | submit the fix for the recipe in OE-Core and upstream so that the | 10276 | submit the fix for the recipe in OE-Core and upstream so that the |
@@ -8998,8 +10342,13 @@ debugger. | |||
8998 | 1. *Configure your build system to construct the companion debug | 10342 | 1. *Configure your build system to construct the companion debug |
8999 | filesystem:* | 10343 | filesystem:* |
9000 | 10344 | ||
9001 | In your ``local.conf`` file, set the following: IMAGE_GEN_DEBUGFS = | 10345 | In your ``local.conf`` file, set the following: |
9002 | "1" IMAGE_FSTYPES_DEBUGFS = "tar.bz2" These options cause the | 10346 | :: |
10347 | |||
10348 | IMAGE_GEN_DEBUGFS = "1" | ||
10349 | IMAGE_FSTYPES_DEBUGFS = "tar.bz2" | ||
10350 | |||
10351 | These options cause the | ||
9003 | OpenEmbedded build system to generate a special companion filesystem | 10352 | OpenEmbedded build system to generate a special companion filesystem |
9004 | fragment, which contains the matching source and debug symbols to | 10353 | fragment, which contains the matching source and debug symbols to |
9005 | your deployable filesystem. The build system does this by looking at | 10354 | your deployable filesystem. The build system does this by looking at |
@@ -9014,26 +10363,44 @@ debugger. | |||
9014 | 2. *Configure the system to include gdbserver in the target filesystem:* | 10363 | 2. *Configure the system to include gdbserver in the target filesystem:* |
9015 | 10364 | ||
9016 | Make the following addition in either your ``local.conf`` file or in | 10365 | Make the following addition in either your ``local.conf`` file or in |
9017 | an image recipe: IMAGE_INSTALL_append = “ gdbserver" The change makes | 10366 | an image recipe: |
10367 | :: | ||
10368 | |||
10369 | IMAGE_INSTALL_append = “ gdbserver" | ||
10370 | |||
10371 | The change makes | ||
9018 | sure the ``gdbserver`` package is included. | 10372 | sure the ``gdbserver`` package is included. |
9019 | 10373 | ||
9020 | 3. *Build the environment:* | 10374 | 3. *Build the environment:* |
9021 | 10375 | ||
9022 | Use the following command to construct the image and the companion | 10376 | Use the following command to construct the image and the companion |
9023 | Debug Filesystem: $ bitbake image Build the cross GDB component and | 10377 | Debug Filesystem: |
10378 | :: | ||
10379 | |||
10380 | $ bitbake image | ||
10381 | |||
10382 | Build the cross GDB component and | ||
9024 | make it available for debugging. Build the SDK that matches the | 10383 | make it available for debugging. Build the SDK that matches the |
9025 | image. Building the SDK is best for a production build that can be | 10384 | image. Building the SDK is best for a production build that can be |
9026 | used later for debugging, especially during long term maintenance: $ | 10385 | used later for debugging, especially during long term maintenance: |
9027 | bitbake -c populate_sdk image | 10386 | :: |
10387 | |||
10388 | $ bitbake -c populate_sdk image | ||
9028 | 10389 | ||
9029 | Alternatively, you can build the minimal toolchain components that | 10390 | Alternatively, you can build the minimal toolchain components that |
9030 | match the target. Doing so creates a smaller than typical SDK and | 10391 | match the target. Doing so creates a smaller than typical SDK and |
9031 | only contains a minimal set of components with which to build simple | 10392 | only contains a minimal set of components with which to build simple |
9032 | test applications, as well as run the debugger: $ bitbake | 10393 | test applications, as well as run the debugger: |
9033 | meta-toolchain | 10394 | :: |
10395 | |||
10396 | $ bitbake meta-toolchain | ||
10397 | |||
10398 | A final method is to build Gdb itself within the build system: | ||
10399 | :: | ||
9034 | 10400 | ||
9035 | A final method is to build Gdb itself within the build system: $ | 10401 | $ bitbake gdb-cross-<architecture> |
9036 | bitbake gdb-cross-architecture Doing so produces a temporary copy of | 10402 | |
10403 | Doing so produces a temporary copy of | ||
9037 | ``cross-gdb`` you can use for debugging during development. While | 10404 | ``cross-gdb`` you can use for debugging during development. While |
9038 | this is the quickest approach, the two previous methods in this step | 10405 | this is the quickest approach, the two previous methods in this step |
9039 | are better when considering long-term maintenance strategies. | 10406 | are better when considering long-term maintenance strategies. |
@@ -9048,11 +10415,13 @@ debugger. | |||
9048 | 10415 | ||
9049 | 4. *Set up the* ``debugfs`` | 10416 | 4. *Set up the* ``debugfs`` |
9050 | 10417 | ||
9051 | Run the following commands to set up the ``debugfs``: $ mkdir debugfs | 10418 | Run the following commands to set up the ``debugfs``: |
9052 | $ cd debugfs $ tar xvfj | 10419 | :: |
9053 | build-dir/tmp-glibc/deploy/images/machine/image.rootfs.tar.bz2 $ tar | 10420 | |
9054 | xvfj | 10421 | $ mkdir debugfs |
9055 | build-dir/tmp-glibc/deploy/images/machine/image-dbg.rootfs.tar.bz2 | 10422 | $ cd debugfs |
10423 | $ tar xvfj build-dir/tmp-glibc/deploy/images/machine/image.rootfs.tar.bz2 | ||
10424 | $ tar xvfj build-dir/tmp-glibc/deploy/images/machine/image-dbg.rootfs.tar.bz2 | ||
9056 | 10425 | ||
9057 | 5. *Set up GDB* | 10426 | 5. *Set up GDB* |
9058 | 10427 | ||
@@ -9076,15 +10445,25 @@ debugger. | |||
9076 | 10445 | ||
9077 | Debugging a program involves running gdbserver on the target and then | 10446 | Debugging a program involves running gdbserver on the target and then |
9078 | running Gdb on the host. The example in this step debugs ``gzip``: | 10447 | running Gdb on the host. The example in this step debugs ``gzip``: |
9079 | root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help For | 10448 | :: |
10449 | |||
10450 | root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help | ||
10451 | |||
10452 | For | ||
9080 | additional gdbserver options, see the `GDB Server | 10453 | additional gdbserver options, see the `GDB Server |
9081 | Documentation <https://www.gnu.org/software/gdb/documentation/>`__. | 10454 | Documentation <https://www.gnu.org/software/gdb/documentation/>`__. |
9082 | 10455 | ||
9083 | After running gdbserver on the target, you need to run Gdb on the | 10456 | After running gdbserver on the target, you need to run Gdb on the |
9084 | host and configure it and connect to the target. Use these commands: | 10457 | host and configure it and connect to the target. Use these commands: |
9085 | $ cd directory-holding-the-debugfs-directory $ arch-gdb (gdb) set | 10458 | :: |
9086 | sysroot debugfs (gdb) set substitute-path /usr/src/debug | 10459 | |
9087 | debugfs/usr/src/debug (gdb) target remote IP-of-target:1234 At this | 10460 | $ cd directory-holding-the-debugfs-directory |
10461 | $ arch-gdb | ||
10462 | (gdb) set sysroot debugfs | ||
10463 | (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug | ||
10464 | (gdb) target remote IP-of-target:1234 | ||
10465 | |||
10466 | At this | ||
9088 | point, everything should automatically load (i.e. matching binaries, | 10467 | point, everything should automatically load (i.e. matching binaries, |
9089 | symbols and headers). | 10468 | symbols and headers). |
9090 | 10469 | ||
@@ -9110,9 +10489,14 @@ debugger. | |||
9110 | If the binary is processed through the debug splitting in | 10489 | If the binary is processed through the debug splitting in |
9111 | OpenEmbedded, you should also copy the debug items (i.e. ``.debug`` | 10490 | OpenEmbedded, you should also copy the debug items (i.e. ``.debug`` |
9112 | contents and corresponding ``/usr/src/debug`` files) from the work | 10491 | contents and corresponding ``/usr/src/debug`` files) from the work |
9113 | directory. Here is an example: $ bitbake bash $ bitbake -c devshell | 10492 | directory. Here is an example: |
9114 | bash $ cd .. $ scp packages-split/bash/bin/bash target:/bin/bash $ cp | 10493 | :: |
9115 | -a packages-split/bash-dbg/\* path/debugfs | 10494 | |
10495 | $ bitbake bash | ||
10496 | $ bitbake -c devshell bash | ||
10497 | $ cd .. | ||
10498 | $ scp packages-split/bash/bin/bash target:/bin/bash | ||
10499 | $ cp -a packages-split/bash-dbg/\* path/debugfs | ||
9116 | 10500 | ||
9117 | Debugging with the GNU Project Debugger (GDB) on the Target | 10501 | Debugging with the GNU Project Debugger (GDB) on the Target |
9118 | ----------------------------------------------------------- | 10502 | ----------------------------------------------------------- |
@@ -9131,12 +10515,21 @@ To support this kind of debugging, you need do the following: | |||
9131 | IMAGE_INSTALL_append = " gdb" Alternatively, you can add | 10515 | IMAGE_INSTALL_append = " gdb" Alternatively, you can add |
9132 | "tools-debug" to | 10516 | "tools-debug" to |
9133 | :term:`IMAGE_FEATURES`: | 10517 | :term:`IMAGE_FEATURES`: |
9134 | IMAGE_FEATURES_append = " tools-debug" | 10518 | :: |
10519 | |||
10520 | IMAGE_FEATURES_append = " tools-debug" | ||
9135 | 10521 | ||
9136 | - Ensure that debug symbols are present. You can make sure these | 10522 | - Ensure that debug symbols are present. You can make sure these |
9137 | symbols are present by installing ``-dbg``: IMAGE_INSTALL_append = " | 10523 | symbols are present by installing ``-dbg``: |
9138 | packagename-dbg" Alternatively, you can do the following to include | 10524 | :: |
9139 | all the debug symbols: IMAGE_FEATURES_append = " dbg-pkgs" | 10525 | |
10526 | IMAGE_INSTALL_append = "packagename-dbg" | ||
10527 | |||
10528 | Alternatively, you can do the following to include | ||
10529 | all the debug symbols: | ||
10530 | :: | ||
10531 | |||
10532 | IMAGE_FEATURES_append = " dbg-pkgs" | ||
9140 | 10533 | ||
9141 | .. note:: | 10534 | .. note:: |
9142 | 10535 | ||
@@ -9152,7 +10545,7 @@ To support this kind of debugging, you need do the following: | |||
9152 | :: | 10545 | :: |
9153 | 10546 | ||
9154 | DEBUG_BUILD = "1" | 10547 | DEBUG_BUILD = "1" |
9155 | 10548 | ||
9156 | 10549 | ||
9157 | Consider that this will reduce the application's performance and is | 10550 | Consider that this will reduce the application's performance and is |
9158 | recommended only for debugging purposes. | 10551 | recommended only for debugging purposes. |
@@ -9198,12 +10591,28 @@ Here are some other tips that you might find useful: | |||
9198 | Using GNU Grep, you can use the following shell function to | 10591 | Using GNU Grep, you can use the following shell function to |
9199 | recursively search through common recipe-related files, skipping | 10592 | recursively search through common recipe-related files, skipping |
9200 | binary files, ``.git`` directories, and the Build Directory (assuming | 10593 | binary files, ``.git`` directories, and the Build Directory (assuming |
9201 | its name starts with "build"): g() { grep -Ir \\ --exclude-dir=.git | 10594 | its name starts with "build"): |
9202 | \\ --exclude-dir='build*' \\ --include='*.bb*' \\ --include='*.inc*' | 10595 | :: |
9203 | \\ --include='*.conf*' \\ --include='*.py*' \\ "$@" } Following are | 10596 | |
9204 | some usage examples: $ g FOO # Search recursively for "FOO" $ g -i | 10597 | g() { |
9205 | foo # Search recursively for "foo", ignoring case $ g -w FOO # Search | 10598 | grep -Ir \ |
9206 | recursively for "FOO" as a word, ignoring e.g. "FOOBAR" If figuring | 10599 | --exclude-dir=.git \ |
10600 | --exclude-dir='build*' \ | ||
10601 | --include='*.bb*' \ | ||
10602 | --include='*.inc*' \ | ||
10603 | --include='*.conf*' \ | ||
10604 | --include='*.py*' \ | ||
10605 | "$@" | ||
10606 | } | ||
10607 | |||
10608 | Following are some usage examples: | ||
10609 | :: | ||
10610 | |||
10611 | $ g FOO # Search recursively for "FOO" | ||
10612 | $ g -i foo # Search recursively for "foo", ignoring case | ||
10613 | $ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR" | ||
10614 | |||
10615 | If figuring | ||
9207 | out how some feature works requires a lot of searching, it might | 10616 | out how some feature works requires a lot of searching, it might |
9208 | indicate that the documentation should be extended or improved. In | 10617 | indicate that the documentation should be extended or improved. In |
9209 | such cases, consider filing a documentation bug using the Yocto | 10618 | such cases, consider filing a documentation bug using the Yocto |
@@ -9236,8 +10645,8 @@ Submitting a Defect Against the Yocto Project | |||
9236 | Use the Yocto Project implementation of | 10645 | Use the Yocto Project implementation of |
9237 | `Bugzilla <http://www.bugzilla.org/about/>`__ to submit a defect (bug) | 10646 | `Bugzilla <http://www.bugzilla.org/about/>`__ to submit a defect (bug) |
9238 | against the Yocto Project. For additional information on this | 10647 | against the Yocto Project. For additional information on this |
9239 | implementation of Bugzilla see the "`Yocto Project | 10648 | implementation of Bugzilla see the :ref:"`Yocto Project |
9240 | Bugzilla <&YOCTO_DOCS_REF_URL;#resources-bugtracker>`__" section in the | 10649 | Bugzilla <resources-bugtracker>`" section in the |
9241 | Yocto Project Reference Manual. For more detail on any of the following | 10650 | Yocto Project Reference Manual. For more detail on any of the following |
9242 | steps, see the Yocto Project | 10651 | steps, see the Yocto Project |
9243 | :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`. | 10652 | :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`. |
@@ -9353,9 +10762,7 @@ Yocto general mailing list or on the openembedded-devel mailing list. | |||
9353 | 10762 | ||
9354 | You can also push a change upstream and request a maintainer to pull the | 10763 | You can also push a change upstream and request a maintainer to pull the |
9355 | change into the component's upstream repository. You do this by pushing | 10764 | change into the component's upstream repository. You do this by pushing |
9356 | to a contribution repository that is upstream. See the "`Git Workflows | 10765 | to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-and-the-yocto-project`" |
9357 | and the Yocto | ||
9358 | Project <&YOCTO_DOCS_OM_URL;#gs-git-workflows-and-the-yocto-project>`__" | ||
9359 | section in the Yocto Project Overview and Concepts Manual for additional | 10766 | section in the Yocto Project Overview and Concepts Manual for additional |
9360 | concepts on working in the Yocto Project development environment. | 10767 | concepts on working in the Yocto Project development environment. |
9361 | 10768 | ||
@@ -9415,23 +10822,34 @@ repository: | |||
9415 | - Be sure to include a "Signed-off-by:" line in the same style as | 10822 | - Be sure to include a "Signed-off-by:" line in the same style as |
9416 | required by the Linux kernel. Adding this line signifies that you, | 10823 | required by the Linux kernel. Adding this line signifies that you, |
9417 | the submitter, have agreed to the Developer's Certificate of | 10824 | the submitter, have agreed to the Developer's Certificate of |
9418 | Origin 1.1 as follows: Developer's Certificate of Origin 1.1 By | 10825 | Origin 1.1 as follows: |
9419 | making a contribution to this project, I certify that: (a) The | 10826 | :: |
9420 | contribution was created in whole or in part by me and I have the | 10827 | |
9421 | right to submit it under the open source license indicated in the | 10828 | Developer's Certificate of Origin 1.1 |
9422 | file; or (b) The contribution is based upon previous work that, to | 10829 | |
9423 | the best of my knowledge, is covered under an appropriate open | 10830 | By making a contribution to this project, I certify that: |
9424 | source license and I have the right under that license to submit | 10831 | |
9425 | that work with modifications, whether created in whole or in part | 10832 | (a) The contribution was created in whole or in part by me and I |
9426 | by me, under the same open source license (unless I am permitted | 10833 | have the right to submit it under the open source license |
9427 | to submit under a different license), as indicated in the file; or | 10834 | indicated in the file; or |
9428 | (c) The contribution was provided directly to me by some other | 10835 | |
9429 | person who certified (a), (b) or (c) and I have not modified it. | 10836 | (b) The contribution is based upon previous work that, to the best |
9430 | (d) I understand and agree that this project and the contribution | 10837 | of my knowledge, is covered under an appropriate open source |
9431 | are public and that a record of the contribution (including all | 10838 | license and I have the right under that license to submit that |
9432 | personal information I submit with it, including my sign-off) is | 10839 | work with modifications, whether created in whole or in part |
9433 | maintained indefinitely and may be redistributed consistent with | 10840 | by me, under the same open source license (unless I am |
9434 | this project or the open source license(s) involved. | 10841 | permitted to submit under a different license), as indicated |
10842 | in the file; or | ||
10843 | |||
10844 | (c) The contribution was provided directly to me by some other | ||
10845 | person who certified (a), (b) or (c) and I have not modified | ||
10846 | it. | ||
10847 | |||
10848 | (d) I understand and agree that this project and the contribution | ||
10849 | are public and that a record of the contribution (including all | ||
10850 | personal information I submit with it, including my sign-off) is | ||
10851 | maintained indefinitely and may be redistributed consistent with | ||
10852 | this project or the open source license(s) involved. | ||
9435 | 10853 | ||
9436 | - Provide a single-line summary of the change. and, if more | 10854 | - Provide a single-line summary of the change. and, if more |
9437 | explanation is needed, provide more detail in the body of the | 10855 | explanation is needed, provide more detail in the body of the |
@@ -9460,19 +10878,29 @@ repository: | |||
9460 | specific convention for bug references - any commit that addresses | 10878 | specific convention for bug references - any commit that addresses |
9461 | a specific bug should use the following form for the detailed | 10879 | a specific bug should use the following form for the detailed |
9462 | description. Be sure to use the actual bug-tracking ID from | 10880 | description. Be sure to use the actual bug-tracking ID from |
9463 | Bugzilla for bug-id: Fixes [YOCTO #bug-id] detailed description of | 10881 | Bugzilla for bug-id: |
9464 | change | 10882 | :: |
10883 | |||
10884 | Fixes [YOCTO #bug-id] | ||
10885 | |||
10886 | detailed description of change | ||
9465 | 10887 | ||
9466 | 4. *Push Your Commits to a "Contrib" Upstream:* If you have arranged for | 10888 | 4. *Push Your Commits to a "Contrib" Upstream:* If you have arranged for |
9467 | permissions to push to an upstream contrib repository, push the | 10889 | permissions to push to an upstream contrib repository, push the |
9468 | change to that repository: $ git push upstream_remote_repo | 10890 | change to that repository: |
9469 | local_branch_name For example, suppose you have permissions to push | 10891 | :: |
10892 | |||
10893 | $ git push upstream_remote_repo local_branch_name | ||
10894 | |||
10895 | For example, suppose you have permissions to push | ||
9470 | into the upstream ``meta-intel-contrib`` repository and you are | 10896 | into the upstream ``meta-intel-contrib`` repository and you are |
9471 | working in a local branch named your_name\ ``/README``. The following | 10897 | working in a local branch named your_name\ ``/README``. The following |
9472 | command pushes your local commits to the ``meta-intel-contrib`` | 10898 | command pushes your local commits to the ``meta-intel-contrib`` |
9473 | upstream repository and puts the commit in a branch named | 10899 | upstream repository and puts the commit in a branch named |
9474 | your_name\ ``/README``: $ git push meta-intel-contrib | 10900 | your_name\ ``/README``: |
9475 | your_name/README | 10901 | :: |
10902 | |||
10903 | $ git push meta-intel-contrib your_name/README | ||
9476 | 10904 | ||
9477 | 5. *Determine Who to Notify:* Determine the maintainer or the mailing | 10905 | 5. *Determine Who to Notify:* Determine the maintainer or the mailing |
9478 | list that you need to notify for the change. | 10906 | list that you need to notify for the change. |
@@ -9485,18 +10913,22 @@ repository: | |||
9485 | located in the :term:`Source Directory` at | 10913 | located in the :term:`Source Directory` at |
9486 | ``meta/conf/distro/include``, to see who is responsible for code. | 10914 | ``meta/conf/distro/include``, to see who is responsible for code. |
9487 | 10915 | ||
9488 | - *Search by File:* Using `Git <&YOCTO_DOCS_OM_URL;#git>`__, you can | 10916 | - *Search by File:* Using :ref:`overview-manual/overview-manual-development-environment:git`, you can |
9489 | enter the following command to bring up a short list of all | 10917 | enter the following command to bring up a short list of all |
9490 | commits against a specific file: git shortlog -- filename Just | 10918 | commits against a specific file: |
9491 | provide the name of the file for which you are interested. The | 10919 | :: |
10920 | |||
10921 | git shortlog -- filename | ||
10922 | |||
10923 | Just provide the name of the file for which you are interested. The | ||
9492 | information returned is not ordered by history but does include a | 10924 | information returned is not ordered by history but does include a |
9493 | list of everyone who has committed grouped by name. From the list, | 10925 | list of everyone who has committed grouped by name. From the list, |
9494 | you can see who is responsible for the bulk of the changes against | 10926 | you can see who is responsible for the bulk of the changes against |
9495 | the file. | 10927 | the file. |
9496 | 10928 | ||
9497 | - *Examine the List of Mailing Lists:* For a list of the Yocto | 10929 | - *Examine the List of Mailing Lists:* For a list of the Yocto |
9498 | Project and related mailing lists, see the "`Mailing | 10930 | Project and related mailing lists, see the ":ref:`Mailing |
9499 | lists <&YOCTO_DOCS_REF_URL;#resources-mailinglist>`__" section in | 10931 | lists <resources-mailinglist>`" section in |
9500 | the Yocto Project Reference Manual. | 10932 | the Yocto Project Reference Manual. |
9501 | 10933 | ||
9502 | 6. *Make a Pull Request:* Notify the maintainer or the mailing list that | 10934 | 6. *Make a Pull Request:* Notify the maintainer or the mailing list that |
@@ -9518,8 +10950,11 @@ repository: | |||
9518 | First, create the pull request. For example, the following command | 10950 | First, create the pull request. For example, the following command |
9519 | runs the script, specifies the upstream repository in the contrib | 10951 | runs the script, specifies the upstream repository in the contrib |
9520 | directory into which you pushed the change, and provides a subject | 10952 | directory into which you pushed the change, and provides a subject |
9521 | line in the created patch files: $ ~/poky/scripts/create-pull-request | 10953 | line in the created patch files: |
9522 | -u meta-intel-contrib -s "Updated Manual Section Reference in README" | 10954 | :: |
10955 | |||
10956 | $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README" | ||
10957 | |||
9523 | Running this script forms ``*.patch`` files in a folder named | 10958 | Running this script forms ``*.patch`` files in a folder named |
9524 | ``pull-``\ PID in the current directory. One of the patch files is a | 10959 | ``pull-``\ PID in the current directory. One of the patch files is a |
9525 | cover letter. | 10960 | cover letter. |
@@ -9529,9 +10964,12 @@ repository: | |||
9529 | editing the cover letter, send the pull request. For example, the | 10964 | editing the cover letter, send the pull request. For example, the |
9530 | following command runs the script and specifies the patch directory | 10965 | following command runs the script and specifies the patch directory |
9531 | and email address. In this example, the email address is a mailing | 10966 | and email address. In this example, the email address is a mailing |
9532 | list: $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 | 10967 | list: |
9533 | -t meta-intel@yoctoproject.org You need to follow the prompts as the | 10968 | :: |
9534 | script is interactive. | 10969 | |
10970 | $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org | ||
10971 | |||
10972 | You need to follow the prompts as the script is interactive. | ||
9535 | 10973 | ||
9536 | .. note:: | 10974 | .. note:: |
9537 | 10975 | ||
@@ -9542,7 +10980,7 @@ repository: | |||
9542 | 10980 | ||
9543 | $ poky/scripts/create-pull-request -h | 10981 | $ poky/scripts/create-pull-request -h |
9544 | $ poky/scripts/send-pull-request -h | 10982 | $ poky/scripts/send-pull-request -h |
9545 | 10983 | ||
9546 | 10984 | ||
9547 | .. _submitting-a-patch: | 10985 | .. _submitting-a-patch: |
9548 | 10986 | ||
@@ -9557,8 +10995,7 @@ Depending on the components changed, you need to submit the email to a | |||
9557 | specific mailing list. For some guidance on which mailing list to use, | 10995 | specific mailing list. For some guidance on which mailing list to use, |
9558 | see the `list <#figuring-out-the-mailing-list-to-use>`__ at the | 10996 | see the `list <#figuring-out-the-mailing-list-to-use>`__ at the |
9559 | beginning of this section. For a description of all the available | 10997 | beginning of this section. For a description of all the available |
9560 | mailing lists, see the "`Mailing | 10998 | mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the |
9561 | Lists <&YOCTO_DOCS_REF_URL;#resources-mailinglist>`__" section in the | ||
9562 | Yocto Project Reference Manual. | 10999 | Yocto Project Reference Manual. |
9563 | 11000 | ||
9564 | Here is the general procedure on how to submit a patch through email | 11001 | Here is the general procedure on how to submit a patch through email |
@@ -9589,8 +11026,14 @@ without using the scripts: | |||
9589 | provide the command, you must include a revision list or a number of | 11026 | provide the command, you must include a revision list or a number of |
9590 | patches as part of the command. For example, either of these two | 11027 | patches as part of the command. For example, either of these two |
9591 | commands takes your most recent single commit and formats it as an | 11028 | commands takes your most recent single commit and formats it as an |
9592 | email message in the current directory: $ git format-patch -1 or $ | 11029 | email message in the current directory: |
9593 | git format-patch HEAD~ | 11030 | :: |
11031 | |||
11032 | $ git format-patch -1 | ||
11033 | |||
11034 | or :: | ||
11035 | |||
11036 | $ git format-patch HEAD~ | ||
9594 | 11037 | ||
9595 | After the command is run, the current directory contains a numbered | 11038 | After the command is run, the current directory contains a numbered |
9596 | ``.patch`` file for the commit. | 11039 | ``.patch`` file for the commit. |
@@ -9647,7 +11090,7 @@ without using the scripts: | |||
9647 | Working With Licenses | 11090 | Working With Licenses |
9648 | ===================== | 11091 | ===================== |
9649 | 11092 | ||
9650 | As mentioned in the "`Licensing <&YOCTO_DOCS_OM_URL;#licensing>`__" | 11093 | As mentioned in the ":ref:`overview-manual/overview-manual-development-environment:licensing`" |
9651 | section in the Yocto Project Overview and Concepts Manual, open source | 11094 | section in the Yocto Project Overview and Concepts Manual, open source |
9652 | projects are open to the public and they consequently have different | 11095 | projects are open to the public and they consequently have different |
9653 | licensing structures in place. This section describes the mechanism by | 11096 | licensing structures in place. This section describes the mechanism by |
@@ -9676,10 +11119,13 @@ Specifying the ``LIC_FILES_CHKSUM`` Variable | |||
9676 | 11119 | ||
9677 | The ``LIC_FILES_CHKSUM`` variable contains checksums of the license text | 11120 | The ``LIC_FILES_CHKSUM`` variable contains checksums of the license text |
9678 | in the source code for the recipe. Following is an example of how to | 11121 | in the source code for the recipe. Following is an example of how to |
9679 | specify ``LIC_FILES_CHKSUM``: LIC_FILES_CHKSUM = | 11122 | specify ``LIC_FILES_CHKSUM``: |
9680 | "file://COPYING;md5=xxxx \\ | 11123 | :: |
9681 | file://licfile1.txt;beginline=5;endline=29;md5=yyyy \\ | 11124 | |
9682 | file://licfile2.txt;endline=50;md5=zzzz \\ ..." | 11125 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ |
11126 | file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ | ||
11127 | file://licfile2.txt;endline=50;md5=zzzz \ | ||
11128 | ..." | ||
9683 | 11129 | ||
9684 | .. note:: | 11130 | .. note:: |
9685 | 11131 | ||
@@ -9697,10 +11143,12 @@ variable as the default directory when searching files listed in | |||
9697 | ``LIC_FILES_CHKSUM``. The previous example employs the default | 11143 | ``LIC_FILES_CHKSUM``. The previous example employs the default |
9698 | directory. | 11144 | directory. |
9699 | 11145 | ||
9700 | Consider this next example: LIC_FILES_CHKSUM = | 11146 | Consider this next example: |
9701 | "file://src/ls.c;beginline=5;endline=16;\\ | 11147 | :: |
9702 | md5=bb14ed3c4cda583abc85401304b5cd4e" LIC_FILES_CHKSUM = | 11148 | |
9703 | "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" | 11149 | LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ |
11150 | md5=bb14ed3c4cda583abc85401304b5cd4e" | ||
11151 | LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" | ||
9704 | 11152 | ||
9705 | The first line locates a file in ``${S}/src/ls.c`` and isolates lines | 11153 | The first line locates a file in ``${S}/src/ls.c`` and isolates lines |
9706 | five through 16 as license text. The second line refers to a file in | 11154 | five through 16 as license text. The second line refers to a file in |
@@ -9760,10 +11208,19 @@ are defined on a recipe-by-recipe basis through the | |||
9760 | :term:`LICENSE_FLAGS` variable | 11208 | :term:`LICENSE_FLAGS` variable |
9761 | definition in the affected recipe. For instance, the | 11209 | definition in the affected recipe. For instance, the |
9762 | ``poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly`` recipe | 11210 | ``poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly`` recipe |
9763 | contains the following statement: LICENSE_FLAGS = "commercial" Here is a | 11211 | contains the following statement: |
11212 | :: | ||
11213 | |||
11214 | LICENSE_FLAGS = "commercial" | ||
11215 | |||
11216 | Here is a | ||
9764 | slightly more complicated example that contains both an explicit recipe | 11217 | slightly more complicated example that contains both an explicit recipe |
9765 | name and version (after variable expansion): LICENSE_FLAGS = | 11218 | name and version (after variable expansion): |
9766 | "license_${PN}_${PV}" In order for a component restricted by a | 11219 | :: |
11220 | |||
11221 | LICENSE_FLAGS = "license_${PN}_${PV}" | ||
11222 | |||
11223 | In order for a component restricted by a | ||
9767 | ``LICENSE_FLAGS`` definition to be enabled and included in an image, it | 11224 | ``LICENSE_FLAGS`` definition to be enabled and included in an image, it |
9768 | needs to have a matching entry in the global | 11225 | needs to have a matching entry in the global |
9769 | :term:`LICENSE_FLAGS_WHITELIST` | 11226 | :term:`LICENSE_FLAGS_WHITELIST` |
@@ -9774,13 +11231,21 @@ could add either the string "commercial_gst-plugins-ugly" or the more | |||
9774 | general string "commercial" to ``LICENSE_FLAGS_WHITELIST``. See the | 11231 | general string "commercial" to ``LICENSE_FLAGS_WHITELIST``. See the |
9775 | "`License Flag Matching <#license-flag-matching>`__" section for a full | 11232 | "`License Flag Matching <#license-flag-matching>`__" section for a full |
9776 | explanation of how ``LICENSE_FLAGS`` matching works. Here is the | 11233 | explanation of how ``LICENSE_FLAGS`` matching works. Here is the |
9777 | example: LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" | 11234 | example: |
11235 | :: | ||
11236 | |||
11237 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" | ||
11238 | |||
9778 | Likewise, to additionally enable the package built from the recipe | 11239 | Likewise, to additionally enable the package built from the recipe |
9779 | containing ``LICENSE_FLAGS = "license_${PN}_${PV}"``, and assuming that | 11240 | containing ``LICENSE_FLAGS = "license_${PN}_${PV}"``, and assuming that |
9780 | the actual recipe name was ``emgd_1.10.bb``, the following string would | 11241 | the actual recipe name was ``emgd_1.10.bb``, the following string would |
9781 | enable that package as well as the original ``gst-plugins-ugly`` | 11242 | enable that package as well as the original ``gst-plugins-ugly`` |
9782 | package: LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly | 11243 | package: |
9783 | license_emgd_1.10" As a convenience, you do not need to specify the | 11244 | :: |
11245 | |||
11246 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" | ||
11247 | |||
11248 | As a convenience, you do not need to specify the | ||
9784 | complete license string in the whitelist for every package. You can use | 11249 | complete license string in the whitelist for every package. You can use |
9785 | an abbreviated form, which consists of just the first portion or | 11250 | an abbreviated form, which consists of just the first portion or |
9786 | portions of the license string before the initial underscore character | 11251 | portions of the license string before the initial underscore character |
@@ -9788,8 +11253,10 @@ or characters. A partial string will match any license that contains the | |||
9788 | given string as the first portion of its license. For example, the | 11253 | given string as the first portion of its license. For example, the |
9789 | following whitelist string will also match both of the packages | 11254 | following whitelist string will also match both of the packages |
9790 | previously mentioned as well as any other packages that have licenses | 11255 | previously mentioned as well as any other packages that have licenses |
9791 | starting with "commercial" or "license". LICENSE_FLAGS_WHITELIST = | 11256 | starting with "commercial" or "license". |
9792 | "commercial license" | 11257 | :: |
11258 | |||
11259 | LICENSE_FLAGS_WHITELIST = "commercial license" | ||
9793 | 11260 | ||
9794 | License Flag Matching | 11261 | License Flag Matching |
9795 | ~~~~~~~~~~~~~~~~~~~~~ | 11262 | ~~~~~~~~~~~~~~~~~~~~~ |
@@ -9833,7 +11300,12 @@ matches any expanded ``LICENSE_FLAGS`` definition that starts with the | |||
9833 | string "commercial" such as "commercial_foo" and "commercial_bar", which | 11300 | string "commercial" such as "commercial_foo" and "commercial_bar", which |
9834 | are the strings the build system automatically generates for | 11301 | are the strings the build system automatically generates for |
9835 | hypothetical recipes named "foo" and "bar" assuming those recipes simply | 11302 | hypothetical recipes named "foo" and "bar" assuming those recipes simply |
9836 | specify the following: LICENSE_FLAGS = "commercial" Thus, you can choose | 11303 | specify the following: |
11304 | :: | ||
11305 | |||
11306 | LICENSE_FLAGS = "commercial" | ||
11307 | |||
11308 | Thus, you can choose | ||
9837 | to exhaustively enumerate each license flag in the whitelist and allow | 11309 | to exhaustively enumerate each license flag in the whitelist and allow |
9838 | only specific recipes into the image, or you can use a string subset | 11310 | only specific recipes into the image, or you can use a string subset |
9839 | that causes a broader range of matches to allow a range of recipes into | 11311 | that causes a broader range of matches to allow a range of recipes into |
@@ -9868,19 +11340,31 @@ Other Variables Related to Commercial Licenses | |||
9868 | Other helpful variables related to commercial license handling exist and | 11340 | Other helpful variables related to commercial license handling exist and |
9869 | are defined in the | 11341 | are defined in the |
9870 | ``poky/meta/conf/distro/include/default-distrovars.inc`` file: | 11342 | ``poky/meta/conf/distro/include/default-distrovars.inc`` file: |
9871 | COMMERCIAL_AUDIO_PLUGINS ?= "" COMMERCIAL_VIDEO_PLUGINS ?= "" If you | 11343 | :: |
11344 | |||
11345 | COMMERCIAL_AUDIO_PLUGINS ?= "" | ||
11346 | COMMERCIAL_VIDEO_PLUGINS ?= "" | ||
11347 | |||
11348 | If you | ||
9872 | want to enable these components, you can do so by making sure you have | 11349 | want to enable these components, you can do so by making sure you have |
9873 | statements similar to the following in your ``local.conf`` configuration | 11350 | statements similar to the following in your ``local.conf`` configuration |
9874 | file: COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \\ | 11351 | file: |
9875 | gst-plugins-ugly-mpegaudioparse" COMMERCIAL_VIDEO_PLUGINS = | 11352 | :: |
9876 | "gst-plugins-ugly-mpeg2dec \\ gst-plugins-ugly-mpegstream | 11353 | |
9877 | gst-plugins-bad-mpegvideoparse" LICENSE_FLAGS_WHITELIST = | 11354 | COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ |
9878 | "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" | 11355 | gst-plugins-ugly-mpegaudioparse" |
11356 | COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \ | ||
11357 | gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" | ||
11358 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" | ||
11359 | |||
11360 | |||
9879 | Of course, you could also create a matching whitelist for those | 11361 | Of course, you could also create a matching whitelist for those |
9880 | components using the more general "commercial" in the whitelist, but | 11362 | components using the more general "commercial" in the whitelist, but |
9881 | that would also enable all the other packages with ``LICENSE_FLAGS`` | 11363 | that would also enable all the other packages with ``LICENSE_FLAGS`` |
9882 | containing "commercial", which you may or may not want: | 11364 | containing "commercial", which you may or may not want: |
9883 | LICENSE_FLAGS_WHITELIST = "commercial" | 11365 | :: |
11366 | |||
11367 | LICENSE_FLAGS_WHITELIST = "commercial" | ||
9884 | 11368 | ||
9885 | Specifying audio and video plugins as part of the | 11369 | Specifying audio and video plugins as part of the |
9886 | ``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements | 11370 | ``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements |
@@ -9958,8 +11442,13 @@ of compliance in mind. | |||
9958 | One way of doing this (but certainly not the only way) is to release | 11442 | One way of doing this (but certainly not the only way) is to release |
9959 | just the source as a tarball. You can do this by adding the following to | 11443 | just the source as a tarball. You can do this by adding the following to |
9960 | the ``local.conf`` file found in the | 11444 | the ``local.conf`` file found in the |
9961 | :term:`Build Directory`: INHERIT += | 11445 | :term:`Build Directory`: |
9962 | "archiver" ARCHIVER_MODE[src] = "original" During the creation of your | 11446 | :: |
11447 | |||
11448 | INHERIT += "archiver" | ||
11449 | ARCHIVER_MODE[src] = "original" | ||
11450 | |||
11451 | During the creation of your | ||
9963 | image, the source from all recipes that deploy packages to the image is | 11452 | image, the source from all recipes that deploy packages to the image is |
9964 | placed within subdirectories of ``DEPLOY_DIR/sources`` based on the | 11453 | placed within subdirectories of ``DEPLOY_DIR/sources`` based on the |
9965 | :term:`LICENSE` for each recipe. | 11454 | :term:`LICENSE` for each recipe. |
@@ -9969,19 +11458,34 @@ the size of the directory can get large. | |||
9969 | 11458 | ||
9970 | A way to help mitigate the size issue is to only release tarballs for | 11459 | A way to help mitigate the size issue is to only release tarballs for |
9971 | licenses that require the release of source. Let us assume you are only | 11460 | licenses that require the release of source. Let us assume you are only |
9972 | concerned with GPL code as identified by running the following script: # | 11461 | concerned with GPL code as identified by running the following script: |
9973 | Script to archive a subset of packages matching specific license(s) # | 11462 | :: |
9974 | Source and license files are copied into sub folders of package folder # | 11463 | |
9975 | Must be run from build folder #!/bin/bash | 11464 | # Script to archive a subset of packages matching specific license(s) |
9976 | src_release_dir="source-release" mkdir -p $src_release_dir for a in | 11465 | # Source and license files are copied into sub folders of package folder |
9977 | tmp/deploy/sources/*; do for d in $a/*; do # Get package name from path | 11466 | # Must be run from build folder |
9978 | p=`basename $d\` p=${p%-*} p=${p%-*} # Only archive GPL packages (update | 11467 | #!/bin/bash |
9979 | \*GPL\* regex for your license check) numfiles=`ls | 11468 | src_release_dir="source-release" |
9980 | tmp/deploy/licenses/$p/*GPL\* 2> /dev/null \| wc -l\` if [ $numfiles -gt | 11469 | mkdir -p $src_release_dir |
9981 | 1 ]; then echo Archiving $p mkdir -p $src_release_dir/$p/source cp $d/\* | 11470 | for a in tmp/deploy/sources/*; do |
9982 | $src_release_dir/$p/source 2> /dev/null mkdir -p | 11471 | for d in $a/*; do |
9983 | $src_release_dir/$p/license cp tmp/deploy/licenses/$p/\* | 11472 | # Get package name from path |
9984 | $src_release_dir/$p/license 2> /dev/null fi done done At this point, you | 11473 | p=`basename $d` |
11474 | p=${p%-*} | ||
11475 | p=${p%-*} | ||
11476 | # Only archive GPL packages (update *GPL* regex for your license check) | ||
11477 | numfiles=`ls tmp/deploy/licenses/$p/*GPL* 2> /dev/null | wc -l` | ||
11478 | if [ $numfiles -gt 1 ]; then | ||
11479 | echo Archiving $p | ||
11480 | mkdir -p $src_release_dir/$p/source | ||
11481 | cp $d/* $src_release_dir/$p/source 2> /dev/null | ||
11482 | mkdir -p $src_release_dir/$p/license | ||
11483 | cp tmp/deploy/licenses/$p/* $src_release_dir/$p/license 2> /dev/null | ||
11484 | fi | ||
11485 | done | ||
11486 | done | ||
11487 | |||
11488 | At this point, you | ||
9985 | could create a tarball from the ``gpl_source_release`` directory and | 11489 | could create a tarball from the ``gpl_source_release`` directory and |
9986 | provide that to the end user. This method would be a step toward | 11490 | provide that to the end user. This method would be a step toward |
9987 | achieving compliance with section 3a of GPLv2 and with section 6 of | 11491 | achieving compliance with section 3a of GPLv2 and with section 6 of |
@@ -9994,8 +11498,14 @@ One requirement that is often overlooked is inclusion of license text. | |||
9994 | This requirement also needs to be dealt with prior to generating the | 11498 | This requirement also needs to be dealt with prior to generating the |
9995 | final image. Some licenses require the license text to accompany the | 11499 | final image. Some licenses require the license text to accompany the |
9996 | binary. You can achieve this by adding the following to your | 11500 | binary. You can achieve this by adding the following to your |
9997 | ``local.conf`` file: COPY_LIC_MANIFEST = "1" COPY_LIC_DIRS = "1" | 11501 | ``local.conf`` file: |
9998 | LICENSE_CREATE_PACKAGE = "1" Adding these statements to the | 11502 | :: |
11503 | |||
11504 | COPY_LIC_MANIFEST = "1" | ||
11505 | COPY_LIC_DIRS = "1" | ||
11506 | LICENSE_CREATE_PACKAGE = "1" | ||
11507 | |||
11508 | Adding these statements to the | ||
9999 | configuration file ensures that the licenses collected during package | 11509 | configuration file ensures that the licenses collected during package |
10000 | generation are included on your image. | 11510 | generation are included on your image. |
10001 | 11511 | ||
@@ -10031,28 +11541,48 @@ By releasing the version of the OpenEmbedded build system and the layers | |||
10031 | used during the build, you will be providing both compilation scripts | 11541 | used during the build, you will be providing both compilation scripts |
10032 | and the source code modifications in one step. | 11542 | and the source code modifications in one step. |
10033 | 11543 | ||
10034 | If the deployment team has a `BSP | 11544 | If the deployment team has a :ref:`overview-manual/overview-manual-concepts:bsp layer` |
10035 | layer <&YOCTO_DOCS_BSP_URL;#bsp-layers>`__ and a distro layer, and those | 11545 | and a distro layer, and those |
10036 | those layers are used to patch, compile, package, or modify (in any way) | 11546 | those layers are used to patch, compile, package, or modify (in any way) |
10037 | any open source software included in your released images, you might be | 11547 | any open source software included in your released images, you might be |
10038 | required to release those layers under section 3 of GPLv2 or section 1 | 11548 | required to release those layers under section 3 of GPLv2 or section 1 |
10039 | of GPLv3. One way of doing that is with a clean checkout of the version | 11549 | of GPLv3. One way of doing that is with a clean checkout of the version |
10040 | of the Yocto Project and layers used during your build. Here is an | 11550 | of the Yocto Project and layers used during your build. Here is an |
10041 | example: # We built using the DISTRO_NAME_NO_CAP branch of the poky repo | 11551 | example: |
10042 | $ git clone -b DISTRO_NAME_NO_CAP git://git.yoctoproject.org/poky $ cd | 11552 | :: |
10043 | poky # We built using the release_branch for our layers $ git clone -b | 11553 | |
10044 | release_branch git://git.mycompany.com/meta-my-bsp-layer $ git clone -b | 11554 | # We built using the dunfell branch of the poky repo |
10045 | release_branch git://git.mycompany.com/meta-my-software-layer # clean up | 11555 | $ git clone -b dunfell git://git.yoctoproject.org/poky |
10046 | the .git repos $ find . -name ".git" -type d -exec rm -rf {} \\; One | 11556 | $ cd poky |
11557 | # We built using the release_branch for our layers | ||
11558 | $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer | ||
11559 | $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer | ||
11560 | # clean up the .git repos | ||
11561 | $ find . -name ".git" -type d -exec rm -rf {} \; | ||
11562 | |||
11563 | One | ||
10047 | thing a development organization might want to consider for end-user | 11564 | thing a development organization might want to consider for end-user |
10048 | convenience is to modify ``meta-poky/conf/bblayers.conf.sample`` to | 11565 | convenience is to modify ``meta-poky/conf/bblayers.conf.sample`` to |
10049 | ensure that when the end user utilizes the released build system to | 11566 | ensure that when the end user utilizes the released build system to |
10050 | build an image, the development organization's layers are included in | 11567 | build an image, the development organization's layers are included in |
10051 | the ``bblayers.conf`` file automatically: # POKY_BBLAYERS_CONF_VERSION | 11568 | the ``bblayers.conf`` file automatically: |
10052 | is increased each time build/conf/bblayers.conf # changes incompatibly | 11569 | :: |
10053 | POKY_BBLAYERS_CONF_VERSION = "2" BBPATH = "${TOPDIR}" BBFILES ?= "" | 11570 | |
10054 | BBLAYERS ?= " \\ ##OEROOT##/meta \\ ##OEROOT##/meta-poky \\ | 11571 | # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf |
10055 | ##OEROOT##/meta-yocto-bsp \\ ##OEROOT##/meta-mylayer \\ " Creating and | 11572 | # changes incompatibly |
11573 | POKY_BBLAYERS_CONF_VERSION = "2" | ||
11574 | |||
11575 | BBPATH = "${TOPDIR}" | ||
11576 | BBFILES ?= "" | ||
11577 | |||
11578 | BBLAYERS ?= " \ | ||
11579 | ##OEROOT##/meta \ | ||
11580 | ##OEROOT##/meta-poky \ | ||
11581 | ##OEROOT##/meta-yocto-bsp \ | ||
11582 | ##OEROOT##/meta-mylayer \ | ||
11583 | " | ||
11584 | |||
11585 | Creating and | ||
10056 | providing an archive of the :term:`Metadata` | 11586 | providing an archive of the :term:`Metadata` |
10057 | layers (recipes, configuration files, and so forth) enables you to meet | 11587 | layers (recipes, configuration files, and so forth) enables you to meet |
10058 | your requirements to include the scripts to control compilation as well | 11588 | your requirements to include the scripts to control compilation as well |
@@ -10070,8 +11600,10 @@ variable. Using this variable also avoids QA errors when you use a | |||
10070 | non-common, non-CLOSED license in a recipe. | 11600 | non-common, non-CLOSED license in a recipe. |
10071 | 11601 | ||
10072 | The following is an example that uses the ``LICENSE.Abilis.txt`` file as | 11602 | The following is an example that uses the ``LICENSE.Abilis.txt`` file as |
10073 | the license from the fetched source: NO_GENERIC_LICENSE[Firmware-Abilis] | 11603 | the license from the fetched source: |
10074 | = "LICENSE.Abilis.txt" | 11604 | :: |
11605 | |||
11606 | NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" | ||
10075 | 11607 | ||
10076 | Using the Error Reporting Tool | 11608 | Using the Error Reporting Tool |
10077 | ============================== | 11609 | ============================== |
@@ -10104,31 +11636,44 @@ inheriting the | |||
10104 | :ref:`report-error <ref-classes-report-error>` | 11636 | :ref:`report-error <ref-classes-report-error>` |
10105 | class by adding the following statement to the end of your | 11637 | class by adding the following statement to the end of your |
10106 | ``local.conf`` file in your | 11638 | ``local.conf`` file in your |
10107 | :term:`Build Directory`. INHERIT += | 11639 | :term:`Build Directory`. |
10108 | "report-error" | 11640 | :: |
11641 | |||
11642 | INHERIT += "report-error" | ||
10109 | 11643 | ||
10110 | By default, the error reporting feature stores information in | 11644 | By default, the error reporting feature stores information in |
10111 | ``${``\ :term:`LOG_DIR`\ ``}/error-report``. | 11645 | ``${``\ :term:`LOG_DIR`\ ``}/error-report``. |
10112 | However, you can specify a directory to use by adding the following to | 11646 | However, you can specify a directory to use by adding the following to |
10113 | your ``local.conf`` file: ERR_REPORT_DIR = "path" Enabling error | 11647 | your ``local.conf`` file: |
11648 | :: | ||
11649 | |||
11650 | ERR_REPORT_DIR = "path" | ||
11651 | |||
11652 | Enabling error | ||
10114 | reporting causes the build process to collect the errors and store them | 11653 | reporting causes the build process to collect the errors and store them |
10115 | in a file as previously described. When the build system encounters an | 11654 | in a file as previously described. When the build system encounters an |
10116 | error, it includes a command as part of the console output. You can run | 11655 | error, it includes a command as part of the console output. You can run |
10117 | the command to send the error file to the server. For example, the | 11656 | the command to send the error file to the server. For example, the |
10118 | following command sends the errors to an upstream server: $ | 11657 | following command sends the errors to an upstream server: |
10119 | send-error-report | 11658 | :: |
10120 | /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt | 11659 | |
11660 | $ send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt | ||
11661 | |||
10121 | In the previous example, the errors are sent to a public database | 11662 | In the previous example, the errors are sent to a public database |
10122 | available at http://errors.yoctoproject.org, which is used by the | 11663 | available at http://errors.yoctoproject.org, which is used by the |
10123 | entire community. If you specify a particular server, you can send the | 11664 | entire community. If you specify a particular server, you can send the |
10124 | errors to a different database. Use the following command for more | 11665 | errors to a different database. Use the following command for more |
10125 | information on available options: $ send-error-report --help | 11666 | information on available options: |
11667 | :: | ||
11668 | |||
11669 | $ send-error-report --help | ||
10126 | 11670 | ||
10127 | When sending the error file, you are prompted to review the data being | 11671 | When sending the error file, you are prompted to review the data being |
10128 | sent as well as to provide a name and optional email address. Once you | 11672 | sent as well as to provide a name and optional email address. Once you |
10129 | satisfy these prompts, the command returns a link from the server that | 11673 | satisfy these prompts, the command returns a link from the server that |
10130 | corresponds to your entry in the database. For example, here is a | 11674 | corresponds to your entry in the database. For example, here is a |
10131 | typical link: http://errors.yoctoproject.org/Errors/Details/9522/ | 11675 | typical link: http://errors.yoctoproject.org/Errors/Details/9522/ |
11676 | |||
10132 | Following the link takes you to a web interface where you can browse, | 11677 | Following the link takes you to a web interface where you can browse, |
10133 | query the errors, and view statistics. | 11678 | query the errors, and view statistics. |
10134 | 11679 | ||
@@ -10137,8 +11682,10 @@ Disabling the Tool | |||
10137 | 11682 | ||
10138 | To disable the error reporting feature, simply remove or comment out the | 11683 | To disable the error reporting feature, simply remove or comment out the |
10139 | following statement from the end of your ``local.conf`` file in your | 11684 | following statement from the end of your ``local.conf`` file in your |
10140 | :term:`Build Directory`. INHERIT += | 11685 | :term:`Build Directory`. |
10141 | "report-error" | 11686 | :: |
11687 | |||
11688 | INHERIT += "report-error" | ||
10142 | 11689 | ||
10143 | Setting Up Your Own Error Reporting Server | 11690 | Setting Up Your Own Error Reporting Server |
10144 | ------------------------------------------ | 11691 | ------------------------------------------ |
@@ -10194,16 +11741,18 @@ included (installed) in the image. | |||
10194 | 11741 | ||
10195 | .. _enable-building: | 11742 | .. _enable-building: |
10196 | 11743 | ||
10197 | Building | 11744 | Building Wayland |
10198 | ~~~~~~~~ | 11745 | ~~~~~~~~~~~~~~~~ |
10199 | 11746 | ||
10200 | To cause Mesa to build the ``wayland-egl`` platform and Weston to build | 11747 | To cause Mesa to build the ``wayland-egl`` platform and Weston to build |
10201 | Wayland with Kernel Mode Setting | 11748 | Wayland with Kernel Mode Setting |
10202 | (`KMS <https://wiki.archlinux.org/index.php/Kernel_Mode_Setting>`__) | 11749 | (`KMS <https://wiki.archlinux.org/index.php/Kernel_Mode_Setting>`__) |
10203 | support, include the "wayland" flag in the | 11750 | support, include the "wayland" flag in the |
10204 | :term:`DISTRO_FEATURES` | 11751 | :term:`DISTRO_FEATURES` |
10205 | statement in your ``local.conf`` file: DISTRO_FEATURES_append = " | 11752 | statement in your ``local.conf`` file: |
10206 | wayland" | 11753 | :: |
11754 | |||
11755 | DISTRO_FEATURES_append = " wayland" | ||
10207 | 11756 | ||
10208 | .. note:: | 11757 | .. note:: |
10209 | 11758 | ||
@@ -10212,14 +11761,16 @@ wayland" | |||
10212 | 11761 | ||
10213 | .. _enable-installation-in-an-image: | 11762 | .. _enable-installation-in-an-image: |
10214 | 11763 | ||
10215 | Installing | 11764 | Installing Wayland and Weston |
10216 | ~~~~~~~~~~ | 11765 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
10217 | 11766 | ||
10218 | To install the Wayland feature into an image, you must include the | 11767 | To install the Wayland feature into an image, you must include the |
10219 | following | 11768 | following |
10220 | :term:`CORE_IMAGE_EXTRA_INSTALL` | 11769 | :term:`CORE_IMAGE_EXTRA_INSTALL` |
10221 | statement in your ``local.conf`` file: CORE_IMAGE_EXTRA_INSTALL += | 11770 | statement in your ``local.conf`` file: |
10222 | "wayland weston" | 11771 | :: |
11772 | |||
11773 | CORE_IMAGE_EXTRA_INSTALL += "wayland weston" | ||
10223 | 11774 | ||
10224 | Running Weston | 11775 | Running Weston |
10225 | -------------- | 11776 | -------------- |
@@ -10232,8 +11783,14 @@ Alternatively, you can run Weston through the command-line interpretor | |||
10232 | (CLI), which is better suited for development work. To run Weston under | 11783 | (CLI), which is better suited for development work. To run Weston under |
10233 | the CLI, you need to do the following after your image is built: | 11784 | the CLI, you need to do the following after your image is built: |
10234 | 11785 | ||
10235 | 1. Run these commands to export ``XDG_RUNTIME_DIR``: mkdir -p | 11786 | 1. Run these commands to export ``XDG_RUNTIME_DIR``: |
10236 | /tmp/$USER-weston chmod 0700 /tmp/$USER-weston export | 11787 | :: |
10237 | XDG_RUNTIME_DIR=/tmp/$USER-weston | 11788 | |
11789 | mkdir -p /tmp/$USER-weston | ||
11790 | chmod 0700 /tmp/$USER-weston | ||
11791 | export XDG_RUNTIME_DIR=/tmp/$USER-weston | ||
11792 | |||
11793 | 2. Launch Weston in the shell: | ||
11794 | :: | ||
10238 | 11795 | ||
10239 | 2. Launch Weston in the shell: weston | 11796 | weston |
diff --git a/documentation/dev-manual/dev-manual-intro.rst b/documentation/dev-manual/dev-manual-intro.rst index 1dc552c750..3225c6ca45 100644 --- a/documentation/dev-manual/dev-manual-intro.rst +++ b/documentation/dev-manual/dev-manual-intro.rst | |||
@@ -32,16 +32,14 @@ This manual provides the following: | |||
32 | 32 | ||
33 | This manual does not provide the following: | 33 | This manual does not provide the following: |
34 | 34 | ||
35 | - Redundant Step-by-step Instructions: For example, the `Yocto Project | 35 | - Redundant Step-by-step Instructions: For example, the |
36 | Application Development and the Extensible Software Development Kit | 36 | :doc:`../sdk-manual/sdk-manual` manual contains detailed |
37 | (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual contains detailed | ||
38 | instructions on how to install an SDK, which is used to develop | 37 | instructions on how to install an SDK, which is used to develop |
39 | applications for target hardware. | 38 | applications for target hardware. |
40 | 39 | ||
41 | - Reference or Conceptual Material: This type of material resides in an | 40 | - Reference or Conceptual Material: This type of material resides in an |
42 | appropriate reference manual. For example, system variables are | 41 | appropriate reference manual. For example, system variables are |
43 | documented in the `Yocto Project Reference | 42 | documented in the :doc`../ref-manual/ref-manual`. |
44 | Manual <&YOCTO_DOCS_REF_URL;>`__. | ||
45 | 43 | ||
46 | - Detailed Public Information Not Specific to the Yocto Project: For | 44 | - Detailed Public Information Not Specific to the Yocto Project: For |
47 | example, exhaustive information on how to use the Source Control | 45 | example, exhaustive information on how to use the Source Control |
@@ -56,9 +54,8 @@ supplemental information is recommended for full comprehension. For | |||
56 | introductory information on the Yocto Project, see the | 54 | introductory information on the Yocto Project, see the |
57 | :yocto_home:`Yocto Project Website <>`. If you want to build an image with no | 55 | :yocto_home:`Yocto Project Website <>`. If you want to build an image with no |
58 | knowledge of Yocto Project as a way of quickly testing it out, see the | 56 | knowledge of Yocto Project as a way of quickly testing it out, see the |
59 | `Yocto Project Quick Build <&YOCTO_DOCS_BRIEF_URL;>`__ document. | 57 | :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. |
60 | 58 | ||
61 | For a comprehensive list of links and other documentation, see the | 59 | For a comprehensive list of links and other documentation, see the |
62 | "`Links and Related | 60 | ":ref:`ref-manual/resources:links and related documentation`" |
63 | Documentation <&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation>`__" | ||
64 | section in the Yocto Project Reference Manual. | 61 | section in the Yocto Project Reference Manual. |
diff --git a/documentation/dev-manual/dev-manual-qemu.rst b/documentation/dev-manual/dev-manual-qemu.rst index d695b90202..82c214b9bb 100644 --- a/documentation/dev-manual/dev-manual-qemu.rst +++ b/documentation/dev-manual/dev-manual-qemu.rst | |||
@@ -50,8 +50,7 @@ available. Follow these general steps to run QEMU: | |||
50 | 50 | ||
51 | 1. *Install QEMU:* QEMU is made available with the Yocto Project a | 51 | 1. *Install QEMU:* QEMU is made available with the Yocto Project a |
52 | number of ways. One method is to install a Software Development Kit | 52 | number of ways. One method is to install a Software Development Kit |
53 | (SDK). See "`The QEMU | 53 | (SDK). See ":ref:`sdk-manual/sdk-intro:the qemu emulator`" section in the |
54 | Emulator <&YOCTO_DOCS_SDK_URL;#the-qemu-emulator>`__" section in the | ||
55 | Yocto Project Application Development and the Extensible Software | 54 | Yocto Project Application Development and the Extensible Software |
56 | Development Kit (eSDK) manual for information on how to install QEMU. | 55 | Development Kit (eSDK) manual for information on how to install QEMU. |
57 | 56 | ||
@@ -60,14 +59,18 @@ available. Follow these general steps to run QEMU: | |||
60 | 59 | ||
61 | - If you cloned the ``poky`` repository or you downloaded and | 60 | - If you cloned the ``poky`` repository or you downloaded and |
62 | unpacked a Yocto Project release tarball, you can source the build | 61 | unpacked a Yocto Project release tarball, you can source the build |
63 | environment script (i.e. | 62 | environment script (i.e. :ref:`structure-core-script`): |
64 | ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__): $ cd | 63 | :: |
65 | ~/poky $ source oe-init-build-env | 64 | |
65 | $ cd ~/poky | ||
66 | $ source oe-init-build-env | ||
66 | 67 | ||
67 | - If you installed a cross-toolchain, you can run the script that | 68 | - If you installed a cross-toolchain, you can run the script that |
68 | initializes the toolchain. For example, the following commands run | 69 | initializes the toolchain. For example, the following commands run |
69 | the initialization script from the default ``poky_sdk`` directory: | 70 | the initialization script from the default ``poky_sdk`` directory: |
70 | . ~/poky_sdk/environment-setup-core2-64-poky-linux | 71 | :: |
72 | |||
73 | . ~/poky_sdk/environment-setup-core2-64-poky-linux | ||
71 | 74 | ||
72 | 3. *Ensure the Artifacts are in Place:* You need to be sure you have a | 75 | 3. *Ensure the Artifacts are in Place:* You need to be sure you have a |
73 | pre-built kernel that will boot in QEMU. You also need the target | 76 | pre-built kernel that will boot in QEMU. You also need the target |
@@ -78,18 +81,21 @@ available. Follow these general steps to run QEMU: | |||
78 | your :term:`Build Directory`. | 81 | your :term:`Build Directory`. |
79 | 82 | ||
80 | - If you have not built an image, you can go to the | 83 | - If you have not built an image, you can go to the |
81 | `machines/qemu <&YOCTO_MACHINES_DL_URL;>`__ area and download a | 84 | :yocto_dl:`machines/qemu <releases/yocto/yocto-3.1.2/machines/qemu/>` area and download a |
82 | pre-built image that matches your architecture and can be run on | 85 | pre-built image that matches your architecture and can be run on |
83 | QEMU. | 86 | QEMU. |
84 | 87 | ||
85 | See the "`Extracting the Root | 88 | See the ":ref:`sdk-manual/sdk-appendix-obtain:extracting the root filesystem`" |
86 | Filesystem <&YOCTO_DOCS_SDK_URL;#sdk-extracting-the-root-filesystem>`__" | ||
87 | section in the Yocto Project Application Development and the | 89 | section in the Yocto Project Application Development and the |
88 | Extensible Software Development Kit (eSDK) manual for information on | 90 | Extensible Software Development Kit (eSDK) manual for information on |
89 | how to extract a root filesystem. | 91 | how to extract a root filesystem. |
90 | 92 | ||
91 | 4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows: $ | 93 | 4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows: |
92 | runqemu [option ] [...] Based on what you provide on the command | 94 | :: |
95 | |||
96 | $ runqemu [option ] [...] | ||
97 | |||
98 | Based on what you provide on the command | ||
93 | line, ``runqemu`` does a good job of figuring out what you are trying | 99 | line, ``runqemu`` does a good job of figuring out what you are trying |
94 | to do. For example, by default, QEMU looks for the most recently | 100 | to do. For example, by default, QEMU looks for the most recently |
95 | built image according to the timestamp when it needs to look for an | 101 | built image according to the timestamp when it needs to look for an |
@@ -113,30 +119,40 @@ available. Follow these general steps to run QEMU: | |||
113 | and uses the most recently built image according to the | 119 | and uses the most recently built image according to the |
114 | timestamp. | 120 | timestamp. |
115 | 121 | ||
116 | $ runqemu qemux86-64 | 122 | :: |
123 | |||
124 | $ runqemu qemux86-64 | ||
117 | 125 | ||
118 | - This example produces the exact same results as the previous | 126 | - This example produces the exact same results as the previous |
119 | example. This command, however, specifically provides the image | 127 | example. This command, however, specifically provides the image |
120 | and root filesystem type. $ runqemu qemux86-64 core-image-minimal | 128 | and root filesystem type. |
121 | ext4 | 129 | :: |
130 | |||
131 | $ runqemu qemux86-64 core-image-minimal ext4 | ||
122 | 132 | ||
123 | - This example specifies to boot an initial RAM disk image and to | 133 | - This example specifies to boot an initial RAM disk image and to |
124 | enable audio in QEMU. For this case, ``runqemu`` set the internal | 134 | enable audio in QEMU. For this case, ``runqemu`` set the internal |
125 | variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled, | 135 | variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled, |
126 | an appropriate driver must be installed (see the previous | 136 | an appropriate driver must be installed (see the previous |
127 | description for the ``audio`` option for more information). $ | 137 | description for the ``audio`` option for more information). |
128 | runqemu qemux86-64 ramfs audio | 138 | :: |
139 | |||
140 | $ runqemu qemux86-64 ramfs audio | ||
129 | 141 | ||
130 | - This example does not provide enough information for QEMU to | 142 | - This example does not provide enough information for QEMU to |
131 | launch. While the command does provide a root filesystem type, it | 143 | launch. While the command does provide a root filesystem type, it |
132 | must also minimally provide a MACHINE, KERNEL, or VM option. $ | 144 | must also minimally provide a MACHINE, KERNEL, or VM option. |
133 | runqemu ext4 | 145 | :: |
146 | |||
147 | $ runqemu ext4 | ||
134 | 148 | ||
135 | - This example specifies to boot a virtual machine image | 149 | - This example specifies to boot a virtual machine image |
136 | (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu`` | 150 | (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu`` |
137 | determines the QEMU architecture (MACHINE) to be "qemux86-64" and | 151 | determines the QEMU architecture (MACHINE) to be "qemux86-64" and |
138 | the root filesystem type to be "vmdk". $ runqemu | 152 | the root filesystem type to be "vmdk". |
139 | /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk | 153 | :: |
154 | |||
155 | $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk | ||
140 | 156 | ||
141 | Switching Between Consoles | 157 | Switching Between Consoles |
142 | ========================== | 158 | ========================== |
@@ -191,15 +207,19 @@ using an NFS server. | |||
191 | The ``runqemu-extract-sdk`` takes a root filesystem tarball and | 207 | The ``runqemu-extract-sdk`` takes a root filesystem tarball and |
192 | extracts it into a location that you specify. Here is an example that | 208 | extracts it into a location that you specify. Here is an example that |
193 | takes a file system and extracts it to a directory named | 209 | takes a file system and extracts it to a directory named |
194 | ``test-nfs``: runqemu-extract-sdk | 210 | ``test-nfs``: |
195 | ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 | 211 | :: |
196 | test-nfs | 212 | |
213 | runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs | ||
197 | 214 | ||
198 | 2. *Start QEMU:* Once you have extracted the file system, you can run | 215 | 2. *Start QEMU:* Once you have extracted the file system, you can run |
199 | ``runqemu`` normally with the additional location of the file system. | 216 | ``runqemu`` normally with the additional location of the file system. |
200 | You can then also make changes to the files within ``./test-nfs`` and | 217 | You can then also make changes to the files within ``./test-nfs`` and |
201 | see those changes appear in the image in real time. Here is an | 218 | see those changes appear in the image in real time. Here is an |
202 | example using the ``qemux86`` image: runqemu qemux86-64 ./test-nfs | 219 | example using the ``qemux86`` image: |
220 | :: | ||
221 | |||
222 | runqemu qemux86-64 ./test-nfs | ||
203 | 223 | ||
204 | .. note:: | 224 | .. note:: |
205 | 225 | ||
@@ -297,38 +317,57 @@ present, the toolchain is also automatically used. | |||
297 | QEMU Command-Line Syntax | 317 | QEMU Command-Line Syntax |
298 | ======================== | 318 | ======================== |
299 | 319 | ||
300 | The basic ``runqemu`` command syntax is as follows: $ runqemu [option ] | 320 | The basic ``runqemu`` command syntax is as follows: |
301 | [...] Based on what you provide on the command line, ``runqemu`` does a | 321 | :: |
322 | |||
323 | $ runqemu [option ] [...] | ||
324 | |||
325 | Based on what you provide on the command line, ``runqemu`` does a | ||
302 | good job of figuring out what you are trying to do. For example, by | 326 | good job of figuring out what you are trying to do. For example, by |
303 | default, QEMU looks for the most recently built image according to the | 327 | default, QEMU looks for the most recently built image according to the |
304 | timestamp when it needs to look for an image. Minimally, through the use | 328 | timestamp when it needs to look for an image. Minimally, through the use |
305 | of options, you must provide either a machine name, a virtual machine | 329 | of options, you must provide either a machine name, a virtual machine |
306 | image (``*wic.vmdk``), or a kernel image (``*.bin``). | 330 | image (``*wic.vmdk``), or a kernel image (``*.bin``). |
307 | 331 | ||
308 | Following is the command-line help output for the ``runqemu`` command: $ | 332 | Following is the command-line help output for the ``runqemu`` command: |
309 | runqemu --help Usage: you can run this script with any valid combination | 333 | :: |
310 | of the following environment variables (in any order): KERNEL - the | 334 | |
311 | kernel image file to use ROOTFS - the rootfs image file or nfsroot | 335 | $ runqemu --help |
312 | directory to use MACHINE - the machine name (optional, autodetected from | 336 | |
313 | KERNEL filename if unspecified) Simplified QEMU command-line options can | 337 | Usage: you can run this script with any valid combination |
314 | be passed with: nographic - disable video console serial - enable a | 338 | of the following environment variables (in any order): |
315 | serial console on /dev/ttyS0 slirp - enable user networking, no root | 339 | KERNEL - the kernel image file to use |
316 | privileges is required kvm - enable KVM when running x86/x86_64 | 340 | ROOTFS - the rootfs image file or nfsroot directory to use |
317 | (VT-capable CPU required) kvm-vhost - enable KVM with vhost when running | 341 | MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified) |
318 | x86/x86_64 (VT-capable CPU required) publicvnc - enable a VNC server | 342 | Simplified QEMU command-line options can be passed with: |
319 | open to all hosts audio - enable audio [*/]ovmf\* - OVMF firmware file | 343 | nographic - disable video console |
320 | or base name for booting with UEFI tcpserial=<port> - specify tcp serial | 344 | serial - enable a serial console on /dev/ttyS0 |
321 | port number biosdir=<dir> - specify custom bios dir | 345 | slirp - enable user networking, no root privileges is required |
322 | biosfilename=<filename> - specify bios filename qemuparams=<xyz> - | 346 | kvm - enable KVM when running x86/x86_64 (VT-capable CPU required) |
323 | specify custom parameters to QEMU bootparams=<xyz> - specify custom | 347 | kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required) |
324 | kernel parameters during boot help, -h, --help: print this text | 348 | publicvnc - enable a VNC server open to all hosts |
325 | Examples: runqemu runqemu qemuarm runqemu tmp/deploy/images/qemuarm | 349 | audio - enable audio |
326 | runqemu tmp/deploy/images/qemux86/<qemuboot.conf> runqemu qemux86-64 | 350 | [*/]ovmf* - OVMF firmware file or base name for booting with UEFI |
327 | core-image-sato ext4 runqemu qemux86-64 wic-image-minimal wic runqemu | 351 | tcpserial=<port> - specify tcp serial port number |
328 | path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial runqemu qemux86 | 352 | biosdir=<dir> - specify custom bios dir |
329 | iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz... runqemu qemux86 | 353 | biosfilename=<filename> - specify bios filename |
330 | qemuparams="-m 256" runqemu qemux86 bootparams="psplash=false" runqemu | 354 | qemuparams=<xyz> - specify custom parameters to QEMU |
331 | path/to/<image>-<machine>.wic runqemu path/to/<image>-<machine>.wic.vmdk | 355 | bootparams=<xyz> - specify custom kernel parameters during boot |
356 | help, -h, --help: print this text | ||
357 | |||
358 | Examples: | ||
359 | runqemu | ||
360 | runqemu qemuarm | ||
361 | runqemu tmp/deploy/images/qemuarm | ||
362 | runqemu tmp/deploy/images/qemux86/<qemuboot.conf> | ||
363 | runqemu qemux86-64 core-image-sato ext4 | ||
364 | runqemu qemux86-64 wic-image-minimal wic | ||
365 | runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial | ||
366 | runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz... | ||
367 | runqemu qemux86 qemuparams="-m 256" | ||
368 | runqemu qemux86 bootparams="psplash=false" | ||
369 | runqemu path/to/<image>-<machine>.wic | ||
370 | runqemu path/to/<image>-<machine>.wic.vmdk | ||
332 | 371 | ||
333 | .. _qemu-dev-runqemu-command-line-options: | 372 | .. _qemu-dev-runqemu-command-line-options: |
334 | 373 | ||
diff --git a/documentation/dev-manual/dev-manual-start.rst b/documentation/dev-manual/dev-manual-start.rst index b935f7b63e..536d5a9cd9 100644 --- a/documentation/dev-manual/dev-manual-start.rst +++ b/documentation/dev-manual/dev-manual-start.rst | |||
@@ -5,9 +5,9 @@ Setting Up to Use the Yocto Project | |||
5 | *********************************** | 5 | *********************************** |
6 | 6 | ||
7 | This chapter provides guidance on how to prepare to use the Yocto | 7 | This chapter provides guidance on how to prepare to use the Yocto |
8 | Project. You can learn about creating a team environment that develops | 8 | Project. You can learn about creating a team environment to develop |
9 | using the Yocto Project, how to set up a `build | 9 | using the Yocto Project, how to set up a :ref:`build |
10 | host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__, how to locate | 10 | host <dev-manual/dev-manual-start:preparing the build host>`, how to locate |
11 | Yocto Project source repositories, and how to create local Git | 11 | Yocto Project source repositories, and how to create local Git |
12 | repositories. | 12 | repositories. |
13 | 13 | ||
@@ -79,8 +79,9 @@ particular working environment and set of practices. | |||
79 | configuration files, classes, and so forth) and any software you are | 79 | configuration files, classes, and so forth) and any software you are |
80 | developing under the control of an SCM system that is compatible | 80 | developing under the control of an SCM system that is compatible |
81 | with the OpenEmbedded build system is advisable. Of all of the SCMs | 81 | with the OpenEmbedded build system is advisable. Of all of the SCMs |
82 | supported by BitBake, the Yocto Project team strongly recommends | 82 | supported by BitBake, the Yocto Project team strongly recommends using |
83 | using `Git <&YOCTO_DOCS_OM_URL;#git>`__. Git is a distributed system | 83 | :ref:`overview-manual/overview-manual-development-environment:git`. |
84 | Git is a distributed system | ||
84 | that is easy to back up, allows you to work remotely, and then | 85 | that is easy to back up, allows you to work remotely, and then |
85 | connects back to the infrastructure. | 86 | connects back to the infrastructure. |
86 | 87 | ||
@@ -171,8 +172,8 @@ particular working environment and set of practices. | |||
171 | 172 | ||
172 | - Highlights when commits break the build. | 173 | - Highlights when commits break the build. |
173 | 174 | ||
174 | - Populates an `sstate | 175 | - Populates an :ref:`sstate |
175 | cache <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ from which | 176 | cache <overview-manual/overview-manual-concepts:shared state cache>` from which |
176 | developers can pull rather than requiring local builds. | 177 | developers can pull rather than requiring local builds. |
177 | 178 | ||
178 | - Allows commit hook triggers, which trigger builds when commits | 179 | - Allows commit hook triggers, which trigger builds when commits |
@@ -226,20 +227,17 @@ particular working environment and set of practices. | |||
226 | some best practices exist within the Yocto Project development | 227 | some best practices exist within the Yocto Project development |
227 | environment. Consider the following: | 228 | environment. Consider the following: |
228 | 229 | ||
229 | - Use `Git <&YOCTO_DOCS_OM_URL;#git>`__ as the source control | 230 | - Use :ref:`overview-manual/overview-manual-development-environment:git` as the source control |
230 | system. | 231 | system. |
231 | 232 | ||
232 | - Maintain your Metadata in layers that make sense for your | 233 | - Maintain your Metadata in layers that make sense for your |
233 | situation. See the "`The Yocto Project Layer | 234 | situation. See the ":ref:`overview-manual/overview-manual-yp-intro:the yocto project layer model`" |
234 | Model <&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model>`__" | ||
235 | section in the Yocto Project Overview and Concepts Manual and the | 235 | section in the Yocto Project Overview and Concepts Manual and the |
236 | "`Understanding and Creating | 236 | ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" |
237 | Layers <#understanding-and-creating-layers>`__" section for more | 237 | section for more information on layers. |
238 | information on layers. | ||
239 | 238 | ||
240 | - Separate the project's Metadata and code by using separate Git | 239 | - Separate the project's Metadata and code by using separate Git |
241 | repositories. See the "`Yocto Project Source | 240 | repositories. See the ":ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`" |
242 | Repositories <&YOCTO_DOCS_OM_URL;#yocto-project-repositories>`__" | ||
243 | section in the Yocto Project Overview and Concepts Manual for | 241 | section in the Yocto Project Overview and Concepts Manual for |
244 | information on these repositories. See the "`Locating Yocto | 242 | information on these repositories. See the "`Locating Yocto |
245 | Project Source Files <#locating-yocto-project-source-files>`__" | 243 | Project Source Files <#locating-yocto-project-source-files>`__" |
@@ -258,15 +256,16 @@ particular working environment and set of practices. | |||
258 | - The Yocto Project community encourages you to send patches to the | 256 | - The Yocto Project community encourages you to send patches to the |
259 | project to fix bugs or add features. If you do submit patches, | 257 | project to fix bugs or add features. If you do submit patches, |
260 | follow the project commit guidelines for writing good commit | 258 | follow the project commit guidelines for writing good commit |
261 | messages. See the "`Submitting a Change to the Yocto | 259 | messages. See the |
262 | Project <#how-to-submit-a-change>`__" section. | 260 | ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`" |
261 | section. | ||
263 | 262 | ||
264 | - Send changes to the core sooner than later as others are likely | 263 | - Send changes to the core sooner than later as others are likely |
265 | to run into the same issues. For some guidance on mailing lists | 264 | to run into the same issues. For some guidance on mailing lists |
266 | to use, see the list in the "`Submitting a Change to the Yocto | 265 | to use, see the list in the |
267 | Project <#how-to-submit-a-change>`__" section. For a description | 266 | ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`" |
268 | of the available mailing lists, see the "`Mailing | 267 | section. For a description |
269 | Lists <&YOCTO_DOCS_REF_URL;#resources-mailinglist>`__" section in | 268 | of the available mailing lists, see the ":ref:`resources-mailinglist`" section in |
270 | the Yocto Project Reference Manual. | 269 | the Yocto Project Reference Manual. |
271 | 270 | ||
272 | .. _dev-preparing-the-build-host: | 271 | .. _dev-preparing-the-build-host: |
@@ -275,7 +274,7 @@ Preparing the Build Host | |||
275 | ======================== | 274 | ======================== |
276 | 275 | ||
277 | This section provides procedures to set up a system to be used as your | 276 | This section provides procedures to set up a system to be used as your |
278 | `build host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ for | 277 | :term:`Build Host` for |
279 | development using the Yocto Project. Your build host can be a native | 278 | development using the Yocto Project. Your build host can be a native |
280 | Linux machine (recommended), it can be a machine (Linux, Mac, or | 279 | Linux machine (recommended), it can be a machine (Linux, Mac, or |
281 | Windows) that uses `CROPS <https://github.com/crops/poky-container>`__, | 280 | Windows) that uses `CROPS <https://github.com/crops/poky-container>`__, |
@@ -297,15 +296,11 @@ are necessary depending on what you want to accomplish. See the | |||
297 | following references for information on how to prepare for Board Support | 296 | following references for information on how to prepare for Board Support |
298 | Package (BSP) development and kernel development: | 297 | Package (BSP) development and kernel development: |
299 | 298 | ||
300 | - *BSP Development:* See the "`Preparing Your Build Host to Work With | 299 | - *BSP Development:* See the ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`" |
301 | BSP | ||
302 | Layers <&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers>`__" | ||
303 | section in the Yocto Project Board Support Package (BSP) Developer's | 300 | section in the Yocto Project Board Support Package (BSP) Developer's |
304 | Guide. | 301 | Guide. |
305 | 302 | ||
306 | - *Kernel Development:* See the "`Preparing the Build Host to Work on | 303 | - *Kernel Development:* See the ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`" |
307 | the | ||
308 | Kernel <&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel>`__" | ||
309 | section in the Yocto Project Linux Kernel Development Manual. | 304 | section in the Yocto Project Linux Kernel Development Manual. |
310 | 305 | ||
311 | Setting Up a Native Linux Host | 306 | Setting Up a Native Linux Host |
@@ -319,8 +314,8 @@ Project Build Host: | |||
319 | a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS | 314 | a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS |
320 | as these releases are frequently tested against the Yocto Project and | 315 | as these releases are frequently tested against the Yocto Project and |
321 | officially supported. For a list of the distributions under | 316 | officially supported. For a list of the distributions under |
322 | validation and their status, see the "`Supported Linux | 317 | validation and their status, see the ":ref:`Supported Linux |
323 | Distributions <&YOCTO_DOCS_REF_URL;#detailed-supported-distros>`__" | 318 | Distributions <detailed-supported-distros>`" |
324 | section in the Yocto Project Reference Manual and the wiki page at | 319 | section in the Yocto Project Reference Manual and the wiki page at |
325 | :yocto_wiki:`Distribution Support </wiki/Distribution_Support>`. | 320 | :yocto_wiki:`Distribution Support </wiki/Distribution_Support>`. |
326 | 321 | ||
@@ -341,9 +336,8 @@ Project Build Host: | |||
341 | 336 | ||
342 | If your build host does not meet any of these three listed version | 337 | If your build host does not meet any of these three listed version |
343 | requirements, you can take steps to prepare the system so that you | 338 | requirements, you can take steps to prepare the system so that you |
344 | can still use the Yocto Project. See the "`Required Git, tar, Python | 339 | can still use the Yocto Project. See the |
345 | and gcc | 340 | ":ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`" |
346 | Versions <&YOCTO_DOCS_REF_URL;#required-git-tar-python-and-gcc-versions>`__" | ||
347 | section in the Yocto Project Reference Manual for information. | 341 | section in the Yocto Project Reference Manual for information. |
348 | 342 | ||
349 | 4. *Install Development Host Packages:* Required development host | 343 | 4. *Install Development Host Packages:* Required development host |
@@ -351,23 +345,19 @@ Project Build Host: | |||
351 | with the Yocto Project. Collectively, the number of required packages | 345 | with the Yocto Project. Collectively, the number of required packages |
352 | is large if you want to be able to cover all cases. | 346 | is large if you want to be able to cover all cases. |
353 | 347 | ||
354 | For lists of required packages for all scenarios, see the "`Required | 348 | For lists of required packages for all scenarios, see the |
355 | Packages for the Build | 349 | ":ref:`ref-manual/ref-system-requirements:required packages for the build host`" |
356 | Host <&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host>`__" | ||
357 | section in the Yocto Project Reference Manual. | 350 | section in the Yocto Project Reference Manual. |
358 | 351 | ||
359 | Once you have completed the previous steps, you are ready to continue | 352 | Once you have completed the previous steps, you are ready to continue |
360 | using a given development path on your native Linux machine. If you are | 353 | using a given development path on your native Linux machine. If you are |
361 | going to use BitBake, see the "`Cloning the ``poky`` | 354 | going to use BitBake, see the |
362 | Repository <#cloning-the-poky-repository>`__" section. If you are going | 355 | ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" |
363 | to use the Extensible SDK, see the "`Using the Extensible | 356 | section. If you are going |
364 | SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" Chapter in the Yocto | 357 | to use the Extensible SDK, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto |
365 | Project Application Development and the Extensible Software Development | 358 | Project Application Development and the Extensible Software Development |
366 | Kit (eSDK) manual. If you want to work on the kernel, see the `Yocto | 359 | Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`../kernel-dev/kernel-dev`. If you are going to use |
367 | Project Linux Kernel Development | 360 | Toaster, see the ":doc:`../toaster-manual/toaster-manual-setup-and-use`" |
368 | Manual <&YOCTO_DOCS_KERNEL_DEV_URL;>`__. If you are going to use | ||
369 | Toaster, see the "`Setting Up and Using | ||
370 | Toaster <&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use>`__" | ||
371 | section in the Toaster User Manual. | 361 | section in the Toaster User Manual. |
372 | 362 | ||
373 | .. _setting-up-to-use-crops: | 363 | .. _setting-up-to-use-crops: |
@@ -465,12 +455,11 @@ Once you have a container set up, everything is in place to develop just | |||
465 | as if you were running on a native Linux machine. If you are going to | 455 | as if you were running on a native Linux machine. If you are going to |
466 | use the Poky container, see the "`Cloning the ``poky`` | 456 | use the Poky container, see the "`Cloning the ``poky`` |
467 | Repository <#cloning-the-poky-repository>`__" section. If you are going | 457 | Repository <#cloning-the-poky-repository>`__" section. If you are going |
468 | to use the Extensible SDK container, see the "`Using the Extensible | 458 | to use the Extensible SDK container, see the |
469 | SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" Chapter in the Yocto | 459 | ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto |
470 | Project Application Development and the Extensible Software Development | 460 | Project Application Development and the Extensible Software Development |
471 | Kit (eSDK) manual. If you are going to use the Toaster container, see | 461 | Kit (eSDK) manual. If you are going to use the Toaster container, see |
472 | the "`Setting Up and Using | 462 | the ":doc:`../toaster-manual/toaster-manual-setup-and-use`" |
473 | Toaster <&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use>`__" | ||
474 | section in the Toaster User Manual. | 463 | section in the Toaster User Manual. |
475 | 464 | ||
476 | .. _setting-up-to-use-wsl: | 465 | .. _setting-up-to-use-wsl: |
@@ -490,8 +479,14 @@ your Yocto Project build host: | |||
490 | 1. *Make sure your Windows 10 machine is capable of running WSLv2:* | 479 | 1. *Make sure your Windows 10 machine is capable of running WSLv2:* |
491 | WSLv2 is only available for Windows 10 builds > 18917. To check which | 480 | WSLv2 is only available for Windows 10 builds > 18917. To check which |
492 | build version you are running, you may open a command prompt on | 481 | build version you are running, you may open a command prompt on |
493 | Windows and execute the command "ver". C:\Users\myuser> ver Microsoft | 482 | Windows and execute the command "ver". |
494 | Windows [Version 10.0.19041.153] If your build is capable of running | 483 | :: |
484 | |||
485 | C:\Users\myuser> ver | ||
486 | |||
487 | Microsoft Windows [Version 10.0.19041.153] | ||
488 | |||
489 | If your build is capable of running | ||
495 | WSLv2 you may continue, for more information on this subject or | 490 | WSLv2 you may continue, for more information on this subject or |
496 | instructions on how to upgrade to WSLv2 visit `Windows 10 | 491 | instructions on how to upgrade to WSLv2 visit `Windows 10 |
497 | WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/wsl2-install>`__ | 492 | WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/wsl2-install>`__ |
@@ -507,8 +502,14 @@ your Yocto Project build host: | |||
507 | distribution. | 502 | distribution. |
508 | 503 | ||
509 | 3. *Check your Linux distribution is using WSLv2:* Open a Windows | 504 | 3. *Check your Linux distribution is using WSLv2:* Open a Windows |
510 | PowerShell and run: C:\WINDOWS\system32> wsl -l -v NAME STATE VERSION | 505 | PowerShell and run: |
511 | \*Ubuntu Running 2 Note the version column which says the WSL version | 506 | :: |
507 | |||
508 | C:\WINDOWS\system32> wsl -l -v | ||
509 | NAME STATE VERSION | ||
510 | *Ubuntu Running 2 | ||
511 | |||
512 | Note the version column which says the WSL version | ||
512 | being used by your distribution, on compatible systems, this can be | 513 | being used by your distribution, on compatible systems, this can be |
513 | changed back at any point in time. | 514 | changed back at any point in time. |
514 | 515 | ||
@@ -529,25 +530,35 @@ your Yocto Project build host: | |||
529 | 530 | ||
530 | 1. *Find the location of your VHDX file:* First you need to find the | 531 | 1. *Find the location of your VHDX file:* First you need to find the |
531 | distro app package directory, to achieve this open a Windows | 532 | distro app package directory, to achieve this open a Windows |
532 | Powershell as Administrator and run: C:\WINDOWS\system32> | 533 | Powershell as Administrator and run: |
533 | Get-AppxPackage -Name "*Ubuntu*" \| Select PackageFamilyName | 534 | :: |
534 | PackageFamilyName ----------------- | 535 | |
535 | CanonicalGroupLimited.UbuntuonWindows_79abcdefgh You should now | 536 | C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName |
537 | PackageFamilyName | ||
538 | ----------------- | ||
539 | CanonicalGroupLimited.UbuntuonWindows_79abcdefgh | ||
540 | |||
541 | |||
542 | You should now | ||
536 | replace the PackageFamilyName and your user on the following path | 543 | replace the PackageFamilyName and your user on the following path |
537 | to find your VHDX file: | 544 | to find your VHDX file: |
538 | ``C:\Users\user\AppData\Local\Packages\PackageFamilyName\LocalState\`` | 545 | :: |
539 | For example: ls | 546 | |
540 | C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\\ | 547 | ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ |
541 | Mode LastWriteTime Length Name -a---- 3/14/2020 9:52 PM | 548 | Mode LastWriteTime Length Name |
542 | 57418973184 ext4.vhdx Your VHDX file path is: | 549 | -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx |
550 | |||
551 | Your VHDX file path is: | ||
543 | ``C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx`` | 552 | ``C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx`` |
544 | 553 | ||
545 | 2. *Optimize your VHDX file:* Open a Windows Powershell as | 554 | 2. *Optimize your VHDX file:* Open a Windows Powershell as |
546 | Administrator to optimize your VHDX file, shutting down WSL first: | 555 | Administrator to optimize your VHDX file, shutting down WSL first: |
547 | C:\WINDOWS\system32> wsl --shutdown C:\WINDOWS\system32> | 556 | :: |
548 | optimize-vhd -Path | 557 | |
549 | C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx | 558 | C:\WINDOWS\system32> wsl --shutdown |
550 | -Mode full A progress bar should be shown while optimizing the | 559 | C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full |
560 | |||
561 | A progress bar should be shown while optimizing the | ||
551 | VHDX file, and storage should now be reflected correctly on the | 562 | VHDX file, and storage should now be reflected correctly on the |
552 | Windows Explorer. | 563 | Windows Explorer. |
553 | 564 | ||
@@ -565,12 +576,10 @@ your Yocto Project build host: | |||
565 | 576 | ||
566 | Once you have WSLv2 set up, everything is in place to develop just as if | 577 | Once you have WSLv2 set up, everything is in place to develop just as if |
567 | you were running on a native Linux machine. If you are going to use the | 578 | you were running on a native Linux machine. If you are going to use the |
568 | Extensible SDK container, see the "`Using the Extensible | 579 | Extensible SDK container, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto |
569 | SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" Chapter in the Yocto | ||
570 | Project Application Development and the Extensible Software Development | 580 | Project Application Development and the Extensible Software Development |
571 | Kit (eSDK) manual. If you are going to use the Toaster container, see | 581 | Kit (eSDK) manual. If you are going to use the Toaster container, see |
572 | the "`Setting Up and Using | 582 | the ":doc:`../toaster-manual/toaster-manual-setup-and-use`" |
573 | Toaster <&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use>`__" | ||
574 | section in the Toaster User Manual. | 583 | section in the Toaster User Manual. |
575 | 584 | ||
576 | Locating Yocto Project Source Files | 585 | Locating Yocto Project Source Files |
@@ -582,19 +591,17 @@ files you'll need to work with the Yocto Project. | |||
582 | .. note:: | 591 | .. note:: |
583 | 592 | ||
584 | - For concepts and introductory information about Git as it is used | 593 | - For concepts and introductory information about Git as it is used |
585 | in the Yocto Project, see the "`Git <&YOCTO_DOCS_OM_URL;#git>`__" | 594 | in the Yocto Project, see the ":ref:`overview-manual/overview-manual-development-environment:git`" |
586 | section in the Yocto Project Overview and Concepts Manual. | 595 | section in the Yocto Project Overview and Concepts Manual. |
587 | 596 | ||
588 | - For concepts on Yocto Project source repositories, see the "`Yocto | 597 | - For concepts on Yocto Project source repositories, see the |
589 | Project Source | 598 | ":ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`" |
590 | Repositories <&YOCTO_DOCS_OM_URL;#yocto-project-repositories>`__" | ||
591 | section in the Yocto Project Overview and Concepts Manual." | 599 | section in the Yocto Project Overview and Concepts Manual." |
592 | 600 | ||
593 | Accessing Source Repositories | 601 | Accessing Source Repositories |
594 | ----------------------------- | 602 | ----------------------------- |
595 | 603 | ||
596 | Working from a copy of the upstream Yocto Project `Source | 604 | Working from a copy of the upstream :ref:`dev-manual/dev-manual-start:accessing source repositories` is the |
597 | Repositories <&YOCTO_DOCS_OM_URL;#source-repositories>`__ is the | ||
598 | preferred method for obtaining and using a Yocto Project release. You | 605 | preferred method for obtaining and using a Yocto Project release. You |
599 | can view the Yocto Project Source Repositories at | 606 | can view the Yocto Project Source Repositories at |
600 | :yocto_git:`/`. In particular, you can find the ``poky`` | 607 | :yocto_git:`/`. In particular, you can find the ``poky`` |
@@ -611,8 +618,7 @@ Use the following procedure to locate the latest upstream copy of the | |||
611 | interested (e.g. ``poky``). | 618 | interested (e.g. ``poky``). |
612 | 619 | ||
613 | 3. *Find the URL Used to Clone the Repository:* At the bottom of the | 620 | 3. *Find the URL Used to Clone the Repository:* At the bottom of the |
614 | page, note the URL used to | 621 | page, note the URL used to clone that repository |
615 | `clone <&YOCTO_DOCS_OM_URL;#git-commands-clone>`__ that repository | ||
616 | (e.g. :yocto_git:`/git/poky`). | 622 | (e.g. :yocto_git:`/git/poky`). |
617 | 623 | ||
618 | .. note:: | 624 | .. note:: |
@@ -658,9 +664,9 @@ Follow these steps to locate and download a particular tarball: | |||
658 | are interested (e.g. ``yocto``). | 664 | are interested (e.g. ``yocto``). |
659 | 665 | ||
660 | 3. *Find the Tarball:* Drill down to find the associated tarball. For | 666 | 3. *Find the Tarball:* Drill down to find the associated tarball. For |
661 | example, click on ``yocto-DISTRO`` to view files associated with the | 667 | example, click on ``yocto-&DISTRO;`` to view files associated with the |
662 | Yocto Project DISTRO release (e.g. | 668 | Yocto Project &DISTRO; release (e.g. |
663 | ``poky-DISTRO_NAME_NO_CAP-POKYVERSION.tar.bz2``, which is the | 669 | ``&YOCTO_POKY;.tar.bz2``, which is the |
664 | released Poky tarball). | 670 | released Poky tarball). |
665 | 671 | ||
666 | 4. *Download the Tarball:* Click the tarball to download and save a | 672 | 4. *Download the Tarball:* Click the tarball to download and save a |
@@ -691,8 +697,7 @@ Releases <#accessing-index-of-releases>`__" section. | |||
691 | 697 | ||
692 | 3. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to | 698 | 3. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to |
693 | display and choose a recent or past supported Yocto Project release | 699 | display and choose a recent or past supported Yocto Project release |
694 | (e.g. DISTRO_NAME_NO_CAP, DISTRO_NAME_NO_CAP_MINUS_ONE, and so | 700 | (e.g. &DISTRO_NAME_NO_CAP;, &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth). |
695 | forth). | ||
696 | 701 | ||
697 | .. note:: | 702 | .. note:: |
698 | 703 | ||
@@ -711,7 +716,7 @@ Accessing Nightly Builds | |||
711 | ------------------------ | 716 | ------------------------ |
712 | 717 | ||
713 | Yocto Project maintains an area for nightly builds that contains tarball | 718 | Yocto Project maintains an area for nightly builds that contains tarball |
714 | releases at ` <&YOCTO_AB_NIGHTLY_URL;>`__. These builds include Yocto | 719 | releases at https://autobuilder.yocto.io//pub/nightly/. These builds include Yocto |
715 | Project releases ("poky"), toolchains, and builds for supported | 720 | Project releases ("poky"), toolchains, and builds for supported |
716 | machines. | 721 | machines. |
717 | 722 | ||
@@ -719,7 +724,7 @@ Should you ever want to access a nightly build of a particular Yocto | |||
719 | Project component, use the following procedure: | 724 | Project component, use the following procedure: |
720 | 725 | ||
721 | 1. *Locate the Index of Nightly Builds:* Open a browser and go to | 726 | 1. *Locate the Index of Nightly Builds:* Open a browser and go to |
722 | ` <&YOCTO_AB_NIGHTLY_URL;>`__ to access the Nightly Builds. | 727 | https://autobuilder.yocto.io//pub/nightly/ to access the Nightly Builds. |
723 | 728 | ||
724 | 2. *Select a Date:* Click on the date in which you are interested. If | 729 | 2. *Select a Date:* Click on the date in which you are interested. If |
725 | you want the latest builds, use "CURRENT". | 730 | you want the latest builds, use "CURRENT". |
@@ -739,11 +744,10 @@ Cloning and Checking Out Branches | |||
739 | To use the Yocto Project for development, you need a release locally | 744 | To use the Yocto Project for development, you need a release locally |
740 | installed on your development system. This locally installed set of | 745 | installed on your development system. This locally installed set of |
741 | files is referred to as the :term:`Source Directory` | 746 | files is referred to as the :term:`Source Directory` |
742 | in the Yocto | 747 | in the Yocto Project documentation. |
743 | Project documentation. | ||
744 | 748 | ||
745 | The preferred method of creating your Source Directory is by using | 749 | The preferred method of creating your Source Directory is by using |
746 | `Git <&YOCTO_DOCS_OM_URL;#git>`__ to clone a local copy of the upstream | 750 | :ref:`overview-manual/overview-manual-development-environment:git` to clone a local copy of the upstream |
747 | ``poky`` repository. Working from a cloned copy of the upstream | 751 | ``poky`` repository. Working from a cloned copy of the upstream |
748 | repository allows you to contribute back into the Yocto Project or to | 752 | repository allows you to contribute back into the Yocto Project or to |
749 | simply work with the latest software on a development branch. Because | 753 | simply work with the latest software on a development branch. Because |
@@ -756,19 +760,26 @@ Cloning the ``poky`` Repository | |||
756 | ------------------------------- | 760 | ------------------------------- |
757 | 761 | ||
758 | Follow these steps to create a local version of the upstream | 762 | Follow these steps to create a local version of the upstream |
759 | ```poky`` <&YOCTO_DOCS_REF_URL;#poky>`__ Git repository. | 763 | :term:`Poky` Git repository. |
760 | 764 | ||
761 | 1. *Set Your Directory:* Change your working directory to where you want | 765 | 1. *Set Your Directory:* Change your working directory to where you want |
762 | to create your local copy of ``poky``. | 766 | to create your local copy of ``poky``. |
763 | 767 | ||
764 | 2. *Clone the Repository:* The following example command clones the | 768 | 2. *Clone the Repository:* The following example command clones the |
765 | ``poky`` repository and uses the default name "poky" for your local | 769 | ``poky`` repository and uses the default name "poky" for your local |
766 | repository: $ git clone git://git.yoctoproject.org/poky Cloning into | 770 | repository: |
767 | 'poky'... remote: Counting objects: 432160, done. remote: Compressing | 771 | :: |
768 | objects: 100% (102056/102056), done. remote: Total 432160 (delta | 772 | |
769 | 323116), reused 432037 (delta 323000) Receiving objects: 100% | 773 | $ git clone git://git.yoctoproject.org/poky |
770 | (432160/432160), 153.81 MiB \| 8.54 MiB/s, done. Resolving deltas: | 774 | Cloning into 'poky'... |
771 | 100% (323116/323116), done. Checking connectivity... done. Unless you | 775 | remote: Counting objects: 432160, done. |
776 | remote: Compressing objects: 100% (102056/102056), done. | ||
777 | remote: Total 432160 (delta 323116), reused 432037 (delta 323000) | ||
778 | Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done. | ||
779 | Resolving deltas: 100% (323116/323116), done. | ||
780 | Checking connectivity... done. | ||
781 | |||
782 | Unless you | ||
772 | specify a specific development branch or tag name, Git clones the | 783 | specify a specific development branch or tag name, Git clones the |
773 | "master" branch, which results in a snapshot of the latest | 784 | "master" branch, which results in a snapshot of the latest |
774 | development changes for "master". For information on how to check out | 785 | development changes for "master". For information on how to check out |
@@ -779,13 +790,21 @@ Follow these steps to create a local version of the upstream | |||
779 | 790 | ||
780 | Once the local repository is created, you can change to that | 791 | Once the local repository is created, you can change to that |
781 | directory and check its status. Here, the single "master" branch | 792 | directory and check its status. Here, the single "master" branch |
782 | exists on your system and by default, it is checked out: $ cd ~/poky | 793 | exists on your system and by default, it is checked out: |
783 | $ git status On branch master Your branch is up-to-date with | 794 | :: |
784 | 'origin/master'. nothing to commit, working directory clean $ git | 795 | |
785 | branch \* master Your local repository of poky is identical to the | 796 | $ cd ~/poky |
797 | $ git status | ||
798 | On branch master | ||
799 | Your branch is up-to-date with 'origin/master'. | ||
800 | nothing to commit, working directory clean | ||
801 | $ git branch | ||
802 | * master | ||
803 | |||
804 | Your local repository of poky is identical to the | ||
786 | upstream poky repository at the time from which it was cloned. As you | 805 | upstream poky repository at the time from which it was cloned. As you |
787 | work with the local branch, you can periodically use the | 806 | work with the local branch, you can periodically use the |
788 | ``git pull DASHDASHrebase`` command to be sure you are up-to-date | 807 | ``git pull --rebase`` command to be sure you are up-to-date |
789 | with the upstream branch. | 808 | with the upstream branch. |
790 | 809 | ||
791 | Checking Out by Branch in Poky | 810 | Checking Out by Branch in Poky |
@@ -809,28 +828,48 @@ and then specifically check out that development branch. | |||
809 | copy of poky, see the "`Cloning the ``poky`` | 828 | copy of poky, see the "`Cloning the ``poky`` |
810 | Repository <#cloning-the-poky-repository>`__" section. | 829 | Repository <#cloning-the-poky-repository>`__" section. |
811 | 830 | ||
812 | 2. *Determine Existing Branch Names:* $ git branch -a \* master | 831 | 2. *Determine Existing Branch Names:* |
813 | remotes/origin/1.1_M1 remotes/origin/1.1_M2 remotes/origin/1.1_M3 | 832 | :: |
814 | remotes/origin/1.1_M4 remotes/origin/1.2_M1 remotes/origin/1.2_M2 | 833 | |
815 | remotes/origin/1.2_M3 . . . remotes/origin/thud | 834 | $ git branch -a |
816 | remotes/origin/thud-next remotes/origin/warrior | 835 | * master |
817 | remotes/origin/warrior-next remotes/origin/zeus | 836 | remotes/origin/1.1_M1 |
818 | remotes/origin/zeus-next ... and so on ... | 837 | remotes/origin/1.1_M2 |
838 | remotes/origin/1.1_M3 | ||
839 | remotes/origin/1.1_M4 | ||
840 | remotes/origin/1.2_M1 | ||
841 | remotes/origin/1.2_M2 | ||
842 | remotes/origin/1.2_M3 | ||
843 | . . . | ||
844 | remotes/origin/thud | ||
845 | remotes/origin/thud-next | ||
846 | remotes/origin/warrior | ||
847 | remotes/origin/warrior-next | ||
848 | remotes/origin/zeus | ||
849 | remotes/origin/zeus-next | ||
850 | ... and so on ... | ||
819 | 851 | ||
820 | 3. *Check out the Branch:* Check out the development branch in which you | 852 | 3. *Check out the Branch:* Check out the development branch in which you |
821 | want to work. For example, to access the files for the Yocto Project | 853 | want to work. For example, to access the files for the Yocto Project |
822 | DISTRO Release (DISTRO_NAME), use the following command: $ git | 854 | &DISTRO; Release (&DISTRO_NAME;), use the following command: |
823 | checkout -b DISTRO_NAME_NO_CAP origin/DISTRO_NAME_NO_CAP Branch | 855 | :: |
824 | DISTRO_NAME_NO_CAP set up to track remote branch DISTRO_NAME_NO_CAP | 856 | |
825 | from origin. Switched to a new branch 'DISTRO_NAME_NO_CAP' The | 857 | $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; |
826 | previous command checks out the "DISTRO_NAME_NO_CAP" development | 858 | Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin. |
859 | Switched to a new branch '&DISTRO_NAME;' | ||
860 | |||
861 | The previous command checks out the "&DISTRO_NAME;" development | ||
827 | branch and reports that the branch is tracking the upstream | 862 | branch and reports that the branch is tracking the upstream |
828 | "origin/DISTRO_NAME_NO_CAP" branch. | 863 | "origin/&DISTRO_NAME;" branch. |
829 | 864 | ||
830 | The following command displays the branches that are now part of your | 865 | The following command displays the branches that are now part of your |
831 | local poky repository. The asterisk character indicates the branch | 866 | local poky repository. The asterisk character indicates the branch |
832 | that is currently checked out for work: $ git branch master \* | 867 | that is currently checked out for work: |
833 | DISTRO_NAME_NO_CAP | 868 | :: |
869 | |||
870 | $ git branch | ||
871 | master * | ||
872 | &DISTRO_NAME; | ||
834 | 873 | ||
835 | .. _checkout-out-by-tag-in-poky: | 874 | .. _checkout-out-by-tag-in-poky: |
836 | 875 | ||
@@ -854,20 +893,48 @@ similar to checking out by branch name except you use tag names. | |||
854 | Repository <#cloning-the-poky-repository>`__" section. | 893 | Repository <#cloning-the-poky-repository>`__" section. |
855 | 894 | ||
856 | 2. *Fetch the Tag Names:* To checkout the branch based on a tag name, | 895 | 2. *Fetch the Tag Names:* To checkout the branch based on a tag name, |
857 | you need to fetch the upstream tags into your local repository: $ git | 896 | you need to fetch the upstream tags into your local repository: |
858 | fetch --tags $ | 897 | :: |
859 | 898 | ||
860 | 3. *List the Tag Names:* You can list the tag names now: $ git tag | 899 | $ git fetch --tags |
861 | 1.1_M1.final 1.1_M1.rc1 1.1_M1.rc2 1.1_M2.final 1.1_M2.rc1 . . . | 900 | $ |
862 | yocto-2.5 yocto-2.5.1 yocto-2.5.2 yocto-2.5.3 yocto-2.6 yocto-2.6.1 | 901 | |
863 | yocto-2.6.2 yocto-2.7 yocto_1.5_M5.rc8 | 902 | 3. *List the Tag Names:* You can list the tag names now: |
864 | 903 | :: | |
865 | 4. *Check out the Branch:* $ git checkout tags/DISTRO_REL_TAG -b | 904 | |
866 | my_yocto_DISTRO Switched to a new branch 'my_yocto_DISTRO' $ git | 905 | $ git tag |
867 | branch master \* my_yocto_DISTRO The previous command creates and | 906 | 1.1_M1.final |
868 | checks out a local branch named "my_yocto_DISTRO", which is based on | 907 | 1.1_M1.rc1 |
908 | 1.1_M1.rc2 | ||
909 | 1.1_M2.final | ||
910 | 1.1_M2.rc1 | ||
911 | . | ||
912 | . | ||
913 | . | ||
914 | yocto-2.5 | ||
915 | yocto-2.5.1 | ||
916 | yocto-2.5.2 | ||
917 | yocto-2.5.3 | ||
918 | yocto-2.6 | ||
919 | yocto-2.6.1 | ||
920 | yocto-2.6.2 | ||
921 | yocto-2.7 | ||
922 | yocto_1.5_M5.rc8 | ||
923 | |||
924 | |||
925 | 4. *Check out the Branch:* | ||
926 | :: | ||
927 | |||
928 | $ git checkout tags/yocto-&DISTRO; -b my_yocto_&DISTRO; | ||
929 | Switched to a new branch 'my_yocto_&DISTRO;' | ||
930 | $ git branch | ||
931 | master | ||
932 | * my_yocto_&DISTRO; | ||
933 | |||
934 | The previous command creates and | ||
935 | checks out a local branch named "my_yocto_&DISTRO;", which is based on | ||
869 | the commit in the upstream poky repository that has the same tag. In | 936 | the commit in the upstream poky repository that has the same tag. In |
870 | this example, the files you have available locally as a result of the | 937 | this example, the files you have available locally as a result of the |
871 | ``checkout`` command are a snapshot of the "DISTRO_NAME_NO_CAP" | 938 | ``checkout`` command are a snapshot of the "&DISTRO_NAME_NO_CAP;" |
872 | development branch at the point where Yocto Project DISTRO was | 939 | development branch at the point where Yocto Project &DISTRO; was |
873 | released. | 940 | released. |