summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-extensible.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual/sdk-extensible.rst')
-rw-r--r--documentation/sdk-manual/sdk-extensible.rst64
1 files changed, 32 insertions, 32 deletions
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
148perform development tasks. Run devtool --help for further details. 148perform development tasks. Run devtool --help for further details.
149Running the setup script defines many environment variables needed in 149Running the setup script defines many environment variables needed in
150order to use the SDK (e.g. ``PATH``, 150order to use the SDK (e.g. ``PATH``,
151```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__, 151:term:`CC`,
152```LD`` <&YOCTO_DOCS_REF_URL;#var-LD>`__, and so forth). If you want to 152:term:`LD`, and so forth). If you want to
153see all the environment variables the script exports, examine the 153see all the environment variables the script exports, examine the
154installation file itself. 154installation file itself.
155 155
@@ -215,7 +215,7 @@ Use ``devtool add`` to Add an Application
215 215
216The ``devtool add`` command generates a new recipe based on existing 216The ``devtool add`` command generates a new recipe based on existing
217source code. This command takes advantage of the 217source code. This command takes advantage of the
218`workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__ 218:ref:`devtool-the-workspace-layer-structure`
219layer that many ``devtool`` commands use. The command is flexible enough 219layer that many ``devtool`` commands use. The command is flexible enough
220to allow you to extract source code into both the workspace or a 220to allow you to extract source code into both the workspace or a
221separate local Git repository and to use existing code that does not 221separate local Git repository and to use existing code that does not
@@ -397,7 +397,7 @@ command:
397 The following command identifies the recipe and, by default, 397 The following command identifies the recipe and, by default,
398 extracts the source files: $ devtool modify recipe Once 398 extracts the source files: $ devtool modify recipe Once
399 ``devtool``\ locates the recipe, ``devtool`` uses the recipe's 399 ``devtool``\ locates the recipe, ``devtool`` uses the recipe's
400 ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements to 400 :term:`SRC_URI` statements to
401 locate the source code and any local patch files from other 401 locate the source code and any local patch files from other
402 developers. 402 developers.
403 403
@@ -569,7 +569,7 @@ counterparts.
569The ``devtool upgrade`` command is flexible enough to allow you to 569The ``devtool upgrade`` command is flexible enough to allow you to
570specify source code revision and versioning schemes, extract code into 570specify source code revision and versioning schemes, extract code into
571or out of the ``devtool`` 571or out of the ``devtool``
572`workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__, 572:ref:`devtool-the-workspace-layer-structure`,
573and work with any source file forms that the 573and work with any source file forms that the
574`fetchers <&YOCTO_DOCS_BB_URL;#bb-fetchers>`__ support. 574`fetchers <&YOCTO_DOCS_BB_URL;#bb-fetchers>`__ support.
575 575
@@ -584,7 +584,7 @@ The following diagram shows the common development flow used with the
584 workspace. 584 workspace.
585 585
586 - The source files for the new release exist in the same location 586 - The source files for the new release exist in the same location
587 pointed to by ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ 587 pointed to by :term:`SRC_URI`
588 in the recipe (e.g. a tarball with the new version number in the 588 in the recipe (e.g. a tarball with the new version number in the
589 name, or as a different revision in the upstream Git repository). 589 name, or as a different revision in the upstream Git repository).
590 590
@@ -594,7 +594,7 @@ The following diagram shows the common development flow used with the
594 use the newer version of the software: $ devtool upgrade -V version 594 use the newer version of the software: $ devtool upgrade -V version
595 recipe By default, the ``devtool upgrade`` command extracts source 595 recipe By default, the ``devtool upgrade`` command extracts source
596 code into the ``sources`` directory in the 596 code into the ``sources`` directory in the
597 `workspace <&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure>`__. 597 :ref:`devtool-the-workspace-layer-structure`.
598 If you want the code extracted to any other location, you need to 598 If you want the code extracted to any other location, you need to
599 provide the srctree positional argument with the command as follows: 599 provide the srctree positional argument with the command as follows:
600 $ devtool upgrade -V version recipe srctree 600 $ devtool upgrade -V version recipe srctree
@@ -773,7 +773,7 @@ Dependency Detection and Mapping
773The ``devtool add`` command attempts to detect build-time dependencies 773The ``devtool add`` command attempts to detect build-time dependencies
774and map them to other recipes in the system. During this mapping, the 774and map them to other recipes in the system. During this mapping, the
775command fills in the names of those recipes as part of the 775command fills in the names of those recipes as part of the
776```DEPENDS`` <&YOCTO_DOCS_REF_URL;#var-DEPENDS>`__ variable within the 776:term:`DEPENDS` variable within the
777recipe. If a dependency cannot be mapped, ``devtool`` places a comment 777recipe. If a dependency cannot be mapped, ``devtool`` places a comment
778in the recipe indicating such. The inability to map a dependency can 778in the recipe indicating such. The inability to map a dependency can
779result from naming not being recognized or because the dependency simply 779result from naming not being recognized or because the dependency simply
@@ -807,13 +807,13 @@ License Detection
807The ``devtool add`` command attempts to determine if the software you 807The ``devtool add`` command attempts to determine if the software you
808are adding is able to be distributed under a common, open-source 808are adding is able to be distributed under a common, open-source
809license. If so, the command sets the 809license. If so, the command sets the
810```LICENSE`` <&YOCTO_DOCS_REF_URL;#var-LICENSE>`__ value accordingly. 810:term:`LICENSE` value accordingly.
811You should double-check the value added by the command against the 811You should double-check the value added by the command against the
812documentation or source files for the software you are building and, if 812documentation or source files for the software you are building and, if
813necessary, update that ``LICENSE`` value. 813necessary, update that ``LICENSE`` value.
814 814
815The ``devtool add`` command also sets the 815The ``devtool add`` command also sets the
816```LIC_FILES_CHKSUM`` <&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM>`__ 816:term:`LIC_FILES_CHKSUM`
817value to point to all files that appear to be license-related. Realize 817value to point to all files that appear to be license-related. Realize
818that license statements often appear in comments at the top of source 818that license statements often appear in comments at the top of source
819files or within the documentation. In such cases, the command does not 819files or within the documentation. In such cases, the command does not
@@ -842,7 +842,7 @@ open-source software. Unfortunately, Makefiles are often not written
842with cross-compilation in mind. Thus, ``devtool add`` often cannot do 842with cross-compilation in mind. Thus, ``devtool add`` often cannot do
843very much to ensure that these Makefiles build correctly. It is very 843very much to ensure that these Makefiles build correctly. It is very
844common, for example, to explicitly call ``gcc`` instead of using the 844common, for example, to explicitly call ``gcc`` instead of using the
845```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__ variable. Usually, in a 845:term:`CC` variable. Usually, in a
846cross-compilation environment, ``gcc`` is the compiler for the build 846cross-compilation environment, ``gcc`` is the compiler for the build
847host and the cross-compiler is named something similar to 847host and the cross-compiler is named something similar to
848``arm-poky-linux-gnueabi-gcc`` and might require arguments (e.g. to 848``arm-poky-linux-gnueabi-gcc`` and might require arguments (e.g. to
@@ -869,8 +869,8 @@ mind:
869 sets the default using the "?=" operator, or you can alternatively 869 sets the default using the "?=" operator, or you can alternatively
870 force the value on the ``make`` command line. To force the value on 870 force the value on the ``make`` command line. To force the value on
871 the command line, add the variable setting to 871 the command line, add the variable setting to
872 ```EXTRA_OEMAKE`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE>`__ or 872 :term:`EXTRA_OEMAKE` or
873 ```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__ 873 :term:`PACKAGECONFIG_CONFARGS`
874 within the recipe. Here is an example using ``EXTRA_OEMAKE``: 874 within the recipe. Here is an example using ``EXTRA_OEMAKE``:
875 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" In the above example, 875 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" In the above example,
876 single quotes are used around the variable settings as the values are 876 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
951https://github.com/diversario/node-ssdp In this example, ``devtool`` 951https://github.com/diversario/node-ssdp In this example, ``devtool``
952fetches the specified Git repository, detects the code as Node.js code, 952fetches the specified Git repository, detects the code as Node.js code,
953fetches dependencies using ``npm``, and sets 953fetches dependencies using ``npm``, and sets
954```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ accordingly. 954:term:`SRC_URI` accordingly.
955 955
956.. _sdk-working-with-recipes: 956.. _sdk-working-with-recipes:
957 957
@@ -976,8 +976,8 @@ build progresses as follows:
976For recipes in the workspace, fetching and unpacking is disabled as the 976For recipes in the workspace, fetching and unpacking is disabled as the
977source tree has already been prepared and is persistent. Each of these 977source tree has already been prepared and is persistent. Each of these
978build steps is defined as a function (task), usually with a "do_" prefix 978build steps is defined as a function (task), usually with a "do_" prefix
979(e.g. ```do_fetch`` <&YOCTO_DOCS_REF_URL;#ref-tasks-fetch>`__, 979(e.g. :ref:`ref-tasks-fetch`,
980```do_unpack`` <&YOCTO_DOCS_REF_URL;#ref-tasks-unpack>`__, and so 980:ref:`ref-tasks-unpack`, and so
981forth). These functions are typically shell scripts but can instead be 981forth). These functions are typically shell scripts but can instead be
982written in Python. 982written in Python.
983 983
@@ -986,7 +986,7 @@ does not include complete instructions for building the software.
986Instead, common functionality is encapsulated in classes inherited with 986Instead, common functionality is encapsulated in classes inherited with
987the ``inherit`` directive. This technique leaves the recipe to describe 987the ``inherit`` directive. This technique leaves the recipe to describe
988just the things that are specific to the software being built. A 988just the things that are specific to the software being built. A
989```base`` <&YOCTO_DOCS_REF_URL;#ref-classes-base>`__ class exists that 989:ref:`base <ref-classes-base>` class exists that
990is implicitly inherited by all recipes and provides the functionality 990is implicitly inherited by all recipes and provides the functionality
991that most recipes typically need. 991that most recipes typically need.
992 992
@@ -1011,9 +1011,9 @@ links created within the source tree:
1011 useful: 1011 useful:
1012 1012
1013 - ``image/``: Contains all of the files installed during the 1013 - ``image/``: Contains all of the files installed during the
1014 ```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ stage. 1014 :ref:`ref-tasks-install` stage.
1015 Within a recipe, this directory is referred to by the expression 1015 Within a recipe, this directory is referred to by the expression
1016 ``${``\ ```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__\ ``}``. 1016 ``${``\ :term:`D`\ ``}``.
1017 1017
1018 - ``sysroot-destdir/``: Contains a subset of files installed within 1018 - ``sysroot-destdir/``: Contains a subset of files installed within
1019 ``do_install`` that have been put into the shared sysroot. For 1019 ``do_install`` that have been put into the shared sysroot. For
@@ -1035,16 +1035,16 @@ Setting Configure Arguments
1035If the software your recipe is building uses GNU autoconf, then a fixed 1035If the software your recipe is building uses GNU autoconf, then a fixed
1036set of arguments is passed to it to enable cross-compilation plus any 1036set of arguments is passed to it to enable cross-compilation plus any
1037extras specified by 1037extras specified by
1038```EXTRA_OECONF`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF>`__ or 1038:term:`EXTRA_OECONF` or
1039```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__ 1039:term:`PACKAGECONFIG_CONFARGS`
1040set within the recipe. If you wish to pass additional options, add them 1040set within the recipe. If you wish to pass additional options, add them
1041to ``EXTRA_OECONF`` or ``PACKAGECONFIG_CONFARGS``. Other supported build 1041to ``EXTRA_OECONF`` or ``PACKAGECONFIG_CONFARGS``. Other supported build
1042tools have similar variables (e.g. 1042tools have similar variables (e.g.
1043```EXTRA_OECMAKE`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE>`__ for 1043:term:`EXTRA_OECMAKE` for
1044CMake, ```EXTRA_OESCONS`` <&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS>`__ 1044CMake, :term:`EXTRA_OESCONS`
1045for Scons, and so forth). If you need to pass anything on the ``make`` 1045for Scons, and so forth). If you need to pass anything on the ``make``
1046command line, you can use ``EXTRA_OEMAKE`` or the 1046command line, you can use ``EXTRA_OEMAKE`` or the
1047```PACKAGECONFIG_CONFARGS`` <&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS>`__ 1047:term:`PACKAGECONFIG_CONFARGS`
1048variables to do so. 1048variables to do so.
1049 1049
1050You can use the ``devtool configure-help`` command to help you set the 1050You can use the ``devtool configure-help`` command to help you set the
@@ -1071,8 +1071,8 @@ the build host.
1071 1071
1072Recipes should never write files directly into the sysroot. Instead, 1072Recipes should never write files directly into the sysroot. Instead,
1073files should be installed into standard locations during the 1073files should be installed into standard locations during the
1074```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task within 1074:ref:`ref-tasks-install` task within
1075the ``${``\ ```D`` <&YOCTO_DOCS_REF_URL;#var-D>`__\ ``}`` directory. A 1075the ``${``\ :term:`D`\ ``}`` directory. A
1076subset of these files automatically goes into the sysroot. The reason 1076subset of these files automatically goes into the sysroot. The reason
1077for this limitation is that almost all files that go into the sysroot 1077for this limitation is that almost all files that go into the sysroot
1078are cataloged in manifests in order to ensure they can be removed later 1078are 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
1090contents of the image are expressed in terms of packages and not 1090contents of the image are expressed in terms of packages and not
1091recipes. 1091recipes.
1092 1092
1093During the ```do_package`` <&YOCTO_DOCS_REF_URL;#ref-tasks-package>`__ 1093During the :ref:`ref-tasks-package`
1094task, files installed during the 1094task, files installed during the
1095```do_install`` <&YOCTO_DOCS_REF_URL;#ref-tasks-install>`__ task are 1095:ref:`ref-tasks-install` task are
1096split into one main package, which is almost always named the same as 1096split into one main package, which is almost always named the same as
1097the recipe, and into several other packages. This separation exists 1097the recipe, and into several other packages. This separation exists
1098because not all of those installed files are useful in every image. For 1098because not all of those installed files are useful in every image. For
@@ -1105,14 +1105,14 @@ package splitting as well.
1105After building a recipe, you can see where files have gone by looking in 1105After building a recipe, you can see where files have gone by looking in
1106the ``oe-workdir/packages-split`` directory, which contains a 1106the ``oe-workdir/packages-split`` directory, which contains a
1107subdirectory for each package. Apart from some advanced cases, the 1107subdirectory for each package. Apart from some advanced cases, the
1108```PACKAGES`` <&YOCTO_DOCS_REF_URL;#var-PACKAGES>`__ and 1108:term:`PACKAGES` and
1109```FILES`` <&YOCTO_DOCS_REF_URL;#var-FILES>`__ variables controls 1109:term:`FILES` variables controls
1110splitting. The ``PACKAGES`` variable lists all of the packages to be 1110splitting. The ``PACKAGES`` variable lists all of the packages to be
1111produced, while the ``FILES`` variable specifies which files to include 1111produced, while the ``FILES`` variable specifies which files to include
1112in each package by using an override to specify the package. For 1112in each package by using an override to specify the package. For
1113example, ``FILES_${PN}`` specifies the files to go into the main package 1113example, ``FILES_${PN}`` specifies the files to go into the main package
1114(i.e. the main package has the same name as the recipe and 1114(i.e. the main package has the same name as the recipe and
1115``${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}`` evaluates to the 1115``${``\ :term:`PN`\ ``}`` evaluates to the
1116recipe name). The order of the ``PACKAGES`` value is significant. For 1116recipe name). The order of the ``PACKAGES`` value is significant. For
1117each installed file, the first package whose ``FILES`` value matches the 1117each installed file, the first package whose ``FILES`` value matches the
1118file is the package into which the file goes. Defaults exist for both 1118file 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.
1190To update your installed SDK, use ``devtool`` as follows: $ devtool 1190To update your installed SDK, use ``devtool`` as follows: $ devtool
1191sdk-update The previous command assumes your SDK provider has set the 1191sdk-update The previous command assumes your SDK provider has set the
1192default update URL for you through the 1192default update URL for you through the
1193```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__ 1193:term:`SDK_UPDATE_URL`
1194variable as described in the "`Providing Updates to the Extensible SDK 1194variable as described in the "`Providing Updates to the Extensible SDK
1195After 1195After
1196Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__" 1196Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__"