* [PATCH 0/6] Simplify style around the use of the "exist" verb
@ 2021-05-14 8:35 Michael Opdenacker
2021-05-14 8:35 ` [PATCH 1/6] ref-manual: simplify style Michael Opdenacker
` (5 more replies)
0 siblings, 6 replies; 7+ messages in thread
From: Michael Opdenacker @ 2021-05-14 8:35 UTC (permalink / raw)
To: docs; +Cc: Michael Opdenacker
This patchset, split by manual (or small group of manuals) to
ease the review process, addresses the excess use of the verb
"exist", which is either vague at best, or yields expressions
which can be replaced by much simpler and natural ones.
The resulting text is not always shorter, but should at least
be easier to read.
By trying to simplify such expressions, further style simplifications
are sometimes implemented on the corresponding text, as well as a few formating
fixes, together with missing reference additions.
Note that many paragraphs modified this way could further be simplified,
as well as other ones. However, this will have to be addressed in an
iterative and progressive way.
Michael Opdenacker (6):
ref-manual: simplify style
kernel-dev manual: simplify style
dev-manual: simplify style
sdk-manual: simplify style and fix formating
overview-manual: simplify style and add missings references
manuals: simplify style
documentation/README | 2 +-
documentation/brief-yoctoprojectqs/index.rst | 10 +-
documentation/bsp-guide/bsp.rst | 36 +++--
documentation/dev-manual/common-tasks.rst | 139 +++++++++---------
documentation/dev-manual/qemu.rst | 4 +-
documentation/dev-manual/start.rst | 26 ++--
documentation/kernel-dev/advanced.rst | 12 +-
documentation/kernel-dev/common.rst | 12 +-
documentation/kernel-dev/concepts-appx.rst | 2 +-
documentation/kernel-dev/intro.rst | 6 +-
documentation/kernel-dev/maint-appx.rst | 4 +-
documentation/overview-manual/concepts.rst | 73 +++++----
.../development-environment.rst | 12 +-
documentation/overview-manual/yp-intro.rst | 14 +-
documentation/ref-manual/classes.rst | 12 +-
.../ref-manual/devtool-reference.rst | 10 +-
documentation/ref-manual/faq.rst | 2 +-
documentation/ref-manual/kickstart.rst | 2 +-
documentation/ref-manual/qa-checks.rst | 8 +-
documentation/ref-manual/release-process.rst | 4 +-
documentation/ref-manual/resources.rst | 12 +-
documentation/ref-manual/structure.rst | 8 +-
.../ref-manual/system-requirements.rst | 8 +-
documentation/ref-manual/tasks.rst | 3 +-
documentation/ref-manual/variables.rst | 76 +++++-----
.../sdk-manual/appendix-customizing.rst | 7 +-
documentation/sdk-manual/extensible.rst | 45 +++---
documentation/sdk-manual/intro.rst | 2 +-
documentation/toaster-manual/reference.rst | 6 +-
29 files changed, 265 insertions(+), 292 deletions(-)
--
2.25.1
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH 1/6] ref-manual: simplify style
2021-05-14 8:35 [PATCH 0/6] Simplify style around the use of the "exist" verb Michael Opdenacker
@ 2021-05-14 8:35 ` Michael Opdenacker
2021-05-14 8:35 ` [PATCH 2/6] kernel-dev manual: " Michael Opdenacker
` (4 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Michael Opdenacker @ 2021-05-14 8:35 UTC (permalink / raw)
To: docs; +Cc: Michael Opdenacker
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
documentation/ref-manual/classes.rst | 12 +--
.../ref-manual/devtool-reference.rst | 10 +--
documentation/ref-manual/faq.rst | 2 +-
documentation/ref-manual/kickstart.rst | 2 +-
documentation/ref-manual/qa-checks.rst | 8 +-
documentation/ref-manual/release-process.rst | 4 +-
documentation/ref-manual/resources.rst | 12 ++-
documentation/ref-manual/structure.rst | 8 +-
.../ref-manual/system-requirements.rst | 8 +-
documentation/ref-manual/tasks.rst | 3 +-
documentation/ref-manual/variables.rst | 76 +++++++++----------
11 files changed, 69 insertions(+), 76 deletions(-)
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index ffa17139fe..6dd0cbbd41 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1006,7 +1006,7 @@ package name override, in this example ``${PN}``, must be used::
INSANE_SKIP_${PN} += "dev-so"
Please keep in mind that the QA checks
-exist in order to detect real or potential problems in the packaged
+are meant to detect real or potential problems in the packaged
output. So exercise caution when disabling these checks.
Here are the tests you can list with the ``WARN_QA`` and
@@ -1085,8 +1085,8 @@ Here are the tests you can list with the ``WARN_QA`` and
- ``dev-so:`` Checks that the ``.so`` symbolic links are in the
``-dev`` package and not in any of the other packages. In general,
these symlinks are only useful for development purposes. Thus, the
- ``-dev`` package is the correct location for them. Some very rare
- cases do exist for dynamically loaded modules where these symlinks
+ ``-dev`` package is the correct location for them. In very rare
+ cases, such as dynamically loaded modules, these symlinks
are needed instead in the main package.
- ``file-rdeps:`` Checks that file-level dependencies identified by
@@ -1676,7 +1676,7 @@ couple different ways:
nativesdk-myrecipe.bb
- Not doing so can lead to subtle problems because code exists that
+ Not doing so can lead to subtle problems because there is code that
depends on the naming convention.
Although applied differently, the ``nativesdk`` class is used with both
@@ -1714,10 +1714,10 @@ section in the Yocto Project Development Tasks Manual.
``oelint.bbclass``
==================
-The ``oelint`` class is an obsolete lint checking tool that exists in
+The ``oelint`` class is an obsolete lint checking tool available in
``meta/classes`` in the :term:`Source Directory`.
-A number of classes exist that could be generally useful in OE-Core but
+There are some classes that could be generally useful in OE-Core but
are never actually used within OE-Core itself. The ``oelint`` class is
one such example. However, being aware of this class can reduce the
proliferation of different versions of similar classes across multiple
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 0ce3219831..1862c481df 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -403,8 +403,8 @@ Upgrading a Recipe
As software matures, upstream recipes are upgraded to newer versions. As
a developer, you need to keep your local recipes up-to-date with the
-upstream version releases. Several methods exist by which you can
-upgrade recipes. You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`"
+upstream version releases. There are several ways of upgrading recipes.
+You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`"
section of the Yocto Project Development Tasks Manual. This section
overviews the ``devtool upgrade`` command.
@@ -516,8 +516,8 @@ you do, the package manager is bypassed.
should never use it to update an image that will be used in
production.
-Some conditions exist that could prevent a deployed application from
-behaving as expected. When both of the following conditions exist, your
+Some conditions could prevent a deployed application from
+behaving as expected. When both of the following conditions are met, your
application has the potential to not behave correctly when run on the
target:
@@ -528,7 +528,7 @@ target:
- The target does not physically have the packages on which the
application depends installed.
-If both of these conditions exist, your application will not behave as
+If both of these conditions are met, your application will not behave as
expected. The reason for this misbehavior is because the
``devtool deploy-target`` command does not deploy the packages (e.g.
libraries) on which your new application depends. The assumption is that
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index e7bca829a3..f1b564a60e 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -312,7 +312,7 @@ HTTPS requests and direct them to the ``http://`` sources mirror. You
can use ``file://`` URLs to point to local directories or network shares
as well.
-Aside from the previous technique, these options also exist::
+Here are other options::
BB_NO_NETWORK = "1"
diff --git a/documentation/ref-manual/kickstart.rst b/documentation/ref-manual/kickstart.rst
index 843292b528..8308ffff5b 100644
--- a/documentation/ref-manual/kickstart.rst
+++ b/documentation/ref-manual/kickstart.rst
@@ -210,5 +210,5 @@ supports the following options:
- ``--configfile``: Specifies a user-defined configuration file for
the bootloader. You can provide a full pathname for the file or a
- file that exists in the ``canned-wks`` folder. This option overrides
+ file located in the ``canned-wks`` folder. This option overrides
all other bootloader options.
diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst
index 9cc4c577c7..2e98713a27 100644
--- a/documentation/ref-manual/qa-checks.rst
+++ b/documentation/ref-manual/qa-checks.rst
@@ -97,7 +97,7 @@ Errors and Warnings
- ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]``
- A runtime dependency exists between the two specified packages, but
+ There is a runtime dependency between the two specified packages, but
there is nothing explicit within the recipe to enable the
OpenEmbedded build system to ensure that dependency is satisfied.
This condition is usually triggered by an
@@ -303,7 +303,7 @@ Errors and Warnings
- ``<packagename> rdepends on <debug_packagename> [debug-deps]``
- A dependency exists between the specified non-dbg package (i.e. a
+ There is a dependency between the specified non-dbg package (i.e. a
package whose name does not end in ``-dbg``) and a package that is a
``dbg`` package. The ``dbg`` packages contain debug symbols and are
brought in using several different methods:
@@ -326,7 +326,7 @@ Errors and Warnings
- ``<packagename> rdepends on <dev_packagename> [dev-deps]``
- A dependency exists between the specified non-dev package (a package
+ There is a dependency between the specified non-dev package (a package
whose name does not end in ``-dev``) and a package that is a ``dev``
package. The ``dev`` packages contain development headers and are
usually brought in using several different methods:
@@ -753,6 +753,6 @@ how to work with the QA checks, see the
.. note::
- Please keep in mind that the QA checks exist in order to detect real
+ Please keep in mind that the QA checks are meant to detect real
or potential problems in the packaged output. So exercise caution
when disabling these checks.
diff --git a/documentation/ref-manual/release-process.rst b/documentation/ref-manual/release-process.rst
index 93ab6ed08a..935a2e39bb 100644
--- a/documentation/ref-manual/release-process.rst
+++ b/documentation/ref-manual/release-process.rst
@@ -82,14 +82,14 @@ stable release.
bug fixes and security fixes only. Policy dictates that features are
not backported to a stable release. This policy means generic recipe
version upgrades are unlikely to be accepted for backporting. The
- exception to this policy occurs when a strong reason exists such as
+ exception to this policy occurs when there is a strong reason such as
the fix happens to also be the preferred upstream approach.
Stable release branches have strong maintenance for about a year after
their initial release. Should significant issues be found for any
release regardless of its age, fixes could be backported to older
releases. For issues that are not backported given an older release,
-Community LTS trees and branches exist where community members share
+Community LTS trees and branches allow community members to share
patches for older releases. However, these types of patches do not go
through the same release process as do point releases. You can find more
information about stable branch maintenance at
diff --git a/documentation/ref-manual/resources.rst b/documentation/ref-manual/resources.rst
index 663f0d96d5..5ffd2b3991 100644
--- a/documentation/ref-manual/resources.rst
+++ b/documentation/ref-manual/resources.rst
@@ -10,7 +10,7 @@ Introduction
============
The Yocto Project team is happy for people to experiment with the Yocto
-Project. A number of places exist to find help if you run into
+Project. There is a number of places where you can find help if you run into
difficulties or find bugs. This presents information about contributing
and participating in the Yocto Project.
@@ -43,8 +43,7 @@ the Yocto Project itself (e.g. when discovering an issue with some
component of the build system that acts contrary to the documentation or
your expectations).
-A general procedure and guidelines exist for when you use Bugzilla to
-submit a bug. For information on how to use Bugzilla to submit a bug
+For a general procedure and guidelines on how to use Bugzilla to submit a bug
against the Yocto Project, see the following:
- The ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`"
@@ -59,7 +58,7 @@ For information on Bugzilla in general, see https://www.bugzilla.org/about/.
Mailing lists
=============
-A number of mailing lists maintained by the Yocto Project exist as well
+There are multiple mailing lists maintained by the Yocto Project as well
as related OpenEmbedded mailing lists for discussion, patch submission
and announcements. To subscribe to one of the following mailing lists,
click on the appropriate URL in the following list and follow the
@@ -156,9 +155,8 @@ Here is a list of resources you might find helpful:
- :yocto_docs:`Yocto Project Mega-Manual </singleindex.html>`\ *:* This manual
is simply a single HTML file comprised of the bulk of the Yocto
- Project manuals. The Mega-Manual primarily exists as a vehicle by
- which you can easily search for phrases and terms used in the Yocto
- Project documentation set.
+ Project manuals. It makes it easy to search for phrases and terms used
+ in the Yocto Project documentation set.
- :doc:`/profile-manual/index` *:* This manual presents a set of
common and generally useful tracing and profiling schemes along with
diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
index 2106a8083b..36c9efc1e2 100644
--- a/documentation/ref-manual/structure.rst
+++ b/documentation/ref-manual/structure.rst
@@ -510,8 +510,8 @@ should be automatic, and recipes should not directly reference
-----------------------
Previous versions of the OpenEmbedded build system used to create a
-global shared sysroot per machine along with a native sysroot. Beginning
-with the 2.3 version of the Yocto Project, sysroots exist in
+global shared sysroot per machine along with a native sysroot. Since
+the 2.3 version of the Yocto Project, there are sysroots in
recipe-specific :term:`WORKDIR` directories. Thus, the
``build/tmp/sysroots/`` directory is unused.
@@ -601,7 +601,7 @@ constructed using the architecture of the given build (e.g.
name, and the version of the recipe (i.e.
:term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`).
-A number of key subdirectories exist within each recipe work directory:
+Here are key subdirectories within each recipe work directory:
- ``${WORKDIR}/temp``: Contains the log files of each task executed for
this recipe, the "run" files for each executed task, which contain
@@ -624,7 +624,7 @@ A number of key subdirectories exist within each recipe work directory:
- ``${WORKDIR}/packages-split``: Contains the output of the
``do_package`` task after the output has been split into individual
- packages. Subdirectories exist for each individual package created by
+ packages. There are subdirectories for each individual package created by
the recipe.
- ``${WORKDIR}/recipe-sysroot``: A directory populated with the target
diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index fc251945db..87d68df493 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -66,9 +66,8 @@ distributions:
- While the Yocto Project Team attempts to ensure all Yocto Project
releases are one hundred percent compatible with each officially
- supported Linux distribution, instances might exist where you
- encounter a problem while using the Yocto Project on a specific
- distribution.
+ supported Linux distribution, you may still encounter problems
+ that happen only with a specific distribution.
- Yocto Project releases are tested against the stable Linux
distributions in the above list. The Yocto Project should work
@@ -119,8 +118,7 @@ supported Ubuntu or Debian Linux distribution:
- If your build system has the ``oss4-dev`` package installed, you
might experience QEMU build failures due to the package installing
its own custom ``/usr/include/linux/soundcard.h`` on the Debian
- system. If you run into this situation, either of the following
- solutions exist::
+ system. If you run into this situation, try either of these solutions::
$ sudo apt-get build-dep qemu
$ sudo apt-get remove oss4-dev
diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst
index 001edf6bb3..5bceb79b8d 100644
--- a/documentation/ref-manual/tasks.rst
+++ b/documentation/ref-manual/tasks.rst
@@ -823,6 +823,5 @@ sections from a size-sensitive configuration.
After the kernel is unpacked but before it is patched, this task makes
sure that the machine and metadata branches as specified by the
:term:`SRCREV` variables actually exist on the specified
-branches. If these branches do not exist and
-:term:`AUTOREV` is not being used, the
+branches. Otherwise, if :term:`AUTOREV` is not being used, the
``do_validate_branches`` task fails during the build.
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 0b61f77cb4..a3401a4f1b 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -49,10 +49,9 @@ system and gives an overview of their function and contents.
alternatives system to create a different binary naming scheme so the
commands can co-exist.
- To use the variable, list out the package's commands that also exist
- as part of another package. For example, if the ``busybox`` package
- has four commands that also exist as part of another package, you
- identify them as follows::
+ To use the variable, list out the package's commands that are also
+ provided by another package. For example, if the ``busybox`` package
+ has four such commands, you identify them as follows::
ALTERNATIVE_busybox = "sh sed test bracket"
@@ -306,8 +305,8 @@ system and gives an overview of their function and contents.
variable), the OpenEmbedded build system ignores your request and
will install the packages to avoid dependency errors.
- Support for this variable exists only when using the IPK and RPM
- packaging backend. Support does not exist for DEB.
+ This variable is supported only when using the IPK and RPM
+ packaging backends. DEB is not supported.
See the :term:`NO_RECOMMENDATIONS` and the
:term:`PACKAGE_EXCLUDE` variables for related
@@ -336,8 +335,8 @@ system and gives an overview of their function and contents.
- This host list is only used if ``BB_NO_NETWORK`` is either not set
or set to "0".
- - Limited support for wildcard matching against the beginning of
- host names exists. For example, the following setting matches
+ - There is limited support for wildcard matching against the beginning of
+ host names. For example, the following setting matches
``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``.
::
@@ -558,7 +557,7 @@ system and gives an overview of their function and contents.
:term:`BBCLASSEXTEND`
Allows you to extend a recipe so that it builds variants of the
- software. Common variants for recipes exist such as "natives" like
+ software. There are common variants for recipes as "natives" like
``quilt-native``, which is a copy of Quilt built to run on the build
system; "crosses" such as ``gcc-cross``, which is a compiler built to
run on the build machine but produces binaries that run on the target
@@ -1237,7 +1236,7 @@ system and gives an overview of their function and contents.
CONFFILES_${PN} += "${sysconfdir}/file1 \
${sysconfdir}/file2 ${sysconfdir}/file3"
- A relationship exists between the ``CONFFILES`` and ``FILES``
+ There is a relationship between the ``CONFFILES`` and ``FILES``
variables. The files listed within ``CONFFILES`` must be a subset of
the files listed within ``FILES``. Because the configuration files
you provide with ``CONFFILES`` are simply being identified so that
@@ -1417,8 +1416,8 @@ system and gives an overview of their function and contents.
:term:`COREBASE_FILES`
Lists files from the :term:`COREBASE` directory that
should be copied other than the layers listed in the
- ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for
- the purpose of copying metadata from the OpenEmbedded build system
+ ``bblayers.conf`` file. The ``COREBASE_FILES`` variable allows
+ to copy metadata from the OpenEmbedded build system
into the extensible SDK.
Explicitly listing files in ``COREBASE`` is needed because it
@@ -2460,8 +2459,8 @@ system and gives an overview of their function and contents.
``FILESEXTRAPATHS`` variable.
You can take advantage of this searching behavior in useful ways. For
- example, consider a case where the following directory structure
- exists for general and machine-specific configurations::
+ example, consider a case where there is the following directory structure
+ for general and machine-specific configurations::
files/defconfig
files/MACHINEA/defconfig
@@ -3013,8 +3012,8 @@ system and gives an overview of their function and contents.
Image recipes set ``IMAGE_INSTALL`` to specify the packages to
install into an image through ``image.bbclass``. Additionally,
- "helper" classes such as the
- :ref:`core-image <ref-classes-core-image>` class exist that can
+ there are "helper" classes such as the
+ :ref:`core-image <ref-classes-core-image>` class which can
take lists used with ``IMAGE_FEATURES`` and turn them into
auto-generated entries in ``IMAGE_INSTALL`` in addition to its
default contents.
@@ -3465,8 +3464,8 @@ system and gives an overview of their function and contents.
Use of the ``INHIBIT_SYSROOT_STRIP`` variable occurs in rare and
special circumstances. For example, suppose you are building
bare-metal firmware by using an external GCC toolchain. Furthermore,
- even if the toolchain's binaries are strippable, other files exist
- that are needed for the build that are not strippable.
+ even if the toolchain's binaries are strippable, there are other files
+ needed for the build that are not strippable.
:term:`INITRAMFS_FSTYPES`
Defines the format for the output image of an initial RAM filesystem
@@ -3817,7 +3816,7 @@ system and gives an overview of their function and contents.
.. note::
- Legacy support exists for specifying the full path to the device
+ There is legacy support for specifying the full path to the device
tree. However, providing just the ``.dtb`` file is preferred.
In order to use this variable, the
@@ -4042,7 +4041,7 @@ system and gives an overview of their function and contents.
:term:`KERNELDEPMODDEPEND`
Specifies whether the data referenced through
- :term:`PKGDATA_DIR` is needed or not. The
+ :term:`PKGDATA_DIR` is needed or not.
``KERNELDEPMODDEPEND`` does not control whether or not that data
exists, but simply whether or not it is used. If you do not need to
use the data, set the ``KERNELDEPMODDEPEND`` variable in your
@@ -4227,8 +4226,8 @@ system and gives an overview of their function and contents.
- Separate license names using \| (pipe) when there is a choice
between licenses.
- - Separate license names using & (ampersand) when multiple licenses
- exist that cover different parts of the source.
+ - Separate license names using & (ampersand) when there are
+ multiple licenses for different parts of the source.
- You can use spaces between license names.
@@ -4376,8 +4375,8 @@ system and gives an overview of their function and contents.
The variable corresponds to a machine configuration file of the same
name, through which machine-specific configurations are set. Thus,
- when ``MACHINE`` is set to "qemux86" there exists the corresponding
- ``qemux86.conf`` machine configuration file, which can be found in
+ when ``MACHINE`` is set to "qemux86", the corresponding
+ ``qemux86.conf`` machine configuration file can be found in
the :term:`Source Directory` in
``meta/conf/machine``.
@@ -4742,7 +4741,7 @@ system and gives an overview of their function and contents.
:term:`NO_GENERIC_LICENSE`
Avoids QA errors when you use a non-common, non-CLOSED license in a
- recipe. Packages exist, such as the linux-firmware package, with many
+ recipe. There are packages, such as the linux-firmware package, with many
licenses that are not in any way common. Also, new licenses are added
occasionally to avoid introducing a lot of common license files,
which are only applicable to a specific package.
@@ -4786,8 +4785,8 @@ system and gives an overview of their function and contents.
functionality, such as kernel modules. It is up to you to add
packages with the :term:`IMAGE_INSTALL` variable.
- Support for this variable exists only when using the IPK and RPM
- packaging backend. Support does not exist for DEB.
+ This variable is only supported when using the IPK and RPM
+ packaging backends. DEB is not supported.
See the :term:`BAD_RECOMMENDATIONS` and
the :term:`PACKAGE_EXCLUDE` variables for
@@ -5064,8 +5063,8 @@ system and gives an overview of their function and contents.
an iterative development process to remove specific components from a
system.
- Support for this variable exists only when using the IPK and RPM
- packaging backend. Support does not exist for DEB.
+ This variable is supported only when using the IPK and RPM
+ packaging backends. DEB is not supported.
See the :term:`NO_RECOMMENDATIONS` and the
:term:`BAD_RECOMMENDATIONS` variables for
@@ -6211,7 +6210,7 @@ system and gives an overview of their function and contents.
:term:`PACKAGE_EXCLUDE` variables.
Packages specified in ``RRECOMMENDS`` need not actually be produced.
- However, a recipe must exist that provides each package, either
+ However, there must be a recipe providing each package, either
through the :term:`PACKAGES` or
:term:`PACKAGES_DYNAMIC` variables or the
:term:`RPROVIDES` variable, or an error will occur
@@ -6979,8 +6978,8 @@ system and gives an overview of their function and contents.
- ``az://`` - Fetches files from an Azure Storage account.
- Standard and recipe-specific options for ``SRC_URI`` exist. Here are
- standard options:
+ There are standard and recipe-specific options for ``SRC_URI``. Here are
+ standard ones:
- ``apply`` - Whether to apply the patch or not. The default
action is to apply the patch.
@@ -7667,8 +7666,8 @@ system and gives an overview of their function and contents.
:term:`TARGET_OS`
Specifies the target's operating system. The variable can be set to
"linux" for glibc-based systems (GNU C Library) and to "linux-musl"
- for musl libc. For ARM/EABI targets, "linux-gnueabi" and
- "linux-musleabi" possible values exist.
+ for musl libc. For ARM/EABI targets, the possible values are
+ "linux-gnueabi" and "linux-musleabi".
:term:`TARGET_PREFIX`
Specifies the prefix used for the toolchain binary target tools.
@@ -8369,11 +8368,10 @@ system and gives an overview of their function and contents.
configure options are simply not passed to the configure script (e.g.
should be removed from :term:`EXTRA_OECONF` or
:term:`PACKAGECONFIG_CONFARGS`).
- However, common options, for example, exist that are passed to all
- configure scripts at a class level that might not be valid for some
- configure scripts. It follows that no benefit exists in seeing a
- warning about these options. For these cases, the options are added
- to ``UNKNOWN_CONFIGURE_WHITELIST``.
+ However, there are common options that are passed to all
+ configure scripts at a class level, but might not be valid for some
+ configure scripts. Therefore warnings about these options are useless.
+ For these cases, the options are added to ``UNKNOWN_CONFIGURE_WHITELIST``.
The configure arguments check that uses
``UNKNOWN_CONFIGURE_WHITELIST`` is part of the
--
2.25.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 2/6] kernel-dev manual: simplify style
2021-05-14 8:35 [PATCH 0/6] Simplify style around the use of the "exist" verb Michael Opdenacker
2021-05-14 8:35 ` [PATCH 1/6] ref-manual: simplify style Michael Opdenacker
@ 2021-05-14 8:35 ` Michael Opdenacker
2021-05-14 8:35 ` [PATCH 3/6] dev-manual: " Michael Opdenacker
` (3 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Michael Opdenacker @ 2021-05-14 8:35 UTC (permalink / raw)
To: docs; +Cc: Michael Opdenacker
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
documentation/kernel-dev/advanced.rst | 12 ++++++------
documentation/kernel-dev/common.rst | 12 ++++++------
documentation/kernel-dev/concepts-appx.rst | 2 +-
documentation/kernel-dev/intro.rst | 6 +++---
documentation/kernel-dev/maint-appx.rst | 4 ++--
5 files changed, 18 insertions(+), 18 deletions(-)
diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst
index b0d03851b3..0e745c375d 100644
--- a/documentation/kernel-dev/advanced.rst
+++ b/documentation/kernel-dev/advanced.rst
@@ -21,7 +21,7 @@ is the ``yocto-kernel-cache`` Git repository. You can find this repository
grouped under the "Yocto Linux Kernel" heading in the
:yocto_git:`Yocto Project Source Repositories <>`.
-Kernel development tools ("kern-tools") exist also in the Yocto Project
+Kernel development tools ("kern-tools") are also available in the Yocto Project
Source Repositories under the "Yocto Linux Kernel" heading in the
``yocto-kernel-tools`` Git repository. The recipe that builds these
tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in
@@ -313,7 +313,7 @@ The following listings show the ``build.scc`` file and part of the
The description file can
include multiple patch statements where each statement handles a single
-patch. In the example ``build.scc`` file, five patch statements exist
+patch. In the example ``build.scc`` file, there are five patch statements
for the five patches in the directory.
You can create a typical ``.patch`` file using ``diff -Nurp`` or
@@ -509,8 +509,8 @@ description as meeting the criteria set by the recipe being built. This
example supports the "beaglebone" machine for the "standard" kernel and
the "arm" architecture.
-Be aware that a hard link between the ``KTYPE`` variable and a kernel
-type description file does not exist. Thus, if you do not have the
+Be aware that there is no hard link between the ``KTYPE`` variable and a kernel
+type description file. Thus, if you do not have the
kernel type defined in your kernel Metadata as it is here, you only need
to ensure that the
:term:`LINUX_KERNEL_TYPE`
@@ -776,8 +776,8 @@ patches in every kernel you build (i.e. have the patches as part of the
lone "master" branch). It is situations like these that give rise to
multiple branches used within a Linux kernel sources Git repository.
-Repository organization strategies exist that maximize source reuse,
-remove redundancy, and logically order your changes. This section
+Here are repository organization strategies maximizing source reuse,
+removing redundancy, and logically ordering your changes. This section
presents strategies for the following cases:
- Encapsulating patches in a feature description and only including the
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 0fede0c012..f64cbab56c 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -578,7 +578,7 @@ recipe is processed.
.. note::
- Other methods exist to accomplish grouping and defining configuration
+ There are other ways of grouping and defining configuration
options. For example, if you are working with a local clone of the
kernel repository, you could checkout the kernel's ``meta`` branch,
make your changes, and then push the changes to the local bare clone
@@ -781,8 +781,8 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
.. note::
- During the checkout operation, a bug exists that could cause
- errors such as the following to appear:
+ During the checkout operation, there is a bug that could cause
+ errors such as the following:
.. code-block:: none
@@ -1306,7 +1306,7 @@ steps:
$ bitbake linux-yocto -c kernel_configme -f
This step ensures that you create a
- ``.config`` file from a known state. Because situations exist where
+ ``.config`` file from a known state. Because there are situations where
your build state might become unknown, it is best to run this task
prior to starting ``menuconfig``.
@@ -1536,7 +1536,7 @@ Working with a "Dirty" Kernel Version String
============================================
If you build a kernel image and the version string has a "+" or a
-"-dirty" at the end, uncommitted modifications exist in the kernel's
+"-dirty" at the end, it means there are uncommitted modifications in the kernel's
source directory. Follow these steps to clean up the version string:
1. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
@@ -1615,7 +1615,7 @@ Here are some basic steps you can use to work with your own sources:
Running the ``make defconfig`` command results in the default
configuration for your architecture as defined by your kernel.
- However, no guarantee exists that this configuration is valid for
+ However, there is no guarantee that this configuration is valid for
your use case, or that your board will even boot. This is
particularly true for non-x86 architectures.
diff --git a/documentation/kernel-dev/concepts-appx.rst b/documentation/kernel-dev/concepts-appx.rst
index 2101f374cb..cf2e75d853 100644
--- a/documentation/kernel-dev/concepts-appx.rst
+++ b/documentation/kernel-dev/concepts-appx.rst
@@ -213,7 +213,7 @@ BSP-specific commits. In other words, the divisions of the kernel are
transparent and are not relevant to the developer on a day-to-day basis.
From the developer's perspective, this path is the "master" branch in
Git terms. The developer does not need to be aware of the existence of
-any other branches at all. Of course, value exists in the having these
+any other branches at all. Of course, it can make sense to have these
branches in the tree, should a person decide to explore them. For
example, a comparison between two BSPs at either the commit level or at
the line-by-line code ``diff`` level is now a trivial operation.
diff --git a/documentation/kernel-dev/intro.rst b/documentation/kernel-dev/intro.rst
index 5592f74c82..e406f6e47f 100644
--- a/documentation/kernel-dev/intro.rst
+++ b/documentation/kernel-dev/intro.rst
@@ -66,9 +66,9 @@ from the continual kernel integration and testing performed during
development of the Yocto Project.
If, instead, you have a very specific Linux kernel source tree and are
-unable to align with one of the official Yocto Linux kernel recipes, an
-alternative exists by which you can use the Yocto Project Linux kernel
-tools with your own kernel sources.
+unable to align with one of the official Yocto Linux kernel recipes,
+you have a way to use the Yocto Project Linux kernel tools with your
+own kernel sources.
The remainder of this manual provides instructions for completing
specific Linux kernel development tasks. These instructions assume you
diff --git a/documentation/kernel-dev/maint-appx.rst b/documentation/kernel-dev/maint-appx.rst
index f84ab6e239..3354de5f0c 100644
--- a/documentation/kernel-dev/maint-appx.rst
+++ b/documentation/kernel-dev/maint-appx.rst
@@ -175,7 +175,7 @@ Build Strategy
Once you have cloned a Yocto Linux kernel repository and the cache
repository (``yocto-kernel-cache``) onto your development system, you
can consider the compilation phase of kernel development, which is
-building a kernel image. Some prerequisites exist that are validated by
+building a kernel image. Some prerequisites are validated by
the build process before compilation starts:
- The :term:`SRC_URI` points to the
@@ -194,7 +194,7 @@ the build process before compilation starts:
In the previous example, the "yocto-4.12" branch is checked out in
the ``yocto-kernel-cache`` repository.
-The OpenEmbedded build system makes sure these conditions exist before
+The OpenEmbedded build system makes sure these conditions are satisfied before
attempting compilation. Other means, however, do exist, such as
bootstrapping a BSP.
--
2.25.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 3/6] dev-manual: simplify style
2021-05-14 8:35 [PATCH 0/6] Simplify style around the use of the "exist" verb Michael Opdenacker
2021-05-14 8:35 ` [PATCH 1/6] ref-manual: simplify style Michael Opdenacker
2021-05-14 8:35 ` [PATCH 2/6] kernel-dev manual: " Michael Opdenacker
@ 2021-05-14 8:35 ` Michael Opdenacker
2021-05-14 8:35 ` [PATCH 4/6] sdk-manual: simplify style and fix formating Michael Opdenacker
` (2 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Michael Opdenacker @ 2021-05-14 8:35 UTC (permalink / raw)
To: docs; +Cc: Michael Opdenacker
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
documentation/dev-manual/common-tasks.rst | 139 +++++++++++-----------
documentation/dev-manual/qemu.rst | 4 +-
documentation/dev-manual/start.rst | 26 ++--
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:
of the Yocto Project for which your layer is compatible.
- *Acceptance Criteria:* Provide "Yes" or "No" answers for each of the
- items in the checklist. Space exists at the bottom of the form for
+ items in the checklist. There is space at the bottom of the form for
any explanations for items for which you answered "No".
- *Recommendations:* Provide answers for the questions regarding Linux
@@ -542,7 +542,7 @@ important as it ensures that items in the list remain colon-separated.
paths in the final list.
Also, not all append files add extra files. Many append files simply
- exist to add build options (e.g. ``systemd``). For these cases, your
+ allow to add build options (e.g. ``systemd``). For these cases, your
append file would not even use the ``FILESEXTRAPATHS`` statement.
Prioritizing Your Layer
@@ -1060,8 +1060,8 @@ The remainder of the section provides details for the steps.
Locate or Automatically Create a Base Recipe
--------------------------------------------
-You can always write a recipe from scratch. However, three choices exist
-that can help you quickly get a start on a new recipe:
+You can always write a recipe from scratch. However, there are three choices
+that can help you quickly get started with a new recipe:
- ``devtool add``: A command that assists in creating a recipe and an
environment conducive to development.
@@ -1521,8 +1521,8 @@ software is built; and runtime dependencies, which are required to be
installed on the target in order for the software to run.
Within a recipe, you specify build-time dependencies using the
-:term:`DEPENDS` variable. Although
-nuances exist, items specified in ``DEPENDS`` should be names of other
+:term:`DEPENDS` variable. Although there are nuances,
+items specified in ``DEPENDS`` should be names of other
recipes. It is important that you specify all build-time dependencies
explicitly.
@@ -2183,8 +2183,8 @@ script to first boot is undesirable and for read-only rootfs impossible.
.. note::
- Equivalent support for pre-install, pre-uninstall, and post-uninstall
- scripts exist by way of ``pkg_preinst``, ``pkg_prerm``, and ``pkg_postrm``,
+ There is equivalent support for pre-install, pre-uninstall, and post-uninstall
+ scripts by way of ``pkg_preinst``, ``pkg_prerm``, and ``pkg_postrm``,
respectively. These scrips work in exactly the same way as does
``pkg_postinst`` with the exception that they run at different times. Also,
because of when they run, they are not applicable to being run at image
@@ -2376,7 +2376,7 @@ Packaging Externally Produced Binaries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes, you need to add pre-compiled binaries to an image. For
-example, suppose that binaries for proprietary code exist, which are
+example, suppose that there are binaries for proprietary code,
created by a particular division of a company. Your part of the company
needs to use those binaries as part of an image that you are building
using the OpenEmbedded build system. Since you only have the binaries
@@ -2832,7 +2832,7 @@ Over time, upstream developers publish new versions for software built
by layer recipes. It is recommended to keep recipes up-to-date with
upstream version releases.
-While several methods exist that allow you upgrade a recipe, you might
+While there are several methods to upgrade a recipe, you might
consider checking on the upgrade status of a recipe first. You can do so
using the ``devtool check-upgrade-status`` command. See the
":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.
.. note::
- Conditions do exist when you should not use AUH to upgrade recipes
- and you should instead use either ``devtool upgrade`` or upgrade your
+ In some conditions, you should not use AUH to upgrade recipes
+ and should instead use either ``devtool upgrade`` or upgrade your
recipes manually:
- When AUH cannot complete the upgrade sequence. This situation
@@ -2922,7 +2922,7 @@ The following steps describe how to set up the AUH utility:
undesirably.
5. *Make Configurations in Your Local Configuration File:* Several
- settings need to exist in the ``local.conf`` file in the build
+ settings are needed in the ``local.conf`` file in the build
directory you just created for AUH. Make these following
configurations:
@@ -3131,8 +3131,8 @@ newly upgraded recipe::
NOTE: nano: compiling from external source tree /home/scottrif/poky/build/workspace/sources/nano
NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded.
-Within the ``devtool upgrade`` workflow, opportunity
-exists to deploy and test your rebuilt software. For this example,
+Within the ``devtool upgrade`` workflow, you can
+deploy and test your rebuilt software. For this example,
however, running ``devtool finish`` cleans up the workspace once the
source in your workspace is clean. This usually means using Git to stage
and submit commits for the changes generated by the upgrade process.
@@ -3214,7 +3214,7 @@ To manually upgrade recipe versions, follow these general steps:
if the recipe is to be released publicly.
5. *Check the Upstream Change Log or Release Notes:* Checking both these
- reveals if new features exist that could break
+ reveals if there are new features that could break
backwards-compatibility. If so, you need to take steps to mitigate or
eliminate that situation.
@@ -3517,7 +3517,7 @@ Building a Simple Image
In the development environment, you need to build an image whenever you
change hardware support, add or change system libraries, or add or
-change services that have dependencies. Several methods exist that allow
+change services that have dependencies. There are several methods that allow
you to build an image within the Yocto Project. This section presents
the basic steps you need to build a simple image using BitBake from a
build host running Linux.
@@ -4215,7 +4215,7 @@ your tunings to best consider build times and package feed maintenance.
sysroot for each machine is generated, the software is not recompiled
and only one package feed exists.
-- *Manage Granular Level Packaging:* Sometimes cases exist where
+- *Manage Granular Level Packaging:* Sometimes there are cases where
injecting another level of package architecture beyond the three
higher levels noted earlier can be useful. For example, consider how
NXP (formerly Freescale) allows for the easy reuse of binary packages
@@ -4281,7 +4281,7 @@ By default, the OpenEmbedded build system uses the
code. The build process involves fetching the source files, unpacking
them, and then patching them if necessary before the build takes place.
-Situations exist where you might want to build software from source
+There are situations where you might want to build software from source
files that are external to and thus outside of the OpenEmbedded build
system. For example, suppose you have a project that includes a new BSP
with 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
libraries could differ in architecture, compiler options, or other
optimizations.
-Several examples exist in the ``meta-skeleton`` layer found in the
+There are several examples in the ``meta-skeleton`` layer found in the
:term:`Source Directory`:
- ``conf/multilib-example.conf`` configuration file
@@ -4661,7 +4661,7 @@ Preparing to Use Multilib
~~~~~~~~~~~~~~~~~~~~~~~~~
User-specific requirements drive the Multilib feature. Consequently,
-there is no one "out-of-the-box" configuration that likely exists to
+there is no one "out-of-the-box" configuration that would
meet your needs.
In order to enable Multilib, you first need to ensure your recipe is
@@ -4724,8 +4724,8 @@ specifically with a command like this::
Additional Implementation Details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Generic implementation details as well as details that are specific to
-package management systems exist. Following are implementation details
+There are generic implementation details as well as details that are specific to
+package management systems. Following are implementation details
that exist regardless of the package management system:
- The typical convention used for the class extension code as used by
@@ -4742,8 +4742,7 @@ that exist regardless of the package management system:
vendor string presently break Autoconf's ``config.sub``, and other
separators are problematic for different reasons.
-For the RPM Package Management System, the following implementation
-details exist:
+Here are the implementation details for the RPM Package Management System:
- A unique architecture is defined for the Multilib packages, along
with creating a unique deploy folder under ``tmp/deploy/rpm`` in the
@@ -4764,8 +4763,7 @@ details exist:
- The build system relies on RPM to resolve the identical files in the
two (or more) Multilib packages.
-For the IPK Package Management System, the following implementation
-details exist:
+Here are the implementation details for the IPK Package Management System:
- The ``${MLPREFIX}`` is not stripped from ``${PN}`` during IPK
packaging. The naming for a normal RPM package and a Multilib IPK
@@ -4783,9 +4781,9 @@ details exist:
Installing Multiple Versions of the Same Library
------------------------------------------------
-Situations can exist where you need to install and use multiple versions
-of the same library on the same system at the same time. These
-situations almost always exist when a library API changes and you have
+There are be situations where you need to install and use multiple versions
+of the same library on the same system at the same time. This
+almost always happens when a library API changes and you have
multiple pieces of software that depend on the separate versions of the
library. To accommodate these situations, you can install multiple
versions of the same library in parallel on the same system.
@@ -4850,9 +4848,9 @@ follows:
- You can create and boot ``core-image-minimal`` and
``core-image-sato`` images.
-- RPM Package Manager (RPM) support exists for x32 binaries.
+- There is RPM Package Manager (RPM) support for x32 binaries.
-- Support for large images exists.
+- There is support for large images.
To use the x32 psABI, you need to edit your ``conf/local.conf``
configuration file as follows::
@@ -4918,7 +4916,7 @@ library package involves the following:
:term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
and that "qemu-usermode" is not in
:term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
- If either of these conditions exist, nothing will happen.
+ In either of these conditions, nothing will happen.
3. Try to build the recipe. If you encounter build errors that look like
something is unable to find ``.so`` libraries, check where these
@@ -5005,7 +5003,7 @@ working in an image:
Known Issues
------------
-The following know issues exist for GObject Introspection Support:
+Here are know issues in GObject Introspection Support:
- ``qemu-ppc64`` immediately crashes. Consequently, you cannot build
introspection data on that architecture.
@@ -5184,7 +5182,7 @@ For example, the following returns overview help for Wic::
$ wic help overview
-One additional level of help exists for Wic. You can get help on
+There is one additional level of help for Wic. You can get help on
individual images through the ``list`` command. You can use the ``list``
command to return the available Wic images as follows::
@@ -5872,8 +5870,8 @@ your image more secure.
General Considerations
----------------------
-General considerations exist that help you create more secure images.
-You should consider the following suggestions to help make your device
+There are general considerations that help you create more secure images.
+You should consider the following suggestions to make your device
more secure:
- Scan additional code you are adding to the system (e.g. application
@@ -6210,8 +6208,8 @@ or to not install a package at all.
The following list introduces variables you can use to prevent packages
from being installed into your image. Each of these variables only works
-with IPK and RPM package types. Support for Debian packages does not
-exist. Also, you can use these variables from your ``local.conf`` file
+with IPK and RPM package types, not for Debian packages.
+Also, you can use these variables from your ``local.conf`` file
or attach them to a specific image recipe by using a recipe name
override. For more detail on the variables, see the descriptions in the
Yocto Project Reference Manual's glossary chapter.
@@ -6285,7 +6283,7 @@ maintain a package feed that is compatible with existing package manager
applications such as RPM, APT, and OPKG, using an automated system is
much preferred over a manual system. In either system, the main
requirement is that binary package version numbering increases in a
-linear fashion and that a number of version components exist that
+linear fashion and that there is a number of version components that
support that linear progression. For information on how to ensure
package revisioning remains linear, see the
":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
packages and there are no guarantees about upgrade paths but images will
be consistent and correct with the latest changes.
-The simplest form for a PR Service is for it to exist for a single host
+The simplest form for a PR Service is for a single host
development system that builds the package feed (building system). For
this scenario, you can enable a local PR Service by setting
:term:`PRSERV_HOST` in your
@@ -6545,7 +6543,7 @@ The previous example specifies a number of things in the call to
"Lighttpd module for alias".
Often, packaging modules is as simple as the previous example. However,
-more advanced options exist that you can use within
+there are more advanced options that you can use within
``do_split_packages`` to modify its behavior. And, if you need to, you
can add more logic by specifying a hook function that is called for each
package. It is also perfectly acceptable to call ``do_split_packages``
@@ -7024,7 +7022,7 @@ file::
`passphrase`.
Aside from the ``RPM_GPG_NAME`` and ``RPM_GPG_PASSPHRASE`` variables in
-the previous example, two optional variables related to signing exist:
+the previous example, two optional variables related to signing are available:
- *GPG_BIN:* Specifies a ``gpg`` binary/wrapper that is executed
when the package is signed.
@@ -7046,14 +7044,14 @@ your ``local.config`` or ``distro.config`` file::
PACKAGE_FEED_GPG_NAME = "key_name"
PACKAGE_FEED_GPG_PASSPHRASE_FILE = "path_to_file_containing_passphrase"
-For signed package feeds, the passphrase must exist in a separate file,
+For signed package feeds, the passphrase must be specified in a separate file,
which is pointed to by the ``PACKAGE_FEED_GPG_PASSPHRASE_FILE``
variable. Regarding security, keeping a plain text passphrase out of the
configuration is more secure.
Aside from the ``PACKAGE_FEED_GPG_NAME`` and
``PACKAGE_FEED_GPG_PASSPHRASE_FILE`` variables, three optional variables
-related to signed package feeds exist:
+related to signed package feeds are available:
- *GPG_BIN* Specifies a ``gpg`` binary/wrapper that is executed
when the package is signed.
@@ -7192,7 +7190,7 @@ use this fetcher in combination with
:doc:`devtool </ref-manual/devtool-reference>` to create
recipes that produce NPM packages.
-Two workflows exist that allow you to create NPM packages using
+There are two workflows that allow you to create NPM packages using
``devtool``: the NPM registry modules method and the NPM project code
method.
@@ -7296,7 +7294,7 @@ The ``devtool edit-recipe`` command lets you take a look at the recipe::
...
LICENSE_${PN}-vary = "MIT"
-Three key points exist in the previous example:
+Here are three key points in the previous example:
- :term:`SRC_URI` uses the NPM
scheme so that the NPM fetcher is used.
@@ -7488,7 +7486,7 @@ Selecting an Initialization Manager
===================================
By default, the Yocto Project uses SysVinit as the initialization
-manager. However, support also exists for systemd, which is a full
+manager. However, there is also support for systemd, which is a full
replacement for init with parallel starting of services, reduced shell
overhead and other features that are used by many distributions.
@@ -7794,7 +7792,7 @@ link to the built library and that library will be pulled into your
image along with the new software even if you did not want the library.
The :ref:`buildhistory <ref-classes-buildhistory>`
-class exists to help you maintain the quality of your build output. You
+class helps you maintain the quality of your build output. You
can use the class to highlight unexpected and possibly unwanted changes
in the build output. When you enable build history, it records
information about the contents of each package and image and then
@@ -7849,7 +7847,7 @@ variable. Here is an example abbreviated listing:
.. image:: figures/buildhistory.png
:align: center
-At the top level, a ``metadata-revs`` file exists that lists the
+At the top level, there is a ``metadata-revs`` file that lists the
revisions of the repositories for the enabled layers when the build was
produced. The rest of the data splits into separate ``packages``,
``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
the package, and ``PKGSIZE``, which is the total size of files in the
package in bytes.
-A file also exists that corresponds to the recipe from which the package
+There is also a file that corresponds to the recipe from which the package
came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``):
.. code-block:: none
@@ -7900,8 +7898,8 @@ came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``):
busybox-staticdev busybox-dev busybox-doc busybox-locale busybox
Finally, for those recipes fetched from a version control system (e.g.,
-Git), a file exists that lists source revisions that are specified in
-the recipe and lists the actual revisions used during the build. Listed
+Git), there is a file that lists source revisions that are specified in
+the recipe and the actual revisions used during the build. Listed
and actual revisions might differ when
:term:`SRCREV` is set to
${:term:`AUTOREV`}. Here is an
@@ -8141,7 +8139,7 @@ You need to realize,
however, that this method does show changes that are not significant
(e.g. a package's size changing by a few bytes).
-A command-line tool called ``buildhistory-diff`` does exist, though,
+There is a command-line tool called ``buildhistory-diff``, though,
that queries the Git repository and prints just the differences that
might be significant in human-readable form. Here is an example::
@@ -8315,7 +8313,7 @@ the MAC address of the device.
In order to run tests on hardware, you need to set ``TEST_TARGET`` to an
appropriate value. For QEMU, you do not have to change anything, the
default value is "qemu". For running tests on hardware, the following
-options exist:
+options are available:
- *"simpleremote":* Choose "simpleremote" if you are going to run tests
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:
- Do not use module names that collide with existing core tests.
-- Minimally, an empty ``__init__.py`` file must exist in the runtime
+- Minimally, an empty ``__init__.py`` file must be present in the runtime
directory.
To create a new test, start by copying an existing module (e.g.
@@ -8719,7 +8717,7 @@ Class attributes are as follows:
Instance Attributes
~~~~~~~~~~~~~~~~~~~
-A single instance attribute exists, which is ``target``. The ``target``
+There is a single instance attribute, which is ``target``. The ``target``
instance attribute is identical to the class attribute of the same name,
which is described in the previous section. This attribute exists as
both an instance and class attribute so tests can use
@@ -9348,7 +9346,7 @@ Recipe Logging Mechanisms
The Yocto Project provides several logging functions for producing
debugging output and reporting errors and warnings. For Python
-functions, the following logging functions exist. All of these functions
+functions, the following logging functions are available. All of these functions
log to ``${T}/log.do_``\ `task`, and can also log to standard output
(stdout) with the right settings:
@@ -9454,8 +9452,8 @@ A parallel ``make`` race occurs when the build consists of several parts
that are run simultaneously and a situation occurs when the output or
result of one part is not ready for use with a different part of the
build that depends on that output. Parallel make races are annoying and
-can sometimes be difficult to reproduce and fix. However, some simple
-tips and tricks exist that can help you debug and fix them. This section
+can sometimes be difficult to reproduce and fix. However, there are some simple
+tips and tricks that can help you debug and fix them. This section
presents a real-world example of an error encountered on the Yocto
Project autobuilder and the process used to fix it.
@@ -9578,7 +9576,7 @@ In the ``devshell``, do the following::
$ make tools/snep-send.o
The ``devshell`` commands cause the failure to clearly
-be visible. In this case, a missing dependency exists for the "neard"
+be visible. In this case, there is a missing dependency for the ``neard``
Makefile target. Here is some abbreviated, sample output with the
missing dependency clearly visible at the end::
@@ -9623,9 +9621,8 @@ patch::
$ quilt refresh
Refreshed patch patches/parallelmake.patch
-Once
-the patch file exists, you need to add it back to the originating recipe
-folder. Here is an example assuming a top-level
+Once the patch file is created, you need to add it back to the originating
+recipe folder. Here is an example assuming a top-level
:term:`Source Directory` named ``poky``::
$ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard
@@ -10119,7 +10116,7 @@ specific uses.
The Yocto Project uses a mailing list and a patch-based workflow that is
similar to the Linux kernel but contains important differences. In
-general, a mailing list exists through which you can submit patches. You
+general, there is a mailing list through which you can submit patches. You
should send patches to the appropriate mailing list so that they can be
reviewed and merged by the appropriate maintainer. The specific mailing
list you need to use depends on the location of the code you are
@@ -10796,8 +10793,8 @@ Here are some other scenarios:
Other Variables Related to Commercial Licenses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Other helpful variables related to commercial license handling exist and
-are defined in the
+There are other helpful variables related to commercial license handling,
+defined in the
``poky/meta/conf/distro/include/default-distrovars.inc`` file::
COMMERCIAL_AUDIO_PLUGINS ?= ""
@@ -10841,7 +10838,7 @@ requirements during a software release.
With hundreds of different open source licenses that the Yocto Project
tracks, it is difficult to know the requirements of each and every
license. However, the requirements of the major FLOSS licenses can begin
-to be covered by assuming that three main areas of concern exist:
+to be covered by assuming that there are three main areas of concern:
- Source code must be provided.
@@ -11105,9 +11102,9 @@ portion is integrated with the installed Yocto Project
The server receives the information collected and saves it in a
database.
-A live instance of the error reporting server exists at
-https://errors.yoctoproject.org. This server exists so that when
-you want to get help with build failures, you can submit all of the
+There is a live instance of the error reporting server at
+https://errors.yoctoproject.org.
+When you want to get help with build failures, you can submit all of the
information on the failure easily and then point to the URL in your bug
report or send an email to the mailing list.
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.
.. note::
- Several mechanisms exist that let you connect to the system running
+ There are several mechanisms to connect to the system running
on the QEMU emulator:
- QEMU provides a framebuffer interface that makes standard consoles
@@ -286,7 +286,7 @@ present, the toolchain is also automatically used.
that port to run a console. The connection uses standard IP
networking.
- - SSH servers exist in some QEMU images. The ``core-image-sato``
+ - SSH servers are available in some QEMU images. The ``core-image-sato``
QEMU image has a Dropbear secure shell (SSH) server that runs with
the root password disabled. The ``core-image-full-cmdline`` and
``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.
equipment together and set up your development environment's
hardware topology.
- The following roles exist:
+ Here are possible roles:
- *Application Developer:* This type of developer does application
level work on top of an existing software stack.
@@ -99,8 +99,7 @@ particular working environment and set of practices.
.. note::
The setup of these services is beyond the scope of this manual.
- However, sites such as the following exist that describe how to
- perform setup:
+ However, here are sites describing how to perform setup:
- `Gitolite <https://gitolite.com>`__: Information for
``gitolite``.
@@ -190,7 +189,7 @@ particular working environment and set of practices.
develop locally using their primary development system.
9. *Document Policies and Change Flow:* The Yocto Project uses a
- hierarchical structure and a pull model. Scripts exist to create and
+ hierarchical structure and a pull model. There are scripts to create and
send pull requests (i.e. ``create-pull-request`` and
``send-pull-request``). This model is in line with other open source
projects where maintainers are responsible for specific areas of the
@@ -215,8 +214,8 @@ particular working environment and set of practices.
someone else in the community needs them also.
10. *Development Environment Summary:* Aside from the previous steps,
- some best practices exist within the Yocto Project development
- environment. Consider the following:
+ here are best practices within the Yocto Project development
+ environment:
- Use :ref:`overview-manual/development-environment:git` as the source control
system.
@@ -607,8 +606,8 @@ of a given component.
The recommended method for accessing Yocto Project components is to
use Git to clone the upstream repository and work from within that
- locally cloned repository. The procedure in this section exists
- should you desire a tarball snapshot of any given component.
+ locally cloned repository. However, this section documents how to
+ use a tarball snapshot of any given component.
Follow these steps to locate and download a particular tarball:
@@ -645,13 +644,6 @@ release. Rather than Git repositories, these files represent snapshot
tarballs similar to the tarballs located in the Index of Releases
described in the ":ref:`dev-manual/start:accessing index of releases`" section.
-.. note::
-
- The recommended method for accessing Yocto Project components is to
- use Git to clone a repository and work from within that local
- repository. The procedure in this section exists should you desire a
- tarball snapshot of any given component.
-
1. *Go to the Yocto Project Website:* Open The
:yocto_home:`Yocto Project Website <>` in your browser.
@@ -750,8 +742,8 @@ Follow these steps to create a local version of the upstream
":ref:`dev-manual/start:checking out by tag in poky`" sections, respectively.
Once the local repository is created, you can change to that
- directory and check its status. Here, the single "master" branch
- exists on your system and by default, it is checked out::
+ directory and check its status. The ``master`` branch is checked out
+ by default::
$ cd poky
$ git status
--
2.25.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 4/6] sdk-manual: simplify style and fix formating
2021-05-14 8:35 [PATCH 0/6] Simplify style around the use of the "exist" verb Michael Opdenacker
` (2 preceding siblings ...)
2021-05-14 8:35 ` [PATCH 3/6] dev-manual: " Michael Opdenacker
@ 2021-05-14 8:35 ` Michael Opdenacker
2021-05-14 8:35 ` [PATCH 5/6] overview-manual: simplify style and add missings references Michael Opdenacker
2021-05-14 8:35 ` [PATCH 6/6] manuals: simplify style Michael Opdenacker
5 siblings, 0 replies; 7+ messages in thread
From: Michael Opdenacker @ 2021-05-14 8:35 UTC (permalink / raw)
To: docs; +Cc: Michael Opdenacker
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
.../sdk-manual/appendix-customizing.rst | 7 ++-
documentation/sdk-manual/extensible.rst | 45 ++++++++++---------
documentation/sdk-manual/intro.rst | 2 +-
3 files changed, 27 insertions(+), 27 deletions(-)
diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst
index fb2d78452b..67b49d9f49 100644
--- a/documentation/sdk-manual/appendix-customizing.rst
+++ b/documentation/sdk-manual/appendix-customizing.rst
@@ -57,8 +57,7 @@ Adjusting the Extensible SDK to Suit Your Build Host's Setup
============================================================
In most cases, the extensible SDK defaults should work with your :term:`Build
-Host`'s setup.
-However, some cases exist for which you might consider making
+Host`'s setup. However, there are cases when you might consider making
adjustments:
- If your SDK configuration inherits additional classes using the
@@ -153,7 +152,7 @@ follows::
SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
-While several ways exist to change this variable, an efficient method is
+While there are several ways of changing this variable, an efficient method is
to set the variable in your distribution's configuration file. Doing so
creates an SDK installer title that applies across your distribution. As
an example, assume you have your own layer for your distribution named
@@ -223,7 +222,7 @@ You can
change this default installation directory by specifically setting the
``SDKEXTPATH`` variable.
-While a number of ways exist through which you can set this variable,
+While there are several ways of setting this variable,
the method that makes the most sense is to set the variable in your
distribution's configuration file. Doing so creates an SDK installer
default directory that applies across your distribution. As an example,
diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst
index 81727e6f28..55bd7f6ebf 100644
--- a/documentation/sdk-manual/extensible.rst
+++ b/documentation/sdk-manual/extensible.rst
@@ -194,7 +194,7 @@ all the commands.
devtool
quick reference.
-Three ``devtool`` subcommands exist that provide entry-points into
+Three ``devtool`` subcommands provide entry-points into
development:
- *devtool add*: Assists in adding new software to be built.
@@ -276,7 +276,7 @@ command:
devtool
always creates a Git repository locally during the extraction.
- Furthermore, the first positional argument srctree in this case
+ Furthermore, the first positional argument ``srctree`` in this case
identifies where the ``devtool add`` command will locate the
extracted code outside of the workspace. You need to specify an
empty directory::
@@ -285,13 +285,13 @@ command:
In summary,
the source code is pulled from fetchuri and extracted into the
- location defined by srctree as a local Git repository.
+ location defined by ``srctree`` as a local Git repository.
Within workspace, ``devtool`` creates a recipe named recipe along
with an associated append file.
- *Right*: The right scenario in the figure represents a situation
- where the srctree has been previously prepared outside of the
+ where the ``srctree`` has been previously prepared outside of the
``devtool`` workspace.
The following command provides a new recipe name and identifies
@@ -437,7 +437,7 @@ command:
locate the source code and any local patch files from other
developers.
- With this scenario, no srctree argument exists. Consequently, the
+ With this scenario, there is no ``srctree`` argument. Consequently, the
default behavior of the ``devtool modify`` command is to extract
the source files pointed to by the ``SRC_URI`` statements into a
local Git structure. Furthermore, the location for the extracted
@@ -483,21 +483,21 @@ command:
under the newly created source tree.
Once the files are located, the command by default extracts them
- into srctree.
+ into ``srctree``.
Within workspace, ``devtool`` creates an append file for the
recipe. The recipe remains in its original location but the source
- files are extracted to the location you provide with srctree.
+ files are extracted to the location you provide with ``srctree``.
- *Right*: The right scenario in the figure represents a situation
- where the source tree (srctree) already exists locally as a
+ where the source tree (``srctree``) already exists locally as a
previously extracted Git structure outside of the ``devtool``
workspace. In this example, the recipe also exists elsewhere
locally in its own layer.
The following command tells ``devtool`` the recipe with which to
work, uses the "-n" option to indicate source does not need to be
- extracted, and uses srctree to point to the previously extracted
+ extracted, and uses ``srctree`` to point to the previously extracted
source files::
$ devtool modify -n recipe srctree
@@ -646,8 +646,9 @@ The following diagram shows the common development flow used with the
code into the ``sources`` directory in the
:ref:`devtool-the-workspace-layer-structure`.
If you want the code extracted to any other location, you need to
- provide the srctree positional argument with the command as follows:
- $ devtool upgrade -V version recipe srctree
+ provide the ``srctree`` positional argument with the command as follows::
+
+ $ devtool upgrade -V version recipe srctree
.. note::
@@ -674,8 +675,8 @@ The following diagram shows the common development flow used with the
are incorporated into the build the next time you build the software
just as are other changes you might have made to the source.
-2. *Resolve any Conflicts created by the Upgrade*: Conflicts could exist
- due to the software being upgraded to a new version. Conflicts occur
+2. *Resolve any Conflicts created by the Upgrade*: Conflicts could happen
+ after upgrading the software to a new version. Conflicts occur
if your recipe specifies some patch files in ``SRC_URI`` that
conflict with changes made in the new version of the software. For
such cases, you need to resolve the conflicts by editing the source
@@ -908,8 +909,8 @@ mind:
similar manner to the environment set up by the SDK's environment
setup script. One easy way to see these variables is to run the
``devtool build`` command on the recipe and then look in
- ``oe-logs/run.do_compile``. Towards the top of this file, a list of
- environment variables exists that are being set. You can take
+ ``oe-logs/run.do_compile``. Towards the top of this file, there is
+ a list of environment variables that are set. You can take
advantage of these variables within the Makefile.
- If the Makefile sets a default for a variable using "=", that default
@@ -1037,8 +1038,8 @@ If you look at the contents of a recipe, you will see that the recipe
does not include complete instructions for building the software.
Instead, common functionality is encapsulated in classes inherited with
the ``inherit`` directive. This technique leaves the recipe to describe
-just the things that are specific to the software being built. A
-:ref:`base <ref-classes-base>` class exists that
+just the things that are specific to the software being built. There is
+a :ref:`base <ref-classes-base>` class that
is implicitly inherited by all recipes and provides the functionality
that most recipes typically need.
@@ -1110,9 +1111,9 @@ Recipes often need to use files provided by other recipes on the
:term:`Build Host`. For example,
an application linking to a common library needs access to the library
itself and its associated headers. The way this access is accomplished
-within the extensible SDK is through the sysroot. One sysroot exists per
+within the extensible SDK is through the sysroot. There is one sysroot per
"machine" for which the SDK is being built. In practical terms, this
-means a sysroot exists for the target machine, and a sysroot exists for
+means there is a sysroot for the target machine, and a sysroot for
the build host.
Recipes should never write files directly into the sysroot. Instead,
@@ -1159,8 +1160,8 @@ example, ``FILES_${PN}`` specifies the files to go into the main package
``${``\ :term:`PN`\ ``}`` evaluates to the
recipe name). The order of the ``PACKAGES`` value is significant. For
each installed file, the first package whose ``FILES`` value matches the
-file is the package into which the file goes. Defaults exist for both
-the ``PACKAGES`` and ``FILES`` variables. Consequently, you might find
+file is the package into which the file goes. Both the ``PACKAGES`` and
+``FILES`` variables have default values. Consequently, you might find
you do not even need to set these variables in your recipe unless the
software the recipe is building installs files into non-standard
locations.
@@ -1230,7 +1231,7 @@ source, you can add the "-s" option as follows::
It is important to remember that building the item from source
takes significantly longer than installing the pre-built artifact. Also,
-if no recipe exists for the item you want to add to the SDK, you must
+if there is no recipe for the item you want to add to the SDK, you must
instead add the item using the ``devtool add`` command.
Applying Updates to an Installed Extensible SDK
diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
index 124d8a8b1f..2f94aaf874 100644
--- a/documentation/sdk-manual/intro.rst
+++ b/documentation/sdk-manual/intro.rst
@@ -214,5 +214,5 @@ You just need to follow these general steps:
within the Yocto Project.
The remainder of this manual describes how to use the extensible and
-standard SDKs. Information also exists in appendix form that describes
+standard SDKs. There is also information in appendix form describing
how you can build, install, and modify an SDK.
--
2.25.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 5/6] overview-manual: simplify style and add missings references
2021-05-14 8:35 [PATCH 0/6] Simplify style around the use of the "exist" verb Michael Opdenacker
` (3 preceding siblings ...)
2021-05-14 8:35 ` [PATCH 4/6] sdk-manual: simplify style and fix formating Michael Opdenacker
@ 2021-05-14 8:35 ` Michael Opdenacker
2021-05-14 8:35 ` [PATCH 6/6] manuals: simplify style Michael Opdenacker
5 siblings, 0 replies; 7+ messages in thread
From: Michael Opdenacker @ 2021-05-14 8:35 UTC (permalink / raw)
To: docs; +Cc: Michael Opdenacker
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
documentation/overview-manual/concepts.rst | 73 +++++++++----------
.../development-environment.rst | 12 +--
documentation/overview-manual/yp-intro.rst | 14 ++--
3 files changed, 46 insertions(+), 53 deletions(-)
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
index 2e3f1af442..e5bdcdad2a 100644
--- a/documentation/overview-manual/concepts.rst
+++ b/documentation/overview-manual/concepts.rst
@@ -139,7 +139,7 @@ hardware-specific configurations allows you to share other metadata by
using a different layer where that metadata might be common across
several pieces of hardware.
-Many layers exist that work in the Yocto Project development environment. The
+There are many layers working in the Yocto Project development environment. The
:yocto_home:`Yocto Project Curated Layer Index </software-overview/layers/>`
and :oe_layerindex:`OpenEmbedded Layer Index <>` both contain layers from
which you can use or leverage.
@@ -370,7 +370,7 @@ BitBake's global behavior. This section takes a closer look at the
layers the build system uses to further control the build. These layers
provide Metadata for the software, machine, and policies.
-In general, three types of layer input exists. You can see them below
+In general, there are three types of layer input. You can see them below
the "User Configuration" box in the `general workflow
figure <overview-manual/concepts:openembedded build system concepts>`:
@@ -427,8 +427,8 @@ Repositories <>` also shows layers categorized under "Yocto Metadata Layers."
.. note::
- Layers exist in the Yocto Project Source Repositories that cannot be
- found in the OpenEmbedded Layer Index. These layers are either
+ There are layers in the Yocto Project Source Repositories that cannot be
+ found in the OpenEmbedded Layer Index. Such layers are either
deprecated or experimental in nature.
BitBake uses the ``conf/bblayers.conf`` file, which is part of the user
@@ -489,7 +489,7 @@ the machine (``conf/machine/machine.conf``) and, of course, the layer
The remainder of the layer is dedicated to specific recipes by function:
``recipes-bsp``, ``recipes-core``, ``recipes-graphics``,
-``recipes-kernel``, and so forth. Metadata can exist for multiple
+``recipes-kernel``, and so forth. There can be metadata for multiple
formfactors, graphics support systems, and so forth.
.. note::
@@ -528,9 +528,7 @@ project that is more dynamic or experimental in nature, a project might
keep source files in a repository controlled by a Source Control Manager
(SCM) such as Git. Pulling source from a repository allows you to
control the point in the repository (the revision) from which you want
-to build software. Finally, a combination of the two might exist, which
-would give the consumer a choice when deciding where to get source
-files.
+to build software. A combination of the two is also possible.
BitBake uses the :term:`SRC_URI`
variable to point to source files regardless of their location. Each
@@ -609,7 +607,7 @@ the specific revision from which to build.
Source Mirror(s)
~~~~~~~~~~~~~~~~
-Two kinds of mirrors exist: pre-mirrors and regular mirrors. The
+There are two kinds of mirrors: pre-mirrors and regular mirrors. The
:term:`PREMIRRORS` and
:term:`MIRRORS` variables point to
these, respectively. BitBake checks pre-mirrors before looking upstream
@@ -667,8 +665,8 @@ package files are kept:
variables are used, respectively.
- :term:`PACKAGE_ARCH`: Defines
- architecture-specific sub-folders. For example, packages could exist
- for the i586 or qemux86 architectures.
+ architecture-specific sub-folders. For example, packages could be
+ available for the i586 or qemux86 architectures.
BitBake uses the
:ref:`do_package_write_* <ref-tasks-package_write_deb>`
@@ -681,8 +679,8 @@ and
":ref:`ref-tasks-package_write_tar`"
sections in the Yocto Project Reference Manual for additional
information. As an example, consider a scenario where an IPK packaging
-manager is being used and package architecture support for both i586 and
-qemux86 exist. Packages for the i586 architecture are placed in
+manager is being used and there is package architecture support for both
+i586 and qemux86. Packages for the i586 architecture are placed in
``build/tmp/deploy/ipk/i586``, while packages for the qemux86
architecture are placed in ``build/tmp/deploy/ipk/qemux86``.
@@ -698,7 +696,7 @@ closer look at each of those areas.
.. note::
- Separate documentation exists for the BitBake tool. See the
+ Documentation for the BitBake tool is available separately. See the
BitBake User Manual
for reference material on BitBake.
@@ -783,12 +781,10 @@ Build Directory's hierarchy:
.. note::
- In the previous figure, notice that two sample hierarchies exist: one
- based on package architecture (i.e.
- PACKAGE_ARCH
- ) and one based on a machine (i.e.
- MACHINE
- ). The underlying structures are identical. The differentiator being
+ In the previous figure, notice that there are two sample hierarchies:
+ one based on package architecture (i.e. :term:`PACKAGE_ARCH`)
+ and one based on a machine (i.e. :term:`MACHINE`).
+ The underlying structures are identical. The differentiator being
what the OpenEmbedded build system is using as a build target (e.g.
general architecture, a build host, an SDK, or a specific machine).
@@ -963,8 +959,7 @@ that part of the build process.
.. note::
- Support for creating feeds directly from the
- deploy/\*
+ Support for creating feeds directly from the ``deploy/*``
directories does not exist. Creating such feeds usually requires some
kind of feed maintenance mechanism that would upload the new packages
into an official package feed (e.g. the Ångström distribution). This
@@ -1156,9 +1151,9 @@ checksum <overview-manual/concepts:checksums (signatures)>`.
OpenEmbedded.
To determine if a task needs to be rerun, BitBake checks if a stamp file
-with a matching input checksum exists for the task. If such a stamp file
-exists, the task's output is assumed to exist and still be valid. If the
-file does not exist, the task is rerun.
+with a matching input checksum exists for the task. In this case,
+the task's output is assumed to exist and still be valid. Otherwise,
+the task is rerun.
.. note::
@@ -1234,14 +1229,14 @@ to run any of the ``do_fetch``, ``do_unpack``, ``do_patch``,
It becomes more complicated if everything can come from an sstate cache
because some objects are simply not required at all. For example, you do
-not need a compiler or native tools, such as quilt, if nothing exists to
-compile or patch. If the ``do_package_write_*`` packages are available
+not need a compiler or native tools, such as quilt, if there isn't anything
+to compile or patch. If the ``do_package_write_*`` packages are available
from sstate, BitBake does not need the ``do_package`` task data.
To handle all these complexities, BitBake runs in two phases. The first
is the "setscene" stage. During this stage, BitBake first checks the
sstate cache for any targets it is planning to build. BitBake does a
-fast check to see if the object exists rather than a complete download.
+fast check to see if the object exists rather than doing a complete download.
If nothing exists, the second phase, which is the setscene stage,
completes and the main build proceeds.
@@ -1366,9 +1361,9 @@ can initialize the environment before using the tools.
All the output files for an SDK are written to the ``deploy/sdk`` folder
inside the :term:`Build Directory` as
-shown in the previous figure. Depending on the type of SDK, several
-variables exist that help configure these files. The following list
-shows the variables associated with an extensible SDK:
+shown in the previous figure. Depending on the type of SDK, there are
+several variables to configure these files. Here are the variables
+associated with an extensible SDK:
- :term:`DEPLOY_DIR`: Points to
the ``deploy`` directory.
@@ -1577,8 +1572,8 @@ Shared State Cache
By design, the OpenEmbedded build system builds everything from scratch
unless :term:`BitBake` can determine
that parts do not need to be rebuilt. Fundamentally, building from
-scratch is attractive as it means all parts are built fresh and no
-possibility of stale data exists that can cause problems. When
+scratch is attractive as it means all parts are built fresh and there is
+no possibility of stale data that can cause problems. When
developers hit problems, they typically default back to building from
scratch so they have a know state from the start.
@@ -1617,7 +1612,7 @@ them if they are deemed to be valid.
- The build system does not maintain
:term:`PR` information as part of
- the shared state packages. Consequently, considerations exist that
+ the shared state packages. Consequently, there are considerations that
affect maintaining shared state feeds. For information on how the
build system works with packages and can track incrementing ``PR``
information, see the ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`"
@@ -1687,7 +1682,7 @@ used to prune the "run" scripts down to the minimum set, thereby
alleviating this problem and making the "run" scripts much more readable
as a bonus.
-So far, solutions for shell scripts exist. What about Python tasks? The
+So far, there are solutions for shell scripts. What about Python tasks? The
same approach applies even though these tasks are more difficult. The
process needs to figure out what variables a Python function accesses
and what functions it calls. Again, the incremental build solution
@@ -1695,7 +1690,7 @@ contains code that first figures out the variable and function
dependencies, and then creates a checksum for the data used as the input
to the task.
-Like the ``WORKDIR`` case, situations exist where dependencies should be
+Like the ``WORKDIR`` case, there can be situations where dependencies should be
ignored. For these situations, you can instruct the build process to
ignore a dependency by using a line like the following::
@@ -1732,7 +1727,7 @@ to add is a policy decision. However, the effect is to generate a master
checksum that combines the basehash and the hashes of the task's
dependencies.
-At the code level, a variety of ways exist by which both the basehash
+At the code level, there are multiple ways by which both the basehash
and the dependent task hashes can be influenced. Within the BitBake
configuration file, you can give BitBake some extra information to help
it construct the basehash. The following statement effectively results
@@ -1961,8 +1956,8 @@ Automatically Added Runtime Dependencies
The OpenEmbedded build system automatically adds common types of runtime
dependencies between packages, which means that you do not need to
explicitly declare the packages using
-:term:`RDEPENDS`. Three automatic
-mechanisms exist (``shlibdeps``, ``pcdeps``, and ``depchains``) that
+:term:`RDEPENDS`. There are three automatic
+mechanisms (``shlibdeps``, ``pcdeps``, and ``depchains``) that
handle shared libraries, package configuration (pkg-config) modules, and
``-dev`` and ``-dbg`` packages, respectively. For other types of runtime
dependencies, you must manually declare the dependencies.
diff --git a/documentation/overview-manual/development-environment.rst b/documentation/overview-manual/development-environment.rst
index 1decf01e43..ab155dc3b0 100644
--- a/documentation/overview-manual/development-environment.rst
+++ b/documentation/overview-manual/development-environment.rst
@@ -71,7 +71,7 @@ section in
the Yocto Project Development Tasks Manual.
If your development host is going to be a system that runs a Linux
-distribution, steps still exist that you must take to prepare the system
+distribution, you must still take steps to prepare the system
for use with the Yocto Project. You need to be sure that the Linux
distribution on the system is one that supports the Yocto Project. You
also need to be sure that the correct set of host packages are installed
@@ -80,8 +80,8 @@ set up a development host that runs Linux, see the
":ref:`dev-manual/start:setting up a native linux host`"
section in the Yocto Project Development Tasks Manual.
-Once your development host is set up to use the Yocto Project, several
-methods exist for you to do work in the Yocto Project environment:
+Once your development host is set up to use the Yocto Project, there
+are several ways of working in the Yocto Project environment:
- *Command Lines, BitBake, and Shells:* Traditional development in the
Yocto Project involves using the :term:`OpenEmbedded Build System`,
@@ -271,7 +271,7 @@ files that are being worked on simultaneously by more than one person.
All this work is done locally on the development host before anything is
pushed to a "contrib" area and examined at the maintainer's level.
-A somewhat formal method exists by which developers commit changes and
+There is a somewhat formal method by which developers commit changes and
push them into the "contrib" area and subsequently request that the
maintainer include them into an upstream branch. This process is called
"submitting a patch" or "submitting a change." For information on
@@ -279,9 +279,9 @@ submitting patches and changes, see the
":ref:`dev-manual/common-tasks:submitting a change to the yocto project`"
section in the Yocto Project Development Tasks Manual.
-In summary, a single point of entry exists for changes into a "master"
+In summary, there is a single point of entry for changes into a "master"
or development branch of the Git repository, which is controlled by the
-project's maintainer. And, a set of developers exist who independently
+project's maintainer. A set of developers independently
develop, test, and submit changes to "contrib" areas for the maintainer
to examine. The maintainer then chooses which changes are going to
become a permanent part of the project.
diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst
index 7a01828c5f..28ed07994a 100644
--- a/documentation/overview-manual/yp-intro.rst
+++ b/documentation/overview-manual/yp-intro.rst
@@ -140,8 +140,7 @@ Here are challenges you might encounter when developing using the Yocto Project:
- *Steep Learning Curve:* The Yocto Project has a steep learning curve
and has many different ways to accomplish similar tasks. It can be
- difficult to choose how to proceed when varying methods exist by
- which to accomplish a given task.
+ difficult to choose between such ways.
- *Understanding What Changes You Need to Make For Your Design Requires
Some Research:* Beyond the simple tutorial stage, understanding what
@@ -156,7 +155,7 @@ Here are challenges you might encounter when developing using the Yocto Project:
workflow <overview-manual/development-environment:the yocto project development environment>`
could be confusing if you are used to traditional desktop and server
software development.
- In a desktop development environment, mechanisms exist to easily pull
+ In a desktop development environment, there are mechanisms to easily pull
and install new packages, which are typically pre-compiled binaries
from servers accessible over the Internet. Using the Yocto Project,
you must modify your configuration and rebuild to add additional
@@ -430,8 +429,8 @@ Yocto Project:
require system administrator privileges. For example, file ownership
or permissions might need to be defined. Pseudo is a tool that you
can either use directly or through the environment variable
- ``LD_PRELOAD``. Either method allows these operations to succeed as
- if system administrator privileges exist even when they do not.
+ ``LD_PRELOAD``. Either method allows these operations to succeed
+ even without system administrator privileges.
Thanks to Pseudo, the Yocto Project never needs root privileges to
build images for your target system.
@@ -579,8 +578,7 @@ software.
This section provides an introduction to the choices or development
methods you have when setting up your Build Host. Depending on your
particular workflow preference and the type of operating system your
-Build Host runs, several choices exist that allow you to use the Yocto
-Project.
+Build Host runs, you have several choices.
.. note::
@@ -790,7 +788,7 @@ Some Basic Terms
================
It helps to understand some basic fundamental terms when learning the
-Yocto Project. Although a list of terms exists in the ":doc:`Yocto Project
+Yocto Project. Although there is a list of terms in the ":doc:`Yocto Project
Terms </ref-manual/terms>`" section of the Yocto Project
Reference Manual, this section provides the definitions of some terms
helpful for getting started:
--
2.25.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 6/6] manuals: simplify style
2021-05-14 8:35 [PATCH 0/6] Simplify style around the use of the "exist" verb Michael Opdenacker
` (4 preceding siblings ...)
2021-05-14 8:35 ` [PATCH 5/6] overview-manual: simplify style and add missings references Michael Opdenacker
@ 2021-05-14 8:35 ` Michael Opdenacker
5 siblings, 0 replies; 7+ messages in thread
From: Michael Opdenacker @ 2021-05-14 8:35 UTC (permalink / raw)
To: docs; +Cc: Michael Opdenacker
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
documentation/README | 2 +-
documentation/brief-yoctoprojectqs/index.rst | 10 +++---
documentation/bsp-guide/bsp.rst | 36 +++++++++-----------
documentation/toaster-manual/reference.rst | 6 ++--
4 files changed, 26 insertions(+), 28 deletions(-)
diff --git a/documentation/README b/documentation/README
index fddf4e706d..3ad23a902d 100644
--- a/documentation/README
+++ b/documentation/README
@@ -32,7 +32,7 @@ these instances.
Manual Organization
===================
-Folders exist for individual manuals as follows:
+Here the folders corresponding to individual manuals:
* sdk-manual - The Yocto Project Software Development Kit (SDK) Developer's Guide.
* bsp-guide - The Yocto Project Board Support Package (BSP) Developer's Guide
diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 6a12b19ca0..7ae4526c42 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -297,7 +297,7 @@ modular development and makes it easier to reuse the layer metadata.
Follow these steps to add a hardware layer:
-#. **Find a Layer:** Lots of hardware layers exist. The Yocto Project
+#. **Find a Layer:** Many hardware layers are available. The Yocto Project
:yocto_git:`Source Repositories <>` has many hardware layers.
This example adds the
`meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
@@ -318,8 +318,8 @@ Follow these steps to add a hardware layer:
Resolving deltas: 100% (13385/13385), done.
Checking connectivity... done.
- The hardware layer now exists
- with other layers inside the Poky reference repository on your build
+ The hardware layer is now available
+ next to other layers inside the Poky reference repository on your build
host as ``meta-altera`` and contains all the metadata needed to
support hardware from Altera, which is owned by Intel.
@@ -431,8 +431,8 @@ information including the website, wiki pages, and user manuals:
information.
- **Yocto Project Mailing Lists:** Related mailing lists provide a forum
- for discussion, patch submission and announcements. Several mailing
- lists exist and are grouped according to areas of concern. See the
+ for discussion, patch submission and announcements. There are several
+ mailing lists grouped by topic. See the
:ref:`ref-manual/resources:mailing lists`
section in the Yocto Project Reference Manual for a complete list of
Yocto Project mailing lists.
diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst
index 0b0b52d904..b46773dedd 100644
--- a/documentation/bsp-guide/bsp.rst
+++ b/documentation/bsp-guide/bsp.rst
@@ -267,7 +267,7 @@ maintain the distinction that the BSP layer, a build system, and tools
are separate components that could be combined in certain end products.
Before looking at the recommended form for the directory structure
-inside a BSP layer, you should be aware that some requirements do exist
+inside a BSP layer, you should be aware that there are some requirements
in order for a BSP layer to be considered compliant with the Yocto
Project. For that list of requirements, see the
":ref:`bsp-guide/bsp:released bsp requirements`" section.
@@ -763,8 +763,8 @@ workflow.
.. note::
- - Four hardware reference BSPs exist that are part of the Yocto
- Project release and are located in the ``poky/meta-yocto-bsp``
+ - There are four hardware reference BSPs in the Yocto
+ Project release, located in the ``poky/meta-yocto-bsp``
BSP layer:
- Texas Instruments Beaglebone (``beaglebone-yocto``)
@@ -773,8 +773,8 @@ workflow.
- Two general IA platforms (``genericx86`` and ``genericx86-64``)
- - Three core Intel BSPs exist as part of the Yocto Project
- release in the ``meta-intel`` layer:
+ - There are three core Intel BSPs in the Yocto Project
+ release, in the ``meta-intel`` layer:
- ``intel-core2-32``, which is a BSP optimized for the Core2
family of CPUs as well as all CPUs prior to the Silvermont
@@ -832,10 +832,8 @@ workflow.
Requirements and Recommendations for Released BSPs
==================================================
-Certain requirements exist for a released BSP to be considered compliant
-with the Yocto Project. Additionally, recommendations also exist. This
-section describes the requirements and recommendations for released
-BSPs.
+This section describes requirements and recommendations for a released
+BSP to be considered compliant with the Yocto Project.
Released BSP Requirements
-------------------------
@@ -864,7 +862,7 @@ Before looking at BSP requirements, you should consider the following:
- It is not required that specific packages or package modifications
exist in the BSP layer, beyond the requirements for general
- compliance with the Yocto Project. For example, no requirement exists
+ compliance with the Yocto Project. For example, there is no requirement
dictating that a specific kernel or kernel version be used in a given
BSP.
@@ -900,7 +898,7 @@ Yocto Project:
- *License File:* You must include a license file in the
``meta-bsp_root_name`` directory. This license covers the BSP
Metadata as a whole. You must specify which license to use since no
- default license exists when one is not specified. See the
+ default license exists. See the
:yocto_git:`COPYING.MIT </meta-raspberrypi/tree/COPYING.MIT>`
file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer
as an example.
@@ -1107,7 +1105,7 @@ system requirements.
unsuitable functionality or quality, you can use an encumbered
version.
-A couple different methods exist within the OpenEmbedded build system to
+There are two different methods within the OpenEmbedded build system to
satisfy the licensing requirements for an encumbered BSP. The following
list describes them in order of preference:
@@ -1186,11 +1184,11 @@ Use these steps to create a BSP layer:
- *Create a Machine Configuration File:* Create a
``conf/machine/bsp_root_name.conf`` file. See
:yocto_git:`meta-yocto-bsp/conf/machine </poky/tree/meta-yocto-bsp/conf/machine>`
- for sample ``bsp_root_name.conf`` files. Other samples such as
+ for sample ``bsp_root_name.conf`` files. There are other samples such as
:yocto_git:`meta-ti </meta-ti/tree/conf/machine>`
and
:yocto_git:`meta-freescale </meta-freescale/tree/conf/machine>`
- exist from other vendors that have more specific machine and tuning
+ from other vendors that have more specific machine and tuning
examples.
- *Create a Kernel Recipe:* Create a kernel recipe in
@@ -1241,7 +1239,7 @@ As mentioned earlier in this section, the existence of a machine
configuration file is what makes a layer a BSP layer as compared to a
general or kernel layer.
-One or more machine configuration files exist in the
+There are one or more machine configuration files in the
``bsp_layer/conf/machine/`` directory of the layer::
bsp_layer/conf/machine/machine1\.conf
@@ -1311,7 +1309,7 @@ Project Reference Manual.
- :term:`PREFERRED_PROVIDER_virtual/xserver <PREFERRED_PROVIDER>`:
The recipe that provides "virtual/xserver" when more than one
provider is found. In this case, the recipe that provides
- "virtual/xserver" is "xserver-xorg", which exists in
+ "virtual/xserver" is "xserver-xorg", available in
``poky/meta/recipes-graphics/xorg-xserver``.
- :term:`XSERVER`: The packages that
@@ -1326,7 +1324,7 @@ Project Reference Manual.
.. tip::
- Many ``MACHINE*`` variables exist that help you configure a particular piece
+ There are many ``MACHINE*`` variables that help you configure a particular piece
of hardware.
- :term:`EXTRA_IMAGEDEPENDS`:
@@ -1339,9 +1337,9 @@ Project Reference Manual.
- :term:`DEFAULTTUNE`: Machines
use tunings to optimize machine, CPU, and application performance.
These features, which are collectively known as "tuning features",
- exist in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g.
+ are set in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g.
``poky/meta/conf/machine/include``). In this example, the default
- tuning file is "cortexa8hf-neon".
+ tuning file is ``cortexa8hf-neon``.
.. note::
diff --git a/documentation/toaster-manual/reference.rst b/documentation/toaster-manual/reference.rst
index 988a262188..c0d02ff9ab 100644
--- a/documentation/toaster-manual/reference.rst
+++ b/documentation/toaster-manual/reference.rst
@@ -9,8 +9,8 @@ concepts and have some basic command reference material available. This
final chapter provides conceptual information on layer sources,
releases, and JSON configuration files. Also provided is a quick look at
some useful ``manage.py`` commands that are Toaster-specific.
-Information on ``manage.py`` commands does exist across the Web and the
-information in this manual by no means attempts to provide a command
+Information on ``manage.py`` commands is available across the Web and
+this manual by no means attempts to provide a command
comprehensive reference.
Layer Source
@@ -508,7 +508,7 @@ Useful Commands
===============
In addition to the web user interface and the scripts that start and
-stop Toaster, command-line commands exist through the ``manage.py``
+stop Toaster, command-line commands are available through the ``manage.py``
management script. You can find general documentation on ``manage.py``
at the
`Django <https://docs.djangoproject.com/en/2.2/topics/settings/>`__
--
2.25.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
end of thread, other threads:[~2021-05-14 8:35 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-14 8:35 [PATCH 0/6] Simplify style around the use of the "exist" verb Michael Opdenacker
2021-05-14 8:35 ` [PATCH 1/6] ref-manual: simplify style Michael Opdenacker
2021-05-14 8:35 ` [PATCH 2/6] kernel-dev manual: " Michael Opdenacker
2021-05-14 8:35 ` [PATCH 3/6] dev-manual: " Michael Opdenacker
2021-05-14 8:35 ` [PATCH 4/6] sdk-manual: simplify style and fix formating Michael Opdenacker
2021-05-14 8:35 ` [PATCH 5/6] overview-manual: simplify style and add missings references Michael Opdenacker
2021-05-14 8:35 ` [PATCH 6/6] manuals: simplify style Michael Opdenacker
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.