From 5a6fb291ad16ce4110e65adf2d29e8ccfe6fa25a Mon Sep 17 00:00:00 2001 From: Quentin Schulz Date: Sat, 19 Jun 2021 09:07:35 +0200 Subject: docs: replace remaining ``FOO`` by :term:`FOO` A few occurences appeared between the time the original patch was sent and it was applied, this fixes it. Also, the original patch didn't take into account lowercase terms, this is now fixed, see module_autoload for example. Finally, as is often the case with regexp, there was a typo in it that didn't make it match as much as it should have. The script that is used to do the replacement of ``FOO`` by :term:`FOO` is the following Python code: import re from pathlib import Path from runpy import run_module import contextlib import io import sys re_term = re.compile(r'variables.html#term-([a-zA-Z_0-9]*)') terms = [] new_terms = set() with contextlib.redirect_stdout(io.StringIO()) as f: run_module('sphinx.ext.intersphinx', run_name='__main__') objects = f.getvalue() match = re_term.search(objects) while match: if match.group(1): terms.append(match.group(1)) match = re_term.search(objects, match.end()) for rst in Path('.').rglob('*.rst'): with open(rst, 'r') as f: content = "".join(f.readlines()) for term in terms: content = re.sub(r'``({})``(?!.*\s+[~=-]{{{:d},}})'.format(term, len(term)), r':term:`\1`', content) with open(rst, 'w') as f: f.write(content) This script takes one argument as input: an objects.inv. Bitbake's can be gotten from https://docs.yoctoproject.org/bitbake/objects.inv. The objetcs.inv from the current git repo can be gotten from documentation/_build/html/objetcs.inv after running `make html`. Note that this excludes from replacement terms that appear in section titles as it requires refs to be changed too. This can be automated too if need be but right now it looks a bit confusing to have an anchor link (for sections) also have a term/reference link in it. I am not sure this is desired today. This is the result of two runs of the aforementioned script, once with Bitbake objects.inv and once with this repo's. Fixes: ba49d9babfcb "docs: replace ``FOO`` by :term:`FOO` where possible" (From yocto-docs rev: 1e1b0c4dd241b6657035172b1f7b5f341afa8b25) Signed-off-by: Quentin Schulz Reviewed-by: Michael Opdenacker Signed-off-by: Richard Purdie --- documentation/ref-manual/classes.rst | 10 +++--- documentation/ref-manual/faq.rst | 2 +- documentation/ref-manual/kickstart.rst | 2 +- documentation/ref-manual/qa-checks.rst | 2 +- documentation/ref-manual/variables.rst | 60 +++++++++++++++++----------------- 5 files changed, 38 insertions(+), 38 deletions(-) (limited to 'documentation/ref-manual') diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 9b93807b6d..49905f2725 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -116,7 +116,7 @@ It's useful to have some idea of how the tasks defined by the - :ref:`ref-tasks-compile` - Runs ``make`` with arguments that specify the compiler and linker. You can pass - additional arguments through the ``EXTRA_OEMAKE`` variable. + additional arguments through the :term:`EXTRA_OEMAKE` variable. - :ref:`ref-tasks-install` - Runs ``make install`` and passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``. @@ -981,7 +981,7 @@ 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 :term:`WARN_QA` and -``ERROR_QA`` variables: +:term:`ERROR_QA` variables: - ``already-stripped:`` Checks that produced binaries have not already been stripped prior to the build system extracting debug @@ -1016,7 +1016,7 @@ Here are the tests you can list with the :term:`WARN_QA` and adds a dependency on the ``initscripts-functions`` package to packages that install an initscript that refers to ``/etc/init.d/functions``. The recipe should really have an explicit - ``RDEPENDS`` for the package in question on ``initscripts-functions`` + :term:`RDEPENDS` for the package in question on ``initscripts-functions`` so that the OpenEmbedded build system is able to ensure that the ``initscripts`` recipe is actually built and thus the ``initscripts-functions`` package is made available. @@ -1186,7 +1186,7 @@ Here are the tests you can list with the :term:`WARN_QA` and turn into ``FILES = "xyz"``. - ``rpaths:`` Checks for rpaths in the binaries that contain build - system paths such as ``TMPDIR``. If this test fails, bad ``-rpath`` + system paths such as :term:`TMPDIR`. If this test fails, bad ``-rpath`` options are being passed to the linker commands and your binaries have potential security issues. @@ -1259,7 +1259,7 @@ themselves. The ``kernel`` class handles building Linux kernels. The class contains code to build all kernel trees. All needed headers are staged into the -``STAGING_KERNEL_DIR`` directory to allow out-of-tree module builds +:term:`STAGING_KERNEL_DIR` directory to allow out-of-tree module builds using the :ref:`module ` class. This means that each built kernel module is packaged separately and diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst index 640ef77d03..c7322e7623 100644 --- a/documentation/ref-manual/faq.rst +++ b/documentation/ref-manual/faq.rst @@ -292,7 +292,7 @@ download directory. If that location fails, Poky tries :term:`MIRRORS` in that order. Assuming your distribution is "poky", the OpenEmbedded build system uses -the Yocto Project source ``PREMIRRORS`` by default for SCM-based +the Yocto Project source :term:`PREMIRRORS` by default for SCM-based sources, upstreams for normal tarballs, and then falls back to a number of other mirrors including the Yocto Project source mirror if those fail. diff --git a/documentation/ref-manual/kickstart.rst b/documentation/ref-manual/kickstart.rst index a7443f9ea3..fc723ccbe2 100644 --- a/documentation/ref-manual/kickstart.rst +++ b/documentation/ref-manual/kickstart.rst @@ -208,7 +208,7 @@ supports the following options: bootloader times out and boots the default option. - ``--append``: Specifies kernel parameters. These parameters will be - added to the syslinux ``APPEND`` or ``grub`` kernel command line. + added to the syslinux :term:`APPEND` or ``grub`` kernel command line. - ``--configfile``: Specifies a user-defined configuration file for the bootloader. You can provide a full pathname for the file or a diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst index a105acc2c8..0ef203c70f 100644 --- a/documentation/ref-manual/qa-checks.rst +++ b/documentation/ref-manual/qa-checks.rst @@ -604,7 +604,7 @@ Errors and Warnings so using ${:term:`BPN`} rather than ${:term:`PN`} as the latter will change for different variants of the same recipe e.g. when :term:`BBCLASSEXTEND` or multilib are being used. This check will fail if a reference to ``${PN}`` - is found within the ``SRC_URI`` value - change it to ``${BPN}`` instead. + is found within the :term:`SRC_URI` value - change it to ``${BPN}`` instead. .. _qa-check-unhandled-features-check: diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 00d45a79f0..354721d1a8 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -280,7 +280,7 @@ system and gives an overview of their function and contents. S = "${WORKDIR}/${BP}" You can separate the (:term:`S`) directory and the directory pointed to - by the ``B`` variable. Most Autotools-based recipes support + by the :term:`B` variable. Most Autotools-based recipes support separating these directories. The build system defaults to using separate directories for ``gcc`` and some kernel recipes. @@ -553,7 +553,7 @@ system and gives an overview of their function and contents. BB_SERVER_TIMEOUT = "20" If you want the server to never be unloaded, - set ``BB_SERVER_TIMEOUT`` to "-1". + set :term:`BB_SERVER_TIMEOUT` to "-1". :term:`BBCLASSEXTEND` Allows you to extend a recipe so that it builds variants of the @@ -577,7 +577,7 @@ system and gives an overview of their function and contents. variants by rewriting variable values and applying overrides such as ``_class-native``. For example, to generate a native version of a recipe, a :term:`DEPENDS` on "foo" is rewritten - to a ``DEPENDS`` on "foo-native". + to a :term:`DEPENDS` on "foo-native". Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once. Parsing once adds some limitations. For example, it is not @@ -892,13 +892,13 @@ system and gives an overview of their function and contents. the :term:`BUILD_CFLAGS` and :term:`BUILDSDK_CFLAGS` default values. - The default value of the ``BUILD_OPTIMIZATION`` variable is "-O2 + The default value of the :term:`BUILD_OPTIMIZATION` variable is "-O2 -pipe". :term:`BUILD_OS` Specifies the operating system in use on the build host (e.g. "linux"). The OpenEmbedded build system sets the value of - ``BUILD_OS`` from the OS reported by the ``uname`` command - the + :term:`BUILD_OS` from the OS reported by the ``uname`` command - the first word, converted to lower-case characters. :term:`BUILD_PREFIX` @@ -1114,7 +1114,7 @@ system and gives an overview of their function and contents. .. note:: - ``CLASSOVERRIDE`` gets its default "class-target" value from the + :term:`CLASSOVERRIDE` gets its default "class-target" value from the ``bitbake.conf`` file. As an example, the following override allows you to install extra @@ -1205,7 +1205,7 @@ system and gives an overview of their function and contents. :term:`COMPONENTS_DIR` Stores sysroot components for each recipe. The OpenEmbedded build - system uses ``COMPONENTS_DIR`` when constructing recipe-specific + system uses :term:`COMPONENTS_DIR` when constructing recipe-specific sysroots for other recipes. The default is @@ -1611,7 +1611,7 @@ system and gives an overview of their function and contents. ":ref:`overview-manual/concepts:automatically added runtime dependencies`" section in the Yocto Project Overview and Concepts Manual, runtime dependencies will often be added automatically, meaning - ``DEPENDS`` alone is sufficient for most recipes. + :term:`DEPENDS` alone is sufficient for most recipes. - Counterintuitively, :term:`DEPENDS` is often necessary even for recipes that install precompiled components. For example, if @@ -1652,7 +1652,7 @@ system and gives an overview of their function and contents. "package_deb". The BitBake configuration file initially defines the - ``DEPLOY_DIR_DEB`` variable as a sub-folder of + :term:`DEPLOY_DIR_DEB` variable as a sub-folder of :term:`DEPLOY_DIR`:: DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" @@ -2568,7 +2568,7 @@ system and gives an overview of their function and contents. :term:`FONT_EXTRA_RDEPENDS` When inheriting the :ref:`fontcache ` class, this variable specifies the runtime dependencies for font packages. - By default, the ``FONT_EXTRA_RDEPENDS`` is set to "fontconfig-utils". + By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils". :term:`FONT_PACKAGES` When inheriting the :ref:`fontcache ` class, @@ -3005,7 +3005,7 @@ system and gives an overview of their function and contents. - If an image recipe uses the "inherit image" line and you are setting :term:`IMAGE_FSTYPES` inside the recipe, you must set - ``IMAGE_FSTYPES`` prior to using the "inherit image" line. + :term:`IMAGE_FSTYPES` prior to using the "inherit image" line. - Due to the way the OpenEmbedded build system processes this variable, you cannot update its contents by using ``_append`` @@ -3334,13 +3334,13 @@ system and gives an overview of their function and contents. :term:`IMGDEPLOYDIR` When inheriting the :ref:`image ` class directly or through the :ref:`core-image ` class, the - ``IMGDEPLOYDIR`` points to a temporary work area for deployed files + :term:`IMGDEPLOYDIR` points to a temporary work area for deployed files that is set in the ``image`` class as follows:: IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete" Recipes inheriting the ``image`` class should copy files to be - deployed into ``IMGDEPLOYDIR``, and the class will take care of + deployed into :term:`IMGDEPLOYDIR`, and the class will take care of copying them into :term:`DEPLOY_DIR_IMAGE` afterwards. :term:`INC_PR` @@ -3698,7 +3698,7 @@ system and gives an overview of their function and contents. - qemu - mips - You define the ``KARCH`` variable in the :ref:`kernel-dev/advanced:bsp descriptions`. + You define the :term:`KARCH` variable in the :ref:`kernel-dev/advanced:bsp descriptions`. :term:`KBRANCH` A regular expression used by the build process to explicitly identify @@ -4653,7 +4653,7 @@ system and gives an overview of their function and contents. :term:`module_autoload` This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD` - variable. You should replace all occurrences of ``module_autoload`` + variable. You should replace all occurrences of :term:`module_autoload` with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example:: module_autoload_rfcomm = "rfcomm" @@ -4684,9 +4684,9 @@ system and gives an overview of their function and contents. You must use the kernel module name override. Run ``man modprobe.d`` in the shell to find out more information on - the exact syntax you want to provide with ``module_conf``. + the exact syntax you want to provide with :term:`module_conf`. - Including ``module_conf`` causes the OpenEmbedded build system to + Including :term:`module_conf` causes the OpenEmbedded build system to populate the ``/etc/modprobe.d/modname.conf`` file with ``modprobe.d`` syntax lines. Here is an example that adds the options ``arg1`` and ``arg2`` to a module named ``mymodule``:: @@ -4876,7 +4876,7 @@ system and gives an overview of their function and contents. information, see the ":ref:`dev-manual/common-tasks:using a development shell`" section in the Yocto Project Development Tasks Manual. - You can use the following values for the ``OE_TERMINAL`` variable: + You can use the following values for the :term:`OE_TERMINAL` variable: - auto - gnome @@ -5260,7 +5260,7 @@ system and gives an overview of their function and contents. PACKAGECONFIG[f2] = "\ ... and so on and so on ... - The ``PACKAGECONFIG`` variable itself specifies a space-separated + The :term:`PACKAGECONFIG` variable itself specifies a space-separated list of the features to enable. Following the features, you can determine the behavior of each feature by providing up to six order-dependent arguments, which are separated by commas. You can @@ -5600,7 +5600,7 @@ system and gives an overview of their function and contents. If applicable, the :term:`PN` variable also contains any special suffix or prefix. For example, using ``bash`` to build packages for the - native machine, ``PN`` is ``bash-native``. Using ``bash`` to build + native machine, :term:`PN` is ``bash-native``. Using ``bash`` to build packages for the target and for Multilib, :term:`PN` would be ``bash`` and ``lib64-bash``, respectively. @@ -5670,7 +5670,7 @@ system and gives an overview of their function and contents. :term:`PR` does not need to be increased for changes that do not change the package contents or metadata. - Because manually managing ``PR`` can be cumbersome and error-prone, + Because manually managing :term:`PR` can be cumbersome and error-prone, an automated solution exists. See the ":ref:`dev-manual/common-tasks:working with a pr service`" section in the Yocto Project Development Tasks Manual for more information. @@ -6042,7 +6042,7 @@ system and gives an overview of their function and contents. In the example, the development package depends on the ``perl`` package. Thus, the - ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of + :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of the variable. .. note:: @@ -7079,7 +7079,7 @@ system and gives an overview of their function and contents. :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` By default, the OpenEmbedded build system automatically detects - whether ``SRC_URI`` contains files that are machine-specific. If so, + whether :term:`SRC_URI` contains files that are machine-specific. If so, the build system automatically changes :term:`PACKAGE_ARCH`. Setting this variable to "0" disables this behavior. @@ -7292,7 +7292,7 @@ system and gives an overview of their function and contents. ``-native`` recipes are not installed into host paths like such as ``/usr``. Rather, these recipes are installed into - ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes, + :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes, standard build environment variables such as :term:`CPPFLAGS` and :term:`CFLAGS` are set up so that both host paths @@ -7726,13 +7726,13 @@ system and gives an overview of their function and contents. Specifies the prefix used for the toolchain binary target tools. Depending on the type of recipe and the build target, - ``TARGET_PREFIX`` is set as follows: + :term:`TARGET_PREFIX` is set as follows: - For recipes building for the target machine, the value is "${:term:`TARGET_SYS`}-". - For native recipes, the build system sets the variable to the - value of ``BUILD_PREFIX``. + value of :term:`BUILD_PREFIX`. - For native SDK recipes (``nativesdk``), the build system sets the variable to the value of :term:`SDK_PREFIX`. @@ -7778,7 +7778,7 @@ system and gives an overview of their function and contents. separate to avoid potential conflicts. In the ``defaultsetup.conf`` file, the default value of - ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky, + :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky, which normally only support one ``libc`` variant, set :term:`TCLIBCAPPEND` to "" in their distro configuration file resulting in no suffix being applied. @@ -7960,7 +7960,7 @@ system and gives an overview of their function and contents. ``BaseTarget`` class, which is an abstract class that cannot be used as a value of :term:`TEST_TARGET`. - You can provide the following arguments with ``TEST_TARGET``: + You can provide the following arguments with :term:`TEST_TARGET`: - *"qemu":* Boots a QEMU image and runs the tests. See the ":ref:`dev-manual/common-tasks:enabling runtime tests on qemu`" section @@ -8298,7 +8298,7 @@ system and gives an overview of their function and contents. In this example, "sd" is selected as the configuration of the possible four for the :term:`UBOOT_MACHINE`. The "sd" configuration defines "mx6qsabreauto_config" as the value for :term:`UBOOT_MACHINE`, while the - "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-Boot image. + "sdcard" specifies the :term:`IMAGE_FSTYPES` to use for the U-Boot image. For more information on how the :term:`UBOOT_CONFIG` is handled, see the :ref:`uboot-config ` @@ -8357,7 +8357,7 @@ system and gives an overview of their function and contents. :term:`UBOOT_MKIMAGE_DTCOPTS` Options for the device tree compiler passed to mkimage '-D' feature while creating FIT image in :ref:`kernel-fitimage ` class. - If ``UBOOT_MKIMAGE_DTCOPTS`` is not set then kernel-fitimage will not + If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then kernel-fitimage will not pass the ``-D`` option to mkimage. :term:`UBOOT_MKIMAGE_SIGN` -- cgit v1.2.3-54-g00ecf