From c473fa229239752367c5d573160fc8738cf1907e Mon Sep 17 00:00:00 2001 From: Nicolas Dechesne Date: Fri, 24 Jul 2020 16:27:54 +0200 Subject: 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 `", line) line = re.sub("`+([a-z_\-\*\.]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__", ":ref:`\\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 Signed-off-by: Richard Purdie --- .../sdk-appendix-customizing-standard.rst | 6 +- .../sdk-manual/sdk-appendix-customizing.rst | 50 ++++++++--------- documentation/sdk-manual/sdk-appendix-obtain.rst | 8 +-- documentation/sdk-manual/sdk-extensible.rst | 64 +++++++++++----------- documentation/sdk-manual/sdk-intro.rst | 10 ++-- documentation/sdk-manual/sdk-working-projects.rst | 4 +- 6 files changed, 71 insertions(+), 71 deletions(-) (limited to 'documentation/sdk-manual') diff --git a/documentation/sdk-manual/sdk-appendix-customizing-standard.rst b/documentation/sdk-manual/sdk-appendix-customizing-standard.rst index 02f7d764ca..f6f2b6640f 100644 --- a/documentation/sdk-manual/sdk-appendix-customizing-standard.rst +++ b/documentation/sdk-manual/sdk-appendix-customizing-standard.rst @@ -11,9 +11,9 @@ Adding Individual Packages to the Standard SDK When you build a standard SDK using the ``bitbake -c populate_sdk``, a default set of packages is included in the resulting SDK. The -```TOOLCHAIN_HOST_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK>`__ +:term:`TOOLCHAIN_HOST_TASK` and -```TOOLCHAIN_TARGET_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK>`__ +:term:`TOOLCHAIN_TARGET_TASK` variables control the set of packages adding to the SDK. If you want to add individual packages to the toolchain that runs on the @@ -28,7 +28,7 @@ Adding API Documentation to the Standard SDK You can include API documentation as well as any other documentation provided by recipes with the standard SDK by adding "api-documentation" to the -```DISTRO_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES>`__ +:term:`DISTRO_FEATURES` variable: DISTRO_FEATURES_append = " api-documentation" Setting this variable as shown here causes the OpenEmbedded build system to build the documentation and then include it in the standard SDK. diff --git a/documentation/sdk-manual/sdk-appendix-customizing.rst b/documentation/sdk-manual/sdk-appendix-customizing.rst index 522b41033d..8169f2bed8 100644 --- a/documentation/sdk-manual/sdk-appendix-customizing.rst +++ b/documentation/sdk-manual/sdk-appendix-customizing.rst @@ -22,7 +22,7 @@ build system applies them against ``local.conf`` and ``auto.conf``: host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__. - Variables listed in - ```SDK_LOCAL_CONF_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST>`__ + :term:`SDK_LOCAL_CONF_BLACKLIST` are excluded. These variables are not allowed through from the OpenEmbedded build system configuration into the extensible SDK configuration. Typically, these variables are specific to the machine @@ -30,23 +30,23 @@ build system applies them against ``local.conf`` and ``auto.conf``: of the extensible SDK configuration. For a list of the variables excluded by default, see the - ```SDK_LOCAL_CONF_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST>`__ + :term:`SDK_LOCAL_CONF_BLACKLIST` in the glossary of the Yocto Project Reference Manual. - Variables listed in - ```SDK_LOCAL_CONF_WHITELIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST>`__ + :term:`SDK_LOCAL_CONF_WHITELIST` are included. Including a variable in the value of ``SDK_LOCAL_CONF_WHITELIST`` overrides either of the previous two filters. The default value is blank. - Classes inherited globally with - ```INHERIT`` <&YOCTO_DOCS_REF_URL;#var-INHERIT>`__ that are listed in - ```SDK_INHERIT_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST>`__ + :term:`INHERIT` that are listed in + :term:`SDK_INHERIT_BLACKLIST` are disabled. Using ``SDK_INHERIT_BLACKLIST`` to disable these classes is the typical method to disable classes that are problematic or unnecessary in the SDK context. The default value blacklists the - ```buildhistory`` <&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory>`__ - and ```icecc`` <&YOCTO_DOCS_REF_URL;#ref-classes-icecc>`__ classes. + :ref:`buildhistory ` + and :ref:`icecc ` classes. Additionally, the contents of ``conf/sdk-extra.conf``, when present, are appended to the end of ``conf/local.conf`` within the produced SDK, @@ -63,10 +63,10 @@ However, some cases exist for which you might consider making adjustments: - If your SDK configuration inherits additional classes using the - ```INHERIT`` <&YOCTO_DOCS_REF_URL;#var-INHERIT>`__ variable and you + :term:`INHERIT` variable and you do not need or want those classes enabled in the SDK, you can blacklist them by adding them to the - ```SDK_INHERIT_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST>`__ + :term:`SDK_INHERIT_BLACKLIST` variable as described in the fourth bullet of the previous section. .. note:: @@ -93,7 +93,7 @@ adjustments: state cache) or ensuring the tasks are able to be produced quickly from a task that is a shared state task, add the task name to the value of - ```SDK_RECRDEP_TASKS`` <&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS>`__. + :term:`SDK_RECRDEP_TASKS`. - Disable the tasks if they are added by a class and you do not need the functionality the class provides in the extensible SDK. To @@ -109,24 +109,24 @@ adjustments: - If you want users of the SDK to be able to easily update the SDK, you need to set the - ```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__ + :term:`SDK_UPDATE_URL` variable. For more information, see the "`Providing Updates to the Extensible SDK After Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__" section. - If you have adjusted the list of files and directories that appear in - ```COREBASE`` <&YOCTO_DOCS_REF_URL;#var-COREBASE>`__ (other than + :term:`COREBASE` (other than layers that are enabled through ``bblayers.conf``), then you must list these files in - ```COREBASE_FILES`` <&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES>`__ so + :term:`COREBASE_FILES` so that the files are copied into the SDK. - If your OpenEmbedded build system setup uses a different environment setup script other than ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, then you must set - ```OE_INIT_ENV_SCRIPT`` <&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT>`__ + :term:`OE_INIT_ENV_SCRIPT` to point to the environment setup script you use. .. note:: @@ -139,15 +139,15 @@ Changing the Extensible SDK Installer Title =========================================== You can change the displayed title for the SDK installer by setting the -```SDK_TITLE`` <&YOCTO_DOCS_REF_URL;#var-SDK_TITLE>`__ variable and then +:term:`SDK_TITLE` variable and then rebuilding the the SDK installer. For information on how to build an SDK installer, see the "`Building an SDK Installer <#sdk-building-an-sdk-installer>`__" section. By default, this title is derived from -```DISTRO_NAME`` <&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME>`__ when it is +:term:`DISTRO_NAME` when it is set. If the ``DISTRO_NAME`` variable is not set, the title is derived -from the ```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__ variable. +from the :term:`DISTRO` variable. The ```populate_sdk_base`` <&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*>`__ @@ -181,7 +181,7 @@ the installed SDKs to update the installed SDKs by using the to host the directory. This directory must contain the published SDK. 2. Set the - ```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__ + :term:`SDK_UPDATE_URL` variable to point to the corresponding HTTP or HTTPS URL. Setting this variable causes any SDK built to default to that URL and thus, the user does not have to pass the URL to the ``devtool sdk-update`` @@ -209,8 +209,8 @@ Changing the Default SDK Installation Directory When you build the installer for the Extensible SDK, the default installation directory for the SDK is based on the -```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__ and -```SDKEXTPATH`` <&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH>`__ variables from +:term:`DISTRO` and +:term:`SDKEXTPATH` variables from within the ```populate_sdk_base`` <&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*>`__ class as follows: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" You can @@ -248,7 +248,7 @@ source, you need to do a number of things: - Build the "world" target and set ``EXCLUDE_FROM_WORLD_pn-``\ recipename for the recipes you do not want built. See the - ```EXCLUDE_FROM_WORLD`` <&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD>`__ + :term:`EXCLUDE_FROM_WORLD` variable for additional information. 2. Expose the ``sstate-cache`` directory produced by the build. @@ -259,7 +259,7 @@ source, you need to do a number of things: 3. Set the appropriate configuration so that the produced SDK knows how to find the configuration. The variable you need to set is - ```SSTATE_MIRRORS`` <&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS>`__: + :term:`SSTATE_MIRRORS`: SSTATE_MIRRORS = "file://.\* http://example.com/some_path/sstate-cache/PATH" You can set the ``SSTATE_MIRRORS`` variable in two different places: @@ -297,7 +297,7 @@ more in size. If the size of this file causes a problem, you can build an SDK that has just enough in it to install and provide access to the ``devtool command`` by setting the following in your configuration: SDK_EXT_TYPE = "minimal" Setting -```SDK_EXT_TYPE`` <&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE>`__ to +:term:`SDK_EXT_TYPE` to "minimal" produces an SDK installer that is around 35 Mbytes in size, which downloads and installs quickly. You need to realize, though, that the minimal installer does not install any libraries or tools out of the @@ -315,7 +315,7 @@ results. To facilitate this wider range of information, you would need to set the following: SDK_INCLUDE_PKGDATA = "1" See the -```SDK_INCLUDE_PKGDATA`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA>`__ +:term:`SDK_INCLUDE_PKGDATA` variable for additional information. Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world" @@ -341,7 +341,7 @@ in most cases. You can explicitly control whether or not to include the toolchain when you build an SDK by setting the -```SDK_INCLUDE_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN>`__ +:term:`SDK_INCLUDE_TOOLCHAIN` variable to "1". In particular, it is useful to include the toolchain when you have set ``SDK_EXT_TYPE`` to "minimal", which by default, excludes the toolchain. Also, it is helpful if you are building a small diff --git a/documentation/sdk-manual/sdk-appendix-obtain.rst b/documentation/sdk-manual/sdk-appendix-obtain.rst index 1c69b3254d..c6efdf674c 100644 --- a/documentation/sdk-manual/sdk-appendix-obtain.rst +++ b/documentation/sdk-manual/sdk-appendix-obtain.rst @@ -95,14 +95,14 @@ build the SDK installer. Follow these steps: 4. *Make Sure You Are Building an Installer for the Correct Machine:* Check to be sure that your - ```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable in the + :term:`MACHINE` variable in the ``local.conf`` file in your Build Directory matches the architecture for which you are building. 5. *Make Sure Your SDK Machine is Correctly Set:* If you are building a toolchain designed to run on an architecture that differs from your current development host machine (i.e. the build host), be sure that - the ```SDKMACHINE`` <&YOCTO_DOCS_REF_URL;#var-SDKMACHINE>`__ variable + the :term:`SDKMACHINE` variable in the ``local.conf`` file in your Build Directory is correctly set. .. note:: @@ -138,7 +138,7 @@ build the SDK installer. Follow these steps: binaries. If you want to use the toolchain to build these types of libraries, you need to be sure your SDK has the appropriate static development libraries. Use the - ```TOOLCHAIN_TARGET_TASK`` <&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK>`__ + :term:`TOOLCHAIN_TARGET_TASK` variable inside your ``local.conf`` file before building the SDK installer. Doing so ensures that the eventual SDK installation process installs the appropriate library packages @@ -189,7 +189,7 @@ Follow these steps to extract the root filesystem: filesystem image's profile: lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs, sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on these types of image profiles, see - the "`Images <&YOCTO_DOCS_REF_URL;#ref-images>`__" chapter in the + the ":ref:`ref-manual/ref-images:Images`" chapter in the Yocto Project Reference Manual. arch is a string representing the target architecture: beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb, genericx86, genericx86-64, diff --git a/documentation/sdk-manual/sdk-extensible.rst b/documentation/sdk-manual/sdk-extensible.rst index cccc857d46..17cd08a25c 100644 --- a/documentation/sdk-manual/sdk-extensible.rst +++ b/documentation/sdk-manual/sdk-extensible.rst @@ -148,8 +148,8 @@ SDK environment now set up; additionally you may now run devtool to perform development tasks. Run devtool --help for further details. Running the setup script defines many environment variables needed in order to use the SDK (e.g. ``PATH``, -```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__, -```LD`` <&YOCTO_DOCS_REF_URL;#var-LD>`__, and so forth). If you want to +:term:`CC`, +:term:`LD`, and so forth). If you want to see all the environment variables the script exports, examine the installation file itself. @@ -215,7 +215,7 @@ Use ``devtool add`` to Add an Application The ``devtool add`` command generates a new recipe based on existing source code. This command takes advantage of the -`workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__ +:ref:`devtool-the-workspace-layer-structure` layer that many ``devtool`` commands use. The command is flexible enough to allow you to extract source code into both the workspace or a separate local Git repository and to use existing code that does not @@ -397,7 +397,7 @@ command: The following command identifies the recipe and, by default, extracts the source files: $ devtool modify recipe Once ``devtool``\ locates the recipe, ``devtool`` uses the recipe's - ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements to + :term:`SRC_URI` statements to locate the source code and any local patch files from other developers. @@ -569,7 +569,7 @@ counterparts. The ``devtool upgrade`` command is flexible enough to allow you to specify source code revision and versioning schemes, extract code into or out of the ``devtool`` -`workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__, +:ref:`devtool-the-workspace-layer-structure`, and work with any source file forms that the `fetchers <&YOCTO_DOCS_BB_URL;#bb-fetchers>`__ support. @@ -584,7 +584,7 @@ The following diagram shows the common development flow used with the workspace. - The source files for the new release exist in the same location - pointed to by ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ + pointed to by :term:`SRC_URI` in the recipe (e.g. a tarball with the new version number in the name, or as a different revision in the upstream Git repository). @@ -594,7 +594,7 @@ The following diagram shows the common development flow used with the use the newer version of the software: $ devtool upgrade -V version recipe By default, the ``devtool upgrade`` command extracts source code into the ``sources`` directory in the - `workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__. + :ref:`devtool-the-workspace-layer-structure`. If you want the code extracted to any other location, you need to provide the srctree positional argument with the command as follows: $ devtool upgrade -V version recipe srctree @@ -773,7 +773,7 @@ Dependency Detection and Mapping The ``devtool add`` command attempts to detect build-time dependencies and map them to other recipes in the system. During this mapping, the command fills in the names of those recipes as part of the -```DEPENDS`` <&YOCTO_DOCS_REF_URL;#var-DEPENDS>`__ variable within the +:term:`DEPENDS` variable within the recipe. If a dependency cannot be mapped, ``devtool`` places a comment in the recipe indicating such. The inability to map a dependency can result from naming not being recognized or because the dependency simply @@ -807,13 +807,13 @@ License Detection The ``devtool add`` command attempts to determine if the software you are adding is able to be distributed under a common, open-source license. If so, the command sets the -```LICENSE`` <&YOCTO_DOCS_REF_URL;#var-LICENSE>`__ value accordingly. +:term:`LICENSE` value accordingly. You should double-check the value added by the command against the documentation or source files for the software you are building and, if necessary, update that ``LICENSE`` value. The ``devtool add`` command also sets the -```LIC_FILES_CHKSUM`` <&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM>`__ +:term:`LIC_FILES_CHKSUM` value to point to all files that appear to be license-related. Realize that license statements often appear in comments at the top of source files or within the documentation. In such cases, the command does not @@ -842,7 +842,7 @@ open-source software. Unfortunately, Makefiles are often not written with cross-compilation in mind. Thus, ``devtool add`` often cannot do very much to ensure that these Makefiles build correctly. It is very common, for example, to explicitly call ``gcc`` instead of using the -```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__ variable. Usually, in a +:term:`CC` variable. Usually, in a cross-compilation environment, ``gcc`` is the compiler for the build host and the cross-compiler is named something similar to ``arm-poky-linux-gnueabi-gcc`` and might require arguments (e.g. to @@ -869,8 +869,8 @@ mind: sets the default using the "?=" operator, or you can alternatively force the value on the ``make`` command line. To force the value on the command line, add the variable setting to - ```EXTRA_OEMAKE`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE>`__ or - ```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__ + :term:`EXTRA_OEMAKE` or + :term:`PACKAGECONFIG_CONFARGS` within the recipe. Here is an example using ``EXTRA_OEMAKE``: EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" In the above example, single quotes are used around the variable settings as the values are @@ -951,7 +951,7 @@ repository or local source tree. To add modules this way, use https://github.com/diversario/node-ssdp In this example, ``devtool`` fetches the specified Git repository, detects the code as Node.js code, fetches dependencies using ``npm``, and sets -```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ accordingly. +:term:`SRC_URI` accordingly. .. _sdk-working-with-recipes: @@ -976,8 +976,8 @@ build progresses as follows: For recipes in the workspace, fetching and unpacking is disabled as the source tree has already been prepared and is persistent. Each of these build steps is defined as a function (task), usually with a "do_" prefix -(e.g. ```do_fetch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-fetch>`__, -```do_unpack`` <&YOCTO_DOCS_REF_URL;#ref-tasks-unpack>`__, and so +(e.g. :ref:`ref-tasks-fetch`, +:ref:`ref-tasks-unpack`, and so forth). These functions are typically shell scripts but can instead be written in Python. @@ -986,7 +986,7 @@ does not include complete instructions for building the software. Instead, common functionality is encapsulated in classes inherited with the ``inherit`` directive. This technique leaves the recipe to describe just the things that are specific to the software being built. A -```base`` <&YOCTO_DOCS_REF_URL;#ref-classes-base>`__ class exists that +:ref:`base ` class exists that is implicitly inherited by all recipes and provides the functionality that most recipes typically need. @@ -1011,9 +1011,9 @@ links created within the source tree: useful: - ``image/``: Contains all of the files installed during the - ```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ stage. + :ref:`ref-tasks-install` stage. Within a recipe, this directory is referred to by the expression - ``${``\ ```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__\ ``}``. + ``${``\ :term:`D`\ ``}``. - ``sysroot-destdir/``: Contains a subset of files installed within ``do_install`` that have been put into the shared sysroot. For @@ -1035,16 +1035,16 @@ Setting Configure Arguments If the software your recipe is building uses GNU autoconf, then a fixed set of arguments is passed to it to enable cross-compilation plus any extras specified by -```EXTRA_OECONF`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF>`__ or -```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__ +:term:`EXTRA_OECONF` or +:term:`PACKAGECONFIG_CONFARGS` set within the recipe. If you wish to pass additional options, add them to ``EXTRA_OECONF`` or ``PACKAGECONFIG_CONFARGS``. Other supported build tools have similar variables (e.g. -```EXTRA_OECMAKE`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE>`__ for -CMake, ```EXTRA_OESCONS`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS>`__ +:term:`EXTRA_OECMAKE` for +CMake, :term:`EXTRA_OESCONS` for Scons, and so forth). If you need to pass anything on the ``make`` command line, you can use ``EXTRA_OEMAKE`` or the -```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__ +:term:`PACKAGECONFIG_CONFARGS` variables to do so. You can use the ``devtool configure-help`` command to help you set the @@ -1071,8 +1071,8 @@ the build host. Recipes should never write files directly into the sysroot. Instead, files should be installed into standard locations during the -```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task within -the ``${``\ ```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__\ ``}`` directory. A +:ref:`ref-tasks-install` task within +the ``${``\ :term:`D`\ ``}`` directory. A subset of these files automatically goes into the sysroot. The reason for this limitation is that almost all files that go into the sysroot are cataloged in manifests in order to ensure they can be removed later @@ -1090,9 +1090,9 @@ the target device, it is important to understand packaging because the contents of the image are expressed in terms of packages and not recipes. -During the ```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__ +During the :ref:`ref-tasks-package` task, files installed during the -```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task are +:ref:`ref-tasks-install` task are split into one main package, which is almost always named the same as the recipe, and into several other packages. This separation exists because not all of those installed files are useful in every image. For @@ -1105,14 +1105,14 @@ package splitting as well. After building a recipe, you can see where files have gone by looking in the ``oe-workdir/packages-split`` directory, which contains a subdirectory for each package. Apart from some advanced cases, the -```PACKAGES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGES>`__ and -```FILES`` <&YOCTO_DOCS_REF_URL;#var-FILES>`__ variables controls +:term:`PACKAGES` and +:term:`FILES` variables controls splitting. The ``PACKAGES`` variable lists all of the packages to be produced, while the ``FILES`` variable specifies which files to include in each package by using an override to specify the package. For example, ``FILES_${PN}`` specifies the files to go into the main package (i.e. the main package has the same name as the recipe and -``${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}`` evaluates to the +``${``\ :term:`PN`\ ``}`` evaluates to the recipe name). The order of the ``PACKAGES`` value is significant. For each installed file, the first package whose ``FILES`` value matches the file is the package into which the file goes. Defaults exist for both @@ -1190,7 +1190,7 @@ manually "pull down" the updates into the installed SDK. To update your installed SDK, use ``devtool`` as follows: $ devtool sdk-update The previous command assumes your SDK provider has set the default update URL for you through the -```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__ +:term:`SDK_UPDATE_URL` variable as described in the "`Providing Updates to the Extensible SDK After Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__" diff --git a/documentation/sdk-manual/sdk-intro.rst b/documentation/sdk-manual/sdk-intro.rst index 1a07a9e7a9..fcb15a8592 100644 --- a/documentation/sdk-manual/sdk-intro.rst +++ b/documentation/sdk-manual/sdk-intro.rst @@ -56,8 +56,8 @@ toolchain binaries are produced for any given architecture. This feature takes advantage of the fact that the target hardware can be passed to ``gcc`` as a set of compiler options. Those options are set up by the environment script and contained in variables such as -```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__ and -```LD`` <&YOCTO_DOCS_REF_URL;#var-LD>`__. This reduces the space needed +:term:`CC` and +:term:`LD`. This reduces the space needed for the tools. Understand, however, that every target still needs a sysroot because those binaries are target-specific. @@ -66,7 +66,7 @@ The SDK development environment consists of the following: - The self-contained SDK, which is an architecture-specific cross-toolchain and matching sysroots (target and native) all built by the OpenEmbedded build system (e.g. the SDK). The toolchain and - sysroots are based on a `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ + sysroots are based on a :term:`Metadata` configuration and extensions, which allows you to cross-develop on the host machine for the target hardware. Additionally, the extensible SDK contains the ``devtool`` functionality. @@ -107,9 +107,9 @@ when considering which to build: +-----------------------+-----------------------+-----------------------+ \* Extensible SDK contains the toolchain and debugger if -```SDK_EXT_TYPE`` <&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE>`__ is "full" +:term:`SDK_EXT_TYPE` is "full" or -```SDK_INCLUDE_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN>`__ +:term:`SDK_INCLUDE_TOOLCHAIN` is "1", which is the default. \*\* Sysroot is managed through the use of ``devtool``. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries. \**\* You can add diff --git a/documentation/sdk-manual/sdk-working-projects.rst b/documentation/sdk-manual/sdk-working-projects.rst index 1d001d1099..63f61de66d 100644 --- a/documentation/sdk-manual/sdk-working-projects.rst +++ b/documentation/sdk-manual/sdk-working-projects.rst @@ -79,7 +79,7 @@ project: 4. *Cross-Compile the Project:* This command compiles the project using the cross-compiler. The - ```CONFIGURE_FLAGS`` <&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS>`__ + :term:`CONFIGURE_FLAGS` environment variable provides the minimal arguments for GNU configure: $ ./configure ${CONFIGURE_FLAGS} For an Autotools-based project, you can use the cross-toolchain by just passing the @@ -167,7 +167,7 @@ demonstrates these variable behaviors. In a new shell environment variables are not established for the SDK until you run the setup script. For example, the following commands show a null value for the compiler variable (i.e. -```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__). $ echo ${CC} $ Running the +:term:`CC`). $ echo ${CC} $ Running the SDK setup script for a 64-bit build host and an i586-tuned target architecture for a ``core-image-sato`` image using the current DISTRO Yocto Project release and then echoing that variable shows the value -- cgit v1.2.3-54-g00ecf