From 09209eec235a35b7089db987561c12e9bd023237 Mon Sep 17 00:00:00 2001 From: Andrew Geissler Date: Sun, 13 Dec 2020 08:44:15 -0600 Subject: poky: subtree update:0ac99625bf..796be0593a Alexander Kanavin (31): netbase: upgrade 6.1 -> 6.2 meson: upgrade 0.55.1 -> 0.56.0 vulkan-samples: update to latest revision libcap: update 2.44 -> 2.45 bind: upgrade 9.16.7 -> 9.16.9 quota: upgrade 4.05 -> 4.06 pango: upgrade 1.46.2 -> 1.48.0 elfutils: upgrade 0.181 -> 0.182 ifupdown: upgrade 0.8.35 -> 0.8.36 createrepo-c: upgrade 0.16.1 -> 0.16.2 acpica: upgrade 20200925 -> 20201113 grep: upgrade 3.5 -> 3.6 man-pages: upgrade 5.08 -> 5.09 stress-ng: upgrade 0.11.23 -> 0.11.24 libhandy: upgrade 1.0.1 -> 1.0.2 piglit: upgrade to latest revision xkbcomp: upgrade 1.4.3 -> 1.4.4 lz4: upgrade 1.9.2 -> 1.9.3 bison: upgrade 3.7.3 -> 3.7.4 python3-setuptools-scm: fix upstream version check cantarell-fonts: update 0.0.25 -> 0.201 meta/lib/oe/reproducible.py: gitsm:// works just as fine as git:// for timestamps llvm: fix reproducibility ruby: fix reproducibility webkitgtk: fix reproducibility ffmpeg: fix reproducibility piglit: fix reproducibility serf: do not install the static library llvm: sort the lists in generated source reproducibibly kea: fix reproducibility poky.conf: do not write current date into distro version, use git hash instead Andrej Valek (1): kernel-dummy: fix executing unexpected tasks Anuj Mittal (1): releases.rst: add gatesgarth to current releases Brett Warren (1): libffi: add patch to revert clang VFP workaround Chandana kalluri (1): populate_sdk_ext: use SDK_CUSTOM_TEPLATECONF variable to enable custom templateconf.cfg Changqing Li (1): buildtools-tarball: add wic dependency into extended buildtools Diego Sueiro (2): modutils-initscripts: Fix modules.dep creation when USE_DEPMOD="0" initscripts: Change execution order between checkroot and modutils Dmitry Baryshkov (2): linux-firmware: upgrade 20201022 -> 20201118 linux-firmware: package ath11k firmware Fabio Berton (1): mesa: Update 20.2.1 -> 20.2.4 Gratian Crisan (1): kernel-module-split.bbclass: fix kernel modules getting marked as CONFFILES Jack Mitchell (3): Revert "connman: set service to conflict with systemd-networkd" systemd-conf: add PACKAGECONFIG to enable/disable auto ethernet DHCP systemd-conf: match ethernet interfaces by type rather than globbing Joshua Watt (2): bitbake: hashserv: client: Fix AF_UNIX path length limits bitbake: hashserv: Fix broken AF_UNIX path length limit Kai Kang (2): systemd-systemctl-native: capable to call without argument systemd.bbclass: update command to check systemctl available Kevin Hao (1): tune-octeontx2.inc: Add tune for Marvell OCTEON TX2 core Li Wang (2): qemu: CVE-2020-29129 CVE-2020-29130 qemu: CVE-2020-25624 Luca Boccassi (1): dbus: move messagebus user to dbus-common package Michael Halstead (1): releases: conf: add link to 3.1.4, update to include 3.1.4 Nicolas Dechesne (19): sphinx: add .vscode in .gitignore {dev,kernel,sdk}-manual: replace hardcoded release version with &DISTRO; sphinx: replace bitbake labels with references to corresponding title brief-yoctoprojectqs: replace labels with references to section title dev-manual: replace labels with references to section title ref-manual: replace labels with references to section title sdk-manual: replace labels with references to section title overview-manual: remove unused labels dev-manual: remove unused labels sphinx: rename top level document in each manual sphinx: use absolute paths for :doc: references test-manual: remove 'test-manual' from filenames toaster-manual: remove 'toaster-manual' from filenames dev-manual: remove 'dev-manual' from filenames kernel-dev: remove 'kernel-dev' from filenames profile-manual: remove 'profile-manual' from filenames overview-manual: remove 'overview-manual' from filenames sdk-manual: remove 'sdk' from filenames ref-manual: remove 'ref' from filenames Paul Barker (5): documentation: Simplify yocto_wiki links documentation: Simplify yocto_git links ref-manual: Simplify oe_git links poky.conf: Add opensuseleap-15.2 and fedora-33 to tested distros poky.conf: Drop fedora-30 from tested distros Peter Kjellerstedt (2): pseudo: Simplify pseudo_client_ignore_path_chroot() bitbake.conf: Add all layers (from BBLAYERS) to PSEUDO_IGNORE_PATHS Richard Purdie (8): lz4: Use the new branch naming from upstream Revert "bitbake.conf: Add all layers (from BBLAYERS) to PSEUDO_IGNORE_PATHS" build-appliance-image: Update to master head revision bitbake: Revert "fetch2: use relative symlinks for anything pulled from PREMIRRORS" build-appliance-image: Update to master head revision metadata_scm: Fix signature handling of METADATA_REVISION and METADATA_BRANCH poky: Set SDK_VERSION explicitly build-appliance-image: Update to master head revision Ross Burton (9): oeqa/devtool: use Yocto mirror for pv-1.5.3 tarball image_types: remove obsolete tar comment image_types: sort tarball file listings package_manager/ipk: neaten OPKGLIBDIR logic ldconfig-native: don't write auxiliary cache package_manager/ipk: improve remove_packaging_data oeqa/selftest/containerimage: update for improved cleanup coreutils: add SUSE-specific issues to CVE whitelist bitbake: msg: use safe YAML loader Sinan Kaya (1): poky-tiny: enable section removal Tomasz Dziendzielski (1): pseudo: Update to print PSEUDO_LOGFILE in abort message on path mismatches sangeeta jain (1): meta/lib/oeqa/manual/oe-core.json: Update test_bitbake_devshell zangrc (3): libinput: upgrade 1.16.3 -> 1.16.4 lighttpd: upgrade 1.4.55 -> 1.4.56 sysstat: upgrade 12.4.0 -> 12.4.1 Signed-off-by: Andrew Geissler Change-Id: I65f2f1c9d44433f3e62609240012c42256679b51 --- .../sdk-manual/appendix-customizing-standard.rst | 34 + .../sdk-manual/appendix-customizing.rst | 377 ++++++ poky/documentation/sdk-manual/appendix-obtain.rst | 319 +++++ poky/documentation/sdk-manual/extensible.rst | 1312 ++++++++++++++++++++ poky/documentation/sdk-manual/index.rst | 22 + poky/documentation/sdk-manual/intro.rst | 220 ++++ .../sdk-appendix-customizing-standard.rst | 34 - .../sdk-manual/sdk-appendix-customizing.rst | 377 ------ .../sdk-manual/sdk-appendix-obtain.rst | 319 ----- poky/documentation/sdk-manual/sdk-extensible.rst | 1312 -------------------- poky/documentation/sdk-manual/sdk-intro.rst | 220 ---- poky/documentation/sdk-manual/sdk-manual.rst | 22 - poky/documentation/sdk-manual/sdk-using.rst | 153 --- .../sdk-manual/sdk-working-projects.rst | 423 ------- poky/documentation/sdk-manual/using.rst | 153 +++ poky/documentation/sdk-manual/working-projects.rst | 423 +++++++ 16 files changed, 2860 insertions(+), 2860 deletions(-) create mode 100644 poky/documentation/sdk-manual/appendix-customizing-standard.rst create mode 100644 poky/documentation/sdk-manual/appendix-customizing.rst create mode 100644 poky/documentation/sdk-manual/appendix-obtain.rst create mode 100644 poky/documentation/sdk-manual/extensible.rst create mode 100644 poky/documentation/sdk-manual/index.rst create mode 100644 poky/documentation/sdk-manual/intro.rst delete mode 100644 poky/documentation/sdk-manual/sdk-appendix-customizing-standard.rst delete mode 100644 poky/documentation/sdk-manual/sdk-appendix-customizing.rst delete mode 100644 poky/documentation/sdk-manual/sdk-appendix-obtain.rst delete mode 100644 poky/documentation/sdk-manual/sdk-extensible.rst delete mode 100644 poky/documentation/sdk-manual/sdk-intro.rst delete mode 100644 poky/documentation/sdk-manual/sdk-manual.rst delete mode 100644 poky/documentation/sdk-manual/sdk-using.rst delete mode 100644 poky/documentation/sdk-manual/sdk-working-projects.rst create mode 100644 poky/documentation/sdk-manual/using.rst create mode 100644 poky/documentation/sdk-manual/working-projects.rst (limited to 'poky/documentation/sdk-manual') diff --git a/poky/documentation/sdk-manual/appendix-customizing-standard.rst b/poky/documentation/sdk-manual/appendix-customizing-standard.rst new file mode 100644 index 000000000..90b634529 --- /dev/null +++ b/poky/documentation/sdk-manual/appendix-customizing-standard.rst @@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +**************************** +Customizing the Standard SDK +**************************** + +This appendix presents customizations you can apply to the standard SDK. + +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 +:term:`TOOLCHAIN_HOST_TASK` +and +: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 +host, simply add those packages to the ``TOOLCHAIN_HOST_TASK`` variable. +Similarly, if you want to add packages to the default set that is part +of the toolchain that runs on the target, add the packages to the +``TOOLCHAIN_TARGET_TASK`` variable. + +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 +: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/poky/documentation/sdk-manual/appendix-customizing.rst b/poky/documentation/sdk-manual/appendix-customizing.rst new file mode 100644 index 000000000..97ade0801 --- /dev/null +++ b/poky/documentation/sdk-manual/appendix-customizing.rst @@ -0,0 +1,377 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +****************************** +Customizing the Extensible SDK +****************************** + +This appendix describes customizations you can apply to the extensible +SDK. + +Configuring the Extensible SDK +============================== + +The extensible SDK primarily consists of a pre-configured copy of the +OpenEmbedded build system from which it was produced. Thus, the SDK's +configuration is derived using that build system and the filters shown +in the following list. When these filters are present, the OpenEmbedded +build system applies them against ``local.conf`` and ``auto.conf``: + +- Variables whose values start with "/" are excluded since the + assumption is that those values are paths that are likely to be + specific to the :term:`Build Host`. + +- Variables listed in + :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 + on which the build system is running and could be problematic as part + of the extensible SDK configuration. + + For a list of the variables excluded by default, see the + :term:`SDK_LOCAL_CONF_BLACKLIST` + in the glossary of the Yocto Project Reference Manual. + +- Variables listed in + :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 + :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 + :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, +without any filtering. The ``sdk-extra.conf`` file is particularly +useful if you want to set a variable value just for the SDK and not the +OpenEmbedded build system used to create the SDK. + +Adjusting the Extensible SDK to Suit Your Build Host's Setup +============================================================ + +In most cases, the extensible SDK defaults should work with your :term:`Build +Host`'s setup. +However, some cases exist for which you might consider making +adjustments: + +- If your SDK configuration inherits additional classes using the + :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 + :term:`SDK_INHERIT_BLACKLIST` + variable as described in the fourth bullet of the previous section. + + .. note:: + + The default value of + SDK_INHERIT_BLACKLIST + is set using the "?=" operator. Consequently, you will need to + either define the entire list by using the "=" operator, or you + will need to append a value using either "_append" or the "+=" + operator. You can learn more about these operators in the " + Basic Syntax + " section of the BitBake User Manual. + + . + +- If you have classes or recipes that add additional tasks to the + standard build flow (i.e. the tasks execute as the recipe builds as + opposed to being called explicitly), then you need to do one of the + following: + + - After ensuring the tasks are :ref:`shared + state ` tasks (i.e. the + output of the task is saved to and can be restored from the shared + 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 + :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 + disable the tasks, add the class to the ``SDK_INHERIT_BLACKLIST`` + variable as described in the previous section. + +- Generally, you want to have a shared state mirror set up so users of + the SDK can add additional items to the SDK after installation + without needing to build the items from source. See the "`Providing + Additional Installable Extensible SDK + Content <#sdk-providing-additional-installable-extensible-sdk-content>`__" + section for information. + +- If you want users of the SDK to be able to easily update the SDK, you + need to set the + :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 + :term:`COREBASE` (other than + layers that are enabled through ``bblayers.conf``), then you must + list these files in + :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 + :ref:`structure-core-script`, then you must + set + :term:`OE_INIT_ENV_SCRIPT` + to point to the environment setup script you use. + + .. note:: + + You must also reflect this change in the value used for the + COREBASE_FILES + variable as previously described. + +Changing the Extensible SDK Installer Title +=========================================== + +You can change the displayed title for the SDK installer by setting the +: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 +:term:`DISTRO_NAME` when it is +set. If the ``DISTRO_NAME`` variable is not set, the title is derived +from the :term:`DISTRO` variable. + +The +:ref:`populate_sdk_base ` +class defines the default value of the ``SDK_TITLE`` variable as +follows: +:: + + SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" + +While several ways exist to change this variable, an efficient method is +to set the variable in your distribution's configuration file. Doing so +creates an SDK installer title that applies across your distribution. As +an example, assume you have your own layer for your distribution named +"meta-mydistro" and you are using the same type of file hierarchy as +does the default "poky" distribution. If so, you could update the +``SDK_TITLE`` variable in the +``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following +form: +:: + + SDK_TITLE = "your_title" + +Providing Updates to the Extensible SDK After Installation +========================================================== + +When you make changes to your configuration or to the metadata and if +you want those changes to be reflected in installed SDKs, you need to +perform additional steps. These steps make it possible for anyone using +the installed SDKs to update the installed SDKs by using the +``devtool sdk-update`` command: + +1. Create a directory that can be shared over HTTP or HTTPS. You can do + this by setting up a web server such as an `Apache HTTP + Server `__ or + `Nginx `__ server in the cloud + to host the directory. This directory must contain the published SDK. + +2. Set the + :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`` + command as described in the "`Applying Updates to an Installed + Extensible + SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" + section. + +3. Build the extensible SDK normally (i.e., use the + ``bitbake -c populate_sdk_ext`` imagename command). + +4. Publish the SDK using the following command: + :: + + $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory + + You must + repeat this step each time you rebuild the SDK with changes that you + want to make available through the update mechanism. + +Completing the above steps allows users of the existing installed SDKs +to simply run ``devtool sdk-update`` to retrieve and apply the latest +updates. See the "`Applying Updates to an Installed Extensible +SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" section +for further information. + +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 +:term:`DISTRO` and +:term:`SDKEXTPATH` variables from +within the +:ref:`populate_sdk_base ` +class as follows: +:: + + SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" + +You can +change this default installation directory by specifically setting the +``SDKEXTPATH`` variable. + +While a number of ways exist through which you can set this variable, +the method that makes the most sense is to set the variable in your +distribution's configuration file. Doing so creates an SDK installer +default directory that applies across your distribution. As an example, +assume you have your own layer for your distribution named +"meta-mydistro" and you are using the same type of file hierarchy as +does the default "poky" distribution. If so, you could update the +``SDKEXTPATH`` variable in the +``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following +form: +:: + + SDKEXTPATH = "some_path_for_your_installed_sdk" + +After building your installer, running it prompts the user for +acceptance of the some_path_for_your_installed_sdk directory as the +default location to install the Extensible SDK. + +Providing Additional Installable Extensible SDK Content +======================================================= + +If you want the users of an extensible SDK you build to be able to add +items to the SDK without requiring the users to build the items from +source, you need to do a number of things: + +1. Ensure the additional items you want the user to be able to install + are already built: + + - Build the items explicitly. You could use one or more "meta" + recipes that depend on lists of other recipes. + + - Build the "world" target and set + ``EXCLUDE_FROM_WORLD_pn-``\ recipename for the recipes you do not + want built. See the + :term:`EXCLUDE_FROM_WORLD` + variable for additional information. + +2. Expose the ``sstate-cache`` directory produced by the build. + Typically, you expose this directory by making it available through + an `Apache HTTP + Server `__ or + `Nginx `__ server. + +3. Set the appropriate configuration so that the produced SDK knows how + to find the configuration. The variable you need to set is + :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: + + - If the mirror value you are setting is appropriate to be set for + both the OpenEmbedded build system that is actually building the + SDK and the SDK itself (i.e. the mirror is accessible in both + places or it will fail quickly on the OpenEmbedded build system + side, and its contents will not interfere with the build), then + you can set the variable in your ``local.conf`` or custom distro + configuration file. You can then "whitelist" the variable through + to the SDK by adding the following: + :: + + SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS" + + - Alternatively, if you just want to set the ``SSTATE_MIRRORS`` + variable's value for the SDK alone, create a + ``conf/sdk-extra.conf`` file either in your + :term:`Build Directory` or within any + layer and put your ``SSTATE_MIRRORS`` setting within that file. + + .. note:: + + This second option is the safest option should you have any + doubts as to which method to use when setting + SSTATE_MIRRORS + . + +Minimizing the Size of the Extensible SDK Installer Download +============================================================ + +By default, the extensible SDK bundles the shared state artifacts for +everything needed to reconstruct the image for which the SDK was built. +This bundling can lead to an SDK installer file that is a Gigabyte or +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 +: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 +box. These libraries and tools must be installed either "on the fly" or +through actions you perform using ``devtool`` or explicitly with the +``devtool sdk-install`` command. + +In most cases, when building a minimal SDK you need to also enable +bringing in the information on a wider range of packages produced by the +system. Requiring this wider range of information is particularly true +so that ``devtool add`` is able to effectively map dependencies it +discovers in a source tree to the appropriate recipes. Additionally, the +information enables the ``devtool search`` command to return useful +results. + +To facilitate this wider range of information, you would need to set the +following: +:: + + SDK_INCLUDE_PKGDATA = "1" + +See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information. + +Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world" +target to be built so that information for all of the recipes included +within it are available. Having these recipes available increases build +time significantly and increases the size of the SDK installer by 30-80 +Mbytes depending on how many recipes are included in your configuration. + +You can use ``EXCLUDE_FROM_WORLD_pn-``\ recipename for recipes you want +to exclude. However, it is assumed that you would need to be building +the "world" target if you want to provide additional items to the SDK. +Consequently, building for "world" should not represent undue overhead +in most cases. + +.. note:: + + If you set + SDK_EXT_TYPE + to "minimal", then providing a shared state mirror is mandatory so + that items can be installed as needed. See the " + Providing Additional Installable Extensible SDK Content + " section for more information. + +You can explicitly control whether or not to include the toolchain when +you build an SDK by setting the +: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 +SDK for use with an IDE or some other tool where you do not want to take +extra steps to install a toolchain. diff --git a/poky/documentation/sdk-manual/appendix-obtain.rst b/poky/documentation/sdk-manual/appendix-obtain.rst new file mode 100644 index 000000000..cdfe2cc85 --- /dev/null +++ b/poky/documentation/sdk-manual/appendix-obtain.rst @@ -0,0 +1,319 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +***************** +Obtaining the SDK +***************** + +Locating Pre-Built SDK Installers +================================= + +You can use existing, pre-built toolchains by locating and running an +SDK installer script that ships with the Yocto Project. Using this +method, you select and download an architecture-specific SDK installer +and then run the script to hand-install the toolchain. + +Follow these steps to locate and hand-install the toolchain: + +1. *Go to the Installers Directory:* Go to + :yocto_dl:`/releases/yocto/yocto-&DISTRO;/toolchain/` + +2. *Open the Folder for Your Build Host:* Open the folder that matches + your :term:`Build Host` (i.e. + ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines). + +3. *Locate and Download the SDK Installer:* You need to find and + download the installer appropriate for your build host, target + hardware, and image type. + + The installer files (``*.sh``) follow this naming convention: + :: + + poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh + + Where: + host_system is a string representing your development system: + "i686" or "x86_64" + + type is a string representing the image: + "sato" or "minimal" + + arch is a string representing the target architecture: + "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2", + "mips64", or "ppc7400" + + release is the version of Yocto Project. + + NOTE: + The standard SDK installer does not have the "-ext" string as + part of the filename. + + + The toolchains provided by the Yocto + Project are based off of the ``core-image-sato`` and + ``core-image-minimal`` images and contain libraries appropriate for + developing against those images. + + For example, if your build host is a 64-bit x86 system and you need + an extended SDK for a 64-bit core2 target, go into the ``x86_64`` + folder and download the following installer: + :: + + poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh + +4. *Run the Installer:* Be sure you have execution privileges and run + the installer. Following is an example from the ``Downloads`` + directory: + :: + + $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh + + During execution of the script, you choose the root location for the + toolchain. See the "`Installed Standard SDK Directory + Structure <#sdk-installed-standard-sdk-directory-structure>`__" + section and the "`Installed Extensible SDK Directory + Structure <#sdk-installed-extensible-sdk-directory-structure>`__" + section for more information. + +Building an SDK Installer +========================= + +As an alternative to locating and downloading an SDK installer, you can +build the SDK installer. Follow these steps: + +1. *Set Up the Build Environment:* Be sure you are set up to use BitBake + in a shell. See the ":ref:`dev-manual/start:preparing the build host`" section + in the Yocto Project Development Tasks Manual for information on how + to get a build host ready that is either a native Linux machine or a + machine that uses CROPS. + +2. *Clone the ``poky`` Repository:* You need to have a local copy of the + Yocto Project :term:`Source Directory` + (i.e. a local + ``poky`` repository). See the ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and + possibly the ":ref:`dev-manual/start:checking out by branch in poky`" and + ":ref:`dev-manual/start:checking out by tag in poky`" sections + all in the Yocto Project Development Tasks Manual for information on + how to clone the ``poky`` repository and check out the appropriate + branch for your work. + +3. *Initialize the Build Environment:* While in the root directory of + the Source Directory (i.e. ``poky``), run the + :ref:`structure-core-script` environment + setup script to define the OpenEmbedded build environment on your + build host. + :: + + $ source oe-init-build-env + + Among other things, the script + creates the :term:`Build Directory`, + which is + ``build`` in this case and is located in the Source Directory. After + the script runs, your current working directory is set to the + ``build`` directory. + +4. *Make Sure You Are Building an Installer for the Correct Machine:* + Check to be sure that your + :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 :term:`SDKMACHINE` variable + in the ``local.conf`` file in your Build Directory is correctly set. + + .. note:: + + If you are building an SDK installer for the Extensible SDK, the + SDKMACHINE + value must be set for the architecture of the machine you are + using to build the installer. If + SDKMACHINE + is not set appropriately, the build fails and provides an error + message similar to the following: + :: + + The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is + set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64). + Unable to continue. + + +6. *Build the SDK Installer:* To build the SDK installer for a standard + SDK and populate the SDK image, use the following command form. Be + sure to replace image with an image (e.g. "core-image-sato"): $ + bitbake image -c populate_sdk You can do the same for the extensible + SDK using this command form: + :: + + $ bitbake image -c populate_sdk_ext + + These commands produce an SDK installer that contains the sysroot + that matches your target root filesystem. + + When the ``bitbake`` command completes, the SDK installer will be in + ``tmp/deploy/sdk`` in the Build Directory. + + .. note:: + + - By default, the previous BitBake command does not build static + 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 + :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 + as part of the SDK. Following is an example using ``libc`` + static development libraries: TOOLCHAIN_TARGET_TASK_append = " + libc-staticdev" + +7. *Run the Installer:* You can now run the SDK installer from + ``tmp/deploy/sdk`` in the Build Directory. Following is an example: + :: + + $ cd ~/poky/build/tmp/deploy/sdk + $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh + + During execution of the script, you choose the root location for the + toolchain. See the "`Installed Standard SDK Directory + Structure <#sdk-installed-standard-sdk-directory-structure>`__" + section and the "`Installed Extensible SDK Directory + Structure <#sdk-installed-extensible-sdk-directory-structure>`__" + section for more information. + +Extracting the Root Filesystem +============================== + +After installing the toolchain, for some use cases you might need to +separately extract a root filesystem: + +- You want to boot the image using NFS. + +- You want to use the root filesystem as the target sysroot. + +- You want to develop your target application using the root filesystem + as the target sysroot. + +Follow these steps to extract the root filesystem: + +1. *Locate and Download the Tarball for the Pre-Built Root Filesystem + Image File:* You need to find and download the root filesystem image + file that is appropriate for your target system. These files are kept + in machine-specific folders in the + :yocto_dl:`Index of Releases ` + in the "machines" directory. + + The machine-specific folders of the "machines" directory contain + tarballs (``*.tar.bz2``) for supported machines. These directories + also contain flattened root filesystem image files (``*.ext4``), + which you can use with QEMU directly. + + The pre-built root filesystem image files follow these naming + conventions: + :: + + core-image-profile-arch.tar.bz2 + + Where: + profile is the 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" 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, genericx86-64-lsb, genericx86-lsb and qemu*. + + The root filesystems + provided by the Yocto Project are based off of the + ``core-image-sato`` and ``core-image-minimal`` images. + + For example, if you plan on using a BeagleBone device as your target + hardware and your image is a ``core-image-sato-sdk`` image, you can + download the following file: + :: + + core-image-sato-sdk-beaglebone-yocto.tar.bz2 + +2. *Initialize the Cross-Development Environment:* You must ``source`` + the cross-development environment setup script to establish necessary + environment variables. + + This script is located in the top-level directory in which you + installed the toolchain (e.g. ``poky_sdk``). + + Following is an example based on the toolchain installed in the + ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section: + :: + + $ source ~/poky_sdk/environment-setup-core2-64-poky-linux + +3. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk`` + command and provide the root filesystem image. + + Following is an example command that extracts the root filesystem + from a previously built root filesystem image that was downloaded + from the :yocto_dl:`Index of Releases `. + This command extracts the root filesystem into the ``core2-64-sato`` + directory: + :: + + $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato + + You could now point to the target sysroot at ``beablebone-sato``. + +Installed Standard SDK Directory Structure +========================================== + +The following figure shows the resulting directory structure after you +install the Standard SDK by running the ``*.sh`` SDK installation +script: + +.. image:: figures/sdk-installed-standard-sdk-directory.png + :scale: 80% + :align: center + +The installed SDK consists of an environment setup script for the SDK, a +configuration file for the target, a version file for the target, and +the root filesystem (``sysroots``) needed to develop objects for the +target system. + +Within the figure, italicized text is used to indicate replaceable +portions of the file or directory name. For example, install_dir/version +is the directory where the SDK is installed. By default, this directory +is ``/opt/poky/``. And, version represents the specific snapshot of the +SDK (e.g. &DISTRO;). Furthermore, target represents the target architecture +(e.g. ``i586``) and host represents the development system's +architecture (e.g. ``x86_64``). Thus, the complete names of the two +directories within the ``sysroots`` could be ``i586-poky-linux`` and +``x86_64-pokysdk-linux`` for the target and host, respectively. + +Installed Extensible SDK Directory Structure +============================================ + +The following figure shows the resulting directory structure after you +install the Extensible SDK by running the ``*.sh`` SDK installation +script: + +.. image:: figures/sdk-installed-extensible-sdk-directory.png + :scale: 80% + :align: center + +The installed directory structure for the extensible SDK is quite +different than the installed structure for the standard SDK. The +extensible SDK does not separate host and target parts in the same +manner as does the standard SDK. The extensible SDK uses an embedded +copy of the OpenEmbedded build system, which has its own sysroots. + +Of note in the directory structure are an environment setup script for +the SDK, a configuration file for the target, a version file for the +target, and log files for the OpenEmbedded build system preparation +script run by the installer and BitBake. + +Within the figure, italicized text is used to indicate replaceable +portions of the file or directory name. For example, install_dir is the +directory where the SDK is installed, which is ``poky_sdk`` by default, +and target represents the target architecture (e.g. ``i586``). diff --git a/poky/documentation/sdk-manual/extensible.rst b/poky/documentation/sdk-manual/extensible.rst new file mode 100644 index 000000000..c94213d6c --- /dev/null +++ b/poky/documentation/sdk-manual/extensible.rst @@ -0,0 +1,1312 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +************************ +Using the Extensible SDK +************************ + +This chapter describes the extensible SDK and how to install it. +Information covers the pieces of the SDK, how to install it, and +presents a look at using the ``devtool`` functionality. The extensible +SDK makes it easy to add new applications and libraries to an image, +modify the source for an existing component, test changes on the target +hardware, and ease integration into the rest of the +:term:`OpenEmbedded Build System`. + +.. note:: + + For a side-by-side comparison of main features supported for an + extensible SDK as compared to a standard SDK, see the " + Introduction + " section. + +In addition to the functionality available through ``devtool``, you can +alternatively make use of the toolchain directly, for example from +Makefile and Autotools. See the "`Using the SDK Toolchain +Directly <#sdk-working-projects>`__" chapter for more information. + +Why use the Extensible SDK and What is in It? +============================================= + +The extensible SDK provides a cross-development toolchain and libraries +tailored to the contents of a specific image. You would use the +Extensible SDK if you want a toolchain experience supplemented with the +powerful set of ``devtool`` commands tailored for the Yocto Project +environment. + +The installed extensible SDK consists of several files and directories. +Basically, it contains an SDK environment setup script, some +configuration files, an internal build system, and the ``devtool`` +functionality. + +Installing the Extensible SDK +============================= + +The first thing you need to do is install the SDK on your :term:`Build +Host` by running the ``*.sh`` installation script. + +You can download a tarball installer, which includes the pre-built +toolchain, the ``runqemu`` script, the internal build system, +``devtool``, and support files from the appropriate +:yocto_dl:`toolchain ` directory within the Index of +Releases. Toolchains are available for several 32-bit and 64-bit +architectures with the ``x86_64`` directories, respectively. The +toolchains the Yocto Project provides are based off the +``core-image-sato`` and ``core-image-minimal`` images and contain +libraries appropriate for developing against that image. + +The names of the tarball installer scripts are such that a string +representing the host system appears first in the filename and then is +immediately followed by a string representing the target architecture. +An extensible SDK has the string "-ext" as part of the name. Following +is the general form: +:: + + poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh + + Where: + host_system is a string representing your development system: + + i686 or x86_64. + + image_type is the image for which the SDK was built: + + core-image-sato or core-image-minimal + + arch is a string representing the tuned target architecture: + + aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon + + release_version is a string representing the release number of the Yocto Project: + + &DISTRO;, &DISTRO;+snapshot + +For example, the following SDK installer is for a 64-bit +development host system and a i586-tuned target architecture based off +the SDK for ``core-image-sato`` and using the current DISTRO snapshot: +:: + + poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-DISTRO.sh + +.. note:: + + As an alternative to downloading an SDK, you can build the SDK + installer. For information on building the installer, see the " + Building an SDK Installer + " section. + +The SDK and toolchains are self-contained and by default are installed +into the ``poky_sdk`` folder in your home directory. You can choose to +install the extensible SDK in any location when you run the installer. +However, because files need to be written under that directory during +the normal course of operation, the location you choose for installation +must be writable for whichever users need to use the SDK. + +The following command shows how to run the installer given a toolchain +tarball for a 64-bit x86 development host system and a 64-bit x86 target +architecture. The example assumes the SDK installer is located in +``~/Downloads/`` and has execution rights. + +.. note:: + + If you do not have write permissions for the directory into which you + are installing the SDK, the installer notifies you and exits. For + that case, set up the proper permissions in the directory and run the + installer again. + +:: + + $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh + Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5 + ========================================================================== + Enter target directory for SDK (default: ~/poky_sdk): + You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y + Extracting SDK..............done + Setting it up... + Extracting buildtools... + Preparing build system... + Parsing recipes: 100% |##################################################################| Time: 0:00:52 + Initialising tasks: 100% |###############################################################| Time: 0:00:00 + Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00 + Loading cache: 100% |####################################################################| Time: 0:00:00 + Initialising tasks: 100% |###############################################################| Time: 0:00:00 + done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux + +Running the Extensible SDK Environment Setup Script +=================================================== + +Once you have the SDK installed, you must run the SDK environment setup +script before you can actually use the SDK. This setup script resides in +the directory you chose when you installed the SDK, which is either the +default ``poky_sdk`` directory or the directory you chose during +installation. + +Before running the script, be sure it is the one that matches the +architecture for which you are developing. Environment setup scripts +begin with the string "``environment-setup``" and include as part of +their name the tuned target architecture. As an example, the following +commands set the working directory to where the SDK was installed and +then source the environment setup script. In this example, the setup +script is for an IA-based target machine using i586 tuning: +:: + + $ cd /home/scottrif/poky_sdk + $ source environment-setup-core2-64-poky-linux + 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``, +:term:`CC`, +:term:`LD`, and so forth). If you want to +see all the environment variables the script exports, examine the +installation file itself. + +Using ``devtool`` in Your SDK Workflow +====================================== + +The cornerstone of the extensible SDK is a command-line tool called +``devtool``. This tool provides a number of features that help you +build, test and package software within the extensible SDK, and +optionally integrate it into an image built by the OpenEmbedded build +system. + +.. note:: + + The use of + devtool + is not limited to the extensible SDK. You can use + devtool + to help you easily develop any project whose build output must be + part of an image built using the build system. + +The ``devtool`` command line is organized similarly to +:ref:`overview-manual/development-environment:git` in that it has a number of +sub-commands for each function. You can run ``devtool --help`` to see +all the commands. + +.. note:: + + See the " + devtool +  Quick Reference + " in the Yocto Project Reference Manual for a + devtool + quick reference. + +Three ``devtool`` subcommands exist that provide entry-points into +development: + +- *devtool add*: Assists in adding new software to be built. + +- *devtool modify*: Sets up an environment to enable you to modify + the source of an existing component. + +- *devtool upgrade*: Updates an existing recipe so that you can + build it for an updated set of source files. + +As with the build system, "recipes" represent software packages within +``devtool``. When you use ``devtool add``, a recipe is automatically +created. When you use ``devtool modify``, the specified existing recipe +is used in order to determine where to get the source code and how to +patch it. In both cases, an environment is set up so that when you build +the recipe a source tree that is under your control is used in order to +allow you to make changes to the source as desired. By default, new +recipes and the source go into a "workspace" directory under the SDK. + +The remainder of this section presents the ``devtool add``, +``devtool modify``, and ``devtool upgrade`` workflows. + +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 +: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 +need to be extracted. + +Depending on your particular scenario, the arguments and options you use +with ``devtool add`` form different combinations. The following diagram +shows common development flows you would use with the ``devtool add`` +command: + +.. image:: figures/sdk-devtool-add-flow.png + :align: center + +1. *Generating the New Recipe*: The top part of the flow shows three + scenarios by which you could use ``devtool add`` to generate a recipe + based on existing source code. + + In a shared development environment, it is typical for other + developers to be responsible for various areas of source code. As a + developer, you are probably interested in using that source code as + part of your development within the Yocto Project. All you need is + access to the code, a recipe, and a controlled area in which to do + your work. + + Within the diagram, three possible scenarios feed into the + ``devtool add`` workflow: + + - *Left*: The left scenario in the figure represents a common + situation where the source code does not exist locally and needs + to be extracted. In this situation, the source code is extracted + to the default workspace - you do not want the files in some + specific location outside of the workspace. Thus, everything you + need will be located in the workspace: + :: + + $ devtool add recipe fetchuri + + With this command, ``devtool`` extracts the upstream + source files into a local Git repository within the ``sources`` + folder. The command then creates a recipe named recipe and a + corresponding append file in the workspace. If you do not provide + recipe, the command makes an attempt to determine the recipe name. + + - *Middle*: The middle scenario in the figure also represents a + situation where the source code does not exist locally. In this + case, the code is again upstream and needs to be extracted to some + local area - this time outside of the default workspace. + + .. note:: + + If required, + devtool + always creates a Git repository locally during the extraction. + + Furthermore, the first positional argument srctree in this case + identifies where the ``devtool add`` command will locate the + extracted code outside of the workspace. You need to specify an + empty directory: + :: + + $ devtool add recipe srctree fetchuri + + In summary, + the source code is pulled from fetchuri and extracted into the + location defined by srctree as a local Git repository. + + Within workspace, ``devtool`` creates a recipe named recipe along + with an associated append file. + + - *Right*: The right scenario in the figure represents a situation + where the srctree has been previously prepared outside of the + ``devtool`` workspace. + + The following command provides a new recipe name and identifies + the existing source tree location: + :: + + $ devtool add recipe srctree + + The command examines the source code and creates a recipe named + recipe for the code and places the recipe into the workspace. + + Because the extracted source code already exists, ``devtool`` does + not try to relocate the source code into the workspace - only the + new recipe is placed in the workspace. + + Aside from a recipe folder, the command also creates an associated + append folder and places an initial ``*.bbappend`` file within. + +2. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the + editor as defined by the ``$EDITOR`` environment variable and modify + the file: + :: + + $ devtool edit-recipe recipe + + From within the editor, you + can make modifications to the recipe that take affect when you build + it later. + +3. *Build the Recipe or Rebuild the Image*: The next step you take + depends on what you are going to do with the new code. + + If you need to eventually move the build output to the target + hardware, use the following ``devtool`` command: + :; + + $ devtool build recipe + + On the other hand, if you want an image to contain the recipe's + packages from the workspace for immediate deployment onto a device + (e.g. for testing purposes), you can use the ``devtool build-image`` + command: + :: + + $ devtool build-image image + +4. *Deploy the Build Output*: When you use the ``devtool build`` command + to build out your recipe, you probably want to see if the resulting + build output works as expected on the target hardware. + + .. note:: + + This step assumes you have a previously built image that is + already either running in QEMU or is running on actual hardware. + Also, it is assumed that for deployment of the image to the + target, SSH is installed in the image and, if the image is running + on real hardware, you have network access to and from your + development machine. + + You can deploy your build output to that target hardware by using the + ``devtool deploy-target`` command: $ devtool deploy-target recipe + target The target is a live target machine running as an SSH server. + + You can, of course, also deploy the image you build to actual + hardware by using the ``devtool build-image`` command. However, + ``devtool`` does not provide a specific command that allows you to + deploy the image to actual hardware. + +5. *Finish Your Work With the Recipe*: The ``devtool finish`` command + creates any patches corresponding to commits in the local Git + repository, moves the new recipe to a more permanent layer, and then + resets the recipe so that the recipe is built normally rather than + from the workspace. + :: + + $ devtool finish recipe layer + + .. note:: + + Any changes you want to turn into patches must be committed to the + Git repository in the source tree. + + As mentioned, the ``devtool finish`` command moves the final recipe + to its permanent layer. + + As a final process of the ``devtool finish`` command, the state of + the standard layers and the upstream source is restored so that you + can build the recipe from those areas rather than the workspace. + + .. note:: + + You can use the + devtool reset + command to put things back should you decide you do not want to + proceed with your work. If you do use this command, realize that + the source tree is preserved. + +Use ``devtool modify`` to Modify the Source of an Existing Component +-------------------------------------------------------------------- + +The ``devtool modify`` command prepares the way to work on existing code +that already has a local recipe in place that is used to build the +software. The command is flexible enough to allow you to extract code +from an upstream source, specify the existing recipe, and keep track of +and gather any patch files from other developers that are associated +with the code. + +Depending on your particular scenario, the arguments and options you use +with ``devtool modify`` form different combinations. The following +diagram shows common development flows for the ``devtool modify`` +command: + +.. image:: figures/sdk-devtool-modify-flow.png + :align: center + +1. *Preparing to Modify the Code*: The top part of the flow shows three + scenarios by which you could use ``devtool modify`` to prepare to + work on source files. Each scenario assumes the following: + + - The recipe exists locally in a layer external to the ``devtool`` + workspace. + + - The source files exist either upstream in an un-extracted state or + locally in a previously extracted state. + + The typical situation is where another developer has created a layer + for use with the Yocto Project and their recipe already resides in + that layer. Furthermore, their source code is readily available + either upstream or locally. + + - *Left*: The left scenario in the figure represents a common + situation where the source code does not exist locally and it + needs to be extracted from an upstream source. In this situation, + the source is extracted into the default ``devtool`` workspace + location. The recipe, in this scenario, is in its own layer + outside the workspace (i.e. ``meta-``\ layername). + + 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 + :term:`SRC_URI` statements to + locate the source code and any local patch files from other + developers. + + With this scenario, no srctree argument exists. Consequently, the + default behavior of the ``devtool modify`` command is to extract + the source files pointed to by the ``SRC_URI`` statements into a + local Git structure. Furthermore, the location for the extracted + source is the default area within the ``devtool`` workspace. The + result is that the command sets up both the source code and an + append file within the workspace while the recipe remains in its + original location. + + Additionally, if you have any non-patch local files (i.e. files + referred to with ``file://`` entries in ``SRC_URI`` statement + excluding ``*.patch/`` or ``*.diff``), these files are copied to + an ``oe-local-files`` folder under the newly created source tree. + Copying the files here gives you a convenient area from which you + can modify the files. Any changes or additions you make to those + files are incorporated into the build the next time you build the + software just as are other changes you might have made to the + source. + + - *Middle*: The middle scenario in the figure represents a situation + where the source code also does not exist locally. In this case, + the code is again upstream and needs to be extracted to some local + area as a Git repository. The recipe, in this scenario, is again + local and in its own layer outside the workspace. + + The following command tells ``devtool`` the recipe with which to + work and, in this case, identifies a local area for the extracted + source files that exists outside of the default ``devtool`` + workspace: + :: + + $ devtool modify recipe srctree + + .. note:: + + You cannot provide a URL for + srctree + using the + devtool + command. + + As with all extractions, the command uses the recipe's ``SRC_URI`` + statements to locate the source files and any associated patch + files. Non-patch files are copied to an ``oe-local-files`` folder + under the newly created source tree. + + Once the files are located, the command by default extracts them + into srctree. + + Within workspace, ``devtool`` creates an append file for the + recipe. The recipe remains in its original location but the source + files are extracted to the location you provide with srctree. + + - *Right*: The right scenario in the figure represents a situation + where the source tree (srctree) already exists locally as a + previously extracted Git structure outside of the ``devtool`` + workspace. In this example, the recipe also exists elsewhere + locally in its own layer. + + The following command tells ``devtool`` the recipe with which to + work, uses the "-n" option to indicate source does not need to be + extracted, and uses srctree to point to the previously extracted + source files: + :: + + $ devtool modify -n recipe srctree + + If an ``oe-local-files`` subdirectory happens to exist and it + contains non-patch files, the files are used. However, if the + subdirectory does not exist and you run the ``devtool finish`` + command, any non-patch files that might exist next to the recipe + are removed because it appears to ``devtool`` that you have + deleted those files. + + Once the ``devtool modify`` command finishes, it creates only an + append file for the recipe in the ``devtool`` workspace. The + recipe and the source code remain in their original locations. + +2. *Edit the Source*: Once you have used the ``devtool modify`` command, + you are free to make changes to the source files. You can use any + editor you like to make and save your source code modifications. + +3. *Build the Recipe or Rebuild the Image*: The next step you take + depends on what you are going to do with the new code. + + If you need to eventually move the build output to the target + hardware, use the following ``devtool`` command: + :: + + $ devtool build recipe + + On the other hand, if you want an image to contain the recipe's + packages from the workspace for immediate deployment onto a device + (e.g. for testing purposes), you can use the ``devtool build-image`` + command: $ devtool build-image image + +4. *Deploy the Build Output*: When you use the ``devtool build`` command + to build out your recipe, you probably want to see if the resulting + build output works as expected on target hardware. + + .. note:: + + This step assumes you have a previously built image that is + already either running in QEMU or running on actual hardware. + Also, it is assumed that for deployment of the image to the + target, SSH is installed in the image and if the image is running + on real hardware that you have network access to and from your + development machine. + + You can deploy your build output to that target hardware by using the + ``devtool deploy-target`` command: + :: + + $ devtool deploy-target recipe target + + The target is a live target machine running as an SSH server. + + You can, of course, use other methods to deploy the image you built + using the ``devtool build-image`` command to actual hardware. + ``devtool`` does not provide a specific command to deploy the image + to actual hardware. + +5. *Finish Your Work With the Recipe*: The ``devtool finish`` command + creates any patches corresponding to commits in the local Git + repository, updates the recipe to point to them (or creates a + ``.bbappend`` file to do so, depending on the specified destination + layer), and then resets the recipe so that the recipe is built + normally rather than from the workspace. + :: + + $ devtool finish recipe layer + + .. note:: + + Any changes you want to turn into patches must be staged and + committed within the local Git repository before you use the + devtool finish + command. + + Because there is no need to move the recipe, ``devtool finish`` + either updates the original recipe in the original layer or the + command creates a ``.bbappend`` file in a different layer as provided + by layer. Any work you did in the ``oe-local-files`` directory is + preserved in the original files next to the recipe during the + ``devtool finish`` command. + + As a final process of the ``devtool finish`` command, the state of + the standard layers and the upstream source is restored so that you + can build the recipe from those areas rather than from the workspace. + + .. note:: + + You can use the + devtool reset + command to put things back should you decide you do not want to + proceed with your work. If you do use this command, realize that + the source tree is preserved. + +Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software +------------------------------------------------------------------------------------------------------- + +The ``devtool upgrade`` command upgrades an existing recipe to that of a +more up-to-date version found upstream. Throughout the life of software, +recipes continually undergo version upgrades by their upstream +publishers. You can use the ``devtool upgrade`` workflow to make sure +your recipes you are using for builds are up-to-date with their upstream +counterparts. + +.. note:: + + Several methods exist by which you can upgrade recipes - + devtool upgrade + happens to be one. You can read about all the methods by which you + can upgrade recipes in the " + Upgrading Recipes + " section of the Yocto Project Development Tasks Manual. + +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`` +:ref:`devtool-the-workspace-layer-structure`, +and work with any source file forms that the +:ref:`fetchers ` support. + +The following diagram shows the common development flow used with the +``devtool upgrade`` command: + +.. image:: figures/sdk-devtool-upgrade-flow.png + :align: center + +1. *Initiate the Upgrade*: The top part of the flow shows the typical + scenario by which you use the ``devtool upgrade`` command. The + following conditions exist: + + - The recipe exists in a local layer external to the ``devtool`` + workspace. + + - The source files for the new release exist in the same location + 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). + + A common situation is where third-party software has undergone a + revision so that it has been upgraded. The recipe you have access to + is likely in your own layer. Thus, you need to upgrade the recipe to + 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 + :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 + + .. note:: + + In this example, the "-V" option specifies the new version. If you + don't use "-V", the command upgrades the recipe to the latest + version. + + If the source files pointed to by the ``SRC_URI`` statement in the + recipe are in a Git repository, you must provide the "-S" option and + specify a revision for the software. + + Once ``devtool`` locates the recipe, it uses the ``SRC_URI`` variable + to locate the source code and any local patch files from other + developers. The result is that the command sets up the source code, + the new version of the recipe, and an append file all within the + workspace. + + Additionally, if you have any non-patch local files (i.e. files + referred to with ``file://`` entries in ``SRC_URI`` statement + excluding ``*.patch/`` or ``*.diff``), these files are copied to an + ``oe-local-files`` folder under the newly created source tree. + Copying the files here gives you a convenient area from which you can + modify the files. Any changes or additions you make to those files + are incorporated into the build the next time you build the software + just as are other changes you might have made to the source. + +2. *Resolve any Conflicts created by the Upgrade*: Conflicts could exist + due to the software being upgraded to a new version. Conflicts occur + if your recipe specifies some patch files in ``SRC_URI`` that + conflict with changes made in the new version of the software. For + such cases, you need to resolve the conflicts by editing the source + and following the normal ``git rebase`` conflict resolution process. + + Before moving onto the next step, be sure to resolve any such + conflicts created through use of a newer or different version of the + software. + +3. *Build the Recipe or Rebuild the Image*: The next step you take + depends on what you are going to do with the new code. + + If you need to eventually move the build output to the target + hardware, use the following ``devtool`` command: + :: + + $ devtool build recipe + + On the other hand, if you want an image to contain the recipe's + packages from the workspace for immediate deployment onto a device + (e.g. for testing purposes), you can use the ``devtool build-image`` + command: + :: + + $ devtool build-image image + +4. *Deploy the Build Output*: When you use the ``devtool build`` command + or ``bitbake`` to build your recipe, you probably want to see if the + resulting build output works as expected on target hardware. + + .. note:: + + This step assumes you have a previously built image that is + already either running in QEMU or running on actual hardware. + Also, it is assumed that for deployment of the image to the + target, SSH is installed in the image and if the image is running + on real hardware that you have network access to and from your + development machine. + + You can deploy your build output to that target hardware by using the + ``devtool deploy-target`` command: $ devtool deploy-target recipe + target The target is a live target machine running as an SSH server. + + You can, of course, also deploy the image you build using the + ``devtool build-image`` command to actual hardware. However, + ``devtool`` does not provide a specific command that allows you to do + this. + +5. *Finish Your Work With the Recipe*: The ``devtool finish`` command + creates any patches corresponding to commits in the local Git + repository, moves the new recipe to a more permanent layer, and then + resets the recipe so that the recipe is built normally rather than + from the workspace. + + Any work you did in the ``oe-local-files`` directory is preserved in + the original files next to the recipe during the ``devtool finish`` + command. + + If you specify a destination layer that is the same as the original + source, then the old version of the recipe and associated files are + removed prior to adding the new version. + :: + + $ devtool finish recipe layer + + .. note:: + + Any changes you want to turn into patches must be committed to the + Git repository in the source tree. + + As a final process of the ``devtool finish`` command, the state of + the standard layers and the upstream source is restored so that you + can build the recipe from those areas rather than the workspace. + + .. note:: + + You can use the + devtool reset + command to put things back should you decide you do not want to + proceed with your work. If you do use this command, realize that + the source tree is preserved. + +A Closer Look at ``devtool add`` +================================ + +The ``devtool add`` command automatically creates a recipe based on the +source tree you provide with the command. Currently, the command has +support for the following: + +- Autotools (``autoconf`` and ``automake``) + +- CMake + +- Scons + +- ``qmake`` + +- Plain ``Makefile`` + +- Out-of-tree kernel module + +- Binary package (i.e. "-b" option) + +- Node.js module + +- Python modules that use ``setuptools`` or ``distutils`` + +Apart from binary packages, the determination of how a source tree +should be treated is automatic based on the files present within that +source tree. For example, if a ``CMakeLists.txt`` file is found, then +the source tree is assumed to be using CMake and is treated accordingly. + +.. note:: + + In most cases, you need to edit the automatically generated recipe in + order to make it build properly. Typically, you would go through + several edit and build cycles until the recipe successfully builds. + Once the recipe builds, you could use possible further iterations to + test the recipe on the target device. + +The remainder of this section covers specifics regarding how parts of +the recipe are generated. + +Name and Version +---------------- + +If you do not specify a name and version on the command line, +``devtool add`` uses various metadata within the source tree in an +attempt to determine the name and version of the software being built. +Based on what the tool determines, ``devtool`` sets the name of the +created recipe file accordingly. + +If ``devtool`` cannot determine the name and version, the command prints +an error. For such cases, you must re-run the command and provide the +name and version, just the name, or just the version as part of the +command line. + +Sometimes the name or version determined from the source tree might be +incorrect. For such a case, you must reset the recipe: +:: + + $ devtool reset -n recipename + +After running the ``devtool reset`` command, you need to +run ``devtool add`` again and provide the name or the version. + +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 +: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 +is not available. For cases where the dependency is not available, you +must use the ``devtool add`` command to add an additional recipe that +satisfies the dependency. Once you add that recipe, you need to update +the ``DEPENDS`` variable in the original recipe to include the new +recipe. + +If you need to add runtime dependencies, you can do so by adding the +following to your recipe: +:: + + RDEPENDS_${PN} += "dependency1 dependency2 ..." + +.. note:: + + The + devtool add + command often cannot distinguish between mandatory and optional + dependencies. Consequently, some of the detected dependencies might + in fact be optional. When in doubt, consult the documentation or the + configure script for the software the recipe is building for further + details. In some cases, you might find you can substitute the + dependency with an option that disables the associated functionality + passed to the configure script. + +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 +: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 +: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 +recognize those license statements. Consequently, you might need to +amend the ``LIC_FILES_CHKSUM`` variable to point to one or more of those +comments if present. Setting ``LIC_FILES_CHKSUM`` is particularly +important for third-party software. The mechanism attempts to ensure +correct licensing should you upgrade the recipe to a newer upstream +version in future. Any change in licensing is detected and you receive +an error prompting you to check the license text again. + +If the ``devtool add`` command cannot determine licensing information, +``devtool`` sets the ``LICENSE`` value to "CLOSED" and leaves the +``LIC_FILES_CHKSUM`` value unset. This behavior allows you to continue +with development even though the settings are unlikely to be correct in +all cases. You should check the documentation or source files for the +software you are building to determine the actual license. + +Adding Makefile-Only Software +----------------------------- + +The use of Make by itself is very common in both proprietary and +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 +: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 +point to the associated sysroot for the target machine). + +When writing a recipe for Makefile-only software, keep the following in +mind: + +- You probably need to patch the Makefile to use variables instead of + hardcoding tools within the toolchain such as ``gcc`` and ``g++``. + +- The environment in which Make runs is set up with various standard + variables for compilation (e.g. ``CC``, ``CXX``, and so forth) in a + similar manner to the environment set up by the SDK's environment + setup script. One easy way to see these variables is to run the + ``devtool build`` command on the recipe and then look in + ``oe-logs/run.do_compile``. Towards the top of this file, a list of + environment variables exists that are being set. You can take + advantage of these variables within the Makefile. + +- If the Makefile sets a default for a variable using "=", that default + overrides the value set in the environment, which is usually not + desirable. For this case, you can either patch the Makefile so it + 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 + :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 + likely to contain spaces because required default options are passed + to the compiler. + +- Hardcoding paths inside Makefiles is often problematic in a + cross-compilation environment. This is particularly true because + those hardcoded paths often point to locations on the build host and + thus will either be read-only or will introduce contamination into + the cross-compilation because they are specific to the build host + rather than the target. Patching the Makefile to use prefix variables + or other path variables is usually the way to handle this situation. + +- Sometimes a Makefile runs target-specific commands such as + ``ldconfig``. For such cases, you might be able to apply patches that + remove these commands from the Makefile. + +Adding Native Tools +------------------- + +Often, you need to build additional tools that run on the :term:`Build +Host` as opposed to +the target. You should indicate this requirement by using one of the +following methods when you run ``devtool add``: + +- Specify the name of the recipe such that it ends with "-native". + Specifying the name like this produces a recipe that only builds for + the build host. + +- Specify the "DASHDASHalso-native" option with the ``devtool add`` + command. Specifying this option creates a recipe file that still + builds for the target but also creates a variant with a "-native" + suffix that builds for the build host. + +.. note:: + + If you need to add a tool that is shipped as part of a source tree + that builds code for the target, you can typically accomplish this by + building the native and target parts separately rather than within + the same compilation process. Realize though that with the + "DASHDASHalso-native" option, you can add the tool using just one + recipe file. + +Adding Node.js Modules +---------------------- + +You can use the ``devtool add`` command two different ways to add +Node.js modules: 1) Through ``npm`` and, 2) from a repository or local +source. + +Use the following form to add Node.js modules through ``npm``: +:: + + $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" + +The name and +version parameters are mandatory. Lockdown and shrinkwrap files are +generated and pointed to by the recipe in order to freeze the version +that is fetched for the dependencies according to the first time. This +also saves checksums that are verified on future fetches. Together, +these behaviors ensure the reproducibility and integrity of the build. + +.. note:: + + - You must use quotes around the URL. The ``devtool add`` does not + require the quotes, but the shell considers ";" as a splitter + between multiple commands. Thus, without the quotes, + ``devtool add`` does not receive the other parts, which results in + several "command not found" errors. + + - In order to support adding Node.js modules, a ``nodejs`` recipe + must be part of your SDK. + +As mentioned earlier, you can also add Node.js modules directly from a +repository or local source tree. To add modules this way, use +``devtool add`` in the following form: +:: + + $ devtool add 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 +:term:`SRC_URI` accordingly. + +Working With Recipes +==================== + +When building a recipe using the ``devtool build`` command, the typical +build progresses as follows: + +1. Fetch the source + +2. Unpack the source + +3. Configure the source + +4. Compile the source + +5. Install the build output + +6. Package the installed output + +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. :ref:`ref-tasks-fetch`, +:ref:`ref-tasks-unpack`, and so +forth). These functions are typically shell scripts but can instead be +written in Python. + +If you look at the contents of a recipe, you will see that the recipe +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 +:ref:`base ` class exists that +is implicitly inherited by all recipes and provides the functionality +that most recipes typically need. + +The remainder of this section presents information useful when working +with recipes. + +Finding Logs and Work Files +--------------------------- + +After the first run of the ``devtool build`` command, recipes that were +previously created using the ``devtool add`` command or whose sources +were modified using the ``devtool modify`` command contain symbolic +links created within the source tree: + +- ``oe-logs``: This link points to the directory in which log files and + run scripts for each build step are created. + +- ``oe-workdir``: This link points to the temporary work area for the + recipe. The following locations under ``oe-workdir`` are particularly + useful: + + - ``image/``: Contains all of the files installed during the + :ref:`ref-tasks-install` stage. + Within a recipe, this directory is referred to by the expression + ``${``\ :term:`D`\ ``}``. + + - ``sysroot-destdir/``: Contains a subset of files installed within + ``do_install`` that have been put into the shared sysroot. For + more information, see the "`Sharing Files Between + Recipes <#sdk-sharing-files-between-recipes>`__" section. + + - ``packages-split/``: Contains subdirectories for each package + produced by the recipe. For more information, see the + "`Packaging <#sdk-packaging>`__" section. + +You can use these links to get more information on what is happening at +each build step. + +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 +: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. +: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 +:term:`PACKAGECONFIG_CONFARGS` +variables to do so. + +You can use the ``devtool configure-help`` command to help you set the +arguments listed in the previous paragraph. The command determines the +exact options being passed, and shows them to you along with any custom +arguments specified through ``EXTRA_OECONF`` or +``PACKAGECONFIG_CONFARGS``. If applicable, the command also shows you +the output of the configure script's "DASHDASHhelp" option as a +reference. + +Sharing Files Between Recipes +----------------------------- + +Recipes often need to use files provided by other recipes on the +:term:`Build Host`. For example, +an application linking to a common library needs access to the library +itself and its associated headers. The way this access is accomplished +within the extensible SDK is through the sysroot. One sysroot exists per +"machine" for which the SDK is being built. In practical terms, this +means a sysroot exists for the target machine, and a sysroot exists for +the build host. + +Recipes should never write files directly into the sysroot. Instead, +files should be installed into standard locations during the +: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 +when a recipe is modified or removed. Thus, the sysroot is able to +remain free from stale files. + +Packaging +--------- + +Packaging is not always particularly relevant within the extensible SDK. +However, if you examine how build output gets into the final image on +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 :ref:`ref-tasks-package` +task, files installed during the +: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 +example, you probably do not need any of the documentation installed in +a production image. Consequently, for each recipe the documentation +files are separated into a ``-doc`` package. Recipes that package +software containing optional modules or plugins might undergo additional +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 +: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 +``${``\ :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 +the ``PACKAGES`` and ``FILES`` variables. Consequently, you might find +you do not even need to set these variables in your recipe unless the +software the recipe is building installs files into non-standard +locations. + +Restoring the Target Device to its Original State +================================================= + +If you use the ``devtool deploy-target`` command to write a recipe's +build output to the target, and you are working on an existing component +of the system, then you might find yourself in a situation where you +need to restore the original files that existed prior to running the +``devtool deploy-target`` command. Because the ``devtool deploy-target`` +command backs up any files it overwrites, you can use the +``devtool undeploy-target`` command to restore those files and remove +any other files the recipe deployed. Consider the following example: +:: + + $ devtool undeploy-target lighttpd root@192.168.7.2 + +If you have deployed +multiple applications, you can remove them all using the "-a" option +thus restoring the target device to its original state: +:: + + $ devtool undeploy-target -a root@192.168.7.2 + +Information about files deployed to +the target as well as any backed up files are stored on the target +itself. This storage, of course, requires some additional space on the +target machine. + +.. note:: + + The + devtool deploy-target + and + devtool undeploy-target + commands do not currently interact with any package management system + on the target device (e.g. RPM or OPKG). Consequently, you should not + intermingle + devtool deploy-target + and package manager operations on the target device. Doing so could + result in a conflicting set of files. + +Installing Additional Items Into the Extensible SDK +=================================================== + +Out of the box the extensible SDK typically only comes with a small +number of tools and libraries. A minimal SDK starts mostly empty and is +populated on-demand. Sometimes you must explicitly install extra items +into the SDK. If you need these extra items, you can first search for +the items using the ``devtool search`` command. For example, suppose you +need to link to libGL but you are not sure which recipe provides libGL. +You can use the following command to find out: +:: + + $ devtool search libGL mesa + +A free implementation of the OpenGL API Once you know the recipe +(i.e. ``mesa`` in this example), you can install it: +:: + + $ devtool sdk-install mesa + +By default, the ``devtool sdk-install`` command assumes +the item is available in pre-built form from your SDK provider. If the +item is not available and it is acceptable to build the item from +source, you can add the "-s" option as follows: +:: + + $ devtool sdk-install -s mesa + +It is important to remember that building the item from source +takes significantly longer than installing the pre-built artifact. Also, +if no recipe exists for the item you want to add to the SDK, you must +instead add the item using the ``devtool add`` command. + +Applying Updates to an Installed Extensible SDK +=============================================== + +If you are working with an installed extensible SDK that gets +occasionally updated (e.g. a third-party SDK), then you will need to +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 +: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>`__" +section. If the SDK provider has not set that default URL, you need to +specify it yourself in the command as follows: $ devtool sdk-update +path_to_update_directory + +.. note:: + + The URL needs to point specifically to a published SDK and not to an + SDK installer that you would download and install. + +Creating a Derivative SDK With Additional Components +==================================================== + +You might need to produce an SDK that contains your own custom +libraries. A good example would be if you were a vendor with customers +that use your SDK to build their own platform-specific software and +those customers need an SDK that has custom libraries. In such a case, +you can produce a derivative SDK based on the currently installed SDK +fairly easily by following these steps: + +1. If necessary, install an extensible SDK that you want to use as a + base for your derivative SDK. + +2. Source the environment script for the SDK. + +3. Add the extra libraries or other components you want by using the + ``devtool add`` command. + +4. Run the ``devtool build-sdk`` command. + +The previous steps take the recipes added to the workspace and construct +a new SDK installer that contains those recipes and the resulting binary +artifacts. The recipes go into their own separate layer in the +constructed derivative SDK, which leaves the workspace clean and ready +for users to add their own recipes. diff --git a/poky/documentation/sdk-manual/index.rst b/poky/documentation/sdk-manual/index.rst new file mode 100644 index 000000000..fce2b199c --- /dev/null +++ b/poky/documentation/sdk-manual/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +======================================================================================== +Yocto Project Application Development and the Extensible Software Development Kit (eSDK) +======================================================================================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + intro + extensible + using + working-projects + appendix-obtain + appendix-customizing + appendix-customizing-standard + history + +.. include:: /boilerplate.rst diff --git a/poky/documentation/sdk-manual/intro.rst b/poky/documentation/sdk-manual/intro.rst new file mode 100644 index 000000000..66b12cdff --- /dev/null +++ b/poky/documentation/sdk-manual/intro.rst @@ -0,0 +1,220 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +************ +Introduction +************ + +eSDK Introduction +================= + +Welcome to the Yocto Project Application Development and the Extensible +Software Development Kit (eSDK) manual. This manual provides information +that explains how to use both the Yocto Project extensible and standard +SDKs to develop applications and images. + +.. note:: + + Prior to the 2.0 Release of the Yocto Project, application + development was primarily accomplished through the use of the + Application Development Toolkit (ADT) and the availability of + stand-alone cross-development toolchains and other tools. With the + 2.1 Release of the Yocto Project, application development has + transitioned to within a tool-rich extensible SDK and the more + traditional standard SDK. + +All SDKs consist of the following: + +- *Cross-Development Toolchain*: This toolchain contains a compiler, + debugger, and various miscellaneous tools. + +- *Libraries, Headers, and Symbols*: The libraries, headers, and + symbols are specific to the image (i.e. they match the image). + +- *Environment Setup Script*: This ``*.sh`` file, once run, sets up the + cross-development environment by defining variables and preparing for + SDK use. + +Additionally, an extensible SDK has tools that allow you to easily add +new applications and libraries to an image, modify the source of an +existing component, test changes on the target hardware, and easily +integrate an application into the :term:`OpenEmbedded Build System`. + +You can use an SDK to independently develop and test code that is +destined to run on some target machine. SDKs are completely +self-contained. The binaries are linked against their own copy of +``libc``, which results in no dependencies on the target system. To +achieve this, the pointer to the dynamic loader is configured at install +time since that path cannot be dynamically altered. This is the reason +for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext`` +archives. + +Another feature for the SDKs is that only one set of cross-compiler +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 +: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. + +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 :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. + +- The Quick EMUlator (QEMU), which lets you simulate target hardware. + QEMU is not literally part of the SDK. You must build and include + this emulator separately. However, QEMU plays an important role in + the development process that revolves around use of the SDK. + +In summary, the extensible and standard SDK share many features. +However, the extensible SDK has powerful development tools to help you +more quickly develop applications. Following is a table that summarizes +the primary differences between the standard and extensible SDK types +when considering which to build: + ++-----------------------+-----------------------+-----------------------+ +| *Feature* | *Standard SDK* | *Extensible SDK* | ++=======================+=======================+=======================+ +| Toolchain | Yes | Yes [1]_ | ++-----------------------+-----------------------+-----------------------+ +| Debugger | Yes | Yes [1]_ | ++-----------------------+-----------------------+-----------------------+ +| Size | 100+ MBytes | 1+ GBytes (or 300+ | +| | | MBytes for minimal | +| | | w/toolchain) | ++-----------------------+-----------------------+-----------------------+ +| ``devtool`` | No | Yes | ++-----------------------+-----------------------+-----------------------+ +| Build Images | No | Yes | ++-----------------------+-----------------------+-----------------------+ +| Updateable | No | Yes | ++-----------------------+-----------------------+-----------------------+ +| Managed Sysroot [2]_ | No | Yes | ++-----------------------+-----------------------+-----------------------+ +| Installed Packages | No [3]_ | Yes [4]_ | ++-----------------------+-----------------------+-----------------------+ +| Construction | Packages | Shared State | ++-----------------------+-----------------------+-----------------------+ + +.. [1] Extensible SDK contains the toolchain and debugger if :term:`SDK_EXT_TYPE` + is "full" or :term:`SDK_INCLUDE_TOOLCHAIN` is "1", which is the default. +.. [2] 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. +.. [3] You can add runtime package management to the standard SDK but it is not + supported by default. +.. [4] You must build and make the shared state available to extensible SDK + users for "packages" you want to enable users to install. + +The Cross-Development Toolchain +------------------------------- + +The :term:`Cross-Development Toolchain` consists +of a cross-compiler, cross-linker, and cross-debugger that are used to +develop user-space applications for targeted hardware. Additionally, for +an extensible SDK, the toolchain also has built-in ``devtool`` +functionality. This toolchain is created by running a SDK installer +script or through a :term:`Build Directory` that is based on +your metadata configuration or extension for your targeted device. The +cross-toolchain works with a matching target sysroot. + +Sysroots +-------- + +The native and target sysroots contain needed headers and libraries for +generating binaries that run on the target architecture. The target +sysroot is based on the target root filesystem image that is built by +the OpenEmbedded build system and uses the same metadata configuration +used to build the cross-toolchain. + +The QEMU Emulator +----------------- + +The QEMU emulator allows you to simulate your hardware while running +your application or image. QEMU is not part of the SDK but is made +available a number of different ways: + +- If you have cloned the ``poky`` Git repository to create a + :term:`Source Directory` and you have + sourced the environment setup script, QEMU is installed and + automatically available. + +- If you have downloaded a Yocto Project release and unpacked it to + create a Source Directory and you have sourced the environment setup + script, QEMU is installed and automatically available. + +- If you have installed the cross-toolchain tarball and you have + sourced the toolchain's setup environment script, QEMU is also + installed and automatically available. + +SDK Development Model +===================== + +Fundamentally, the SDK fits into the development process as follows: + +.. image:: figures/sdk-environment.png + :align: center + +The SDK is installed on any machine and can be used to develop applications, +images, and kernels. An SDK can even be used by a QA Engineer or Release +Engineer. The fundamental concept is that the machine that has the SDK +installed does not have to be associated with the machine that has the +Yocto Project installed. A developer can independently compile and test +an object on their machine and then, when the object is ready for +integration into an image, they can simply make it available to the +machine that has the Yocto Project. Once the object is available, the +image can be rebuilt using the Yocto Project to produce the modified +image. + +You just need to follow these general steps: + +1. *Install the SDK for your target hardware:* For information on how to + install the SDK, see the "`Installing the + SDK <#sdk-installing-the-sdk>`__" section. + +2. *Download or Build the Target Image:* The Yocto Project supports + several target architectures and has many pre-built kernel images and + root filesystem images. + + If you are going to develop your application on hardware, go to the + :yocto_dl:`machines ` download area and choose a + target machine area from which to download the kernel image and root + filesystem. This download area could have several files in it that + support development using actual hardware. For example, the area + might contain ``.hddimg`` files that combine the kernel image with + the filesystem, boot loaders, and so forth. Be sure to get the files + you need for your particular development process. + + If you are going to develop your application and then run and test it + using the QEMU emulator, go to the + :yocto_dl:`machines/qemu ` download area. From this + area, go down into the directory for your target architecture (e.g. + ``qemux86_64`` for an Intel-based 64-bit architecture). Download the + kernel, root filesystem, and any other files you need for your + process. + + .. note:: + + To use the root filesystem in QEMU, you need to extract it. See + the " + Extracting the Root Filesystem + " section for information on how to extract the root filesystem. + +3. *Develop and Test your Application:* At this point, you have the + tools to develop your application. If you need to separately install + and use the QEMU emulator, you can go to `QEMU Home + Page `__ to download and learn about + the emulator. See the ":doc:`/dev-manual/qemu`" chapter in the + Yocto Project Development Tasks Manual for information on using QEMU + within the Yocto Project. + +The remainder of this manual describes how to use the extensible and +standard SDKs. Information also exists in appendix form that describes +how you can build, install, and modify an SDK. diff --git a/poky/documentation/sdk-manual/sdk-appendix-customizing-standard.rst b/poky/documentation/sdk-manual/sdk-appendix-customizing-standard.rst deleted file mode 100644 index 90b634529..000000000 --- a/poky/documentation/sdk-manual/sdk-appendix-customizing-standard.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -**************************** -Customizing the Standard SDK -**************************** - -This appendix presents customizations you can apply to the standard SDK. - -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 -:term:`TOOLCHAIN_HOST_TASK` -and -: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 -host, simply add those packages to the ``TOOLCHAIN_HOST_TASK`` variable. -Similarly, if you want to add packages to the default set that is part -of the toolchain that runs on the target, add the packages to the -``TOOLCHAIN_TARGET_TASK`` variable. - -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 -: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/poky/documentation/sdk-manual/sdk-appendix-customizing.rst b/poky/documentation/sdk-manual/sdk-appendix-customizing.rst deleted file mode 100644 index 5a33f6385..000000000 --- a/poky/documentation/sdk-manual/sdk-appendix-customizing.rst +++ /dev/null @@ -1,377 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -****************************** -Customizing the Extensible SDK -****************************** - -This appendix describes customizations you can apply to the extensible -SDK. - -Configuring the Extensible SDK -============================== - -The extensible SDK primarily consists of a pre-configured copy of the -OpenEmbedded build system from which it was produced. Thus, the SDK's -configuration is derived using that build system and the filters shown -in the following list. When these filters are present, the OpenEmbedded -build system applies them against ``local.conf`` and ``auto.conf``: - -- Variables whose values start with "/" are excluded since the - assumption is that those values are paths that are likely to be - specific to the :term:`Build Host`. - -- Variables listed in - :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 - on which the build system is running and could be problematic as part - of the extensible SDK configuration. - - For a list of the variables excluded by default, see the - :term:`SDK_LOCAL_CONF_BLACKLIST` - in the glossary of the Yocto Project Reference Manual. - -- Variables listed in - :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 - :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 - :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, -without any filtering. The ``sdk-extra.conf`` file is particularly -useful if you want to set a variable value just for the SDK and not the -OpenEmbedded build system used to create the SDK. - -Adjusting the Extensible SDK to Suit Your Build Host's Setup -============================================================ - -In most cases, the extensible SDK defaults should work with your :term:`Build -Host`'s setup. -However, some cases exist for which you might consider making -adjustments: - -- If your SDK configuration inherits additional classes using the - :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 - :term:`SDK_INHERIT_BLACKLIST` - variable as described in the fourth bullet of the previous section. - - .. note:: - - The default value of - SDK_INHERIT_BLACKLIST - is set using the "?=" operator. Consequently, you will need to - either define the entire list by using the "=" operator, or you - will need to append a value using either "_append" or the "+=" - operator. You can learn more about these operators in the " - Basic Syntax - " section of the BitBake User Manual. - - . - -- If you have classes or recipes that add additional tasks to the - standard build flow (i.e. the tasks execute as the recipe builds as - opposed to being called explicitly), then you need to do one of the - following: - - - After ensuring the tasks are :ref:`shared - state ` tasks (i.e. the - output of the task is saved to and can be restored from the shared - 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 - :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 - disable the tasks, add the class to the ``SDK_INHERIT_BLACKLIST`` - variable as described in the previous section. - -- Generally, you want to have a shared state mirror set up so users of - the SDK can add additional items to the SDK after installation - without needing to build the items from source. See the "`Providing - Additional Installable Extensible SDK - Content <#sdk-providing-additional-installable-extensible-sdk-content>`__" - section for information. - -- If you want users of the SDK to be able to easily update the SDK, you - need to set the - :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 - :term:`COREBASE` (other than - layers that are enabled through ``bblayers.conf``), then you must - list these files in - :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 - :ref:`structure-core-script`, then you must - set - :term:`OE_INIT_ENV_SCRIPT` - to point to the environment setup script you use. - - .. note:: - - You must also reflect this change in the value used for the - COREBASE_FILES - variable as previously described. - -Changing the Extensible SDK Installer Title -=========================================== - -You can change the displayed title for the SDK installer by setting the -: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 -:term:`DISTRO_NAME` when it is -set. If the ``DISTRO_NAME`` variable is not set, the title is derived -from the :term:`DISTRO` variable. - -The -:ref:`populate_sdk_base ` -class defines the default value of the ``SDK_TITLE`` variable as -follows: -:: - - SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" - -While several ways exist to change this variable, an efficient method is -to set the variable in your distribution's configuration file. Doing so -creates an SDK installer title that applies across your distribution. As -an example, assume you have your own layer for your distribution named -"meta-mydistro" and you are using the same type of file hierarchy as -does the default "poky" distribution. If so, you could update the -``SDK_TITLE`` variable in the -``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following -form: -:: - - SDK_TITLE = "your_title" - -Providing Updates to the Extensible SDK After Installation -========================================================== - -When you make changes to your configuration or to the metadata and if -you want those changes to be reflected in installed SDKs, you need to -perform additional steps. These steps make it possible for anyone using -the installed SDKs to update the installed SDKs by using the -``devtool sdk-update`` command: - -1. Create a directory that can be shared over HTTP or HTTPS. You can do - this by setting up a web server such as an `Apache HTTP - Server `__ or - `Nginx `__ server in the cloud - to host the directory. This directory must contain the published SDK. - -2. Set the - :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`` - command as described in the "`Applying Updates to an Installed - Extensible - SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" - section. - -3. Build the extensible SDK normally (i.e., use the - ``bitbake -c populate_sdk_ext`` imagename command). - -4. Publish the SDK using the following command: - :: - - $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory - - You must - repeat this step each time you rebuild the SDK with changes that you - want to make available through the update mechanism. - -Completing the above steps allows users of the existing installed SDKs -to simply run ``devtool sdk-update`` to retrieve and apply the latest -updates. See the "`Applying Updates to an Installed Extensible -SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" section -for further information. - -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 -:term:`DISTRO` and -:term:`SDKEXTPATH` variables from -within the -:ref:`populate_sdk_base ` -class as follows: -:: - - SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" - -You can -change this default installation directory by specifically setting the -``SDKEXTPATH`` variable. - -While a number of ways exist through which you can set this variable, -the method that makes the most sense is to set the variable in your -distribution's configuration file. Doing so creates an SDK installer -default directory that applies across your distribution. As an example, -assume you have your own layer for your distribution named -"meta-mydistro" and you are using the same type of file hierarchy as -does the default "poky" distribution. If so, you could update the -``SDKEXTPATH`` variable in the -``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following -form: -:: - - SDKEXTPATH = "some_path_for_your_installed_sdk" - -After building your installer, running it prompts the user for -acceptance of the some_path_for_your_installed_sdk directory as the -default location to install the Extensible SDK. - -Providing Additional Installable Extensible SDK Content -======================================================= - -If you want the users of an extensible SDK you build to be able to add -items to the SDK without requiring the users to build the items from -source, you need to do a number of things: - -1. Ensure the additional items you want the user to be able to install - are already built: - - - Build the items explicitly. You could use one or more "meta" - recipes that depend on lists of other recipes. - - - Build the "world" target and set - ``EXCLUDE_FROM_WORLD_pn-``\ recipename for the recipes you do not - want built. See the - :term:`EXCLUDE_FROM_WORLD` - variable for additional information. - -2. Expose the ``sstate-cache`` directory produced by the build. - Typically, you expose this directory by making it available through - an `Apache HTTP - Server `__ or - `Nginx `__ server. - -3. Set the appropriate configuration so that the produced SDK knows how - to find the configuration. The variable you need to set is - :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: - - - If the mirror value you are setting is appropriate to be set for - both the OpenEmbedded build system that is actually building the - SDK and the SDK itself (i.e. the mirror is accessible in both - places or it will fail quickly on the OpenEmbedded build system - side, and its contents will not interfere with the build), then - you can set the variable in your ``local.conf`` or custom distro - configuration file. You can then "whitelist" the variable through - to the SDK by adding the following: - :: - - SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS" - - - Alternatively, if you just want to set the ``SSTATE_MIRRORS`` - variable's value for the SDK alone, create a - ``conf/sdk-extra.conf`` file either in your - :term:`Build Directory` or within any - layer and put your ``SSTATE_MIRRORS`` setting within that file. - - .. note:: - - This second option is the safest option should you have any - doubts as to which method to use when setting - SSTATE_MIRRORS - . - -Minimizing the Size of the Extensible SDK Installer Download -============================================================ - -By default, the extensible SDK bundles the shared state artifacts for -everything needed to reconstruct the image for which the SDK was built. -This bundling can lead to an SDK installer file that is a Gigabyte or -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 -: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 -box. These libraries and tools must be installed either "on the fly" or -through actions you perform using ``devtool`` or explicitly with the -``devtool sdk-install`` command. - -In most cases, when building a minimal SDK you need to also enable -bringing in the information on a wider range of packages produced by the -system. Requiring this wider range of information is particularly true -so that ``devtool add`` is able to effectively map dependencies it -discovers in a source tree to the appropriate recipes. Additionally, the -information enables the ``devtool search`` command to return useful -results. - -To facilitate this wider range of information, you would need to set the -following: -:: - - SDK_INCLUDE_PKGDATA = "1" - -See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information. - -Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world" -target to be built so that information for all of the recipes included -within it are available. Having these recipes available increases build -time significantly and increases the size of the SDK installer by 30-80 -Mbytes depending on how many recipes are included in your configuration. - -You can use ``EXCLUDE_FROM_WORLD_pn-``\ recipename for recipes you want -to exclude. However, it is assumed that you would need to be building -the "world" target if you want to provide additional items to the SDK. -Consequently, building for "world" should not represent undue overhead -in most cases. - -.. note:: - - If you set - SDK_EXT_TYPE - to "minimal", then providing a shared state mirror is mandatory so - that items can be installed as needed. See the " - Providing Additional Installable Extensible SDK Content - " section for more information. - -You can explicitly control whether or not to include the toolchain when -you build an SDK by setting the -: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 -SDK for use with an IDE or some other tool where you do not want to take -extra steps to install a toolchain. diff --git a/poky/documentation/sdk-manual/sdk-appendix-obtain.rst b/poky/documentation/sdk-manual/sdk-appendix-obtain.rst deleted file mode 100644 index eef425bdf..000000000 --- a/poky/documentation/sdk-manual/sdk-appendix-obtain.rst +++ /dev/null @@ -1,319 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -***************** -Obtaining the SDK -***************** - -Locating Pre-Built SDK Installers -================================= - -You can use existing, pre-built toolchains by locating and running an -SDK installer script that ships with the Yocto Project. Using this -method, you select and download an architecture-specific SDK installer -and then run the script to hand-install the toolchain. - -Follow these steps to locate and hand-install the toolchain: - -1. *Go to the Installers Directory:* Go to - :yocto_dl:`/releases/yocto/yocto-3.1.2/toolchain/` - -2. *Open the Folder for Your Build Host:* Open the folder that matches - your :term:`Build Host` (i.e. - ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines). - -3. *Locate and Download the SDK Installer:* You need to find and - download the installer appropriate for your build host, target - hardware, and image type. - - The installer files (``*.sh``) follow this naming convention: - :: - - poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh - - Where: - host_system is a string representing your development system: - "i686" or "x86_64" - - type is a string representing the image: - "sato" or "minimal" - - arch is a string representing the target architecture: - "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2", - "mips64", or "ppc7400" - - release is the version of Yocto Project. - - NOTE: - The standard SDK installer does not have the "-ext" string as - part of the filename. - - - The toolchains provided by the Yocto - Project are based off of the ``core-image-sato`` and - ``core-image-minimal`` images and contain libraries appropriate for - developing against those images. - - For example, if your build host is a 64-bit x86 system and you need - an extended SDK for a 64-bit core2 target, go into the ``x86_64`` - folder and download the following installer: - :: - - poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh - -4. *Run the Installer:* Be sure you have execution privileges and run - the installer. Following is an example from the ``Downloads`` - directory: - :: - - $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh - - During execution of the script, you choose the root location for the - toolchain. See the "`Installed Standard SDK Directory - Structure <#sdk-installed-standard-sdk-directory-structure>`__" - section and the "`Installed Extensible SDK Directory - Structure <#sdk-installed-extensible-sdk-directory-structure>`__" - section for more information. - -Building an SDK Installer -========================= - -As an alternative to locating and downloading an SDK installer, you can -build the SDK installer. Follow these steps: - -1. *Set Up the Build Environment:* Be sure you are set up to use BitBake - in a shell. See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" section - in the Yocto Project Development Tasks Manual for information on how - to get a build host ready that is either a native Linux machine or a - machine that uses CROPS. - -2. *Clone the ``poky`` Repository:* You need to have a local copy of the - Yocto Project :term:`Source Directory` - (i.e. a local - ``poky`` repository). See the ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" and - possibly the ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" and - ":ref:`checkout-out-by-tag-in-poky`" sections - all in the Yocto Project Development Tasks Manual for information on - how to clone the ``poky`` repository and check out the appropriate - branch for your work. - -3. *Initialize the Build Environment:* While in the root directory of - the Source Directory (i.e. ``poky``), run the - :ref:`structure-core-script` environment - setup script to define the OpenEmbedded build environment on your - build host. - :: - - $ source oe-init-build-env - - Among other things, the script - creates the :term:`Build Directory`, - which is - ``build`` in this case and is located in the Source Directory. After - the script runs, your current working directory is set to the - ``build`` directory. - -4. *Make Sure You Are Building an Installer for the Correct Machine:* - Check to be sure that your - :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 :term:`SDKMACHINE` variable - in the ``local.conf`` file in your Build Directory is correctly set. - - .. note:: - - If you are building an SDK installer for the Extensible SDK, the - SDKMACHINE - value must be set for the architecture of the machine you are - using to build the installer. If - SDKMACHINE - is not set appropriately, the build fails and provides an error - message similar to the following: - :: - - The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is - set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64). - Unable to continue. - - -6. *Build the SDK Installer:* To build the SDK installer for a standard - SDK and populate the SDK image, use the following command form. Be - sure to replace image with an image (e.g. "core-image-sato"): $ - bitbake image -c populate_sdk You can do the same for the extensible - SDK using this command form: - :: - - $ bitbake image -c populate_sdk_ext - - These commands produce an SDK installer that contains the sysroot - that matches your target root filesystem. - - When the ``bitbake`` command completes, the SDK installer will be in - ``tmp/deploy/sdk`` in the Build Directory. - - .. note:: - - - By default, the previous BitBake command does not build static - 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 - :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 - as part of the SDK. Following is an example using ``libc`` - static development libraries: TOOLCHAIN_TARGET_TASK_append = " - libc-staticdev" - -7. *Run the Installer:* You can now run the SDK installer from - ``tmp/deploy/sdk`` in the Build Directory. Following is an example: - :: - - $ cd ~/poky/build/tmp/deploy/sdk - $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh - - During execution of the script, you choose the root location for the - toolchain. See the "`Installed Standard SDK Directory - Structure <#sdk-installed-standard-sdk-directory-structure>`__" - section and the "`Installed Extensible SDK Directory - Structure <#sdk-installed-extensible-sdk-directory-structure>`__" - section for more information. - -Extracting the Root Filesystem -============================== - -After installing the toolchain, for some use cases you might need to -separately extract a root filesystem: - -- You want to boot the image using NFS. - -- You want to use the root filesystem as the target sysroot. - -- You want to develop your target application using the root filesystem - as the target sysroot. - -Follow these steps to extract the root filesystem: - -1. *Locate and Download the Tarball for the Pre-Built Root Filesystem - Image File:* You need to find and download the root filesystem image - file that is appropriate for your target system. These files are kept - in machine-specific folders in the - :yocto_dl:`Index of Releases ` - in the "machines" directory. - - The machine-specific folders of the "machines" directory contain - tarballs (``*.tar.bz2``) for supported machines. These directories - also contain flattened root filesystem image files (``*.ext4``), - which you can use with QEMU directly. - - The pre-built root filesystem image files follow these naming - conventions: - :: - - core-image-profile-arch.tar.bz2 - - Where: - profile is the 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" 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, genericx86-64-lsb, genericx86-lsb and qemu*. - - The root filesystems - provided by the Yocto Project are based off of the - ``core-image-sato`` and ``core-image-minimal`` images. - - For example, if you plan on using a BeagleBone device as your target - hardware and your image is a ``core-image-sato-sdk`` image, you can - download the following file: - :: - - core-image-sato-sdk-beaglebone-yocto.tar.bz2 - -2. *Initialize the Cross-Development Environment:* You must ``source`` - the cross-development environment setup script to establish necessary - environment variables. - - This script is located in the top-level directory in which you - installed the toolchain (e.g. ``poky_sdk``). - - Following is an example based on the toolchain installed in the - ":ref:`sdk-manual/sdk-appendix-obtain:locating pre-built sdk installers`" section: - :: - - $ source ~/poky_sdk/environment-setup-core2-64-poky-linux - -3. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk`` - command and provide the root filesystem image. - - Following is an example command that extracts the root filesystem - from a previously built root filesystem image that was downloaded - from the :yocto_dl:`Index of Releases `. - This command extracts the root filesystem into the ``core2-64-sato`` - directory: - :: - - $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato - - You could now point to the target sysroot at ``beablebone-sato``. - -Installed Standard SDK Directory Structure -========================================== - -The following figure shows the resulting directory structure after you -install the Standard SDK by running the ``*.sh`` SDK installation -script: - -.. image:: figures/sdk-installed-standard-sdk-directory.png - :scale: 80% - :align: center - -The installed SDK consists of an environment setup script for the SDK, a -configuration file for the target, a version file for the target, and -the root filesystem (``sysroots``) needed to develop objects for the -target system. - -Within the figure, italicized text is used to indicate replaceable -portions of the file or directory name. For example, install_dir/version -is the directory where the SDK is installed. By default, this directory -is ``/opt/poky/``. And, version represents the specific snapshot of the -SDK (e.g. 3.1.2). Furthermore, target represents the target architecture -(e.g. ``i586``) and host represents the development system's -architecture (e.g. ``x86_64``). Thus, the complete names of the two -directories within the ``sysroots`` could be ``i586-poky-linux`` and -``x86_64-pokysdk-linux`` for the target and host, respectively. - -Installed Extensible SDK Directory Structure -============================================ - -The following figure shows the resulting directory structure after you -install the Extensible SDK by running the ``*.sh`` SDK installation -script: - -.. image:: figures/sdk-installed-extensible-sdk-directory.png - :scale: 80% - :align: center - -The installed directory structure for the extensible SDK is quite -different than the installed structure for the standard SDK. The -extensible SDK does not separate host and target parts in the same -manner as does the standard SDK. The extensible SDK uses an embedded -copy of the OpenEmbedded build system, which has its own sysroots. - -Of note in the directory structure are an environment setup script for -the SDK, a configuration file for the target, a version file for the -target, and log files for the OpenEmbedded build system preparation -script run by the installer and BitBake. - -Within the figure, italicized text is used to indicate replaceable -portions of the file or directory name. For example, install_dir is the -directory where the SDK is installed, which is ``poky_sdk`` by default, -and target represents the target architecture (e.g. ``i586``). diff --git a/poky/documentation/sdk-manual/sdk-extensible.rst b/poky/documentation/sdk-manual/sdk-extensible.rst deleted file mode 100644 index 10e4d2061..000000000 --- a/poky/documentation/sdk-manual/sdk-extensible.rst +++ /dev/null @@ -1,1312 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -************************ -Using the Extensible SDK -************************ - -This chapter describes the extensible SDK and how to install it. -Information covers the pieces of the SDK, how to install it, and -presents a look at using the ``devtool`` functionality. The extensible -SDK makes it easy to add new applications and libraries to an image, -modify the source for an existing component, test changes on the target -hardware, and ease integration into the rest of the -:term:`OpenEmbedded Build System`. - -.. note:: - - For a side-by-side comparison of main features supported for an - extensible SDK as compared to a standard SDK, see the " - Introduction - " section. - -In addition to the functionality available through ``devtool``, you can -alternatively make use of the toolchain directly, for example from -Makefile and Autotools. See the "`Using the SDK Toolchain -Directly <#sdk-working-projects>`__" chapter for more information. - -Why use the Extensible SDK and What is in It? -============================================= - -The extensible SDK provides a cross-development toolchain and libraries -tailored to the contents of a specific image. You would use the -Extensible SDK if you want a toolchain experience supplemented with the -powerful set of ``devtool`` commands tailored for the Yocto Project -environment. - -The installed extensible SDK consists of several files and directories. -Basically, it contains an SDK environment setup script, some -configuration files, an internal build system, and the ``devtool`` -functionality. - -Installing the Extensible SDK -============================= - -The first thing you need to do is install the SDK on your :term:`Build -Host` by running the ``*.sh`` installation script. - -You can download a tarball installer, which includes the pre-built -toolchain, the ``runqemu`` script, the internal build system, -``devtool``, and support files from the appropriate -:yocto_dl:`toolchain ` directory within the Index of -Releases. Toolchains are available for several 32-bit and 64-bit -architectures with the ``x86_64`` directories, respectively. The -toolchains the Yocto Project provides are based off the -``core-image-sato`` and ``core-image-minimal`` images and contain -libraries appropriate for developing against that image. - -The names of the tarball installer scripts are such that a string -representing the host system appears first in the filename and then is -immediately followed by a string representing the target architecture. -An extensible SDK has the string "-ext" as part of the name. Following -is the general form: -:: - - poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh - - Where: - host_system is a string representing your development system: - - i686 or x86_64. - - image_type is the image for which the SDK was built: - - core-image-sato or core-image-minimal - - arch is a string representing the tuned target architecture: - - aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon - - release_version is a string representing the release number of the Yocto Project: - - 3.1.2, 3.1.2+snapshot - -For example, the following SDK installer is for a 64-bit -development host system and a i586-tuned target architecture based off -the SDK for ``core-image-sato`` and using the current DISTRO snapshot: -:: - - poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-DISTRO.sh - -.. note:: - - As an alternative to downloading an SDK, you can build the SDK - installer. For information on building the installer, see the " - Building an SDK Installer - " section. - -The SDK and toolchains are self-contained and by default are installed -into the ``poky_sdk`` folder in your home directory. You can choose to -install the extensible SDK in any location when you run the installer. -However, because files need to be written under that directory during -the normal course of operation, the location you choose for installation -must be writable for whichever users need to use the SDK. - -The following command shows how to run the installer given a toolchain -tarball for a 64-bit x86 development host system and a 64-bit x86 target -architecture. The example assumes the SDK installer is located in -``~/Downloads/`` and has execution rights. - -.. note:: - - If you do not have write permissions for the directory into which you - are installing the SDK, the installer notifies you and exits. For - that case, set up the proper permissions in the directory and run the - installer again. - -:: - - $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh - Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5 - ========================================================================== - Enter target directory for SDK (default: ~/poky_sdk): - You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y - Extracting SDK..............done - Setting it up... - Extracting buildtools... - Preparing build system... - Parsing recipes: 100% |##################################################################| Time: 0:00:52 - Initialising tasks: 100% |###############################################################| Time: 0:00:00 - Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00 - Loading cache: 100% |####################################################################| Time: 0:00:00 - Initialising tasks: 100% |###############################################################| Time: 0:00:00 - done - SDK has been successfully set up and is ready to be used. - Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. - $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux - -Running the Extensible SDK Environment Setup Script -=================================================== - -Once you have the SDK installed, you must run the SDK environment setup -script before you can actually use the SDK. This setup script resides in -the directory you chose when you installed the SDK, which is either the -default ``poky_sdk`` directory or the directory you chose during -installation. - -Before running the script, be sure it is the one that matches the -architecture for which you are developing. Environment setup scripts -begin with the string "``environment-setup``" and include as part of -their name the tuned target architecture. As an example, the following -commands set the working directory to where the SDK was installed and -then source the environment setup script. In this example, the setup -script is for an IA-based target machine using i586 tuning: -:: - - $ cd /home/scottrif/poky_sdk - $ source environment-setup-core2-64-poky-linux - 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``, -:term:`CC`, -:term:`LD`, and so forth). If you want to -see all the environment variables the script exports, examine the -installation file itself. - -Using ``devtool`` in Your SDK Workflow -====================================== - -The cornerstone of the extensible SDK is a command-line tool called -``devtool``. This tool provides a number of features that help you -build, test and package software within the extensible SDK, and -optionally integrate it into an image built by the OpenEmbedded build -system. - -.. note:: - - The use of - devtool - is not limited to the extensible SDK. You can use - devtool - to help you easily develop any project whose build output must be - part of an image built using the build system. - -The ``devtool`` command line is organized similarly to -:ref:`overview-manual/overview-manual-development-environment:git` in that it has a number of -sub-commands for each function. You can run ``devtool --help`` to see -all the commands. - -.. note:: - - See the " - devtool -  Quick Reference - " in the Yocto Project Reference Manual for a - devtool - quick reference. - -Three ``devtool`` subcommands exist that provide entry-points into -development: - -- *devtool add*: Assists in adding new software to be built. - -- *devtool modify*: Sets up an environment to enable you to modify - the source of an existing component. - -- *devtool upgrade*: Updates an existing recipe so that you can - build it for an updated set of source files. - -As with the build system, "recipes" represent software packages within -``devtool``. When you use ``devtool add``, a recipe is automatically -created. When you use ``devtool modify``, the specified existing recipe -is used in order to determine where to get the source code and how to -patch it. In both cases, an environment is set up so that when you build -the recipe a source tree that is under your control is used in order to -allow you to make changes to the source as desired. By default, new -recipes and the source go into a "workspace" directory under the SDK. - -The remainder of this section presents the ``devtool add``, -``devtool modify``, and ``devtool upgrade`` workflows. - -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 -: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 -need to be extracted. - -Depending on your particular scenario, the arguments and options you use -with ``devtool add`` form different combinations. The following diagram -shows common development flows you would use with the ``devtool add`` -command: - -.. image:: figures/sdk-devtool-add-flow.png - :align: center - -1. *Generating the New Recipe*: The top part of the flow shows three - scenarios by which you could use ``devtool add`` to generate a recipe - based on existing source code. - - In a shared development environment, it is typical for other - developers to be responsible for various areas of source code. As a - developer, you are probably interested in using that source code as - part of your development within the Yocto Project. All you need is - access to the code, a recipe, and a controlled area in which to do - your work. - - Within the diagram, three possible scenarios feed into the - ``devtool add`` workflow: - - - *Left*: The left scenario in the figure represents a common - situation where the source code does not exist locally and needs - to be extracted. In this situation, the source code is extracted - to the default workspace - you do not want the files in some - specific location outside of the workspace. Thus, everything you - need will be located in the workspace: - :: - - $ devtool add recipe fetchuri - - With this command, ``devtool`` extracts the upstream - source files into a local Git repository within the ``sources`` - folder. The command then creates a recipe named recipe and a - corresponding append file in the workspace. If you do not provide - recipe, the command makes an attempt to determine the recipe name. - - - *Middle*: The middle scenario in the figure also represents a - situation where the source code does not exist locally. In this - case, the code is again upstream and needs to be extracted to some - local area - this time outside of the default workspace. - - .. note:: - - If required, - devtool - always creates a Git repository locally during the extraction. - - Furthermore, the first positional argument srctree in this case - identifies where the ``devtool add`` command will locate the - extracted code outside of the workspace. You need to specify an - empty directory: - :: - - $ devtool add recipe srctree fetchuri - - In summary, - the source code is pulled from fetchuri and extracted into the - location defined by srctree as a local Git repository. - - Within workspace, ``devtool`` creates a recipe named recipe along - with an associated append file. - - - *Right*: The right scenario in the figure represents a situation - where the srctree has been previously prepared outside of the - ``devtool`` workspace. - - The following command provides a new recipe name and identifies - the existing source tree location: - :: - - $ devtool add recipe srctree - - The command examines the source code and creates a recipe named - recipe for the code and places the recipe into the workspace. - - Because the extracted source code already exists, ``devtool`` does - not try to relocate the source code into the workspace - only the - new recipe is placed in the workspace. - - Aside from a recipe folder, the command also creates an associated - append folder and places an initial ``*.bbappend`` file within. - -2. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the - editor as defined by the ``$EDITOR`` environment variable and modify - the file: - :: - - $ devtool edit-recipe recipe - - From within the editor, you - can make modifications to the recipe that take affect when you build - it later. - -3. *Build the Recipe or Rebuild the Image*: The next step you take - depends on what you are going to do with the new code. - - If you need to eventually move the build output to the target - hardware, use the following ``devtool`` command: - :; - - $ devtool build recipe - - On the other hand, if you want an image to contain the recipe's - packages from the workspace for immediate deployment onto a device - (e.g. for testing purposes), you can use the ``devtool build-image`` - command: - :: - - $ devtool build-image image - -4. *Deploy the Build Output*: When you use the ``devtool build`` command - to build out your recipe, you probably want to see if the resulting - build output works as expected on the target hardware. - - .. note:: - - This step assumes you have a previously built image that is - already either running in QEMU or is running on actual hardware. - Also, it is assumed that for deployment of the image to the - target, SSH is installed in the image and, if the image is running - on real hardware, you have network access to and from your - development machine. - - You can deploy your build output to that target hardware by using the - ``devtool deploy-target`` command: $ devtool deploy-target recipe - target The target is a live target machine running as an SSH server. - - You can, of course, also deploy the image you build to actual - hardware by using the ``devtool build-image`` command. However, - ``devtool`` does not provide a specific command that allows you to - deploy the image to actual hardware. - -5. *Finish Your Work With the Recipe*: The ``devtool finish`` command - creates any patches corresponding to commits in the local Git - repository, moves the new recipe to a more permanent layer, and then - resets the recipe so that the recipe is built normally rather than - from the workspace. - :: - - $ devtool finish recipe layer - - .. note:: - - Any changes you want to turn into patches must be committed to the - Git repository in the source tree. - - As mentioned, the ``devtool finish`` command moves the final recipe - to its permanent layer. - - As a final process of the ``devtool finish`` command, the state of - the standard layers and the upstream source is restored so that you - can build the recipe from those areas rather than the workspace. - - .. note:: - - You can use the - devtool reset - command to put things back should you decide you do not want to - proceed with your work. If you do use this command, realize that - the source tree is preserved. - -Use ``devtool modify`` to Modify the Source of an Existing Component --------------------------------------------------------------------- - -The ``devtool modify`` command prepares the way to work on existing code -that already has a local recipe in place that is used to build the -software. The command is flexible enough to allow you to extract code -from an upstream source, specify the existing recipe, and keep track of -and gather any patch files from other developers that are associated -with the code. - -Depending on your particular scenario, the arguments and options you use -with ``devtool modify`` form different combinations. The following -diagram shows common development flows for the ``devtool modify`` -command: - -.. image:: figures/sdk-devtool-modify-flow.png - :align: center - -1. *Preparing to Modify the Code*: The top part of the flow shows three - scenarios by which you could use ``devtool modify`` to prepare to - work on source files. Each scenario assumes the following: - - - The recipe exists locally in a layer external to the ``devtool`` - workspace. - - - The source files exist either upstream in an un-extracted state or - locally in a previously extracted state. - - The typical situation is where another developer has created a layer - for use with the Yocto Project and their recipe already resides in - that layer. Furthermore, their source code is readily available - either upstream or locally. - - - *Left*: The left scenario in the figure represents a common - situation where the source code does not exist locally and it - needs to be extracted from an upstream source. In this situation, - the source is extracted into the default ``devtool`` workspace - location. The recipe, in this scenario, is in its own layer - outside the workspace (i.e. ``meta-``\ layername). - - 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 - :term:`SRC_URI` statements to - locate the source code and any local patch files from other - developers. - - With this scenario, no srctree argument exists. Consequently, the - default behavior of the ``devtool modify`` command is to extract - the source files pointed to by the ``SRC_URI`` statements into a - local Git structure. Furthermore, the location for the extracted - source is the default area within the ``devtool`` workspace. The - result is that the command sets up both the source code and an - append file within the workspace while the recipe remains in its - original location. - - Additionally, if you have any non-patch local files (i.e. files - referred to with ``file://`` entries in ``SRC_URI`` statement - excluding ``*.patch/`` or ``*.diff``), these files are copied to - an ``oe-local-files`` folder under the newly created source tree. - Copying the files here gives you a convenient area from which you - can modify the files. Any changes or additions you make to those - files are incorporated into the build the next time you build the - software just as are other changes you might have made to the - source. - - - *Middle*: The middle scenario in the figure represents a situation - where the source code also does not exist locally. In this case, - the code is again upstream and needs to be extracted to some local - area as a Git repository. The recipe, in this scenario, is again - local and in its own layer outside the workspace. - - The following command tells ``devtool`` the recipe with which to - work and, in this case, identifies a local area for the extracted - source files that exists outside of the default ``devtool`` - workspace: - :: - - $ devtool modify recipe srctree - - .. note:: - - You cannot provide a URL for - srctree - using the - devtool - command. - - As with all extractions, the command uses the recipe's ``SRC_URI`` - statements to locate the source files and any associated patch - files. Non-patch files are copied to an ``oe-local-files`` folder - under the newly created source tree. - - Once the files are located, the command by default extracts them - into srctree. - - Within workspace, ``devtool`` creates an append file for the - recipe. The recipe remains in its original location but the source - files are extracted to the location you provide with srctree. - - - *Right*: The right scenario in the figure represents a situation - where the source tree (srctree) already exists locally as a - previously extracted Git structure outside of the ``devtool`` - workspace. In this example, the recipe also exists elsewhere - locally in its own layer. - - The following command tells ``devtool`` the recipe with which to - work, uses the "-n" option to indicate source does not need to be - extracted, and uses srctree to point to the previously extracted - source files: - :: - - $ devtool modify -n recipe srctree - - If an ``oe-local-files`` subdirectory happens to exist and it - contains non-patch files, the files are used. However, if the - subdirectory does not exist and you run the ``devtool finish`` - command, any non-patch files that might exist next to the recipe - are removed because it appears to ``devtool`` that you have - deleted those files. - - Once the ``devtool modify`` command finishes, it creates only an - append file for the recipe in the ``devtool`` workspace. The - recipe and the source code remain in their original locations. - -2. *Edit the Source*: Once you have used the ``devtool modify`` command, - you are free to make changes to the source files. You can use any - editor you like to make and save your source code modifications. - -3. *Build the Recipe or Rebuild the Image*: The next step you take - depends on what you are going to do with the new code. - - If you need to eventually move the build output to the target - hardware, use the following ``devtool`` command: - :: - - $ devtool build recipe - - On the other hand, if you want an image to contain the recipe's - packages from the workspace for immediate deployment onto a device - (e.g. for testing purposes), you can use the ``devtool build-image`` - command: $ devtool build-image image - -4. *Deploy the Build Output*: When you use the ``devtool build`` command - to build out your recipe, you probably want to see if the resulting - build output works as expected on target hardware. - - .. note:: - - This step assumes you have a previously built image that is - already either running in QEMU or running on actual hardware. - Also, it is assumed that for deployment of the image to the - target, SSH is installed in the image and if the image is running - on real hardware that you have network access to and from your - development machine. - - You can deploy your build output to that target hardware by using the - ``devtool deploy-target`` command: - :: - - $ devtool deploy-target recipe target - - The target is a live target machine running as an SSH server. - - You can, of course, use other methods to deploy the image you built - using the ``devtool build-image`` command to actual hardware. - ``devtool`` does not provide a specific command to deploy the image - to actual hardware. - -5. *Finish Your Work With the Recipe*: The ``devtool finish`` command - creates any patches corresponding to commits in the local Git - repository, updates the recipe to point to them (or creates a - ``.bbappend`` file to do so, depending on the specified destination - layer), and then resets the recipe so that the recipe is built - normally rather than from the workspace. - :: - - $ devtool finish recipe layer - - .. note:: - - Any changes you want to turn into patches must be staged and - committed within the local Git repository before you use the - devtool finish - command. - - Because there is no need to move the recipe, ``devtool finish`` - either updates the original recipe in the original layer or the - command creates a ``.bbappend`` file in a different layer as provided - by layer. Any work you did in the ``oe-local-files`` directory is - preserved in the original files next to the recipe during the - ``devtool finish`` command. - - As a final process of the ``devtool finish`` command, the state of - the standard layers and the upstream source is restored so that you - can build the recipe from those areas rather than from the workspace. - - .. note:: - - You can use the - devtool reset - command to put things back should you decide you do not want to - proceed with your work. If you do use this command, realize that - the source tree is preserved. - -Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software -------------------------------------------------------------------------------------------------------- - -The ``devtool upgrade`` command upgrades an existing recipe to that of a -more up-to-date version found upstream. Throughout the life of software, -recipes continually undergo version upgrades by their upstream -publishers. You can use the ``devtool upgrade`` workflow to make sure -your recipes you are using for builds are up-to-date with their upstream -counterparts. - -.. note:: - - Several methods exist by which you can upgrade recipes - - devtool upgrade - happens to be one. You can read about all the methods by which you - can upgrade recipes in the " - Upgrading Recipes - " section of the Yocto Project Development Tasks Manual. - -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`` -:ref:`devtool-the-workspace-layer-structure`, -and work with any source file forms that the -:ref:`fetchers ` support. - -The following diagram shows the common development flow used with the -``devtool upgrade`` command: - -.. image:: figures/sdk-devtool-upgrade-flow.png - :align: center - -1. *Initiate the Upgrade*: The top part of the flow shows the typical - scenario by which you use the ``devtool upgrade`` command. The - following conditions exist: - - - The recipe exists in a local layer external to the ``devtool`` - workspace. - - - The source files for the new release exist in the same location - 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). - - A common situation is where third-party software has undergone a - revision so that it has been upgraded. The recipe you have access to - is likely in your own layer. Thus, you need to upgrade the recipe to - 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 - :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 - - .. note:: - - In this example, the "-V" option specifies the new version. If you - don't use "-V", the command upgrades the recipe to the latest - version. - - If the source files pointed to by the ``SRC_URI`` statement in the - recipe are in a Git repository, you must provide the "-S" option and - specify a revision for the software. - - Once ``devtool`` locates the recipe, it uses the ``SRC_URI`` variable - to locate the source code and any local patch files from other - developers. The result is that the command sets up the source code, - the new version of the recipe, and an append file all within the - workspace. - - Additionally, if you have any non-patch local files (i.e. files - referred to with ``file://`` entries in ``SRC_URI`` statement - excluding ``*.patch/`` or ``*.diff``), these files are copied to an - ``oe-local-files`` folder under the newly created source tree. - Copying the files here gives you a convenient area from which you can - modify the files. Any changes or additions you make to those files - are incorporated into the build the next time you build the software - just as are other changes you might have made to the source. - -2. *Resolve any Conflicts created by the Upgrade*: Conflicts could exist - due to the software being upgraded to a new version. Conflicts occur - if your recipe specifies some patch files in ``SRC_URI`` that - conflict with changes made in the new version of the software. For - such cases, you need to resolve the conflicts by editing the source - and following the normal ``git rebase`` conflict resolution process. - - Before moving onto the next step, be sure to resolve any such - conflicts created through use of a newer or different version of the - software. - -3. *Build the Recipe or Rebuild the Image*: The next step you take - depends on what you are going to do with the new code. - - If you need to eventually move the build output to the target - hardware, use the following ``devtool`` command: - :: - - $ devtool build recipe - - On the other hand, if you want an image to contain the recipe's - packages from the workspace for immediate deployment onto a device - (e.g. for testing purposes), you can use the ``devtool build-image`` - command: - :: - - $ devtool build-image image - -4. *Deploy the Build Output*: When you use the ``devtool build`` command - or ``bitbake`` to build your recipe, you probably want to see if the - resulting build output works as expected on target hardware. - - .. note:: - - This step assumes you have a previously built image that is - already either running in QEMU or running on actual hardware. - Also, it is assumed that for deployment of the image to the - target, SSH is installed in the image and if the image is running - on real hardware that you have network access to and from your - development machine. - - You can deploy your build output to that target hardware by using the - ``devtool deploy-target`` command: $ devtool deploy-target recipe - target The target is a live target machine running as an SSH server. - - You can, of course, also deploy the image you build using the - ``devtool build-image`` command to actual hardware. However, - ``devtool`` does not provide a specific command that allows you to do - this. - -5. *Finish Your Work With the Recipe*: The ``devtool finish`` command - creates any patches corresponding to commits in the local Git - repository, moves the new recipe to a more permanent layer, and then - resets the recipe so that the recipe is built normally rather than - from the workspace. - - Any work you did in the ``oe-local-files`` directory is preserved in - the original files next to the recipe during the ``devtool finish`` - command. - - If you specify a destination layer that is the same as the original - source, then the old version of the recipe and associated files are - removed prior to adding the new version. - :: - - $ devtool finish recipe layer - - .. note:: - - Any changes you want to turn into patches must be committed to the - Git repository in the source tree. - - As a final process of the ``devtool finish`` command, the state of - the standard layers and the upstream source is restored so that you - can build the recipe from those areas rather than the workspace. - - .. note:: - - You can use the - devtool reset - command to put things back should you decide you do not want to - proceed with your work. If you do use this command, realize that - the source tree is preserved. - -A Closer Look at ``devtool add`` -================================ - -The ``devtool add`` command automatically creates a recipe based on the -source tree you provide with the command. Currently, the command has -support for the following: - -- Autotools (``autoconf`` and ``automake``) - -- CMake - -- Scons - -- ``qmake`` - -- Plain ``Makefile`` - -- Out-of-tree kernel module - -- Binary package (i.e. "-b" option) - -- Node.js module - -- Python modules that use ``setuptools`` or ``distutils`` - -Apart from binary packages, the determination of how a source tree -should be treated is automatic based on the files present within that -source tree. For example, if a ``CMakeLists.txt`` file is found, then -the source tree is assumed to be using CMake and is treated accordingly. - -.. note:: - - In most cases, you need to edit the automatically generated recipe in - order to make it build properly. Typically, you would go through - several edit and build cycles until the recipe successfully builds. - Once the recipe builds, you could use possible further iterations to - test the recipe on the target device. - -The remainder of this section covers specifics regarding how parts of -the recipe are generated. - -Name and Version ----------------- - -If you do not specify a name and version on the command line, -``devtool add`` uses various metadata within the source tree in an -attempt to determine the name and version of the software being built. -Based on what the tool determines, ``devtool`` sets the name of the -created recipe file accordingly. - -If ``devtool`` cannot determine the name and version, the command prints -an error. For such cases, you must re-run the command and provide the -name and version, just the name, or just the version as part of the -command line. - -Sometimes the name or version determined from the source tree might be -incorrect. For such a case, you must reset the recipe: -:: - - $ devtool reset -n recipename - -After running the ``devtool reset`` command, you need to -run ``devtool add`` again and provide the name or the version. - -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 -: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 -is not available. For cases where the dependency is not available, you -must use the ``devtool add`` command to add an additional recipe that -satisfies the dependency. Once you add that recipe, you need to update -the ``DEPENDS`` variable in the original recipe to include the new -recipe. - -If you need to add runtime dependencies, you can do so by adding the -following to your recipe: -:: - - RDEPENDS_${PN} += "dependency1 dependency2 ..." - -.. note:: - - The - devtool add - command often cannot distinguish between mandatory and optional - dependencies. Consequently, some of the detected dependencies might - in fact be optional. When in doubt, consult the documentation or the - configure script for the software the recipe is building for further - details. In some cases, you might find you can substitute the - dependency with an option that disables the associated functionality - passed to the configure script. - -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 -: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 -: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 -recognize those license statements. Consequently, you might need to -amend the ``LIC_FILES_CHKSUM`` variable to point to one or more of those -comments if present. Setting ``LIC_FILES_CHKSUM`` is particularly -important for third-party software. The mechanism attempts to ensure -correct licensing should you upgrade the recipe to a newer upstream -version in future. Any change in licensing is detected and you receive -an error prompting you to check the license text again. - -If the ``devtool add`` command cannot determine licensing information, -``devtool`` sets the ``LICENSE`` value to "CLOSED" and leaves the -``LIC_FILES_CHKSUM`` value unset. This behavior allows you to continue -with development even though the settings are unlikely to be correct in -all cases. You should check the documentation or source files for the -software you are building to determine the actual license. - -Adding Makefile-Only Software ------------------------------ - -The use of Make by itself is very common in both proprietary and -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 -: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 -point to the associated sysroot for the target machine). - -When writing a recipe for Makefile-only software, keep the following in -mind: - -- You probably need to patch the Makefile to use variables instead of - hardcoding tools within the toolchain such as ``gcc`` and ``g++``. - -- The environment in which Make runs is set up with various standard - variables for compilation (e.g. ``CC``, ``CXX``, and so forth) in a - similar manner to the environment set up by the SDK's environment - setup script. One easy way to see these variables is to run the - ``devtool build`` command on the recipe and then look in - ``oe-logs/run.do_compile``. Towards the top of this file, a list of - environment variables exists that are being set. You can take - advantage of these variables within the Makefile. - -- If the Makefile sets a default for a variable using "=", that default - overrides the value set in the environment, which is usually not - desirable. For this case, you can either patch the Makefile so it - 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 - :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 - likely to contain spaces because required default options are passed - to the compiler. - -- Hardcoding paths inside Makefiles is often problematic in a - cross-compilation environment. This is particularly true because - those hardcoded paths often point to locations on the build host and - thus will either be read-only or will introduce contamination into - the cross-compilation because they are specific to the build host - rather than the target. Patching the Makefile to use prefix variables - or other path variables is usually the way to handle this situation. - -- Sometimes a Makefile runs target-specific commands such as - ``ldconfig``. For such cases, you might be able to apply patches that - remove these commands from the Makefile. - -Adding Native Tools -------------------- - -Often, you need to build additional tools that run on the :term:`Build -Host` as opposed to -the target. You should indicate this requirement by using one of the -following methods when you run ``devtool add``: - -- Specify the name of the recipe such that it ends with "-native". - Specifying the name like this produces a recipe that only builds for - the build host. - -- Specify the "DASHDASHalso-native" option with the ``devtool add`` - command. Specifying this option creates a recipe file that still - builds for the target but also creates a variant with a "-native" - suffix that builds for the build host. - -.. note:: - - If you need to add a tool that is shipped as part of a source tree - that builds code for the target, you can typically accomplish this by - building the native and target parts separately rather than within - the same compilation process. Realize though that with the - "DASHDASHalso-native" option, you can add the tool using just one - recipe file. - -Adding Node.js Modules ----------------------- - -You can use the ``devtool add`` command two different ways to add -Node.js modules: 1) Through ``npm`` and, 2) from a repository or local -source. - -Use the following form to add Node.js modules through ``npm``: -:: - - $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" - -The name and -version parameters are mandatory. Lockdown and shrinkwrap files are -generated and pointed to by the recipe in order to freeze the version -that is fetched for the dependencies according to the first time. This -also saves checksums that are verified on future fetches. Together, -these behaviors ensure the reproducibility and integrity of the build. - -.. note:: - - - You must use quotes around the URL. The ``devtool add`` does not - require the quotes, but the shell considers ";" as a splitter - between multiple commands. Thus, without the quotes, - ``devtool add`` does not receive the other parts, which results in - several "command not found" errors. - - - In order to support adding Node.js modules, a ``nodejs`` recipe - must be part of your SDK. - -As mentioned earlier, you can also add Node.js modules directly from a -repository or local source tree. To add modules this way, use -``devtool add`` in the following form: -:: - - $ devtool add 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 -:term:`SRC_URI` accordingly. - -Working With Recipes -==================== - -When building a recipe using the ``devtool build`` command, the typical -build progresses as follows: - -1. Fetch the source - -2. Unpack the source - -3. Configure the source - -4. Compile the source - -5. Install the build output - -6. Package the installed output - -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. :ref:`ref-tasks-fetch`, -:ref:`ref-tasks-unpack`, and so -forth). These functions are typically shell scripts but can instead be -written in Python. - -If you look at the contents of a recipe, you will see that the recipe -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 -:ref:`base ` class exists that -is implicitly inherited by all recipes and provides the functionality -that most recipes typically need. - -The remainder of this section presents information useful when working -with recipes. - -Finding Logs and Work Files ---------------------------- - -After the first run of the ``devtool build`` command, recipes that were -previously created using the ``devtool add`` command or whose sources -were modified using the ``devtool modify`` command contain symbolic -links created within the source tree: - -- ``oe-logs``: This link points to the directory in which log files and - run scripts for each build step are created. - -- ``oe-workdir``: This link points to the temporary work area for the - recipe. The following locations under ``oe-workdir`` are particularly - useful: - - - ``image/``: Contains all of the files installed during the - :ref:`ref-tasks-install` stage. - Within a recipe, this directory is referred to by the expression - ``${``\ :term:`D`\ ``}``. - - - ``sysroot-destdir/``: Contains a subset of files installed within - ``do_install`` that have been put into the shared sysroot. For - more information, see the "`Sharing Files Between - Recipes <#sdk-sharing-files-between-recipes>`__" section. - - - ``packages-split/``: Contains subdirectories for each package - produced by the recipe. For more information, see the - "`Packaging <#sdk-packaging>`__" section. - -You can use these links to get more information on what is happening at -each build step. - -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 -: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. -: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 -:term:`PACKAGECONFIG_CONFARGS` -variables to do so. - -You can use the ``devtool configure-help`` command to help you set the -arguments listed in the previous paragraph. The command determines the -exact options being passed, and shows them to you along with any custom -arguments specified through ``EXTRA_OECONF`` or -``PACKAGECONFIG_CONFARGS``. If applicable, the command also shows you -the output of the configure script's "DASHDASHhelp" option as a -reference. - -Sharing Files Between Recipes ------------------------------ - -Recipes often need to use files provided by other recipes on the -:term:`Build Host`. For example, -an application linking to a common library needs access to the library -itself and its associated headers. The way this access is accomplished -within the extensible SDK is through the sysroot. One sysroot exists per -"machine" for which the SDK is being built. In practical terms, this -means a sysroot exists for the target machine, and a sysroot exists for -the build host. - -Recipes should never write files directly into the sysroot. Instead, -files should be installed into standard locations during the -: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 -when a recipe is modified or removed. Thus, the sysroot is able to -remain free from stale files. - -Packaging ---------- - -Packaging is not always particularly relevant within the extensible SDK. -However, if you examine how build output gets into the final image on -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 :ref:`ref-tasks-package` -task, files installed during the -: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 -example, you probably do not need any of the documentation installed in -a production image. Consequently, for each recipe the documentation -files are separated into a ``-doc`` package. Recipes that package -software containing optional modules or plugins might undergo additional -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 -: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 -``${``\ :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 -the ``PACKAGES`` and ``FILES`` variables. Consequently, you might find -you do not even need to set these variables in your recipe unless the -software the recipe is building installs files into non-standard -locations. - -Restoring the Target Device to its Original State -================================================= - -If you use the ``devtool deploy-target`` command to write a recipe's -build output to the target, and you are working on an existing component -of the system, then you might find yourself in a situation where you -need to restore the original files that existed prior to running the -``devtool deploy-target`` command. Because the ``devtool deploy-target`` -command backs up any files it overwrites, you can use the -``devtool undeploy-target`` command to restore those files and remove -any other files the recipe deployed. Consider the following example: -:: - - $ devtool undeploy-target lighttpd root@192.168.7.2 - -If you have deployed -multiple applications, you can remove them all using the "-a" option -thus restoring the target device to its original state: -:: - - $ devtool undeploy-target -a root@192.168.7.2 - -Information about files deployed to -the target as well as any backed up files are stored on the target -itself. This storage, of course, requires some additional space on the -target machine. - -.. note:: - - The - devtool deploy-target - and - devtool undeploy-target - commands do not currently interact with any package management system - on the target device (e.g. RPM or OPKG). Consequently, you should not - intermingle - devtool deploy-target - and package manager operations on the target device. Doing so could - result in a conflicting set of files. - -Installing Additional Items Into the Extensible SDK -=================================================== - -Out of the box the extensible SDK typically only comes with a small -number of tools and libraries. A minimal SDK starts mostly empty and is -populated on-demand. Sometimes you must explicitly install extra items -into the SDK. If you need these extra items, you can first search for -the items using the ``devtool search`` command. For example, suppose you -need to link to libGL but you are not sure which recipe provides libGL. -You can use the following command to find out: -:: - - $ devtool search libGL mesa - -A free implementation of the OpenGL API Once you know the recipe -(i.e. ``mesa`` in this example), you can install it: -:: - - $ devtool sdk-install mesa - -By default, the ``devtool sdk-install`` command assumes -the item is available in pre-built form from your SDK provider. If the -item is not available and it is acceptable to build the item from -source, you can add the "-s" option as follows: -:: - - $ devtool sdk-install -s mesa - -It is important to remember that building the item from source -takes significantly longer than installing the pre-built artifact. Also, -if no recipe exists for the item you want to add to the SDK, you must -instead add the item using the ``devtool add`` command. - -Applying Updates to an Installed Extensible SDK -=============================================== - -If you are working with an installed extensible SDK that gets -occasionally updated (e.g. a third-party SDK), then you will need to -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 -: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>`__" -section. If the SDK provider has not set that default URL, you need to -specify it yourself in the command as follows: $ devtool sdk-update -path_to_update_directory - -.. note:: - - The URL needs to point specifically to a published SDK and not to an - SDK installer that you would download and install. - -Creating a Derivative SDK With Additional Components -==================================================== - -You might need to produce an SDK that contains your own custom -libraries. A good example would be if you were a vendor with customers -that use your SDK to build their own platform-specific software and -those customers need an SDK that has custom libraries. In such a case, -you can produce a derivative SDK based on the currently installed SDK -fairly easily by following these steps: - -1. If necessary, install an extensible SDK that you want to use as a - base for your derivative SDK. - -2. Source the environment script for the SDK. - -3. Add the extra libraries or other components you want by using the - ``devtool add`` command. - -4. Run the ``devtool build-sdk`` command. - -The previous steps take the recipes added to the workspace and construct -a new SDK installer that contains those recipes and the resulting binary -artifacts. The recipes go into their own separate layer in the -constructed derivative SDK, which leaves the workspace clean and ready -for users to add their own recipes. diff --git a/poky/documentation/sdk-manual/sdk-intro.rst b/poky/documentation/sdk-manual/sdk-intro.rst deleted file mode 100644 index ca6138cce..000000000 --- a/poky/documentation/sdk-manual/sdk-intro.rst +++ /dev/null @@ -1,220 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -************ -Introduction -************ - -eSDK Introduction -================= - -Welcome to the Yocto Project Application Development and the Extensible -Software Development Kit (eSDK) manual. This manual provides information -that explains how to use both the Yocto Project extensible and standard -SDKs to develop applications and images. - -.. note:: - - Prior to the 2.0 Release of the Yocto Project, application - development was primarily accomplished through the use of the - Application Development Toolkit (ADT) and the availability of - stand-alone cross-development toolchains and other tools. With the - 2.1 Release of the Yocto Project, application development has - transitioned to within a tool-rich extensible SDK and the more - traditional standard SDK. - -All SDKs consist of the following: - -- *Cross-Development Toolchain*: This toolchain contains a compiler, - debugger, and various miscellaneous tools. - -- *Libraries, Headers, and Symbols*: The libraries, headers, and - symbols are specific to the image (i.e. they match the image). - -- *Environment Setup Script*: This ``*.sh`` file, once run, sets up the - cross-development environment by defining variables and preparing for - SDK use. - -Additionally, an extensible SDK has tools that allow you to easily add -new applications and libraries to an image, modify the source of an -existing component, test changes on the target hardware, and easily -integrate an application into the :term:`OpenEmbedded Build System`. - -You can use an SDK to independently develop and test code that is -destined to run on some target machine. SDKs are completely -self-contained. The binaries are linked against their own copy of -``libc``, which results in no dependencies on the target system. To -achieve this, the pointer to the dynamic loader is configured at install -time since that path cannot be dynamically altered. This is the reason -for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext`` -archives. - -Another feature for the SDKs is that only one set of cross-compiler -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 -: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. - -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 :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. - -- The Quick EMUlator (QEMU), which lets you simulate target hardware. - QEMU is not literally part of the SDK. You must build and include - this emulator separately. However, QEMU plays an important role in - the development process that revolves around use of the SDK. - -In summary, the extensible and standard SDK share many features. -However, the extensible SDK has powerful development tools to help you -more quickly develop applications. Following is a table that summarizes -the primary differences between the standard and extensible SDK types -when considering which to build: - -+-----------------------+-----------------------+-----------------------+ -| *Feature* | *Standard SDK* | *Extensible SDK* | -+=======================+=======================+=======================+ -| Toolchain | Yes | Yes [1]_ | -+-----------------------+-----------------------+-----------------------+ -| Debugger | Yes | Yes [1]_ | -+-----------------------+-----------------------+-----------------------+ -| Size | 100+ MBytes | 1+ GBytes (or 300+ | -| | | MBytes for minimal | -| | | w/toolchain) | -+-----------------------+-----------------------+-----------------------+ -| ``devtool`` | No | Yes | -+-----------------------+-----------------------+-----------------------+ -| Build Images | No | Yes | -+-----------------------+-----------------------+-----------------------+ -| Updateable | No | Yes | -+-----------------------+-----------------------+-----------------------+ -| Managed Sysroot [2]_ | No | Yes | -+-----------------------+-----------------------+-----------------------+ -| Installed Packages | No [3]_ | Yes [4]_ | -+-----------------------+-----------------------+-----------------------+ -| Construction | Packages | Shared State | -+-----------------------+-----------------------+-----------------------+ - -.. [1] Extensible SDK contains the toolchain and debugger if :term:`SDK_EXT_TYPE` - is "full" or :term:`SDK_INCLUDE_TOOLCHAIN` is "1", which is the default. -.. [2] 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. -.. [3] You can add runtime package management to the standard SDK but it is not - supported by default. -.. [4] You must build and make the shared state available to extensible SDK - users for "packages" you want to enable users to install. - -The Cross-Development Toolchain -------------------------------- - -The :term:`Cross-Development Toolchain` consists -of a cross-compiler, cross-linker, and cross-debugger that are used to -develop user-space applications for targeted hardware. Additionally, for -an extensible SDK, the toolchain also has built-in ``devtool`` -functionality. This toolchain is created by running a SDK installer -script or through a :term:`Build Directory` that is based on -your metadata configuration or extension for your targeted device. The -cross-toolchain works with a matching target sysroot. - -Sysroots --------- - -The native and target sysroots contain needed headers and libraries for -generating binaries that run on the target architecture. The target -sysroot is based on the target root filesystem image that is built by -the OpenEmbedded build system and uses the same metadata configuration -used to build the cross-toolchain. - -The QEMU Emulator ------------------ - -The QEMU emulator allows you to simulate your hardware while running -your application or image. QEMU is not part of the SDK but is made -available a number of different ways: - -- If you have cloned the ``poky`` Git repository to create a - :term:`Source Directory` and you have - sourced the environment setup script, QEMU is installed and - automatically available. - -- If you have downloaded a Yocto Project release and unpacked it to - create a Source Directory and you have sourced the environment setup - script, QEMU is installed and automatically available. - -- If you have installed the cross-toolchain tarball and you have - sourced the toolchain's setup environment script, QEMU is also - installed and automatically available. - -SDK Development Model -===================== - -Fundamentally, the SDK fits into the development process as follows: - -.. image:: figures/sdk-environment.png - :align: center - -The SDK is installed on any machine and can be used to develop applications, -images, and kernels. An SDK can even be used by a QA Engineer or Release -Engineer. The fundamental concept is that the machine that has the SDK -installed does not have to be associated with the machine that has the -Yocto Project installed. A developer can independently compile and test -an object on their machine and then, when the object is ready for -integration into an image, they can simply make it available to the -machine that has the Yocto Project. Once the object is available, the -image can be rebuilt using the Yocto Project to produce the modified -image. - -You just need to follow these general steps: - -1. *Install the SDK for your target hardware:* For information on how to - install the SDK, see the "`Installing the - SDK <#sdk-installing-the-sdk>`__" section. - -2. *Download or Build the Target Image:* The Yocto Project supports - several target architectures and has many pre-built kernel images and - root filesystem images. - - If you are going to develop your application on hardware, go to the - :yocto_dl:`machines ` download area and choose a - target machine area from which to download the kernel image and root - filesystem. This download area could have several files in it that - support development using actual hardware. For example, the area - might contain ``.hddimg`` files that combine the kernel image with - the filesystem, boot loaders, and so forth. Be sure to get the files - you need for your particular development process. - - If you are going to develop your application and then run and test it - using the QEMU emulator, go to the - :yocto_dl:`machines/qemu ` download area. From this - area, go down into the directory for your target architecture (e.g. - ``qemux86_64`` for an Intel-based 64-bit architecture). Download the - kernel, root filesystem, and any other files you need for your - process. - - .. note:: - - To use the root filesystem in QEMU, you need to extract it. See - the " - Extracting the Root Filesystem - " section for information on how to extract the root filesystem. - -3. *Develop and Test your Application:* At this point, you have the - tools to develop your application. If you need to separately install - and use the QEMU emulator, you can go to `QEMU Home - Page `__ to download and learn about - the emulator. See the ":doc:`../dev-manual/dev-manual-qemu`" chapter in the - Yocto Project Development Tasks Manual for information on using QEMU - within the Yocto Project. - -The remainder of this manual describes how to use the extensible and -standard SDKs. Information also exists in appendix form that describes -how you can build, install, and modify an SDK. diff --git a/poky/documentation/sdk-manual/sdk-manual.rst b/poky/documentation/sdk-manual/sdk-manual.rst deleted file mode 100644 index 177826edf..000000000 --- a/poky/documentation/sdk-manual/sdk-manual.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -======================================================================================== -Yocto Project Application Development and the Extensible Software Development Kit (eSDK) -======================================================================================== - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - sdk-intro - sdk-extensible - sdk-using - sdk-working-projects - sdk-appendix-obtain - sdk-appendix-customizing - sdk-appendix-customizing-standard - history - -.. include:: /boilerplate.rst diff --git a/poky/documentation/sdk-manual/sdk-using.rst b/poky/documentation/sdk-manual/sdk-using.rst deleted file mode 100644 index 3a1cae773..000000000 --- a/poky/documentation/sdk-manual/sdk-using.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -********************** -Using the Standard SDK -********************** - -This chapter describes the standard SDK and how to install it. -Information includes unique installation and setup aspects for the -standard SDK. - -.. note:: - - For a side-by-side comparison of main features supported for a - standard SDK as compared to an extensible SDK, see the " - Introduction - " section. - -You can use a standard SDK to work on Makefile and Autotools-based -projects. See the "`Using the SDK Toolchain -Directly <#sdk-working-projects>`__" chapter for more information. - -Why use the Standard SDK and What is in It? -=========================================== - -The Standard SDK provides a cross-development toolchain and libraries -tailored to the contents of a specific image. You would use the Standard -SDK if you want a more traditional toolchain experience as compared to -the extensible SDK, which provides an internal build system and the -``devtool`` functionality. - -The installed Standard SDK consists of several files and directories. -Basically, it contains an SDK environment setup script, some -configuration files, and host and target root filesystems to support -usage. You can see the directory structure in the "`Installed Standard -SDK Directory -Structure <#sdk-installed-standard-sdk-directory-structure>`__" section. - -Installing the SDK -================== - -The first thing you need to do is install the SDK on your :term:`Build -Host` by running the ``*.sh`` installation script. - -You can download a tarball installer, which includes the pre-built -toolchain, the ``runqemu`` script, and support files from the -appropriate :yocto_dl:`toolchain ` directory within -the Index of Releases. Toolchains are available for several 32-bit and -64-bit architectures with the ``x86_64`` directories, respectively. The -toolchains the Yocto Project provides are based off the -``core-image-sato`` and ``core-image-minimal`` images and contain -libraries appropriate for developing against that image. - -The names of the tarball installer scripts are such that a string -representing the host system appears first in the filename and then is -immediately followed by a string representing the target architecture. -:: - - poky-glibc-host_system-image_type-arch-toolchain-release_version.sh - - Where: - host_system is a string representing your development system: - - i686 or x86_64. - - image_type is the image for which the SDK was built: - - core-image-minimal or core-image-sato. - - arch is a string representing the tuned target architecture: - - aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon. - - release_version is a string representing the release number of the Yocto Project: - - 3.1.2, 3.1.2+snapshot - -For example, the following SDK installer is for a 64-bit -development host system and a i586-tuned target architecture based off -the SDK for ``core-image-sato`` and using the current DISTRO snapshot: -:: - - poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh - -.. note:: - - As an alternative to downloading an SDK, you can build the SDK - installer. For information on building the installer, see the " - Building an SDK Installer - " section. - -The SDK and toolchains are self-contained and by default are installed -into the ``poky_sdk`` folder in your home directory. You can choose to -install the extensible SDK in any location when you run the installer. -However, because files need to be written under that directory during -the normal course of operation, the location you choose for installation -must be writable for whichever users need to use the SDK. - -The following command shows how to run the installer given a toolchain -tarball for a 64-bit x86 development host system and a 64-bit x86 target -architecture. The example assumes the SDK installer is located in -``~/Downloads/`` and has execution rights. - -.. note:: - - If you do not have write permissions for the directory into which you - are installing the SDK, the installer notifies you and exits. For - that case, set up the proper permissions in the directory and run the - installer again. - -:: - - $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-3.1.2.sh - Poky (Yocto Project Reference Distro) SDK installer version 3.1.2 - =============================================================== - Enter target directory for SDK (default: /opt/poky/3.1.2): - You are about to install the SDK to "/opt/poky/3.1.2". Proceed [Y/n]? Y - Extracting SDK........................................ ..............................done - Setting it up...done - SDK has been successfully set up and is ready to be used. - Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. - $ . /opt/poky/3.1.2/environment-setup-i586-poky-linux - -Again, reference the "`Installed Standard SDK Directory -Structure <#sdk-installed-standard-sdk-directory-structure>`__" section -for more details on the resulting directory structure of the installed -SDK. - -Running the SDK Environment Setup Script -======================================== - -Once you have the SDK installed, you must run the SDK environment setup -script before you can actually use the SDK. This setup script resides in -the directory you chose when you installed the SDK, which is either the -default ``/opt/poky/3.1.2`` directory or the directory you chose during -installation. - -Before running the script, be sure it is the one that matches the -architecture for which you are developing. Environment setup scripts -begin with the string "``environment-setup``" and include as part of -their name the tuned target architecture. As an example, the following -commands set the working directory to where the SDK was installed and -then source the environment setup script. In this example, the setup -script is for an IA-based target machine using i586 tuning: -:: - - $ source /opt/poky/3.1.2/environment-setup-i586-poky-linux - -When you run the -setup script, the same environment variables are defined as are when you -run the setup script for an extensible SDK. See the "`Running the -Extensible SDK Environment Setup -Script <#sdk-running-the-extensible-sdk-environment-setup-script>`__" -section for more information. diff --git a/poky/documentation/sdk-manual/sdk-working-projects.rst b/poky/documentation/sdk-manual/sdk-working-projects.rst deleted file mode 100644 index 5c828fd58..000000000 --- a/poky/documentation/sdk-manual/sdk-working-projects.rst +++ /dev/null @@ -1,423 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -******************************** -Using the SDK Toolchain Directly -******************************** - -You can use the SDK toolchain directly with Makefile and Autotools-based -projects. - -Autotools-Based Projects -======================== - -Once you have a suitable :ref:`sdk-manual/sdk-intro:the cross-development toolchain` -installed, it is very easy to develop a project using the `GNU -Autotools-based `__ -workflow, which is outside of the :term:`OpenEmbedded Build System`. - -The following figure presents a simple Autotools workflow. - -.. image:: figures/sdk-autotools-flow.png - :align: center - -Follow these steps to create a simple Autotools-based "Hello World" -project: - -.. note:: - - For more information on the GNU Autotools workflow, see the same - example on the - GNOME Developer - site. - -1. *Create a Working Directory and Populate It:* Create a clean - directory for your project and then make that directory your working - location. - :: - - $ mkdir $HOME/helloworld - $ cd $HOME/helloworld - - After setting up the directory, populate it with files needed for the flow. - You need a project source file, a file to help with configuration, - and a file to help create the Makefile, and a README file: - ``hello.c``, ``configure.ac``, ``Makefile.am``, and ``README``, - respectively. - - Use the following command to create an empty README file, which is - required by GNU Coding Standards: - :: - - $ touch README - - Create the remaining - three files as follows: - - - ``hello.c``: - :: - - #include - - main() - { - printf("Hello World!\n"); - } - - - ``configure.ac``: - :: - - AC_INIT(hello,0.1) - AM_INIT_AUTOMAKE([foreign]) - AC_PROG_CC - AC_CONFIG_FILES(Makefile) - AC_OUTPUT - - - ``Makefile.am``: - :: - - bin_PROGRAMS = hello - hello_SOURCES = hello.c - -2. *Source the Cross-Toolchain Environment Setup File:* As described - earlier in the manual, installing the cross-toolchain creates a - cross-toolchain environment setup script in the directory that the - SDK was installed. Before you can use the tools to develop your - project, you must source this setup script. The script begins with - the string "environment-setup" and contains the machine architecture, - which is followed by the string "poky-linux". For this example, the - command sources a script from the default SDK installation directory - that uses the 32-bit Intel x86 Architecture and the 3.1.2 Yocto - Project release: - :: - - $ source /opt/poky/3.1.2/environment-setup-i586-poky-linux - -3. *Create the configure Script:* Use the ``autoreconf`` command to - generate the ``configure`` script. - :: - - $ autoreconf - - The ``autoreconf`` - tool takes care of running the other Autotools such as ``aclocal``, - ``autoconf``, and ``automake``. - - .. note:: - - If you get errors from - configure.ac - , which - autoreconf - runs, that indicate missing files, you can use the "-i" option, - which ensures missing auxiliary files are copied to the build - host. - -4. *Cross-Compile the Project:* This command compiles the project using - the cross-compiler. The - :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 - appropriate host option to ``configure.sh``. The host option you use - is derived from the name of the environment setup script found in the - directory in which you installed the cross-toolchain. For example, - the host option for an ARM-based target that uses the GNU EABI is - ``armv5te-poky-linux-gnueabi``. You will notice that the name of the - script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the - following command works to update your project and rebuild it using - the appropriate cross-toolchain tools: - :: - - $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir - -5. *Make and Install the Project:* These two commands generate and - install the project into the destination directory: - :: - - $ make - $ make install DESTDIR=./tmp - - .. note:: - - To learn about environment variables established when you run the - cross-toolchain environment setup script and how they are used or - overridden when the Makefile, see the " - Makefile-Based Projects - " section. - - This next command is a simple way to verify the installation of your - project. Running the command prints the architecture on which the - binary file can run. This architecture should be the same - architecture that the installed cross-toolchain supports. - :: - - $ file ./tmp/usr/local/bin/hello - -6. *Execute Your Project:* To execute the project, you would need to run - it on your target hardware. If your target hardware happens to be - your build host, you could run the project as follows: - :: - - $ ./tmp/usr/local/bin/hello - - As expected, the project displays the "Hello World!" message. - -Makefile-Based Projects -======================= - -Simple Makefile-based projects use and interact with the cross-toolchain -environment variables established when you run the cross-toolchain -environment setup script. The environment variables are subject to -general ``make`` rules. - -This section presents a simple Makefile development flow and provides an -example that lets you see how you can use cross-toolchain environment -variables and Makefile variables during development. - -.. image:: figures/sdk-makefile-flow.png - :align: center - -The main point of this section is to explain the following three cases -regarding variable behavior: - -- *Case 1 - No Variables Set in the Makefile Map to Equivalent - Environment Variables Set in the SDK Setup Script:* Because matching - variables are not specifically set in the ``Makefile``, the variables - retain their values based on the environment setup script. - -- *Case 2 - Variables Are Set in the Makefile that Map to Equivalent - Environment Variables from the SDK Setup Script:* Specifically - setting matching variables in the ``Makefile`` during the build - results in the environment settings of the variables being - overwritten. In this case, the variables you set in the ``Makefile`` - are used. - -- *Case 3 - Variables Are Set Using the Command Line that Map to - Equivalent Environment Variables from the SDK Setup Script:* - Executing the ``Makefile`` from the command line results in the - environment variables being overwritten. In this case, the - command-line content is used. - -.. note:: - - Regardless of how you set your variables, if you use the "-e" option - with - make - , the variables from the SDK setup script take precedence: - :: - - $ make -e target - - -The remainder of this section presents a simple Makefile example that -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. -: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 3.1.2 -Yocto Project release and then echoing that variable shows the value -established through the script: -:: - - $ source /opt/poky/3.1.2/environment-setup-i586-poky-linux - $ echo ${CC} - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/3.1.2/sysroots/i586-poky-linux - -To illustrate variable use, work through this simple "Hello World!" -example: - -1. *Create a Working Directory and Populate It:* Create a clean - directory for your project and then make that directory your working - location. - :: - - $ mkdir $HOME/helloworld - $ cd $HOME/helloworld - - After - setting up the directory, populate it with files needed for the flow. - You need a ``main.c`` file from which you call your function, a - ``module.h`` file to contain headers, and a ``module.c`` that defines - your function. - - Create the three files as follows: - - - ``main.c``: - :: - - #include "module.h" - void sample_func(); - int main() - { - sample_func(); - return 0; - } - - - ``module.h``: - :: - - #include - void sample_func(); - - - ``module.c``: - :: - - #include "module.h" - void sample_func() - { - printf("Hello World!"); - printf("\n"); - } - -2. *Source the Cross-Toolchain Environment Setup File:* As described - earlier in the manual, installing the cross-toolchain creates a - cross-toolchain environment setup script in the directory that the - SDK was installed. Before you can use the tools to develop your - project, you must source this setup script. The script begins with - the string "environment-setup" and contains the machine architecture, - which is followed by the string "poky-linux". For this example, the - command sources a script from the default SDK installation directory - that uses the 32-bit Intel x86 Architecture and the DISTRO_NAME Yocto - Project release: - :: - - $ source /opt/poky/DISTRO/environment-setup-i586-poky-linux - -3. *Create the Makefile:* For this example, the Makefile contains - two lines that can be used to set the ``CC`` variable. One line is - identical to the value that is set when you run the SDK environment - setup script, and the other line sets ``CC`` to "gcc", the default - GNU compiler on the build host: - :: - - # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux - # CC="gcc" - all: main.o module.o - ${CC} main.o module.o -o target_bin - main.o: main.c module.h - ${CC} -I . -c main.c - module.o: module.c - module.h ${CC} -I . -c module.c - clean: - rm -rf *.o - rm target_bin - -4. *Make the Project:* Use the ``make`` command to create the binary - output file. Because variables are commented out in the Makefile, the - value used for ``CC`` is the value set when the SDK environment setup - file was run: - :: - - $ make - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin - - From the results of the previous command, you can see that - the compiler used was the compiler established through the ``CC`` - variable defined in the setup script. - - You can override the ``CC`` environment variable with the same - variable as set from the Makefile by uncommenting the line in the - Makefile and running ``make`` again. - :: - - $ make clean - rm -rf *.o - rm target_bin - # - # Edit the Makefile by uncommenting the line that sets CC to "gcc" - # - $ make - gcc -I . -c main.c - gcc -I . -c module.c - gcc main.o module.o -o target_bin - - As shown in the previous example, the - cross-toolchain compiler is not used. Rather, the default compiler is - used. - - This next case shows how to override a variable by providing the - variable as part of the command line. Go into the Makefile and - re-insert the comment character so that running ``make`` uses the - established SDK compiler. However, when you run ``make``, use a - command-line argument to set ``CC`` to "gcc": - :: - - $ make clean - rm -rf *.o - rm target_bin - # - # Edit the Makefile to comment out the line setting CC to "gcc" - # - $ make - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin - $ make clean - rm -rf *.o - rm target_bin - $ make CC="gcc" - gcc -I . -c main.c - gcc -I . -c module.c - gcc main.o module.o -o target_bin - - In the previous case, the command-line argument overrides the SDK - environment variable. - - In this last case, edit Makefile again to use the "gcc" compiler but - then use the "-e" option on the ``make`` command line: - :: - - $ make clean - rm -rf *.o - rm target_bin - # - # Edit the Makefile to use "gcc" - # - $ make - gcc -I . -c main.c - gcc -I . -c module.c - gcc main.o module.o -o target_bin - $ make clean - rm -rf *.o - rm target_bin - $ make -e - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin - - In the previous case, the "-e" option forces ``make`` to - use the SDK environment variables regardless of the values in the - Makefile. - -5. *Execute Your Project:* To execute the project (i.e. ``target_bin``), - use the following command: - :: - - $ ./target_bin - Hello World! - - .. note:: - - If you used the cross-toolchain compiler to build - target_bin - and your build host differs in architecture from that of the - target machine, you need to run your project on the target device. - - As expected, the project displays the "Hello World!" message. diff --git a/poky/documentation/sdk-manual/using.rst b/poky/documentation/sdk-manual/using.rst new file mode 100644 index 000000000..29fb50465 --- /dev/null +++ b/poky/documentation/sdk-manual/using.rst @@ -0,0 +1,153 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +********************** +Using the Standard SDK +********************** + +This chapter describes the standard SDK and how to install it. +Information includes unique installation and setup aspects for the +standard SDK. + +.. note:: + + For a side-by-side comparison of main features supported for a + standard SDK as compared to an extensible SDK, see the " + Introduction + " section. + +You can use a standard SDK to work on Makefile and Autotools-based +projects. See the "`Using the SDK Toolchain +Directly <#sdk-working-projects>`__" chapter for more information. + +Why use the Standard SDK and What is in It? +=========================================== + +The Standard SDK provides a cross-development toolchain and libraries +tailored to the contents of a specific image. You would use the Standard +SDK if you want a more traditional toolchain experience as compared to +the extensible SDK, which provides an internal build system and the +``devtool`` functionality. + +The installed Standard SDK consists of several files and directories. +Basically, it contains an SDK environment setup script, some +configuration files, and host and target root filesystems to support +usage. You can see the directory structure in the "`Installed Standard +SDK Directory +Structure <#sdk-installed-standard-sdk-directory-structure>`__" section. + +Installing the SDK +================== + +The first thing you need to do is install the SDK on your :term:`Build +Host` by running the ``*.sh`` installation script. + +You can download a tarball installer, which includes the pre-built +toolchain, the ``runqemu`` script, and support files from the +appropriate :yocto_dl:`toolchain ` directory within +the Index of Releases. Toolchains are available for several 32-bit and +64-bit architectures with the ``x86_64`` directories, respectively. The +toolchains the Yocto Project provides are based off the +``core-image-sato`` and ``core-image-minimal`` images and contain +libraries appropriate for developing against that image. + +The names of the tarball installer scripts are such that a string +representing the host system appears first in the filename and then is +immediately followed by a string representing the target architecture. +:: + + poky-glibc-host_system-image_type-arch-toolchain-release_version.sh + + Where: + host_system is a string representing your development system: + + i686 or x86_64. + + image_type is the image for which the SDK was built: + + core-image-minimal or core-image-sato. + + arch is a string representing the tuned target architecture: + + aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon. + + release_version is a string representing the release number of the Yocto Project: + + &DISTRO;, &DISTRO;+snapshot + +For example, the following SDK installer is for a 64-bit +development host system and a i586-tuned target architecture based off +the SDK for ``core-image-sato`` and using the current DISTRO snapshot: +:: + + poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh + +.. note:: + + As an alternative to downloading an SDK, you can build the SDK + installer. For information on building the installer, see the " + Building an SDK Installer + " section. + +The SDK and toolchains are self-contained and by default are installed +into the ``poky_sdk`` folder in your home directory. You can choose to +install the extensible SDK in any location when you run the installer. +However, because files need to be written under that directory during +the normal course of operation, the location you choose for installation +must be writable for whichever users need to use the SDK. + +The following command shows how to run the installer given a toolchain +tarball for a 64-bit x86 development host system and a 64-bit x86 target +architecture. The example assumes the SDK installer is located in +``~/Downloads/`` and has execution rights. + +.. note:: + + If you do not have write permissions for the directory into which you + are installing the SDK, the installer notifies you and exits. For + that case, set up the proper permissions in the directory and run the + installer again. + +:: + + $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + Poky (Yocto Project Reference Distro) SDK installer version &DISTRO; + =============================================================== + Enter target directory for SDK (default: /opt/poky/&DISTRO;): + You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed [Y/n]? Y + Extracting SDK........................................ ..............................done + Setting it up...done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + +Again, reference the "`Installed Standard SDK Directory +Structure <#sdk-installed-standard-sdk-directory-structure>`__" section +for more details on the resulting directory structure of the installed +SDK. + +Running the SDK Environment Setup Script +======================================== + +Once you have the SDK installed, you must run the SDK environment setup +script before you can actually use the SDK. This setup script resides in +the directory you chose when you installed the SDK, which is either the +default ``/opt/poky/&DISTRO;`` directory or the directory you chose during +installation. + +Before running the script, be sure it is the one that matches the +architecture for which you are developing. Environment setup scripts +begin with the string "``environment-setup``" and include as part of +their name the tuned target architecture. As an example, the following +commands set the working directory to where the SDK was installed and +then source the environment setup script. In this example, the setup +script is for an IA-based target machine using i586 tuning: +:: + + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + +When you run the +setup script, the same environment variables are defined as are when you +run the setup script for an extensible SDK. See the "`Running the +Extensible SDK Environment Setup +Script <#sdk-running-the-extensible-sdk-environment-setup-script>`__" +section for more information. diff --git a/poky/documentation/sdk-manual/working-projects.rst b/poky/documentation/sdk-manual/working-projects.rst new file mode 100644 index 000000000..3e40936ff --- /dev/null +++ b/poky/documentation/sdk-manual/working-projects.rst @@ -0,0 +1,423 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +******************************** +Using the SDK Toolchain Directly +******************************** + +You can use the SDK toolchain directly with Makefile and Autotools-based +projects. + +Autotools-Based Projects +======================== + +Once you have a suitable :ref:`sdk-manual/intro:the cross-development toolchain` +installed, it is very easy to develop a project using the `GNU +Autotools-based `__ +workflow, which is outside of the :term:`OpenEmbedded Build System`. + +The following figure presents a simple Autotools workflow. + +.. image:: figures/sdk-autotools-flow.png + :align: center + +Follow these steps to create a simple Autotools-based "Hello World" +project: + +.. note:: + + For more information on the GNU Autotools workflow, see the same + example on the + GNOME Developer + site. + +1. *Create a Working Directory and Populate It:* Create a clean + directory for your project and then make that directory your working + location. + :: + + $ mkdir $HOME/helloworld + $ cd $HOME/helloworld + + After setting up the directory, populate it with files needed for the flow. + You need a project source file, a file to help with configuration, + and a file to help create the Makefile, and a README file: + ``hello.c``, ``configure.ac``, ``Makefile.am``, and ``README``, + respectively. + + Use the following command to create an empty README file, which is + required by GNU Coding Standards: + :: + + $ touch README + + Create the remaining + three files as follows: + + - ``hello.c``: + :: + + #include + + main() + { + printf("Hello World!\n"); + } + + - ``configure.ac``: + :: + + AC_INIT(hello,0.1) + AM_INIT_AUTOMAKE([foreign]) + AC_PROG_CC + AC_CONFIG_FILES(Makefile) + AC_OUTPUT + + - ``Makefile.am``: + :: + + bin_PROGRAMS = hello + hello_SOURCES = hello.c + +2. *Source the Cross-Toolchain Environment Setup File:* As described + earlier in the manual, installing the cross-toolchain creates a + cross-toolchain environment setup script in the directory that the + SDK was installed. Before you can use the tools to develop your + project, you must source this setup script. The script begins with + the string "environment-setup" and contains the machine architecture, + which is followed by the string "poky-linux". For this example, the + command sources a script from the default SDK installation directory + that uses the 32-bit Intel x86 Architecture and the &DISTRO; Yocto + Project release: + :: + + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + +3. *Create the configure Script:* Use the ``autoreconf`` command to + generate the ``configure`` script. + :: + + $ autoreconf + + The ``autoreconf`` + tool takes care of running the other Autotools such as ``aclocal``, + ``autoconf``, and ``automake``. + + .. note:: + + If you get errors from + configure.ac + , which + autoreconf + runs, that indicate missing files, you can use the "-i" option, + which ensures missing auxiliary files are copied to the build + host. + +4. *Cross-Compile the Project:* This command compiles the project using + the cross-compiler. The + :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 + appropriate host option to ``configure.sh``. The host option you use + is derived from the name of the environment setup script found in the + directory in which you installed the cross-toolchain. For example, + the host option for an ARM-based target that uses the GNU EABI is + ``armv5te-poky-linux-gnueabi``. You will notice that the name of the + script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the + following command works to update your project and rebuild it using + the appropriate cross-toolchain tools: + :: + + $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir + +5. *Make and Install the Project:* These two commands generate and + install the project into the destination directory: + :: + + $ make + $ make install DESTDIR=./tmp + + .. note:: + + To learn about environment variables established when you run the + cross-toolchain environment setup script and how they are used or + overridden when the Makefile, see the " + Makefile-Based Projects + " section. + + This next command is a simple way to verify the installation of your + project. Running the command prints the architecture on which the + binary file can run. This architecture should be the same + architecture that the installed cross-toolchain supports. + :: + + $ file ./tmp/usr/local/bin/hello + +6. *Execute Your Project:* To execute the project, you would need to run + it on your target hardware. If your target hardware happens to be + your build host, you could run the project as follows: + :: + + $ ./tmp/usr/local/bin/hello + + As expected, the project displays the "Hello World!" message. + +Makefile-Based Projects +======================= + +Simple Makefile-based projects use and interact with the cross-toolchain +environment variables established when you run the cross-toolchain +environment setup script. The environment variables are subject to +general ``make`` rules. + +This section presents a simple Makefile development flow and provides an +example that lets you see how you can use cross-toolchain environment +variables and Makefile variables during development. + +.. image:: figures/sdk-makefile-flow.png + :align: center + +The main point of this section is to explain the following three cases +regarding variable behavior: + +- *Case 1 - No Variables Set in the Makefile Map to Equivalent + Environment Variables Set in the SDK Setup Script:* Because matching + variables are not specifically set in the ``Makefile``, the variables + retain their values based on the environment setup script. + +- *Case 2 - Variables Are Set in the Makefile that Map to Equivalent + Environment Variables from the SDK Setup Script:* Specifically + setting matching variables in the ``Makefile`` during the build + results in the environment settings of the variables being + overwritten. In this case, the variables you set in the ``Makefile`` + are used. + +- *Case 3 - Variables Are Set Using the Command Line that Map to + Equivalent Environment Variables from the SDK Setup Script:* + Executing the ``Makefile`` from the command line results in the + environment variables being overwritten. In this case, the + command-line content is used. + +.. note:: + + Regardless of how you set your variables, if you use the "-e" option + with + make + , the variables from the SDK setup script take precedence: + :: + + $ make -e target + + +The remainder of this section presents a simple Makefile example that +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. +: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 +established through the script: +:: + + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + $ echo ${CC} + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux + +To illustrate variable use, work through this simple "Hello World!" +example: + +1. *Create a Working Directory and Populate It:* Create a clean + directory for your project and then make that directory your working + location. + :: + + $ mkdir $HOME/helloworld + $ cd $HOME/helloworld + + After + setting up the directory, populate it with files needed for the flow. + You need a ``main.c`` file from which you call your function, a + ``module.h`` file to contain headers, and a ``module.c`` that defines + your function. + + Create the three files as follows: + + - ``main.c``: + :: + + #include "module.h" + void sample_func(); + int main() + { + sample_func(); + return 0; + } + + - ``module.h``: + :: + + #include + void sample_func(); + + - ``module.c``: + :: + + #include "module.h" + void sample_func() + { + printf("Hello World!"); + printf("\n"); + } + +2. *Source the Cross-Toolchain Environment Setup File:* As described + earlier in the manual, installing the cross-toolchain creates a + cross-toolchain environment setup script in the directory that the + SDK was installed. Before you can use the tools to develop your + project, you must source this setup script. The script begins with + the string "environment-setup" and contains the machine architecture, + which is followed by the string "poky-linux". For this example, the + command sources a script from the default SDK installation directory + that uses the 32-bit Intel x86 Architecture and the DISTRO_NAME Yocto + Project release: + :: + + $ source /opt/poky/DISTRO/environment-setup-i586-poky-linux + +3. *Create the Makefile:* For this example, the Makefile contains + two lines that can be used to set the ``CC`` variable. One line is + identical to the value that is set when you run the SDK environment + setup script, and the other line sets ``CC`` to "gcc", the default + GNU compiler on the build host: + :: + + # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux + # CC="gcc" + all: main.o module.o + ${CC} main.o module.o -o target_bin + main.o: main.c module.h + ${CC} -I . -c main.c + module.o: module.c + module.h ${CC} -I . -c module.c + clean: + rm -rf *.o + rm target_bin + +4. *Make the Project:* Use the ``make`` command to create the binary + output file. Because variables are commented out in the Makefile, the + value used for ``CC`` is the value set when the SDK environment setup + file was run: + :: + + $ make + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin + + From the results of the previous command, you can see that + the compiler used was the compiler established through the ``CC`` + variable defined in the setup script. + + You can override the ``CC`` environment variable with the same + variable as set from the Makefile by uncommenting the line in the + Makefile and running ``make`` again. + :: + + $ make clean + rm -rf *.o + rm target_bin + # + # Edit the Makefile by uncommenting the line that sets CC to "gcc" + # + $ make + gcc -I . -c main.c + gcc -I . -c module.c + gcc main.o module.o -o target_bin + + As shown in the previous example, the + cross-toolchain compiler is not used. Rather, the default compiler is + used. + + This next case shows how to override a variable by providing the + variable as part of the command line. Go into the Makefile and + re-insert the comment character so that running ``make`` uses the + established SDK compiler. However, when you run ``make``, use a + command-line argument to set ``CC`` to "gcc": + :: + + $ make clean + rm -rf *.o + rm target_bin + # + # Edit the Makefile to comment out the line setting CC to "gcc" + # + $ make + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin + $ make clean + rm -rf *.o + rm target_bin + $ make CC="gcc" + gcc -I . -c main.c + gcc -I . -c module.c + gcc main.o module.o -o target_bin + + In the previous case, the command-line argument overrides the SDK + environment variable. + + In this last case, edit Makefile again to use the "gcc" compiler but + then use the "-e" option on the ``make`` command line: + :: + + $ make clean + rm -rf *.o + rm target_bin + # + # Edit the Makefile to use "gcc" + # + $ make + gcc -I . -c main.c + gcc -I . -c module.c + gcc main.o module.o -o target_bin + $ make clean + rm -rf *.o + rm target_bin + $ make -e + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin + + In the previous case, the "-e" option forces ``make`` to + use the SDK environment variables regardless of the values in the + Makefile. + +5. *Execute Your Project:* To execute the project (i.e. ``target_bin``), + use the following command: + :: + + $ ./target_bin + Hello World! + + .. note:: + + If you used the cross-toolchain compiler to build + target_bin + and your build host differs in architecture from that of the + target machine, you need to run your project on the target device. + + As expected, the project displays the "Hello World!" message. -- cgit v1.2.3