diff options
Diffstat (limited to 'poky/documentation/dev-manual')
| -rw-r--r-- | poky/documentation/dev-manual/building.rst | 9 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/debugging.rst | 21 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/development-shell.rst | 2 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/device-manager.rst | 8 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/layers.rst | 8 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/libraries.rst | 4 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/licenses.rst | 2 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/new-machine.rst | 2 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/new-recipe.rst | 8 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/packages.rst | 22 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/prebuilt-libraries.rst | 4 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/python-development-shell.rst | 2 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/qemu.rst | 4 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/runtime-testing.rst | 4 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/sbom.rst | 40 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/speeding-up-build.rst | 4 | ||||
| -rw-r--r-- | poky/documentation/dev-manual/start.rst | 6 |
17 files changed, 88 insertions, 62 deletions
diff --git a/poky/documentation/dev-manual/building.rst b/poky/documentation/dev-manual/building.rst index e964bd1aee..fe502690dd 100644 --- a/poky/documentation/dev-manual/building.rst +++ b/poky/documentation/dev-manual/building.rst @@ -160,7 +160,7 @@ Follow these steps to set up and execute multiple configuration builds: The location for these multiconfig configuration files is specific. They must reside in the current :term:`Build Directory` in a sub-directory of ``conf`` named ``multiconfig`` or within a layer's ``conf`` directory - under a directory named ``multiconfig``. Following is an example that defines + under a directory named ``multiconfig``. Here is an example that defines two configuration files for the "x86" and "arm" multiconfigs: .. image:: figures/multiconfig_files.png @@ -775,10 +775,9 @@ your tunings to best consider build times and package feed maintenance. in the script for information on how to use the tool. - *BitBake's "-S printdiff" Option:* Using this option causes - BitBake to try to establish the closest signature match it can - (e.g. in the shared state cache) and then run ``bitbake-diffsigs`` - over the matches to determine the stamps and delta where these two - stamp trees diverge. + BitBake to try to establish the most recent signature match + (e.g. in the shared state cache) and then compare matched signatures + to determine the stamps and delta where these two stamp trees diverge. Building Software from an External Source ========================================= diff --git a/poky/documentation/dev-manual/debugging.rst b/poky/documentation/dev-manual/debugging.rst index bd1e716b0b..74f5772554 100644 --- a/poky/documentation/dev-manual/debugging.rst +++ b/poky/documentation/dev-manual/debugging.rst @@ -170,7 +170,7 @@ You can use the ``oe-pkgdata-util`` command-line utility to query various package-related information. When you use the utility, you must use it to view information on packages that have already been built. -Following are a few of the available ``oe-pkgdata-util`` subcommands. +Here are a few of the available ``oe-pkgdata-util`` subcommands. .. note:: @@ -339,7 +339,10 @@ BitBake has determined by doing the following: :term:`BB_BASEHASH_IGNORE_VARS` information. -There is also a ``bitbake-diffsigs`` command for comparing two +Debugging signature construction and unexpected task executions +=============================================================== + +There is a ``bitbake-diffsigs`` command for comparing two ``siginfo`` or ``sigdata`` files. This command can be helpful when trying to figure out what changed between two versions of a task. If you call ``bitbake-diffsigs`` with just one file, the command behaves like @@ -356,8 +359,12 @@ BitBake command-line options:: .. note:: Two common values for `SIGNATURE_HANDLER` are "none" and "printdiff", which - dump only the signature or compare the dumped signature with the cached one, - respectively. + dump only the signature or compare the dumped signature with the most recent one, + respectively. "printdiff" will try to establish the most recent + signature match (e.g. in the sstate cache) and then + compare the matched signatures to determine the stamps and delta + where these two stamp trees diverge. This can be used to determine why + tasks need to be re-run in situations where that is not expected. Using BitBake with either of these options causes BitBake to dump out ``sigdata`` files in the ``stamps`` directory for every task it would @@ -608,7 +615,7 @@ logs, keep in mind the goal is to have informative logs while keeping the console as "silent" as possible. Also, if you want status messages in the log, use the "debug" loglevel. -Following is an example written in Python. The code handles logging for +Here is an example written in Python. The code handles logging for a function that determines the number of tasks needed to be run. See the ":ref:`ref-tasks-listtasks`" section for additional information:: @@ -636,7 +643,7 @@ logs, you have the same goals --- informative with minimal console output. The syntax you use for recipes written in Bash is similar to that of recipes written in Python described in the previous section. -Following is an example written in Bash. The code logs the progress of +Here is an example written in Bash. The code logs the progress of the ``do_my_function`` function:: do_my_function() { @@ -1221,7 +1228,7 @@ Here are some other tips that you might find useful: "$@" } - Following are some usage examples:: + Here are some usage examples:: $ g FOO # Search recursively for "FOO" $ g -i foo # Search recursively for "foo", ignoring case diff --git a/poky/documentation/dev-manual/development-shell.rst b/poky/documentation/dev-manual/development-shell.rst index a18d792150..be26bcffc7 100644 --- a/poky/documentation/dev-manual/development-shell.rst +++ b/poky/documentation/dev-manual/development-shell.rst @@ -16,7 +16,7 @@ OpenEmbedded build system were executing them. Consequently, working this way can be helpful when debugging a build or preparing software to be used with the OpenEmbedded build system. -Following is an example that uses ``devshell`` on a target named +Here is an example that uses ``devshell`` on a target named ``matchbox-desktop``:: $ bitbake matchbox-desktop -c devshell diff --git a/poky/documentation/dev-manual/device-manager.rst b/poky/documentation/dev-manual/device-manager.rst index 0343d19b9c..49fc785fec 100644 --- a/poky/documentation/dev-manual/device-manager.rst +++ b/poky/documentation/dev-manual/device-manager.rst @@ -60,10 +60,10 @@ kernel. All devices created by ``devtmpfs`` will be owned by ``root`` and have permissions ``0600``. -To have more control over the device nodes, you can use a device manager -like ``udev`` or ``busybox-mdev``. You choose the device manager by -defining the ``VIRTUAL-RUNTIME_dev_manager`` variable in your machine or -distro configuration file. Alternatively, you can set this variable in +To have more control over the device nodes, you can use a device manager like +``udev`` or ``busybox-mdev``. You choose the device manager by defining the +:term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` variable in your machine +or distro configuration file. Alternatively, you can set this variable in your ``local.conf`` configuration file:: VIRTUAL-RUNTIME_dev_manager = "udev" diff --git a/poky/documentation/dev-manual/layers.rst b/poky/documentation/dev-manual/layers.rst index b3ccf633df..f7929e630e 100644 --- a/poky/documentation/dev-manual/layers.rst +++ b/poky/documentation/dev-manual/layers.rst @@ -82,7 +82,7 @@ Follow these general steps to create your layer without using tools: LAYERVERSION_yoctobsp = "4" LAYERSERIES_COMPAT_yoctobsp = "dunfell" - Following is an explanation of the layer configuration file: + Here is an explanation of the layer configuration file: - :term:`BBPATH`: Adds the layer's root directory to BitBake's search path. Through the use of the @@ -191,7 +191,7 @@ following list: - *Structure Your Layers:* Proper use of overrides within append files and placement of machine-specific files within your layer can ensure that a build is not using the wrong Metadata and negatively impacting - a build for a different machine. Following are some examples: + a build for a different machine. Here are some examples: - *Modify Variables to Support a Different Machine:* Suppose you have a layer named ``meta-one`` that adds support for building @@ -513,7 +513,7 @@ In the main recipe, note the :term:`SRC_URI` variable, which tells the OpenEmbedded build system where to find files during the build. -Following is the append file, which is named ``formfactor_0.0.bbappend`` +Here is the append file, which is named ``formfactor_0.0.bbappend`` and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The file is in the layer at ``recipes-bsp/formfactor``:: @@ -588,7 +588,7 @@ Directory`. Here is the main ``xserver-xf86-config`` recipe, which is named fi } -Following is the append file, which is named ``xserver-xf86-config_%.bbappend`` +Here is the append file, which is named ``xserver-xf86-config_%.bbappend`` and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The file is in the layer at ``recipes-graphics/xorg-xserver``:: diff --git a/poky/documentation/dev-manual/libraries.rst b/poky/documentation/dev-manual/libraries.rst index ae4ca27209..521dbb9a7c 100644 --- a/poky/documentation/dev-manual/libraries.rst +++ b/poky/documentation/dev-manual/libraries.rst @@ -37,7 +37,7 @@ library files. Some previously released versions of the Yocto Project defined the static library files through ``${PN}-dev``. -Following is part of the BitBake configuration file, where you can see +Here is the part of the BitBake configuration file, where you can see how the static library files are defined:: PACKAGE_BEFORE_PN ?= "" @@ -177,7 +177,7 @@ Additional Implementation Details --------------------------------- There are generic implementation details as well as details that are specific to -package management systems. Following are implementation details +package management systems. Here are implementation details that exist regardless of the package management system: - The typical convention used for the class extension code as used by diff --git a/poky/documentation/dev-manual/licenses.rst b/poky/documentation/dev-manual/licenses.rst index 57713effa0..bffff3675f 100644 --- a/poky/documentation/dev-manual/licenses.rst +++ b/poky/documentation/dev-manual/licenses.rst @@ -27,7 +27,7 @@ Specifying the ``LIC_FILES_CHKSUM`` Variable -------------------------------------------- The :term:`LIC_FILES_CHKSUM` variable contains checksums of the license text -in the source code for the recipe. Following is an example of how to +in the source code for the recipe. Here is an example of how to specify :term:`LIC_FILES_CHKSUM`:: LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ diff --git a/poky/documentation/dev-manual/new-machine.rst b/poky/documentation/dev-manual/new-machine.rst index 6b41d24db4..469b2d395a 100644 --- a/poky/documentation/dev-manual/new-machine.rst +++ b/poky/documentation/dev-manual/new-machine.rst @@ -104,7 +104,7 @@ contains directories for specific machines such as ``qemuarm`` and defaults, see the ``meta/recipes-bsp/formfactor/files/config`` file found in the same area. -Following is an example for "qemuarm" machine:: +Here is an example for "qemuarm" machine:: HAVE_TOUCHSCREEN=1 HAVE_KEYBOARD=1 diff --git a/poky/documentation/dev-manual/new-recipe.rst b/poky/documentation/dev-manual/new-recipe.rst index 2c1033eb35..61fc2eb122 100644 --- a/poky/documentation/dev-manual/new-recipe.rst +++ b/poky/documentation/dev-manual/new-recipe.rst @@ -100,7 +100,7 @@ command:: Running ``recipetool create -o OUTFILE`` creates the base recipe and locates it properly in the layer that contains your source files. -Following are some syntax examples: +Here are some syntax examples: - Use this syntax to generate a recipe based on source. Once generated, the recipe resides in the existing source code layer:: @@ -1232,7 +1232,7 @@ inherit the :ref:`ref-classes-autotools` class, which contains the definitions of all the steps needed to build an Autotool-based application. The result of the build is automatically packaged. And, if the application uses NLS for localization, packages with local information are generated (one package per -language). Following is one example: (``hello_2.3.bb``):: +language). Here is one example: (``hello_2.3.bb``):: SUMMARY = "GNU Helloworld application" SECTION = "examples" @@ -1285,7 +1285,7 @@ Splitting an Application into Multiple Packages You can use the variables :term:`PACKAGES` and :term:`FILES` to split an application into multiple packages. -Following is an example that uses the ``libxpm`` recipe. By default, +Here is an example that uses the ``libxpm`` recipe. By default, this recipe generates a single package that contains the library along with a few binaries. You can modify the recipe to split the binaries into separate packages:: @@ -1510,7 +1510,7 @@ in the BitBake User Manual. when you make the assignment, but this is not generally needed. - *Quote All Assignments ("value"):* Use double quotes around values in - all variable assignments (e.g. ``"value"``). Following is an example:: + all variable assignments (e.g. ``"value"``). Here is an example:: VAR1 = "${OTHERVAR}" VAR2 = "The version is ${PV}" diff --git a/poky/documentation/dev-manual/packages.rst b/poky/documentation/dev-manual/packages.rst index 79f21d9f34..e5028fffdc 100644 --- a/poky/documentation/dev-manual/packages.rst +++ b/poky/documentation/dev-manual/packages.rst @@ -205,9 +205,14 @@ history, see the The OpenEmbedded build system does not maintain :term:`PR` information as part of the shared state (sstate) packages. If you maintain an sstate feed, it's expected that either all your building systems that - contribute to the sstate feed use a shared PR Service, or you do not - run a PR Service on any of your building systems. Having some systems - use a PR Service while others do not leads to obvious problems. + contribute to the sstate feed use a shared PR service, or you do not + run a PR service on any of your building systems. + + That's because if you had multiple machines sharing a PR service but + not their sstate feed, you could end up with "diverging" hashes for + the same output artefacts. When presented to the share PR service, + each would be considered as new and would increase the revision + number, causing many unnecessary package upgrades. For more information on shared state, see the ":ref:`overview-manual/concepts:shared state cache`" @@ -365,7 +370,7 @@ For more examples that show how to use ``do_split_packages``, see the directory of the ``poky`` :ref:`source repository <overview-manual/development-environment:yocto project source repositories>`. You can also find examples in ``meta/classes-recipe/kernel.bbclass``. -Following is a reference that shows ``do_split_packages`` mandatory and +Here is a reference that shows ``do_split_packages`` mandatory and optional arguments:: Mandatory arguments @@ -607,6 +612,13 @@ subsequent sections are necessary to configure the target. You should set these variables before building the image in order to produce a correctly configured image. +.. note:: + + Your image will need enough free storage space to run package upgrades, + especially if many of them need to be downloaded at the same time. + You should make sure images are created with enough free space + by setting the :term:`IMAGE_ROOTFS_EXTRA_SPACE` variable. + When your build is complete, your packages reside in the ``${TMPDIR}/deploy/packageformat`` directory. For example, if ``${``\ :term:`TMPDIR`\ ``}`` is @@ -1123,7 +1135,7 @@ The ``devtool edit-recipe`` command lets you take a look at the recipe:: ... LICENSE:${PN}-vary = "MIT" -Here are three key points in the previous example: +Three key points in the previous example are: - :term:`SRC_URI` uses the NPM scheme so that the NPM fetcher is used. diff --git a/poky/documentation/dev-manual/prebuilt-libraries.rst b/poky/documentation/dev-manual/prebuilt-libraries.rst index b80a844e93..a05f39ca1e 100644 --- a/poky/documentation/dev-manual/prebuilt-libraries.rst +++ b/poky/documentation/dev-manual/prebuilt-libraries.rst @@ -148,8 +148,8 @@ recipe. By default, ``libfoo.so`` gets packaged into ``${PN}-dev``, which triggers a QA warning that a non-symlink library is in a ``-dev`` package, and binaries in the same recipe link to the library in ``${PN}-dev``, which triggers more QA warnings. To solve this problem, you need to package the -unversioned library into ``${PN}`` where it belongs. The following are the abridged -default :term:`FILES` variables in ``bitbake.conf``:: +unversioned library into ``${PN}`` where it belongs. The abridged +default :term:`FILES` variables in ``bitbake.conf`` are:: SOLIBS = ".so.*" SOLIBSDEV = ".so" diff --git a/poky/documentation/dev-manual/python-development-shell.rst b/poky/documentation/dev-manual/python-development-shell.rst index 2dc6a3f138..81a5c43472 100644 --- a/poky/documentation/dev-manual/python-development-shell.rst +++ b/poky/documentation/dev-manual/python-development-shell.rst @@ -35,7 +35,7 @@ system were executing them. Consequently, working this way can be helpful when debugging a build or preparing software to be used with the OpenEmbedded build system. -Following is an example that uses ``pydevshell`` on a target named +Here is an example that uses ``pydevshell`` on a target named ``matchbox-desktop``:: $ bitbake matchbox-desktop -c pydevshell diff --git a/poky/documentation/dev-manual/qemu.rst b/poky/documentation/dev-manual/qemu.rst index d431ea4b99..19f3e40d63 100644 --- a/poky/documentation/dev-manual/qemu.rst +++ b/poky/documentation/dev-manual/qemu.rst @@ -311,7 +311,7 @@ timestamp when it needs to look for an image. Minimally, through the use of options, you must provide either a machine name, a virtual machine image (``*wic.vmdk``), or a kernel image (``*.bin``). -Following is the command-line help output for the ``runqemu`` command:: +Here is the command-line help output for the ``runqemu`` command:: $ runqemu --help @@ -353,7 +353,7 @@ Following is the command-line help output for the ``runqemu`` command:: ``runqemu`` Command-Line Options ================================ -Following is a description of ``runqemu`` options you can provide on the +Here is a description of ``runqemu`` options you can provide on the command line: .. note:: diff --git a/poky/documentation/dev-manual/runtime-testing.rst b/poky/documentation/dev-manual/runtime-testing.rst index 1a2e9ec4fe..7a2b42f25a 100644 --- a/poky/documentation/dev-manual/runtime-testing.rst +++ b/poky/documentation/dev-manual/runtime-testing.rst @@ -193,7 +193,7 @@ perform a one-time setup of your controller image by doing the following: "controller" image and you can customize the image recipe as you would any other recipe. - Here are the image recipe requirements: + Image recipe requirements are: - Inherits ``core-image`` so that kernel modules are installed. @@ -572,7 +572,7 @@ data: When set to "true", the package is not automatically installed into the DUT. -Following is an example JSON file that handles test "foo" installing +Here is an example JSON file that handles test "foo" installing package "bar" and test "foobar" installing packages "foo" and "bar". Once the test is complete, the packages are removed from the DUT:: diff --git a/poky/documentation/dev-manual/sbom.rst b/poky/documentation/dev-manual/sbom.rst index f51d08f84d..b72bad1554 100644 --- a/poky/documentation/dev-manual/sbom.rst +++ b/poky/documentation/dev-manual/sbom.rst @@ -30,22 +30,29 @@ To make this happen, you must inherit the INHERIT += "create-spdx" -You then get :term:`SPDX` output in JSON format as an -``IMAGE-MACHINE.spdx.json`` file in ``tmp/deploy/images/MACHINE/`` inside the -:term:`Build Directory`. +Upon building an image, you will then get: -This is a toplevel file accompanied by an ``IMAGE-MACHINE.spdx.index.json`` -containing an index of JSON :term:`SPDX` files for individual recipes, together -with an ``IMAGE-MACHINE.spdx.tar.zst`` compressed archive containing all such -files. +- :term:`SPDX` output in JSON format as an ``IMAGE-MACHINE.spdx.json`` file in + ``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`. + +- This toplevel file is accompanied by an ``IMAGE-MACHINE.spdx.index.json`` + containing an index of JSON :term:`SPDX` files for individual recipes. + +- The compressed archive ``IMAGE-MACHINE.spdx.tar.zst`` contains the index + and the files for the single recipes. The :ref:`ref-classes-create-spdx` class offers options to include -more information in the output :term:`SPDX` data, such as making the generated -files more human readable (:term:`SPDX_PRETTY`), adding compressed archives of -the files in the generated target packages (:term:`SPDX_ARCHIVE_PACKAGED`), -adding a description of the source files used to generate host tools and target -packages (:term:`SPDX_INCLUDE_SOURCES`) and adding archives of these source -files themselves (:term:`SPDX_ARCHIVE_SOURCES`). +more information in the output :term:`SPDX` data: + +- Make the json files more human readable by setting (:term:`SPDX_PRETTY`). + +- Add compressed archives of the files in the generated target packages by + setting (:term:`SPDX_ARCHIVE_PACKAGED`). + +- Add a description of the source files used to generate host tools and target + packages (:term:`SPDX_INCLUDE_SOURCES`) + +- Add archives of these source files themselves (:term:`SPDX_ARCHIVE_SOURCES`). Though the toplevel :term:`SPDX` output is available in ``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`, ancillary @@ -65,11 +72,12 @@ generated files are available in ``tmp/deploy/spdx/MACHINE`` too, such as: See also the :term:`SPDX_CUSTOM_ANNOTATION_VARS` variable which allows to associate custom notes to a recipe. - See the `tools page <https://spdx.dev/resources/tools/>`__ on the :term:`SPDX` project website for a list of tools to consume and transform the :term:`SPDX` data generated by the OpenEmbedded build system. -See also Joshua Watt's +See also Joshua Watt's presentations `Automated SBoM generation with OpenEmbedded and the Yocto Project <https://youtu.be/Q5UQUM6zxVU>`__ -presentation at FOSDEM 2023. +at FOSDEM 2023 and +`SPDX in the Yocto Project <https://fosdem.org/2024/schedule/event/fosdem-2024-3318-spdx-in-the-yocto-project/>`__ +at FOSDEM 2024. diff --git a/poky/documentation/dev-manual/speeding-up-build.rst b/poky/documentation/dev-manual/speeding-up-build.rst index 31b6f75ab0..6e0d7873ac 100644 --- a/poky/documentation/dev-manual/speeding-up-build.rst +++ b/poky/documentation/dev-manual/speeding-up-build.rst @@ -33,7 +33,7 @@ auto-scaling ensures that the build system fundamentally takes advantage of potential parallel operations during the build based on the build machine's capabilities. -Following are additional factors that can affect build speed: +Additional factors that can affect build speed are: - File system type: The file system type that the build is being performed on can also influence performance. Using ``ext4`` is @@ -88,7 +88,7 @@ that can help you speed up the build: variable to "1". - Disable static library generation for recipes derived from - ``autoconf`` or ``libtool``: Following is an example showing how to + ``autoconf`` or ``libtool``: Here is an example showing how to disable static libraries and still provide an override to handle exceptions:: diff --git a/poky/documentation/dev-manual/start.rst b/poky/documentation/dev-manual/start.rst index b108337795..8539bc0889 100644 --- a/poky/documentation/dev-manual/start.rst +++ b/poky/documentation/dev-manual/start.rst @@ -36,7 +36,7 @@ particular working environment and set of practices. equipment together and set up your development environment's hardware topology. - Here are possible roles: + Possible roles are: - *Application Developer:* This type of developer does application level work on top of an existing software stack. @@ -99,7 +99,7 @@ particular working environment and set of practices. #. *Set up the Application Development Machines:* As mentioned earlier, application developers are creating applications on top of existing - software stacks. Following are some best practices for setting up + software stacks. Here are some best practices for setting up machines used for application development: - Use a pre-built toolchain that contains the software stack @@ -118,7 +118,7 @@ particular working environment and set of practices. #. *Set up the Core Development Machines:* As mentioned earlier, core developers work on the contents of the operating system itself. - Following are some best practices for setting up machines used for + Here are some best practices for setting up machines used for developing images: - Have the :term:`OpenEmbedded Build System` available on |