diff options
Diffstat (limited to 'documentation/sdk-manual')
18 files changed, 3061 insertions, 5095 deletions
diff --git a/documentation/sdk-manual/appendix-customizing-standard.rst b/documentation/sdk-manual/appendix-customizing-standard.rst new file mode 100644 index 0000000000..c619c15e46 --- /dev/null +++ b/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 :term:`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 +:term:`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/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst new file mode 100644 index 0000000000..61091d83ba --- /dev/null +++ b/documentation/sdk-manual/appendix-customizing.rst @@ -0,0 +1,358 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +*************************************************** +Customizing the Extensible SDK standalone installer +*************************************************** + +This appendix describes customizations you can apply to the extensible +SDK when using in the standalone installer version. + +.. note:: + + It is also possible to use the Extensible SDK functionality directly in a + Yocto build, avoiding separate installer artefacts. Please refer to + ":ref:`sdk-manual/extensible:Installing 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:`ESDK_LOCALCONF_REMOVE` + 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:`ESDK_LOCALCONF_REMOVE` + in the glossary of the Yocto Project Reference Manual. + +- Variables listed in + :term:`ESDK_LOCALCONF_ALLOW` + are included. Including a variable in the value of + :term:`ESDK_LOCALCONF_ALLOW` overrides either of the previous two + filters. The default value is blank. + +- Classes inherited globally with :term:`INHERIT` that are listed in + :term:`ESDK_CLASS_INHERIT_DISABLE` are disabled. Using + :term:`ESDK_CLASS_INHERIT_DISABLE` to disable these classes is the typical + method to disable classes that are problematic or unnecessary in the SDK + context. The default value disables the + :ref:`ref-classes-buildhistory` and :ref:`ref-classes-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, there are cases when 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 + disable them by adding them to the :term:`ESDK_CLASS_INHERIT_DISABLE` + variable as described in the previous section. + + .. note:: + + The default value of :term:`ESDK_CLASS_INHERIT_DISABLE` + 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 + ":ref:`bitbake-user-manual/bitbake-user-manual-metadata: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 <overview-manual/concepts:shared state cache>` 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 :term:`ESDK_CLASS_INHERIT_DISABLE` + 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 + ":ref:`sdk-manual/appendix-customizing: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 + ":ref:`sdk-manual/appendix-customizing: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 + :term:`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 SDK installer. For information on how to build an SDK +installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" +section. + +By default, this title is derived from +:term:`DISTRO_NAME` when it is +set. If the :term:`DISTRO_NAME` variable is not set, the title is derived +from the :term:`DISTRO` variable. + +The +:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` +class defines the default value of the :term:`SDK_TITLE` variable as +follows:: + + SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" + +While there are several ways of changing 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 +:term:`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: + +#. Create a directory that can be shared over HTTP or HTTPS. You can do + this by setting up a web server such as an :wikipedia:`Apache HTTP Server + <Apache_HTTP_Server>` or :wikipedia:`Nginx <Nginx>` server in the cloud + to host the directory. This directory must contain the published SDK. + +#. 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 + ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`" + section. + +#. Build the extensible SDK normally (i.e., use the + ``bitbake -c populate_sdk_ext`` imagename command). + +#. 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 +":ref:`sdk-manual/extensible: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 <ref-classes-populate-sdk-*>` +class as follows:: + + SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" + +You can +change this default installation directory by specifically setting the +:term:`SDKEXTPATH` variable. + +While there are several ways of setting 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 +:term:`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: + +#. 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. + +#. Expose the ``sstate-cache`` directory produced by the build. + Typically, you expose this directory by making it available through + an :wikipedia:`Apache HTTP Server <Apache_HTTP_Server>` or + :wikipedia:`Nginx <Nginx>` server. + +#. 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://.* https://example.com/some_path/sstate-cache/PATH" + + You can set the :term:`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 pass the variable to the SDK by + adding the following:: + + ESDK_LOCALCONF_ALLOW = "SSTATE_MIRRORS" + + - Alternatively, if you just want to set the :term:`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 :term:`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 + :term:`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 :term:`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 + :ref:`sdk-manual/appendix-customizing: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 :term:`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/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst new file mode 100644 index 0000000000..d06d6ec6b5 --- /dev/null +++ b/documentation/sdk-manual/appendix-obtain.rst @@ -0,0 +1,306 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +***************** +Obtaining the SDK +***************** + +Working with the SDK components directly in a Yocto build +========================================================= + +Please refer to section +":ref:`sdk-manual/extensible:Setting up the Extensible SDK environment directly in a Yocto build`" + +Note that to use this feature effectively either a powerful build +machine, or a well-functioning sstate cache infrastructure is required: +otherwise significant time could be spent waiting for components to be built +by BitBake from source code. + +Working with standalone SDK Installers +====================================== + +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: + +#. *Go to the Installers Directory:* Go to + :yocto_dl:`/releases/yocto/yocto-&DISTRO;/toolchain/` + +#. *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). + +#. *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``: + + - ``host_system``: string representing your development system: ``i686`` or ``x86_64`` + + - ``type``: string representing the image: ``sato`` or ``minimal`` + + - ``arch``: string representing the target architecture such as ``cortexa57-qemuarm64`` + + - ``release``: version of the 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 QEMU target, go into the ``x86_64`` + folder and download the following installer:: + + poky-glibc-x86_64-core-image-sato-core2-64-qemux86-64-toolchain-&DISTRO;.sh + +#. *Run the Installer:* Be sure you have execution privileges and run + the installer. Here is an example from the ``Downloads`` + directory:: + + $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-qemux86-64-toolchain-&DISTRO;.sh + + During execution of the script, you choose the root location for the + toolchain. See the + ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`" + section and the + ":ref:`sdk-manual/appendix-obtain: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: + +#. *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. + +#. *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. + +#. *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. + +#. *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 :term:`Build Directory` matches the architecture + for which you are building. + +#. *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 + :term:`Build Directory` is correctly set. + + .. note:: + + If you are building an SDK installer for the Extensible SDK, the + :term:`SDKMACHINE` value must be set for the architecture of the + machine you are using to build the installer. If :term:`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. + + +#. *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 :term:`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. Here is an example using ``libc`` + static development libraries: TOOLCHAIN_TARGET_TASK:append = " + libc-staticdev" + +#. *Run the Installer:* You can now run the SDK installer from + ``tmp/deploy/sdk`` in the :term:`Build Directory`. Here 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 + ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`" + section and the + ":ref:`sdk-manual/appendix-obtain: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: + +#. *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 </releases/yocto/yocto-&DISTRO;/machines/>` + 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 the + ``core-image-profile-machine.tar.bz2`` naming convention: + + - ``profile``: filesystem image's profile, such as ``minimal``, + ``minimal-dev`` or ``sato``. For information on these types of image + profiles, see the "Images" chapter in the Yocto Project Reference Manual. + + - ``machine``: same string as the name of the parent download directory. + + 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 + +#. *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``). + + Here 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 + +#. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk`` + command and provide the root filesystem image. + + Here 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 </releases/yocto/yocto-&DISTRO;/machines/>`. + 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 ``beaglebone-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: 100% + +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/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst new file mode 100644 index 0000000000..3f6a754d88 --- /dev/null +++ b/documentation/sdk-manual/extensible.rst @@ -0,0 +1,1584 @@ +.. 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 + :ref:`sdk-manual/intro: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 +":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" 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 +============================= + +Two ways to install the Extensible SDK +-------------------------------------- + +Extensible SDK can be installed in two different ways, and both have +their own pros and cons: + +#. *Setting up the Extensible SDK environment directly in a Yocto build*. This + avoids having to produce, test, distribute and maintain separate SDK + installer archives, which can get very large. There is only one environment + for the regular Yocto build and the SDK and less code paths where things can + go not according to plan. It's easier to update the SDK: it simply means + updating the Yocto layers with git fetch or layer management tooling. The + SDK extensibility is better than in the second option: just run ``bitbake`` + again to add more things to the sysroot, or add layers if even more things + are required. + +#. *Setting up the Extensible SDK from a standalone installer*. This has the + benefit of having a single, self-contained archive that includes all the + needed binary artifacts. So nothing needs to be rebuilt, and there is no + need to provide a well-functioning binary artefact cache over the network + for developers with underpowered laptops. + +.. _setting_up_ext_sdk_in_build: + +Setting up the Extensible SDK environment directly in a Yocto build +------------------------------------------------------------------- + +#. Set up all the needed layers and a Yocto :term:`Build Directory`, e.g. a regular Yocto + build where ``bitbake`` can be executed. + +#. Run:: + + $ bitbake meta-ide-support + $ bitbake -c populate_sysroot gtk+3 + # or any other target or native item that the application developer would need + $ bitbake build-sysroots -c build_native_sysroot && bitbake build-sysroots -c build_target_sysroot + +Setting up the Extensible SDK from a standalone installer +--------------------------------------------------------- + +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 </releases/yocto/yocto-&DISTRO;/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 + :ref:`sdk-manual/appendix-obtain: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:: + + $ ./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 + +.. 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. + +.. _running_the_ext_sdk_env: + +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. + +When using a SDK directly in a Yocto build, you will find the script in +``tmp/deploy/images/qemux86-64/`` in your :term:`Build Directory`. + +When using a standalone SDK installer, 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. + +When using the environment script directly in a Yocto build, it can +be run similarly:: + + $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux + +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: + +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 ":doc:`/ref-manual/devtool-reference`" + section in the Yocto Project Reference Manual. + +``devtool`` subcommands 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 ide-sdk*: Generates a configuration for an IDE. + +- *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 + :width: 100% + +#. *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. + +#. *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 effect when you build it later. + +#. *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 + +#. *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. + +#. *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 + :width: 100% + +#. *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, there is no ``srctree`` argument. Consequently, the + default behavior of the ``devtool modify`` command is to extract + the source files pointed to by the :term:`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 :term:`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 :term:`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. + +#. *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. + +#. *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 + +#. *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. + +#. *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. + +``devtool ide-sdk`` configures IDEs for the extensible SDK +---------------------------------------------------------- + +``devtool ide-sdk`` automatically configures IDEs to use the extensible SDK. +To make sure that all parts of the extensible SDK required by the generated +IDE configuration are available, ``devtool ide-sdk`` uses BitBake in the +background to bootstrap the extensible SDK. + +The extensible SDK supports two different development modes. +``devtool ide-sdk`` supports both of them: + +#. *Modified mode*: + + By default ``devtool ide-sdk`` generates IDE configurations for recipes in + workspaces created by ``devtool modify`` or ``devtool add`` as described in + :ref:`using_devtool`. This mode creates IDE configurations with support for + advanced features, such as deploying the binaries to the remote target + device and performing remote debugging sessions. The generated IDE + configurations use the per recipe sysroots as Bitbake does internally. + + In order to use the tool, a few settings are needed. As a starting example, + the following lines of code can be added to the ``local.conf`` file:: + + # Build the companion debug file system + IMAGE_GEN_DEBUGFS = "1" + # Optimize build time: with devtool ide-sdk the dbg tar is not needed + IMAGE_FSTYPES_DEBUGFS = "" + # Without copying the binaries into roofs-dbg, GDB does not find all source files. + IMAGE_CLASSES += "image-combined-dbg" + + # SSH is mandatory, no password simplifies the usage + EXTRA_IMAGE_FEATURES += "\ + ssh-server-openssh \ + debug-tweaks \ + " + + # Remote debugging needs gdbserver on the target device + IMAGE_INSTALL:append = " gdbserver" + + # Add the recipes which should be modified to the image + # Otherwise some dependencies might be missing. + IMAGE_INSTALL:append = " my-recipe" + + Assuming the BitBake environment is set up correctly and a workspace has + been created for the recipe using ``devtool modify my-recipe``, the + following command can create the SDK and the configuration for VSCode in + the recipe workspace:: + + $ devtool ide-sdk my-recipe core-image-minimal --target root@192.168.7.2 + + The command requires an image recipe (``core-image-minimal`` for this example) + that is used to create the SDK. This firmware image should also be installed + on the target device. It is possible to pass multiple package recipes. + ``devtool ide-sdk`` tries to create an IDE configuration for all package + recipes. + + What this command does exactly depends on the recipe, more precisely on the + build tool used by the recipe. The basic idea is to configure the IDE so + that it calls the build tool exactly as ``bitbake`` does. + + For example, a CMake preset is created for a recipe that inherits + :ref:`ref-classes-cmake`. In the case of VSCode, CMake presets are supported + by the CMake Tools plugin. This is an example of how the build + configuration used by ``bitbake`` is exported to an IDE configuration that + gives exactly the same build results. + + Support for remote debugging with seamless integration into the IDE is + important for a cross-SDK. ``devtool ide-sdk`` automatically generates the + necessary helper scripts for deploying the compiled artifacts to the target + device as well as the necessary configuration for the debugger and the IDE. + + .. note:: + + To ensure that the debug symbols on the build machine match the binaries + running on the target device, it is essential that the image built by + ``devtool ide-sdk`` is running on the target device. + + ``devtool ide-sdk`` aims to support multiple programming languages and + multiple IDEs natively. "Natively" means that the IDE is configured to call + the build tool (e.g. CMake or Meson) directly. This has several advantages. + First of all, it is much faster than ``devtool build``, but it also allows + to use the very good integration of tools like CMake or GDB in VSCode and + other IDEs. However, supporting many programming languages and multiple + IDEs is quite an elaborate and constantly evolving thing. Support for IDEs + is therefore implemented as plugins. Plugins can also be provided by + optional layers. + + The default IDE is VSCode. Some hints about using VSCode: + + - To work on the source code of a recipe an instance of VSCode is started in + the recipe's workspace. Example:: + + code build/workspace/sources/my-recipe + + - To work with CMake press ``Ctrl + Shift + p``, type ``cmake``. This will + show some possible commands like selecting a CMake preset, compiling or + running CTest. + + For recipes inheriting :ref:`ref-classes-cmake-qemu` rather than + :ref:`ref-classes-cmake`, executing cross-compiled unit tests on the host + can be supported transparently with QEMU user-mode. + + - To work with Meson press ``Ctrl + Shift + p``, type ``meson``. This will + show some possible commands like compiling or executing the unit tests. + + A note on running cross-compiled unit tests on the host: Meson enables + support for QEMU user-mode by default. It is expected that the execution + of the unit tests from the IDE will work easily without any additional + steps, provided that the code is suitable for execution on the host + machine. + + - For the deployment to the target device, just press ``Ctrl + Shift + p``, + type ``task``. Select ``install && deploy-target``. + + - For remote debugging, switch to the debugging view by pressing the "play" + button with the ``bug icon`` on the left side. This will provide a green + play button with a drop-down list where a debug configuration can be + selected. After selecting one of the generated configurations, press the + "play" button. + + Starting a remote debugging session automatically initiates the deployment + to the target device. If this is not desired, the + ``"dependsOn": ["install && deploy-target...]`` parameter of the tasks + with ``"label": "gdbserver start...`` can be removed from the + ``tasks.json`` file. + + VSCode supports GDB with many different setups and configurations for many + different use cases. However, most of these setups have some limitations + when it comes to cross-development, support only a few target + architectures or require a high performance target device. Therefore + ``devtool ide-sdk`` supports the classic, generic setup with GDB on the + development host and gdbserver on the target device. + + Roughly summarized, this means: + + - The binaries are copied via SSH to the remote target device by a script + referred by ``tasks.json``. + + - gdbserver is started on the remote target device via SSH by a script + referred by ``tasks.json``. + + Changing the parameters that are passed to the debugging executable + requires modifying the generated script. The script is located at + ``oe-scripts/gdbserver_*``. Defining the parameters in the ``args`` + field in the ``launch.json`` file does not work. + + - VSCode connects to gdbserver as documented in + `Remote debugging or debugging with a local debugger server + <https://code.visualstudio.com/docs/cpp/launch-json-reference#_remote-debugging-or-debugging-with-a-local-debugger-server>`__. + + Additionally ``--ide=none`` is supported. With the ``none`` IDE parameter, + some generic configuration files like ``gdbinit`` files and some helper + scripts starting gdbserver remotely on the target device as well as the GDB + client on the host are generated. + + Here is a usage example for the ``cmake-example`` recipe from the + ``meta-selftest`` layer which inherits :ref:`ref-classes-cmake-qemu`: + + .. code-block:: sh + + # Create the SDK + devtool modify cmake-example + devtool ide-sdk cmake-example core-image-minimal -c --debug-build-config --ide=none + + # Install the firmware on a target device or start QEMU + runqemu + + # From exploring the workspace of cmake-example + cd build/workspace/sources/cmake-example + + # Find cmake-native and save the path into a variable + # Note: using just cmake instead of $CMAKE_NATIVE would work in many cases + CMAKE_NATIVE="$(jq -r '.configurePresets[0] | "\(.cmakeExecutable)"' CMakeUserPresets.json)" + + # List available CMake presets + "$CMAKE_NATIVE" --list-presets + Available configure presets: + + "cmake-example-cortexa57" - cmake-example: cortexa57 + + # Re-compile the already compiled sources + "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 + ninja: no work to do. + # Do a clean re-build + "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target clean + [1/1] Cleaning all built files... + Cleaning... 8 files. + "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target all + [7/7] Linking CXX executable cmake-example + + # Run the cross-compiled unit tests with QEMU user-mode + "$CMAKE_NATIVE" --build --preset cmake-example-cortexa57 --target test + [0/1] Running tests... + Test project .../build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 + Start 1: test-cmake-example + 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec + + 100% tests passed, 0 tests failed out of 1 + + Total Test time (real) = 0.03 sec + + # Using CTest directly is possible as well + CTEST_NATIVE="$(dirname "$CMAKE_NATIVE")/ctest" + + # List available CMake presets + "$CTEST_NATIVE" --list-presets + Available test presets: + + "cmake-example-cortexa57" - cmake-example: cortexa57 + + # Run the cross-compiled unit tests with QEMU user-mode + "$CTEST_NATIVE" --preset "cmake-example-cortexa57" + Test project ...build/tmp/work/cortexa57-poky-linux/cmake-example/1.0/cmake-example-1.0 + Start 1: test-cmake-example + 1/1 Test #1: test-cmake-example ............... Passed 0.03 sec + + 100% tests passed, 0 tests failed out of 1 + + Total Test time (real) = 0.03 sec + + # Deploying the new build to the target device (default is QEUM at 192.168.7.2) + oe-scripts/install_and_deploy_cmake-example-cortexa57 + + # Start a remote debugging session with gdbserver on the target and GDB on the host + oe-scripts/gdbserver_1234_usr-bin-cmake-example_m + oe-scripts/gdb_1234_usr-bin-cmake-example + break main + run + step + stepi + continue + quit + + # Stop gdbserver on the target device + oe-scripts/gdbserver_1234_usr-bin-cmake-example_m stop + +#. *Shared sysroots mode* + + For some recipes and use cases a per-recipe sysroot based SDK is not + suitable. Optionally ``devtool ide-sdk`` configures the IDE to use the + toolchain provided by the extensible SDK as described in + :ref:`running_the_ext_sdk_env`. ``devtool ide-sdk --mode=shared`` is + basically a wrapper for the setup of the extensible SDK as described in + :ref:`setting_up_ext_sdk_in_build`. The IDE gets a configuration to use the + shared sysroots. + + Creating a SDK with shared sysroots that contains all the dependencies needed + to work with ``my-recipe`` is possible with the following example command:: + + $ devtool ide-sdk --mode=shared my-recipe + + For VSCode the cross-toolchain is exposed as a CMake kit. CMake kits are + defined in ``~/.local/share/CMakeTools/cmake-tools-kits.json``. + The following example shows how the cross-toolchain can be selected in + VSCode. First of all we need a folder containing a CMake project. + For this example, let's create a CMake project and start VSCode:: + + mkdir kit-test + echo "project(foo VERSION 1.0)" > kit-test/CMakeLists.txt + code kit-test + + If there is a CMake project in the workspace, cross-compilation is supported: + + - Press ``Ctrl + Shift + P``, type ``CMake: Scan for Kits`` + - Press ``Ctrl + Shift + P``, type ``CMake: Select a Kit`` + + Finally most of the features provided by CMake and the IDE should be available. + + Other IDEs than VSCode are supported as well. However, + ``devtool ide-sdk --mode=shared --ide=none my-recipe`` is currently + just a simple wrapper for the setup of the extensible SDK, as described in + :ref:`setting_up_ext_sdk_in_build`. + +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 + :ref:`dev-manual/upgrading-recipes: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:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers` support. + +The following diagram shows the common development flow used with the +``devtool upgrade`` command: + +.. image:: figures/sdk-devtool-upgrade-flow.png + :width: 100% + +#. *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 :term:`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 :term:`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 :term:`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. + +#. *Resolve any Conflicts created by the Upgrade*: Conflicts could happen + after upgrading the software to a new version. Conflicts occur + if your recipe specifies some patch files in :term:`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. + +#. *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 + +#. *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. + +#. *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 :term:`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 :term:`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 :term:`LIC_FILES_CHKSUM` variable to point to one or more of those +comments if present. Setting :term:`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 :term:`LICENSE` value to "CLOSED" and leaves the +:term:`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. :term:`CC`, :term:`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, there is + a list of environment variables that are 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 :term:`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 "--also-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 + "--also-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: through ``npm`` or 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. ``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: + +#. Fetch the source + +#. Unpack the source + +#. Configure the source + +#. Compile the source + +#. Install the build output + +#. 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. There is +a :ref:`ref-classes-base` class 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 + :ref:`ref-tasks-install` that have been put into the shared sysroot. For + more information, see the + ":ref:`dev-manual/new-recipe:sharing files between recipes`" section. + + - ``packages-split/``: Contains subdirectories for each package + produced by the recipe. For more information, see the + ":ref:`sdk-manual/extensible: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 :term:`EXTRA_OECONF` or :term:`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 :term:`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 :term:`EXTRA_OECONF` or +:term:`PACKAGECONFIG_CONFARGS`. If applicable, the command also shows you +the output of the configure script's "--help" 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. There is one sysroot per +"machine" for which the SDK is being built. In practical terms, this +means there is a sysroot for the target machine, and a sysroot 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 :term:`PACKAGES` variable lists all of the packages to be +produced, while the :term:`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 :term:`PACKAGES` value is significant. For +each installed file, the first package whose :term:`FILES` value matches the +file is the package into which the file goes. Both the :term:`PACKAGES` and +:term:`FILES` variables have default values. 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. + +When using the extensible SDK directly in a Yocto build +------------------------------------------------------- + +In this scenario, the Yocto build tooling, e.g. ``bitbake`` +is directly accessible to build additional items, and it +can simply be executed directly:: + + $ bitbake curl-native + # Add newly built native items to native sysroot + $ bitbake build-sysroots -c build_native_sysroot + $ bitbake mesa + # Add newly built target items to target sysroot + $ bitbake build-sysroots -c build_target_sysroot + +When using a standalone installer for the Extensible SDK +-------------------------------------------------------- + +:: + + $ 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 there is no recipe 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 +":ref:`sdk-manual/appendix-customizing: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: + +#. If necessary, install an extensible SDK that you want to use as a + base for your derivative SDK. + +#. Source the environment script for the SDK. + +#. Add the extra libraries or other components you want by using the + ``devtool add`` command. + +#. 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/documentation/sdk-manual/index.rst b/documentation/sdk-manual/index.rst new file mode 100644 index 0000000000..dc7186b911 --- /dev/null +++ b/documentation/sdk-manual/index.rst @@ -0,0 +1,21 @@ +.. 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 + +.. include:: /boilerplate.rst diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst new file mode 100644 index 0000000000..e8fd191dbc --- /dev/null +++ b/documentation/sdk-manual/intro.rst @@ -0,0 +1,208 @@ +.. 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 +explains how to use both the Yocto Project extensible and standard +SDKs to develop applications and images. + +All SDKs consist of the following: + +- *Cross-Development Toolchain*: This toolchain contains a compiler, + debugger, and various associated tools. + +- *Libraries, Headers, and Symbols*: The libraries, headers, and + symbols are specific to the image (i.e. they match the image + against which the SDK was built). + +- *Environment Setup Script*: This ``*.sh`` file, once sourced, 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 of 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 its own +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. Here 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; in addition, +the extensible SDK comes with 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 +automatically installed and available if you have done any one of +the following: + +- cloned the ``poky`` Git repository to create a + :term:`Source Directory` and sourced the environment setup script. + +- downloaded a Yocto Project release and unpacked it to + create a Source Directory and sourced the environment setup + script. + +- installed the cross-toolchain tarball and + sourced the toolchain's setup environment script. + +SDK Development Model +===================== + +Fundamentally, the SDK fits into the development process as follows: + +.. image:: figures/sdk-environment.png + :width: 100% + +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: + +#. *Install the SDK for your target hardware:* For information on how to + install the SDK, see the ":ref:`sdk-manual/using:installing the sdk`" + section. + +#. *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 </releases/yocto/yocto-&DISTRO;/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 </releases/yocto/yocto-&DISTRO;/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 + ":ref:`sdk-manual/appendix-obtain:extracting the root filesystem`" + section for information on how to do this extraction. + +#. *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 <https://wiki.qemu.org/Main_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. There is also information in appendix form describing +how you can build, install, and modify an SDK. diff --git a/documentation/sdk-manual/sdk-appendix-customizing-standard.xml b/documentation/sdk-manual/sdk-appendix-customizing-standard.xml deleted file mode 100644 index f20891c80d..0000000000 --- a/documentation/sdk-manual/sdk-appendix-customizing-standard.xml +++ /dev/null @@ -1,58 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > - -<appendix id='sdk-appendix-customizing-standard'> - -<title>Customizing the Standard SDK</title> - -<para> - This appendix presents customizations you can apply to the standard SDK. -</para> - -<section id='sdk-adding-individual-packages'> - <title>Adding Individual Packages to the Standard SDK</title> - - <para> - When you build a standard SDK using the - <filename>bitbake -c populate_sdk</filename>, a default set of - packages is included in the resulting SDK. - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink> - variables control the set of packages adding to the SDK. - </para> - - <para> - If you want to add individual packages to the toolchain that runs on - the host, simply add those packages to the - <filename>TOOLCHAIN_HOST_TASK</filename> 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 - <filename>TOOLCHAIN_TARGET_TASK</filename> variable. - </para> -</section> - -<section id='adding-api-documentation-to-the-standard-sdk'> - <title>Adding API Documentation to the Standard SDK</title> - - <para> - You can include API documentation as well as any other - documentation provided by recipes with the standard SDK by - adding "api-documentation" to the - <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> - variable: - <literallayout class='monospaced'> - DISTRO_FEATURES_append = " api-documentation" - </literallayout> - Setting this variable as shown here causes the OpenEmbedded build - system to build the documentation and then include it in the standard - SDK. - </para> -</section> - -</appendix> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml b/documentation/sdk-manual/sdk-appendix-customizing.xml deleted file mode 100644 index 911658f914..0000000000 --- a/documentation/sdk-manual/sdk-appendix-customizing.xml +++ /dev/null @@ -1,514 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > - -<appendix id='sdk-appendix-customizing'> - -<title>Customizing the Extensible SDK</title> - -<para> - This appendix describes customizations you can apply to the extensible SDK. -</para> - -<section id='sdk-configuring-the-extensible-sdk'> - <title>Configuring the Extensible SDK</title> - - <para> - 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 <filename>local.conf</filename> and - <filename>auto.conf</filename>: - <itemizedlist> - <listitem><para> - Variables whose values start with "/" are excluded since the - assumption is that those values are paths that are likely to - be specific to the - <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>. - </para></listitem> - <listitem><para> - Variables listed in - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink> - 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.</para> - - <para>For a list of the variables excluded by default, see the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink> - in the glossary of the Yocto Project Reference Manual. - </para></listitem> - <listitem><para> - Variables listed in - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink> - are included. - Including a variable in the value of - <filename>SDK_LOCAL_CONF_WHITELIST</filename> overrides either - of the previous two filters. - The default value is blank. - </para></listitem> - <listitem><para> - Classes inherited globally with - <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink> - that are listed in - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink> - are disabled. - Using <filename>SDK_INHERIT_BLACKLIST</filename> 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 - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-icecc'><filename>icecc</filename></ulink> - classes. - </para></listitem> - </itemizedlist> - Additionally, the contents of <filename>conf/sdk-extra.conf</filename>, - when present, are appended to the end of - <filename>conf/local.conf</filename> within the produced SDK, without - any filtering. - The <filename>sdk-extra.conf</filename> 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. - </para> -</section> - -<section id='adjusting-the-extensible-sdk-to-suit-your-build-hosts-setup'> - <title>Adjusting the Extensible SDK to Suit Your Build Host's Setup</title> - - <para> - In most cases, the extensible SDK defaults should work with your - <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host's</ulink> - setup. - However, some cases exist for which you might consider making - adjustments: - <itemizedlist> - <listitem><para> - If your SDK configuration inherits additional classes - using the - <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink> - variable and you do not need or want those classes enabled in - the SDK, you can blacklist them by adding them to the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink> - variable as described in the fourth bullet of the previous - section. - <note> - The default value of - <filename>SDK_INHERIT_BLACKLIST</filename> 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 - "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>" - section of the BitBake User Manual. - </note>. - </para></listitem> - <listitem><para> - 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: - <itemizedlist> - <listitem><para> - After ensuring the tasks are - <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink> - 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 - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS'><filename>SDK_RECRDEP_TASKS</filename></ulink>. - </para></listitem> - <listitem><para> - 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 - <filename>SDK_INHERIT_BLACKLIST</filename> variable - as described in the previous section. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para> - 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 - "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>" - section for information. - </para></listitem> - <listitem><para> - If you want users of the SDK to be able to easily update the - SDK, you need to set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink> - variable. - For more information, see the - "<link linkend='sdk-providing-updates-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</link>" - section. - </para></listitem> - <listitem><para> - If you have adjusted the list of files and directories that - appear in - <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE'><filename>COREBASE</filename></ulink> - (other than layers that are enabled through - <filename>bblayers.conf</filename>), then you must list these - files in - <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES'><filename>COREBASE_FILES</filename></ulink> - so that the files are copied into the SDK. - </para></listitem> - <listitem><para> - If your OpenEmbedded build system setup uses a different - environment setup script other than - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>, - then you must set - <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT'><filename>OE_INIT_ENV_SCRIPT</filename></ulink> - to point to the environment setup script you use. - <note> - You must also reflect this change in the value used for the - <filename>COREBASE_FILES</filename> variable as previously - described. - </note> - </para></listitem> - </itemizedlist> - </para> -</section> - -<section id='sdk-changing-the-sdk-installer-title'> - <title>Changing the Extensible SDK Installer Title</title> - - <para> - You can change the displayed title for the SDK installer by setting - the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink> - variable and then rebuilding the the SDK installer. - For information on how to build an SDK installer, see the - "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" - section. - </para> - - <para> - By default, this title is derived from - <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink> - when it is set. - If the <filename>DISTRO_NAME</filename> variable is not set, the title - is derived from the - <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> - variable. - </para> - - <para> - The - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink> - class defines the default value of the <filename>SDK_TITLE</filename> - variable as follows: - <literallayout class='monospaced'> - SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" - </literallayout> - </para> - - <para> - 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 <filename>SDK_TITLE</filename> variable - in the - <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file - using the following form: - <literallayout class='monospaced'> - SDK_TITLE = "<replaceable>your_title</replaceable>" - </literallayout> - </para> -</section> - -<section id='sdk-providing-updates-to-the-extensible-sdk-after-installation'> - <title>Providing Updates to the Extensible SDK After Installation</title> - - <para> - 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 - <filename>devtool sdk-update</filename> command: - <orderedlist> - <listitem><para> - Create a directory that can be shared over HTTP or HTTPS. - You can do this by setting up a web server such as an - <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink> - or - <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink> - server in the cloud to host the directory. - This directory must contain the published SDK. - </para></listitem> - <listitem><para> - Set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink> - 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 - <filename>devtool sdk-update</filename> command as described - in the - "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>" - section. - </para></listitem> - <listitem><para> - Build the extensible SDK normally (i.e., use the - <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable> - command). - </para></listitem> - <listitem><para> - Publish the SDK using the following command: - <literallayout class='monospaced'> - $ oe-publish-sdk <replaceable>some_path</replaceable>/sdk-installer.sh <replaceable>path_to_shared_http_directory</replaceable> - </literallayout> - You must repeat this step each time you rebuild the SDK - with changes that you want to make available through the - update mechanism. - </para></listitem> - </orderedlist> - </para> - - <para> - Completing the above steps allows users of the existing installed - SDKs to simply run <filename>devtool sdk-update</filename> to - retrieve and apply the latest updates. - See the - "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>" - section for further information. - </para> -</section> - -<section id='sdk-changing-the-default-sdk-installation-directory'> - <title>Changing the Default SDK Installation Directory</title> - - <para> - When you build the installer for the Extensible SDK, the default - installation directory for the SDK is based on the - <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH'><filename>SDKEXTPATH</filename></ulink> - variables from within the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink> - class as follows: - <literallayout class='monospaced'> - SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" - </literallayout> - You can change this default installation directory by specifically - setting the <filename>SDKEXTPATH</filename> variable. - </para> - - <para> - 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 <filename>SDKEXTPATH</filename> variable - in the - <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file - using the following form: - <literallayout class='monospaced'> - SDKEXTPATH = "<replaceable>some_path_for_your_installed_sdk</replaceable>" - </literallayout> - </para> - - <para> - After building your installer, running it prompts the user for - acceptance of the - <replaceable>some_path_for_your_installed_sdk</replaceable> directory - as the default location to install the Extensible SDK. - </para> -</section> - -<section id='sdk-providing-additional-installable-extensible-sdk-content'> - <title>Providing Additional Installable Extensible SDK Content</title> - - <para> - 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: - <orderedlist> - <listitem><para> - Ensure the additional items you want the user to be able to - install are already built: - <itemizedlist> - <listitem><para> - Build the items explicitly. - You could use one or more "meta" recipes that depend - on lists of other recipes. - </para></listitem> - <listitem><para> - Build the "world" target and set - <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable> - for the recipes you do not want built. - See the - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD'><filename>EXCLUDE_FROM_WORLD</filename></ulink> - variable for additional information. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para> - Expose the <filename>sstate-cache</filename> directory - produced by the build. - Typically, you expose this directory by making it available - through an - <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink> - or - <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink> - server. - </para></listitem> - <listitem><para> - Set the appropriate configuration so that the produced SDK - knows how to find the configuration. - The variable you need to set is - <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>: - <literallayout class='monospaced'> - SSTATE_MIRRORS = "file://.* http://<replaceable>example</replaceable>.com/<replaceable>some_path</replaceable>/sstate-cache/PATH" - </literallayout> - You can set the <filename>SSTATE_MIRRORS</filename> variable - in two different places: - <itemizedlist> - <listitem><para> - 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 - <filename>local.conf</filename> or custom distro - configuration file. - You can then "whitelist" the variable through - to the SDK by adding the following: - <literallayout class='monospaced'> - SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS" - </literallayout> - </para></listitem> - <listitem><para> - Alternatively, if you just want to set the - <filename>SSTATE_MIRRORS</filename> variable's value - for the SDK alone, create a - <filename>conf/sdk-extra.conf</filename> file either in - your - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> - or within any layer and put your - <filename>SSTATE_MIRRORS</filename> 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 <filename>SSTATE_MIRRORS</filename>. - </note> - </para></listitem> - </itemizedlist> - </para></listitem> - </orderedlist> - </para> -</section> - -<section id='sdk-minimizing-the-size-of-the-extensible-sdk-installer-download'> - <title>Minimizing the Size of the Extensible SDK Installer Download</title> - - <para> - 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 - <filename>devtool command</filename> by setting the following in your - configuration: - <literallayout class='monospaced'> - SDK_EXT_TYPE = "minimal" - </literallayout> - Setting - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> - 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 <filename>devtool</filename> or - explicitly with the <filename>devtool sdk-install</filename> command. - </para> - - <para> - 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 <filename>devtool add</filename> is able to effectively map - dependencies it discovers in a source tree to the appropriate recipes. - Additionally, the information enables the - <filename>devtool search</filename> command to return useful results. - </para> - - <para> - To facilitate this wider range of information, you would need to - set the following: - <literallayout class='monospaced'> - SDK_INCLUDE_PKGDATA = "1" - </literallayout> - See the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink> - variable for additional information. - </para> - - <para> - Setting the <filename>SDK_INCLUDE_PKGDATA</filename> 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. - </para> - - <para> - You can use - <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable> - 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 <filename>SDK_EXT_TYPE</filename> to "minimal", - then providing a shared state mirror is mandatory so that items - can be installed as needed. - See the - "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>" - section for more information. - </note> - </para> - - <para> - You can explicitly control whether or not to include the toolchain - when you build an SDK by setting the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> - variable to "1". - In particular, it is useful to include the toolchain when you - have set <filename>SDK_EXT_TYPE</filename> 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. - </para> -</section> -</appendix> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml deleted file mode 100644 index 86b6d7dd07..0000000000 --- a/documentation/sdk-manual/sdk-appendix-obtain.xml +++ /dev/null @@ -1,443 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > - -<appendix id='sdk-appendix-obtain'> - -<title>Obtaining the SDK</title> - -<section id='sdk-locating-pre-built-sdk-installers'> - <title>Locating Pre-Built SDK Installers</title> - - <para> - 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. - </para> - - <para> - Follow these steps to locate and hand-install the toolchain: - <orderedlist> - <listitem><para> - <emphasis>Go to the Installers Directory:</emphasis> - Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink> - </para></listitem> - <listitem><para> - <emphasis>Open the Folder for Your Build Host:</emphasis> - Open the folder that matches your - <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>build host</ulink> - (i.e. <filename>i686</filename> for 32-bit machines or - <filename>x86_64</filename> for 64-bit machines). - </para></listitem> - <listitem><para> - <emphasis>Locate and Download the SDK Installer:</emphasis> - You need to find and download the installer appropriate for - your build host, target hardware, and image type. - </para> - - <para>The installer files (<filename>*.sh</filename>) follow - this naming convention: - <literallayout class='monospaced'> - poky-glibc-<replaceable>host_system</replaceable>-core-image-<replaceable>type</replaceable>-<replaceable>arch</replaceable>-toolchain[-ext]-<replaceable>release</replaceable>.sh - - Where: - <replaceable>host_system</replaceable> is a string representing your development system: - "i686" or "x86_64" - - <replaceable>type</replaceable> is a string representing the image: - "sato" or "minimal" - - <replaceable>arch</replaceable> is a string representing the target architecture: - "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2", - "mips64", or "ppc7400" - - <replaceable>release</replaceable> is the version of Yocto Project. - - NOTE: - The standard SDK installer does not have the "-ext" string as - part of the filename. - - </literallayout> - The toolchains provided by the Yocto Project are based off of - the <filename>core-image-sato</filename> and - <filename>core-image-minimal</filename> images and contain - libraries appropriate for developing against those images. - </para> - - <para>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 <filename>x86_64</filename> folder and download the - following installer: - <literallayout class='monospaced'> - poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Run the Installer:</emphasis> - Be sure you have execution privileges and run the installer. - Following is an example from the <filename>Downloads</filename> - directory: - <literallayout class='monospaced'> - $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh - </literallayout> - During execution of the script, you choose the root location - for the toolchain. - See the - "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" - section and the - "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>" - section for more information. - </para></listitem> - </orderedlist> - </para> -</section> - -<section id='sdk-building-an-sdk-installer'> - <title>Building an SDK Installer</title> - - <para> - As an alternative to locating and downloading an SDK installer, - you can build the SDK installer. - Follow these steps: - <orderedlist> - <listitem><para> - <emphasis>Set Up the Build Environment:</emphasis> - Be sure you are set up to use BitBake in a shell. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>" - 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. - </para></listitem> - <listitem><para> - <emphasis>Clone the <filename>poky</filename> Repository:</emphasis> - You need to have a local copy of the Yocto Project - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> - (i.e. a local <filename>poky</filename> repository). - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>" - and possibly the - "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>" - and - "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>" - sections all in the Yocto Project Development Tasks Manual for - information on how to clone the <filename>poky</filename> - repository and check out the appropriate branch for your work. - </para></listitem> - <listitem><para> - <emphasis>Initialize the Build Environment:</emphasis> - While in the root directory of the Source Directory (i.e. - <filename>poky</filename>), run the - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - environment setup script to define the OpenEmbedded - build environment on your build host. - <literallayout class='monospaced'> - $ source &OE_INIT_FILE; - </literallayout> - Among other things, the script creates the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, - which is <filename>build</filename> in this case - and is located in the Source Directory. - After the script runs, your current working directory - is set to the <filename>build</filename> directory. - </para></listitem> - <listitem><para> - <emphasis>Make Sure You Are Building an Installer for the Correct Machine:</emphasis> - Check to be sure that your - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable in the <filename>local.conf</filename> file in your - Build Directory matches the architecture for which you are - building. - </para></listitem> - <listitem><para> - <emphasis>Make Sure Your SDK Machine is Correctly Set:</emphasis> - 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 - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink> - variable in the <filename>local.conf</filename> file in your - Build Directory is correctly set. - <note> - If you are building an SDK installer for the Extensible - SDK, the <filename>SDKMACHINE</filename> value must be - set for the architecture of the machine you are using to - build the installer. - If <filename>SDKMACHINE</filename> is not set appropriately, - the build fails and provides an error message similar to - the following: - <literallayout class='monospaced'> - 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. - </literallayout> - </note> - </para></listitem> - <listitem><para> - <emphasis>Build the SDK Installer:</emphasis> - To build the SDK installer for a standard SDK and populate - the SDK image, use the following command form. - Be sure to replace <replaceable>image</replaceable> with - an image (e.g. "core-image-sato"): - <literallayout class='monospaced'> - $ bitbake <replaceable>image</replaceable> -c populate_sdk - </literallayout> - You can do the same for the extensible SDK using this command - form: - <literallayout class='monospaced'> - $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext - </literallayout> - These commands produce an SDK installer that contains the - sysroot that matches your target root filesystem.</para> - - <para>When the <filename>bitbake</filename> command completes, - the SDK installer will be in - <filename>tmp/deploy/sdk</filename> in the Build Directory. - <note><title>Notes</title> - <itemizedlist> - <listitem><para> - 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 - <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink> - variable inside your <filename>local.conf</filename> - 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 - <filename>libc</filename> static development - libraries: - <literallayout class='monospaced'> - TOOLCHAIN_TARGET_TASK_append = " libc-staticdev" - </literallayout> - </para></listitem> - </itemizedlist> - </note> - </para></listitem> - <listitem><para> - <emphasis>Run the Installer:</emphasis> - You can now run the SDK installer from - <filename>tmp/deploy/sdk</filename> in the Build Directory. - Following is an example: - <literallayout class='monospaced'> - $ cd ~/poky/build/tmp/deploy/sdk - $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh - </literallayout> - During execution of the script, you choose the root location - for the toolchain. - See the - "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" - section and the - "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>" - section for more information. - </para></listitem> - </orderedlist> - </para> -</section> - -<section id='sdk-extracting-the-root-filesystem'> - <title>Extracting the Root Filesystem</title> - - <para> - After installing the toolchain, for some use cases you - might need to separately extract a root filesystem: - <itemizedlist> - <listitem><para> - You want to boot the image using NFS. - </para></listitem> - <listitem><para> - You want to use the root filesystem as the - target sysroot. - </para></listitem> - <listitem><para> - You want to develop your target application - using the root filesystem as the target sysroot. - </para></listitem> - </itemizedlist> - </para> - - <para> - Follow these steps to extract the root filesystem: - <orderedlist> - <listitem><para> - <emphasis>Locate and Download the Tarball for the Pre-Built - Root Filesystem Image File:</emphasis> - 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 - <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/machines/'>Index of Releases</ulink> - in the "machines" directory.</para> - - <para>The machine-specific folders of the "machines" directory - contain tarballs (<filename>*.tar.bz2</filename>) for supported - machines. - These directories also contain flattened root filesystem - image files (<filename>*.ext4</filename>), which you can use - with QEMU directly.</para> - - <para>The pre-built root filesystem image files - follow these naming conventions: - <literallayout class='monospaced'> -<!-- - core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>-<replaceable>date_time</replaceable>.rootfs.tar.bz2 ---> - core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>.tar.bz2 - - Where: - <replaceable>profile</replaceable> 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 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in - the Yocto Project Reference Manual. - - <replaceable>arch</replaceable> 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*. - -<!--> - <replaceable>date_time</replaceable> is a date and time stamp. ---> - - </literallayout> - The root filesystems provided by the Yocto Project are based - off of the <filename>core-image-sato</filename> and - <filename>core-image-minimal</filename> images. - </para> - - <para>For example, if you plan on using a BeagleBone device - as your target hardware and your image is a - <filename>core-image-sato-sdk</filename> - image, you can download the following file: - <literallayout class='monospaced'> - core-image-sato-sdk-beaglebone-yocto.tar.bz2 - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Initialize the Cross-Development Environment:</emphasis> - You must <filename>source</filename> the cross-development - environment setup script to establish necessary environment - variables.</para> - - <para>This script is located in the top-level directory in - which you installed the toolchain (e.g. - <filename>poky_sdk</filename>).</para> - - <para>Following is an example based on the toolchain installed - in the - "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>" - section: - <literallayout class='monospaced'> - $ source ~/poky_sdk/environment-setup-core2-64-poky-linux - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Extract the Root Filesystem:</emphasis> - Use the <filename>runqemu-extract-sdk</filename> command - and provide the root filesystem image.</para> - - <para>Following is an example command that extracts the root - filesystem from a previously built root filesystem image that - was downloaded from the - <ulink url='&YOCTO_DOCS_OM_URL;#index-downloads'>Index of Releases</ulink>. - This command extracts the root filesystem into the - <filename>core2-64-sato</filename> directory: - <literallayout class='monospaced'> - $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato - </literallayout> - You could now point to the target sysroot at - <filename>beablebone-sato</filename>. - </para></listitem> - </orderedlist> - </para> -</section> - -<section id='sdk-installed-standard-sdk-directory-structure'> - <title>Installed Standard SDK Directory Structure</title> - - <para> - The following figure shows the resulting directory structure after - you install the Standard SDK by running the <filename>*.sh</filename> - SDK installation script: - </para> - - <para> - <imagedata fileref="figures/sdk-installed-standard-sdk-directory.png" scale="80" align="center" /> - </para> - - <para> - 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 (<filename>sysroots</filename>) needed to - develop objects for the target system. - </para> - - <para> - Within the figure, italicized text is used to indicate replaceable - portions of the file or directory name. - For example, - <replaceable>install_dir</replaceable>/<replaceable>version</replaceable> - is the directory where the SDK is installed. - By default, this directory is <filename>/opt/poky/</filename>. - And, <replaceable>version</replaceable> represents the specific - snapshot of the SDK (e.g. <filename>&DISTRO;</filename>). - Furthermore, <replaceable>target</replaceable> represents the target - architecture (e.g. <filename>i586</filename>) and - <replaceable>host</replaceable> represents the development system's - architecture (e.g. <filename>x86_64</filename>). - Thus, the complete names of the two directories within the - <filename>sysroots</filename> could be - <filename>i586-poky-linux</filename> and - <filename>x86_64-pokysdk-linux</filename> for the target and host, - respectively. - </para> -</section> - -<section id='sdk-installed-extensible-sdk-directory-structure'> - <title>Installed Extensible SDK Directory Structure</title> - - <para> - The following figure shows the resulting directory structure after - you install the Extensible SDK by running the <filename>*.sh</filename> - SDK installation script: - </para> - - <para> - <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="80" align="center" /> - </para> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <para> - Within the figure, italicized text is used to indicate replaceable - portions of the file or directory name. - For example, - <replaceable>install_dir</replaceable> is the directory where the SDK - is installed, which is <filename>poky_sdk</filename> by default, and - <replaceable>target</replaceable> represents the target - architecture (e.g. <filename>i586</filename>). - </para> -</section> - -</appendix> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml deleted file mode 100644 index 94d2a241fe..0000000000 --- a/documentation/sdk-manual/sdk-extensible.xml +++ /dev/null @@ -1,1846 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > - -<chapter id='sdk-extensible'> - - <title>Using the Extensible SDK</title> - - <para> - 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 <filename>devtool</filename> - 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 - <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>. - <note> - For a side-by-side comparison of main features supported for an - extensible SDK as compared to a standard SDK, see the - "<link linkend='sdk-manual-intro'>Introduction</link>" - section. - </note> - </para> - - <para> - In addition to the functionality available through - <filename>devtool</filename>, you can alternatively make use of the - toolchain directly, for example from Makefile and Autotools. - See the - "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>" - chapter for more information. - </para> - - <section id='sdk-extensible-sdk-intro'> - <title>Why use the Extensible SDK and What is in It?</title> - - <para> - 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 <filename>devtool</filename> - commands tailored for the Yocto Project environment. - </para> - - <para> - 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 - <filename>devtool</filename> functionality. - </para> - </section> - - <section id='sdk-installing-the-extensible-sdk'> - <title>Installing the Extensible SDK</title> - - <para> - The first thing you need to do is install the SDK on your - <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink> - by running the <filename>*.sh</filename> installation script. - </para> - - <para> - You can download a tarball installer, which includes the - pre-built toolchain, the <filename>runqemu</filename> - script, the internal build system, <filename>devtool</filename>, - and support files from the appropriate - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink> - directory within the Index of Releases. - Toolchains are available for several 32-bit and 64-bit - architectures with the <filename>x86_64</filename> directories, - respectively. - The toolchains the Yocto Project provides are based off the - <filename>core-image-sato</filename> and - <filename>core-image-minimal</filename> images and contain - libraries appropriate for developing against that image. - </para> - - <para> - 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: - <literallayout class='monospaced'> - poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh - - Where: - <replaceable>host_system</replaceable> is a string representing your development system: - - i686 or x86_64. - - <replaceable>image_type</replaceable> is the image for which the SDK was built: - - core-image-sato or core-image-minimal - - <replaceable>arch</replaceable> is a string representing the tuned target architecture: - - aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon - - <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project: - - &DISTRO;, &DISTRO;+snapshot - </literallayout> - 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 <filename>core-image-sato</filename> and - using the current &DISTRO; snapshot: - <literallayout class='monospaced'> - poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh - </literallayout> - <note> - As an alternative to downloading an SDK, you can build the - SDK installer. - For information on building the installer, see the - "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" - section. - </note> - </para> - - <para> - The SDK and toolchains are self-contained and by default are - installed into the <filename>poky_sdk</filename> 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. - </para> - - <para> - 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 - <filename>~/Downloads/</filename> 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. - </note> - <literallayout class='monospaced'> - $ ./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 - - </literallayout> - </para> - </section> - - <section id='sdk-running-the-extensible-sdk-environment-setup-script'> - <title>Running the Extensible SDK Environment Setup Script</title> - - <para> - 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 - <filename>poky_sdk</filename> directory or the directory you - chose during installation. - </para> - - <para> - 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 - "<filename>environment-setup</filename>" 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: - <literallayout class='monospaced'> - $ 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. - </literallayout> - Running the setup script defines many environment variables needed - in order to use the SDK (e.g. <filename>PATH</filename>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>, - and so forth). - If you want to see all the environment variables the script - exports, examine the installation file itself. - </para> - </section> - - <section id='using-devtool-in-your-sdk-workflow'> - <title>Using <filename>devtool</filename> in Your SDK Workflow</title> - - <para> - The cornerstone of the extensible SDK is a command-line tool - called <filename>devtool</filename>. - 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><title>Tip</title> - The use of <filename>devtool</filename> is not limited to - the extensible SDK. - You can use <filename>devtool</filename> to help you easily - develop any project whose build output must be part of an - image built using the build system. - </note> - </para> - - <para> - The <filename>devtool</filename> command line is organized - similarly to - <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> in that it - has a number of sub-commands for each function. - You can run <filename>devtool --help</filename> to see all the - commands. - <note> - See the - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename> Quick Reference</ulink>" - in the Yocto Project Reference Manual for a - <filename>devtool</filename> quick reference. - </note> - </para> - - <para> - Three <filename>devtool</filename> subcommands exist that provide - entry-points into development: - <itemizedlist> - <listitem><para> - <emphasis><filename>devtool add</filename></emphasis>: - Assists in adding new software to be built. - </para></listitem> - <listitem><para> - <emphasis><filename>devtool modify</filename></emphasis>: - Sets up an environment to enable you to modify the source of - an existing component. - </para></listitem> - <listitem><para> - <emphasis><filename>devtool upgrade</filename></emphasis>: - Updates an existing recipe so that you can build it for - an updated set of source files. - </para></listitem> - </itemizedlist> - As with the build system, "recipes" represent software packages - within <filename>devtool</filename>. - When you use <filename>devtool add</filename>, a recipe is - automatically created. - When you use <filename>devtool modify</filename>, 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. - </para> - - <para> - The remainder of this section presents the - <filename>devtool add</filename>, - <filename>devtool modify</filename>, and - <filename>devtool upgrade</filename> workflows. - </para> - - <section id='sdk-use-devtool-to-add-an-application'> - <title>Use <filename>devtool add</filename> to Add an Application</title> - - <para> - The <filename>devtool add</filename> command generates - a new recipe based on existing source code. - This command takes advantage of the - <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink> - layer that many <filename>devtool</filename> 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. - </para> - - <para> - Depending on your particular scenario, the arguments and options - you use with <filename>devtool add</filename> form different - combinations. - The following diagram shows common development flows - you would use with the <filename>devtool add</filename> - command: - </para> - - <para> - <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" /> - </para> - - <para> - <orderedlist> - <listitem><para><emphasis>Generating the New Recipe</emphasis>: - The top part of the flow shows three scenarios by which - you could use <filename>devtool add</filename> to - generate a recipe based on existing source code.</para> - - <para>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.</para> - - <para>Within the diagram, three possible scenarios - feed into the <filename>devtool add</filename> workflow: - <itemizedlist> - <listitem><para> - <emphasis>Left</emphasis>: - 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: - <literallayout class='monospaced'> - $ devtool add <replaceable>recipe fetchuri</replaceable> - </literallayout> - With this command, <filename>devtool</filename> - extracts the upstream source files into a local - Git repository within the - <filename>sources</filename> folder. - The command then creates a recipe named - <replaceable>recipe</replaceable> and a - corresponding append file in the workspace. - If you do not provide - <replaceable>recipe</replaceable>, the command - makes an attempt to determine the recipe name. - </para></listitem> - <listitem><para> - <emphasis>Middle</emphasis>: - 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, <filename>devtool</filename> - always creates - a Git repository locally during the - extraction. - </note> - Furthermore, the first positional argument - <replaceable>srctree</replaceable> in this - case identifies where the - <filename>devtool add</filename> command - will locate the extracted code outside of the - workspace. - You need to specify an empty directory: - <literallayout class='monospaced'> - $ devtool add <replaceable>recipe srctree fetchuri</replaceable> - </literallayout> - In summary, the source code is pulled from - <replaceable>fetchuri</replaceable> and - extracted into the location defined by - <replaceable>srctree</replaceable> as a local - Git repository.</para> - - <para>Within workspace, - <filename>devtool</filename> creates a - recipe named <replaceable>recipe</replaceable> - along with an associated append file. - </para></listitem> - <listitem><para> - <emphasis>Right</emphasis>: - The right scenario in the figure represents a - situation where the - <replaceable>srctree</replaceable> has been - previously prepared outside of the - <filename>devtool</filename> workspace.</para> - - <para>The following command provides a new - recipe name and identifies the existing source - tree location: - <literallayout class='monospaced'> - $ devtool add <replaceable>recipe srctree</replaceable> - </literallayout> - The command examines the source code and - creates a recipe named - <replaceable>recipe</replaceable> for the code - and places the recipe into the workspace. - </para> - - <para>Because the extracted source code already - exists, <filename>devtool</filename> does not - try to relocate the source code into the - workspace - only the new recipe is placed - in the workspace.</para> - - <para>Aside from a recipe folder, the command - also creates an associated append folder and - places an initial - <filename>*.bbappend</filename> file within. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para> - <emphasis>Edit the Recipe</emphasis>: - You can use <filename>devtool edit-recipe</filename> - to open up the editor as defined by the - <filename>$EDITOR</filename> environment variable - and modify the file: - <literallayout class='monospaced'> - $ devtool edit-recipe <replaceable>recipe</replaceable> - </literallayout> - From within the editor, you can make modifications to - the recipe that take affect when you build it later. - </para></listitem> - <listitem><para> - <emphasis>Build the Recipe or Rebuild the Image</emphasis>: - The next step you take depends on what you are going - to do with the new code.</para> - - <para>If you need to eventually move the build output - to the target hardware, use the following - <filename>devtool</filename> command: - <literallayout class='monospaced'> - $ devtool build <replaceable>recipe</replaceable> - </literallayout></para> - - <para>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 <filename>devtool build-image</filename> command: - <literallayout class='monospaced'> - $ devtool build-image <replaceable>image</replaceable> - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Deploy the Build Output</emphasis>: - When you use the <filename>devtool build</filename> - 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. - </note> - You can deploy your build output to that target - hardware by using the - <filename>devtool deploy-target</filename> command: - <literallayout class='monospaced'> - $ devtool deploy-target <replaceable>recipe target</replaceable> - </literallayout> - The <replaceable>target</replaceable> is a live target - machine running as an SSH server.</para> - - <para>You can, of course, also deploy the image you - build to actual hardware by using the - <filename>devtool build-image</filename> command. - However, <filename>devtool</filename> does not provide - a specific command that allows you to deploy the - image to actual hardware. - </para></listitem> - <listitem><para> - <emphasis>Finish Your Work With the Recipe</emphasis>: - The <filename>devtool finish</filename> 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. - <literallayout class='monospaced'> - $ devtool finish <replaceable>recipe layer</replaceable> - </literallayout> - <note> - Any changes you want to turn into patches must be - committed to the Git repository in the source tree. - </note></para> - - <para>As mentioned, the - <filename>devtool finish</filename> command moves the - final recipe to its permanent layer. - </para> - - <para>As a final process of the - <filename>devtool finish</filename> 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 <filename>devtool reset</filename> - 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. - </note> - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'> - <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title> - - <para> - The <filename>devtool modify</filename> 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. - </para> - - <para> - Depending on your particular scenario, the arguments and options - you use with <filename>devtool modify</filename> form different - combinations. - The following diagram shows common development flows for the - <filename>devtool modify</filename> command: - </para> - - <para> - <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" /> - </para> - - <para> - <orderedlist> - <listitem><para> - <emphasis>Preparing to Modify the Code</emphasis>: - The top part of the flow shows three scenarios by which - you could use <filename>devtool modify</filename> to - prepare to work on source files. - Each scenario assumes the following: - <itemizedlist> - <listitem><para> - The recipe exists locally in a layer external - to the <filename>devtool</filename> workspace. - </para></listitem> - <listitem><para> - The source files exist either upstream in an - un-extracted state or locally in a previously - extracted state. - </para></listitem> - </itemizedlist> - 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. - <itemizedlist> - <listitem><para> - <emphasis>Left</emphasis>: - 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 <filename>devtool</filename> - workspace location. - The recipe, in this scenario, is in its own - layer outside the workspace - (i.e. - <filename>meta-</filename><replaceable>layername</replaceable>). - </para> - - <para>The following command identifies the - recipe and, by default, extracts the source - files: - <literallayout class='monospaced'> - $ devtool modify <replaceable>recipe</replaceable> - </literallayout> - Once <filename>devtool</filename>locates the - recipe, <filename>devtool</filename> uses the - recipe's - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statements to locate the source code and any - local patch files from other developers.</para> - - <para>With this scenario, no - <replaceable>srctree</replaceable> argument - exists. - Consequently, the default behavior of the - <filename>devtool modify</filename> command is - to extract the source files pointed to by the - <filename>SRC_URI</filename> statements into a - local Git structure. - Furthermore, the location for the extracted - source is the default area within the - <filename>devtool</filename> 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.</para> - - <para>Additionally, if you have any non-patch - local files (i.e. files referred to with - <filename>file://</filename> entries in - <filename>SRC_URI</filename> statement excluding - <filename>*.patch/</filename> or - <filename>*.diff</filename>), these files are - copied to an - <filename>oe-local-files</filename> 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. - </para></listitem> - <listitem><para> - <emphasis>Middle</emphasis>: - 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. - </para> - - <para>The following command tells - <filename>devtool</filename> 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 - <filename>devtool</filename> workspace: - <literallayout class='monospaced'> - $ devtool modify <replaceable>recipe srctree</replaceable> - </literallayout> - <note> - You cannot provide a URL for - <replaceable>srctree</replaceable> using - the <filename>devtool</filename> command. - </note> - As with all extractions, the command uses - the recipe's <filename>SRC_URI</filename> - statements to locate the source files and any - associated patch files. - Non-patch files are copied to an - <filename>oe-local-files</filename> folder - under the newly created source tree.</para> - - <para>Once the files are located, the command - by default extracts them into - <replaceable>srctree</replaceable>.</para> - - <para>Within workspace, - <filename>devtool</filename> 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 - <replaceable>srctree</replaceable>. - </para></listitem> - <listitem><para> - <emphasis>Right</emphasis>: - The right scenario in the figure represents a - situation where the source tree - (<replaceable>srctree</replaceable>) already - exists locally as a previously extracted Git - structure outside of the - <filename>devtool</filename> workspace. - In this example, the recipe also exists - elsewhere locally in its own layer. - </para> - - <para>The following command tells - <filename>devtool</filename> the recipe - with which to work, uses the "-n" option to - indicate source does not need to be extracted, - and uses <replaceable>srctree</replaceable> to - point to the previously extracted source files: - <literallayout class='monospaced'> - $ devtool modify -n <replaceable>recipe srctree</replaceable> - </literallayout> - </para> - - <para>If an <filename>oe-local-files</filename> - 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 <filename>devtool finish</filename> - command, any non-patch files that might exist - next to the recipe are removed because it - appears to <filename>devtool</filename> that - you have deleted those files.</para> - - <para>Once the - <filename>devtool modify</filename> command - finishes, it creates only an append file for - the recipe in the <filename>devtool</filename> - workspace. - The recipe and the source code remain in their - original locations. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para> - <emphasis>Edit the Source</emphasis>: - Once you have used the - <filename>devtool modify</filename> 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. - </para></listitem> - <listitem><para> - <emphasis>Build the Recipe or Rebuild the Image</emphasis>: - The next step you take depends on what you are going - to do with the new code.</para> - - <para>If you need to eventually move the build output - to the target hardware, use the following - <filename>devtool</filename> command: - <literallayout class='monospaced'> - $ devtool build <replaceable>recipe</replaceable> - </literallayout></para> - - <para>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 <filename>devtool build-image</filename> command: - <literallayout class='monospaced'> - $ devtool build-image <replaceable>image</replaceable> - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Deploy the Build Output</emphasis>: - When you use the <filename>devtool build</filename> - 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. - </note> - You can deploy your build output to that target - hardware by using the - <filename>devtool deploy-target</filename> command: - <literallayout class='monospaced'> - $ devtool deploy-target <replaceable>recipe target</replaceable> - </literallayout> - The <replaceable>target</replaceable> is a live target - machine running as an SSH server.</para> - - <para>You can, of course, use other methods to deploy - the image you built using the - <filename>devtool build-image</filename> command to - actual hardware. - <filename>devtool</filename> does not provide - a specific command to deploy the image to actual - hardware. - </para></listitem> - <listitem><para> - <emphasis>Finish Your Work With the Recipe</emphasis>: - The <filename>devtool finish</filename> command creates - any patches corresponding to commits in the local - Git repository, updates the recipe to point to them - (or creates a <filename>.bbappend</filename> 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. - <literallayout class='monospaced'> - $ devtool finish <replaceable>recipe layer</replaceable> - </literallayout> - <note> - Any changes you want to turn into patches must be - staged and committed within the local Git - repository before you use the - <filename>devtool finish</filename> command. - </note></para> - - <para>Because there is no need to move the recipe, - <filename>devtool finish</filename> either updates the - original recipe in the original layer or the command - creates a <filename>.bbappend</filename> file in a - different layer as provided by - <replaceable>layer</replaceable>. - Any work you did in the - <filename>oe-local-files</filename> directory is - preserved in the original files next to the recipe - during the <filename>devtool finish</filename> - command.</para> - - <para>As a final process of the - <filename>devtool finish</filename> 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 <filename>devtool reset</filename> - 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. - </note> - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'> - <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title> - - <para> - The <filename>devtool upgrade</filename> 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 <filename>devtool upgrade</filename> - 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 - - <filename>devtool upgrade</filename> happens to be one. - You can read about all the methods by which you can - upgrade recipes in the - "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>" - section of the Yocto Project Development Tasks Manual. - </note> - </para> - - <para> - The <filename>devtool upgrade</filename> command is flexible - enough to allow you to specify source code revision and - versioning schemes, extract code into or out of the - <filename>devtool</filename> - <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>, - and work with any source file forms that the - <ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>fetchers</ulink> - support. - </para> - - <para> - The following diagram shows the common development flow - used with the <filename>devtool upgrade</filename> command: - </para> - - <para> - <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" /> - </para> - - <para> - <orderedlist> - <listitem><para> - <emphasis>Initiate the Upgrade</emphasis>: - The top part of the flow shows the typical scenario by - which you use the <filename>devtool upgrade</filename> - command. - The following conditions exist: - <itemizedlist> - <listitem><para> - The recipe exists in a local layer external - to the <filename>devtool</filename> workspace. - </para></listitem> - <listitem><para> - The source files for the new release - exist in the same location pointed to by - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - 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). - </para></listitem> - </itemizedlist> - 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: - <literallayout class='monospaced'> - $ devtool upgrade -V <replaceable>version recipe</replaceable> - </literallayout> - By default, the <filename>devtool upgrade</filename> - command extracts source code into the - <filename>sources</filename> directory in the - <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>. - If you want the code extracted to any other location, - you need to provide the - <replaceable>srctree</replaceable> positional argument - with the command as follows: - <literallayout class='monospaced'> - $ devtool upgrade -V <replaceable>version recipe srctree</replaceable> - </literallayout> - <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. - </note> - If the source files pointed to by the - <filename>SRC_URI</filename> statement in the recipe - are in a Git repository, you must provide the "-S" - option and specify a revision for the software.</para> - - <para>Once <filename>devtool</filename> locates the - recipe, it uses the <filename>SRC_URI</filename> - 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.</para> - - <para>Additionally, if you have any non-patch - local files (i.e. files referred to with - <filename>file://</filename> entries in - <filename>SRC_URI</filename> statement excluding - <filename>*.patch/</filename> or - <filename>*.diff</filename>), these files are - copied to an - <filename>oe-local-files</filename> 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. - </para></listitem> - <listitem><para> - <emphasis>Resolve any Conflicts created by the Upgrade</emphasis>: - Conflicts could exist due to the software being - upgraded to a new version. - Conflicts occur if your recipe specifies some patch - files in <filename>SRC_URI</filename> 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 - <filename>git rebase</filename> conflict resolution - process.</para> - - <para>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. - </para></listitem> - <listitem><para> - <emphasis>Build the Recipe or Rebuild the Image</emphasis>: - The next step you take depends on what you are going - to do with the new code.</para> - - <para>If you need to eventually move the build output - to the target hardware, use the following - <filename>devtool</filename> command: - <literallayout class='monospaced'> - $ devtool build <replaceable>recipe</replaceable> - </literallayout></para> - - <para>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 <filename>devtool build-image</filename> command: - <literallayout class='monospaced'> - $ devtool build-image <replaceable>image</replaceable> - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Deploy the Build Output</emphasis>: - When you use the <filename>devtool build</filename> - command or <filename>bitbake</filename> 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. - </note> - You can deploy your build output to that target - hardware by using the - <filename>devtool deploy-target</filename> command: - <literallayout class='monospaced'> - $ devtool deploy-target <replaceable>recipe target</replaceable> - </literallayout> - The <replaceable>target</replaceable> is a live target - machine running as an SSH server.</para> - - <para>You can, of course, also deploy the image you - build using the - <filename>devtool build-image</filename> command - to actual hardware. - However, <filename>devtool</filename> does not provide - a specific command that allows you to do this. - </para></listitem> - <listitem><para> - <emphasis>Finish Your Work With the Recipe</emphasis>: - The <filename>devtool finish</filename> 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.</para> - - <para>Any work you did in the - <filename>oe-local-files</filename> directory is - preserved in the original files next to the recipe - during the <filename>devtool finish</filename> - command.</para> - - <para> - 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. - <literallayout class='monospaced'> - $ devtool finish <replaceable>recipe layer</replaceable> - </literallayout> - <note> - Any changes you want to turn into patches must be - committed to the Git repository in the source tree. - </note></para> - - <para>As a final process of the - <filename>devtool finish</filename> 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 <filename>devtool reset</filename> - 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. - </note> - </para></listitem> - </orderedlist> - </para> - </section> - </section> - - <section id='sdk-a-closer-look-at-devtool-add'> - <title>A Closer Look at <filename>devtool add</filename></title> - - <para> - The <filename>devtool add</filename> command automatically creates - a recipe based on the source tree you provide with the command. - Currently, the command has support for the following: - <itemizedlist> - <listitem><para> - Autotools (<filename>autoconf</filename> and - <filename>automake</filename>) - </para></listitem> - <listitem><para> - CMake - </para></listitem> - <listitem><para> - Scons - </para></listitem> - <listitem><para> - <filename>qmake</filename> - </para></listitem> - <listitem><para> - Plain <filename>Makefile</filename> - </para></listitem> - <listitem><para> - Out-of-tree kernel module - </para></listitem> - <listitem><para> - Binary package (i.e. "-b" option) - </para></listitem> - <listitem><para> - Node.js module - </para></listitem> - <listitem><para> - Python modules that use <filename>setuptools</filename> - or <filename>distutils</filename> - </para></listitem> - </itemizedlist> - </para> - - <para> - 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 <filename>CMakeLists.txt</filename> 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. - </note> - </para> - - <para> - The remainder of this section covers specifics regarding how parts - of the recipe are generated. - </para> - - <section id='sdk-name-and-version'> - <title>Name and Version</title> - - <para> - If you do not specify a name and version on the command - line, <filename>devtool add</filename> 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, <filename>devtool</filename> - sets the name of the created recipe file accordingly. - </para> - - <para> - If <filename>devtool</filename> 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. - </para> - - <para> - Sometimes the name or version determined from the source tree - might be incorrect. - For such a case, you must reset the recipe: - <literallayout class='monospaced'> - $ devtool reset -n <replaceable>recipename</replaceable> - </literallayout> - After running the <filename>devtool reset</filename> command, - you need to run <filename>devtool add</filename> again and - provide the name or the version. - </para> - </section> - - <section id='sdk-dependency-detection-and-mapping'> - <title>Dependency Detection and Mapping</title> - - <para> - The <filename>devtool add</filename> 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 - <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> - variable within the recipe. - If a dependency cannot be mapped, <filename>devtool</filename> - 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 <filename>devtool add</filename> command to add an - additional recipe that satisfies the dependency. - Once you add that recipe, you need to update the - <filename>DEPENDS</filename> variable in the original recipe - to include the new recipe. - </para> - - <para> - If you need to add runtime dependencies, you can do so by - adding the following to your recipe: - <literallayout class='monospaced'> - RDEPENDS_${PN} += "<replaceable>dependency1 dependency2 ...</replaceable>" - </literallayout> - <note> - The <filename>devtool add</filename> 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. - </note> - </para> - </section> - - <section id='sdk-license-detection'> - <title>License Detection</title> - - <para> - The <filename>devtool add</filename> 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 - <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> - 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 - <filename>LICENSE</filename> value. - </para> - - <para> - The <filename>devtool add</filename> command also sets the - <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> - 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 - <filename>LIC_FILES_CHKSUM</filename> variable to point to one - or more of those comments if present. - Setting <filename>LIC_FILES_CHKSUM</filename> 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. - </para> - - <para> - If the <filename>devtool add</filename> command cannot - determine licensing information, <filename>devtool</filename> - sets the <filename>LICENSE</filename> value to "CLOSED" and - leaves the <filename>LIC_FILES_CHKSUM</filename> 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. - </para> - </section> - - <section id='sdk-adding-makefile-only-software'> - <title>Adding Makefile-Only Software</title> - - <para> - 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, <filename>devtool add</filename> often cannot do very - much to ensure that these Makefiles build correctly. - It is very common, for example, to explicitly call - <filename>gcc</filename> instead of using the - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - variable. - Usually, in a cross-compilation environment, - <filename>gcc</filename> is the compiler for the build host - and the cross-compiler is named something similar to - <filename>arm-poky-linux-gnueabi-gcc</filename> and might - require arguments (e.g. to point to the associated sysroot - for the target machine). - </para> - - <para> - When writing a recipe for Makefile-only software, keep the - following in mind: - <itemizedlist> - <listitem><para> - You probably need to patch the Makefile to use - variables instead of hardcoding tools within the - toolchain such as <filename>gcc</filename> and - <filename>g++</filename>. - </para></listitem> - <listitem><para> - The environment in which Make runs is set up with - various standard variables for compilation (e.g. - <filename>CC</filename>, <filename>CXX</filename>, 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 - <filename>devtool build</filename> command on the - recipe and then look in - <filename>oe-logs/run.do_compile</filename>. - 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. - </para></listitem> - <listitem><para> - 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 - <filename>make</filename> command line. - To force the value on the command line, add the - variable setting to - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> - within the recipe. - Here is an example using <filename>EXTRA_OEMAKE</filename>: - <literallayout class='monospaced'> - EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" - </literallayout> - 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. - </para></listitem> - <listitem><para> - 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. - </para></listitem> - <listitem><para> - Sometimes a Makefile runs target-specific commands such - as <filename>ldconfig</filename>. - For such cases, you might be able to apply patches that - remove these commands from the Makefile. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='sdk-adding-native-tools'> - <title>Adding Native Tools</title> - - <para> - Often, you need to build additional tools that run on the - <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink> - as opposed to the target. - You should indicate this requirement by using one of the - following methods when you run - <filename>devtool add</filename>: - <itemizedlist> - <listitem><para> - 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. - </para></listitem> - <listitem><para> - Specify the "‐‐also-native" option with the - <filename>devtool add</filename> 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. - </para></listitem> - </itemizedlist> - <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 "‐‐also-native" - option, you can add the tool using just one recipe file. - </note> - </para> - </section> - - <section id='sdk-adding-node-js-modules'> - <title>Adding Node.js Modules</title> - - <para> - You can use the <filename>devtool add</filename> command two - different ways to add Node.js modules: 1) Through - <filename>npm</filename> and, 2) from a repository or local - source. - </para> - - <para> - Use the following form to add Node.js modules through - <filename>npm</filename>: - <literallayout class='monospaced'> - $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" - </literallayout> - 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><title>Notes</title> - <itemizedlist> - <listitem><para> - You must use quotes around the URL. - The <filename>devtool add</filename> does not require - the quotes, but the shell considers ";" as a splitter - between multiple commands. - Thus, without the quotes, - <filename>devtool add</filename> does not receive the - other parts, which results in several "command not - found" errors. - </para></listitem> - <listitem><para> - In order to support adding Node.js modules, a - <filename>nodejs</filename> recipe must be part - of your SDK. - </para></listitem> - </itemizedlist> - </note> - </para> - - <para> - As mentioned earlier, you can also add Node.js modules - directly from a repository or local source tree. - To add modules this way, use <filename>devtool add</filename> - in the following form: - <literallayout class='monospaced'> - $ devtool add https://github.com/diversario/node-ssdp - </literallayout> - In this example, <filename>devtool</filename> fetches the - specified Git repository, detects the code as Node.js - code, fetches dependencies using <filename>npm</filename>, and - sets - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - accordingly. - </para> - </section> - </section> - - <section id='sdk-working-with-recipes'> - <title>Working With Recipes</title> - - <para> - When building a recipe using the - <filename>devtool build</filename> command, the typical build - progresses as follows: - <orderedlist> - <listitem><para> - Fetch the source - </para></listitem> - <listitem><para> - Unpack the source - </para></listitem> - <listitem><para> - Configure the source - </para></listitem> - <listitem><para> - Compile the source - </para></listitem> - <listitem><para> - Install the build output - </para></listitem> - <listitem><para> - Package the installed output - </para></listitem> - </orderedlist> - 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. - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>, - and so forth). - These functions are typically shell scripts but can instead be - written in Python. - </para> - - <para> - 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 <filename>inherit</filename> directive. - This technique leaves the recipe to describe just the things that - are specific to the software being built. - A - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink> - class exists that is implicitly inherited by all recipes and - provides the functionality that most recipes typically need. - </para> - - <para> - The remainder of this section presents information useful when - working with recipes. - </para> - - <section id='sdk-finding-logs-and-work-files'> - <title>Finding Logs and Work Files</title> - - <para> - After the first run of the <filename>devtool build</filename> - command, recipes that were previously created using the - <filename>devtool add</filename> command or whose sources were - modified using the <filename>devtool modify</filename> - command contain symbolic links created within the source tree: - <itemizedlist> - <listitem><para> - <filename>oe-logs</filename>: - This link points to the directory in which log files - and run scripts for each build step are created. - </para></listitem> - <listitem><para> - <filename>oe-workdir</filename>: - This link points to the temporary work area for the - recipe. - The following locations under - <filename>oe-workdir</filename> are particularly - useful: - <itemizedlist> - <listitem><para> - <filename>image/</filename>: - Contains all of the files installed during - the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> - stage. - Within a recipe, this directory is referred - to by the expression - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>. - </para></listitem> - <listitem><para> - <filename>sysroot-destdir/</filename>: - Contains a subset of files installed within - <filename>do_install</filename> that have - been put into the shared sysroot. - For more information, see the - "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>" - section. - </para></listitem> - <listitem><para> - <filename>packages-split/</filename>: - Contains subdirectories for each package - produced by the recipe. - For more information, see the - "<link linkend='sdk-packaging'>Packaging</link>" - section. - </para></listitem> - </itemizedlist> - </para></listitem> - </itemizedlist> - You can use these links to get more information on what is - happening at each build step. - </para> - </section> - - <section id='sdk-setting-configure-arguments'> - <title>Setting Configure Arguments</title> - - <para> - 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 - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> - set within the recipe. - If you wish to pass additional options, add them to - <filename>EXTRA_OECONF</filename> or - <filename>PACKAGECONFIG_CONFARGS</filename>. - Other supported build tools have similar variables - (e.g. - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink> - for CMake, - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink> - for Scons, and so forth). - If you need to pass anything on the <filename>make</filename> - command line, you can use <filename>EXTRA_OEMAKE</filename> or the - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> - variables to do so. - </para> - - <para> - You can use the <filename>devtool configure-help</filename> 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 - <filename>EXTRA_OECONF</filename> or - <filename>PACKAGECONFIG_CONFARGS</filename>. - If applicable, the command also shows you the output of the - configure script's "‐‐help" option as a reference. - </para> - </section> - - <section id='sdk-sharing-files-between-recipes'> - <title>Sharing Files Between Recipes</title> - - <para> - Recipes often need to use files provided by other recipes on - the - <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>. - 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. - </para> - - <para> - Recipes should never write files directly into the sysroot. - Instead, files should be installed into standard locations - during the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> - task within the - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename> - 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. - </para> - </section> - - <section id='sdk-packaging'> - <title>Packaging</title> - - <para> - 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. - </para> - - <para> - During the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> - task, files installed during the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> - 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 <filename>-doc</filename> package. - Recipes that package software containing optional modules or - plugins might undergo additional package splitting as well. - </para> - - <para> - After building a recipe, you can see where files have gone by - looking in the <filename>oe-workdir/packages-split</filename> - directory, which contains a subdirectory for each package. - Apart from some advanced cases, the - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink> - variables controls splitting. - The <filename>PACKAGES</filename> variable lists all of the - packages to be produced, while the <filename>FILES</filename> - variable specifies which files to include in each package by - using an override to specify the package. - For example, <filename>FILES_${PN}</filename> specifies the - files to go into the main package (i.e. the main package has - the same name as the recipe and - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> - evaluates to the recipe name). - The order of the <filename>PACKAGES</filename> value is - significant. - For each installed file, the first package whose - <filename>FILES</filename> value matches the file is the - package into which the file goes. - Defaults exist for both the <filename>PACKAGES</filename> and - <filename>FILES</filename> 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. - </para> - </section> - </section> - - <section id='sdk-restoring-the-target-device-to-its-original-state'> - <title>Restoring the Target Device to its Original State</title> - - <para> - If you use the <filename>devtool deploy-target</filename> - 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 - <filename>devtool deploy-target</filename> command. - Because the <filename>devtool deploy-target</filename> command - backs up any files it overwrites, you can use the - <filename>devtool undeploy-target</filename> command to restore - those files and remove any other files the recipe deployed. - Consider the following example: - <literallayout class='monospaced'> - $ devtool undeploy-target lighttpd root@192.168.7.2 - </literallayout> - If you have deployed multiple applications, you can remove them - all using the "-a" option thus restoring the target device to its - original state: - <literallayout class='monospaced'> - $ devtool undeploy-target -a root@192.168.7.2 - </literallayout> - 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 <filename>devtool deploy-target</filename> and - <filename>devtool undeploy-target</filename> commands do not - currently interact with any package management system on the - target device (e.g. RPM or OPKG). - Consequently, you should not intermingle - <filename>devtool deploy-target</filename> and package - manager operations on the target device. - Doing so could result in a conflicting set of files. - </note> - </para> - </section> - - <section id='sdk-installing-additional-items-into-the-extensible-sdk'> - <title>Installing Additional Items Into the Extensible SDK</title> - - <para> - 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 <filename>devtool search</filename> 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: - <literallayout class='monospaced'> - $ devtool search libGL - mesa A free implementation of the OpenGL API - </literallayout> - Once you know the recipe (i.e. <filename>mesa</filename> in this - example), you can install it: - <literallayout class='monospaced'> - $ devtool sdk-install mesa - </literallayout> - By default, the <filename>devtool sdk-install</filename> 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: - <literallayout class='monospaced'> - $ devtool sdk-install -s mesa - </literallayout> - 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 - <filename>devtool add</filename> command. - </para> - </section> - - <section id='sdk-applying-updates-to-an-installed-extensible-sdk'> - <title>Applying Updates to an Installed Extensible SDK</title> - - <para> - 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. - </para> - - <para> - To update your installed SDK, use <filename>devtool</filename> as - follows: - <literallayout class='monospaced'> - $ devtool sdk-update - </literallayout> - The previous command assumes your SDK provider has set the default - update URL for you through the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink> - variable as described in the - "<link linkend='sdk-providing-updates-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</link>" - section. - If the SDK provider has not set that default URL, you need to - specify it yourself in the command as follows: - <literallayout class='monospaced'> - $ devtool sdk-update <replaceable>path_to_update_directory</replaceable> - </literallayout> - <note> - The URL needs to point specifically to a published SDK and - not to an SDK installer that you would download and install. - </note> - </para> - </section> - - <section id='sdk-creating-a-derivative-sdk-with-additional-components'> - <title>Creating a Derivative SDK With Additional Components</title> - - <para> - 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: - <orderedlist> - <listitem><para> - If necessary, install an extensible SDK that - you want to use as a base for your derivative SDK. - </para></listitem> - <listitem><para> - Source the environment script for the SDK. - </para></listitem> - <listitem><para> - Add the extra libraries or other components you want by - using the <filename>devtool add</filename> command. - </para></listitem> - <listitem><para> - Run the <filename>devtool build-sdk</filename> command. - </para></listitem> - </orderedlist> - 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. - </para> - </section> -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml deleted file mode 100644 index 9169fe9c05..0000000000 --- a/documentation/sdk-manual/sdk-intro.xml +++ /dev/null @@ -1,352 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > - -<chapter id='sdk-intro'> -<title>Introduction</title> - -<section id='sdk-manual-intro'> - <title>Introduction</title> - - <para> - 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. - </note> - </para> - - <para> - All SDKs consist of the following: - <itemizedlist> - <listitem><para> - <emphasis>Cross-Development Toolchain</emphasis>: - This toolchain contains a compiler, debugger, and various - miscellaneous tools. - </para></listitem> - <listitem><para> - <emphasis>Libraries, Headers, and Symbols</emphasis>: - The libraries, headers, and symbols are specific to the image - (i.e. they match the image). - </para></listitem> - <listitem><para> - <emphasis>Environment Setup Script</emphasis>: - This <filename>*.sh</filename> file, once run, sets up the - cross-development environment by defining variables and - preparing for SDK use. - </para></listitem> - </itemizedlist> - </para> - - <para> - 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 - <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>. - </para> - - <para> - 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 - <filename>libc</filename>, 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 - <filename>populate_sdk</filename> and - <filename>populate_sdk_ext</filename> archives. - </para> - - <para> - 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 <filename>gcc</filename> as a set of compiler options. - Those options are set up by the environment script and contained in - variables such as - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>. - This reduces the space needed for the tools. - Understand, however, that every target still needs a sysroot because - those binaries are target-specific. - </para> - - <para> - The SDK development environment consists of the following: - <itemizedlist> - <listitem><para> - 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 - <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> - configuration and extensions, - which allows you to cross-develop on the host machine for the - target hardware. - Additionally, the extensible SDK contains the - <filename>devtool</filename> functionality. - </para></listitem> - <listitem><para> - 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. - </para></listitem> - </itemizedlist> - </para> - - <para> - 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: - <informaltable frame='none'> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth='1*'/> - <colspec colname='c2' colwidth='1*'/> - <colspec colname='c3' colwidth='1*'/> - <thead> - <row> - <entry align="left"><emphasis>Feature</emphasis></entry> - <entry align="left"><emphasis>Standard SDK</emphasis></entry> - <entry align="left"><emphasis>Extensible SDK</emphasis></entry> - </row> - </thead> - <tbody> - <row> - <entry align="left">Toolchain</entry> - <entry align="left">Yes</entry> - <entry align="left">Yes*</entry> - </row> - <row> - <entry align="left">Debugger</entry> - <entry align="left">Yes</entry> - <entry align="left">Yes*</entry> - </row> - <row> - <entry align="left">Size</entry> - <entry align="left">100+ MBytes</entry> - <entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry> - </row> - <row> - <entry align="left"><filename>devtool</filename></entry> - <entry align="left">No</entry> - <entry align="left">Yes</entry> - </row> - <row> - <entry align="left">Build Images</entry> - <entry align="left">No</entry> - <entry align="left">Yes</entry> - </row> - <row> - <entry align="left">Updateable</entry> - <entry align="left">No</entry> - <entry align="left">Yes</entry> - </row> - <row> - <entry align="left">Managed Sysroot**</entry> - <entry align="left">No</entry> - <entry align="left">Yes</entry> - </row> - <row> - <entry align="left">Installed Packages</entry> - <entry align="left">No***</entry> - <entry align="left">Yes****</entry> - </row> - <row> - <entry align="left">Construction</entry> - <entry align="left">Packages</entry> - <entry align="left">Shared State</entry> - </row> - </tbody> - </tgroup> - </informaltable> - <literallayout class='monospaced'> - * Extensible SDK contains the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default. - - ** Sysroot is managed through the use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries. - - *** You can add runtime package management to the standard SDK but it is not supported by default. - - **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install. - </literallayout> - </para> - - <section id='the-cross-development-toolchain'> - <title>The Cross-Development Toolchain</title> - - <para> - The - <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink> - 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 <filename>devtool</filename> functionality. - This toolchain is created by running a SDK installer script - or through a - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> - that is based on your metadata configuration or extension for - your targeted device. - The cross-toolchain works with a matching target sysroot. - </para> - </section> - - <section id='sysroot'> - <title>Sysroots</title> - - <para> - 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. - </para> - </section> - - <section id='the-qemu-emulator'> - <title>The QEMU Emulator</title> - - <para> - 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: - <itemizedlist> - <listitem><para> - If you have cloned the <filename>poky</filename> Git - repository to create a - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> - and you have sourced the environment setup script, QEMU is - installed and automatically available. - </para></listitem> - <listitem><para> - 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. - </para></listitem> - <listitem><para> - 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. - </para></listitem> - </itemizedlist> - </para> - </section> -</section> - -<section id='sdk-development-model'> - <title>SDK Development Model</title> - - <para> - Fundamentally, the SDK fits into the development process as follows: - <imagedata fileref="figures/sdk-environment.png" align="center" width="6in" depth="5in" scalefit="100" /> - 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. - </para> - - <para> - You just need to follow these general steps: - <orderedlist> - <listitem><para> - <emphasis>Install the SDK for your target hardware:</emphasis> - For information on how to install the SDK, see the - "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" - section. - </para></listitem> - <listitem><para> - <emphasis>Download or Build the Target Image:</emphasis> - The Yocto Project supports several target architectures - and has many pre-built kernel images and root filesystem - images.</para> - - <para>If you are going to develop your application on - hardware, go to the - <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> - 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 - <filename>.hddimg</filename> 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.</para> - - <para>If you are going to develop your application and - then run and test it using the QEMU emulator, go to the - <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink> - download area. - From this area, go down into the directory for your - target architecture (e.g. <filename>qemux86_64</filename> - for an <trademark class='registered'>Intel</trademark>-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 - "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" - section for information on how to extract the root - filesystem. - </note> - </para></listitem> - <listitem><para> - <emphasis>Develop and Test your Application:</emphasis> - 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 - <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink> - to download and learn about the emulator. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" - chapter in the Yocto Project Development Tasks Manual - for information on using QEMU within the Yocto - Project. - </para></listitem> - </orderedlist> - </para> - - <para> - 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. - </para> -</section> - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/sdk-manual/sdk-manual-customization.xsl b/documentation/sdk-manual/sdk-manual-customization.xsl deleted file mode 100644 index efa8a84bbb..0000000000 --- a/documentation/sdk-manual/sdk-manual-customization.xsl +++ /dev/null @@ -1,26 +0,0 @@ -<?xml version='1.0'?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - - <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> - -<!-- - <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> - - <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> - ---> - - <xsl:include href="../template/permalinks.xsl"/> - <xsl:include href="../template/section.title.xsl"/> - <xsl:include href="../template/component.title.xsl"/> - <xsl:include href="../template/division.title.xsl"/> - <xsl:include href="../template/formal.object.heading.xsl"/> - - <xsl:param name="html.stylesheet" select="'sdk-style.css'" /> - <xsl:param name="chapter.autolabel" select="1" /> - <xsl:param name="appendix.autolabel">A</xsl:param> - <xsl:param name="section.autolabel" select="1" /> - <xsl:param name="section.label.includes.component.label" select="1" /> - <xsl:param name="generate.id.attributes" select="1" /> - -</xsl:stylesheet> diff --git a/documentation/sdk-manual/sdk-manual.xml b/documentation/sdk-manual/sdk-manual.xml deleted file mode 100755 index 537663dade..0000000000 --- a/documentation/sdk-manual/sdk-manual.xml +++ /dev/null @@ -1,158 +0,0 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > - -<book id='sdk-manual' lang='en' - xmlns:xi="http://www.w3.org/2003/XInclude" - xmlns="http://docbook.org/ns/docbook" - > - <bookinfo> - - <mediaobject> - <imageobject> - <imagedata fileref='figures/sdk-title.png' - format='SVG' - align='left' scalefit='1' width='100%'/> - </imageobject> - </mediaobject> - - <title> - Yocto Project Application Development and the Extensible Software Development Kit (eSDK) - </title> - - <authorgroup> - <author> - <affiliation> - <orgname>&ORGNAME;</orgname> - </affiliation> - <email>&ORGEMAIL;</email> - </author> - </authorgroup> - - <revhistory> - <revision> - <revnumber>2.1</revnumber> - <date>April 2016</date> - <revremark>The initial document released with the Yocto Project 2.1 Release.</revremark> - </revision> - <revision> - <revnumber>2.2</revnumber> - <date>October 2016</date> - <revremark>Released with the Yocto Project 2.2 Release.</revremark> - </revision> - <revision> - <revnumber>2.3</revnumber> - <date>May 2017</date> - <revremark>Released with the Yocto Project 2.3 Release.</revremark> - </revision> - <revision> - <revnumber>2.4</revnumber> - <date>October 2017</date> - <revremark>Released with the Yocto Project 2.4 Release.</revremark> - </revision> - <revision> - <revnumber>2.5</revnumber> - <date>May 2018</date> - <revremark>Released with the Yocto Project 2.5 Release.</revremark> - </revision> - <revision> - <revnumber>2.6</revnumber> - <date>November 2018</date> - <revremark>Released with the Yocto Project 2.6 Release.</revremark> - </revision> - <revision> - <revnumber>2.7</revnumber> - <date>May 2019</date> - <revremark>Released with the Yocto Project 2.7 Release.</revremark> - </revision> - <revision> - <revnumber>3.0</revnumber> - <date>October 2019</date> - <revremark>Released with the Yocto Project 3.0 Release.</revremark> - </revision> - <revision> - <revnumber>3.1</revnumber> - <date>&REL_MONTH_YEAR;</date> - <revremark>Released with the Yocto Project 3.1 Release.</revremark> - </revision> - </revhistory> - - <copyright> - <year>©RIGHT_YEAR;</year> - <holder>Linux Foundation</holder> - </copyright> - - <legalnotice> - <para> - Permission is granted to copy, distribute and/or modify this document under - the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. - </para> - <note><title>Manual Notes</title> - <itemizedlist> - <listitem><para> - This version of the - <emphasis>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</emphasis> - manual is for the &YOCTO_DOC_VERSION; release of the - Yocto Project. - To be sure you have the latest version of the manual - for this release, go to the - <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink> - and select the manual from that site. - Manuals from the site are more up-to-date than manuals - derived from the Yocto Project released TAR files. - </para></listitem> - <listitem><para> - If you located this manual through a web search, the - version of the manual might not be the one you want - (e.g. the search might have returned a manual much - older than the Yocto Project version with which you - are working). - You can see all Yocto Project major releases by - visiting the - <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink> - page. - If you need a version of this manual for a different - Yocto Project release, visit the - <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink> - and select the manual set by using the - "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE" - pull-down menus. - </para></listitem> - <listitem> - <para> - To report any inaccuracies or problems with this - (or any other Yocto Project) manual, send an email to - the Yocto Project documentation mailing list at - <filename>docs@lists.yoctoproject.org</filename> or - log into the freenode <filename>#yocto</filename> channel. - </para> - </listitem> - </itemizedlist> - </note> - </legalnotice> - - </bookinfo> - - <xi:include href="sdk-intro.xml"/> - - <xi:include href="sdk-extensible.xml"/> - - <xi:include href="sdk-using.xml"/> - - <xi:include href="sdk-working-projects.xml"/> - - <xi:include href="sdk-appendix-obtain.xml"/> - - <xi:include href="sdk-appendix-customizing.xml"/> - - <xi:include href="sdk-appendix-customizing-standard.xml"/> - -<!-- <index id='index'> - <title>Index</title> - </index> ---> - -</book> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/sdk-manual/sdk-style.css b/documentation/sdk-manual/sdk-style.css deleted file mode 100644 index 52518964ca..0000000000 --- a/documentation/sdk-manual/sdk-style.css +++ /dev/null @@ -1,988 +0,0 @@ -/* - Generic XHTML / DocBook XHTML CSS Stylesheet. - - Browser wrangling and typographic design by - Oyvind Kolas / pippin@gimp.org - - Customised for Poky by - Matthew Allum / mallum@o-hand.com - - Thanks to: - Liam R. E. Quin - William Skaggs - Jakub Steiner - - Structure - --------- - - The stylesheet is divided into the following sections: - - Positioning - Margins, paddings, width, font-size, clearing. - Decorations - Borders, style - Colors - Colors - Graphics - Graphical backgrounds - Nasty IE tweaks - Workarounds needed to make it work in internet explorer, - currently makes the stylesheet non validating, but up until - this point it is validating. - Mozilla extensions - Transparency for footer - Rounded corners on boxes - -*/ - - - /*************** / - / Positioning / -/ ***************/ - -body { - font-family: Verdana, Sans, sans-serif; - - min-width: 640px; - width: 80%; - margin: 0em auto; - padding: 2em 5em 5em 5em; - color: #333; -} - -h1,h2,h3,h4,h5,h6,h7 { - font-family: Arial, Sans; - color: #00557D; - clear: both; -} - -h1 { - font-size: 2em; - text-align: left; - padding: 0em 0em 0em 0em; - margin: 2em 0em 0em 0em; -} - -h2.subtitle { - margin: 0.10em 0em 3.0em 0em; - padding: 0em 0em 0em 0em; - font-size: 1.8em; - padding-left: 20%; - font-weight: normal; - font-style: italic; -} - -h2 { - margin: 2em 0em 0.66em 0em; - padding: 0.5em 0em 0em 0em; - font-size: 1.5em; - font-weight: bold; -} - -h3.subtitle { - margin: 0em 0em 1em 0em; - padding: 0em 0em 0em 0em; - font-size: 142.14%; - text-align: right; -} - -h3 { - margin: 1em 0em 0.5em 0em; - padding: 1em 0em 0em 0em; - font-size: 140%; - font-weight: bold; -} - -h4 { - margin: 1em 0em 0.5em 0em; - padding: 1em 0em 0em 0em; - font-size: 120%; - font-weight: bold; -} - -h5 { - margin: 1em 0em 0.5em 0em; - padding: 1em 0em 0em 0em; - font-size: 110%; - font-weight: bold; -} - -h6 { - margin: 1em 0em 0em 0em; - padding: 1em 0em 0em 0em; - font-size: 110%; - font-weight: bold; -} - -.authorgroup { - background-color: transparent; - background-repeat: no-repeat; - padding-top: 256px; - background-image: url("figures/sdk-title.png"); - background-position: left top; - margin-top: -256px; - padding-right: 50px; - margin-left: 0px; - text-align: right; - width: 740px; -} - -h3.author { - margin: 0em 0me 0em 0em; - padding: 0em 0em 0em 0em; - font-weight: normal; - font-size: 100%; - color: #333; - clear: both; -} - -.author tt.email { - font-size: 66%; -} - -.titlepage hr { - width: 0em; - clear: both; -} - -.revhistory { - padding-top: 2em; - clear: both; -} - -.toc, -.list-of-tables, -.list-of-examples, -.list-of-figures { - padding: 1.33em 0em 2.5em 0em; - color: #00557D; -} - -.toc p, -.list-of-tables p, -.list-of-figures p, -.list-of-examples p { - padding: 0em 0em 0em 0em; - padding: 0em 0em 0.3em; - margin: 1.5em 0em 0em 0em; -} - -.toc p b, -.list-of-tables p b, -.list-of-figures p b, -.list-of-examples p b{ - font-size: 100.0%; - font-weight: bold; -} - -.toc dl, -.list-of-tables dl, -.list-of-figures dl, -.list-of-examples dl { - margin: 0em 0em 0.5em 0em; - padding: 0em 0em 0em 0em; -} - -.toc dt { - margin: 0em 0em 0em 0em; - padding: 0em 0em 0em 0em; -} - -.toc dd { - margin: 0em 0em 0em 2.6em; - padding: 0em 0em 0em 0em; -} - -div.glossary dl, -div.variablelist dl { -} - -.glossary dl dt, -.variablelist dl dt, -.variablelist dl dt span.term { - font-weight: normal; - width: 20em; - text-align: right; -} - -.variablelist dl dt { - margin-top: 0.5em; -} - -.glossary dl dd, -.variablelist dl dd { - margin-top: -1em; - margin-left: 25.5em; -} - -.glossary dd p, -.variablelist dd p { - margin-top: 0em; - margin-bottom: 1em; -} - - -div.calloutlist table td { - padding: 0em 0em 0em 0em; - margin: 0em 0em 0em 0em; -} - -div.calloutlist table td p { - margin-top: 0em; - margin-bottom: 1em; -} - -div p.copyright { - text-align: left; -} - -div.legalnotice p.legalnotice-title { - margin-bottom: 0em; -} - -p { - line-height: 1.5em; - margin-top: 0em; - -} - -dl { - padding-top: 0em; -} - -hr { - border: solid 1px; -} - - -.mediaobject, -.mediaobjectco { - text-align: center; -} - -img { - border: none; -} - -ul { - padding: 0em 0em 0em 1.5em; -} - -ul li { - padding: 0em 0em 0em 0em; -} - -ul li p { - text-align: left; -} - -table { - width :100%; -} - -th { - padding: 0.25em; - text-align: left; - font-weight: normal; - vertical-align: top; -} - -td { - padding: 0.25em; - vertical-align: top; -} - -p a[id] { - margin: 0px; - padding: 0px; - display: inline; - background-image: none; -} - -a { - text-decoration: underline; - color: #444; -} - -pre { - overflow: auto; -} - -a:hover { - text-decoration: underline; - /*font-weight: bold;*/ -} - -/* This style defines how the permalink character - appears by itself and when hovered over with - the mouse. */ - -[alt='Permalink'] { color: #eee; } -[alt='Permalink']:hover { color: black; } - - -div.informalfigure, -div.informalexample, -div.informaltable, -div.figure, -div.table, -div.example { - margin: 1em 0em; - padding: 1em; - page-break-inside: avoid; -} - - -div.informalfigure p.title b, -div.informalexample p.title b, -div.informaltable p.title b, -div.figure p.title b, -div.example p.title b, -div.table p.title b{ - padding-top: 0em; - margin-top: 0em; - font-size: 100%; - font-weight: normal; -} - -.mediaobject .caption, -.mediaobject .caption p { - text-align: center; - font-size: 80%; - padding-top: 0.5em; - padding-bottom: 0.5em; -} - -.epigraph { - padding-left: 55%; - margin-bottom: 1em; -} - -.epigraph p { - text-align: left; -} - -.epigraph .quote { - font-style: italic; -} -.epigraph .attribution { - font-style: normal; - text-align: right; -} - -span.application { - font-style: italic; -} - -.programlisting { - font-family: monospace; - font-size: 80%; - white-space: pre; - margin: 1.33em 0em; - padding: 1.33em; -} - -.tip, -.warning, -.caution, -.note { - margin-top: 1em; - margin-bottom: 1em; - -} - -/* force full width of table within div */ -.tip table, -.warning table, -.caution table, -.note table { - border: none; - width: 100%; -} - - -.tip table th, -.warning table th, -.caution table th, -.note table th { - padding: 0.8em 0.0em 0.0em 0.0em; - margin : 0em 0em 0em 0em; -} - -.tip p, -.warning p, -.caution p, -.note p { - margin-top: 0.5em; - margin-bottom: 0.5em; - padding-right: 1em; - text-align: left; -} - -.acronym { - text-transform: uppercase; -} - -b.keycap, -.keycap { - padding: 0.09em 0.3em; - margin: 0em; -} - -.itemizedlist li { - clear: none; -} - -.filename { - font-size: medium; - font-family: Courier, monospace; -} - - -div.navheader, div.heading{ - position: absolute; - left: 0em; - top: 0em; - width: 100%; - background-color: #cdf; - width: 100%; -} - -div.navfooter, div.footing{ - position: fixed; - left: 0em; - bottom: 0em; - background-color: #eee; - width: 100%; -} - - -div.navheader td, -div.navfooter td { - font-size: 66%; -} - -div.navheader table th { - /*font-family: Georgia, Times, serif;*/ - /*font-size: x-large;*/ - font-size: 80%; -} - -div.navheader table { - border-left: 0em; - border-right: 0em; - border-top: 0em; - width: 100%; -} - -div.navfooter table { - border-left: 0em; - border-right: 0em; - border-bottom: 0em; - width: 100%; -} - -div.navheader table td a, -div.navfooter table td a { - color: #777; - text-decoration: none; -} - -/* normal text in the footer */ -div.navfooter table td { - color: black; -} - -div.navheader table td a:visited, -div.navfooter table td a:visited { - color: #444; -} - - -/* links in header and footer */ -div.navheader table td a:hover, -div.navfooter table td a:hover { - text-decoration: underline; - background-color: transparent; - color: #33a; -} - -div.navheader hr, -div.navfooter hr { - display: none; -} - - -.qandaset tr.question td p { - margin: 0em 0em 1em 0em; - padding: 0em 0em 0em 0em; -} - -.qandaset tr.answer td p { - margin: 0em 0em 1em 0em; - padding: 0em 0em 0em 0em; -} -.answer td { - padding-bottom: 1.5em; -} - -.emphasis { - font-weight: bold; -} - - - /************* / - / decorations / -/ *************/ - -.titlepage { -} - -.part .title { -} - -.subtitle { - border: none; -} - -/* -h1 { - border: none; -} - -h2 { - border-top: solid 0.2em; - border-bottom: solid 0.06em; -} - -h3 { - border-top: 0em; - border-bottom: solid 0.06em; -} - -h4 { - border: 0em; - border-bottom: solid 0.06em; -} - -h5 { - border: 0em; -} -*/ - -.programlisting { - border: solid 1px; -} - -div.figure, -div.table, -div.informalfigure, -div.informaltable, -div.informalexample, -div.example { - border: 1px solid; -} - - - -.tip, -.warning, -.caution, -.note { - border: 1px solid; -} - -.tip table th, -.warning table th, -.caution table th, -.note table th { - border-bottom: 1px solid; -} - -.question td { - border-top: 1px solid black; -} - -.answer { -} - - -b.keycap, -.keycap { - border: 1px solid; -} - - -div.navheader, div.heading{ - border-bottom: 1px solid; -} - - -div.navfooter, div.footing{ - border-top: 1px solid; -} - - /********* / - / colors / -/ *********/ - -body { - color: #333; - background: white; -} - -a { - background: transparent; -} - -a:hover { - background-color: #dedede; -} - - -h1, -h2, -h3, -h4, -h5, -h6, -h7, -h8 { - background-color: transparent; -} - -hr { - border-color: #aaa; -} - - -.tip, .warning, .caution, .note { - border-color: #fff; -} - - -.tip table th, -.warning table th, -.caution table th, -.note table th { - border-bottom-color: #fff; -} - - -.warning { - background-color: #f0f0f2; -} - -.caution { - background-color: #f0f0f2; -} - -.tip { - background-color: #f0f0f2; -} - -.note { - background-color: #f0f0f2; -} - -.writernotes { - color: #ff0000; -} - -.glossary dl dt, -.variablelist dl dt, -.variablelist dl dt span.term { - color: #044; -} - -div.figure, -div.table, -div.example, -div.informalfigure, -div.informaltable, -div.informalexample { - border-color: #aaa; -} - -pre.programlisting { - color: black; - background-color: #fff; - border-color: #aaa; - border-width: 2px; -} - -.guimenu, -.guilabel, -.guimenuitem { - background-color: #eee; -} - - -b.keycap, -.keycap { - background-color: #eee; - border-color: #999; -} - - -div.navheader { - border-color: black; -} - - -div.navfooter { - border-color: black; -} - - - /*********** / - / graphics / -/ ***********/ - -/* -body { - background-image: url("images/body_bg.jpg"); - background-attachment: fixed; -} - -.navheader, -.note, -.tip { - background-image: url("images/note_bg.jpg"); - background-attachment: fixed; -} - -.warning, -.caution { - background-image: url("images/warning_bg.jpg"); - background-attachment: fixed; -} - -.figure, -.informalfigure, -.example, -.informalexample, -.table, -.informaltable { - background-image: url("images/figure_bg.jpg"); - background-attachment: fixed; -} - -*/ -h1, -h2, -h3, -h4, -h5, -h6, -h7{ -} - -/* -Example of how to stick an image as part of the title. - -div.article .titlepage .title -{ - background-image: url("figures/white-on-black.png"); - background-position: center; - background-repeat: repeat-x; -} -*/ - -div.preface .titlepage .title, -div.colophon .title, -div.chapter .titlepage .title, -div.article .titlepage .title -{ -} - -div.section div.section .titlepage .title, -div.sect2 .titlepage .title { - background: none; -} - - -h1.title { - background-color: transparent; - background-repeat: no-repeat; - height: 256px; - text-indent: -9000px; - overflow:hidden; -} - -h2.subtitle { - background-color: transparent; - text-indent: -9000px; - overflow:hidden; - width: 0px; - display: none; -} - - /*************************************** / - / pippin.gimp.org specific alterations / -/ ***************************************/ - -/* -div.heading, div.navheader { - color: #777; - font-size: 80%; - padding: 0; - margin: 0; - text-align: left; - position: absolute; - top: 0px; - left: 0px; - width: 100%; - height: 50px; - background: url('/gfx/heading_bg.png') transparent; - background-repeat: repeat-x; - background-attachment: fixed; - border: none; -} - -div.heading a { - color: #444; -} - -div.footing, div.navfooter { - border: none; - color: #ddd; - font-size: 80%; - text-align:right; - - width: 100%; - padding-top: 10px; - position: absolute; - bottom: 0px; - left: 0px; - - background: url('/gfx/footing_bg.png') transparent; -} -*/ - - - - /****************** / - / nasty ie tweaks / -/ ******************/ - -/* -div.heading, div.navheader { - width:expression(document.body.clientWidth + "px"); -} - -div.footing, div.navfooter { - width:expression(document.body.clientWidth + "px"); - margin-left:expression("-5em"); -} -body { - padding:expression("4em 5em 0em 5em"); -} -*/ - - /**************************************** / - / mozilla vendor specific css extensions / -/ ****************************************/ -/* -div.navfooter, div.footing{ - -moz-opacity: 0.8em; -} - -div.figure, -div.table, -div.informalfigure, -div.informaltable, -div.informalexample, -div.example, -.tip, -.warning, -.caution, -.note { - -moz-border-radius: 0.5em; -} - -b.keycap, -.keycap { - -moz-border-radius: 0.3em; -} -*/ - -table tr td table tr td { - display: none; -} - - -hr { - display: none; -} - -table { - border: 0em; -} - - .photo { - float: right; - margin-left: 1.5em; - margin-bottom: 1.5em; - margin-top: 0em; - max-width: 17em; - border: 1px solid gray; - padding: 3px; - background: white; -} - .seperator { - padding-top: 2em; - clear: both; - } - - #validators { - margin-top: 5em; - text-align: right; - color: #777; - } - @media print { - body { - font-size: 8pt; - } - .noprint { - display: none; - } - } - - -.tip, -.note { - background: #f0f0f2; - color: #333; - padding: 20px; - margin: 20px; -} - -.tip h3, -.note h3 { - padding: 0em; - margin: 0em; - font-size: 2em; - font-weight: bold; - color: #333; -} - -.tip a, -.note a { - color: #333; - text-decoration: underline; -} - -.footnote { - font-size: small; - color: #333; -} - -/* Changes the announcement text */ -.tip h3, -.warning h3, -.caution h3, -.note h3 { - font-size:large; - color: #00557D; -} diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml deleted file mode 100644 index 66b15cd6ce..0000000000 --- a/documentation/sdk-manual/sdk-using.xml +++ /dev/null @@ -1,200 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > - -<chapter id='sdk-using-the-standard-sdk'> - <title>Using the Standard SDK</title> - - <para> - 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 - "<link linkend='sdk-manual-intro'>Introduction</link>" - section. - </note> - </para> - - <para> - You can use a standard SDK to work on Makefile and Autotools-based - projects. - See the - "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>" - chapter for more information. - </para> - - <section id='sdk-standard-sdk-intro'> - <title>Why use the Standard SDK and What is in It?</title> - - <para> - 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 - <filename>devtool</filename> functionality. - </para> - - <para> - 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 - "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" - section. - </para> - </section> - - <section id='sdk-installing-the-sdk'> - <title>Installing the SDK</title> - - <para> - The first thing you need to do is install the SDK on your - <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink> - by running the <filename>*.sh</filename> installation script. - </para> - - <para> - You can download a tarball installer, which includes the - pre-built toolchain, the <filename>runqemu</filename> - script, and support files from the appropriate - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink> - directory within the Index of Releases. - Toolchains are available for several 32-bit and 64-bit - architectures with the <filename>x86_64</filename> directories, - respectively. - The toolchains the Yocto Project provides are based off the - <filename>core-image-sato</filename> and - <filename>core-image-minimal</filename> images and contain - libraries appropriate for developing against that image. - </para> - - <para> - 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. - <literallayout class='monospaced'> - poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh - - Where: - <replaceable>host_system</replaceable> is a string representing your development system: - - i686 or x86_64. - - <replaceable>image_type</replaceable> is the image for which the SDK was built: - - core-image-minimal or core-image-sato. - - <replaceable>arch</replaceable> is a string representing the tuned target architecture: - - aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon. - - <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project: - - &DISTRO;, &DISTRO;+snapshot - </literallayout> - 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 <filename>core-image-sato</filename> and - using the current &DISTRO; snapshot: - <literallayout class='monospaced'> - poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout> - <note> - As an alternative to downloading an SDK, you can build the - SDK installer. - For information on building the installer, see the - "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" - section. - </note> - </para> - - <para> - The SDK and toolchains are self-contained and by default are - installed into the <filename>poky_sdk</filename> 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. - </para> - - <para> - 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 - <filename>~/Downloads/</filename> 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. - </note> - <literallayout class='monospaced'> - $ ./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 - </literallayout> - </para> - - <para> - Again, reference the - "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" - section for more details on the resulting directory structure of - the installed SDK. - </para> - </section> - - <section id='sdk-running-the-sdk-environment-setup-script'> - <title>Running the SDK Environment Setup Script</title> - - <para> - 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 - <filename>/opt/poky/&DISTRO;</filename> directory or the directory - you chose during installation. - </para> - - <para> - 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 - "<filename>environment-setup</filename>" 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: - <literallayout class='monospaced'> - $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux - </literallayout> - 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 - "<link linkend='sdk-running-the-extensible-sdk-environment-setup-script'>Running the Extensible SDK Environment Setup Script</link>" - section for more information. - </para> - </section> -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/sdk-manual/sdk-working-projects.xml b/documentation/sdk-manual/sdk-working-projects.xml deleted file mode 100644 index 521271d54c..0000000000 --- a/documentation/sdk-manual/sdk-working-projects.xml +++ /dev/null @@ -1,510 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > - -<chapter id='sdk-working-projects'> - - <title>Using the SDK Toolchain Directly</title> - - <para> - You can use the SDK toolchain directly with Makefile and - Autotools-based projects. - </para> - - <section id='autotools-based-projects'> - <title>Autotools-Based Projects</title> - - <para> - Once you have a suitable - <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchain</ulink> - installed, it is very easy to develop a project using the - <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>GNU Autotools-based</ulink> - workflow, which is outside of the - <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>. - </para> - - <para> - The following figure presents a simple Autotools workflow. - <imagedata fileref="figures/sdk-autotools-flow.png" width="7in" height="8in" align="center" /> - </para> - - <para> - 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 - <ulink url='https://developer.gnome.org/anjuta-build-tutorial/stable/create-autotools.html.en'>GNOME Developer</ulink> - site. - </note> - <orderedlist> - <listitem><para> - <emphasis>Create a Working Directory and Populate It:</emphasis> - Create a clean directory for your project and then make - that directory your working location. - <literallayout class='monospaced'> - $ mkdir $HOME/helloworld - $ cd $HOME/helloworld - </literallayout> - 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: - <filename>hello.c</filename>, - <filename>configure.ac</filename>, - <filename>Makefile.am</filename>, and - <filename>README</filename>, respectively.</para> - - <para> Use the following command to create an empty README - file, which is required by GNU Coding Standards: - <literallayout class='monospaced'> - $ touch README - </literallayout> - Create the remaining three files as follows: - <itemizedlist> - <listitem><para> - <emphasis><filename>hello.c</filename>:</emphasis> - <literallayout class='monospaced'> - #include <stdio.h> - - main() - { - printf("Hello World!\n"); - } - </literallayout> - </para></listitem> - <listitem><para> - <emphasis><filename>configure.ac</filename>:</emphasis> - <literallayout class='monospaced'> - AC_INIT(hello,0.1) - AM_INIT_AUTOMAKE([foreign]) - AC_PROG_CC - AC_CONFIG_FILES(Makefile) - AC_OUTPUT - </literallayout> - </para></listitem> - <listitem><para> - <emphasis><filename>Makefile.am</filename>:</emphasis> - <literallayout class='monospaced'> - bin_PROGRAMS = hello - hello_SOURCES = hello.c - </literallayout> - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para> - <emphasis>Source the Cross-Toolchain - Environment Setup File:</emphasis> - 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: - <literallayout class='monospaced'> - $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Create the <filename>configure</filename> Script:</emphasis> - Use the <filename>autoreconf</filename> command to - generate the <filename>configure</filename> script. - <literallayout class='monospaced'> - $ autoreconf - </literallayout> - The <filename>autoreconf</filename> tool takes care - of running the other Autotools such as - <filename>aclocal</filename>, - <filename>autoconf</filename>, and - <filename>automake</filename>. - <note> - If you get errors from - <filename>configure.ac</filename>, which - <filename>autoreconf</filename> runs, that indicate - missing files, you can use the "-i" option, which - ensures missing auxiliary files are copied to the build - host. - </note> - </para></listitem> - <listitem><para> - <emphasis>Cross-Compile the Project:</emphasis> - This command compiles the project using the - cross-compiler. - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - environment variable provides the minimal arguments for - GNU configure: - <literallayout class='monospaced'> - $ ./configure ${CONFIGURE_FLAGS} - </literallayout> - For an Autotools-based project, you can use the - cross-toolchain by just passing the appropriate host - option to <filename>configure.sh</filename>. - 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 - <filename>armv5te-poky-linux-gnueabi</filename>. - You will notice that the name of the script is - <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>. - Thus, the following command works to update your project - and rebuild it using the appropriate cross-toolchain tools: - <literallayout class='monospaced'> - $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable> - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Make and Install the Project:</emphasis> - These two commands generate and install the project - into the destination directory: - <literallayout class='monospaced'> - $ make - $ make install DESTDIR=./tmp - </literallayout> - <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 - "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>" - section. - </note> - 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. - <literallayout class='monospaced'> - $ file ./tmp/usr/local/bin/hello - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Execute Your Project:</emphasis> - 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: - <literallayout class='monospaced'> - $ ./tmp/usr/local/bin/hello - </literallayout> - As expected, the project displays the "Hello World!" - message. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='makefile-based-projects'> - <title>Makefile-Based Projects</title> - - <para> - 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 - <filename>make</filename> rules. - </para> - - <para> - 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. - <imagedata fileref="figures/sdk-makefile-flow.png" width="6in" height="7in" align="center" /> - </para> - - <para> - The main point of this section is to explain the following three - cases regarding variable behavior: - <itemizedlist> - <listitem><para> - <emphasis>Case 1 - No Variables Set in the - <filename>Makefile</filename> Map to Equivalent - Environment Variables Set in the SDK Setup Script:</emphasis> - Because matching variables are not specifically set in the - <filename>Makefile</filename>, the variables retain their - values based on the environment setup script. - </para></listitem> - <listitem><para> - <emphasis>Case 2 - Variables Are Set in the Makefile that - Map to Equivalent Environment Variables from the SDK - Setup Script:</emphasis> - Specifically setting matching variables in the - <filename>Makefile</filename> during the build results in - the environment settings of the variables being - overwritten. - In this case, the variables you set in the - <filename>Makefile</filename> are used. - </para></listitem> - <listitem><para> - <emphasis>Case 3 - Variables Are Set Using the Command Line - that Map to Equivalent Environment Variables from the - SDK Setup Script:</emphasis> - Executing the <filename>Makefile</filename> from the - command line results in the environment variables being - overwritten. - In this case, the command-line content is used. - </para></listitem> - </itemizedlist> - <note> - Regardless of how you set your variables, if you use - the "-e" option with <filename>make</filename>, the - variables from the SDK setup script take precedence: - <literallayout class='monospaced'> - $ make -e <replaceable>target</replaceable> - </literallayout> - </note> - </para> - - <para> - The remainder of this section presents a simple Makefile example - that demonstrates these variable behaviors. - </para> - - <para> - 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. - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>). - <literallayout class='monospaced'> - $ echo ${CC} - - $ - </literallayout> - Running the SDK setup script for a 64-bit build host and an - i586-tuned target architecture for a - <filename>core-image-sato</filename> image using the current - &DISTRO; Yocto Project release and then echoing that variable - shows the value established through the script: - <literallayout class='monospaced'> - $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux - $ echo ${CC} - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux - </literallayout> - </para> - - <para> - To illustrate variable use, work through this simple "Hello World!" - example: - <orderedlist> - <listitem><para> - <emphasis>Create a Working Directory and Populate It:</emphasis> - Create a clean directory for your project and then make - that directory your working location. - <literallayout class='monospaced'> - $ mkdir $HOME/helloworld - $ cd $HOME/helloworld - </literallayout> - After setting up the directory, populate it with files - needed for the flow. - You need a <filename>main.c</filename> file from which you - call your function, a <filename>module.h</filename> file - to contain headers, and a <filename>module.c</filename> - that defines your function. - </para> - - <para>Create the three files as follows: - <itemizedlist> - <listitem><para> - <emphasis><filename>main.c</filename>:</emphasis> - <literallayout class='monospaced'> - #include "module.h" - void sample_func(); - int main() - { - sample_func(); - return 0; - } - </literallayout> - </para></listitem> - <listitem><para> - <emphasis><filename>module.h</filename>:</emphasis> - <literallayout class='monospaced'> - #include <stdio.h> - void sample_func(); - </literallayout> - </para></listitem> - <listitem><para> - <emphasis><filename>module.c</filename>:</emphasis> - <literallayout class='monospaced'> - #include "module.h" - void sample_func() - { - printf("Hello World!"); - printf("\n"); - } - </literallayout> - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para> - <emphasis>Source the Cross-Toolchain Environment Setup File:</emphasis> - 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: - <literallayout class='monospaced'> - $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Create the <filename>Makefile</filename>:</emphasis> - For this example, the Makefile contains two lines that - can be used to set the <filename>CC</filename> variable. - One line is identical to the value that is set when you - run the SDK environment setup script, and the other line - sets <filename>CC</filename> to "gcc", the default GNU - compiler on the build host: - <literallayout class='monospaced'> - # 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 - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Make the Project:</emphasis> - Use the <filename>make</filename> command to create the - binary output file. - Because variables are commented out in the Makefile, - the value used for <filename>CC</filename> is the value - set when the SDK environment setup file was run: - <literallayout class='monospaced'> - $ 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 - </literallayout> - From the results of the previous command, you can see that - the compiler used was the compiler established through - the <filename>CC</filename> variable defined in the - setup script.</para> - - <para>You can override the <filename>CC</filename> - environment variable with the same variable as set from - the Makefile by uncommenting the line in the Makefile - and running <filename>make</filename> again. - <literallayout class='monospaced'> - $ 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 - </literallayout> - As shown in the previous example, the cross-toolchain - compiler is not used. - Rather, the default compiler is used.</para> - - <para>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 <filename>make</filename> uses - the established SDK compiler. - However, when you run <filename>make</filename>, use a - command-line argument to set <filename>CC</filename> - to "gcc": - <literallayout class='monospaced'> - $ 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 - </literallayout> - In the previous case, the command-line argument overrides - the SDK environment variable.</para> - - <para>In this last case, edit Makefile again to use the - "gcc" compiler but then use the "-e" option on the - <filename>make</filename> command line: - <literallayout class='monospaced'> - $ 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 - </literallayout> - In the previous case, the "-e" option forces - <filename>make</filename> to use the SDK environment - variables regardless of the values in the Makefile. - </para></listitem> - <listitem><para> - <emphasis>Execute Your Project:</emphasis> - To execute the project (i.e. - <filename>target_bin</filename>), use the following - command: - <literallayout class='monospaced'> - $ ./target_bin - Hello World! - </literallayout> - <note> - If you used the cross-toolchain compiler to build - <filename>target_bin</filename> and your build host - differs in architecture from that of the target - machine, you need to run your project on the target - device. - </note> - As expected, the project displays the "Hello World!" - message. - </para></listitem> - </orderedlist> - </para> - </section> -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/sdk-manual/using.rst b/documentation/sdk-manual/using.rst new file mode 100644 index 0000000000..f1ff0c76ca --- /dev/null +++ b/documentation/sdk-manual/using.rst @@ -0,0 +1,147 @@ +.. 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 + ":ref:`sdk-manual/intro:introduction`" section. + +You can use a standard SDK to work on Makefile and Autotools-based +projects. See the +":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" 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 +":ref:`sdk-manual/appendix-obtain: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 </releases/yocto/yocto-&DISTRO;/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 the corresponding 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 + ":ref:`sdk-manual/appendix-obtain: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:: + + $ ./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 + +.. 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. + +Again, reference the +":ref:`sdk-manual/appendix-obtain: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 +":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`" +section for more information. diff --git a/documentation/sdk-manual/working-projects.rst b/documentation/sdk-manual/working-projects.rst new file mode 100644 index 0000000000..4236bcec24 --- /dev/null +++ b/documentation/sdk-manual/working-projects.rst @@ -0,0 +1,403 @@ +.. 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 :wikipedia:`GNU +Autotools-based <GNU_Build_System>` 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 + :width: 70% + +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. + +#. *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 <stdio.h> + + 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 + +#. *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 + + Another example is sourcing the environment setup directly in a Yocto + build:: + + $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux + +#. *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. + +#. *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 + +#. *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 by the Makefile, see the + :ref:`sdk-manual/working-projects: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 + +#. *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 + :width: 70% + +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: + +#. *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 <stdio.h> + void sample_func(); + + - ``module.c``:: + + #include "module.h" + void sample_func() + { + printf("Hello World!"); + printf("\n"); + } + +#. *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 + + Another example is sourcing the environment setup directly in a Yocto + build:: + + $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux + +#. *Create the Makefile:* For this example, the Makefile contains + two lines that can be used to set the :term:`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 :term:`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 + +#. *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 :term:`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 :term:`CC` + variable defined in the setup script. + + You can override the :term:`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 :term:`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. + +#. *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. |