diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-extensible.xml')
| -rw-r--r-- | documentation/sdk-manual/sdk-extensible.xml | 2866 |
1 files changed, 1489 insertions, 1377 deletions
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml index 73b317f5c8..8c568a739e 100644 --- a/documentation/sdk-manual/sdk-extensible.xml +++ b/documentation/sdk-manual/sdk-extensible.xml @@ -4,1516 +4,1628 @@ <chapter id='sdk-extensible'> -<title>Using the Extensible SDK</title> - -<para> - This chapter describes the extensible SDK and how to use it. - 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_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. -</para> - -<para> - Information in this chapter covers features that are not part of the - standard SDK. - In other words, the chapter presents information unique to the - extensible SDK only. - For information on how to use the standard SDK, see the - "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>" - chapter. -</para> - -<section id='sdk-setting-up-to-use-the-extensible-sdk'> - <title>Setting Up to Use the Extensible SDK</title> + <title>Using the Extensible SDK</title> <para> - Getting set up to use the extensible SDK is identical to getting set - up to use the standard SDK. - You still need to locate and run the installer and then run the - environment setup script. - See the - "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" - and the - "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>" - sections for general information. - The following items highlight the only differences between getting - set up to use the extensible SDK as compared to the standard SDK: - <itemizedlist> - <listitem><para><emphasis>Default Installation Directory:</emphasis> - By default, the extensible SDK installs into the - <filename>poky_sdk</filename> folder of your home directory. - As with the standard SDK, you can choose to install the - extensible SDK in any location when you run the installer. - However, unlike the standard SDK, the location you choose needs - to be writable for whichever users need to use the SDK, - since files will need to be written under that directory during - the normal course of operation. - </para></listitem> - <listitem><para><emphasis>Build Tools and Build System:</emphasis> - The extensible SDK installer performs additional tasks as - compared to the standard SDK installer. - to the SDK and the installer also prepares the internal build - system within the SDK. - You can find pre-built extensible SDK installers in the same - <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-&DISTRO;/toolchain/'>toolchain</ulink> - location as the pre-built standard SDK installers. - For extensible SDK installers, the - <filename>ext</filename> string is part of the name. - Here is an example: - <literallayout class='monospaced'> - poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh - </literallayout> - <note> - As an alternative to downloading an SDK, you can build the toolchain - installer. - For information on building the installer, see the - "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" - section. - Another helpful resource for building an installer is the - <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> - wiki page. - </note> - Here is example output for running the extensible SDK - installer: - <literallayout class='monospaced'> - $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh - Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO; - =================================================================================== - 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... - 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></listitem> - </itemizedlist> - </para> - - <para> - After installing the SDK, you need to run the SDK environment setup - script. - Here is the output from an example run: - <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> - Once you run the environment setup script, you have - <filename>devtool</filename> available. - </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. - </para> - - <para> - The <filename>devtool</filename> command line is organized similarly - to - <ulink url='&YOCTO_DOCS_DEV_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. + 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_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. <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 more a - <filename>devtool</filename> reference. + 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> - Two <filename>devtool</filename> subcommands that provide - entry-points into development are: - <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> - </itemizedlist> - As with the OpenEmbedded 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, both 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> and - <filename>devtool modify</filename> workflows. + You can use an extensible SDK to work on Makefile, Autotools, and + Eclipse-based projects. + See the + "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>" + chapter for more information. </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_DEV_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> + <section id='sdk-extensible-sdk-intro'> + <title>Why use the Extensible SDK and What is in It?</title> <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: + 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> - <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 where other developers are responsible for - various areas of source code. - As a developer, you are probably interested in using - that source code as part of your development using - 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 represents a common situation - where the source code does not exist locally - and needs to be extracted. - In this situation, you just let it get - extracted to the default workspace - you do not - want it 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> - creates a recipe and an append file in the - workspace as well as extracts the upstream - source files into a local Git repository also - within the <filename>sources</filename> folder. - </para></listitem> - <listitem><para><emphasis>Middle</emphasis>: - The middle scenario 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. - If required, <filename>devtool</filename> - always creates - a Git repository locally during the extraction. - 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: - <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 both the recipe and an append file - for the recipe. - </para></listitem> - <listitem><para><emphasis>Right</emphasis>: - The right scenario represents a situation - where the source tree (srctree) has been - previously prepared outside of the - <filename>devtool</filename> workspace. - </para> - - <para>The following command names the recipe - and identifies where the existing source tree - is located: - <literallayout class='monospaced'> - $ devtool add <replaceable>recipe srctree</replaceable> - </literallayout> - The command examines the source code and creates - a recipe for it placing the recipe into the - workspace.</para> - - <para>Because the extracted source code already exists, - <filename>devtool</filename> does not try to - relocate it into the workspace - just the new - the recipe is placed in the workspace.</para> - - <para>Aside from a recipe folder, the command - also creates an append folder and places an initial - <filename>*.bbappend</filename> within. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para><emphasis>Edit the Recipe</emphasis>: - At this point, 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>: - At this point in the flow, the next step you - take depends on what you are going to do with - the new code.</para> - <para>If you need to take the build output and eventually - move it to the target hardware, you would use - <filename>devtool build</filename>: - <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 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, 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. - <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> + 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-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> + <section id='sdk-setting-up-to-use-the-extensible-sdk'> + <title>Setting Up to Use the Extensible SDK</title> <para> - The <filename>devtool modify</filename> command prepares the - way to work on existing code that already has a recipe in - place. - The command is flexible enough to allow you to extract code, - specify the existing recipe, and keep track of and gather any - patch files from other developers that are - associated with the code. + The first thing you need to do is install the SDK on your host + development machine by running the <filename>*.sh</filename> + installation script. </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 - you would use with the <filename>devtool modify</filename> - command: + 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 directory under + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. + Toolchains are available for 32-bit and 64-bit x86 development + systems from the <filename>i686</filename> and + <filename>x86_64</filename> directories, respectively. + The toolchains the Yocto Project provides are based off the + <filename>core-image-sato</filename> image and contain + libraries appropriate for developing against that image. + Each type of development system supports five or more target + architectures. </para> <para> - <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" /> - </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. + <literallayout class='monospaced'> + poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh - <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 in some layer external - to the <filename>devtool</filename> workspace. - </para></listitem> - <listitem><para>The source files exist 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 some 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 represents a common situation - where the source code does not exist locally - and needs to be extracted. - In this situation, the source is extracted - into the default 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, - it uses the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - variable to locate the source code and - any local patch files from other developers are - located. - <note> - You cannot provide an URL for - <replaceable>srctree</replaceable> when using the - <filename>devtool modify</filename> command. - </note> - With this scenario, however, since no - <replaceable>srctree</replaceable> argument exists, the - <filename>devtool modify</filename> command by default - extracts the source files to a Git structure. - Furthermore, the location for the extracted source is the - default area within the workspace. - The result is that the command sets up both the source - code and an append file within the workspace with the - recipe remaining in its original location. - </para></listitem> - <listitem><para><emphasis>Middle</emphasis>: - The middle scenario 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 in its own - layer outside the workspace.</para> - - <para>The following command tells - <filename>devtool</filename> what recipe with - which to work and, in this case, identifies a local - area for the extracted source files that is outside - of the default workspace: - <literallayout class='monospaced'> - $ devtool modify <replaceable>recipe srctree</replaceable> - </literallayout> - As with all extractions, the command uses - the recipe's <filename>SRC_URI</filename> to locate the - source files. - Once the files are located, the command by default - extracts them. - Providing the <replaceable>srctree</replaceable> - argument instructs <filename>devtool</filename> where - place the extracted source.</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 - provided with <replaceable>srctree</replaceable>. - </para></listitem> - <listitem><para><emphasis>Right</emphasis>: - The right scenario represents a situation - where the source tree - (<replaceable>srctree</replaceable>) exists as a - previously extracted Git structure outside of - the <filename>devtool</filename> workspace. - In this example, the recipe also exists - elsewhere 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> + Where: + <replaceable>host_system</replaceable> is a string representing your development system: - <para>Once the command finishes, it creates only - an append file for the recipe in the 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</emphasis>: - Once you have updated the source files, you can build - the recipe. - </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, 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, 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 - committed to the Git repository in the source tree. - </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> in a different - layer as provided by <replaceable>layer</replaceable>. - </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> + i686 or x86_64. - <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> + <replaceable>image_type</replaceable> is the image for which the SDK was built. - <para> - The <filename>devtool upgrade</filename> command updates - an existing recipe so that you can build it for an updated - set of source files. - The 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> workspace, and - work with any source file forms that the fetchers support. - </para> + <replaceable>arch</replaceable> is a string representing the tuned target architecture: - <para> - Depending on your particular scenario, the arguments and options - you use with <filename>devtool upgrade</filename> form different - combinations. - The following diagram shows a common development flow - you would use with the <filename>devtool modify</filename> - command: + i586, x86_64, powerpc, mips, armv7a or armv5te + + <replaceable>release_version</replaceable> is a string representing the release number of the + Yocto Project: + + &DISTRO;, &DISTRO;+snapshot + </literallayout> + For example, the following toolchain 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 + toolchain installer. + For information on building the installer, see the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section. + Another helpful resource for building an installer is the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + wiki page. + This wiki page focuses on development when using the Eclipse + IDE. + </note> </para> <para> - <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" /> + 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, the location you choose needs to be writable for whichever + users need to use the SDK, since files will need to be written + under that directory during the normal course of operation. </para> <para> - <orderedlist> - <listitem><para><emphasis>Initiate the Upgrade</emphasis>: - The top part of the flow shows a typical scenario by which - you could use <filename>devtool upgrade</filename>. - The following conditions exist: - <itemizedlist> - <listitem><para>The recipe exists in some layer external - to the <filename>devtool</filename> workspace. - </para></listitem> - <listitem><para>The source files for the new release - exist adjacent to 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 workspace. - 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> - Also, in this example, the "-V" option is used to specify - the new version. - 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 are located. - 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></listitem> - <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>: - At this point, there could be some conflicts due to the - software being upgraded to a new version. - This would 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. - If this is the case, 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</emphasis>: - Once you have your recipe in order, you can build it. - You can either use <filename>devtool build</filename> or - <filename>bitbake</filename>. - Either method produces build output that is stored - in - <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. - </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 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, 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, 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 - committed to the Git repository in the source tree. - </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> in a different - layer as provided by <replaceable>layer</replaceable>. - </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> + 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 toolchain installer is located in + <filename>~/Downloads/</filename>. + <note> + If you do not have write permissions for the directory + into which you are installing the SDK, the installer + notifies you and exits. + Be sure you have write permissions in the directory and + run the installer again. + </note> + <literallayout class='monospaced'> + $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh + Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO; + =================================================================================== + 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... + 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> - -<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 with which you provide it. - 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 you can build the recipe. - Once the recipe can be built, 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> + <section id='sdk-running-the-extensible-sdk-environment-setup-script'> + <title>Running the Extensible SDK Environment Setup Script</title> <para> - If you do not specify a name and version on the command - line, <filename>devtool add</filename> attempts to determine - the name and version of the software being built from - various metadata within the source tree. - Furthermore, the command sets the name of the created recipe - file accordingly. - If the name or version cannot be determined, the - <filename>devtool add</filename> command prints an error and - you must re-run the command with both the name and version - or just the name or version specified. + Once you have the SDK installed, you must run the SDK environment + setup script before you can actually use it. + 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> - Sometimes the name or version determined from the source tree - might be incorrect. - For such a case, you must reset the recipe: + 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'> - $ devtool reset -n <replaceable>recipename</replaceable> + $ 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> + When you run the setup script, many environment variables are + defined: + <literallayout class='monospaced'> + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation + <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler + <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler + <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor + <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker + <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger + <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols + <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib' + <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy' + <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump' + <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar' + <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm' + <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools + <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure + <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags + <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags + <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link + <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags </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> + <section id='using-devtool-in-your-sdk-workflow'> + <title>Using <filename>devtool</filename> in Your SDK Workflow</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 in the - <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> - value within the recipe. - If a dependency cannot be mapped, then a comment is placed in - the recipe indicating such. - The inability to map a dependency might be caused because the - naming is not 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 to satisfy the dependency and then come - back to the first recipe and add its name to - <filename>DEPENDS</filename>. + 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. </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} += "dependency1 dependency2 ..." - </literallayout> + The <filename>devtool</filename> command line is organized similarly + to + <ulink url='&YOCTO_DOCS_DEV_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> - 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 for an option to disable the associated - functionality passed to the configure script. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename> Quick Reference</ulink>" + in the Yocto Project Reference Manual for more a + <filename>devtool</filename> reference. </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 and sets the - <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> - value accordingly. - You should double-check this value against the documentation - or source files for the software you are building and update - that <filename>LICENSE</filename> value if necessary. + Two <filename>devtool</filename> subcommands that provide + entry-points into development are: + <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> + </itemizedlist> + As with the OpenEmbedded 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, both new recipes and the source go into a "workspace" + directory under the SDK. </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. - However, license statements often appear in comments at the top - of source files or within documentation. - 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. + The remainder of this section presents the + <filename>devtool add</filename> and + <filename>devtool modify</filename> workflows. </para> - <para> - If the <filename>devtool add</filename> command cannot - determine licensing information, the - <filename>LICENSE</filename> value is set to "CLOSED" and the - <filename>LIC_FILES_CHKSUM</filename> value remains unset. - This behavior allows you to continue with development but is - unlikely to be correct in all cases. - Consequently, you should check the documentation or source - files for the software you are building to determine the actual - license. - </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_DEV_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 where other developers are responsible for + various areas of source code. + As a developer, you are probably interested in using + that source code as part of your development using + 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 represents a common situation + where the source code does not exist locally + and needs to be extracted. + In this situation, you just let it get + extracted to the default workspace - you do not + want it 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> + creates a recipe and an append file in the + workspace as well as extracts the upstream + source files into a local Git repository also + within the <filename>sources</filename> folder. + </para></listitem> + <listitem><para><emphasis>Middle</emphasis>: + The middle scenario 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. + If required, <filename>devtool</filename> + always creates + a Git repository locally during the extraction. + 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: + <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 both the recipe and an append file + for the recipe. + </para></listitem> + <listitem><para><emphasis>Right</emphasis>: + The right scenario represents a situation + where the source tree (srctree) has been + previously prepared outside of the + <filename>devtool</filename> workspace. + </para> + + <para>The following command names the recipe + and identifies where the existing source tree + is located: + <literallayout class='monospaced'> + $ devtool add <replaceable>recipe srctree</replaceable> + </literallayout> + The command examines the source code and creates + a recipe for it placing the recipe into the + workspace.</para> + + <para>Because the extracted source code already exists, + <filename>devtool</filename> does not try to + relocate it into the workspace - just the new + the recipe is placed in the workspace.</para> + + <para>Aside from a recipe folder, the command + also creates an append folder and places an initial + <filename>*.bbappend</filename> within. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Edit the Recipe</emphasis>: + At this point, 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>: + At this point in the flow, the next step you + take depends on what you are going to do with + the new code.</para> + <para>If you need to take the build output and eventually + move it to the target hardware, you would use + <filename>devtool build</filename>: + <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 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, 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. + <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 recipe in + place. + The command is flexible enough to allow you to extract code, + 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 + you would use with 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 in some layer external + to the <filename>devtool</filename> workspace. + </para></listitem> + <listitem><para>The source files exist 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 some 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 represents a common situation + where the source code does not exist locally + and needs to be extracted. + In this situation, the source is extracted + into the default 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, + it uses the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable to locate the source code and + any local patch files from other developers are + located. + <note> + You cannot provide an URL for + <replaceable>srctree</replaceable> when using the + <filename>devtool modify</filename> command. + </note> + With this scenario, however, since no + <replaceable>srctree</replaceable> argument exists, the + <filename>devtool modify</filename> command by default + extracts the source files to a Git structure. + Furthermore, the location for the extracted source is the + default area within the workspace. + The result is that the command sets up both the source + code and an append file within the workspace with the + recipe remaining in its original location. + </para></listitem> + <listitem><para><emphasis>Middle</emphasis>: + The middle scenario 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 in its own + layer outside the workspace.</para> + + <para>The following command tells + <filename>devtool</filename> what recipe with + which to work and, in this case, identifies a local + area for the extracted source files that is outside + of the default workspace: + <literallayout class='monospaced'> + $ devtool modify <replaceable>recipe srctree</replaceable> + </literallayout> + As with all extractions, the command uses + the recipe's <filename>SRC_URI</filename> to locate the + source files. + Once the files are located, the command by default + extracts them. + Providing the <replaceable>srctree</replaceable> + argument instructs <filename>devtool</filename> where + place the extracted source.</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 + provided with <replaceable>srctree</replaceable>. + </para></listitem> + <listitem><para><emphasis>Right</emphasis>: + The right scenario represents a situation + where the source tree + (<replaceable>srctree</replaceable>) exists as a + previously extracted Git structure outside of + the <filename>devtool</filename> workspace. + In this example, the recipe also exists + elsewhere 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>Once the command finishes, it creates only + an append file for the recipe in the 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</emphasis>: + Once you have updated the source files, you can build + the recipe. + </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, 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, 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 + committed to the Git repository in the source tree. + </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> in a different + layer as provided by <replaceable>layer</replaceable>. + </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-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 updates + an existing recipe so that you can build it for an updated + set of source files. + The 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> workspace, and + work with any source file forms that the fetchers support. + </para> + + <para> + Depending on your particular scenario, the arguments and options + you use with <filename>devtool upgrade</filename> form different + combinations. + The following diagram shows a common development flow + you would use with the <filename>devtool modify</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 a typical scenario by which + you could use <filename>devtool upgrade</filename>. + The following conditions exist: + <itemizedlist> + <listitem><para>The recipe exists in some layer external + to the <filename>devtool</filename> workspace. + </para></listitem> + <listitem><para>The source files for the new release + exist adjacent to 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 workspace. + 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> + Also, in this example, the "-V" option is used to specify + the new version. + 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 are located. + 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></listitem> + <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>: + At this point, there could be some conflicts due to the + software being upgraded to a new version. + This would 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. + If this is the case, 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</emphasis>: + Once you have your recipe in order, you can build it. + You can either use <filename>devtool build</filename> or + <filename>bitbake</filename>. + Either method produces build output that is stored + in + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. + </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 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, 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, 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 + committed to the Git repository in the source tree. + </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> in a different + layer as provided by <replaceable>layer</replaceable>. + </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-adding-makefile-only-software'> - <title>Adding Makefile-Only Software</title> - - <para> - The use of <filename>make</filename> 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 some arguments (e.g. to point to the associated sysroot - for the target machine). - </para> + <section id='sdk-a-closer-look-at-devtool-add'> + <title>A Closer Look at <filename>devtool add</filename></title> <para> - When writing a recipe for Makefile-only software, keep the - following in mind: + The <filename>devtool add</filename> command automatically creates a + recipe based on the source tree with which you provide it. + Currently, the command has support for the following: <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>. + Autotools (<filename>autoconf</filename> and + <filename>automake</filename>) </para></listitem> <listitem><para> - The environment in which <filename>make</filename> 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 you will see a list of - environment variables that are being set. - You can take advantage of these variables within the - Makefile. + CMake </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. - In this situation, 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. + Scons </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 by virtue of - being 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. + <filename>qmake</filename> </para></listitem> <listitem><para> - Sometimes a Makefile runs target-specific commands such - as <filename>ldconfig</filename>. - For such cases, you might be able to simply apply - patches that remove these commands from the Makefile. + 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> - </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 - build host system as opposed to the target. - You should indicate this 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. + Node.js module </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. + 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> - 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. + 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 you can build the recipe. + Once the recipe can be built, you could use possible further + iterations to test the recipe on the target device. </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. + The remainder of this section covers specifics regarding how parts + of the recipe are generated. </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> + <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> attempts to determine + the name and version of the software being built from + various metadata within the source tree. + Furthermore, the command sets the name of the created recipe + file accordingly. + If the name or version cannot be determined, the + <filename>devtool add</filename> command prints an error and + you must re-run the command with both the name and version + or just the name or version specified. + </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 in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> + value within the recipe. + If a dependency cannot be mapped, then a comment is placed in + the recipe indicating such. + The inability to map a dependency might be caused because the + naming is not 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 to satisfy the dependency and then come + back to the first recipe and add its name to + <filename>DEPENDS</filename>. + </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} += "dependency1 dependency2 ..." + </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 for an option to disable 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 and sets the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> + value accordingly. + You should double-check this value against the documentation + or source files for the software you are building and update + that <filename>LICENSE</filename> value if necessary. + </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. + However, license statements often appear in comments at the top + of source files or within documentation. + 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, the + <filename>LICENSE</filename> value is set to "CLOSED" and the + <filename>LIC_FILES_CHKSUM</filename> value remains unset. + This behavior allows you to continue with development but is + unlikely to be correct in all cases. + Consequently, 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 <filename>make</filename> 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 some 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 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. + 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> - In order to support adding - Node.js modules, a - <filename>nodejs</filename> recipe must be part of your - SDK in order to provide Node.js - itself. + The environment in which <filename>make</filename> 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 you will see a list of + environment variables 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. + In this situation, 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 by virtue of + being 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. + </para></listitem> + <listitem><para> + Sometimes a Makefile runs target-specific commands such + as <filename>ldconfig</filename>. + For such cases, you might be able to simply apply + patches that remove these commands from the Makefile. </para></listitem> </itemizedlist> - </note> - </para> + </para> + </section> - <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 that the code is 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-adding-native-tools'> + <title>Adding Native Tools</title> -<section id='sdk-working-with-recipes'> - <title>Working With Recipes</title> - - <para> - When building a recipe with <filename>devtool build</filename> the - typical build progression is 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> - Compiling 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, usually with a - "do_" prefix. - 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, leaving the recipe - to describe just the things that are specific to the software to be - 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 typical recipes need. - </para> - - <para> - The remainder of this section presents information useful when - working with recipes. - </para> + <para> + Often, you need to build additional tools that run on the + build host system as opposed to the target. + You should indicate this 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 in order to provide Node.js + itself. + </para></listitem> + </itemizedlist> + </note> + </para> - <section id='sdk-finding-logs-and-work-files'> - <title>Finding Logs and Work Files</title> + <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 that the code is 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> - <para> - When you are debugging a recipe that you previously created using - <filename>devtool add</filename> or whose source you are modifying - by using the <filename>devtool modify</filename> command, after - the first run of <filename>devtool build</filename>, you will - find some symbolic links created within the source tree: - <filename>oe-logs</filename>, which points to the directory in - which log files and run scripts for each build step are created - and <filename>oe-workdir</filename>, which points to the temporary - work area for the recipe. - You can use these links to get more information on what is - happening at each build step. - </para> + <section id='sdk-working-with-recipes'> + <title>Working With Recipes</title> <para> - These locations under <filename>oe-workdir</filename> are - particularly useful: - <itemizedlist> - <listitem><para><filename>image/</filename>: - Contains all of the files installed at 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>. + When building a recipe with <filename>devtool build</filename> the + typical build progression is as follows: + <orderedlist> + <listitem><para> + Fetch the source </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. + <listitem><para> + Unpack the source </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. + <listitem><para> + Configure the source </para></listitem> - </itemizedlist> - </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. + <listitem><para> + Compiling 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, usually with a + "do_" prefix. + These functions are typically shell scripts but can instead be written + in Python. </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. + 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, leaving the recipe + to describe just the things that are specific to the software to be + 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 typical recipes need. </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 build host. - For example, an application linking to a common library needs - access to the library itself and its associated headers. - The way this access is accomplished within the extensible SDK is - through the sysroot. - One sysroot exists per "machine" for which the SDK is being built. - In practical terms, this means a sysroot exists for the target - machine, and a sysroot exists for the build host. + The remainder of this section presents information useful when + working with recipes. </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 go 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 id='sdk-finding-logs-and-work-files'> + <title>Finding Logs and Work Files</title> + + <para> + When you are debugging a recipe that you previously created using + <filename>devtool add</filename> or whose source you are modifying + by using the <filename>devtool modify</filename> command, after + the first run of <filename>devtool build</filename>, you will + find some symbolic links created within the source tree: + <filename>oe-logs</filename>, which points to the directory in + which log files and run scripts for each build step are created + and <filename>oe-workdir</filename>, which points to the temporary + work area for the recipe. + You can use these links to get more information on what is + happening at each build step. + </para> + + <para> + These locations under <filename>oe-workdir</filename> are + particularly useful: + <itemizedlist> + <listitem><para><filename>image/</filename>: + Contains all of the files installed at 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> + </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 build host. + For example, an application linking to a common library needs + access to the library itself and its associated headers. + The way this access is accomplished within the extensible SDK is + through the sysroot. + One sysroot exists per "machine" for which the SDK is being built. + In practical terms, this means a sysroot exists for the target + machine, and a sysroot exists for the build host. + </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 go 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 several other packages. + This separation is done because not all of those installed files + are always 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 that has optional modules or + plugins might do 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, + 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 is named the + same 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-packaging'> - <title>Packaging</title> + <section id='sdk-restoring-the-target-device-to-its-original-state'> + <title>Restoring the Target Device to its Original State</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 several other packages. - This separation is done because not all of those installed files - are always 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 that has optional modules or - plugins might do 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, - 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 is named the - same 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> to restore those files - and remove any other files the recipe deployed. - Consider the following example: - <literallayout class='monospaced'> + 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> 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 at once thus restoring the target device back to its - original state: - <literallayout class='monospaced'> + </literallayout> + If you have deployed multiple applications, you can remove them + all at once thus restoring the target device back 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> command do not - currently interact with any package management system on the - target device (e.g. RPM or OPKG). - Consequently, you should not intermingle operations - <filename>devtool deploy-target</filename> and the package - manager operations on the target device. - Doing so could result in a conflicting set of files. - </note> - </para> -</section> + </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> command do not + currently interact with any package management system on the + target device (e.g. RPM or OPKG). + Consequently, you should not intermingle operations + <filename>devtool deploy-target</filename> and the 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> + <section id='sdk-installing-additional-items-into-the-extensible-sdk'> + <title>Installing Additional Items Into the Extensible SDK</title> - <para> - The extensible SDK typically only comes with a small number of tools - and libraries out of the box. - If you have a minimal SDK, then it starts mostly empty and is - populated on-demand. - However, sometimes you will need to 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 it. - You can use the following command to find out: - <literallayout class='monospaced'> + <para> + The extensible SDK typically only comes with a small number of tools + and libraries out of the box. + If you have a minimal SDK, then it starts mostly empty and is + populated on-demand. + However, sometimes you will need to 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 it. + 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'> + </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> 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'> + </literallayout> + By default, the <filename>devtool sdk-install</filename> 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 it using the <filename>devtool add</filename> command. - </para> -</section> + </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 it using the <filename>devtool add</filename> command. + </para> + </section> -<section id='sdk-updating-the-extensible-sdk'> - <title>Updating the Extensible SDK</title> + <section id='sdk-updating-the-extensible-sdk'> + <title>Updating the Extensible SDK</title> - <para> - If you are working with an extensible SDK that gets occasionally - updated (e.g. typically when that SDK has been provided to you by - another party), then you will need to manually pull down those - updates to your installed SDK. - </para> + <para> + If you are working with an extensible SDK that gets occasionally + updated (e.g. typically when that SDK has been provided to you by + another party), then you will need to manually pull down those + updates to your installed SDK. + </para> - <para> - To update your installed SDK, run the following: - <literallayout class='monospaced'> + <para> + To update your installed SDK, run the following: + <literallayout class='monospaced'> $ devtool sdk-update - </literallayout> - The previous command assumes your SDK provider has set the default - update URL for you. - If that URL has not been set, you need to specify it yourself as - follows: - <literallayout class='monospaced'> + </literallayout> + The previous command assumes your SDK provider has set the default + update URL for you. + If that URL has not been set, you need to specify it yourself 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 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> + </literallayout> + <note> + The URL needs to point specifically to a published SDK and not an + SDK installer that you would download and install. + </note> + </para> + </section> - <para> - You might need to produce an SDK that contains your own custom - libraries for sending to a third party (e.g., if you are a vendor with - customers needing to build their own software for the target platform). - If that is the case, then you can produce a derivative SDK based on - the currently installed SDK fairly easily. - Use 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 above procedure takes the recipes added to the workspace and - constructs a new SDK installer containing those recipes and the - resulting binary artifacts. - The recipes go into their own separate layer in the constructed - derivative SDK, leaving the workspace clean and ready for users - to add their own recipes. - </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 for sending to a third party (e.g., if you are a vendor with + customers needing to build their own software for the target platform). + If that is the case, then you can produce a derivative SDK based on + the currently installed SDK fairly easily. + Use 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 above procedure takes the recipes added to the workspace and + constructs a new SDK installer containing those recipes and the + resulting binary artifacts. + The recipes go into their own separate layer in the constructed + derivative SDK, leaving the workspace clean and ready for users + to add their own recipes. + </para> + </section> </chapter> <!-- vim: expandtab tw=80 ts=4 |