diff options
author | Nicolas Dechesne <nicolas.dechesne@linaro.org> | 2020-07-24 16:27:54 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2020-09-17 10:09:33 +0100 |
commit | c473fa229239752367c5d573160fc8738cf1907e (patch) | |
tree | f8520ba3aa3cf911333dbd31e38e9a52203a0285 /documentation/ref-manual/ref-structure.rst | |
parent | 4cd953989de42c7a83f666c23e077d53b016a1f1 (diff) | |
download | poky-c473fa229239752367c5d573160fc8738cf1907e.tar.gz |
sphinx: fix internal links
Many of the internal links were not converted probably from DocBook
using pandoc. After looking at the various patterns, the follow series
of 'naive' Python regexp were used to perform some additional
automatic conversion.
Also, since we rely on built-in glossary, all links to terms need to
use the sphinx :term: syntax.
This commit is generated using the following Python series of regexp:
line = re.sub("`+(\w+)`* <(\&YOCTO_DOCS_REF_URL;)?#var-\\1>`__",
":term:`\\1`",
line)
line = re.sub("`+do_([a-z_]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-tasks-\\1>`__",
":ref:`ref-tasks-\\1`",
line)
line = re.sub("`+([a-z_\-\*\.]+).bbclass`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__",
":ref:`\\1.bbclass <ref-classes-\\1>`",
line)
line = re.sub("`+([a-z_\-\*\.]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__",
":ref:`\\1 <ref-classes-\\1>`",
line)
line = re.sub("`Source Directory <(\&YOCTO_DOCS_REF_URL;)?#source-directory>`__",
":term:`Source Directory`",
line)
line = re.sub("`Build Directory <(\&YOCTO_DOCS_REF_URL;)?#build-directory>`__",
":term:`Build Directory`",
line)
line = re.sub("`Metadata <(\&YOCTO_DOCS_REF_URL;)?#metadata>`__",
":term:`Metadata`",
line)
line = re.sub("`BitBake <(\&YOCTO_DOCS_REF_URL;)?#bitbake-term>`__",
":term:`BitBake`",
line)
line = re.sub("`Images <(\&YOCTO_DOCS_REF_URL;)?#ref-images>`__",
":ref:`ref-manual/ref-images:Images`",
line)
line = re.sub("`Classes <(\&YOCTO_DOCS_REF_URL;)?#ref-classes>`__",
":ref:`ref-manual/ref-classes:Classes`",
line)
line = re.sub("`workspace <(\&YOCTO_DOCS_REF_URL;)?#devtool-the-workspace-layer-structure>`__",
":ref:`devtool-the-workspace-layer-structure`",
line)
line = re.sub("`Open-?Embedded b?B?uild s?S?ystem <(\&YOCTO_DOCS_REF_URL;)?#build-system-term>`__",
":term:`OpenEmbedded Build System`",
line)
line = re.sub("`(OpenEmbedded-Core )?(\(?OE-Core\)? )?<(\&YOCTO_DOCS_REF_URL;)?#oe-core>`__",
":term:`OpenEmbedded-Core (OE-Core)`",
line)
It won't catch multiline strings, but it catches a very large number
of occurences!
(From yocto-docs rev: 3f537d17de5b1fb76ba3bee196481984a4826378)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-structure.rst')
-rw-r--r-- | documentation/ref-manual/ref-structure.rst | 58 |
1 files changed, 29 insertions, 29 deletions
diff --git a/documentation/ref-manual/ref-structure.rst b/documentation/ref-manual/ref-structure.rst index 5e30a08041..c63900e604 100644 --- a/documentation/ref-manual/ref-structure.rst +++ b/documentation/ref-manual/ref-structure.rst | |||
@@ -4,7 +4,7 @@ | |||
4 | Source Directory Structure | 4 | Source Directory Structure |
5 | ************************** | 5 | ************************** |
6 | 6 | ||
7 | The `Source Directory <#source-directory>`__ consists of numerous files, | 7 | The :term:`Source Directory` consists of numerous files, |
8 | directories and subdirectories; understanding their locations and | 8 | directories and subdirectories; understanding their locations and |
9 | contents is key to using the Yocto Project effectively. This chapter | 9 | contents is key to using the Yocto Project effectively. This chapter |
10 | describes the Source Directory and gives information about those files | 10 | describes the Source Directory and gives information about those files |
@@ -36,7 +36,7 @@ Directory <#source-directory>`__. | |||
36 | 36 | ||
37 | This directory includes a copy of BitBake for ease of use. The copy | 37 | This directory includes a copy of BitBake for ease of use. The copy |
38 | usually matches the current stable BitBake release from the BitBake | 38 | usually matches the current stable BitBake release from the BitBake |
39 | project. BitBake, a `Metadata <#metadata>`__ interpreter, reads the | 39 | project. BitBake, a :term:`Metadata` interpreter, reads the |
40 | Yocto Project Metadata and runs the tasks defined by that data. Failures | 40 | Yocto Project Metadata and runs the tasks defined by that data. Failures |
41 | are usually caused by errors in your Metadata and not from BitBake | 41 | are usually caused by errors in your Metadata and not from BitBake |
42 | itself; consequently, most users do not need to worry about BitBake. | 42 | itself; consequently, most users do not need to worry about BitBake. |
@@ -63,7 +63,7 @@ the OpenEmbedded build environment setup script (i.e. | |||
63 | ````` <#structure-core-script>`__). | 63 | ````` <#structure-core-script>`__). |
64 | 64 | ||
65 | It is also possible to place output and configuration files in a | 65 | It is also possible to place output and configuration files in a |
66 | directory separate from the `Source Directory <#source-directory>`__ by | 66 | directory separate from the :term:`Source Directory` by |
67 | providing a directory name when you ``source`` the setup script. For | 67 | providing a directory name when you ``source`` the setup script. For |
68 | information on separating output from your local Source Directory files | 68 | information on separating output from your local Source Directory files |
69 | (commonly described as an "out of tree" build), see the | 69 | (commonly described as an "out of tree" build), see the |
@@ -152,7 +152,7 @@ BitBake commands. The script uses other scripts within the ``scripts`` | |||
152 | directory to do the bulk of the work. | 152 | directory to do the bulk of the work. |
153 | 153 | ||
154 | When you run this script, your Yocto Project environment is set up, a | 154 | When you run this script, your Yocto Project environment is set up, a |
155 | `Build Directory <#build-directory>`__ is created, your working | 155 | :term:`Build Directory` is created, your working |
156 | directory becomes the Build Directory, and you are presented with some | 156 | directory becomes the Build Directory, and you are presented with some |
157 | simple suggestions as to what to do next, including a list of some | 157 | simple suggestions as to what to do next, including a list of some |
158 | possible targets to build. Here is an example: $ source | 158 | possible targets to build. Here is an example: $ source |
@@ -162,7 +162,7 @@ core-image-sato meta-toolchain meta-ide-support You can also run | |||
162 | generated qemu images with a command like 'runqemu qemux86-64' The | 162 | generated qemu images with a command like 'runqemu qemux86-64' The |
163 | default output of the ``oe-init-build-env`` script is from the | 163 | default output of the ``oe-init-build-env`` script is from the |
164 | ``conf-notes.txt`` file, which is found in the ``meta-poky`` directory | 164 | ``conf-notes.txt`` file, which is found in the ``meta-poky`` directory |
165 | within the `Source Directory <#source-directory>`__. If you design a | 165 | within the :term:`Source Directory`. If you design a |
166 | custom distribution, you can include your own version of this | 166 | custom distribution, you can include your own version of this |
167 | configuration file to mention the targets defined by your distribution. | 167 | configuration file to mention the targets defined by your distribution. |
168 | See the "`Creating a Custom Template Configuration | 168 | See the "`Creating a Custom Template Configuration |
@@ -213,7 +213,7 @@ Directory a specific name when you run the setup script, the name | |||
213 | defaults to ``build/``. | 213 | defaults to ``build/``. |
214 | 214 | ||
215 | For subsequent parsing and processing, the name of the Build directory | 215 | For subsequent parsing and processing, the name of the Build directory |
216 | is available via the ```TOPDIR`` <#var-TOPDIR>`__ variable. | 216 | is available via the :term:`TOPDIR` variable. |
217 | 217 | ||
218 | .. _structure-build-buildhistory: | 218 | .. _structure-build-buildhistory: |
219 | 219 | ||
@@ -243,7 +243,7 @@ relatively rare. | |||
243 | 243 | ||
244 | At a minimum, you would normally edit this file to select the target | 244 | At a minimum, you would normally edit this file to select the target |
245 | ``MACHINE``, which package types you wish to use | 245 | ``MACHINE``, which package types you wish to use |
246 | (```PACKAGE_CLASSES`` <#var-PACKAGE_CLASSES>`__), and the location from | 246 | (:term:`PACKAGE_CLASSES`), and the location from |
247 | which you want to access downloaded files (``DL_DIR``). | 247 | which you want to access downloaded files (``DL_DIR``). |
248 | 248 | ||
249 | If ``local.conf`` is not present when you start the build, the | 249 | If ``local.conf`` is not present when you start the build, the |
@@ -261,7 +261,7 @@ build environment from any layer by setting the variable in the | |||
261 | top-level build environment setup script as follows: | 261 | top-level build environment setup script as follows: |
262 | TEMPLATECONF=your_layer/conf Once the build process gets the sample | 262 | TEMPLATECONF=your_layer/conf Once the build process gets the sample |
263 | file, it uses ``sed`` to substitute final | 263 | file, it uses ``sed`` to substitute final |
264 | ``${``\ ```OEROOT`` <#var-OEROOT>`__\ ``}`` values for all | 264 | ``${``\ :term:`OEROOT`\ ``}`` values for all |
265 | ``##OEROOT##`` values. | 265 | ``##OEROOT##`` values. |
266 | 266 | ||
267 | .. note:: | 267 | .. note:: |
@@ -286,7 +286,7 @@ file, it uses ``sed`` to substitute final | |||
286 | This configuration file defines | 286 | This configuration file defines |
287 | `layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__, | 287 | `layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__, |
288 | which are directory trees, traversed (or walked) by BitBake. The | 288 | which are directory trees, traversed (or walked) by BitBake. The |
289 | ``bblayers.conf`` file uses the ```BBLAYERS`` <#var-BBLAYERS>`__ | 289 | ``bblayers.conf`` file uses the :term:`BBLAYERS` |
290 | variable to list the layers BitBake tries to find. | 290 | variable to list the layers BitBake tries to find. |
291 | 291 | ||
292 | If ``bblayers.conf`` is not present when you start the build, the | 292 | If ``bblayers.conf`` is not present when you start the build, the |
@@ -304,7 +304,7 @@ implies that you can base your build from any layer by setting the | |||
304 | variable in the top-level build environment setup script as follows: | 304 | variable in the top-level build environment setup script as follows: |
305 | TEMPLATECONF=your_layer/conf Once the build process gets the sample | 305 | TEMPLATECONF=your_layer/conf Once the build process gets the sample |
306 | file, it uses ``sed`` to substitute final | 306 | file, it uses ``sed`` to substitute final |
307 | ``${``\ ```OEROOT`` <#var-OEROOT>`__\ ``}`` values for all | 307 | ``${``\ :term:`OEROOT`\ ``}`` values for all |
308 | ``##OEROOT##`` values. | 308 | ``##OEROOT##`` values. |
309 | 309 | ||
310 | .. note:: | 310 | .. note:: |
@@ -355,7 +355,7 @@ You can control the location of this directory through the | |||
355 | -------------- | 355 | -------------- |
356 | 356 | ||
357 | The OpenEmbedded build system creates and uses this directory for all | 357 | The OpenEmbedded build system creates and uses this directory for all |
358 | the build system's output. The ```TMPDIR`` <#var-TMPDIR>`__ variable | 358 | the build system's output. The :term:`TMPDIR` variable |
359 | points to this directory. | 359 | points to this directory. |
360 | 360 | ||
361 | BitBake creates this directory if it does not exist. As a last resort, | 361 | BitBake creates this directory if it does not exist. As a last resort, |
@@ -393,7 +393,7 @@ cache is reused. If the file has changed, it is reparsed. | |||
393 | --------------------- | 393 | --------------------- |
394 | 394 | ||
395 | This directory contains any "end result" output from the OpenEmbedded | 395 | This directory contains any "end result" output from the OpenEmbedded |
396 | build process. The ```DEPLOY_DIR`` <#var-DEPLOY_DIR>`__ variable points | 396 | build process. The :term:`DEPLOY_DIR` variable points |
397 | to this directory. For more detail on the contents of the ``deploy`` | 397 | to this directory. For more detail on the contents of the ``deploy`` |
398 | directory, see the | 398 | directory, see the |
399 | "`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" and | 399 | "`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" and |
@@ -497,11 +497,11 @@ another. | |||
497 | ---------------------------------- | 497 | ---------------------------------- |
498 | 498 | ||
499 | This directory is the location of the sysroot contents that the task | 499 | This directory is the location of the sysroot contents that the task |
500 | ```do_prepare_recipe_sysroot`` <#ref-tasks-prepare_recipe_sysroot>`__ | 500 | :ref:`ref-tasks-prepare_recipe_sysroot` |
501 | links or copies into the recipe-specific sysroot for each recipe listed | 501 | links or copies into the recipe-specific sysroot for each recipe listed |
502 | in ```DEPENDS`` <#var-DEPENDS>`__. Population of this directory is | 502 | in :term:`DEPENDS`. Population of this directory is |
503 | handled through shared state, while the path is specified by the | 503 | handled through shared state, while the path is specified by the |
504 | ```COMPONENTS_DIR`` <#var-COMPONENTS_DIR>`__ variable. Apart from a few | 504 | :term:`COMPONENTS_DIR` variable. Apart from a few |
505 | unusual circumstances, handling of the ``sysroots-components`` directory | 505 | unusual circumstances, handling of the ``sysroots-components`` directory |
506 | should be automatic, and recipes should not directly reference | 506 | should be automatic, and recipes should not directly reference |
507 | ``build/tmp/sysroots-components``. | 507 | ``build/tmp/sysroots-components``. |
@@ -514,7 +514,7 @@ should be automatic, and recipes should not directly reference | |||
514 | Previous versions of the OpenEmbedded build system used to create a | 514 | Previous versions of the OpenEmbedded build system used to create a |
515 | global shared sysroot per machine along with a native sysroot. Beginning | 515 | global shared sysroot per machine along with a native sysroot. Beginning |
516 | with the DISTRO version of the Yocto Project, sysroots exist in | 516 | with the DISTRO version of the Yocto Project, sysroots exist in |
517 | recipe-specific ```WORKDIR`` <#var-WORKDIR>`__ directories. Thus, the | 517 | recipe-specific :term:`WORKDIR` directories. Thus, the |
518 | ``build/tmp/sysroots/`` directory is unused. | 518 | ``build/tmp/sysroots/`` directory is unused. |
519 | 519 | ||
520 | .. note:: | 520 | .. note:: |
@@ -566,7 +566,7 @@ directory. For example, the source for a particular package is unpacked, | |||
566 | patched, configured and compiled all within its own work directory. | 566 | patched, configured and compiled all within its own work directory. |
567 | Within the work directory, organization is based on the package group | 567 | Within the work directory, organization is based on the package group |
568 | and version for which the source is being compiled as defined by the | 568 | and version for which the source is being compiled as defined by the |
569 | ```WORKDIR`` <#var-WORKDIR>`__. | 569 | :term:`WORKDIR`. |
570 | 570 | ||
571 | It is worth considering the structure of a typical work directory. As an | 571 | It is worth considering the structure of a typical work directory. As an |
572 | example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` | 572 | example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` |
@@ -599,12 +599,12 @@ As described earlier in the | |||
599 | "```build/tmp/sysroots/`` <#structure-build-tmp-sysroots>`__" section, | 599 | "```build/tmp/sysroots/`` <#structure-build-tmp-sysroots>`__" section, |
600 | beginning with the DISTRO release of the Yocto Project, the OpenEmbedded | 600 | beginning with the DISTRO release of the Yocto Project, the OpenEmbedded |
601 | build system builds each recipe in its own work directory (i.e. | 601 | build system builds each recipe in its own work directory (i.e. |
602 | ```WORKDIR`` <#var-WORKDIR>`__). The path to the work directory is | 602 | :term:`WORKDIR`). The path to the work directory is |
603 | constructed using the architecture of the given build (e.g. | 603 | constructed using the architecture of the given build (e.g. |
604 | ```TUNE_PKGARCH`` <#var-TUNE_PKGARCH>`__, | 604 | :term:`TUNE_PKGARCH`, |
605 | ```MACHINE_ARCH`` <#var-MACHINE_ARCH>`__, or "allarch"), the recipe | 605 | :term:`MACHINE_ARCH`, or "allarch"), the recipe |
606 | name, and the version of the recipe (i.e. | 606 | name, and the version of the recipe (i.e. |
607 | ```PE`` <#var-PE>`__\ ``:``\ ```PV`` <#var-PV>`__\ ``-``\ ```PR`` <#var-PR>`__). | 607 | :term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). |
608 | 608 | ||
609 | A number of key subdirectories exist within each recipe work directory: | 609 | A number of key subdirectories exist within each recipe work directory: |
610 | 610 | ||
@@ -614,17 +614,17 @@ A number of key subdirectories exist within each recipe work directory: | |||
614 | which tasks were executed. | 614 | which tasks were executed. |
615 | 615 | ||
616 | - ``${WORKDIR}/image``: Contains the output of the | 616 | - ``${WORKDIR}/image``: Contains the output of the |
617 | ```do_install`` <#ref-tasks-install>`__ task, which corresponds to | 617 | :ref:`ref-tasks-install` task, which corresponds to |
618 | the ``${``\ ```D`` <#var-D>`__\ ``}`` variable in that task. | 618 | the ``${``\ :term:`D`\ ``}`` variable in that task. |
619 | 619 | ||
620 | - ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any | 620 | - ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any |
621 | tasks executed under pseudo for the recipe. | 621 | tasks executed under pseudo for the recipe. |
622 | 622 | ||
623 | - ``${WORKDIR}/sysroot-destdir``: Contains the output of the | 623 | - ``${WORKDIR}/sysroot-destdir``: Contains the output of the |
624 | ```do_populate_sysroot`` <#ref-tasks-populate_sysroot>`__ task. | 624 | :ref:`ref-tasks-populate_sysroot` task. |
625 | 625 | ||
626 | - ``${WORKDIR}/package``: Contains the output of the | 626 | - ``${WORKDIR}/package``: Contains the output of the |
627 | ```do_package`` <#ref-tasks-package>`__ task before the output is | 627 | :ref:`ref-tasks-package` task before the output is |
628 | split into individual packages. | 628 | split into individual packages. |
629 | 629 | ||
630 | - ``${WORKDIR}/packages-split``: Contains the output of the | 630 | - ``${WORKDIR}/packages-split``: Contains the output of the |
@@ -645,7 +645,7 @@ A number of key subdirectories exist within each recipe work directory: | |||
645 | - ``${WORKDIR}/build``: This subdirectory applies only to recipes that | 645 | - ``${WORKDIR}/build``: This subdirectory applies only to recipes that |
646 | support builds where the source is separate from the build artifacts. | 646 | support builds where the source is separate from the build artifacts. |
647 | The OpenEmbedded build system uses this directory as a separate build | 647 | The OpenEmbedded build system uses this directory as a separate build |
648 | directory (i.e. ``${``\ ```B`` <#var-B>`__\ ``}``). | 648 | directory (i.e. ``${``\ :term:`B`\ ``}``). |
649 | 649 | ||
650 | .. _structure-build-work-shared: | 650 | .. _structure-build-work-shared: |
651 | 651 | ||
@@ -662,7 +662,7 @@ recipes. In practice, this is only used for ``gcc`` and its variants | |||
662 | The Metadata - ``meta/`` | 662 | The Metadata - ``meta/`` |
663 | ======================== | 663 | ======================== |
664 | 664 | ||
665 | As mentioned previously, `Metadata <#metadata>`__ is the core of the | 665 | As mentioned previously, :term:`Metadata` is the core of the |
666 | Yocto Project. Metadata has several important subdivisions: | 666 | Yocto Project. Metadata has several important subdivisions: |
667 | 667 | ||
668 | .. _structure-meta-classes: | 668 | .. _structure-meta-classes: |
@@ -681,7 +681,7 @@ generation or packaging also have their specific class files such as | |||
681 | ``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``. | 681 | ``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``. |
682 | 682 | ||
683 | For reference information on classes, see the | 683 | For reference information on classes, see the |
684 | "`Classes <#ref-classes>`__" chapter. | 684 | ":ref:`ref-manual/ref-classes:Classes`" chapter. |
685 | 685 | ||
686 | .. _structure-meta-conf: | 686 | .. _structure-meta-conf: |
687 | 687 | ||
@@ -726,7 +726,7 @@ file mainly inherits its configuration from Poky. | |||
726 | 726 | ||
727 | The OpenEmbedded build system searches this directory for configuration | 727 | The OpenEmbedded build system searches this directory for configuration |
728 | files that correspond to the value of | 728 | files that correspond to the value of |
729 | ```SDKMACHINE`` <#var-SDKMACHINE>`__. By default, 32-bit and 64-bit x86 | 729 | :term:`SDKMACHINE`. By default, 32-bit and 64-bit x86 |
730 | files ship with the Yocto Project that support some SDK hosts. However, | 730 | files ship with the Yocto Project that support some SDK hosts. However, |
731 | it is possible to extend that support to other SDK hosts by adding | 731 | it is possible to extend that support to other SDK hosts by adding |
732 | additional configuration files in this subdirectory within another | 732 | additional configuration files in this subdirectory within another |