diff options
Diffstat (limited to 'documentation/dev-manual/common-tasks.rst')
-rw-r--r-- | documentation/dev-manual/common-tasks.rst | 386 |
1 files changed, 193 insertions, 193 deletions
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst index 1307341730..762636a17c 100644 --- a/documentation/dev-manual/common-tasks.rst +++ b/documentation/dev-manual/common-tasks.rst | |||
@@ -94,10 +94,10 @@ Follow these general steps to create your layer without using tools: | |||
94 | 94 | ||
95 | - :term:`BBPATH`: Adds the layer's | 95 | - :term:`BBPATH`: Adds the layer's |
96 | root directory to BitBake's search path. Through the use of the | 96 | root directory to BitBake's search path. Through the use of the |
97 | ``BBPATH`` variable, BitBake locates class files (``.bbclass``), | 97 | :term:`BBPATH` variable, BitBake locates class files (``.bbclass``), |
98 | configuration files, and files that are included with ``include`` | 98 | configuration files, and files that are included with ``include`` |
99 | and ``require`` statements. For these cases, BitBake uses the | 99 | and ``require`` statements. For these cases, BitBake uses the |
100 | first file that matches the name found in ``BBPATH``. This is | 100 | first file that matches the name found in :term:`BBPATH`. This is |
101 | similar to the way the ``PATH`` variable is used for binaries. It | 101 | similar to the way the ``PATH`` variable is used for binaries. It |
102 | is recommended, therefore, that you use unique class and | 102 | is recommended, therefore, that you use unique class and |
103 | configuration filenames in your custom layer. | 103 | configuration filenames in your custom layer. |
@@ -205,7 +205,7 @@ following list: | |||
205 | ``foo``. | 205 | ``foo``. |
206 | 206 | ||
207 | To make sure your changes apply only when building machine "one", | 207 | To make sure your changes apply only when building machine "one", |
208 | use a machine override with the ``DEPENDS`` statement:: | 208 | use a machine override with the :term:`DEPENDS` statement:: |
209 | 209 | ||
210 | DEPENDS_one = "foo" | 210 | DEPENDS_one = "foo" |
211 | 211 | ||
@@ -255,7 +255,7 @@ following list: | |||
255 | are building for a different machine and the ``bblayers.conf`` | 255 | are building for a different machine and the ``bblayers.conf`` |
256 | file includes the ``meta-one`` layer and the location of your | 256 | file includes the ``meta-one`` layer and the location of your |
257 | machine-specific file is the first location where that file is | 257 | machine-specific file is the first location where that file is |
258 | found according to ``FILESPATH``, builds for all machines will | 258 | found according to :term:`FILESPATH`, builds for all machines will |
259 | also use that machine-specific file. | 259 | also use that machine-specific file. |
260 | 260 | ||
261 | You can make sure that a machine-specific file is used for a | 261 | You can make sure that a machine-specific file is used for a |
@@ -420,7 +420,7 @@ Enabling Your Layer | |||
420 | 420 | ||
421 | Before the OpenEmbedded build system can use your new layer, you need to | 421 | Before the OpenEmbedded build system can use your new layer, you need to |
422 | enable it. To enable your layer, simply add your layer's path to the | 422 | enable it. To enable your layer, simply add your layer's path to the |
423 | ``BBLAYERS`` variable in your ``conf/bblayers.conf`` file, which is | 423 | :term:`BBLAYERS` variable in your ``conf/bblayers.conf`` file, which is |
424 | found in the :term:`Build Directory`. | 424 | found in the :term:`Build Directory`. |
425 | The following example shows how to enable a layer named | 425 | The following example shows how to enable a layer named |
426 | ``meta-mylayer``:: | 426 | ``meta-mylayer``:: |
@@ -438,7 +438,7 @@ The following example shows how to enable a layer named | |||
438 | " | 438 | " |
439 | 439 | ||
440 | BitBake parses each ``conf/layer.conf`` file from the top down as | 440 | BitBake parses each ``conf/layer.conf`` file from the top down as |
441 | specified in the ``BBLAYERS`` variable within the ``conf/bblayers.conf`` | 441 | specified in the :term:`BBLAYERS` variable within the ``conf/bblayers.conf`` |
442 | file. During the processing of each ``conf/layer.conf`` file, BitBake | 442 | file. During the processing of each ``conf/layer.conf`` file, BitBake |
443 | adds the recipes, classes and configurations contained within the | 443 | adds the recipes, classes and configurations contained within the |
444 | particular layer to the source directory. | 444 | particular layer to the source directory. |
@@ -531,19 +531,19 @@ have the supporting directory structure set up that will contain any | |||
531 | files or patches you will be including from the layer. | 531 | files or patches you will be including from the layer. |
532 | 532 | ||
533 | Using the immediate expansion assignment operator ``:=`` is important | 533 | Using the immediate expansion assignment operator ``:=`` is important |
534 | because of the reference to ``THISDIR``. The trailing colon character is | 534 | because of the reference to :term:`THISDIR`. The trailing colon character is |
535 | important as it ensures that items in the list remain colon-separated. | 535 | important as it ensures that items in the list remain colon-separated. |
536 | 536 | ||
537 | .. note:: | 537 | .. note:: |
538 | 538 | ||
539 | BitBake automatically defines the ``THISDIR`` variable. You should | 539 | BitBake automatically defines the :term:`THISDIR` variable. You should |
540 | never set this variable yourself. Using "_prepend" as part of the | 540 | never set this variable yourself. Using "_prepend" as part of the |
541 | ``FILESEXTRAPATHS`` ensures your path will be searched prior to other | 541 | :term:`FILESEXTRAPATHS` ensures your path will be searched prior to other |
542 | paths in the final list. | 542 | paths in the final list. |
543 | 543 | ||
544 | Also, not all append files add extra files. Many append files simply | 544 | Also, not all append files add extra files. Many append files simply |
545 | allow to add build options (e.g. ``systemd``). For these cases, your | 545 | allow to add build options (e.g. ``systemd``). For these cases, your |
546 | append file would not even use the ``FILESEXTRAPATHS`` statement. | 546 | append file would not even use the :term:`FILESEXTRAPATHS` statement. |
547 | 547 | ||
548 | Prioritizing Your Layer | 548 | Prioritizing Your Layer |
549 | ----------------------- | 549 | ----------------------- |
@@ -830,7 +830,7 @@ variable changes are in effect for every build and consequently affect | |||
830 | all images, which might not be what you require. | 830 | all images, which might not be what you require. |
831 | 831 | ||
832 | To add a package to your image using the local configuration file, use | 832 | To add a package to your image using the local configuration file, use |
833 | the ``IMAGE_INSTALL`` variable with the ``_append`` operator:: | 833 | the :term:`IMAGE_INSTALL` variable with the ``_append`` operator:: |
834 | 834 | ||
835 | IMAGE_INSTALL_append = " strace" | 835 | IMAGE_INSTALL_append = " strace" |
836 | 836 | ||
@@ -855,7 +855,7 @@ to a specific image only. Here is an example:: | |||
855 | This example adds ``strace`` to the ``core-image-minimal`` image only. | 855 | This example adds ``strace`` to the ``core-image-minimal`` image only. |
856 | 856 | ||
857 | You can add packages using a similar approach through the | 857 | You can add packages using a similar approach through the |
858 | ``CORE_IMAGE_EXTRA_INSTALL`` variable. If you use this variable, only | 858 | :term:`CORE_IMAGE_EXTRA_INSTALL` variable. If you use this variable, only |
859 | ``core-image-*`` images are affected. | 859 | ``core-image-*`` images are affected. |
860 | 860 | ||
861 | Customizing Images Using Custom ``IMAGE_FEATURES`` and ``EXTRA_IMAGE_FEATURES`` | 861 | Customizing Images Using Custom ``IMAGE_FEATURES`` and ``EXTRA_IMAGE_FEATURES`` |
@@ -866,18 +866,18 @@ high-level image features by using the | |||
866 | :term:`IMAGE_FEATURES` and | 866 | :term:`IMAGE_FEATURES` and |
867 | :term:`EXTRA_IMAGE_FEATURES` | 867 | :term:`EXTRA_IMAGE_FEATURES` |
868 | variables. Although the functions for both variables are nearly | 868 | variables. Although the functions for both variables are nearly |
869 | equivalent, best practices dictate using ``IMAGE_FEATURES`` from within | 869 | equivalent, best practices dictate using :term:`IMAGE_FEATURES` from within |
870 | a recipe and using ``EXTRA_IMAGE_FEATURES`` from within your | 870 | a recipe and using :term:`EXTRA_IMAGE_FEATURES` from within your |
871 | ``local.conf`` file, which is found in the | 871 | ``local.conf`` file, which is found in the |
872 | :term:`Build Directory`. | 872 | :term:`Build Directory`. |
873 | 873 | ||
874 | To understand how these features work, the best reference is | 874 | To understand how these features work, the best reference is |
875 | ``meta/classes/core-image.bbclass``. This class lists out the available | 875 | ``meta/classes/core-image.bbclass``. This class lists out the available |
876 | ``IMAGE_FEATURES`` of which most map to package groups while some, such | 876 | :term:`IMAGE_FEATURES` of which most map to package groups while some, such |
877 | as ``debug-tweaks`` and ``read-only-rootfs``, resolve as general | 877 | as ``debug-tweaks`` and ``read-only-rootfs``, resolve as general |
878 | configuration settings. | 878 | configuration settings. |
879 | 879 | ||
880 | In summary, the file looks at the contents of the ``IMAGE_FEATURES`` | 880 | In summary, the file looks at the contents of the :term:`IMAGE_FEATURES` |
881 | variable and then maps or configures the feature accordingly. Based on | 881 | variable and then maps or configures the feature accordingly. Based on |
882 | this information, the build system automatically adds the appropriate | 882 | this information, the build system automatically adds the appropriate |
883 | packages or configurations to the | 883 | packages or configurations to the |
@@ -885,11 +885,11 @@ packages or configurations to the | |||
885 | Effectively, you are enabling extra features by extending the class or | 885 | Effectively, you are enabling extra features by extending the class or |
886 | creating a custom class for use with specialized image ``.bb`` files. | 886 | creating a custom class for use with specialized image ``.bb`` files. |
887 | 887 | ||
888 | Use the ``EXTRA_IMAGE_FEATURES`` variable from within your local | 888 | Use the :term:`EXTRA_IMAGE_FEATURES` variable from within your local |
889 | configuration file. Using a separate area from which to enable features | 889 | configuration file. Using a separate area from which to enable features |
890 | with this variable helps you avoid overwriting the features in the image | 890 | with this variable helps you avoid overwriting the features in the image |
891 | recipe that are enabled with ``IMAGE_FEATURES``. The value of | 891 | recipe that are enabled with :term:`IMAGE_FEATURES`. The value of |
892 | ``EXTRA_IMAGE_FEATURES`` is added to ``IMAGE_FEATURES`` within | 892 | :term:`EXTRA_IMAGE_FEATURES` is added to :term:`IMAGE_FEATURES` within |
893 | ``meta/conf/bitbake.conf``. | 893 | ``meta/conf/bitbake.conf``. |
894 | 894 | ||
895 | To illustrate how you can use these variables to modify your image, | 895 | To illustrate how you can use these variables to modify your image, |
@@ -903,8 +903,8 @@ images both include OpenSSH. The ``core-image-minimal`` image does not | |||
903 | contain an SSH server. | 903 | contain an SSH server. |
904 | 904 | ||
905 | You can customize your image and change these defaults. Edit the | 905 | You can customize your image and change these defaults. Edit the |
906 | ``IMAGE_FEATURES`` variable in your recipe or use the | 906 | :term:`IMAGE_FEATURES` variable in your recipe or use the |
907 | ``EXTRA_IMAGE_FEATURES`` in your ``local.conf`` file so that it | 907 | :term:`EXTRA_IMAGE_FEATURES` in your ``local.conf`` file so that it |
908 | configures the image you are working with to include | 908 | configures the image you are working with to include |
909 | ``ssh-server-dropbear`` or ``ssh-server-openssh``. | 909 | ``ssh-server-dropbear`` or ``ssh-server-openssh``. |
910 | 910 | ||
@@ -926,7 +926,7 @@ the form for the two lines you need:: | |||
926 | 926 | ||
927 | Defining the software using a custom recipe gives you total control over | 927 | Defining the software using a custom recipe gives you total control over |
928 | the contents of the image. It is important to use the correct names of | 928 | the contents of the image. It is important to use the correct names of |
929 | packages in the ``IMAGE_INSTALL`` variable. You must use the | 929 | packages in the :term:`IMAGE_INSTALL` variable. You must use the |
930 | OpenEmbedded notation and not the Debian notation for the names (e.g. | 930 | OpenEmbedded notation and not the Debian notation for the names (e.g. |
931 | ``glibc-dev`` instead of ``libc6-dev``). | 931 | ``glibc-dev`` instead of ``libc6-dev``). |
932 | 932 | ||
@@ -946,25 +946,25 @@ to create a custom package group recipe that is used to build the image | |||
946 | or images. A good example of a package group recipe is | 946 | or images. A good example of a package group recipe is |
947 | ``meta/recipes-core/packagegroups/packagegroup-base.bb``. | 947 | ``meta/recipes-core/packagegroups/packagegroup-base.bb``. |
948 | 948 | ||
949 | If you examine that recipe, you see that the ``PACKAGES`` variable lists | 949 | If you examine that recipe, you see that the :term:`PACKAGES` variable lists |
950 | the package group packages to produce. The ``inherit packagegroup`` | 950 | the package group packages to produce. The ``inherit packagegroup`` |
951 | statement sets appropriate default values and automatically adds | 951 | statement sets appropriate default values and automatically adds |
952 | ``-dev``, ``-dbg``, and ``-ptest`` complementary packages for each | 952 | ``-dev``, ``-dbg``, and ``-ptest`` complementary packages for each |
953 | package specified in the ``PACKAGES`` statement. | 953 | package specified in the :term:`PACKAGES` statement. |
954 | 954 | ||
955 | .. note:: | 955 | .. note:: |
956 | 956 | ||
957 | The ``inherit packagegroup`` line should be located near the top of the | 957 | The ``inherit packagegroup`` line should be located near the top of the |
958 | recipe, certainly before the ``PACKAGES`` statement. | 958 | recipe, certainly before the :term:`PACKAGES` statement. |
959 | 959 | ||
960 | For each package you specify in ``PACKAGES``, you can use ``RDEPENDS`` | 960 | For each package you specify in :term:`PACKAGES`, you can use :term:`RDEPENDS` |
961 | and ``RRECOMMENDS`` entries to provide a list of packages the parent | 961 | and :term:`RRECOMMENDS` entries to provide a list of packages the parent |
962 | task package should contain. You can see examples of these further down | 962 | task package should contain. You can see examples of these further down |
963 | in the ``packagegroup-base.bb`` recipe. | 963 | in the ``packagegroup-base.bb`` recipe. |
964 | 964 | ||
965 | Here is a short, fabricated example showing the same basic pieces for a | 965 | Here is a short, fabricated example showing the same basic pieces for a |
966 | hypothetical packagegroup defined in ``packagegroup-custom.bb``, where | 966 | hypothetical packagegroup defined in ``packagegroup-custom.bb``, where |
967 | the variable ``PN`` is the standard way to abbreviate the reference to | 967 | the variable :term:`PN` is the standard way to abbreviate the reference to |
968 | the full packagegroup name ``packagegroup-custom``:: | 968 | the full packagegroup name ``packagegroup-custom``:: |
969 | 969 | ||
970 | DESCRIPTION = "My Custom Package Groups" | 970 | DESCRIPTION = "My Custom Package Groups" |
@@ -994,7 +994,7 @@ their dependencies and their recommended package dependencies listed: | |||
994 | ``packagegroup-custom-apps``, and ``packagegroup-custom-tools``. To | 994 | ``packagegroup-custom-apps``, and ``packagegroup-custom-tools``. To |
995 | build an image using these package group packages, you need to add | 995 | build an image using these package group packages, you need to add |
996 | ``packagegroup-custom-apps`` and/or ``packagegroup-custom-tools`` to | 996 | ``packagegroup-custom-apps`` and/or ``packagegroup-custom-tools`` to |
997 | ``IMAGE_INSTALL``. For other forms of image dependencies see the other | 997 | :term:`IMAGE_INSTALL`. For other forms of image dependencies see the other |
998 | areas of this section. | 998 | areas of this section. |
999 | 999 | ||
1000 | Customizing an Image Hostname | 1000 | Customizing an Image Hostname |
@@ -1142,7 +1142,7 @@ Following are some syntax examples: | |||
1142 | 1142 | ||
1143 | - Use this syntax to generate a recipe using code that | 1143 | - Use this syntax to generate a recipe using code that |
1144 | you extract from source. The extracted code is placed in its own layer | 1144 | you extract from source. The extracted code is placed in its own layer |
1145 | defined by ``EXTERNALSRC``. | 1145 | defined by :term:`EXTERNALSRC`. |
1146 | :: | 1146 | :: |
1147 | 1147 | ||
1148 | recipetool create -o OUTFILE -x EXTERNALSRC source | 1148 | recipetool create -o OUTFILE -x EXTERNALSRC source |
@@ -1288,22 +1288,22 @@ Fetching Code | |||
1288 | The first thing your recipe must do is specify how to fetch the source | 1288 | The first thing your recipe must do is specify how to fetch the source |
1289 | files. Fetching is controlled mainly through the | 1289 | files. Fetching is controlled mainly through the |
1290 | :term:`SRC_URI` variable. Your recipe | 1290 | :term:`SRC_URI` variable. Your recipe |
1291 | must have a ``SRC_URI`` variable that points to where the source is | 1291 | must have a :term:`SRC_URI` variable that points to where the source is |
1292 | located. For a graphical representation of source locations, see the | 1292 | located. For a graphical representation of source locations, see the |
1293 | ":ref:`overview-manual/concepts:sources`" section in | 1293 | ":ref:`overview-manual/concepts:sources`" section in |
1294 | the Yocto Project Overview and Concepts Manual. | 1294 | the Yocto Project Overview and Concepts Manual. |
1295 | 1295 | ||
1296 | The :ref:`ref-tasks-fetch` task uses | 1296 | The :ref:`ref-tasks-fetch` task uses |
1297 | the prefix of each entry in the ``SRC_URI`` variable value to determine | 1297 | the prefix of each entry in the :term:`SRC_URI` variable value to determine |
1298 | which :ref:`fetcher <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` to use to get your | 1298 | which :ref:`fetcher <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` to use to get your |
1299 | source files. It is the ``SRC_URI`` variable that triggers the fetcher. | 1299 | source files. It is the :term:`SRC_URI` variable that triggers the fetcher. |
1300 | The :ref:`ref-tasks-patch` task uses | 1300 | The :ref:`ref-tasks-patch` task uses |
1301 | the variable after source is fetched to apply patches. The OpenEmbedded | 1301 | the variable after source is fetched to apply patches. The OpenEmbedded |
1302 | build system uses | 1302 | build system uses |
1303 | :term:`FILESOVERRIDES` for | 1303 | :term:`FILESOVERRIDES` for |
1304 | scanning directory locations for local files in ``SRC_URI``. | 1304 | scanning directory locations for local files in :term:`SRC_URI`. |
1305 | 1305 | ||
1306 | The ``SRC_URI`` variable in your recipe must define each unique location | 1306 | The :term:`SRC_URI` variable in your recipe must define each unique location |
1307 | for your source files. It is good practice to not hard-code version | 1307 | for your source files. It is good practice to not hard-code version |
1308 | numbers in a URL used in ``SRC_URI``. Rather than hard-code these | 1308 | numbers in a URL used in ``SRC_URI``. Rather than hard-code these |
1309 | values, use ``${``\ :term:`PV`\ ``}``, | 1309 | values, use ``${``\ :term:`PV`\ ``}``, |
@@ -1319,7 +1319,7 @@ comes from a single tarball. Notice the use of the | |||
1319 | 1319 | ||
1320 | SRC_URI = "https://strace.io/files/${PV}/strace-${PV}.tar.xz \ | 1320 | SRC_URI = "https://strace.io/files/${PV}/strace-${PV}.tar.xz \ |
1321 | 1321 | ||
1322 | Files mentioned in ``SRC_URI`` whose names end in a typical archive | 1322 | Files mentioned in :term:`SRC_URI` whose names end in a typical archive |
1323 | extension (e.g. ``.tar``, ``.tar.gz``, ``.tar.bz2``, ``.zip``, and so | 1323 | extension (e.g. ``.tar``, ``.tar.gz``, ``.tar.bz2``, ``.zip``, and so |
1324 | forth), are automatically extracted during the | 1324 | forth), are automatically extracted during the |
1325 | :ref:`ref-tasks-unpack` task. For | 1325 | :ref:`ref-tasks-unpack` task. For |
@@ -1341,17 +1341,17 @@ is an example from the recipe | |||
1341 | SRC_URI = "git://git.kernel.dk/blktrace.git \ | 1341 | SRC_URI = "git://git.kernel.dk/blktrace.git \ |
1342 | file://ldflags.patch" | 1342 | file://ldflags.patch" |
1343 | 1343 | ||
1344 | If your ``SRC_URI`` statement includes URLs pointing to individual files | 1344 | If your :term:`SRC_URI` statement includes URLs pointing to individual files |
1345 | fetched from a remote server other than a version control system, | 1345 | fetched from a remote server other than a version control system, |
1346 | BitBake attempts to verify the files against checksums defined in your | 1346 | BitBake attempts to verify the files against checksums defined in your |
1347 | recipe to ensure they have not been tampered with or otherwise modified | 1347 | recipe to ensure they have not been tampered with or otherwise modified |
1348 | since the recipe was written. Two checksums are used: | 1348 | since the recipe was written. Two checksums are used: |
1349 | ``SRC_URI[md5sum]`` and ``SRC_URI[sha256sum]``. | 1349 | ``SRC_URI[md5sum]`` and ``SRC_URI[sha256sum]``. |
1350 | 1350 | ||
1351 | If your ``SRC_URI`` variable points to more than a single URL (excluding | 1351 | If your :term:`SRC_URI` variable points to more than a single URL (excluding |
1352 | SCM URLs), you need to provide the ``md5`` and ``sha256`` checksums for | 1352 | SCM URLs), you need to provide the ``md5`` and ``sha256`` checksums for |
1353 | each URL. For these cases, you provide a name for each URL as part of | 1353 | each URL. For these cases, you provide a name for each URL as part of |
1354 | the ``SRC_URI`` and then reference that name in the subsequent checksum | 1354 | the :term:`SRC_URI` and then reference that name in the subsequent checksum |
1355 | statements. Here is an example combining lines from the files | 1355 | statements. Here is an example combining lines from the files |
1356 | ``git.inc`` and ``git_2.24.1.bb``:: | 1356 | ``git.inc`` and ``git_2.24.1.bb``:: |
1357 | 1357 | ||
@@ -1369,7 +1369,7 @@ with other signatures on the download page for the upstream source (e.g. | |||
1369 | OpenEmbedded build system only deals with ``sha256sum`` and ``md5sum``, | 1369 | OpenEmbedded build system only deals with ``sha256sum`` and ``md5sum``, |
1370 | you should verify all the signatures you find by hand. | 1370 | you should verify all the signatures you find by hand. |
1371 | 1371 | ||
1372 | If no ``SRC_URI`` checksums are specified when you attempt to build the | 1372 | If no :term:`SRC_URI` checksums are specified when you attempt to build the |
1373 | recipe, or you provide an incorrect checksum, the build will produce an | 1373 | recipe, or you provide an incorrect checksum, the build will produce an |
1374 | error for each missing or incorrect checksum. As part of the error | 1374 | error for each missing or incorrect checksum. As part of the error |
1375 | message, the build system provides the checksum string corresponding to | 1375 | message, the build system provides the checksum string corresponding to |
@@ -1385,7 +1385,7 @@ paste them into your recipe and then run the build again to continue. | |||
1385 | 1385 | ||
1386 | This final example is a bit more complicated and is from the | 1386 | This final example is a bit more complicated and is from the |
1387 | ``meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb`` recipe. The | 1387 | ``meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb`` recipe. The |
1388 | example's ``SRC_URI`` statement identifies multiple files as the source | 1388 | example's :term:`SRC_URI` statement identifies multiple files as the source |
1389 | files for the recipe: a tarball, a patch file, a desktop file, and an | 1389 | files for the recipe: a tarball, a patch file, a desktop file, and an |
1390 | icon. | 1390 | icon. |
1391 | :: | 1391 | :: |
@@ -1424,9 +1424,9 @@ If you are fetching your source files from an upstream source archived | |||
1424 | tarball and the tarball's internal structure matches the common | 1424 | tarball and the tarball's internal structure matches the common |
1425 | convention of a top-level subdirectory named | 1425 | convention of a top-level subdirectory named |
1426 | ``${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``, | 1426 | ``${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``, |
1427 | then you do not need to set ``S``. However, if ``SRC_URI`` specifies to | 1427 | then you do not need to set :term:`S`. However, if :term:`SRC_URI` specifies to |
1428 | fetch source from an archive that does not use this convention, or from | 1428 | fetch source from an archive that does not use this convention, or from |
1429 | an SCM like Git or Subversion, your recipe needs to define ``S``. | 1429 | an SCM like Git or Subversion, your recipe needs to define :term:`S`. |
1430 | 1430 | ||
1431 | If processing your recipe using BitBake successfully unpacks the source | 1431 | If processing your recipe using BitBake successfully unpacks the source |
1432 | files, you need to be sure that the directory pointed to by ``${S}`` | 1432 | files, you need to be sure that the directory pointed to by ``${S}`` |
@@ -1436,7 +1436,7 @@ Patching Code | |||
1436 | ------------- | 1436 | ------------- |
1437 | 1437 | ||
1438 | Sometimes it is necessary to patch code after it has been fetched. Any | 1438 | Sometimes it is necessary to patch code after it has been fetched. Any |
1439 | files mentioned in ``SRC_URI`` whose names end in ``.patch`` or | 1439 | files mentioned in :term:`SRC_URI` whose names end in ``.patch`` or |
1440 | ``.diff`` or compressed versions of these suffixes (e.g. ``diff.gz`` are | 1440 | ``.diff`` or compressed versions of these suffixes (e.g. ``diff.gz`` are |
1441 | treated as patches. The | 1441 | treated as patches. The |
1442 | :ref:`ref-tasks-patch` task | 1442 | :ref:`ref-tasks-patch` task |
@@ -1445,7 +1445,7 @@ automatically applies these patches. | |||
1445 | The build system should be able to apply patches with the "-p1" option | 1445 | The build system should be able to apply patches with the "-p1" option |
1446 | (i.e. one directory level in the path will be stripped off). If your | 1446 | (i.e. one directory level in the path will be stripped off). If your |
1447 | patch needs to have more directory levels stripped off, specify the | 1447 | patch needs to have more directory levels stripped off, specify the |
1448 | number of levels using the "striplevel" option in the ``SRC_URI`` entry | 1448 | number of levels using the "striplevel" option in the :term:`SRC_URI` entry |
1449 | for the patch. Alternatively, if your patch needs to be applied in a | 1449 | for the patch. Alternatively, if your patch needs to be applied in a |
1450 | specific subdirectory that is not specified in the patch file, use the | 1450 | specific subdirectory that is not specified in the patch file, use the |
1451 | "patchdir" option in the entry. | 1451 | "patchdir" option in the entry. |
@@ -1465,24 +1465,24 @@ Your recipe needs to have both the | |||
1465 | :term:`LIC_FILES_CHKSUM` | 1465 | :term:`LIC_FILES_CHKSUM` |
1466 | variables: | 1466 | variables: |
1467 | 1467 | ||
1468 | - ``LICENSE``: This variable specifies the license for the software. | 1468 | - :term:`LICENSE`: This variable specifies the license for the software. |
1469 | If you do not know the license under which the software you are | 1469 | If you do not know the license under which the software you are |
1470 | building is distributed, you should go to the source code and look | 1470 | building is distributed, you should go to the source code and look |
1471 | for that information. Typical files containing this information | 1471 | for that information. Typical files containing this information |
1472 | include ``COPYING``, ``LICENSE``, and ``README`` files. You could | 1472 | include ``COPYING``, :term:`LICENSE`, and ``README`` files. You could |
1473 | also find the information near the top of a source file. For example, | 1473 | also find the information near the top of a source file. For example, |
1474 | given a piece of software licensed under the GNU General Public | 1474 | given a piece of software licensed under the GNU General Public |
1475 | License version 2, you would set ``LICENSE`` as follows:: | 1475 | License version 2, you would set :term:`LICENSE` as follows:: |
1476 | 1476 | ||
1477 | LICENSE = "GPLv2" | 1477 | LICENSE = "GPLv2" |
1478 | 1478 | ||
1479 | The licenses you specify within ``LICENSE`` can have any name as long | 1479 | The licenses you specify within :term:`LICENSE` can have any name as long |
1480 | as you do not use spaces, since spaces are used as separators between | 1480 | as you do not use spaces, since spaces are used as separators between |
1481 | license names. For standard licenses, use the names of the files in | 1481 | license names. For standard licenses, use the names of the files in |
1482 | ``meta/files/common-licenses/`` or the ``SPDXLICENSEMAP`` flag names | 1482 | ``meta/files/common-licenses/`` or the :term:`SPDXLICENSEMAP` flag names |
1483 | defined in ``meta/conf/licenses.conf``. | 1483 | defined in ``meta/conf/licenses.conf``. |
1484 | 1484 | ||
1485 | - ``LIC_FILES_CHKSUM``: The OpenEmbedded build system uses this | 1485 | - :term:`LIC_FILES_CHKSUM`: The OpenEmbedded build system uses this |
1486 | variable to make sure the license text has not changed. If it has, | 1486 | variable to make sure the license text has not changed. If it has, |
1487 | the build produces an error and it affords you the chance to figure | 1487 | the build produces an error and it affords you the chance to figure |
1488 | it out and correct the problem. | 1488 | it out and correct the problem. |
@@ -1492,11 +1492,11 @@ variables: | |||
1492 | the checksums of the files to be sure the text has not changed. Any | 1492 | the checksums of the files to be sure the text has not changed. Any |
1493 | differences result in an error with the message containing the | 1493 | differences result in an error with the message containing the |
1494 | current checksum. For more explanation and examples of how to set the | 1494 | current checksum. For more explanation and examples of how to set the |
1495 | ``LIC_FILES_CHKSUM`` variable, see the | 1495 | :term:`LIC_FILES_CHKSUM` variable, see the |
1496 | ":ref:`dev-manual/common-tasks:tracking license changes`" section. | 1496 | ":ref:`dev-manual/common-tasks:tracking license changes`" section. |
1497 | 1497 | ||
1498 | To determine the correct checksum string, you can list the | 1498 | To determine the correct checksum string, you can list the |
1499 | appropriate files in the ``LIC_FILES_CHKSUM`` variable with incorrect | 1499 | appropriate files in the :term:`LIC_FILES_CHKSUM` variable with incorrect |
1500 | md5 strings, attempt to build the software, and then note the | 1500 | md5 strings, attempt to build the software, and then note the |
1501 | resulting error messages that will report the correct md5 strings. | 1501 | resulting error messages that will report the correct md5 strings. |
1502 | See the ":ref:`dev-manual/common-tasks:fetching code`" section for | 1502 | See the ":ref:`dev-manual/common-tasks:fetching code`" section for |
@@ -1522,7 +1522,7 @@ installed on the target in order for the software to run. | |||
1522 | 1522 | ||
1523 | Within a recipe, you specify build-time dependencies using the | 1523 | Within a recipe, you specify build-time dependencies using the |
1524 | :term:`DEPENDS` variable. Although there are nuances, | 1524 | :term:`DEPENDS` variable. Although there are nuances, |
1525 | items specified in ``DEPENDS`` should be names of other | 1525 | items specified in :term:`DEPENDS` should be names of other |
1526 | recipes. It is important that you specify all build-time dependencies | 1526 | recipes. It is important that you specify all build-time dependencies |
1527 | explicitly. | 1527 | explicitly. |
1528 | 1528 | ||
@@ -1639,12 +1639,12 @@ your software is built: | |||
1639 | Once configuration succeeds, it is always good practice to look at the | 1639 | Once configuration succeeds, it is always good practice to look at the |
1640 | ``log.do_configure`` file to ensure that the appropriate options have | 1640 | ``log.do_configure`` file to ensure that the appropriate options have |
1641 | been enabled and no additional build-time dependencies need to be added | 1641 | been enabled and no additional build-time dependencies need to be added |
1642 | to ``DEPENDS``. For example, if the configure script reports that it | 1642 | to :term:`DEPENDS`. For example, if the configure script reports that it |
1643 | found something not mentioned in ``DEPENDS``, or that it did not find | 1643 | found something not mentioned in :term:`DEPENDS`, or that it did not find |
1644 | something that it needed for some desired optional functionality, then | 1644 | something that it needed for some desired optional functionality, then |
1645 | you would need to add those to ``DEPENDS``. Looking at the log might | 1645 | you would need to add those to :term:`DEPENDS`. Looking at the log might |
1646 | also reveal items being checked for, enabled, or both that you do not | 1646 | also reveal items being checked for, enabled, or both that you do not |
1647 | want, or items not being found that are in ``DEPENDS``, in which case | 1647 | want, or items not being found that are in :term:`DEPENDS`, in which case |
1648 | you would need to look at passing extra options to the configure script | 1648 | you would need to look at passing extra options to the configure script |
1649 | as needed. For reference information on configure options specific to | 1649 | as needed. For reference information on configure options specific to |
1650 | the software you are building, you can consult the output of the | 1650 | the software you are building, you can consult the output of the |
@@ -1762,13 +1762,13 @@ Here are some common issues that cause failures. | |||
1762 | compilation process notes that files could not be found. In these | 1762 | compilation process notes that files could not be found. In these |
1763 | cases, you need to go back and add additional options to the | 1763 | cases, you need to go back and add additional options to the |
1764 | configure script as well as possibly add additional build-time | 1764 | configure script as well as possibly add additional build-time |
1765 | dependencies to ``DEPENDS``. | 1765 | dependencies to :term:`DEPENDS`. |
1766 | 1766 | ||
1767 | Occasionally, it is necessary to apply a patch to the source to | 1767 | Occasionally, it is necessary to apply a patch to the source to |
1768 | ensure the correct paths are used. If you need to specify paths to | 1768 | ensure the correct paths are used. If you need to specify paths to |
1769 | find files staged into the sysroot from other recipes, use the | 1769 | find files staged into the sysroot from other recipes, use the |
1770 | variables that the OpenEmbedded build system provides (e.g. | 1770 | variables that the OpenEmbedded build system provides (e.g. |
1771 | ``STAGING_BINDIR``, ``STAGING_INCDIR``, ``STAGING_DATADIR``, and so | 1771 | :term:`STAGING_BINDIR`, :term:`STAGING_INCDIR`, :term:`STAGING_DATADIR`, and so |
1772 | forth). | 1772 | forth). |
1773 | 1773 | ||
1774 | Installing | 1774 | Installing |
@@ -2022,7 +2022,7 @@ the list of directories within a recipe:: | |||
2022 | 2022 | ||
2023 | The `/sysroot-only` is to be used by recipes that generate artifacts | 2023 | The `/sysroot-only` is to be used by recipes that generate artifacts |
2024 | that are not included in the target filesystem, allowing them to share | 2024 | that are not included in the target filesystem, allowing them to share |
2025 | these artifacts without needing to use the ``DEPLOY_DIR``. | 2025 | these artifacts without needing to use the :term:`DEPLOY_DIR`. |
2026 | 2026 | ||
2027 | For a more complete description of the :ref:`ref-tasks-populate_sysroot` | 2027 | For a more complete description of the :ref:`ref-tasks-populate_sysroot` |
2028 | task and its associated functions, see the | 2028 | task and its associated functions, see the |
@@ -2048,7 +2048,7 @@ statement that essentially identifies itself as being able to provide | |||
2048 | PROVIDES += "${@ "virtual/kernel" if (d.getVar("KERNEL_PACKAGE_NAME") == "kernel") else "" }" | 2048 | PROVIDES += "${@ "virtual/kernel" if (d.getVar("KERNEL_PACKAGE_NAME") == "kernel") else "" }" |
2049 | 2049 | ||
2050 | Any recipe that inherits the ``kernel`` class is | 2050 | Any recipe that inherits the ``kernel`` class is |
2051 | going to utilize a ``PROVIDES`` statement that identifies that recipe as | 2051 | going to utilize a :term:`PROVIDES` statement that identifies that recipe as |
2052 | being able to provide the ``virtual/kernel`` item. | 2052 | being able to provide the ``virtual/kernel`` item. |
2053 | 2053 | ||
2054 | Now comes the time to actually build an image and you need a kernel | 2054 | Now comes the time to actually build an image and you need a kernel |
@@ -2072,7 +2072,7 @@ build is dependent on ``virtual/kernel`` for example:: | |||
2072 | 2072 | ||
2073 | During the build, the OpenEmbedded build system picks | 2073 | During the build, the OpenEmbedded build system picks |
2074 | the correct recipe needed for the ``virtual/kernel`` dependency based on | 2074 | the correct recipe needed for the ``virtual/kernel`` dependency based on |
2075 | the ``PREFERRED_PROVIDER`` variable. If you want to use the small kernel | 2075 | the :term:`PREFERRED_PROVIDER` variable. If you want to use the small kernel |
2076 | mentioned at the beginning of this section, configure your build as | 2076 | mentioned at the beginning of this section, configure your build as |
2077 | follows:: | 2077 | follows:: |
2078 | 2078 | ||
@@ -2080,8 +2080,8 @@ follows:: | |||
2080 | 2080 | ||
2081 | .. note:: | 2081 | .. note:: |
2082 | 2082 | ||
2083 | Any recipe that ``PROVIDES`` a ``virtual/*`` item that is ultimately not | 2083 | Any recipe that :term:`PROVIDES` a ``virtual/*`` item that is ultimately not |
2084 | selected through ``PREFERRED_PROVIDER`` does not get built. Preventing these | 2084 | selected through :term:`PREFERRED_PROVIDER` does not get built. Preventing these |
2085 | recipes from building is usually the desired behavior since this mechanism's | 2085 | recipes from building is usually the desired behavior since this mechanism's |
2086 | purpose is to select between mutually exclusive alternative providers. | 2086 | purpose is to select between mutually exclusive alternative providers. |
2087 | 2087 | ||
@@ -2221,8 +2221,8 @@ Single .c File Package (Hello World!) | |||
2221 | 2221 | ||
2222 | Building an application from a single file that is stored locally (e.g. | 2222 | Building an application from a single file that is stored locally (e.g. |
2223 | under ``files``) requires a recipe that has the file listed in the | 2223 | under ``files``) requires a recipe that has the file listed in the |
2224 | ``SRC_URI`` variable. Additionally, you need to manually write the | 2224 | :term:`SRC_URI` variable. Additionally, you need to manually write the |
2225 | ``do_compile`` and ``do_install`` tasks. The ``S`` variable defines the | 2225 | ``do_compile`` and ``do_install`` tasks. The :term:`S` variable defines the |
2226 | directory containing the source code, which is set to | 2226 | directory containing the source code, which is set to |
2227 | :term:`WORKDIR` in this case - the | 2227 | :term:`WORKDIR` in this case - the |
2228 | directory BitBake uses for the build. | 2228 | directory BitBake uses for the build. |
@@ -2256,7 +2256,7 @@ Autotooled Package | |||
2256 | ~~~~~~~~~~~~~~~~~~ | 2256 | ~~~~~~~~~~~~~~~~~~ |
2257 | 2257 | ||
2258 | Applications that use Autotools such as ``autoconf`` and ``automake`` | 2258 | Applications that use Autotools such as ``autoconf`` and ``automake`` |
2259 | require a recipe that has a source archive listed in ``SRC_URI`` and | 2259 | require a recipe that has a source archive listed in :term:`SRC_URI` and |
2260 | also inherit the | 2260 | also inherit the |
2261 | :ref:`autotools <ref-classes-autotools>` class, | 2261 | :ref:`autotools <ref-classes-autotools>` class, |
2262 | which contains the definitions of all the steps needed to build an | 2262 | which contains the definitions of all the steps needed to build an |
@@ -2275,7 +2275,7 @@ Following is one example: (``hello_2.3.bb``) | |||
2275 | 2275 | ||
2276 | inherit autotools gettext | 2276 | inherit autotools gettext |
2277 | 2277 | ||
2278 | The variable ``LIC_FILES_CHKSUM`` is used to track source license | 2278 | The variable :term:`LIC_FILES_CHKSUM` is used to track source license |
2279 | changes as described in the | 2279 | changes as described in the |
2280 | ":ref:`dev-manual/common-tasks:tracking license changes`" section in | 2280 | ":ref:`dev-manual/common-tasks:tracking license changes`" section in |
2281 | the Yocto Project Overview and Concepts Manual. You can quickly create | 2281 | the Yocto Project Overview and Concepts Manual. You can quickly create |
@@ -2285,7 +2285,7 @@ Makefile-Based Package | |||
2285 | ~~~~~~~~~~~~~~~~~~~~~~ | 2285 | ~~~~~~~~~~~~~~~~~~~~~~ |
2286 | 2286 | ||
2287 | Applications that use GNU ``make`` also require a recipe that has the | 2287 | Applications that use GNU ``make`` also require a recipe that has the |
2288 | source archive listed in ``SRC_URI``. You do not need to add a | 2288 | source archive listed in :term:`SRC_URI`. You do not need to add a |
2289 | ``do_compile`` step since by default BitBake starts the ``make`` command | 2289 | ``do_compile`` step since by default BitBake starts the ``make`` command |
2290 | to compile the application. If you need additional ``make`` options, you | 2290 | to compile the application. If you need additional ``make`` options, you |
2291 | should store them in the | 2291 | should store them in the |
@@ -2297,7 +2297,7 @@ Otherwise, BitBake runs an empty ``do_install`` task by default. | |||
2297 | 2297 | ||
2298 | Some applications might require extra parameters to be passed to the | 2298 | Some applications might require extra parameters to be passed to the |
2299 | compiler. For example, the application might need an additional header | 2299 | compiler. For example, the application might need an additional header |
2300 | path. You can accomplish this by adding to the ``CFLAGS`` variable. The | 2300 | path. You can accomplish this by adding to the :term:`CFLAGS` variable. The |
2301 | following example shows this:: | 2301 | following example shows this:: |
2302 | 2302 | ||
2303 | CFLAGS_prepend = "-I ${S}/include " | 2303 | CFLAGS_prepend = "-I ${S}/include " |
@@ -2341,7 +2341,7 @@ In the following example, ``mtd-utils`` is a makefile-based package:: | |||
2341 | Splitting an Application into Multiple Packages | 2341 | Splitting an Application into Multiple Packages |
2342 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 2342 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
2343 | 2343 | ||
2344 | You can use the variables ``PACKAGES`` and ``FILES`` to split an | 2344 | You can use the variables :term:`PACKAGES` and :term:`FILES` to split an |
2345 | application into multiple packages. | 2345 | application into multiple packages. |
2346 | 2346 | ||
2347 | Following is an example that uses the ``libxpm`` recipe. By default, | 2347 | Following is an example that uses the ``libxpm`` recipe. By default, |
@@ -2365,12 +2365,12 @@ into separate packages:: | |||
2365 | 2365 | ||
2366 | In the previous example, we want to ship the ``sxpm`` and ``cxpm`` | 2366 | In the previous example, we want to ship the ``sxpm`` and ``cxpm`` |
2367 | binaries in separate packages. Since ``bindir`` would be packaged into | 2367 | binaries in separate packages. Since ``bindir`` would be packaged into |
2368 | the main ``PN`` package by default, we prepend the ``PACKAGES`` variable | 2368 | the main :term:`PN` package by default, we prepend the :term:`PACKAGES` variable |
2369 | so additional package names are added to the start of list. This results | 2369 | so additional package names are added to the start of list. This results |
2370 | in the extra ``FILES_*`` variables then containing information that | 2370 | in the extra ``FILES_*`` variables then containing information that |
2371 | define which files and directories go into which packages. Files | 2371 | define which files and directories go into which packages. Files |
2372 | included by earlier packages are skipped by latter packages. Thus, the | 2372 | included by earlier packages are skipped by latter packages. Thus, the |
2373 | main ``PN`` package does not include the above listed files. | 2373 | main :term:`PN` package does not include the above listed files. |
2374 | 2374 | ||
2375 | Packaging Externally Produced Binaries | 2375 | Packaging Externally Produced Binaries |
2376 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 2376 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
@@ -2415,12 +2415,12 @@ Reference Manual's variable glossary. | |||
2415 | - Using :term:`DEPENDS` is a good | 2415 | - Using :term:`DEPENDS` is a good |
2416 | idea even for components distributed in binary form, and is often | 2416 | idea even for components distributed in binary form, and is often |
2417 | necessary for shared libraries. For a shared library, listing the | 2417 | necessary for shared libraries. For a shared library, listing the |
2418 | library dependencies in ``DEPENDS`` makes sure that the libraries | 2418 | library dependencies in :term:`DEPENDS` makes sure that the libraries |
2419 | are available in the staging sysroot when other recipes link | 2419 | are available in the staging sysroot when other recipes link |
2420 | against the library, which might be necessary for successful | 2420 | against the library, which might be necessary for successful |
2421 | linking. | 2421 | linking. |
2422 | 2422 | ||
2423 | - Using ``DEPENDS`` also allows runtime dependencies between | 2423 | - Using :term:`DEPENDS` also allows runtime dependencies between |
2424 | packages to be added automatically. See the | 2424 | packages to be added automatically. See the |
2425 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" | 2425 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" |
2426 | section in the Yocto Project Overview and Concepts Manual for more | 2426 | section in the Yocto Project Overview and Concepts Manual for more |
@@ -2747,7 +2747,7 @@ file or include from a lower-level configuration file are as follows: | |||
2747 | 2747 | ||
2748 | - ``PREFERRED_PROVIDER_virtual/kernel`` | 2748 | - ``PREFERRED_PROVIDER_virtual/kernel`` |
2749 | 2749 | ||
2750 | - ``MACHINE_FEATURES`` (e.g. "apm screen wifi") | 2750 | - :term:`MACHINE_FEATURES` (e.g. "apm screen wifi") |
2751 | 2751 | ||
2752 | You might also need these variables: | 2752 | You might also need these variables: |
2753 | 2753 | ||
@@ -2755,7 +2755,7 @@ You might also need these variables: | |||
2755 | 2755 | ||
2756 | - ``KERNEL_IMAGETYPE`` (e.g. "zImage") | 2756 | - ``KERNEL_IMAGETYPE`` (e.g. "zImage") |
2757 | 2757 | ||
2758 | - ``IMAGE_FSTYPES`` (e.g. "tar.gz jffs2") | 2758 | - :term:`IMAGE_FSTYPES` (e.g. "tar.gz jffs2") |
2759 | 2759 | ||
2760 | You can find full details on these variables in the reference section. | 2760 | You can find full details on these variables in the reference section. |
2761 | You can leverage existing machine ``.conf`` files from | 2761 | You can leverage existing machine ``.conf`` files from |
@@ -2771,8 +2771,8 @@ examples in the Source Directory at ``meta/recipes-kernel/linux`` that | |||
2771 | you can use as references. | 2771 | you can use as references. |
2772 | 2772 | ||
2773 | If you are creating a new kernel recipe, normal recipe-writing rules | 2773 | If you are creating a new kernel recipe, normal recipe-writing rules |
2774 | apply for setting up a ``SRC_URI``. Thus, you need to specify any | 2774 | apply for setting up a :term:`SRC_URI`. Thus, you need to specify any |
2775 | necessary patches and set ``S`` to point at the source code. You need to | 2775 | necessary patches and set :term:`S` to point at the source code. You need to |
2776 | create a ``do_configure`` task that configures the unpacked kernel with | 2776 | create a ``do_configure`` task that configures the unpacked kernel with |
2777 | a ``defconfig`` file. You can do this by using a ``make defconfig`` | 2777 | a ``defconfig`` file. You can do this by using a ``make defconfig`` |
2778 | command or, more commonly, by copying in a suitable ``defconfig`` file | 2778 | command or, more commonly, by copying in a suitable ``defconfig`` file |
@@ -2785,8 +2785,8 @@ If you are extending an existing kernel recipe, it is usually a matter | |||
2785 | of adding a suitable ``defconfig`` file. The file needs to be added into | 2785 | of adding a suitable ``defconfig`` file. The file needs to be added into |
2786 | a location similar to ``defconfig`` files used for other machines in a | 2786 | a location similar to ``defconfig`` files used for other machines in a |
2787 | given kernel recipe. A possible way to do this is by listing the file in | 2787 | given kernel recipe. A possible way to do this is by listing the file in |
2788 | the ``SRC_URI`` and adding the machine to the expression in | 2788 | the :term:`SRC_URI` and adding the machine to the expression in |
2789 | ``COMPATIBLE_MACHINE``:: | 2789 | :term:`COMPATIBLE_MACHINE`:: |
2790 | 2790 | ||
2791 | COMPATIBLE_MACHINE = '(qemux86|qemumips)' | 2791 | COMPATIBLE_MACHINE = '(qemux86|qemumips)' |
2792 | 2792 | ||
@@ -3178,9 +3178,9 @@ To manually upgrade recipe versions, follow these general steps: | |||
3178 | 1. *Change the Version:* Rename the recipe such that the version (i.e. | 3178 | 1. *Change the Version:* Rename the recipe such that the version (i.e. |
3179 | the :term:`PV` part of the recipe name) | 3179 | the :term:`PV` part of the recipe name) |
3180 | changes appropriately. If the version is not part of the recipe name, | 3180 | changes appropriately. If the version is not part of the recipe name, |
3181 | change the value as it is set for ``PV`` within the recipe itself. | 3181 | change the value as it is set for :term:`PV` within the recipe itself. |
3182 | 3182 | ||
3183 | 2. *Update* ``SRCREV`` *if Needed*: If the source code your recipe builds | 3183 | 2. *Update* :term:`SRCREV` *if Needed*: If the source code your recipe builds |
3184 | is fetched from Git or some other version control system, update | 3184 | is fetched from Git or some other version control system, update |
3185 | :term:`SRCREV` to point to the | 3185 | :term:`SRCREV` to point to the |
3186 | commit hash that matches the new version. | 3186 | commit hash that matches the new version. |
@@ -3241,15 +3241,15 @@ patches. | |||
3241 | During a build, the unpacked temporary source code used by recipes to | 3241 | During a build, the unpacked temporary source code used by recipes to |
3242 | build packages is available in the Build Directory as defined by the | 3242 | build packages is available in the Build Directory as defined by the |
3243 | :term:`S` variable. Below is the default | 3243 | :term:`S` variable. Below is the default |
3244 | value for the ``S`` variable as defined in the | 3244 | value for the :term:`S` variable as defined in the |
3245 | ``meta/conf/bitbake.conf`` configuration file in the | 3245 | ``meta/conf/bitbake.conf`` configuration file in the |
3246 | :term:`Source Directory`:: | 3246 | :term:`Source Directory`:: |
3247 | 3247 | ||
3248 | S = "${WORKDIR}/${BP}" | 3248 | S = "${WORKDIR}/${BP}" |
3249 | 3249 | ||
3250 | You should be aware that many recipes override the | 3250 | You should be aware that many recipes override the |
3251 | ``S`` variable. For example, recipes that fetch their source from Git | 3251 | :term:`S` variable. For example, recipes that fetch their source from Git |
3252 | usually set ``S`` to ``${WORKDIR}/git``. | 3252 | usually set :term:`S` to ``${WORKDIR}/git``. |
3253 | 3253 | ||
3254 | .. note:: | 3254 | .. note:: |
3255 | 3255 | ||
@@ -3369,13 +3369,13 @@ Follow these general steps: | |||
3369 | ``file2.c``, and ``file3.c`` files. | 3369 | ``file2.c``, and ``file3.c`` files. |
3370 | 3370 | ||
3371 | You can find the resulting patch file in the ``patches/`` | 3371 | You can find the resulting patch file in the ``patches/`` |
3372 | subdirectory of the source (``S``) directory. | 3372 | subdirectory of the source (:term:`S`) directory. |
3373 | 3373 | ||
3374 | 8. *Copy the Patch File:* For simplicity, copy the patch file into a | 3374 | 8. *Copy the Patch File:* For simplicity, copy the patch file into a |
3375 | directory named ``files``, which you can create in the same directory | 3375 | directory named ``files``, which you can create in the same directory |
3376 | that holds the recipe (``.bb``) file or the append (``.bbappend``) | 3376 | that holds the recipe (``.bb``) file or the append (``.bbappend``) |
3377 | file. Placing the patch here guarantees that the OpenEmbedded build | 3377 | file. Placing the patch here guarantees that the OpenEmbedded build |
3378 | system will find the patch. Next, add the patch into the ``SRC_URI`` | 3378 | system will find the patch. Next, add the patch into the :term:`SRC_URI` |
3379 | of the recipe. Here is an example:: | 3379 | of the recipe. Here is an example:: |
3380 | 3380 | ||
3381 | SRC_URI += "file://my_changes.patch" | 3381 | SRC_URI += "file://my_changes.patch" |
@@ -3454,7 +3454,7 @@ terminal window. | |||
3454 | use the full compiler name such as ``arm-poky-linux-gnueabi-gcc`` | 3454 | use the full compiler name such as ``arm-poky-linux-gnueabi-gcc`` |
3455 | instead of just using ``gcc``. The same applies to other | 3455 | instead of just using ``gcc``. The same applies to other |
3456 | applications such as ``binutils``, ``libtool`` and so forth. | 3456 | applications such as ``binutils``, ``libtool`` and so forth. |
3457 | BitBake sets up environment variables such as ``CC`` to assist | 3457 | BitBake sets up environment variables such as :term:`CC` to assist |
3458 | applications, such as ``make`` to find the correct tools. | 3458 | applications, such as ``make`` to find the correct tools. |
3459 | 3459 | ||
3460 | - It is also worth noting that ``devshell`` still works over X11 | 3460 | - It is also worth noting that ``devshell`` still works over X11 |
@@ -3573,7 +3573,7 @@ The following figure and list overviews the build process: | |||
3573 | ``conf/local.conf`` configuration file, which is found in the Build | 3573 | ``conf/local.conf`` configuration file, which is found in the Build |
3574 | Directory, is set up how you want it. This file defines many aspects | 3574 | Directory, is set up how you want it. This file defines many aspects |
3575 | of the build environment including the target machine architecture | 3575 | of the build environment including the target machine architecture |
3576 | through the ``MACHINE`` variable, the packaging format used during | 3576 | through the :term:`MACHINE` variable, the packaging format used during |
3577 | the build | 3577 | the build |
3578 | (:term:`PACKAGE_CLASSES`), | 3578 | (:term:`PACKAGE_CLASSES`), |
3579 | and a centralized tarball download directory through the | 3579 | and a centralized tarball download directory through the |
@@ -3646,7 +3646,7 @@ Follow these steps to set up and execute multiple configuration builds: | |||
3646 | consider a scenario with two different multiconfigs for the same | 3646 | consider a scenario with two different multiconfigs for the same |
3647 | :term:`MACHINE`: "qemux86" built | 3647 | :term:`MACHINE`: "qemux86" built |
3648 | for two distributions such as "poky" and "poky-lsb". In this case, | 3648 | for two distributions such as "poky" and "poky-lsb". In this case, |
3649 | you might want to use the same ``TMPDIR``. | 3649 | you might want to use the same :term:`TMPDIR`. |
3650 | 3650 | ||
3651 | Here is an example showing the minimal statements needed in a | 3651 | Here is an example showing the minimal statements needed in a |
3652 | configuration file for a "qemux86" target whose temporary build | 3652 | configuration file for a "qemux86" target whose temporary build |
@@ -3663,7 +3663,7 @@ Follow these steps to set up and execute multiple configuration builds: | |||
3663 | .. image:: figures/multiconfig_files.png | 3663 | .. image:: figures/multiconfig_files.png |
3664 | :align: center | 3664 | :align: center |
3665 | 3665 | ||
3666 | The reason for this required file hierarchy is because the ``BBPATH`` | 3666 | The reason for this required file hierarchy is because the :term:`BBPATH` |
3667 | variable is not constructed until the layers are parsed. | 3667 | variable is not constructed until the layers are parsed. |
3668 | Consequently, using the configuration file as a pre-configuration | 3668 | Consequently, using the configuration file as a pre-configuration |
3669 | file is not possible unless it is located in the current working | 3669 | file is not possible unless it is located in the current working |
@@ -3674,7 +3674,7 @@ Follow these steps to set up and execute multiple configuration builds: | |||
3674 | :term:`BBMULTICONFIG` | 3674 | :term:`BBMULTICONFIG` |
3675 | variable in your ``conf/local.conf`` configuration file to specify | 3675 | variable in your ``conf/local.conf`` configuration file to specify |
3676 | each multiconfig. Continuing with the example from the previous | 3676 | each multiconfig. Continuing with the example from the previous |
3677 | figure, the ``BBMULTICONFIG`` variable needs to enable two | 3677 | figure, the :term:`BBMULTICONFIG` variable needs to enable two |
3678 | multiconfigs: "x86" and "arm" by specifying each configuration file:: | 3678 | multiconfigs: "x86" and "arm" by specifying each configuration file:: |
3679 | 3679 | ||
3680 | BBMULTICONFIG = "x86 arm" | 3680 | BBMULTICONFIG = "x86 arm" |
@@ -3708,7 +3708,7 @@ Follow these steps to set up and execute multiple configuration builds: | |||
3708 | Support for multiple configuration builds in the Yocto Project &DISTRO; | 3708 | Support for multiple configuration builds in the Yocto Project &DISTRO; |
3709 | (&DISTRO_NAME;) Release does not include Shared State (sstate) | 3709 | (&DISTRO_NAME;) Release does not include Shared State (sstate) |
3710 | optimizations. Consequently, if a build uses the same object twice | 3710 | optimizations. Consequently, if a build uses the same object twice |
3711 | in, for example, two different ``TMPDIR`` | 3711 | in, for example, two different :term:`TMPDIR` |
3712 | directories, the build either loads from an existing sstate cache for | 3712 | directories, the build either loads from an existing sstate cache for |
3713 | that build at the start or builds the object fresh. | 3713 | that build at the start or builds the object fresh. |
3714 | 3714 | ||
@@ -3806,7 +3806,7 @@ Follow these steps to create an initramfs image: | |||
3806 | recipe and the initramfs recipe should the initramfs image include | 3806 | recipe and the initramfs recipe should the initramfs image include |
3807 | kernel modules. | 3807 | kernel modules. |
3808 | 3808 | ||
3809 | Setting the ``INITRAMFS_IMAGE_BUNDLE`` flag causes the initramfs | 3809 | Setting the :term:`INITRAMFS_IMAGE_BUNDLE` flag causes the initramfs |
3810 | image to be unpacked into the ``${B}/usr/`` directory. The unpacked | 3810 | image to be unpacked into the ``${B}/usr/`` directory. The unpacked |
3811 | initramfs image is then passed to the kernel's ``Makefile`` using the | 3811 | initramfs image is then passed to the kernel's ``Makefile`` using the |
3812 | :term:`CONFIG_INITRAMFS_SOURCE` | 3812 | :term:`CONFIG_INITRAMFS_SOURCE` |
@@ -3828,7 +3828,7 @@ Follow these steps to create an initramfs image: | |||
3828 | :term:`PACKAGE_INSTALL` | 3828 | :term:`PACKAGE_INSTALL` |
3829 | rather than | 3829 | rather than |
3830 | :term:`IMAGE_INSTALL`. | 3830 | :term:`IMAGE_INSTALL`. |
3831 | ``PACKAGE_INSTALL`` gives more direct control of what is added to the | 3831 | :term:`PACKAGE_INSTALL` gives more direct control of what is added to the |
3832 | image as compared to the defaults you might not necessarily want that | 3832 | image as compared to the defaults you might not necessarily want that |
3833 | are set by the :ref:`image <ref-classes-image>` | 3833 | are set by the :ref:`image <ref-classes-image>` |
3834 | or :ref:`core-image <ref-classes-core-image>` | 3834 | or :ref:`core-image <ref-classes-core-image>` |
@@ -3912,7 +3912,7 @@ your own distribution that are likely modeled after ``poky-tiny``. | |||
3912 | 3912 | ||
3913 | .. note:: | 3913 | .. note:: |
3914 | 3914 | ||
3915 | To use ``poky-tiny`` in your build, set the ``DISTRO`` variable in your | 3915 | To use ``poky-tiny`` in your build, set the :term:`DISTRO` variable in your |
3916 | ``local.conf`` file to "poky-tiny" as described in the | 3916 | ``local.conf`` file to "poky-tiny" as described in the |
3917 | ":ref:`dev-manual/common-tasks:creating your own distribution`" | 3917 | ":ref:`dev-manual/common-tasks:creating your own distribution`" |
3918 | section. | 3918 | section. |
@@ -4156,17 +4156,17 @@ your tunings to best consider build times and package feed maintenance. | |||
4156 | :term:`TMPDIR` across builds. The | 4156 | :term:`TMPDIR` across builds. The |
4157 | Yocto Project supports switching between different | 4157 | Yocto Project supports switching between different |
4158 | :term:`MACHINE` values in the same | 4158 | :term:`MACHINE` values in the same |
4159 | ``TMPDIR``. This practice is well supported and regularly used by | 4159 | :term:`TMPDIR`. This practice is well supported and regularly used by |
4160 | developers when building for multiple machines. When you use the same | 4160 | developers when building for multiple machines. When you use the same |
4161 | ``TMPDIR`` for multiple machine builds, the OpenEmbedded build system | 4161 | :term:`TMPDIR` for multiple machine builds, the OpenEmbedded build system |
4162 | can reuse the existing native and often cross-recipes for multiple | 4162 | can reuse the existing native and often cross-recipes for multiple |
4163 | machines. Thus, build time decreases. | 4163 | machines. Thus, build time decreases. |
4164 | 4164 | ||
4165 | .. note:: | 4165 | .. note:: |
4166 | 4166 | ||
4167 | If :term:`DISTRO` settings change or fundamental configuration settings | 4167 | If :term:`DISTRO` settings change or fundamental configuration settings |
4168 | such as the filesystem layout, you need to work with a clean ``TMPDIR``. | 4168 | such as the filesystem layout, you need to work with a clean :term:`TMPDIR`. |
4169 | Sharing ``TMPDIR`` under these circumstances might work but since it is | 4169 | Sharing :term:`TMPDIR` under these circumstances might work but since it is |
4170 | not guaranteed, you should use a clean ``TMPDIR``. | 4170 | not guaranteed, you should use a clean ``TMPDIR``. |
4171 | 4171 | ||
4172 | - *Enable the Appropriate Package Architecture:* By default, the | 4172 | - *Enable the Appropriate Package Architecture:* By default, the |
@@ -4304,7 +4304,7 @@ your ``local.conf`` file:: | |||
4304 | EXTERNALSRC_pn-myrecipe = "path-to-your-source-tree" | 4304 | EXTERNALSRC_pn-myrecipe = "path-to-your-source-tree" |
4305 | 4305 | ||
4306 | This next example shows how to accomplish the same thing by setting | 4306 | This next example shows how to accomplish the same thing by setting |
4307 | ``EXTERNALSRC`` in the recipe itself or in the recipe's append file:: | 4307 | :term:`EXTERNALSRC` in the recipe itself or in the recipe's append file:: |
4308 | 4308 | ||
4309 | EXTERNALSRC = "path" | 4309 | EXTERNALSRC = "path" |
4310 | EXTERNALSRC_BUILD = "path" | 4310 | EXTERNALSRC_BUILD = "path" |
@@ -4340,7 +4340,7 @@ Follow these steps to populate your Downloads directory: | |||
4340 | 1. *Create a Clean Downloads Directory:* Start with an empty downloads | 4340 | 1. *Create a Clean Downloads Directory:* Start with an empty downloads |
4341 | directory (:term:`DL_DIR`). You | 4341 | directory (:term:`DL_DIR`). You |
4342 | start with an empty downloads directory by either removing the files | 4342 | start with an empty downloads directory by either removing the files |
4343 | in the existing directory or by setting ``DL_DIR`` to point to either | 4343 | in the existing directory or by setting :term:`DL_DIR` to point to either |
4344 | an empty location or one that does not yet exist. | 4344 | an empty location or one that does not yet exist. |
4345 | 4345 | ||
4346 | 2. *Generate Tarballs of the Source Git Repositories:* Edit your | 4346 | 2. *Generate Tarballs of the Source Git Repositories:* Edit your |
@@ -4351,7 +4351,7 @@ Follow these steps to populate your Downloads directory: | |||
4351 | 4351 | ||
4352 | During | 4352 | During |
4353 | the fetch process in the next step, BitBake gathers the source files | 4353 | the fetch process in the next step, BitBake gathers the source files |
4354 | and creates tarballs in the directory pointed to by ``DL_DIR``. See | 4354 | and creates tarballs in the directory pointed to by :term:`DL_DIR`. See |
4355 | the | 4355 | the |
4356 | :term:`BB_GENERATE_MIRROR_TARBALLS` | 4356 | :term:`BB_GENERATE_MIRROR_TARBALLS` |
4357 | variable for more information. | 4357 | variable for more information. |
@@ -4394,7 +4394,7 @@ directory: | |||
4394 | 4394 | ||
4395 | The ``SOURCE_MIRROR_URL`` and ``own-mirror`` | 4395 | The ``SOURCE_MIRROR_URL`` and ``own-mirror`` |
4396 | class set up the system to use the downloads directory as your "own | 4396 | class set up the system to use the downloads directory as your "own |
4397 | mirror". Using the ``BB_NO_NETWORK`` variable makes sure that | 4397 | mirror". Using the :term:`BB_NO_NETWORK` variable makes sure that |
4398 | BitBake's fetching process in step 3 stays local, which means files | 4398 | BitBake's fetching process in step 3 stays local, which means files |
4399 | from your "own-mirror" are used. | 4399 | from your "own-mirror" are used. |
4400 | 4400 | ||
@@ -4420,27 +4420,27 @@ directory: | |||
4420 | 4420 | ||
4421 | SRCREV = "${AUTOREV}" | 4421 | SRCREV = "${AUTOREV}" |
4422 | 4422 | ||
4423 | When a recipe sets ``SRCREV`` to | 4423 | When a recipe sets :term:`SRCREV` to |
4424 | ``${AUTOREV}``, the build system accesses the network in an | 4424 | ``${AUTOREV}``, the build system accesses the network in an |
4425 | attempt to determine the latest version of software from the SCM. | 4425 | attempt to determine the latest version of software from the SCM. |
4426 | Typically, recipes that use ``AUTOREV`` are custom or modified | 4426 | Typically, recipes that use :term:`AUTOREV` are custom or modified |
4427 | recipes. Recipes that reside in public repositories usually do not | 4427 | recipes. Recipes that reside in public repositories usually do not |
4428 | use ``AUTOREV``. | 4428 | use :term:`AUTOREV`. |
4429 | 4429 | ||
4430 | If you do have recipes that use ``AUTOREV``, you can take steps to | 4430 | If you do have recipes that use :term:`AUTOREV`, you can take steps to |
4431 | still use the recipes in an offline build. Do the following: | 4431 | still use the recipes in an offline build. Do the following: |
4432 | 4432 | ||
4433 | 1. Use a configuration generated by enabling :ref:`build | 4433 | 1. Use a configuration generated by enabling :ref:`build |
4434 | history <dev-manual/common-tasks:maintaining build output quality>`. | 4434 | history <dev-manual/common-tasks:maintaining build output quality>`. |
4435 | 4435 | ||
4436 | 2. Use the ``buildhistory-collect-srcrevs`` command to collect the | 4436 | 2. Use the ``buildhistory-collect-srcrevs`` command to collect the |
4437 | stored ``SRCREV`` values from the build's history. For more | 4437 | stored :term:`SRCREV` values from the build's history. For more |
4438 | information on collecting these values, see the | 4438 | information on collecting these values, see the |
4439 | ":ref:`dev-manual/common-tasks:build history package information`" | 4439 | ":ref:`dev-manual/common-tasks:build history package information`" |
4440 | section. | 4440 | section. |
4441 | 4441 | ||
4442 | 3. Once you have the correct source revisions, you can modify | 4442 | 3. Once you have the correct source revisions, you can modify |
4443 | those recipes to set ``SRCREV`` to specific versions of the | 4443 | those recipes to set :term:`SRCREV` to specific versions of the |
4444 | software. | 4444 | software. |
4445 | 4445 | ||
4446 | Speeding Up a Build | 4446 | Speeding Up a Build |
@@ -4580,7 +4580,7 @@ the built library. | |||
4580 | The :term:`PACKAGES` and | 4580 | The :term:`PACKAGES` and |
4581 | :term:`FILES_* <FILES>` variables in the | 4581 | :term:`FILES_* <FILES>` variables in the |
4582 | ``meta/conf/bitbake.conf`` configuration file define how files installed | 4582 | ``meta/conf/bitbake.conf`` configuration file define how files installed |
4583 | by the ``do_install`` task are packaged. By default, the ``PACKAGES`` | 4583 | by the ``do_install`` task are packaged. By default, the :term:`PACKAGES` |
4584 | variable includes ``${PN}-staticdev``, which represents all static | 4584 | variable includes ``${PN}-staticdev``, which represents all static |
4585 | library files. | 4585 | library files. |
4586 | 4586 | ||
@@ -5943,7 +5943,7 @@ system to make your images more secure: | |||
5943 | EXTRA_IMAGE_FEATURES = "debug-tweaks" | 5943 | EXTRA_IMAGE_FEATURES = "debug-tweaks" |
5944 | 5944 | ||
5945 | To disable that feature, simply comment out that line in your | 5945 | To disable that feature, simply comment out that line in your |
5946 | ``local.conf`` file, or make sure ``IMAGE_FEATURES`` does not contain | 5946 | ``local.conf`` file, or make sure :term:`IMAGE_FEATURES` does not contain |
5947 | "debug-tweaks" before producing your final image. Among other things, | 5947 | "debug-tweaks" before producing your final image. Among other things, |
5948 | leaving this in place sets the root password as blank, which makes | 5948 | leaving this in place sets the root password as blank, which makes |
5949 | logging in for debugging or inspection easy during development but | 5949 | logging in for debugging or inspection easy during development but |
@@ -6248,20 +6248,20 @@ the following: | |||
6248 | .. note:: | 6248 | .. note:: |
6249 | 6249 | ||
6250 | Technically, a third component, the "epoch" (i.e. :term:`PE`) is involved | 6250 | Technically, a third component, the "epoch" (i.e. :term:`PE`) is involved |
6251 | but this discussion for the most part ignores ``PE``. | 6251 | but this discussion for the most part ignores :term:`PE`. |
6252 | 6252 | ||
6253 | The version and revision are taken from the | 6253 | The version and revision are taken from the |
6254 | :term:`PV` and | 6254 | :term:`PV` and |
6255 | :term:`PR` variables, respectively. | 6255 | :term:`PR` variables, respectively. |
6256 | 6256 | ||
6257 | - ``PV``: The recipe version. ``PV`` represents the version of the | 6257 | - :term:`PV`: The recipe version. :term:`PV` represents the version of the |
6258 | software being packaged. Do not confuse ``PV`` with the binary | 6258 | software being packaged. Do not confuse :term:`PV` with the binary |
6259 | package version. | 6259 | package version. |
6260 | 6260 | ||
6261 | - ``PR``: The recipe revision. | 6261 | - ``PR``: The recipe revision. |
6262 | 6262 | ||
6263 | - :term:`SRCPV`: The OpenEmbedded | 6263 | - :term:`SRCPV`: The OpenEmbedded |
6264 | build system uses this string to help define the value of ``PV`` when | 6264 | build system uses this string to help define the value of :term:`PV` when |
6265 | the source code revision needs to be included in it. | 6265 | the source code revision needs to be included in it. |
6266 | 6266 | ||
6267 | - :yocto_wiki:`PR Service </PR_Service>`: A | 6267 | - :yocto_wiki:`PR Service </PR_Service>`: A |
@@ -6271,12 +6271,12 @@ the following: | |||
6271 | 6271 | ||
6272 | Whenever the binary package content changes, the binary package version | 6272 | Whenever the binary package content changes, the binary package version |
6273 | must change. Changing the binary package version is accomplished by | 6273 | must change. Changing the binary package version is accomplished by |
6274 | changing or "bumping" the ``PR`` and/or ``PV`` values. Increasing these | 6274 | changing or "bumping" the :term:`PR` and/or :term:`PV` values. Increasing these |
6275 | values occurs one of two ways: | 6275 | values occurs one of two ways: |
6276 | 6276 | ||
6277 | - Automatically using a Package Revision Service (PR Service). | 6277 | - Automatically using a Package Revision Service (PR Service). |
6278 | 6278 | ||
6279 | - Manually incrementing the ``PR`` and/or ``PV`` variables. | 6279 | - Manually incrementing the :term:`PR` and/or :term:`PV` variables. |
6280 | 6280 | ||
6281 | Given a primary challenge of any build system and its users is how to | 6281 | Given a primary challenge of any build system and its users is how to |
6282 | maintain a package feed that is compatible with existing package manager | 6282 | maintain a package feed that is compatible with existing package manager |
@@ -6290,7 +6290,7 @@ package revisioning remains linear, see the | |||
6290 | section. | 6290 | section. |
6291 | 6291 | ||
6292 | The following three sections provide related information on the PR | 6292 | The following three sections provide related information on the PR |
6293 | Service, the manual method for "bumping" ``PR`` and/or ``PV``, and on | 6293 | Service, the manual method for "bumping" :term:`PR` and/or :term:`PV`, and on |
6294 | how to ensure binary package revisioning remains linear. | 6294 | how to ensure binary package revisioning remains linear. |
6295 | 6295 | ||
6296 | Working With a PR Service | 6296 | Working With a PR Service |
@@ -6320,20 +6320,20 @@ Because the OpenEmbedded build system uses | |||
6320 | unique to a given build, the build system knows when to rebuild | 6320 | unique to a given build, the build system knows when to rebuild |
6321 | packages. All the inputs into a given task are represented by a | 6321 | packages. All the inputs into a given task are represented by a |
6322 | signature, which can trigger a rebuild when different. Thus, the build | 6322 | signature, which can trigger a rebuild when different. Thus, the build |
6323 | system itself does not rely on the ``PR``, ``PV``, and ``PE`` numbers to | 6323 | system itself does not rely on the :term:`PR`, :term:`PV`, and :term:`PE` numbers to |
6324 | trigger a rebuild. The signatures, however, can be used to generate | 6324 | trigger a rebuild. The signatures, however, can be used to generate |
6325 | these values. | 6325 | these values. |
6326 | 6326 | ||
6327 | The PR Service works with both ``OEBasic`` and ``OEBasicHash`` | 6327 | The PR Service works with both ``OEBasic`` and ``OEBasicHash`` |
6328 | generators. The value of ``PR`` bumps when the checksum changes and the | 6328 | generators. The value of :term:`PR` bumps when the checksum changes and the |
6329 | different generator mechanisms change signatures under different | 6329 | different generator mechanisms change signatures under different |
6330 | circumstances. | 6330 | circumstances. |
6331 | 6331 | ||
6332 | As implemented, the build system includes values from the PR Service | 6332 | As implemented, the build system includes values from the PR Service |
6333 | into the ``PR`` field as an addition using the form "``.x``" so ``r0`` | 6333 | into the :term:`PR` field as an addition using the form "``.x``" so ``r0`` |
6334 | becomes ``r0.1``, ``r0.2`` and so forth. This scheme allows existing | 6334 | becomes ``r0.1``, ``r0.2`` and so forth. This scheme allows existing |
6335 | ``PR`` values to be used for whatever reasons, which include manual | 6335 | :term:`PR` values to be used for whatever reasons, which include manual |
6336 | ``PR`` bumps, should it be necessary. | 6336 | :term:`PR` bumps, should it be necessary. |
6337 | 6337 | ||
6338 | By default, the PR Service is not enabled or running. Thus, the packages | 6338 | By default, the PR Service is not enabled or running. Thus, the packages |
6339 | generated are just "self consistent". The build system adds and removes | 6339 | generated are just "self consistent". The build system adds and removes |
@@ -6349,7 +6349,7 @@ this scenario, you can enable a local PR Service by setting | |||
6349 | PRSERV_HOST = "localhost:0" | 6349 | PRSERV_HOST = "localhost:0" |
6350 | 6350 | ||
6351 | Once the service is started, packages will automatically | 6351 | Once the service is started, packages will automatically |
6352 | get increasing ``PR`` values and BitBake takes care of starting and | 6352 | get increasing :term:`PR` values and BitBake takes care of starting and |
6353 | stopping the server. | 6353 | stopping the server. |
6354 | 6354 | ||
6355 | If you have a more complex setup where multiple host development systems | 6355 | If you have a more complex setup where multiple host development systems |
@@ -6379,7 +6379,7 @@ history, see the | |||
6379 | 6379 | ||
6380 | .. note:: | 6380 | .. note:: |
6381 | 6381 | ||
6382 | The OpenEmbedded build system does not maintain ``PR`` information as | 6382 | The OpenEmbedded build system does not maintain :term:`PR` information as |
6383 | part of the shared state (sstate) packages. If you maintain an sstate | 6383 | part of the shared state (sstate) packages. If you maintain an sstate |
6384 | feed, it's expected that either all your building systems that | 6384 | feed, it's expected that either all your building systems that |
6385 | contribute to the sstate feed use a shared PR Service, or you do not | 6385 | contribute to the sstate feed use a shared PR Service, or you do not |
@@ -6398,27 +6398,27 @@ The alternative to setting up a PR Service is to manually "bump" the | |||
6398 | 6398 | ||
6399 | If a committed change results in changing the package output, then the | 6399 | If a committed change results in changing the package output, then the |
6400 | value of the PR variable needs to be increased (or "bumped") as part of | 6400 | value of the PR variable needs to be increased (or "bumped") as part of |
6401 | that commit. For new recipes you should add the ``PR`` variable and set | 6401 | that commit. For new recipes you should add the :term:`PR` variable and set |
6402 | its initial value equal to "r0", which is the default. Even though the | 6402 | its initial value equal to "r0", which is the default. Even though the |
6403 | default value is "r0", the practice of adding it to a new recipe makes | 6403 | default value is "r0", the practice of adding it to a new recipe makes |
6404 | it harder to forget to bump the variable when you make changes to the | 6404 | it harder to forget to bump the variable when you make changes to the |
6405 | recipe in future. | 6405 | recipe in future. |
6406 | 6406 | ||
6407 | If you are sharing a common ``.inc`` file with multiple recipes, you can | 6407 | If you are sharing a common ``.inc`` file with multiple recipes, you can |
6408 | also use the ``INC_PR`` variable to ensure that the recipes sharing the | 6408 | also use the :term:`INC_PR` variable to ensure that the recipes sharing the |
6409 | ``.inc`` file are rebuilt when the ``.inc`` file itself is changed. The | 6409 | ``.inc`` file are rebuilt when the ``.inc`` file itself is changed. The |
6410 | ``.inc`` file must set ``INC_PR`` (initially to "r0"), and all recipes | 6410 | ``.inc`` file must set :term:`INC_PR` (initially to "r0"), and all recipes |
6411 | referring to it should set ``PR`` to "${INC_PR}.0" initially, | 6411 | referring to it should set :term:`PR` to "${INC_PR}.0" initially, |
6412 | incrementing the last number when the recipe is changed. If the ``.inc`` | 6412 | incrementing the last number when the recipe is changed. If the ``.inc`` |
6413 | file is changed then its ``INC_PR`` should be incremented. | 6413 | file is changed then its :term:`INC_PR` should be incremented. |
6414 | 6414 | ||
6415 | When upgrading the version of a binary package, assuming the ``PV`` | 6415 | When upgrading the version of a binary package, assuming the :term:`PV` |
6416 | changes, the ``PR`` variable should be reset to "r0" (or "${INC_PR}.0" | 6416 | changes, the :term:`PR` variable should be reset to "r0" (or "${INC_PR}.0" |
6417 | if you are using ``INC_PR``). | 6417 | if you are using :term:`INC_PR`). |
6418 | 6418 | ||
6419 | Usually, version increases occur only to binary packages. However, if | 6419 | Usually, version increases occur only to binary packages. However, if |
6420 | for some reason ``PV`` changes but does not increase, you can increase | 6420 | for some reason :term:`PV` changes but does not increase, you can increase |
6421 | the ``PE`` variable (Package Epoch). The ``PE`` variable defaults to | 6421 | the :term:`PE` variable (Package Epoch). The :term:`PE` variable defaults to |
6422 | "0". | 6422 | "0". |
6423 | 6423 | ||
6424 | Binary package version numbering strives to follow the `Debian Version | 6424 | Binary package version numbering strives to follow the `Debian Version |
@@ -6433,20 +6433,20 @@ Automatically Incrementing a Package Version Number | |||
6433 | When fetching a repository, BitBake uses the | 6433 | When fetching a repository, BitBake uses the |
6434 | :term:`SRCREV` variable to determine | 6434 | :term:`SRCREV` variable to determine |
6435 | the specific source code revision from which to build. You set the | 6435 | the specific source code revision from which to build. You set the |
6436 | ``SRCREV`` variable to | 6436 | :term:`SRCREV` variable to |
6437 | :term:`AUTOREV` to cause the | 6437 | :term:`AUTOREV` to cause the |
6438 | OpenEmbedded build system to automatically use the latest revision of | 6438 | OpenEmbedded build system to automatically use the latest revision of |
6439 | the software:: | 6439 | the software:: |
6440 | 6440 | ||
6441 | SRCREV = "${AUTOREV}" | 6441 | SRCREV = "${AUTOREV}" |
6442 | 6442 | ||
6443 | Furthermore, you need to reference ``SRCPV`` in ``PV`` in order to | 6443 | Furthermore, you need to reference :term:`SRCPV` in :term:`PV` in order to |
6444 | automatically update the version whenever the revision of the source | 6444 | automatically update the version whenever the revision of the source |
6445 | code changes. Here is an example:: | 6445 | code changes. Here is an example:: |
6446 | 6446 | ||
6447 | PV = "1.0+git${SRCPV}" | 6447 | PV = "1.0+git${SRCPV}" |
6448 | 6448 | ||
6449 | The OpenEmbedded build system substitutes ``SRCPV`` with the following: | 6449 | The OpenEmbedded build system substitutes :term:`SRCPV` with the following: |
6450 | 6450 | ||
6451 | .. code-block:: none | 6451 | .. code-block:: none |
6452 | 6452 | ||
@@ -6479,7 +6479,7 @@ with a number. The number used depends on the state of the PR Service: | |||
6479 | 6479 | ||
6480 | In summary, the OpenEmbedded build system does not track the history of | 6480 | In summary, the OpenEmbedded build system does not track the history of |
6481 | binary package versions for this purpose. ``AUTOINC``, in this case, is | 6481 | binary package versions for this purpose. ``AUTOINC``, in this case, is |
6482 | comparable to ``PR``. If PR server is not enabled, ``AUTOINC`` in the | 6482 | comparable to :term:`PR`. If PR server is not enabled, ``AUTOINC`` in the |
6483 | package version is simply replaced by "0". If PR server is enabled, the | 6483 | package version is simply replaced by "0". If PR server is enabled, the |
6484 | build system keeps track of the package versions and bumps the number | 6484 | build system keeps track of the package versions and bumps the number |
6485 | when the package revision changes. | 6485 | when the package revision changes. |
@@ -6654,7 +6654,7 @@ ensure that any :term:`RDEPENDS` and | |||
6654 | :term:`RRECOMMENDS` on a package | 6654 | :term:`RRECOMMENDS` on a package |
6655 | name starting with the prefix are satisfied during build time. If you | 6655 | name starting with the prefix are satisfied during build time. If you |
6656 | are using ``do_split_packages`` as described in the previous section, | 6656 | are using ``do_split_packages`` as described in the previous section, |
6657 | the value you put in ``PACKAGES_DYNAMIC`` should correspond to the name | 6657 | the value you put in :term:`PACKAGES_DYNAMIC` should correspond to the name |
6658 | pattern specified in the call to ``do_split_packages``. | 6658 | pattern specified in the call to ``do_split_packages``. |
6659 | 6659 | ||
6660 | Using Runtime Package Management | 6660 | Using Runtime Package Management |
@@ -6822,7 +6822,7 @@ From within the build directory where you have built an image based on | |||
6822 | your packaging choice (i.e. the | 6822 | your packaging choice (i.e. the |
6823 | :term:`PACKAGE_CLASSES` | 6823 | :term:`PACKAGE_CLASSES` |
6824 | setting), simply start the server. The following example assumes a build | 6824 | setting), simply start the server. The following example assumes a build |
6825 | directory of ``poky/build/tmp/deploy/rpm`` and a ``PACKAGE_CLASSES`` | 6825 | directory of ``poky/build/tmp/deploy/rpm`` and a :term:`PACKAGE_CLASSES` |
6826 | setting of "package_rpm":: | 6826 | setting of "package_rpm":: |
6827 | 6827 | ||
6828 | $ cd poky/build/tmp/deploy/rpm | 6828 | $ cd poky/build/tmp/deploy/rpm |
@@ -7360,7 +7360,7 @@ command:: | |||
7360 | 7360 | ||
7361 | The | 7361 | The |
7362 | recipe this command generates is very similar to the recipe created in | 7362 | recipe this command generates is very similar to the recipe created in |
7363 | the previous section. However, the ``SRC_URI`` looks like the following:: | 7363 | the previous section. However, the :term:`SRC_URI` looks like the following:: |
7364 | 7364 | ||
7365 | SRC_URI = " \ | 7365 | SRC_URI = " \ |
7366 | git://github.com/martinaglv/cute-files.git;protocol=https \ | 7366 | git://github.com/martinaglv/cute-files.git;protocol=https \ |
@@ -7394,7 +7394,7 @@ of precedence is the same as this list: | |||
7394 | 7394 | ||
7395 | - ``PACKAGE_ADD_METADATA_<PN>`` | 7395 | - ``PACKAGE_ADD_METADATA_<PN>`` |
7396 | 7396 | ||
7397 | - ``PACKAGE_ADD_METADATA`` | 7397 | - :term:`PACKAGE_ADD_METADATA` |
7398 | 7398 | ||
7399 | `<PKGTYPE>` is a parameter and expected to be a distinct name of specific | 7399 | `<PKGTYPE>` is a parameter and expected to be a distinct name of specific |
7400 | package type: | 7400 | package type: |
@@ -7587,7 +7587,7 @@ variable defines the Device Table to use and should be set in the | |||
7587 | machine or distro configuration file. Alternatively, you can set this | 7587 | machine or distro configuration file. Alternatively, you can set this |
7588 | variable in your ``local.conf`` configuration file. | 7588 | variable in your ``local.conf`` configuration file. |
7589 | 7589 | ||
7590 | If you do not define the ``IMAGE_DEVICE_TABLES`` variable, the default | 7590 | If you do not define the :term:`IMAGE_DEVICE_TABLES` variable, the default |
7591 | ``device_table-minimal.txt`` is used:: | 7591 | ``device_table-minimal.txt`` is used:: |
7592 | 7592 | ||
7593 | IMAGE_DEVICE_TABLES = "device_table-mymachine.txt" | 7593 | IMAGE_DEVICE_TABLES = "device_table-mymachine.txt" |
@@ -7713,13 +7713,13 @@ Creating the Root Filesystem | |||
7713 | To create the read-only root filesystem, simply add the | 7713 | To create the read-only root filesystem, simply add the |
7714 | "read-only-rootfs" feature to your image, normally in one of two ways. | 7714 | "read-only-rootfs" feature to your image, normally in one of two ways. |
7715 | The first way is to add the "read-only-rootfs" image feature in the | 7715 | The first way is to add the "read-only-rootfs" image feature in the |
7716 | image's recipe file via the ``IMAGE_FEATURES`` variable:: | 7716 | image's recipe file via the :term:`IMAGE_FEATURES` variable:: |
7717 | 7717 | ||
7718 | IMAGE_FEATURES += "read-only-rootfs" | 7718 | IMAGE_FEATURES += "read-only-rootfs" |
7719 | 7719 | ||
7720 | As an alternative, you can add the same feature | 7720 | As an alternative, you can add the same feature |
7721 | from within your build directory's ``local.conf`` file with the | 7721 | from within your build directory's ``local.conf`` file with the |
7722 | associated ``EXTRA_IMAGE_FEATURES`` variable, as in:: | 7722 | associated :term:`EXTRA_IMAGE_FEATURES` variable, as in:: |
7723 | 7723 | ||
7724 | EXTRA_IMAGE_FEATURES = "read-only-rootfs" | 7724 | EXTRA_IMAGE_FEATURES = "read-only-rootfs" |
7725 | 7725 | ||
@@ -7813,7 +7813,7 @@ Enabling and Disabling Build History | |||
7813 | ------------------------------------ | 7813 | ------------------------------------ |
7814 | 7814 | ||
7815 | Build history is disabled by default. To enable it, add the following | 7815 | Build history is disabled by default. To enable it, add the following |
7816 | ``INHERIT`` statement and set the | 7816 | :term:`INHERIT` statement and set the |
7817 | :term:`BUILDHISTORY_COMMIT` | 7817 | :term:`BUILDHISTORY_COMMIT` |
7818 | variable to "1" at the end of your ``conf/local.conf`` file found in the | 7818 | variable to "1" at the end of your ``conf/local.conf`` file found in the |
7819 | :term:`Build Directory`:: | 7819 | :term:`Build Directory`:: |
@@ -7913,10 +7913,10 @@ example assuming | |||
7913 | 7913 | ||
7914 | You can use the | 7914 | You can use the |
7915 | ``buildhistory-collect-srcrevs`` command with the ``-a`` option to | 7915 | ``buildhistory-collect-srcrevs`` command with the ``-a`` option to |
7916 | collect the stored ``SRCREV`` values from build history and report them | 7916 | collect the stored :term:`SRCREV` values from build history and report them |
7917 | in a format suitable for use in global configuration (e.g., | 7917 | in a format suitable for use in global configuration (e.g., |
7918 | ``local.conf`` or a distro include file) to override floating | 7918 | ``local.conf`` or a distro include file) to override floating |
7919 | ``AUTOREV`` values to a fixed set of revisions. Here is some example | 7919 | :term:`AUTOREV` values to a fixed set of revisions. Here is some example |
7920 | output from this command:: | 7920 | output from this command:: |
7921 | 7921 | ||
7922 | $ buildhistory-collect-srcrevs -a | 7922 | $ buildhistory-collect-srcrevs -a |
@@ -7945,7 +7945,7 @@ output from this command:: | |||
7945 | 7945 | ||
7946 | Here are some notes on using the ``buildhistory-collect-srcrevs`` command: | 7946 | Here are some notes on using the ``buildhistory-collect-srcrevs`` command: |
7947 | 7947 | ||
7948 | - By default, only values where the ``SRCREV`` was not hardcoded | 7948 | - By default, only values where the :term:`SRCREV` was not hardcoded |
7949 | (usually when ``AUTOREV`` is used) are reported. Use the ``-a`` | 7949 | (usually when ``AUTOREV`` is used) are reported. Use the ``-a`` |
7950 | option to see all ``SRCREV`` values. | 7950 | option to see all ``SRCREV`` values. |
7951 | 7951 | ||
@@ -8276,7 +8276,7 @@ Once you start running the tests, the following happens: | |||
8276 | tests run. The full boot log is written to | 8276 | tests run. The full boot log is written to |
8277 | ``${WORKDIR}/testimage/qemu_boot_log``. | 8277 | ``${WORKDIR}/testimage/qemu_boot_log``. |
8278 | 8278 | ||
8279 | 5. Each test module loads in the order found in ``TEST_SUITES``. You can | 8279 | 5. Each test module loads in the order found in :term:`TEST_SUITES`. You can |
8280 | find the full output of the commands run over SSH in | 8280 | find the full output of the commands run over SSH in |
8281 | ``${WORKDIR}/testimgage/ssh_target_log``. | 8281 | ``${WORKDIR}/testimgage/ssh_target_log``. |
8282 | 8282 | ||
@@ -8310,7 +8310,7 @@ addresses written into the image, or set the image to use DHCP and have | |||
8310 | your DHCP server on the test network assign a known IP address based on | 8310 | your DHCP server on the test network assign a known IP address based on |
8311 | the MAC address of the device. | 8311 | the MAC address of the device. |
8312 | 8312 | ||
8313 | In order to run tests on hardware, you need to set ``TEST_TARGET`` to an | 8313 | In order to run tests on hardware, you need to set :term:`TEST_TARGET` to an |
8314 | appropriate value. For QEMU, you do not have to change anything, the | 8314 | appropriate value. For QEMU, you do not have to change anything, the |
8315 | default value is "qemu". For running tests on hardware, the following | 8315 | default value is "qemu". For running tests on hardware, the following |
8316 | options are available: | 8316 | options are available: |
@@ -8359,14 +8359,14 @@ options are available: | |||
8359 | Selecting SystemdbootTarget | 8359 | Selecting SystemdbootTarget |
8360 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 8360 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
8361 | 8361 | ||
8362 | If you did not set ``TEST_TARGET`` to "SystemdbootTarget", then you do | 8362 | If you did not set :term:`TEST_TARGET` to "SystemdbootTarget", then you do |
8363 | not need any information in this section. You can skip down to the | 8363 | not need any information in this section. You can skip down to the |
8364 | ":ref:`dev-manual/common-tasks:running tests`" section. | 8364 | ":ref:`dev-manual/common-tasks:running tests`" section. |
8365 | 8365 | ||
8366 | If you did set ``TEST_TARGET`` to "SystemdbootTarget", you also need to | 8366 | If you did set :term:`TEST_TARGET` to "SystemdbootTarget", you also need to |
8367 | perform a one-time setup of your master image by doing the following: | 8367 | perform a one-time setup of your master image by doing the following: |
8368 | 8368 | ||
8369 | 1. *Set EFI_PROVIDER:* Be sure that ``EFI_PROVIDER`` is as follows:: | 8369 | 1. *Set EFI_PROVIDER:* Be sure that :term:`EFI_PROVIDER` is as follows:: |
8370 | 8370 | ||
8371 | EFI_PROVIDER = "systemd-boot" | 8371 | EFI_PROVIDER = "systemd-boot" |
8372 | 8372 | ||
@@ -8400,7 +8400,7 @@ perform a one-time setup of your master image by doing the following: | |||
8400 | 3. *Install image:* Install the image that you just built on the target | 8400 | 3. *Install image:* Install the image that you just built on the target |
8401 | system. | 8401 | system. |
8402 | 8402 | ||
8403 | The final thing you need to do when setting ``TEST_TARGET`` to | 8403 | The final thing you need to do when setting :term:`TEST_TARGET` to |
8404 | "SystemdbootTarget" is to set up the test image: | 8404 | "SystemdbootTarget" is to set up the test image: |
8405 | 8405 | ||
8406 | 1. *Set up your local.conf file:* Make sure you have the following | 8406 | 1. *Set up your local.conf file:* Make sure you have the following |
@@ -8421,8 +8421,8 @@ Power Control | |||
8421 | For most hardware targets other than "simpleremote", you can control | 8421 | For most hardware targets other than "simpleremote", you can control |
8422 | power: | 8422 | power: |
8423 | 8423 | ||
8424 | - You can use ``TEST_POWERCONTROL_CMD`` together with | 8424 | - You can use :term:`TEST_POWERCONTROL_CMD` together with |
8425 | ``TEST_POWERCONTROL_EXTRA_ARGS`` as a command that runs on the host | 8425 | :term:`TEST_POWERCONTROL_EXTRA_ARGS` as a command that runs on the host |
8426 | and does power cycling. The test code passes one argument to that | 8426 | and does power cycling. The test code passes one argument to that |
8427 | command: off, on or cycle (off then on). Here is an example that | 8427 | command: off, on or cycle (off then on). Here is an example that |
8428 | could appear in your ``local.conf`` file:: | 8428 | could appear in your ``local.conf`` file:: |
@@ -8441,8 +8441,8 @@ power: | |||
8441 | 8441 | ||
8442 | .. note:: | 8442 | .. note:: |
8443 | 8443 | ||
8444 | You need to customize ``TEST_POWERCONTROL_CMD`` and | 8444 | You need to customize :term:`TEST_POWERCONTROL_CMD` and |
8445 | ``TEST_POWERCONTROL_EXTRA_ARGS`` for your own setup. The one requirement | 8445 | :term:`TEST_POWERCONTROL_EXTRA_ARGS` for your own setup. The one requirement |
8446 | is that it accepts "on", "off", and "cycle" as the last argument. | 8446 | is that it accepts "on", "off", and "cycle" as the last argument. |
8447 | 8447 | ||
8448 | - When no command is defined, it connects to the device over SSH and | 8448 | - When no command is defined, it connects to the device over SSH and |
@@ -8540,14 +8540,14 @@ the ``local.conf`` file as normal. Be sure that tests reside in | |||
8540 | 8540 | ||
8541 | You can change the set of tests run by appending or overriding | 8541 | You can change the set of tests run by appending or overriding |
8542 | :term:`TEST_SUITES` variable in | 8542 | :term:`TEST_SUITES` variable in |
8543 | ``local.conf``. Each name in ``TEST_SUITES`` represents a required test | 8543 | ``local.conf``. Each name in :term:`TEST_SUITES` represents a required test |
8544 | for the image. Test modules named within ``TEST_SUITES`` cannot be | 8544 | for the image. Test modules named within :term:`TEST_SUITES` cannot be |
8545 | skipped even if a test is not suitable for an image (e.g. running the | 8545 | skipped even if a test is not suitable for an image (e.g. running the |
8546 | RPM tests on an image without ``rpm``). Appending "auto" to | 8546 | RPM tests on an image without ``rpm``). Appending "auto" to |
8547 | ``TEST_SUITES`` causes the build system to try to run all tests that are | 8547 | :term:`TEST_SUITES` causes the build system to try to run all tests that are |
8548 | suitable for the image (i.e. each test module may elect to skip itself). | 8548 | suitable for the image (i.e. each test module may elect to skip itself). |
8549 | 8549 | ||
8550 | The order you list tests in ``TEST_SUITES`` is important and influences | 8550 | The order you list tests in :term:`TEST_SUITES` is important and influences |
8551 | test dependencies. Consequently, tests that depend on other tests should | 8551 | test dependencies. Consequently, tests that depend on other tests should |
8552 | be added after the test on which they depend. For example, since the | 8552 | be added after the test on which they depend. For example, since the |
8553 | ``ssh`` test depends on the ``ping`` test, "ssh" needs to come after | 8553 | ``ssh`` test depends on the ``ping`` test, "ssh" needs to come after |
@@ -8599,7 +8599,7 @@ following BitBake command form:: | |||
8599 | Exporting the tests places them in the | 8599 | Exporting the tests places them in the |
8600 | :term:`Build Directory` in | 8600 | :term:`Build Directory` in |
8601 | ``tmp/testexport/``\ image, which is controlled by the | 8601 | ``tmp/testexport/``\ image, which is controlled by the |
8602 | ``TEST_EXPORT_DIR`` variable. | 8602 | :term:`TEST_EXPORT_DIR` variable. |
8603 | 8603 | ||
8604 | You can now run the tests outside of the build environment:: | 8604 | You can now run the tests outside of the build environment:: |
8605 | 8605 | ||
@@ -9558,7 +9558,7 @@ So the first thing to do is build "neard" locally. Before you start the | |||
9558 | build, set the | 9558 | build, set the |
9559 | :term:`PARALLEL_MAKE` variable | 9559 | :term:`PARALLEL_MAKE` variable |
9560 | in your ``local.conf`` file to a high number (e.g. "-j 20"). Using a | 9560 | in your ``local.conf`` file to a high number (e.g. "-j 20"). Using a |
9561 | high value for ``PARALLEL_MAKE`` increases the chances of the race | 9561 | high value for :term:`PARALLEL_MAKE` increases the chances of the race |
9562 | condition showing up:: | 9562 | condition showing up:: |
9563 | 9563 | ||
9564 | $ bitbake neard | 9564 | $ bitbake neard |
@@ -9631,7 +9631,7 @@ The final thing you need to do to implement the fix in the build is to | |||
9631 | update the "neard" recipe (i.e. ``neard-0.14.bb``) so that the | 9631 | update the "neard" recipe (i.e. ``neard-0.14.bb``) so that the |
9632 | :term:`SRC_URI` statement includes | 9632 | :term:`SRC_URI` statement includes |
9633 | the patch file. The recipe file is in the folder above the patch. Here | 9633 | the patch file. The recipe file is in the folder above the patch. Here |
9634 | is what the edited ``SRC_URI`` statement would look like:: | 9634 | is what the edited :term:`SRC_URI` statement would look like:: |
9635 | 9635 | ||
9636 | SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \ | 9636 | SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \ |
9637 | file://neard.in \ | 9637 | file://neard.in \ |
@@ -9640,7 +9640,7 @@ is what the edited ``SRC_URI`` statement would look like:: | |||
9640 | " | 9640 | " |
9641 | 9641 | ||
9642 | With the patch complete and moved to the correct folder and the | 9642 | With the patch complete and moved to the correct folder and the |
9643 | ``SRC_URI`` statement updated, you can exit the ``devshell``:: | 9643 | :term:`SRC_URI` statement updated, you can exit the ``devshell``:: |
9644 | 9644 | ||
9645 | $ exit | 9645 | $ exit |
9646 | 9646 | ||
@@ -9985,14 +9985,14 @@ Here are some other tips that you might find useful: | |||
9985 | - Removing :term:`TMPDIR` (usually | 9985 | - Removing :term:`TMPDIR` (usually |
9986 | ``tmp/``, within the | 9986 | ``tmp/``, within the |
9987 | :term:`Build Directory`) can often fix | 9987 | :term:`Build Directory`) can often fix |
9988 | temporary build issues. Removing ``TMPDIR`` is usually a relatively | 9988 | temporary build issues. Removing :term:`TMPDIR` is usually a relatively |
9989 | cheap operation, because task output will be cached in | 9989 | cheap operation, because task output will be cached in |
9990 | :term:`SSTATE_DIR` (usually | 9990 | :term:`SSTATE_DIR` (usually |
9991 | ``sstate-cache/``, which is also in the Build Directory). | 9991 | ``sstate-cache/``, which is also in the Build Directory). |
9992 | 9992 | ||
9993 | .. note:: | 9993 | .. note:: |
9994 | 9994 | ||
9995 | Removing ``TMPDIR`` might be a workaround rather than a fix. | 9995 | Removing :term:`TMPDIR` might be a workaround rather than a fix. |
9996 | Consequently, trying to determine the underlying cause of an issue before | 9996 | Consequently, trying to determine the underlying cause of an issue before |
9997 | removing the directory is a good idea. | 9997 | removing the directory is a good idea. |
9998 | 9998 | ||
@@ -10585,9 +10585,9 @@ build will fail. | |||
10585 | Specifying the ``LIC_FILES_CHKSUM`` Variable | 10585 | Specifying the ``LIC_FILES_CHKSUM`` Variable |
10586 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 10586 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
10587 | 10587 | ||
10588 | The ``LIC_FILES_CHKSUM`` variable contains checksums of the license text | 10588 | The :term:`LIC_FILES_CHKSUM` variable contains checksums of the license text |
10589 | in the source code for the recipe. Following is an example of how to | 10589 | in the source code for the recipe. Following is an example of how to |
10590 | specify ``LIC_FILES_CHKSUM``:: | 10590 | specify :term:`LIC_FILES_CHKSUM`:: |
10591 | 10591 | ||
10592 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ | 10592 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ |
10593 | file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ | 10593 | file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ |
@@ -10607,7 +10607,7 @@ specify ``LIC_FILES_CHKSUM``:: | |||
10607 | 10607 | ||
10608 | The build system uses the :term:`S` | 10608 | The build system uses the :term:`S` |
10609 | variable as the default directory when searching files listed in | 10609 | variable as the default directory when searching files listed in |
10610 | ``LIC_FILES_CHKSUM``. The previous example employs the default | 10610 | :term:`LIC_FILES_CHKSUM`. The previous example employs the default |
10611 | directory. | 10611 | directory. |
10612 | 10612 | ||
10613 | Consider this next example:: | 10613 | Consider this next example:: |
@@ -10620,13 +10620,13 @@ The first line locates a file in ``${S}/src/ls.c`` and isolates lines | |||
10620 | five through 16 as license text. The second line refers to a file in | 10620 | five through 16 as license text. The second line refers to a file in |
10621 | :term:`WORKDIR`. | 10621 | :term:`WORKDIR`. |
10622 | 10622 | ||
10623 | Note that ``LIC_FILES_CHKSUM`` variable is mandatory for all recipes, | 10623 | Note that :term:`LIC_FILES_CHKSUM` variable is mandatory for all recipes, |
10624 | unless the ``LICENSE`` variable is set to "CLOSED". | 10624 | unless the :term:`LICENSE` variable is set to "CLOSED". |
10625 | 10625 | ||
10626 | Explanation of Syntax | 10626 | Explanation of Syntax |
10627 | ~~~~~~~~~~~~~~~~~~~~~ | 10627 | ~~~~~~~~~~~~~~~~~~~~~ |
10628 | 10628 | ||
10629 | As mentioned in the previous section, the ``LIC_FILES_CHKSUM`` variable | 10629 | As mentioned in the previous section, the :term:`LIC_FILES_CHKSUM` variable |
10630 | lists all the important files that contain the license text for the | 10630 | lists all the important files that contain the license text for the |
10631 | source code. It is possible to specify a checksum for an entire file, or | 10631 | source code. It is possible to specify a checksum for an entire file, or |
10632 | a specific section of a file (specified by beginning and ending line | 10632 | a specific section of a file (specified by beginning and ending line |
@@ -10646,7 +10646,7 @@ build, the correct md5 checksum is placed in the build log and can be | |||
10646 | easily copied to the recipe. | 10646 | easily copied to the recipe. |
10647 | 10647 | ||
10648 | There is no limit to how many files you can specify using the | 10648 | There is no limit to how many files you can specify using the |
10649 | ``LIC_FILES_CHKSUM`` variable. Generally, however, every project | 10649 | :term:`LIC_FILES_CHKSUM` variable. Generally, however, every project |
10650 | requires a few specifications for license tracking. Many projects have a | 10650 | requires a few specifications for license tracking. Many projects have a |
10651 | "COPYING" file that stores the license information for all the source | 10651 | "COPYING" file that stores the license information for all the source |
10652 | code files. This practice allows you to just track the "COPYING" file as | 10652 | code files. This practice allows you to just track the "COPYING" file as |
@@ -10683,16 +10683,16 @@ name and version (after variable expansion):: | |||
10683 | LICENSE_FLAGS = "license_${PN}_${PV}" | 10683 | LICENSE_FLAGS = "license_${PN}_${PV}" |
10684 | 10684 | ||
10685 | In order for a component restricted by a | 10685 | In order for a component restricted by a |
10686 | ``LICENSE_FLAGS`` definition to be enabled and included in an image, it | 10686 | :term:`LICENSE_FLAGS` definition to be enabled and included in an image, it |
10687 | needs to have a matching entry in the global | 10687 | needs to have a matching entry in the global |
10688 | :term:`LICENSE_FLAGS_WHITELIST` | 10688 | :term:`LICENSE_FLAGS_WHITELIST` |
10689 | variable, which is a variable typically defined in your ``local.conf`` | 10689 | variable, which is a variable typically defined in your ``local.conf`` |
10690 | file. For example, to enable the | 10690 | file. For example, to enable the |
10691 | ``poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly`` package, you | 10691 | ``poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly`` package, you |
10692 | could add either the string "commercial_gst-plugins-ugly" or the more | 10692 | could add either the string "commercial_gst-plugins-ugly" or the more |
10693 | general string "commercial" to ``LICENSE_FLAGS_WHITELIST``. See the | 10693 | general string "commercial" to :term:`LICENSE_FLAGS_WHITELIST`. See the |
10694 | ":ref:`dev-manual/common-tasks:license flag matching`" section for a full | 10694 | ":ref:`dev-manual/common-tasks:license flag matching`" section for a full |
10695 | explanation of how ``LICENSE_FLAGS`` matching works. Here is the | 10695 | explanation of how :term:`LICENSE_FLAGS` matching works. Here is the |
10696 | example:: | 10696 | example:: |
10697 | 10697 | ||
10698 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" | 10698 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" |
@@ -10723,8 +10723,8 @@ License Flag Matching | |||
10723 | 10723 | ||
10724 | License flag matching allows you to control what recipes the | 10724 | License flag matching allows you to control what recipes the |
10725 | OpenEmbedded build system includes in the build. Fundamentally, the | 10725 | OpenEmbedded build system includes in the build. Fundamentally, the |
10726 | build system attempts to match ``LICENSE_FLAGS`` strings found in | 10726 | build system attempts to match :term:`LICENSE_FLAGS` strings found in |
10727 | recipes against ``LICENSE_FLAGS_WHITELIST`` strings found in the | 10727 | recipes against :term:`LICENSE_FLAGS_WHITELIST` strings found in the |
10728 | whitelist. A match causes the build system to include a recipe in the | 10728 | whitelist. A match causes the build system to include a recipe in the |
10729 | build, while failure to find a match causes the build system to exclude | 10729 | build, while failure to find a match causes the build system to exclude |
10730 | a recipe. | 10730 | a recipe. |
@@ -10734,14 +10734,14 @@ concepts will help you correctly and effectively use matching. | |||
10734 | 10734 | ||
10735 | Before a flag defined by a particular recipe is tested against the | 10735 | Before a flag defined by a particular recipe is tested against the |
10736 | contents of the whitelist, the expanded string ``_${PN}`` is appended to | 10736 | contents of the whitelist, the expanded string ``_${PN}`` is appended to |
10737 | the flag. This expansion makes each ``LICENSE_FLAGS`` value | 10737 | the flag. This expansion makes each :term:`LICENSE_FLAGS` value |
10738 | recipe-specific. After expansion, the string is then matched against the | 10738 | recipe-specific. After expansion, the string is then matched against the |
10739 | whitelist. Thus, specifying ``LICENSE_FLAGS = "commercial"`` in recipe | 10739 | whitelist. Thus, specifying ``LICENSE_FLAGS = "commercial"`` in recipe |
10740 | "foo", for example, results in the string ``"commercial_foo"``. And, to | 10740 | "foo", for example, results in the string ``"commercial_foo"``. And, to |
10741 | create a match, that string must appear in the whitelist. | 10741 | create a match, that string must appear in the whitelist. |
10742 | 10742 | ||
10743 | Judicious use of the ``LICENSE_FLAGS`` strings and the contents of the | 10743 | Judicious use of the :term:`LICENSE_FLAGS` strings and the contents of the |
10744 | ``LICENSE_FLAGS_WHITELIST`` variable allows you a lot of flexibility for | 10744 | :term:`LICENSE_FLAGS_WHITELIST` variable allows you a lot of flexibility for |
10745 | including or excluding recipes based on licensing. For example, you can | 10745 | including or excluding recipes based on licensing. For example, you can |
10746 | broaden the matching capabilities by using license flags string subsets | 10746 | broaden the matching capabilities by using license flags string subsets |
10747 | in the whitelist. | 10747 | in the whitelist. |
@@ -10753,7 +10753,7 @@ in the whitelist. | |||
10753 | ``usethispart_1.3``, ``usethispart_1.4``, and so forth). | 10753 | ``usethispart_1.3``, ``usethispart_1.4``, and so forth). |
10754 | 10754 | ||
10755 | For example, simply specifying the string "commercial" in the whitelist | 10755 | For example, simply specifying the string "commercial" in the whitelist |
10756 | matches any expanded ``LICENSE_FLAGS`` definition that starts with the | 10756 | matches any expanded :term:`LICENSE_FLAGS` definition that starts with the |
10757 | string "commercial" such as "commercial_foo" and "commercial_bar", which | 10757 | string "commercial" such as "commercial_foo" and "commercial_bar", which |
10758 | are the strings the build system automatically generates for | 10758 | are the strings the build system automatically generates for |
10759 | hypothetical recipes named "foo" and "bar" assuming those recipes simply | 10759 | hypothetical recipes named "foo" and "bar" assuming those recipes simply |
@@ -10767,7 +10767,7 @@ only specific recipes into the image, or you can use a string subset | |||
10767 | that causes a broader range of matches to allow a range of recipes into | 10767 | that causes a broader range of matches to allow a range of recipes into |
10768 | the image. | 10768 | the image. |
10769 | 10769 | ||
10770 | This scheme works even if the ``LICENSE_FLAGS`` string already has | 10770 | This scheme works even if the :term:`LICENSE_FLAGS` string already has |
10771 | ``_${PN}`` appended. For example, the build system turns the license | 10771 | ``_${PN}`` appended. For example, the build system turns the license |
10772 | flag "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would match | 10772 | flag "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would match |
10773 | both the general "commercial" and the specific "commercial_1.2_foo" | 10773 | both the general "commercial" and the specific "commercial_1.2_foo" |
@@ -10814,14 +10814,14 @@ file:: | |||
10814 | 10814 | ||
10815 | Of course, you could also create a matching whitelist for those | 10815 | Of course, you could also create a matching whitelist for those |
10816 | components using the more general "commercial" in the whitelist, but | 10816 | components using the more general "commercial" in the whitelist, but |
10817 | that would also enable all the other packages with ``LICENSE_FLAGS`` | 10817 | that would also enable all the other packages with :term:`LICENSE_FLAGS` |
10818 | containing "commercial", which you may or may not want:: | 10818 | containing "commercial", which you may or may not want:: |
10819 | 10819 | ||
10820 | LICENSE_FLAGS_WHITELIST = "commercial" | 10820 | LICENSE_FLAGS_WHITELIST = "commercial" |
10821 | 10821 | ||
10822 | Specifying audio and video plugins as part of the | 10822 | Specifying audio and video plugins as part of the |
10823 | ``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements | 10823 | ``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements |
10824 | (along with the enabling ``LICENSE_FLAGS_WHITELIST``) includes the | 10824 | (along with the enabling :term:`LICENSE_FLAGS_WHITELIST`) includes the |
10825 | plugins or components into built images, thus adding support for media | 10825 | plugins or components into built images, thus adding support for media |
10826 | formats or components. | 10826 | formats or components. |
10827 | 10827 | ||
@@ -10887,7 +10887,7 @@ accidental release of proprietary software. The Yocto Project provides | |||
10887 | an :ref:`archiver <ref-classes-archiver>` class to | 10887 | an :ref:`archiver <ref-classes-archiver>` class to |
10888 | help avoid some of these concerns. | 10888 | help avoid some of these concerns. |
10889 | 10889 | ||
10890 | Before you employ ``DL_DIR`` or the ``archiver`` class, you need to | 10890 | Before you employ :term:`DL_DIR` or the ``archiver`` class, you need to |
10891 | decide how you choose to provide source. The source ``archiver`` class | 10891 | decide how you choose to provide source. The source ``archiver`` class |
10892 | can generate tarballs and SRPMs and can create them with various levels | 10892 | can generate tarballs and SRPMs and can create them with various levels |
10893 | of compliance in mind. | 10893 | of compliance in mind. |