summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorMichael Opdenacker <michael.opdenacker@bootlin.com>2021-05-12 11:30:55 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2021-05-22 12:16:41 +0100
commit5386f28c44700acf92169f80de4d5628ecb40e18 (patch)
treec7920c2982b40af749b6202acb86a664e990864d /documentation/dev-manual
parent020562cfbc3129c3cad7ebc8a5a8447681e5efed (diff)
downloadpoky-5386f28c44700acf92169f80de4d5628ecb40e18.tar.gz
dev-manual: simplify style
(From yocto-docs rev: a8b3c1a5cbfa7fb0bca0d7dd8f38ac59acf032fa) Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/common-tasks.rst139
-rw-r--r--documentation/dev-manual/qemu.rst4
-rw-r--r--documentation/dev-manual/start.rst26
3 files changed, 79 insertions, 90 deletions
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 5c3fc41772..1307341730 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -346,7 +346,7 @@ The application consists of the following sections:
346 of the Yocto Project for which your layer is compatible. 346 of the Yocto Project for which your layer is compatible.
347 347
348- *Acceptance Criteria:* Provide "Yes" or "No" answers for each of the 348- *Acceptance Criteria:* Provide "Yes" or "No" answers for each of the
349 items in the checklist. Space exists at the bottom of the form for 349 items in the checklist. There is space at the bottom of the form for
350 any explanations for items for which you answered "No". 350 any explanations for items for which you answered "No".
351 351
352- *Recommendations:* Provide answers for the questions regarding Linux 352- *Recommendations:* Provide answers for the questions regarding Linux
@@ -542,7 +542,7 @@ important as it ensures that items in the list remain colon-separated.
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 exist 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 ``FILESEXTRAPATHS`` statement.
547 547
548Prioritizing Your Layer 548Prioritizing Your Layer
@@ -1060,8 +1060,8 @@ The remainder of the section provides details for the steps.
1060Locate or Automatically Create a Base Recipe 1060Locate or Automatically Create a Base Recipe
1061-------------------------------------------- 1061--------------------------------------------
1062 1062
1063You can always write a recipe from scratch. However, three choices exist 1063You can always write a recipe from scratch. However, there are three choices
1064that can help you quickly get a start on a new recipe: 1064that can help you quickly get started with a new recipe:
1065 1065
1066- ``devtool add``: A command that assists in creating a recipe and an 1066- ``devtool add``: A command that assists in creating a recipe and an
1067 environment conducive to development. 1067 environment conducive to development.
@@ -1521,8 +1521,8 @@ software is built; and runtime dependencies, which are required to be
1521installed on the target in order for the software to run. 1521installed on the target in order for the software to run.
1522 1522
1523Within a recipe, you specify build-time dependencies using the 1523Within a recipe, you specify build-time dependencies using the
1524:term:`DEPENDS` variable. Although 1524:term:`DEPENDS` variable. Although there are nuances,
1525nuances exist, items specified in ``DEPENDS`` should be names of other 1525items specified in ``DEPENDS`` should be names of other
1526recipes. It is important that you specify all build-time dependencies 1526recipes. It is important that you specify all build-time dependencies
1527explicitly. 1527explicitly.
1528 1528
@@ -2183,8 +2183,8 @@ script to first boot is undesirable and for read-only rootfs impossible.
2183 2183
2184.. note:: 2184.. note::
2185 2185
2186 Equivalent support for pre-install, pre-uninstall, and post-uninstall 2186 There is equivalent support for pre-install, pre-uninstall, and post-uninstall
2187 scripts exist by way of ``pkg_preinst``, ``pkg_prerm``, and ``pkg_postrm``, 2187 scripts by way of ``pkg_preinst``, ``pkg_prerm``, and ``pkg_postrm``,
2188 respectively. These scrips work in exactly the same way as does 2188 respectively. These scrips work in exactly the same way as does
2189 ``pkg_postinst`` with the exception that they run at different times. Also, 2189 ``pkg_postinst`` with the exception that they run at different times. Also,
2190 because of when they run, they are not applicable to being run at image 2190 because of when they run, they are not applicable to being run at image
@@ -2376,7 +2376,7 @@ Packaging Externally Produced Binaries
2376~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2376~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2377 2377
2378Sometimes, you need to add pre-compiled binaries to an image. For 2378Sometimes, you need to add pre-compiled binaries to an image. For
2379example, suppose that binaries for proprietary code exist, which are 2379example, suppose that there are binaries for proprietary code,
2380created by a particular division of a company. Your part of the company 2380created by a particular division of a company. Your part of the company
2381needs to use those binaries as part of an image that you are building 2381needs to use those binaries as part of an image that you are building
2382using the OpenEmbedded build system. Since you only have the binaries 2382using the OpenEmbedded build system. Since you only have the binaries
@@ -2832,7 +2832,7 @@ Over time, upstream developers publish new versions for software built
2832by layer recipes. It is recommended to keep recipes up-to-date with 2832by layer recipes. It is recommended to keep recipes up-to-date with
2833upstream version releases. 2833upstream version releases.
2834 2834
2835While several methods exist that allow you upgrade a recipe, you might 2835While there are several methods to upgrade a recipe, you might
2836consider checking on the upgrade status of a recipe first. You can do so 2836consider checking on the upgrade status of a recipe first. You can do so
2837using the ``devtool check-upgrade-status`` command. See the 2837using the ``devtool check-upgrade-status`` command. See the
2838":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" 2838":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`"
@@ -2861,8 +2861,8 @@ commit messages in the layer's tree for the changes made to recipes.
2861 2861
2862.. note:: 2862.. note::
2863 2863
2864 Conditions do exist when you should not use AUH to upgrade recipes 2864 In some conditions, you should not use AUH to upgrade recipes
2865 and you should instead use either ``devtool upgrade`` or upgrade your 2865 and should instead use either ``devtool upgrade`` or upgrade your
2866 recipes manually: 2866 recipes manually:
2867 2867
2868 - When AUH cannot complete the upgrade sequence. This situation 2868 - When AUH cannot complete the upgrade sequence. This situation
@@ -2922,7 +2922,7 @@ The following steps describe how to set up the AUH utility:
2922 undesirably. 2922 undesirably.
2923 2923
29245. *Make Configurations in Your Local Configuration File:* Several 29245. *Make Configurations in Your Local Configuration File:* Several
2925 settings need to exist in the ``local.conf`` file in the build 2925 settings are needed in the ``local.conf`` file in the build
2926 directory you just created for AUH. Make these following 2926 directory you just created for AUH. Make these following
2927 configurations: 2927 configurations:
2928 2928
@@ -3131,8 +3131,8 @@ newly upgraded recipe::
3131 NOTE: nano: compiling from external source tree /home/scottrif/poky/build/workspace/sources/nano 3131 NOTE: nano: compiling from external source tree /home/scottrif/poky/build/workspace/sources/nano
3132 NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded. 3132 NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded.
3133 3133
3134Within the ``devtool upgrade`` workflow, opportunity 3134Within the ``devtool upgrade`` workflow, you can
3135exists to deploy and test your rebuilt software. For this example, 3135deploy and test your rebuilt software. For this example,
3136however, running ``devtool finish`` cleans up the workspace once the 3136however, running ``devtool finish`` cleans up the workspace once the
3137source in your workspace is clean. This usually means using Git to stage 3137source in your workspace is clean. This usually means using Git to stage
3138and submit commits for the changes generated by the upgrade process. 3138and submit commits for the changes generated by the upgrade process.
@@ -3214,7 +3214,7 @@ To manually upgrade recipe versions, follow these general steps:
3214 if the recipe is to be released publicly. 3214 if the recipe is to be released publicly.
3215 3215
32165. *Check the Upstream Change Log or Release Notes:* Checking both these 32165. *Check the Upstream Change Log or Release Notes:* Checking both these
3217 reveals if new features exist that could break 3217 reveals if there are new features that could break
3218 backwards-compatibility. If so, you need to take steps to mitigate or 3218 backwards-compatibility. If so, you need to take steps to mitigate or
3219 eliminate that situation. 3219 eliminate that situation.
3220 3220
@@ -3517,7 +3517,7 @@ Building a Simple Image
3517 3517
3518In the development environment, you need to build an image whenever you 3518In the development environment, you need to build an image whenever you
3519change hardware support, add or change system libraries, or add or 3519change hardware support, add or change system libraries, or add or
3520change services that have dependencies. Several methods exist that allow 3520change services that have dependencies. There are several methods that allow
3521you to build an image within the Yocto Project. This section presents 3521you to build an image within the Yocto Project. This section presents
3522the basic steps you need to build a simple image using BitBake from a 3522the basic steps you need to build a simple image using BitBake from a
3523build host running Linux. 3523build host running Linux.
@@ -4215,7 +4215,7 @@ your tunings to best consider build times and package feed maintenance.
4215 sysroot for each machine is generated, the software is not recompiled 4215 sysroot for each machine is generated, the software is not recompiled
4216 and only one package feed exists. 4216 and only one package feed exists.
4217 4217
4218- *Manage Granular Level Packaging:* Sometimes cases exist where 4218- *Manage Granular Level Packaging:* Sometimes there are cases where
4219 injecting another level of package architecture beyond the three 4219 injecting another level of package architecture beyond the three
4220 higher levels noted earlier can be useful. For example, consider how 4220 higher levels noted earlier can be useful. For example, consider how
4221 NXP (formerly Freescale) allows for the easy reuse of binary packages 4221 NXP (formerly Freescale) allows for the easy reuse of binary packages
@@ -4281,7 +4281,7 @@ By default, the OpenEmbedded build system uses the
4281code. The build process involves fetching the source files, unpacking 4281code. The build process involves fetching the source files, unpacking
4282them, and then patching them if necessary before the build takes place. 4282them, and then patching them if necessary before the build takes place.
4283 4283
4284Situations exist where you might want to build software from source 4284There are situations where you might want to build software from source
4285files that are external to and thus outside of the OpenEmbedded build 4285files that are external to and thus outside of the OpenEmbedded build
4286system. For example, suppose you have a project that includes a new BSP 4286system. For example, suppose you have a project that includes a new BSP
4287with a heavily customized kernel. And, you want to minimize exposing the 4287with a heavily customized kernel. And, you want to minimize exposing the
@@ -4648,7 +4648,7 @@ libraries and other binaries to use a different set of libraries. The
4648libraries could differ in architecture, compiler options, or other 4648libraries could differ in architecture, compiler options, or other
4649optimizations. 4649optimizations.
4650 4650
4651Several examples exist in the ``meta-skeleton`` layer found in the 4651There are several examples in the ``meta-skeleton`` layer found in the
4652:term:`Source Directory`: 4652:term:`Source Directory`:
4653 4653
4654- ``conf/multilib-example.conf`` configuration file 4654- ``conf/multilib-example.conf`` configuration file
@@ -4661,7 +4661,7 @@ Preparing to Use Multilib
4661~~~~~~~~~~~~~~~~~~~~~~~~~ 4661~~~~~~~~~~~~~~~~~~~~~~~~~
4662 4662
4663User-specific requirements drive the Multilib feature. Consequently, 4663User-specific requirements drive the Multilib feature. Consequently,
4664there is no one "out-of-the-box" configuration that likely exists to 4664there is no one "out-of-the-box" configuration that would
4665meet your needs. 4665meet your needs.
4666 4666
4667In order to enable Multilib, you first need to ensure your recipe is 4667In order to enable Multilib, you first need to ensure your recipe is
@@ -4724,8 +4724,8 @@ specifically with a command like this::
4724Additional Implementation Details 4724Additional Implementation Details
4725~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4725~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4726 4726
4727Generic implementation details as well as details that are specific to 4727There are generic implementation details as well as details that are specific to
4728package management systems exist. Following are implementation details 4728package management systems. Following are implementation details
4729that exist regardless of the package management system: 4729that exist regardless of the package management system:
4730 4730
4731- The typical convention used for the class extension code as used by 4731- The typical convention used for the class extension code as used by
@@ -4742,8 +4742,7 @@ that exist regardless of the package management system:
4742 vendor string presently break Autoconf's ``config.sub``, and other 4742 vendor string presently break Autoconf's ``config.sub``, and other
4743 separators are problematic for different reasons. 4743 separators are problematic for different reasons.
4744 4744
4745For the RPM Package Management System, the following implementation 4745Here are the implementation details for the RPM Package Management System:
4746details exist:
4747 4746
4748- A unique architecture is defined for the Multilib packages, along 4747- A unique architecture is defined for the Multilib packages, along
4749 with creating a unique deploy folder under ``tmp/deploy/rpm`` in the 4748 with creating a unique deploy folder under ``tmp/deploy/rpm`` in the
@@ -4764,8 +4763,7 @@ details exist:
4764- The build system relies on RPM to resolve the identical files in the 4763- The build system relies on RPM to resolve the identical files in the
4765 two (or more) Multilib packages. 4764 two (or more) Multilib packages.
4766 4765
4767For the IPK Package Management System, the following implementation 4766Here are the implementation details for the IPK Package Management System:
4768details exist:
4769 4767
4770- The ``${MLPREFIX}`` is not stripped from ``${PN}`` during IPK 4768- The ``${MLPREFIX}`` is not stripped from ``${PN}`` during IPK
4771 packaging. The naming for a normal RPM package and a Multilib IPK 4769 packaging. The naming for a normal RPM package and a Multilib IPK
@@ -4783,9 +4781,9 @@ details exist:
4783Installing Multiple Versions of the Same Library 4781Installing Multiple Versions of the Same Library
4784------------------------------------------------ 4782------------------------------------------------
4785 4783
4786Situations can exist where you need to install and use multiple versions 4784There are be situations where you need to install and use multiple versions
4787of the same library on the same system at the same time. These 4785of the same library on the same system at the same time. This
4788situations almost always exist when a library API changes and you have 4786almost always happens when a library API changes and you have
4789multiple pieces of software that depend on the separate versions of the 4787multiple pieces of software that depend on the separate versions of the
4790library. To accommodate these situations, you can install multiple 4788library. To accommodate these situations, you can install multiple
4791versions of the same library in parallel on the same system. 4789versions of the same library in parallel on the same system.
@@ -4850,9 +4848,9 @@ follows:
4850- You can create and boot ``core-image-minimal`` and 4848- You can create and boot ``core-image-minimal`` and
4851 ``core-image-sato`` images. 4849 ``core-image-sato`` images.
4852 4850
4853- RPM Package Manager (RPM) support exists for x32 binaries. 4851- There is RPM Package Manager (RPM) support for x32 binaries.
4854 4852
4855- Support for large images exists. 4853- There is support for large images.
4856 4854
4857To use the x32 psABI, you need to edit your ``conf/local.conf`` 4855To use the x32 psABI, you need to edit your ``conf/local.conf``
4858configuration file as follows:: 4856configuration file as follows::
@@ -4918,7 +4916,7 @@ library package involves the following:
4918 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` 4916 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
4919 and that "qemu-usermode" is not in 4917 and that "qemu-usermode" is not in
4920 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. 4918 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
4921 If either of these conditions exist, nothing will happen. 4919 In either of these conditions, nothing will happen.
4922 4920
49233. Try to build the recipe. If you encounter build errors that look like 49213. Try to build the recipe. If you encounter build errors that look like
4924 something is unable to find ``.so`` libraries, check where these 4922 something is unable to find ``.so`` libraries, check where these
@@ -5005,7 +5003,7 @@ working in an image:
5005Known Issues 5003Known Issues
5006------------ 5004------------
5007 5005
5008The following know issues exist for GObject Introspection Support: 5006Here are know issues in GObject Introspection Support:
5009 5007
5010- ``qemu-ppc64`` immediately crashes. Consequently, you cannot build 5008- ``qemu-ppc64`` immediately crashes. Consequently, you cannot build
5011 introspection data on that architecture. 5009 introspection data on that architecture.
@@ -5184,7 +5182,7 @@ For example, the following returns overview help for Wic::
5184 5182
5185 $ wic help overview 5183 $ wic help overview
5186 5184
5187One additional level of help exists for Wic. You can get help on 5185There is one additional level of help for Wic. You can get help on
5188individual images through the ``list`` command. You can use the ``list`` 5186individual images through the ``list`` command. You can use the ``list``
5189command to return the available Wic images as follows:: 5187command to return the available Wic images as follows::
5190 5188
@@ -5872,8 +5870,8 @@ your image more secure.
5872General Considerations 5870General Considerations
5873---------------------- 5871----------------------
5874 5872
5875General considerations exist that help you create more secure images. 5873There are general considerations that help you create more secure images.
5876You should consider the following suggestions to help make your device 5874You should consider the following suggestions to make your device
5877more secure: 5875more secure:
5878 5876
5879- Scan additional code you are adding to the system (e.g. application 5877- Scan additional code you are adding to the system (e.g. application
@@ -6210,8 +6208,8 @@ or to not install a package at all.
6210 6208
6211The following list introduces variables you can use to prevent packages 6209The following list introduces variables you can use to prevent packages
6212from being installed into your image. Each of these variables only works 6210from being installed into your image. Each of these variables only works
6213with IPK and RPM package types. Support for Debian packages does not 6211with IPK and RPM package types, not for Debian packages.
6214exist. Also, you can use these variables from your ``local.conf`` file 6212Also, you can use these variables from your ``local.conf`` file
6215or attach them to a specific image recipe by using a recipe name 6213or attach them to a specific image recipe by using a recipe name
6216override. For more detail on the variables, see the descriptions in the 6214override. For more detail on the variables, see the descriptions in the
6217Yocto Project Reference Manual's glossary chapter. 6215Yocto Project Reference Manual's glossary chapter.
@@ -6285,7 +6283,7 @@ maintain a package feed that is compatible with existing package manager
6285applications such as RPM, APT, and OPKG, using an automated system is 6283applications such as RPM, APT, and OPKG, using an automated system is
6286much preferred over a manual system. In either system, the main 6284much preferred over a manual system. In either system, the main
6287requirement is that binary package version numbering increases in a 6285requirement is that binary package version numbering increases in a
6288linear fashion and that a number of version components exist that 6286linear fashion and that there is a number of version components that
6289support that linear progression. For information on how to ensure 6287support that linear progression. For information on how to ensure
6290package revisioning remains linear, see the 6288package revisioning remains linear, see the
6291":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" 6289":ref:`dev-manual/common-tasks:automatically incrementing a package version number`"
@@ -6342,7 +6340,7 @@ generated are just "self consistent". The build system adds and removes
6342packages and there are no guarantees about upgrade paths but images will 6340packages and there are no guarantees about upgrade paths but images will
6343be consistent and correct with the latest changes. 6341be consistent and correct with the latest changes.
6344 6342
6345The simplest form for a PR Service is for it to exist for a single host 6343The simplest form for a PR Service is for a single host
6346development system that builds the package feed (building system). For 6344development system that builds the package feed (building system). For
6347this scenario, you can enable a local PR Service by setting 6345this scenario, you can enable a local PR Service by setting
6348:term:`PRSERV_HOST` in your 6346:term:`PRSERV_HOST` in your
@@ -6545,7 +6543,7 @@ The previous example specifies a number of things in the call to
6545 "Lighttpd module for alias". 6543 "Lighttpd module for alias".
6546 6544
6547Often, packaging modules is as simple as the previous example. However, 6545Often, packaging modules is as simple as the previous example. However,
6548more advanced options exist that you can use within 6546there are more advanced options that you can use within
6549``do_split_packages`` to modify its behavior. And, if you need to, you 6547``do_split_packages`` to modify its behavior. And, if you need to, you
6550can add more logic by specifying a hook function that is called for each 6548can add more logic by specifying a hook function that is called for each
6551package. It is also perfectly acceptable to call ``do_split_packages`` 6549package. It is also perfectly acceptable to call ``do_split_packages``
@@ -7024,7 +7022,7 @@ file::
7024 `passphrase`. 7022 `passphrase`.
7025 7023
7026Aside from the ``RPM_GPG_NAME`` and ``RPM_GPG_PASSPHRASE`` variables in 7024Aside from the ``RPM_GPG_NAME`` and ``RPM_GPG_PASSPHRASE`` variables in
7027the previous example, two optional variables related to signing exist: 7025the previous example, two optional variables related to signing are available:
7028 7026
7029- *GPG_BIN:* Specifies a ``gpg`` binary/wrapper that is executed 7027- *GPG_BIN:* Specifies a ``gpg`` binary/wrapper that is executed
7030 when the package is signed. 7028 when the package is signed.
@@ -7046,14 +7044,14 @@ your ``local.config`` or ``distro.config`` file::
7046 PACKAGE_FEED_GPG_NAME = "key_name" 7044 PACKAGE_FEED_GPG_NAME = "key_name"
7047 PACKAGE_FEED_GPG_PASSPHRASE_FILE = "path_to_file_containing_passphrase" 7045 PACKAGE_FEED_GPG_PASSPHRASE_FILE = "path_to_file_containing_passphrase"
7048 7046
7049For signed package feeds, the passphrase must exist in a separate file, 7047For signed package feeds, the passphrase must be specified in a separate file,
7050which is pointed to by the ``PACKAGE_FEED_GPG_PASSPHRASE_FILE`` 7048which is pointed to by the ``PACKAGE_FEED_GPG_PASSPHRASE_FILE``
7051variable. Regarding security, keeping a plain text passphrase out of the 7049variable. Regarding security, keeping a plain text passphrase out of the
7052configuration is more secure. 7050configuration is more secure.
7053 7051
7054Aside from the ``PACKAGE_FEED_GPG_NAME`` and 7052Aside from the ``PACKAGE_FEED_GPG_NAME`` and
7055``PACKAGE_FEED_GPG_PASSPHRASE_FILE`` variables, three optional variables 7053``PACKAGE_FEED_GPG_PASSPHRASE_FILE`` variables, three optional variables
7056related to signed package feeds exist: 7054related to signed package feeds are available:
7057 7055
7058- *GPG_BIN* Specifies a ``gpg`` binary/wrapper that is executed 7056- *GPG_BIN* Specifies a ``gpg`` binary/wrapper that is executed
7059 when the package is signed. 7057 when the package is signed.
@@ -7192,7 +7190,7 @@ use this fetcher in combination with
7192:doc:`devtool </ref-manual/devtool-reference>` to create 7190:doc:`devtool </ref-manual/devtool-reference>` to create
7193recipes that produce NPM packages. 7191recipes that produce NPM packages.
7194 7192
7195Two workflows exist that allow you to create NPM packages using 7193There are two workflows that allow you to create NPM packages using
7196``devtool``: the NPM registry modules method and the NPM project code 7194``devtool``: the NPM registry modules method and the NPM project code
7197method. 7195method.
7198 7196
@@ -7296,7 +7294,7 @@ The ``devtool edit-recipe`` command lets you take a look at the recipe::
7296 ... 7294 ...
7297 LICENSE_${PN}-vary = "MIT" 7295 LICENSE_${PN}-vary = "MIT"
7298 7296
7299Three key points exist in the previous example: 7297Here are three key points in the previous example:
7300 7298
7301- :term:`SRC_URI` uses the NPM 7299- :term:`SRC_URI` uses the NPM
7302 scheme so that the NPM fetcher is used. 7300 scheme so that the NPM fetcher is used.
@@ -7488,7 +7486,7 @@ Selecting an Initialization Manager
7488=================================== 7486===================================
7489 7487
7490By default, the Yocto Project uses SysVinit as the initialization 7488By default, the Yocto Project uses SysVinit as the initialization
7491manager. However, support also exists for systemd, which is a full 7489manager. However, there is also support for systemd, which is a full
7492replacement for init with parallel starting of services, reduced shell 7490replacement for init with parallel starting of services, reduced shell
7493overhead and other features that are used by many distributions. 7491overhead and other features that are used by many distributions.
7494 7492
@@ -7794,7 +7792,7 @@ link to the built library and that library will be pulled into your
7794image along with the new software even if you did not want the library. 7792image along with the new software even if you did not want the library.
7795 7793
7796The :ref:`buildhistory <ref-classes-buildhistory>` 7794The :ref:`buildhistory <ref-classes-buildhistory>`
7797class exists to help you maintain the quality of your build output. You 7795class helps you maintain the quality of your build output. You
7798can use the class to highlight unexpected and possibly unwanted changes 7796can use the class to highlight unexpected and possibly unwanted changes
7799in the build output. When you enable build history, it records 7797in the build output. When you enable build history, it records
7800information about the contents of each package and image and then 7798information about the contents of each package and image and then
@@ -7849,7 +7847,7 @@ variable. Here is an example abbreviated listing:
7849.. image:: figures/buildhistory.png 7847.. image:: figures/buildhistory.png
7850 :align: center 7848 :align: center
7851 7849
7852At the top level, a ``metadata-revs`` file exists that lists the 7850At the top level, there is a ``metadata-revs`` file that lists the
7853revisions of the repositories for the enabled layers when the build was 7851revisions of the repositories for the enabled layers when the build was
7854produced. The rest of the data splits into separate ``packages``, 7852produced. The rest of the data splits into separate ``packages``,
7855``images`` and ``sdk`` directories, the contents of which are described 7853``images`` and ``sdk`` directories, the contents of which are described
@@ -7885,7 +7883,7 @@ The exceptions are ``FILELIST``, which is the actual list of files in
7885the package, and ``PKGSIZE``, which is the total size of files in the 7883the package, and ``PKGSIZE``, which is the total size of files in the
7886package in bytes. 7884package in bytes.
7887 7885
7888A file also exists that corresponds to the recipe from which the package 7886There is also a file that corresponds to the recipe from which the package
7889came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``): 7887came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``):
7890 7888
7891.. code-block:: none 7889.. code-block:: none
@@ -7900,8 +7898,8 @@ came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``):
7900 busybox-staticdev busybox-dev busybox-doc busybox-locale busybox 7898 busybox-staticdev busybox-dev busybox-doc busybox-locale busybox
7901 7899
7902Finally, for those recipes fetched from a version control system (e.g., 7900Finally, for those recipes fetched from a version control system (e.g.,
7903Git), a file exists that lists source revisions that are specified in 7901Git), there is a file that lists source revisions that are specified in
7904the recipe and lists the actual revisions used during the build. Listed 7902the recipe and the actual revisions used during the build. Listed
7905and actual revisions might differ when 7903and actual revisions might differ when
7906:term:`SRCREV` is set to 7904:term:`SRCREV` is set to
7907${:term:`AUTOREV`}. Here is an 7905${:term:`AUTOREV`}. Here is an
@@ -8141,7 +8139,7 @@ You need to realize,
8141however, that this method does show changes that are not significant 8139however, that this method does show changes that are not significant
8142(e.g. a package's size changing by a few bytes). 8140(e.g. a package's size changing by a few bytes).
8143 8141
8144A command-line tool called ``buildhistory-diff`` does exist, though, 8142There is a command-line tool called ``buildhistory-diff``, though,
8145that queries the Git repository and prints just the differences that 8143that queries the Git repository and prints just the differences that
8146might be significant in human-readable form. Here is an example:: 8144might be significant in human-readable form. Here is an example::
8147 8145
@@ -8315,7 +8313,7 @@ the MAC address of the device.
8315In order to run tests on hardware, you need to set ``TEST_TARGET`` to an 8313In order to run tests on hardware, you need to set ``TEST_TARGET`` to an
8316appropriate value. For QEMU, you do not have to change anything, the 8314appropriate value. For QEMU, you do not have to change anything, the
8317default value is "qemu". For running tests on hardware, the following 8315default value is "qemu". For running tests on hardware, the following
8318options exist: 8316options are available:
8319 8317
8320- *"simpleremote":* Choose "simpleremote" if you are going to run tests 8318- *"simpleremote":* Choose "simpleremote" if you are going to run tests
8321 on a target system that is already running the image to be tested and 8319 on a target system that is already running the image to be tested and
@@ -8639,7 +8637,7 @@ layer's ``layer.conf`` file as normal). Just remember the following:
8639 8637
8640- Do not use module names that collide with existing core tests. 8638- Do not use module names that collide with existing core tests.
8641 8639
8642- Minimally, an empty ``__init__.py`` file must exist in the runtime 8640- Minimally, an empty ``__init__.py`` file must be present in the runtime
8643 directory. 8641 directory.
8644 8642
8645To create a new test, start by copying an existing module (e.g. 8643To create a new test, start by copying an existing module (e.g.
@@ -8719,7 +8717,7 @@ Class attributes are as follows:
8719Instance Attributes 8717Instance Attributes
8720~~~~~~~~~~~~~~~~~~~ 8718~~~~~~~~~~~~~~~~~~~
8721 8719
8722A single instance attribute exists, which is ``target``. The ``target`` 8720There is a single instance attribute, which is ``target``. The ``target``
8723instance attribute is identical to the class attribute of the same name, 8721instance attribute is identical to the class attribute of the same name,
8724which is described in the previous section. This attribute exists as 8722which is described in the previous section. This attribute exists as
8725both an instance and class attribute so tests can use 8723both an instance and class attribute so tests can use
@@ -9348,7 +9346,7 @@ Recipe Logging Mechanisms
9348 9346
9349The Yocto Project provides several logging functions for producing 9347The Yocto Project provides several logging functions for producing
9350debugging output and reporting errors and warnings. For Python 9348debugging output and reporting errors and warnings. For Python
9351functions, the following logging functions exist. All of these functions 9349functions, the following logging functions are available. All of these functions
9352log to ``${T}/log.do_``\ `task`, and can also log to standard output 9350log to ``${T}/log.do_``\ `task`, and can also log to standard output
9353(stdout) with the right settings: 9351(stdout) with the right settings:
9354 9352
@@ -9454,8 +9452,8 @@ A parallel ``make`` race occurs when the build consists of several parts
9454that are run simultaneously and a situation occurs when the output or 9452that are run simultaneously and a situation occurs when the output or
9455result of one part is not ready for use with a different part of the 9453result of one part is not ready for use with a different part of the
9456build that depends on that output. Parallel make races are annoying and 9454build that depends on that output. Parallel make races are annoying and
9457can sometimes be difficult to reproduce and fix. However, some simple 9455can sometimes be difficult to reproduce and fix. However, there are some simple
9458tips and tricks exist that can help you debug and fix them. This section 9456tips and tricks that can help you debug and fix them. This section
9459presents a real-world example of an error encountered on the Yocto 9457presents a real-world example of an error encountered on the Yocto
9460Project autobuilder and the process used to fix it. 9458Project autobuilder and the process used to fix it.
9461 9459
@@ -9578,7 +9576,7 @@ In the ``devshell``, do the following::
9578 $ make tools/snep-send.o 9576 $ make tools/snep-send.o
9579 9577
9580The ``devshell`` commands cause the failure to clearly 9578The ``devshell`` commands cause the failure to clearly
9581be visible. In this case, a missing dependency exists for the "neard" 9579be visible. In this case, there is a missing dependency for the ``neard``
9582Makefile target. Here is some abbreviated, sample output with the 9580Makefile target. Here is some abbreviated, sample output with the
9583missing dependency clearly visible at the end:: 9581missing dependency clearly visible at the end::
9584 9582
@@ -9623,9 +9621,8 @@ patch::
9623 $ quilt refresh 9621 $ quilt refresh
9624 Refreshed patch patches/parallelmake.patch 9622 Refreshed patch patches/parallelmake.patch
9625 9623
9626Once 9624Once the patch file is created, you need to add it back to the originating
9627the patch file exists, you need to add it back to the originating recipe 9625recipe folder. Here is an example assuming a top-level
9628folder. Here is an example assuming a top-level
9629:term:`Source Directory` named ``poky``:: 9626:term:`Source Directory` named ``poky``::
9630 9627
9631 $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard 9628 $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard
@@ -10119,7 +10116,7 @@ specific uses.
10119 10116
10120The Yocto Project uses a mailing list and a patch-based workflow that is 10117The Yocto Project uses a mailing list and a patch-based workflow that is
10121similar to the Linux kernel but contains important differences. In 10118similar to the Linux kernel but contains important differences. In
10122general, a mailing list exists through which you can submit patches. You 10119general, there is a mailing list through which you can submit patches. You
10123should send patches to the appropriate mailing list so that they can be 10120should send patches to the appropriate mailing list so that they can be
10124reviewed and merged by the appropriate maintainer. The specific mailing 10121reviewed and merged by the appropriate maintainer. The specific mailing
10125list you need to use depends on the location of the code you are 10122list you need to use depends on the location of the code you are
@@ -10796,8 +10793,8 @@ Here are some other scenarios:
10796Other Variables Related to Commercial Licenses 10793Other Variables Related to Commercial Licenses
10797~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 10794~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10798 10795
10799Other helpful variables related to commercial license handling exist and 10796There are other helpful variables related to commercial license handling,
10800are defined in the 10797defined in the
10801``poky/meta/conf/distro/include/default-distrovars.inc`` file:: 10798``poky/meta/conf/distro/include/default-distrovars.inc`` file::
10802 10799
10803 COMMERCIAL_AUDIO_PLUGINS ?= "" 10800 COMMERCIAL_AUDIO_PLUGINS ?= ""
@@ -10841,7 +10838,7 @@ requirements during a software release.
10841With hundreds of different open source licenses that the Yocto Project 10838With hundreds of different open source licenses that the Yocto Project
10842tracks, it is difficult to know the requirements of each and every 10839tracks, it is difficult to know the requirements of each and every
10843license. However, the requirements of the major FLOSS licenses can begin 10840license. However, the requirements of the major FLOSS licenses can begin
10844to be covered by assuming that three main areas of concern exist: 10841to be covered by assuming that there are three main areas of concern:
10845 10842
10846- Source code must be provided. 10843- Source code must be provided.
10847 10844
@@ -11105,9 +11102,9 @@ portion is integrated with the installed Yocto Project
11105The server receives the information collected and saves it in a 11102The server receives the information collected and saves it in a
11106database. 11103database.
11107 11104
11108A live instance of the error reporting server exists at 11105There is a live instance of the error reporting server at
11109https://errors.yoctoproject.org. This server exists so that when 11106https://errors.yoctoproject.org.
11110you want to get help with build failures, you can submit all of the 11107When you want to get help with build failures, you can submit all of the
11111information on the failure easily and then point to the URL in your bug 11108information on the failure easily and then point to the URL in your bug
11112report or send an email to the mailing list. 11109report or send an email to the mailing list.
11113 11110
diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst
index f7366938dd..88a63c1808 100644
--- a/documentation/dev-manual/qemu.rst
+++ b/documentation/dev-manual/qemu.rst
@@ -275,7 +275,7 @@ present, the toolchain is also automatically used.
275 275
276.. note:: 276.. note::
277 277
278 Several mechanisms exist that let you connect to the system running 278 There are several mechanisms to connect to the system running
279 on the QEMU emulator: 279 on the QEMU emulator:
280 280
281 - QEMU provides a framebuffer interface that makes standard consoles 281 - QEMU provides a framebuffer interface that makes standard consoles
@@ -286,7 +286,7 @@ present, the toolchain is also automatically used.
286 that port to run a console. The connection uses standard IP 286 that port to run a console. The connection uses standard IP
287 networking. 287 networking.
288 288
289 - SSH servers exist in some QEMU images. The ``core-image-sato`` 289 - SSH servers are available in some QEMU images. The ``core-image-sato``
290 QEMU image has a Dropbear secure shell (SSH) server that runs with 290 QEMU image has a Dropbear secure shell (SSH) server that runs with
291 the root password disabled. The ``core-image-full-cmdline`` and 291 the root password disabled. The ``core-image-full-cmdline`` and
292 ``core-image-lsb`` QEMU images have OpenSSH instead of Dropbear. 292 ``core-image-lsb`` QEMU images have OpenSSH instead of Dropbear.
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index 18fd8ccf60..c3276c9502 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -36,7 +36,7 @@ particular working environment and set of practices.
36 equipment together and set up your development environment's 36 equipment together and set up your development environment's
37 hardware topology. 37 hardware topology.
38 38
39 The following roles exist: 39 Here are possible roles:
40 40
41 - *Application Developer:* This type of developer does application 41 - *Application Developer:* This type of developer does application
42 level work on top of an existing software stack. 42 level work on top of an existing software stack.
@@ -99,8 +99,7 @@ particular working environment and set of practices.
99 .. note:: 99 .. note::
100 100
101 The setup of these services is beyond the scope of this manual. 101 The setup of these services is beyond the scope of this manual.
102 However, sites such as the following exist that describe how to 102 However, here are sites describing how to perform setup:
103 perform setup:
104 103
105 - `Gitolite <https://gitolite.com>`__: Information for 104 - `Gitolite <https://gitolite.com>`__: Information for
106 ``gitolite``. 105 ``gitolite``.
@@ -190,7 +189,7 @@ particular working environment and set of practices.
190 develop locally using their primary development system. 189 develop locally using their primary development system.
191 190
1929. *Document Policies and Change Flow:* The Yocto Project uses a 1919. *Document Policies and Change Flow:* The Yocto Project uses a
193 hierarchical structure and a pull model. Scripts exist to create and 192 hierarchical structure and a pull model. There are scripts to create and
194 send pull requests (i.e. ``create-pull-request`` and 193 send pull requests (i.e. ``create-pull-request`` and
195 ``send-pull-request``). This model is in line with other open source 194 ``send-pull-request``). This model is in line with other open source
196 projects where maintainers are responsible for specific areas of the 195 projects where maintainers are responsible for specific areas of the
@@ -215,8 +214,8 @@ particular working environment and set of practices.
215 someone else in the community needs them also. 214 someone else in the community needs them also.
216 215
21710. *Development Environment Summary:* Aside from the previous steps, 21610. *Development Environment Summary:* Aside from the previous steps,
218 some best practices exist within the Yocto Project development 217 here are best practices within the Yocto Project development
219 environment. Consider the following: 218 environment:
220 219
221 - Use :ref:`overview-manual/development-environment:git` as the source control 220 - Use :ref:`overview-manual/development-environment:git` as the source control
222 system. 221 system.
@@ -607,8 +606,8 @@ of a given component.
607 606
608 The recommended method for accessing Yocto Project components is to 607 The recommended method for accessing Yocto Project components is to
609 use Git to clone the upstream repository and work from within that 608 use Git to clone the upstream repository and work from within that
610 locally cloned repository. The procedure in this section exists 609 locally cloned repository. However, this section documents how to
611 should you desire a tarball snapshot of any given component. 610 use a tarball snapshot of any given component.
612 611
613Follow these steps to locate and download a particular tarball: 612Follow these steps to locate and download a particular tarball:
614 613
@@ -645,13 +644,6 @@ release. Rather than Git repositories, these files represent snapshot
645tarballs similar to the tarballs located in the Index of Releases 644tarballs similar to the tarballs located in the Index of Releases
646described in the ":ref:`dev-manual/start:accessing index of releases`" section. 645described in the ":ref:`dev-manual/start:accessing index of releases`" section.
647 646
648.. note::
649
650 The recommended method for accessing Yocto Project components is to
651 use Git to clone a repository and work from within that local
652 repository. The procedure in this section exists should you desire a
653 tarball snapshot of any given component.
654
6551. *Go to the Yocto Project Website:* Open The 6471. *Go to the Yocto Project Website:* Open The
656 :yocto_home:`Yocto Project Website <>` in your browser. 648 :yocto_home:`Yocto Project Website <>` in your browser.
657 649
@@ -750,8 +742,8 @@ Follow these steps to create a local version of the upstream
750 ":ref:`dev-manual/start:checking out by tag in poky`" sections, respectively. 742 ":ref:`dev-manual/start:checking out by tag in poky`" sections, respectively.
751 743
752 Once the local repository is created, you can change to that 744 Once the local repository is created, you can change to that
753 directory and check its status. Here, the single "master" branch 745 directory and check its status. The ``master`` branch is checked out
754 exists on your system and by default, it is checked out:: 746 by default::
755 747
756 $ cd poky 748 $ cd poky
757 $ git status 749 $ git status