diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-extensible.xml')
| -rw-r--r-- | documentation/sdk-manual/sdk-extensible.xml | 1847 |
1 files changed, 0 insertions, 1847 deletions
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml deleted file mode 100644 index a73a07a7b9..0000000000 --- a/documentation/sdk-manual/sdk-extensible.xml +++ /dev/null @@ -1,1847 +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; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<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 ---> |