diff options
author | Quentin Schulz <foss@0leil.net> | 2021-05-27 20:41:17 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2021-06-19 16:54:01 +0100 |
commit | 7d3f57cfd2e4322bcd96d67d330124f221a9aedd (patch) | |
tree | 5d07321b7c8bc59bb7fcc0372fab8b7a1966cf06 /documentation/dev-manual | |
parent | 7a9b74e9d2a5cf3b1fb3ac7565c50eae6e0d4632 (diff) | |
download | poky-7d3f57cfd2e4322bcd96d67d330124f221a9aedd.tar.gz |
docs: replace ``FOO`` by :term:`FOO` where possible
If a variable has a glossary entry and some rST files write about those
variables, it's better to point to the glossary entry instead of just
highlighting it by surrounding it with two tick quotes.
This was automated by the following python script:
"""
import re
from pathlib import Path
with open('objects.inv.txt', 'r') as f:
objects = f.readlines()
with open('bitbake-objects.inv.txt', 'r') as f:
objects = objects + f.readlines()
re_term = re.compile(r'variables.html#term-([A-Z_0-9]*)')
terms = []
for obj in objects:
match = re_term.search(obj)
if match and match.group(1):
terms.append(match.group(1))
for rst in Path('.').rglob('*.rst'):
with open(rst, 'r') as f:
content = "".joing(f.readlines())
for term in terms:
content = re.sub(r'``({})``(?!.*\s*[~-]+)'.format(term), r':term:`\1`', content)
with open(rst, 'w') as f:
f.write(content)
"""
(From yocto-docs rev: ba49d9babfcb84bc5c26a68c8c3880a1d9c236d3)
Signed-off-by: Quentin Schulz <foss@0leil.net>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reviewed-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-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. |