documentation/sdk-manual/extensible.rst

1 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
17    For a side-by-side comparison of main features supported for an
19    :ref:`sdk-manual/intro:introduction` section.
24 ":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter
30 The extensible SDK provides a cross-development toolchain and libraries
47 You can download a tarball installer, which includes the pre-built
50 :yocto_dl:`toolchain </releases/yocto/yocto-&DISTRO;/toolchain/>` directory within the Index of
51 Releases. Toolchains are available for several 32-bit and 64-bit
54 ``core-image-sato`` and ``core-image-minimal`` images and contain
60 An extensible SDK has the string "-ext" as part of the name. Following
63    poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh
72                   core-image-sato or core-image-minimal
76                   aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon
82 For example, the following SDK installer is for a 64-bit
83 development host system and a i586-tuned target architecture based off
84 the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot::
86    poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh
92    :ref:`sdk-manual/appendix-obtain:building an sdk installer`
95 The SDK and toolchains are self-contained and by default are installed
103 tarball for a 64-bit x86 development host system and a 64-bit x86 target
116    $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
127 …Checking sstate mirror object availability: 100% |#######################################| Time: 0…
128 …Loading cache: 100% |####################################################################| Time: 0…
133     $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
146 begin with the string "``environment-setup``" and include as part of
150 script is for an IA-based target machine using i586 tuning::
153    $ source environment-setup-core2-64-poky-linux
155    Run devtool --help for further details.
167 The cornerstone of the extensible SDK is a command-line tool called
183 :ref:`overview-manual/development-environment:git` in that it has a number of
184 sub-commands for each function. You can run ``devtool --help`` to see
196 Three ``devtool`` subcommands provide entry-points into
199 -  *devtool add*: Assists in adding new software to be built.
201 -  *devtool modify*: Sets up an environment to enable you to modify
204 -  *devtool upgrade*: Updates an existing recipe so that you can
220 -----------------------------------------
224 :ref:`devtool-the-workspace-layer-structure`
235 .. image:: figures/sdk-devtool-add-flow.png
252    -  *Left*: The left scenario in the figure represents a common
255       to the default workspace - you do not want the files in some
267    -  *Middle*: The middle scenario in the figure also represents a
270       local area - this time outside of the default workspace.
292    -  *Right*: The right scenario in the figure represents a situation
305       not try to relocate the source code into the workspace - only the
311 2. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the
315       $ devtool edit-recipe recipe
332    (e.g. for testing purposes), you can use the ``devtool build-image``
335       $ devtool build-image image
351    ``devtool deploy-target`` command: $ devtool deploy-target recipe
355    hardware by using the ``devtool build-image`` command. However,
389 --------------------------------------------------------------------
403 .. image:: figures/sdk-devtool-modify-flow.png
410    -  The recipe exists locally in a layer external to the ``devtool``
413    -  The source files exist either upstream in an un-extracted state or
421    -  *Left*: The left scenario in the figure represents a common
426       outside the workspace (i.e. ``meta-``\ layername).
448       Additionally, if you have any non-patch local files (i.e. files
451       an ``oe-local-files`` folder under the newly created source tree.
458    -  *Middle*: The middle scenario in the figure represents a situation
481       files. Non-patch files are copied to an ``oe-local-files`` folder
491    -  *Right*: The right scenario in the figure represents a situation
498       work, uses the "-n" option to indicate source does not need to be
502          $ devtool modify -n recipe srctree
504       If an ``oe-local-files`` subdirectory happens to exist and it
505       contains non-patch files, the files are used. However, if the
507       command, any non-patch files that might exist next to the recipe
529    (e.g. for testing purposes), you can use the ``devtool build-image``
530    command: $ devtool build-image image
546    ``devtool deploy-target`` command::
548       $ devtool deploy-target recipe target
553    using the ``devtool build-image`` command to actual hardware.
577    by layer. Any work you did in the ``oe-local-files`` directory is
594 ---------------------------------------------------------------------------------------------------…
597 more up-to-date version found upstream. Throughout the life of software,
600 your recipes you are using for builds are up-to-date with their upstream
605    Several methods exist by which you can upgrade recipes -
609    :ref:`dev-manual/common-tasks:upgrading recipes` section
615 :ref:`devtool-the-workspace-layer-structure`,
617 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers` support.
622 .. image:: figures/sdk-devtool-upgrade-flow.png
629    -  The recipe exists in a local layer external to the ``devtool``
632    -  The source files for the new release exist in the same location
637    A common situation is where third-party software has undergone a
642       $ devtool upgrade -V version recipe
646    :ref:`devtool-the-workspace-layer-structure`.
650       $ devtool upgrade -V version recipe srctree
654       In this example, the "-V" option specifies the new version. If you
655       don't use "-V", the command upgrades the recipe to the latest
659    recipe are in a Git repository, you must provide the "-S" option and
668    Additionally, if you have any non-patch local files (i.e. files
671    ``oe-local-files`` folder under the newly created source tree.
698    (e.g. for testing purposes), you can use the ``devtool build-image``
701       $ devtool build-image image
717    ``devtool deploy-target`` command: $ devtool deploy-target recipe
721    ``devtool build-image`` command to actual hardware. However,
731    Any work you did in the ``oe-local-files`` directory is preserved in
766 -  Autotools (``autoconf`` and ``automake``)
768 -  CMake
770 -  Scons
772 -  ``qmake``
774 -  Plain ``Makefile``
776 -  Out-of-tree kernel module
778 -  Binary package (i.e. "-b" option)
780 -  Node.js module
782 -  Python modules that use ``setuptools`` or ``distutils``
801 ----------------
810 an error. For such cases, you must re-run the command and provide the
817    $ devtool reset -n recipename
823 --------------------------------
825 The ``devtool add`` command attempts to detect build-time dependencies
856 -----------------
859 are adding is able to be distributed under a common, open-source
862 You should double-check the value added by the command against the
868 value to point to all files that appear to be license-related. Realize
874 important for third-party software. The mechanism attempts to ensure
886 Adding Makefile-Only Software
887 -----------------------------
890 open-source software. Unfortunately, Makefiles are often not written
891 with cross-compilation in mind. Thus, ``devtool add`` often cannot do
895 cross-compilation environment, ``gcc`` is the compiler for the build
896 host and the cross-compiler is named something similar to
897 ``arm-poky-linux-gnueabi-gcc`` and might require arguments (e.g. to
900 When writing a recipe for Makefile-only software, keep the following in
903 -  You probably need to patch the Makefile to use variables instead of
906 -  The environment in which Make runs is set up with various standard
911    ``oe-logs/run.do_compile``. Towards the top of this file, there is
915 -  If the Makefile sets a default for a variable using "=", that default
932 -  Hardcoding paths inside Makefiles is often problematic in a
933    cross-compilation environment. This is particularly true because
935    thus will either be read-only or will introduce contamination into
936    the cross-compilation because they are specific to the build host
940 -  Sometimes a Makefile runs target-specific commands such as
945 -------------------
952 -  Specify the name of the recipe such that it ends with "-native".
956 -  Specify the "--also-native" option with the ``devtool add``
958    builds for the target but also creates a variant with a "-native"
967    "--also-native" option, you can add the tool using just one
971 ----------------------
990    -  You must use quotes around the URL. The ``devtool add`` does not
996    -  In order to support adding Node.js modules, a ``nodejs`` recipe
1003    $ devtool add https://github.com/diversario/node-ssdp
1031 (e.g. :ref:`ref-tasks-fetch`,
1032 :ref:`ref-tasks-unpack`, and so
1041 a :ref:`base <ref-classes-base>` class that
1049 ---------------------------
1056 -  ``oe-logs``: This link points to the directory in which log files and
1059 -  ``oe-workdir``: This link points to the temporary work area for the
1060    recipe. The following locations under ``oe-workdir`` are particularly
1063    -  ``image/``: Contains all of the files installed during the
1064       :ref:`ref-tasks-install` stage.
1068    -  ``sysroot-destdir/``: Contains a subset of files installed within
1071       ":ref:`dev-manual/common-tasks:sharing files between recipes`" section.
1073    -  ``packages-split/``: Contains subdirectories for each package
1075       ":ref:`sdk-manual/extensible:packaging`" section.
1081 ---------------------------
1084 set of arguments is passed to it to enable cross-compilation plus any
1098 You can use the ``devtool configure-help`` command to help you set the
1103 the output of the configure script's "--help" option as a
1107 -----------------------------
1120 :ref:`ref-tasks-install` task within
1129 ---------
1137 During the :ref:`ref-tasks-package`
1139 :ref:`ref-tasks-install` task are
1145 files are separated into a ``-doc`` package. Recipes that package
1150 the ``oe-workdir/packages-split`` directory, which contains a
1165 software the recipe is building installs files into non-standard
1171 If you use the ``devtool deploy-target`` command to write a recipe's
1175 ``devtool deploy-target`` command. Because the ``devtool deploy-target``
1177 ``devtool undeploy-target`` command to restore those files and remove
1180    $ devtool undeploy-target lighttpd root@192.168.7.2
1183 multiple applications, you can remove them all using the "-a" option
1186    $ devtool undeploy-target -a root@192.168.7.2
1196    devtool deploy-target
1198    devtool undeploy-target
1199    commands do not currently interact with any package management system
1202    devtool deploy-target
1211 populated on-demand. Sometimes you must explicitly install extra items
1222    $ devtool sdk-install mesa
1224 By default, the ``devtool sdk-install`` command assumes
1225 the item is available in pre-built form from your SDK provider. If the
1227 source, you can add the "-s" option as follows::
1229    $ devtool sdk-install -s mesa
1232 takes significantly longer than installing the pre-built artifact. Also,
1240 occasionally updated (e.g. a third-party SDK), then you will need to
1245    $ devtool sdk-update
1250 ":ref:`sdk-manual/appendix-customizing:Providing Updates to the Extensible SDK After Installation`"
1252 specify it yourself in the command as follows: $ devtool sdk-update
1265 that use your SDK to build their own platform-specific software and
1278 4. Run the ``devtool build-sdk`` command.