From fc876832cb57a1a3e61150778a9cfd7acffbc2b6 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Wed, 16 Sep 2020 10:57:16 +0100 Subject: sphinx: overview-manual: Various URL, code block and other fixes to imported data (From yocto-docs rev: 3325fe660dfea24fba2f964a0060664e3c67459a) Signed-off-by: Richard Purdie --- .../overview-manual/overview-manual-concepts.rst | 249 ++++++++++++--------- .../overview-manual-development-environment.rst | 151 +++++++------ .../overview-manual/overview-manual-intro.rst | 24 +- .../overview-manual/overview-manual-yp-intro.rst | 82 +++---- 4 files changed, 270 insertions(+), 236 deletions(-) (limited to 'documentation') diff --git a/documentation/overview-manual/overview-manual-concepts.rst b/documentation/overview-manual/overview-manual-concepts.rst index 7f8f735b37..695984ff1e 100644 --- a/documentation/overview-manual/overview-manual-concepts.rst +++ b/documentation/overview-manual/overview-manual-concepts.rst @@ -34,14 +34,14 @@ itself is of various types: BitBake knows how to combine multiple data sources together and refers to each data source as a layer. For information on layers, see the -"`Understanding and Creating -Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" +":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" section of the Yocto Project Development Tasks Manual. Following are some brief details on these core components. For additional information on how these components interact during a build, -see the "`OpenEmbedded Build System -Concepts <#openembedded-build-system-build-concepts>`__" section. +see the +":ref:`overview-manual/overview-manual-concepts:openembedded build system concepts`" +section. .. _usingpoky-components-bitbake: @@ -57,14 +57,23 @@ This section briefly introduces BitBake. If you want more information on BitBake, see the :doc:`BitBake User Manual `. To see a list of the options BitBake supports, use either of the -following commands: $ bitbake -h $ bitbake --help +following commands: +:: + + $ bitbake -h + $ bitbake --help The most common usage for BitBake is ``bitbake packagename``, where ``packagename`` is the name of the package you want to build (referred to as the "target"). The target often equates to the first part of a recipe's filename (e.g. "foo" for a recipe named ``foo_1.3.0-r0.bb``). So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might -type the following: $ bitbake matchbox-desktop Several different +type the following: +:: + + $ bitbake matchbox-desktop + +Several different versions of ``matchbox-desktop`` might exist. BitBake chooses the one selected by the distribution configuration. You can get more details about how BitBake chooses between different target versions and @@ -153,9 +162,8 @@ By convention, layers in the Yocto Project follow a specific form. Conforming to a known structure allows BitBake to make assumptions during builds on where to find types of metadata. You can find procedures and learn about tools (i.e. ``bitbake-layers``) for creating -layers suitable for the Yocto Project in the "`Understanding and -Creating -Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" +layers suitable for the Yocto Project in the +":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" section of the Yocto Project Development Tasks Manual. .. _openembedded-build-system-build-concepts: @@ -225,7 +233,7 @@ reside as example files in the ``build/conf`` directory of the :term:`Source Directory`. For simplicity, this section refers to the Source Directory as the "Poky Directory." -When you clone the `Poky <&YOCTO_DOCS_REF_URL;#poky>`__ Git repository +When you clone the :term:`Poky` Git repository or you download and unpack a Yocto Project release, you can set up the Source Directory to be named anything you want. For this discussion, the cloned repository uses the default name ``poky``. @@ -238,7 +246,7 @@ cloned repository uses the default name ``poky``. The ``meta-poky`` layer inside Poky contains a ``conf`` directory that has example configuration files. These example files are used as a basis for creating actual configuration files when you source -````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, which is the +:ref:`structure-core-script`, which is the build environment script. Sourcing the build environment script creates a @@ -251,8 +259,8 @@ if versions do not already exist in the Build Directory at the time you source the build environment setup script. Because the Poky repository is fundamentally an aggregation of existing -repositories, some users might be familiar with running the ```` script -in the context of separate +repositories, some users might be familiar with running the +:ref:`structure-core-script` script in the context of separate :term:`OpenEmbedded-Core (OE-Core)` and BitBake repositories rather than a single Poky repository. This discussion assumes the script is executed from within a cloned or unpacked version @@ -320,16 +328,16 @@ The ``bblayers.conf`` file tells BitBake what layers you want considered during the build. By default, the layers listed in this file include layers minimally needed by the build system. However, you must manually add any custom layers you have created. You can find more information on -working with the ``bblayers.conf`` file in the "`Enabling Your -Layer <&YOCTO_DOCS_DEV_URL;#enabling-your-layer>`__" section in the -Yocto Project Development Tasks Manual. +working with the ``bblayers.conf`` file in the +":ref:`dev-manual/dev-manual-common-tasks:enabling your layer`" +section in the Yocto Project Development Tasks Manual. The files ``site.conf`` and ``auto.conf`` are not created by the environment initialization script. If you want the ``site.conf`` file, you need to create that yourself. The ``auto.conf`` file is typically created by an autobuilder: -- *``site.conf``:* You can use the ``conf/site.conf`` configuration +- *site.conf:* You can use the ``conf/site.conf`` configuration file to configure multiple build directories. For example, suppose you had several build environments and they shared some common features. You can set these default build properties here. A good @@ -346,7 +354,7 @@ created by an autobuilder: configurations within that build directory's ``conf/local.conf`` file. -- *``auto.conf``:* The file is usually created and written to by an +- *auto.conf:* The file is usually created and written to by an autobuilder. The settings put into the file are typically the same as you would find in the ``conf/local.conf`` or the ``conf/site.conf`` files. @@ -382,10 +390,10 @@ In general, three types of layer input exists. You can see them below the "User Configuration" box in the `general workflow figure <#general-workflow-figure>`__: -- *Metadata (``.bb`` + Patches):* Software layers containing +- *Metadata (.bb + Patches):* Software layers containing user-supplied recipe files, patches, and append files. A good example of a software layer might be the - ```meta-qt5`https://github.com/meta-qt5/meta-qt5 layer from + `meta-qt5 layer `__ from the `OpenEmbedded Layer Index `__. This layer is for version 5.0 of the popular @@ -421,8 +429,9 @@ licensing file (e.g. ``COPYING.MIT``) if the layer is to be distributed, a ``README`` file as good practice and especially if the layer is to be distributed, a configuration directory, and recipe directories. You can learn about the general structure for layers used with the Yocto Project -in the "`Creating Your Own -Layer <&YOCTO_DOCS_DEV_URL;#creating-your-own-layer>`__" section in the +in the +":ref:`dev-manual/dev-manual-common-tasks:creating your own layer`" +section in the Yocto Project Development Tasks Manual. For a general discussion on layers and the many layers from which you can draw, see the "`Layers <#overview-layers>`__" and "`The Yocto Project Layer @@ -485,8 +494,7 @@ The BSP Layer provides machine configurations that target specific hardware. Everything in this layer is specific to the machine for which you are building the image or the SDK. A common structure or form is defined for BSP layers. You can learn more about this structure in the -`Yocto Project Board Support Package (BSP) Developer's -Guide <&YOCTO_DOCS_BSP_URL;>`__. +:doc:`../bsp-guide/bsp-guide`. .. note:: @@ -704,8 +712,8 @@ architecture are placed in ``build/tmp/deploy/ipk/qemux86``. .. _bitbake-dev-environment: -BitBake -------- +BitBake Tool +------------ The OpenEmbedded build system uses :term:`BitBake` to produce images and @@ -751,8 +759,7 @@ the source files and unpack them into the By default, everything is accomplished in the Build Directory, which has a defined structure. For additional general information on the Build -Directory, see the -"```build/`` <&YOCTO_DOCS_REF_URL;#structure-core-build>`__" section in +Directory, see the ":ref:`structure-core-build`" section in the Yocto Project Reference Manual. Each recipe has an area in the Build Directory where the unpacked source @@ -769,8 +776,7 @@ Build Directory's hierarchy: - :term:`PACKAGE_ARCH`: The architecture of the built package or packages. Depending on the eventual destination of the package or packages (i.e. machine - architecture, `build - host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__, SDK, or + architecture, :term:`Build Host`, SDK, or specific machine), ``PACKAGE_ARCH`` varies. See the variable's description for details. @@ -846,15 +852,14 @@ source files, which are located in the For more information on how the source directories are created, see the "`Source Fetching <#source-fetching-dev-environment>`__" section. For more information on how to create patches and how the build system -processes patches, see the "`Patching -Code <&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code>`__" section in the -Yocto Project Development Tasks Manual. You can also see the "`Use -``devtool modify`` to Modify the Source of an Existing -Component <&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component>`__" +processes patches, see the +":ref:`dev-manual/dev-manual-common-tasks:patching code`" +section in the +Yocto Project Development Tasks Manual. You can also see the +":ref:`sdk-manual/sdk-extensible:use \`\`devtool modify\`\` to modify the source of an existing component`" section in the Yocto Project Application Development and the Extensible -Software Development Kit (SDK) manual and the "`Using Traditional Kernel -Development to Patch the -Kernel <&YOCTO_DOCS_KERNEL_DEV_URL;#using-traditional-kernel-development-to-patch-the-kernel>`__" +Software Development Kit (SDK) manual and the +":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`" section in the Yocto Project Linux Kernel Development Manual. .. _configuration-compilation-and-staging-dev-environment: @@ -882,7 +887,7 @@ This step in the build process consists of the following tasks: depends. A sysroot exists for both the target and for the native binaries, which run on the host system. -- *``do_configure``*: This task configures the source by enabling and +- *do_configure*: This task configures the source by enabling and disabling any build-time and configuration options for the software being built. Configurations can come from the recipe itself as well as from an inherited class. Additionally, the software itself might @@ -903,7 +908,7 @@ This step in the build process consists of the following tasks: :ref:`autotools ` class :yocto_git:`here `. -- *``do_compile``*: Once a configuration task has been satisfied, +- *do_compile*: Once a configuration task has been satisfied, BitBake compiles the source using the :ref:`ref-tasks-compile` task. Compilation occurs in the directory pointed to by the @@ -911,7 +916,7 @@ This step in the build process consists of the following tasks: ``B`` directory is, by default, the same as the :term:`S` directory. -- *``do_install``*: After compilation completes, BitBake executes the +- *do_install*: After compilation completes, BitBake executes the :ref:`ref-tasks-install` task. This task copies files from the ``B`` directory and places them in a holding area pointed to by the :term:`D` @@ -1055,8 +1060,8 @@ data files are deleted from the root filesystem. As part of the final stage of package installation, post installation scripts that are part of the packages are run. Any scripts that fail to run on the build host are run on the target when the target system is first booted. If you are -using a `read-only root -filesystem <&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem>`__, +using a +:ref:`read-only root filesystem `, all the post installation scripts must succeed on the build host during the package installation phase since the root filesystem on the target is read-only. @@ -1097,9 +1102,17 @@ the image. The formats used for the root filesystem depend on the support compression. As an example, a dynamically created task when creating a particular -image type would take the following form: do_image_type So, if the type +image type would take the following form: +:: + + do_image_type + +So, if the type as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically -generated task would be as follows: do_image_ext4 +generated task would be as follows: +:: + + do_image_ext4 The final task involved in image creation is the :ref:`do_image_complete ` @@ -1217,8 +1230,7 @@ varflag. If some other task depends on such a task, then that task will also always be considered out of date, which might not be what you want. For details on how to view information about a task's signature, see the -"`Viewing Task Variable -Dependencies <&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies>`__" +":ref:`dev-manual/dev-manual-common-tasks:viewing task variable dependencies`" section in the Yocto Project Development Tasks Manual. Setscene Tasks and Shared State @@ -1397,8 +1409,7 @@ can initialize the environment before using the tools. section. - For information on setting up a cross-development environment, see - the `Yocto Project Application Development and the Extensible - Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual. + the :doc:`../sdk-manual/sdk-manual` manual. All the output files for an SDK are written to the ``deploy/sdk`` folder inside the :term:`Build Directory` as @@ -1475,13 +1486,10 @@ Cross-Development Toolchain Generation ====================================== The Yocto Project does most of the work for you when it comes to -creating `cross-development -toolchains <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__. This +creating :ref:`sdk-manual/sdk-intro:the cross-development toolchain`. This section provides some technical background on how cross-development toolchains are created and used. For more information on toolchains, you -can also see the `Yocto Project Application Development and the -Extensible Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ -manual. +can also see the :doc:`../sdk-manual/sdk-manual` manual. In the Yocto Project development environment, cross-development toolchains are used to build images and applications that run on the @@ -1514,8 +1522,10 @@ cross-compiler that is used internally within BitBake only. . The chain of events that occurs when ``gcc-cross`` is bootstrapped is as -follows: gcc -> binutils-cross -> gcc-cross-initial -> -linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime +follows: +:: + + gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime - ``gcc``: The build host's GNU Compiler Collection (GCC). @@ -1571,9 +1581,10 @@ might not be the same machine as the Build Host. can take advantage of pre-built images that ship with the Yocto Project and already contain cross-development toolchain installers. -Here is the bootstrap process for the relocatable toolchain: gcc -> -binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> -glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian +Here is the bootstrap process for the relocatable toolchain: +:: + + gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian - ``gcc``: The build host's GNU Compiler Collection (GCC). @@ -1668,18 +1679,15 @@ them if they are deemed to be valid. the shared state packages. Consequently, considerations exist that affect maintaining shared state feeds. For information on how the build system works with packages and can track incrementing ``PR`` - information, see the "`Automatically Incrementing a Binary Package - Revision - Number <&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number>`__" + information, see the ":ref:`dev-manual/dev-manual-common-tasks:automatically incrementing a package version number`" section in the Yocto Project Development Tasks Manual. - The code in the build system that supports incremental builds is not simple code. For techniques that help you work around issues - related to shared state code, see the "`Viewing Metadata Used to - Create the Input Signature of a Shared State - Task <&YOCTO_DOCS_DEV_URL;#dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task>`__" - and "`Invalidating Shared State to Force a Task to - Run <&YOCTO_DOCS_DEV_URL;#dev-invalidating-shared-state-to-force-a-task-to-run>`__" + related to shared state code, see the + ":ref:`dev-manual/dev-manual-common-tasks:viewing metadata used to create the input signature of a shared state task`" + and + ":ref:`dev-manual/dev-manual-common-tasks:invalidating shared state to force a task to run`" sections both in the Yocto Project Development Tasks Manual. The rest of this section goes into detail about the overall incremental @@ -1754,15 +1762,22 @@ to the task. Like the ``WORKDIR`` case, situations exist 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: -PACKAGE_ARCHS[vardepsexclude] = "MACHINE" This example ensures that the -:term:`PACKAGE_ARCHS` variable -does not depend on the value of -:term:`MACHINE`, even if it does +:: + + PACKAGE_ARCHS[vardepsexclude] = "MACHINE" + +This example ensures that the :term:`PACKAGE_ARCHS` variable +does not depend on the value of :term:`MACHINE`, even if it does reference it. Equally, there are cases where you need to add dependencies BitBake is not able to find. You can accomplish this by using a line like the -following: PACKAGE_ARCHS[vardeps] = "MACHINE" This example explicitly +following: +:: + + PACKAGE_ARCHS[vardeps] = "MACHINE" + +This example explicitly adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``. As an example, consider a case with in-line Python where BitBake is not @@ -1788,12 +1803,16 @@ 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 in a list of global variable dependency excludes (i.e. variables never -included in any checksum): BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH -PWD BB_TASKHASH BBPATH DL_DIR \\ SSTATE_DIR THISDIR FILESEXTRAPATHS -FILE_DIRNAME HOME LOGNAME SHELL TERM \\ USER FILESPATH STAGING_DIR_HOST -STAGING_DIR_TARGET COREBASE PRSERV_HOST \\ PRSERV_DUMPDIR -PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\ CCACHE_DIR -EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" The +included in any checksum): +:: + + BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \\ + SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \\ + USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \\ + PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\ + CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" + +The previous example excludes :term:`WORKDIR` since that variable is actually constructed as a path within @@ -1810,8 +1829,12 @@ desired. This file defines the two basic signature generators "OEBasicHash". By default, a dummy "noop" signature handler is enabled in BitBake. This means that behavior is unchanged from previous versions. OE-Core uses the "OEBasicHash" signature handler by default -through this setting in the ``bitbake.conf`` file: BB_SIGNATURE_HANDLER -?= "OEBasicHash" The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same +through this setting in the ``bitbake.conf`` file: +:: + + BB_SIGNATURE_HANDLER ?= "OEBasicHash" + +The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same as the "OEBasic" version but adds the task hash to the `stamp files <#stamp-files-and-the-rerunning-of-tasks>`__. This results in any metadata change that changes the task hash, automatically causing the @@ -1862,12 +1885,21 @@ implementation hidden in ``sstate`` class. From a user's perspective, adding shared state wrapping to a task is as simple as this :ref:`ref-tasks-deploy` example taken from the :ref:`deploy ` class: -DEPLOYDIR = "${WORKDIR}/deploy-${PN}" SSTATETASKS += "do_deploy" -do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" -do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" python -do_deploy_setscene () { sstate_setscene(d) } addtask do_deploy_setscene -do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = -"${MACHINE_ARCH}" The following list explains the previous example: +:: + + DEPLOYDIR = "${WORKDIR}/deploy-${PN}" + SSTATETASKS += "do_deploy" + do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" + do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" + + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + do_deploy[dirs] = "${DEPLOYDIR} ${B}" + do_deploy[stamp-extra-info] = "${MACHINE_ARCH}" + +The following list explains the previous example: - Adding "do_deploy" to ``SSTATETASKS`` adds some required sstate-related processing, which is implemented in the @@ -1907,9 +1939,15 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = task. - The following task definition is glue logic needed to make the - previous settings effective: python do_deploy_setscene () { - sstate_setscene(d) } addtask do_deploy_setscene ``sstate_setscene()`` - takes the flags above as input and accelerates the ``do_deploy`` task + previous settings effective: + :: + + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + + ``sstate_setscene()`` takes the flags above as input and accelerates the ``do_deploy`` task through the shared state cache if possible. If the task was accelerated, ``sstate_setscene()`` returns True. Otherwise, it returns False, and the normal ``do_deploy`` task runs. For more @@ -1941,7 +1979,7 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = :: do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" - + - The ``do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"`` line appends extra metadata to the `stamp @@ -1956,20 +1994,27 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = ``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories, which populates the shared state cache, and ``PKGDATA_DIR`` and ``SHLIBSDIR`` as the corresponding shared state output directories: - do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" - do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" + :: + + do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" + do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" - These methods also include the ability to take a lockfile when manipulating shared state directory structures, for cases where file - additions or removals are sensitive: do_package[sstate-lockfile] = - "${PACKAGELOCK}" + additions or removals are sensitive: + :: + + do_package[sstate-lockfile] = "${PACKAGELOCK}" Behind the scenes, the shared state code works by looking in :term:`SSTATE_DIR` and :term:`SSTATE_MIRRORS` for -shared state files. Here is an example: SSTATE_MIRRORS ?= "\\ file://.\* -http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \\n \\ -file://.\* file:///some/local/dir/sstate/PATH" +shared state files. Here is an example: +:: + + SSTATE_MIRRORS ?= "\ + file://.\* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ + file://.\* file:///some/local/dir/sstate/PATH" .. note:: @@ -2164,11 +2209,11 @@ accomplished using fakeroot. , giving the following: :: - fakeroot do_mytask () { - ... - } - do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" - + fakeroot do_mytask () { + ... + } + do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" + For more information, see the :term:`FAKEROOT* ` variables in the diff --git a/documentation/overview-manual/overview-manual-development-environment.rst b/documentation/overview-manual/overview-manual-development-environment.rst index f89e9b9dd4..273e1027da 100644 --- a/documentation/overview-manual/overview-manual-development-environment.rst +++ b/documentation/overview-manual/overview-manual-development-environment.rst @@ -50,8 +50,7 @@ Community The Development Host ==================== -A development host or `build -host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ is key to +A development host or :term:`Build Host` is key to using the Yocto Project. Because the goal of the Yocto Project is to develop images or applications that run on embedded hardware, development of those images and applications generally takes place on a @@ -68,8 +67,9 @@ set it up as the development host by using to set up a CROPS machine, you effectively have access to a shell environment that is similar to what you see when using a Linux-based development host. For the steps needed to set up a system using CROPS, -see the "`Setting Up to Use CROss PlatformS -(CROPS) <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops>`__" section in +see the +":ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)`" +section in the Yocto Project Development Tasks Manual. If your development host is going to be a system that runs a Linux @@ -78,8 +78,8 @@ 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 that allow development using the Yocto Project. For the steps needed to -set up a development host that runs Linux, see the "`Setting Up a Native -Linux Host <&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host>`__" +set up a development host that runs Linux, see the +":ref:`dev-manual/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 @@ -95,8 +95,8 @@ methods exist for you to do work in the Yocto Project environment: within a shell-based environment using components and tools available through your Linux distribution and the Yocto Project. - For a general flow of the build procedures, see the "`Building a - Simple Image <&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image>`__" + For a general flow of the build procedures, see the + ":ref:`dev-manual/dev-manual-common-tasks:building a simple image`" section in the Yocto Project Development Tasks Manual. - *Board Support Package (BSP) Development:* Development of BSPs @@ -105,11 +105,9 @@ methods exist for you to do work in the Yocto Project environment: hardware. To development BSPs, you need to take some additional steps beyond what was described in setting up a development host. - The `Yocto Project Board Support Package (BSP) Developer's - Guide <&YOCTO_DOCS_BSP_URL;>`__ provides BSP-related development + The :doc:`../bsp-guide/bsp-guide` provides BSP-related development information. For specifics on development host preparation, see the - "`Preparing Your Build Host to Work With BSP - Layers <&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers>`__" + ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`" section in the Yocto Project Board Support Package (BSP) Developer's Guide. @@ -118,11 +116,10 @@ methods exist for you to do work in the Yocto Project environment: using ``devtool`` makes kernel development quicker by reducing iteration cycle times. - The `Yocto Project Linux Kernel Development - Manual <&YOCTO_DOCS_KERNEL_DEV_URL;>`__ provides kernel-related + The :doc:`../kernel-dev/kernel-dev` provides kernel-related development information. For specifics on development host - preparation, see the "`Preparing the Build Host to Work on the - Kernel <&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel>`__" + preparation, see the + ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`" section in the Yocto Project Linux Kernel Development Manual. - *Using Toaster:* The other Yocto Project development method that @@ -134,8 +131,8 @@ methods exist for you to do work in the Yocto Project environment: multiple remote build servers. For steps that show you how to set up your development host to use - Toaster and on how to use Toaster in general, see the `Toaster User - Manual <&YOCTO_DOCS_TOAST_URL;>`__. + Toaster and on how to use Toaster in general, see the + :doc:`../toaster-manual/toaster-manual`. .. _yocto-project-repositories: @@ -185,8 +182,7 @@ development: :align: center For steps on how to view and access these upstream Git repositories, - see the "`Accessing Source - Repositories <&YOCTO_DOCS_DEV_URL;#accessing-source-repositories>`__" + see the ":ref:`dev-manual/dev-manual-start:accessing source repositories`" Section in the Yocto Project Development Tasks Manual. - :yocto_dl:`Index of /releases: ` This is an index @@ -199,9 +195,8 @@ development: .. image:: figures/index-downloads.png :align: center - For steps on how to view and access these files, see the "`Accessing - Index of - Releases <&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases>`__" + For steps on how to view and access these files, see the + ":ref:`dev-manual/dev-manual-start:accessing index of releases`" section in the Yocto Project Development Tasks Manual. - *"DOWNLOADS" page for the* :yocto_home:`Yocto Project Website <>` *:* @@ -215,8 +210,8 @@ development: .. image:: figures/yp-download.png :align: center - For steps on how to use the "DOWNLOADS" page, see the "`Using the - Downloads Page <&YOCTO_DOCS_DEV_URL;#using-the-downloads-page>`__" + For steps on how to use the "DOWNLOADS" page, see the + ":ref:`dev-manual/dev-manual-start:using the downloads page`" section in the Yocto Project Development Tasks Manual. .. _gs-git-workflows-and-the-yocto-project: @@ -252,9 +247,9 @@ and so forth. .. note:: For information on finding out who is responsible for (maintains) a - particular area of code in the Yocto Project, see the " - Submitting a Change to the Yocto Project - " section of the Yocto Project Development Tasks Manual. + particular area of code in the Yocto Project, see the + ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`" + section of the Yocto Project Development Tasks Manual. The Yocto Project ``poky`` Git repository also has an upstream contribution Git repository named ``poky-contrib``. You can see all the @@ -284,9 +279,9 @@ A somewhat formal method exists 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 -submitting patches and changes, see the "`Submitting a Change to the -Yocto Project <&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change>`__" section -in the Yocto Project Development Tasks Manual. +submitting patches and changes, see the +":ref:`dev-manual/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" or development branch of the Git repository, which is controlled by the @@ -351,20 +346,18 @@ Book `__. release to facilitate this workflow. You can find these scripts in the ``scripts`` folder of the :term:`Source Directory`. For information - on how to use these scripts, see the "`Using Scripts to Push a Change - Upstream and Request a - Pull <&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream>`__" section in - the Yocto Project Development Tasks Manual. + on how to use these scripts, see the + ":ref:`dev-manual/dev-manual-common-tasks:using scripts to push a change upstream and request a pull`" + section in the Yocto Project Development Tasks Manual. - *Patch Workflow:* This workflow allows you to notify the maintainer through an email that you have a change (or patch) you would like considered for the "master" branch of the Git repository. To send this type of change, you format the patch and then send the email using the Git commands ``git format-patch`` and ``git send-email``. - For information on how to use these scripts, see the "`Submitting a - Change to the Yocto - Project <&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change>`__" section in - the Yocto Project Development Tasks Manual. + For information on how to use these scripts, see the + ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`" + section in the Yocto Project Development Tasks Manual. Git === @@ -389,8 +382,7 @@ commands. page, see http://git-scm.com/download. - For information beyond the introductory nature in this section, - see the "`Locating Yocto Project Source - Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__" + see the ":ref:`dev-manual/dev-manual-start:locating yocto project source files`" section in the Yocto Project Development Tasks Manual. Repositories, Tags, and Branches @@ -422,14 +414,13 @@ You can create a local copy of any repository by "cloning" it with the an identical copy of the repository on your development system. Once you have a local copy of a repository, you can take steps to develop locally. For examples on how to clone Git repositories, see the -"`Locating Yocto Project Source -Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__" +":ref:`dev-manual/dev-manual-start:locating yocto project source files`" section in the Yocto Project Development Tasks Manual. It is important to understand that Git tracks content change and not files. Git uses "branches" to organize different development efforts. For example, the ``poky`` repository has several branches that include -the current "DISTRO_NAME_NO_CAP" branch, the "master" branch, and many +the current "&DISTRO_NAME_NO_CAP;" branch, the "master" branch, and many branches for past Yocto Project releases. You can see all the branches by going to https://git.yoctoproject.org/cgit.cgi/poky/ and clicking on the ``[...]`` link beneath the "Branch" heading. @@ -444,17 +435,23 @@ local working area (also called a branch) that tracks a specific development branch from the upstream source Git repository. in other words, you can define your local Git environment to work on any development branch in the repository. To help illustrate, consider the -following example Git commands: $ cd ~ $ git clone -git://git.yoctoproject.org/poky $ cd poky $ git checkout -b -DISTRO_NAME_NO_CAP origin/DISTRO_NAME_NO_CAP In the previous example +following example Git commands: +:: + + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; + +In the previous example after moving to the home directory, the ``git clone`` command creates a local copy of the upstream ``poky`` Git repository. By default, Git checks out the "master" branch for your work. After changing the working directory to the new local repository (i.e. ``poky``), the ``git checkout`` command creates and checks out a local branch named -"DISTRO_NAME_NO_CAP", which tracks the upstream -"origin/DISTRO_NAME_NO_CAP" branch. Changes you make while in this -branch would ultimately affect the upstream "DISTRO_NAME_NO_CAP" branch +"&DISTRO_NAME_NO_CAP;", which tracks the upstream +"origin/&DISTRO_NAME_NO_CAP;" branch. Changes you make while in this +branch would ultimately affect the upstream "&DISTRO_NAME_NO_CAP;" branch of the ``poky`` repository. It is important to understand that when you create and checkout a local @@ -462,7 +459,7 @@ working branch based on a branch name, your local environment matches the "tip" of that particular development branch at the time you created your local branch, which could be different from the files in the "master" branch of the upstream repository. In other words, creating and -checking out a local branch based on the "DISTRO_NAME_NO_CAP" branch +checking out a local branch based on the "&DISTRO_NAME_NO_CAP;" branch name is not the same as checking out the "master" branch in the repository. Keep reading to see how you create a local snapshot of a Yocto Project Release. @@ -476,7 +473,7 @@ beneath the "Tag" heading. Some key tags for the ``poky`` repository are ``jethro-14.0.3``, ``morty-16.0.1``, ``pyro-17.0.0``, and -``DISTRO_NAME_NO_CAP-POKYVERSION``. These tags represent Yocto Project +``&DISTRO_NAME_NO_CAP;-&POKYVERSION;``. These tags represent Yocto Project releases. When you create a local copy of the Git repository, you also have access @@ -485,9 +482,16 @@ create and checkout a local working Git branch based on a tag name. When you do this, you get a snapshot of the Git repository that reflects the state of the files when the change was made associated with that tag. The most common use is to checkout a working branch that matches a -specific Yocto Project release. Here is an example: $ cd ~ $ git clone -git://git.yoctoproject.org/poky $ cd poky $ git fetch --tags $ git -checkout tags/rocko-18.0.0 -b my_rocko-18.0.0 In this example, the name +specific Yocto Project release. Here is an example: +:: + + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git fetch --tags + $ git checkout tags/rocko-18.0.0 -b my_rocko-18.0.0 + +In this example, the name of the top-level directory of your local Yocto Project repository is ``poky``. After moving to the ``poky`` directory, the ``git fetch`` command makes all the upstream tags available locally in your @@ -518,62 +522,62 @@ list (in most cases) simply shows the base command and omits the many arguments it supports. See the Git documentation for complete descriptions and strategies on how to use these commands: -- *``git init``:* Initializes an empty Git repository. You cannot use +- *git init:* Initializes an empty Git repository. You cannot use Git commands unless you have a ``.git`` repository. -- *``git clone``:* Creates a local clone of a Git repository that is on +- *git clone:* Creates a local clone of a Git repository that is on equal footing with a fellow developer’s Git repository or an upstream repository. -- *``git add``:* Locally stages updated file contents to the index that +- *git add:* Locally stages updated file contents to the index that Git uses to track changes. You must stage all files that have changed before you can commit them. -- *``git commit``:* Creates a local "commit" that documents the changes +- *git commit:* Creates a local "commit" that documents the changes you made. Only changes that have been staged can be committed. Commits are used for historical purposes, for determining if a maintainer of a project will allow the change, and for ultimately pushing the change from your local Git repository into the project’s upstream repository. -- *``git status``:* Reports any modified files that possibly need to be +- *git status:* Reports any modified files that possibly need to be staged and gives you a status of where you stand regarding local commits as compared to the upstream repository. -- *``git checkout`` branch-name:* Changes your local working branch and +- *git checkout branch-name:* Changes your local working branch and in this form assumes the local branch already exists. This command is analogous to "cd". -- *``git checkout –b`` working-branch upstream-branch:* Creates and +- *git checkout –b working-branch upstream-branch:* Creates and checks out a working branch on your local machine. The local branch tracks the upstream branch. You can use your local branch to isolate your work. It is a good idea to use local branches when adding specific features or changes. Using isolated branches facilitates easy removal of changes if they do not work out. -- *``git branch``:* Displays the existing local branches associated +- *git branch:* Displays the existing local branches associated with your local repository. The branch that you have currently checked out is noted with an asterisk character. -- *``git branch -D`` branch-name:* Deletes an existing local branch. +- *git branch -D branch-name:* Deletes an existing local branch. You need to be in a local branch other than the one you are deleting in order to delete branch-name. -- *``git pull --rebase``:* Retrieves information from an upstream Git +- *git pull --rebase:* Retrieves information from an upstream Git repository and places it in your local Git repository. You use this command to make sure you are synchronized with the repository from which you are basing changes (.e.g. the "master" branch). The "--rebase" option ensures that any local commits you have in your branch are preserved at the top of your local branch. -- *``git push`` repo-name local-branch\ ``:``\ upstream-branch:* Sends +- *git push repo-name local-branch:upstream-branch:* Sends all your committed local changes to the upstream Git repository that your local repository is tracking (e.g. a contribution repository). The maintainer of the project draws from these repositories to merge changes (commits) into the appropriate branch of project's upstream repository. -- *``git merge``:* Combines or adds changes from one local branch of +- *git merge:* Combines or adds changes from one local branch of your repository with another branch. When you create a local Git repository, the default branch is named "master". A typical workflow is to create a temporary branch that is based off "master" that you @@ -585,12 +589,12 @@ descriptions and strategies on how to use these commands: done with working in that isolated branch, you can safely delete the isolated branch. -- *``git cherry-pick`` commits:* Choose and apply specific commits from +- *git cherry-pick commits:* Choose and apply specific commits from one branch into another branch. There are times when you might not be able to merge all the changes in one branch with another but need to pick out certain ones. -- *``gitk``:* Provides a GUI view of the branches and changes in your +- *gitk:* Provides a GUI view of the branches and changes in your local Git repository. This command is a good way to graphically see where things have diverged in your local repository. @@ -600,11 +604,11 @@ descriptions and strategies on how to use these commands: gitk package on your development system to use this command. -- *``git log``:* Reports a history of your commits to the repository. +- *git log:* Reports a history of your commits to the repository. This report lists all commits regardless of whether you have pushed them upstream or not. -- *``git diff``:* Displays line-by-line differences between a local +- *git diff:* Displays line-by-line differences between a local working file and the same file as understood by Git. This command is useful to see what you have changed in any given file. @@ -663,7 +667,6 @@ Project uses in the ``meta/files/common-licenses`` directory in your For information that can help you maintain compliance with various open source licensing during the lifecycle of a product created using the -Yocto Project, see the "`Maintaining Open Source License Compliance -During Your Product's -Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__" +Yocto Project, see the +":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" section in the Yocto Project Development Tasks Manual. diff --git a/documentation/overview-manual/overview-manual-intro.rst b/documentation/overview-manual/overview-manual-intro.rst index 2e96f1e338..3f206fd54b 100644 --- a/documentation/overview-manual/overview-manual-intro.rst +++ b/documentation/overview-manual/overview-manual-intro.rst @@ -20,7 +20,7 @@ The following list describes what you can get from this manual: provides an introduction to the Yocto Project. You will learn about features and challenges of the Yocto Project, the layer model, components and tools, development methods, the - `Poky <&YOCTO_DOCS_REF_URL;#poky>`__ reference distribution, the + :term:`Poky` reference distribution, the OpenEmbedded build system workflow, and some basic Yocto terms. - `The Yocto Project Development @@ -30,7 +30,7 @@ The following list describes what you can get from this manual: Yocto Project source repositories, workflows using Git and the Yocto Project, a Git primer, and information about licensing. -- `Yocto Project Concepts <#overview-manual-concepts>`__\ *:* This +- :doc:`overview-manual-concepts` *:* This chapter presents various concepts regarding the Yocto Project. You can find conceptual information about components, development, cross-toolchains, and so forth. @@ -39,19 +39,17 @@ This manual does not give you the following: - *Step-by-step Instructions for Development Tasks:* Instructional procedures reside in other manuals within the Yocto Project - documentation set. For example, the `Yocto Project Development Tasks - Manual <&YOCTO_DOCS_DEV_URL;>`__ provides examples on how to perform - various development tasks. As another example, the `Yocto Project - Application Development and the Extensible Software Development Kit - (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual contains detailed + documentation set. For example, the :doc:`../dev-manual/dev-manual` + provides examples on how to perform + various development tasks. As another example, the + :doc:`../sdk-manual/sdk-manual` manual contains detailed instructions on how to install an SDK, which is used to develop applications for target hardware. - *Reference Material:* This type of material resides in an appropriate reference manual. For example, system variables are documented in the - `Yocto Project Reference Manual <&YOCTO_DOCS_REF_URL;>`__. As another - example, the `Yocto Project Board Support Package (BSP) Developer's - Guide <&YOCTO_DOCS_BSP_URL;>`__ contains reference information on + :doc:`../ref-manual/ref-manual`. As another + example, the :doc:`../bsp-guide/bsp-guide` contains reference information on BSPs. - *Detailed Public Information Not Specific to the Yocto Project:* For @@ -69,8 +67,8 @@ supplemental information is recommended for full comprehension. For additional introductory information on the Yocto Project, see the :yocto_home:`Yocto Project Website <>`. If you want to build an image with no knowledge of Yocto Project as a way of quickly testing it out, -see the `Yocto Project Quick Build <&YOCTO_DOCS_BRIEF_URL;>`__ document. +see the :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. For a comprehensive list of links and other documentation, see the -"`Links and Related -Documentation <&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation>`__" +":ref:`Links and Related +Documentation `" section in the Yocto Project Reference Manual. diff --git a/documentation/overview-manual/overview-manual-yp-intro.rst b/documentation/overview-manual/overview-manual-yp-intro.rst index 1a71308fc0..13ff7e9f0e 100644 --- a/documentation/overview-manual/overview-manual-yp-intro.rst +++ b/documentation/overview-manual/overview-manual-yp-intro.rst @@ -113,7 +113,7 @@ Project: development. - *Releases According to a Strict Schedule:* Major releases occur on a - `six-month cycle <&YOCTO_DOCS_REF_URL;#ref-release-process>`__ + :doc:`six-month cycle <../ref-manual/ref-release-process>` predictably in October and April. The most recent two releases support point releases to address common vulnerabilities and exposures. This predictability is crucial for projects based on the @@ -131,8 +131,8 @@ Project: in what order to support dependencies, other build systems can arbitrarily include packages. -- *License Manifest:* The Yocto Project provides a `license - manifest <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__ +- *License Manifest:* The Yocto Project provides a :ref:`license + manifest ` for review by people who need to track the use of open source licenses (e.g.legal teams). @@ -154,10 +154,8 @@ developing using the Yocto Project: changes need to be made for your particular design can require a significant amount of research and investigation. For information that helps you transition from trying out the Yocto Project to using - it for your project, see the "`What I wish I'd - Known <&YOCTO_DOCS_URL;/what-i-wish-id-known/>`__" and - "`Transitioning to a Custom Environment for Systems - Development <&YOCTO_DOCS_URL;/transitioning-to-a-custom-environment/>`__" + it for your project, see the ":ref:`what-i-wish-id-known:what i wish i'd known about yocto project`" and + ":ref:`transitioning-to-a-custom-environment:transitioning to a custom environment for systems development`" documents on the Yocto Project website. - *Project Workflow Could Be Confusing:* The `Yocto Project @@ -233,8 +231,8 @@ your Metadata, the easier it is to cope with future changes. validated. - Layers support the inclusion of technologies, hardware components, - and software components. The `Yocto Project - Compatible <&YOCTO_DOCS_DEV_URL;#making-sure-your-layer-is-compatible-with-yocto-project>`__ + and software components. The :ref:`Yocto Project + Compatible ` designation provides a minimum level of standardization that contributes to a strong ecosystem. "YP Compatible" is applied to appropriate products and software components such as BSPs, other @@ -280,9 +278,8 @@ view `__ of the ``meta-yocto-bsp``. Each of these repositories represents a distinct layer. -For procedures on how to create layers, see the "`Understanding and -Creating -Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" +For procedures on how to create layers, see the +":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" section in the Yocto Project Development Tasks Manual. Components and Tools @@ -292,7 +289,7 @@ The Yocto Project employs a collection of components and tools used by the project itself, by project developers, and by those using the Yocto Project. These components and tools are open source projects and metadata that are separate from the reference distribution -(`Poky <&YOCTO_DOCS_REF_URL;#poky>`__) and the +(:term:`Poky`) and the :term:`OpenEmbedded Build System`. Most of the components and tools are downloaded separately. @@ -336,8 +333,8 @@ applications using the Yocto Project: You can read about the ``devtool`` workflow in the Yocto Project Application Development and Extensible Software Development Kit - (eSDK) Manual in the "`Using ``devtool`` in Your SDK - Workflow' <&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow>`__" + (eSDK) Manual in the + ":ref:`sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow`" section. - *Extensible Software Development Kit (eSDK):* The eSDK provides a @@ -349,14 +346,12 @@ applications using the Yocto Project: experience supplemented with the powerful set of ``devtool`` commands tailored for the Yocto Project environment. - For information on the eSDK, see the `Yocto Project Application - Development and the Extensible Software Development Kit - (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ Manual. + For information on the eSDK, see the :doc:`../sdk-manual/sdk-manual` Manual. - *Toaster:* Toaster is a web interface to the Yocto Project OpenEmbedded build system. Toaster allows you to configure, run, and view information about builds. For information on Toaster, see the - `Toaster User Manual <&YOCTO_DOCS_TOAST_URL;>`__. + :doc:`../toaster-manual/toaster-manual`. .. _gs-production-tools: @@ -406,7 +401,7 @@ activities using the Yocto Project: benefit of the development community. You can learn more about the AutoBuilder used by the Yocto Project - `here <&YOCTO_AB_URL;>`__. + Autobuilder :doc:`here <../test-manual/test-manual-understand-autobuilder>`. - *Cross-Prelink:* Prelinking is the process of pre-computing the load addresses and link tables generated by the dynamic linker as compared @@ -595,8 +590,8 @@ Linux. Development Methods =================== -The Yocto Project development environment usually involves a `Build -Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ and target +The Yocto Project development environment usually involves a +:term:`Build Host` and target hardware. You use the Build Host to build images and develop applications, while you use the target hardware to test deployed software. @@ -622,8 +617,8 @@ Project. supported Linux distribution. For information on how to set up a Build Host on a system running - Linux as its native operating system, see the "`Setting Up a Native - Linux Host <&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host>`__" + Linux as its native operating system, see the + ":ref:`dev-manual/dev-manual-start:setting up a native linux host`" section in the Yocto Project Development Tasks Manual. - *CROss PlatformS (CROPS):* Typically, you use @@ -643,9 +638,8 @@ Project. system natively running Linux. For information on how to set up a Build Host with CROPS, see the - "`Setting Up to Use CROss PlatformS - (CROPS) <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops>`__" section in - the Yocto Project Development Tasks Manual. + ":ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)`" + section in the Yocto Project Development Tasks Manual. - *Windows Subsystem For Linux (WSLv2):* You may use Windows Subsystem For Linux v2 to set up a build host using Windows 10. @@ -661,9 +655,8 @@ Project. virtualization technology. For information on how to set up a Build Host with WSLv2, see the - "`Setting Up to Use Windows Subsystem For - Linux <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-wsl>`__" section in the - Yocto Project Development Tasks Manual. + ":ref:dev-manual/dev-manual-start:setting up to use windows subsystem for linux (wslv2)`" + section in the Yocto Project Development Tasks Manual. - *Toaster:* Regardless of what your Build Host is running, you can use Toaster to develop software using the Yocto Project. Toaster is a web @@ -673,8 +666,8 @@ Project. builds is collected and stored in a database. You can use Toaster to configure and start builds on multiple remote build servers. - For information about and how to use Toaster, see the `Toaster User - Manual <&YOCTO_DOCS_TOAST_URL;>`__. + For information about and how to use Toaster, see the + :doc:`../toaster-manual/toaster-manual`. .. _reference-embedded-distribution: @@ -686,7 +679,7 @@ Project's reference distribution or Reference OS Kit. Poky contains the :term:`OpenEmbedded Build System` (:term:`BitBake` and :term:`OpenEmbedded-Core (OE-Core)`) as well as a set -of `metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ to get you started +of :term:`Metadata` to get you started building your own distro. In other words, Poky is a base specification of the functionality needed for a typical embedded system as well as the components from the Yocto Project that allow you to build a distribution @@ -747,8 +740,7 @@ Poky has a regular, well established, six-month release cycle under its own version. Major releases occur at the same time major releases (point releases) occur for the Yocto Project, which are typically in the Spring and Fall. For more information on the Yocto Project release schedule and -cadence, see the "`Yocto Project Releases and the Stable Release -Process <&YOCTO_DOCS_REF_URL;#ref-release-process>`__" chapter in the +cadence, see the ":doc:`../ref-manual/ref-release-process`" chapter in the Yocto Project Reference Manual. Much has been said about Poky being a "default configuration." A default @@ -827,8 +819,8 @@ Some Basic Terms ================ It helps to understand some basic fundamental terms when learning the -Yocto Project. Although a list of terms exists in the "`Yocto Project -Terms <&YOCTO_DOCS_REF_URL;#ref-terms>`__" section of the Yocto Project +Yocto Project. Although a list of terms exists in the ":doc:`Yocto Project +Terms <../ref-manual/ref-terms>`" section of the Yocto Project Reference Manual, this section provides the definitions of some terms helpful for getting started: @@ -842,9 +834,7 @@ helpful for getting started: application developers. This eSDK allows developers to incorporate their library and programming changes back into the image to make their code available to other application developers. For information - on the eSDK, see the `Yocto Project Application Development and the - Extensible Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ - manual. + on the eSDK, see the :doc:`../sdk-manual/sdk-manual` manual. - *Layer:* A collection of related recipes. Layers allow you to consolidate related metadata to customize your build. Layers also @@ -855,12 +845,11 @@ helpful for getting started: them. You can search the Layer Index for layers used within Yocto Project. - For more detailed information on layers, see the "`Understanding and - Creating - Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" + For more detailed information on layers, see the + ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" section in the Yocto Project Development Tasks Manual. For a - discussion specifically on BSP Layers, see the "`BSP - Layers <&YOCTO_DOCS_BSP_URL;#bsp-layers>`__" section in the Yocto + discussion specifically on BSP Layers, see the + ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board Support Packages (BSP) Developer's Guide. - *Metadata:* A key element of the Yocto Project is the Metadata that @@ -913,8 +902,7 @@ helpful for getting started: It is worth noting that the term "package" can, in general, have subtle meanings. For example, the packages referred to in the - "`Required Packages for the Build - Host <&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host>`__" + ":ref:`ref-manual/ref-system-requirements:required packages for the build host`" section in the Yocto Project Reference Manual are compiled binaries that, when installed, add functionality to your Linux distribution. -- cgit v1.2.3-54-g00ecf