| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| |
| <chapter id='sdk-extensible'> |
| |
| <title>Using the Extensible SDK</title> |
| |
| <para> |
| This chapter describes the extensible SDK and how to install it. |
| Information covers the pieces of the SDK, how to install it, and |
| presents a look at using the <filename>devtool</filename> |
| functionality. |
| The extensible SDK makes it easy to add new applications and libraries |
| to an image, modify the source for an existing component, test |
| changes on the target hardware, and ease integration into the rest of |
| the |
| <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>. |
| <note> |
| For a side-by-side comparison of main features supported for an |
| extensible SDK as compared to a standard SDK, see the |
| "<link linkend='sdk-manual-intro'>Introduction</link>" |
| section. |
| </note> |
| </para> |
| |
| <para> |
| In addition to the functionality available through |
| <filename>devtool</filename>, you can alternatively make use of the |
| toolchain directly, for example from Makefile, Autotools, and |
| <trademark class='trade'>Eclipse</trademark>-based projects. |
| See the |
| "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>" |
| chapter for more information. |
| </para> |
| |
| <section id='sdk-extensible-sdk-intro'> |
| <title>Why use the Extensible SDK and What is in It?</title> |
| |
| <para> |
| The extensible SDK provides a cross-development toolchain and |
| libraries tailored to the contents of a specific image. |
| You would use the Extensible SDK if you want a toolchain experience |
| supplemented with the powerful set of <filename>devtool</filename> |
| commands tailored for the Yocto Project environment. |
| </para> |
| |
| <para> |
| The installed extensible SDK consists of several files and |
| directories. |
| Basically, it contains an SDK environment setup script, some |
| configuration files, an internal build system, and the |
| <filename>devtool</filename> functionality. |
| </para> |
| </section> |
| |
| <section id='sdk-installing-the-extensible-sdk'> |
| <title>Installing the Extensible SDK</title> |
| |
| <para> |
| The first thing you need to do is install the SDK on your |
| <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink> |
| by running the <filename>*.sh</filename> installation script. |
| </para> |
| |
| <para> |
| You can download a tarball installer, which includes the |
| pre-built toolchain, the <filename>runqemu</filename> |
| script, the internal build system, <filename>devtool</filename>, |
| and support files from the appropriate |
| <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink> |
| directory within the Index of Releases. |
| Toolchains are available for several 32-bit and 64-bit |
| architectures with the <filename>x86_64</filename> directories, |
| respectively. |
| The toolchains the Yocto Project provides are based off the |
| <filename>core-image-sato</filename> and |
| <filename>core-image-minimal</filename> images and contain |
| libraries appropriate for developing against that image. |
| </para> |
| |
| <para> |
| The names of the tarball installer scripts are such that a |
| string representing the host system appears first in the |
| filename and then is immediately followed by a string |
| representing the target architecture. |
| An extensible SDK has the string "-ext" as part of the name. |
| Following is the general form: |
| <literallayout class='monospaced'> |
| poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh |
| |
| Where: |
| <replaceable>host_system</replaceable> is a string representing your development system: |
| |
| i686 or x86_64. |
| |
| <replaceable>image_type</replaceable> is the image for which the SDK was built: |
| |
| core-image-sato or core-image-minimal |
| |
| <replaceable>arch</replaceable> is a string representing the tuned target architecture: |
| |
| aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon |
| |
| <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project: |
| |
| &DISTRO;, &DISTRO;+snapshot |
| </literallayout> |
| For example, the following SDK installer is for a 64-bit |
| development host system and a i586-tuned target architecture |
| based off the SDK for <filename>core-image-sato</filename> and |
| using the current &DISTRO; snapshot: |
| <literallayout class='monospaced'> |
| poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh |
| </literallayout> |
| <note> |
| As an alternative to downloading an SDK, you can build the |
| SDK installer. |
| For information on building the installer, see the |
| "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" |
| section. |
| 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> |
| The SDK and toolchains are self-contained and by default are |
| installed into the <filename>poky_sdk</filename> folder in your |
| home directory. |
| You can choose to install the extensible SDK in any location when |
| you run the installer. |
| However, because files need to be written under that directory |
| during the normal course of operation, the location you choose |
| for installation must be writable for whichever |
| users need to use the SDK. |
| </para> |
| |
| <para> |
| The following command shows how to run the installer given a |
| toolchain tarball for a 64-bit x86 development host system and |
| a 64-bit x86 target architecture. |
| The example assumes the SDK installer is located in |
| <filename>~/Downloads/</filename> and has execution rights. |
| <note> |
| If you do not have write permissions for the directory |
| into which you are installing the SDK, the installer |
| notifies you and exits. |
| For that case, set up the proper permissions in the directory |
| and run the installer again. |
| </note> |
| <literallayout class='monospaced'> |
| $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh |
| Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5 |
| ========================================================================== |
| Enter target directory for SDK (default: ~/poky_sdk): |
| You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y |
| Extracting SDK..............done |
| Setting it up... |
| Extracting buildtools... |
| Preparing build system... |
| Parsing recipes: 100% |##################################################################| Time: 0:00:52 |
| Initialising tasks: 100% |###############################################################| Time: 0:00:00 |
| Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00 |
| Loading cache: 100% |####################################################################| Time: 0:00:00 |
| Initialising tasks: 100% |###############################################################| Time: 0:00:00 |
| done |
| SDK has been successfully set up and is ready to be used. |
| Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. |
| $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux |
| |
| </literallayout> |
| </para> |
| </section> |
| |
| <section id='sdk-running-the-extensible-sdk-environment-setup-script'> |
| <title>Running the Extensible SDK Environment Setup Script</title> |
| |
| <para> |
| Once you have the SDK installed, you must run the SDK environment |
| setup script before you can actually use the SDK. |
| This setup script resides in the directory you chose when you |
| installed the SDK, which is either the default |
| <filename>poky_sdk</filename> directory or the directory you |
| chose during installation. |
| </para> |
| |
| <para> |
| Before running the script, be sure it is the one that matches the |
| architecture for which you are developing. |
| Environment setup scripts begin with the string |
| "<filename>environment-setup</filename>" and include as part of |
| their name the tuned target architecture. |
| As an example, the following commands set the working directory |
| to where the SDK was installed and then source the environment |
| setup script. |
| In this example, the setup script is for an IA-based |
| target machine using i586 tuning: |
| <literallayout class='monospaced'> |
| $ cd /home/scottrif/poky_sdk |
| $ source environment-setup-core2-64-poky-linux |
| SDK environment now set up; additionally you may now run devtool to perform development tasks. |
| Run devtool --help for further details. |
| </literallayout> |
| Running the setup script defines many environment variables needed |
| in order to use the SDK (e.g. <filename>PATH</filename>, |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>, |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>, |
| and so forth). |
| If you want to see all the environment variables the script |
| exports, examine the installation file itself. |
| </para> |
| </section> |
| |
| <section id='using-devtool-in-your-sdk-workflow'> |
| <title>Using <filename>devtool</filename> in Your SDK Workflow</title> |
| |
| <para> |
| The cornerstone of the extensible SDK is a command-line tool |
| called <filename>devtool</filename>. |
| This tool provides a number of features that help |
| you build, test and package software within the extensible SDK, and |
| optionally integrate it into an image built by the OpenEmbedded |
| build system. |
| <note><title>Tip</title> |
| The use of <filename>devtool</filename> is not limited to |
| the extensible SDK. |
| You can use <filename>devtool</filename> to help you easily |
| develop any project whose build output must be part of an |
| image built using the build system. |
| </note> |
| </para> |
| |
| <para> |
| The <filename>devtool</filename> command line is organized |
| similarly to |
| <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> in that it |
| has a number of sub-commands for each function. |
| You can run <filename>devtool --help</filename> to see all the |
| commands. |
| <note> |
| See the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename> Quick Reference</ulink>" |
| in the Yocto Project Reference Manual for a |
| <filename>devtool</filename> quick reference. |
| </note> |
| </para> |
| |
| <para> |
| Three <filename>devtool</filename> subcommands exist that provide |
| entry-points into development: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis><filename>devtool add</filename></emphasis>: |
| Assists in adding new software to be built. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>devtool modify</filename></emphasis>: |
| Sets up an environment to enable you to modify the source of |
| an existing component. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>devtool upgrade</filename></emphasis>: |
| Updates an existing recipe so that you can build it for |
| an updated set of source files. |
| </para></listitem> |
| </itemizedlist> |
| As with the build system, "recipes" represent software packages |
| within <filename>devtool</filename>. |
| When you use <filename>devtool add</filename>, a recipe is |
| automatically created. |
| When you use <filename>devtool modify</filename>, the specified |
| existing recipe is used in order to determine where to get the |
| source code and how to patch it. |
| In both cases, an environment is set up so that when you build the |
| recipe a source tree that is under your control is used in order to |
| allow you to make changes to the source as desired. |
| By default, new recipes and the source go into a "workspace" |
| directory under the SDK. |
| </para> |
| |
| <para> |
| The remainder of this section presents the |
| <filename>devtool add</filename>, |
| <filename>devtool modify</filename>, and |
| <filename>devtool upgrade</filename> workflows. |
| </para> |
| |
| <section id='sdk-use-devtool-to-add-an-application'> |
| <title>Use <filename>devtool add</filename> to Add an Application</title> |
| |
| <para> |
| The <filename>devtool add</filename> command generates |
| a new recipe based on existing source code. |
| This command takes advantage of the |
| <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink> |
| layer that many <filename>devtool</filename> commands |
| use. |
| The command is flexible enough to allow you to extract source |
| code into both the workspace or a separate local Git repository |
| and to use existing code that does not need to be extracted. |
| </para> |
| |
| <para> |
| Depending on your particular scenario, the arguments and options |
| you use with <filename>devtool add</filename> form different |
| combinations. |
| The following diagram shows common development flows |
| you would use with the <filename>devtool add</filename> |
| command: |
| </para> |
| |
| <para> |
| <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" /> |
| </para> |
| |
| <para> |
| <orderedlist> |
| <listitem><para><emphasis>Generating the New Recipe</emphasis>: |
| The top part of the flow shows three scenarios by which |
| you could use <filename>devtool add</filename> to |
| generate a recipe based on existing source code.</para> |
| |
| <para>In a shared development environment, it is |
| typical for other developers to be responsible for |
| various areas of source code. |
| As a developer, you are probably interested in using |
| that source code as part of your development within |
| the Yocto Project. |
| All you need is access to the code, a recipe, and a |
| controlled area in which to do your work.</para> |
| |
| <para>Within the diagram, three possible scenarios |
| feed into the <filename>devtool add</filename> workflow: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Left</emphasis>: |
| The left scenario in the figure represents a |
| common situation where the source code does not |
| exist locally and needs to be extracted. |
| In this situation, the source code is extracted |
| to the default workspace - you do not |
| want the files in some specific location |
| outside of the workspace. |
| Thus, everything you need will be located in |
| the workspace: |
| <literallayout class='monospaced'> |
| $ devtool add <replaceable>recipe fetchuri</replaceable> |
| </literallayout> |
| With this command, <filename>devtool</filename> |
| extracts the upstream source files into a local |
| Git repository within the |
| <filename>sources</filename> folder. |
| The command then creates a recipe named |
| <replaceable>recipe</replaceable> and a |
| corresponding append file in the workspace. |
| If you do not provide |
| <replaceable>recipe</replaceable>, the command |
| makes an attempt to determine the recipe name. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Middle</emphasis>: |
| The middle scenario in the figure also |
| represents a situation where the source code |
| does not exist locally. |
| In this case, the code is again upstream |
| and needs to be extracted to some |
| local area - this time outside of the default |
| workspace. |
| <note> |
| If required, <filename>devtool</filename> |
| always creates |
| a Git repository locally during the |
| extraction. |
| </note> |
| Furthermore, the first positional argument |
| <replaceable>srctree</replaceable> in this |
| case identifies where the |
| <filename>devtool add</filename> command |
| will locate the extracted code outside of the |
| workspace. |
| You need to specify an empty directory: |
| <literallayout class='monospaced'> |
| $ devtool add <replaceable>recipe srctree fetchuri</replaceable> |
| </literallayout> |
| In summary, the source code is pulled from |
| <replaceable>fetchuri</replaceable> and |
| extracted into the location defined by |
| <replaceable>srctree</replaceable> as a local |
| Git repository.</para> |
| |
| <para>Within workspace, |
| <filename>devtool</filename> creates a |
| recipe named <replaceable>recipe</replaceable> |
| along with an associated append file. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Right</emphasis>: |
| The right scenario in the figure represents a |
| situation where the |
| <replaceable>srctree</replaceable> has been |
| previously prepared outside of the |
| <filename>devtool</filename> workspace.</para> |
| |
| <para>The following command provides a new |
| recipe name and identifies the existing source |
| tree location: |
| <literallayout class='monospaced'> |
| $ devtool add <replaceable>recipe srctree</replaceable> |
| </literallayout> |
| The command examines the source code and |
| creates a recipe named |
| <replaceable>recipe</replaceable> for the code |
| and places the recipe into the workspace. |
| </para> |
| |
| <para>Because the extracted source code already |
| exists, <filename>devtool</filename> does not |
| try to relocate the source code into the |
| workspace - only the new recipe is placed |
| in the workspace.</para> |
| |
| <para>Aside from a recipe folder, the command |
| also creates an associated append folder and |
| places an initial |
| <filename>*.bbappend</filename> file within. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Edit the Recipe</emphasis>: |
| You can use <filename>devtool edit-recipe</filename> |
| to open up the editor as defined by the |
| <filename>$EDITOR</filename> environment variable |
| and modify the file: |
| <literallayout class='monospaced'> |
| $ devtool edit-recipe <replaceable>recipe</replaceable> |
| </literallayout> |
| From within the editor, you can make modifications to |
| the recipe that take affect when you build it later. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Build the Recipe or Rebuild the Image</emphasis>: |
| The next step you take depends on what you are going |
| to do with the new code.</para> |
| |
| <para>If you need to eventually move the build output |
| to the target hardware, use the following |
| <filename>devtool</filename> command: |
| <literallayout class='monospaced'> |
| $ devtool build <replaceable>recipe</replaceable> |
| </literallayout></para> |
| |
| <para>On the other hand, if you want an image to |
| contain the recipe's packages from the workspace |
| for immediate deployment onto a device (e.g. for |
| testing purposes), you can use |
| the <filename>devtool build-image</filename> command: |
| <literallayout class='monospaced'> |
| $ devtool build-image <replaceable>image</replaceable> |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Deploy the Build Output</emphasis>: |
| When you use the <filename>devtool build</filename> |
| command to build out your recipe, you probably want to |
| see if the resulting build output works as expected |
| on the target hardware. |
| <note> |
| This step assumes you have a previously built |
| image that is already either running in QEMU or |
| is running on actual hardware. |
| Also, it is assumed that for deployment of the |
| image to the target, SSH is installed in the image |
| and, if the image is running on real hardware, |
| you have network access to and from your |
| development machine. |
| </note> |
| You can deploy your build output to that target |
| hardware by using the |
| <filename>devtool deploy-target</filename> command: |
| <literallayout class='monospaced'> |
| $ devtool deploy-target <replaceable>recipe target</replaceable> |
| </literallayout> |
| The <replaceable>target</replaceable> is a live target |
| machine running as an SSH server.</para> |
| |
| <para>You can, of course, also deploy the image you |
| build to actual hardware by using the |
| <filename>devtool build-image</filename> command. |
| However, <filename>devtool</filename> does not provide |
| a specific command that allows you to deploy the |
| image to actual hardware. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Finish Your Work With the Recipe</emphasis>: |
| The <filename>devtool finish</filename> command creates |
| any patches corresponding to commits in the local |
| Git repository, moves the new recipe to a more permanent |
| layer, and then resets the recipe so that the recipe is |
| built normally rather than from the workspace. |
| <literallayout class='monospaced'> |
| $ devtool finish <replaceable>recipe layer</replaceable> |
| </literallayout> |
| <note> |
| Any changes you want to turn into patches must be |
| committed to the Git repository in the source tree. |
| </note></para> |
| |
| <para>As mentioned, the |
| <filename>devtool finish</filename> command moves the |
| final recipe to its permanent layer. |
| </para> |
| |
| <para>As a final process of the |
| <filename>devtool finish</filename> command, the state |
| of the standard layers and the upstream source is |
| restored so that you can build the recipe from those |
| areas rather than the workspace. |
| <note> |
| You can use the <filename>devtool reset</filename> |
| command to put things back should you decide you |
| do not want to proceed with your work. |
| If you do use this command, realize that the source |
| tree is preserved. |
| </note> |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'> |
| <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title> |
| |
| <para> |
| The <filename>devtool modify</filename> command prepares the |
| way to work on existing code that already has a local recipe in |
| place that is used to build the software. |
| The command is flexible enough to allow you to extract code |
| from an upstream source, specify the existing recipe, and |
| keep track of and gather any patch files from other developers |
| that are associated with the code. |
| </para> |
| |
| <para> |
| Depending on your particular scenario, the arguments and options |
| you use with <filename>devtool modify</filename> form different |
| combinations. |
| The following diagram shows common development flows for the |
| <filename>devtool modify</filename> command: |
| </para> |
| |
| <para> |
| <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" /> |
| </para> |
| |
| <para> |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Preparing to Modify the Code</emphasis>: |
| The top part of the flow shows three scenarios by which |
| you could use <filename>devtool modify</filename> to |
| prepare to work on source files. |
| Each scenario assumes the following: |
| <itemizedlist> |
| <listitem><para> |
| The recipe exists locally in a layer external |
| to the <filename>devtool</filename> workspace. |
| </para></listitem> |
| <listitem><para> |
| The source files exist either upstream in an |
| un-extracted state or locally in a previously |
| extracted state. |
| </para></listitem> |
| </itemizedlist> |
| The typical situation is where another developer has |
| created a layer for use with the Yocto Project and |
| their recipe already resides in that layer. |
| Furthermore, their source code is readily available |
| either upstream or locally. |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Left</emphasis>: |
| The left scenario in the figure represents a |
| common situation where the source code does |
| not exist locally and it needs to be extracted |
| from an upstream source. |
| In this situation, the source is extracted |
| into the default <filename>devtool</filename> |
| workspace location. |
| The recipe, in this scenario, is in its own |
| layer outside the workspace |
| (i.e. |
| <filename>meta-</filename><replaceable>layername</replaceable>). |
| </para> |
| |
| <para>The following command identifies the |
| recipe and, by default, extracts the source |
| files: |
| <literallayout class='monospaced'> |
| $ devtool modify <replaceable>recipe</replaceable> |
| </literallayout> |
| Once <filename>devtool</filename>locates the |
| recipe, <filename>devtool</filename> uses the |
| recipe's |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| statements to locate the source code and any |
| local patch files from other developers.</para> |
| |
| <para>With this scenario, no |
| <replaceable>srctree</replaceable> argument |
| exists. |
| Consequently, the default behavior of the |
| <filename>devtool modify</filename> command is |
| to extract the source files pointed to by the |
| <filename>SRC_URI</filename> statements into a |
| local Git structure. |
| Furthermore, the location for the extracted |
| source is the default area within the |
| <filename>devtool</filename> workspace. |
| The result is that the command sets up both |
| the source code and an append file within the |
| workspace while the recipe remains in its |
| original location. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Middle</emphasis>: |
| The middle scenario in the figure represents a |
| situation where the source code also does not |
| exist locally. |
| In this case, the code is again upstream |
| and needs to be extracted to some |
| local area as a Git repository. |
| The recipe, in this scenario, is again local |
| and in its own layer outside the workspace. |
| </para> |
| |
| <para>The following command tells |
| <filename>devtool</filename> 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 |
| <filename>devtool</filename> workspace: |
| <literallayout class='monospaced'> |
| $ devtool modify <replaceable>recipe srctree</replaceable> |
| </literallayout> |
| <note> |
| You cannot provide a URL for |
| <replaceable>srctree</replaceable> using |
| the <filename>devtool</filename> command. |
| </note> |
| As with all extractions, the command uses |
| the recipe's <filename>SRC_URI</filename> |
| statements to locate the source files and any |
| associated patch files. |
| Once the files are located, the command by |
| default extracts them into |
| <replaceable>srctree</replaceable>.</para> |
| |
| <para>Within workspace, |
| <filename>devtool</filename> creates an append |
| file for the recipe. |
| The recipe remains in its original location but |
| the source files are extracted to the location |
| you provide with |
| <replaceable>srctree</replaceable>. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Right</emphasis>: |
| The right scenario in the figure represents a |
| situation where the source tree |
| (<replaceable>srctree</replaceable>) already |
| exists locally as a previously extracted Git |
| structure outside of the |
| <filename>devtool</filename> workspace. |
| In this example, the recipe also exists |
| elsewhere locally in its own layer. |
| </para> |
| |
| <para>The following command tells |
| <filename>devtool</filename> the recipe |
| with which to work, uses the "-n" option to |
| indicate source does not need to be extracted, |
| and uses <replaceable>srctree</replaceable> to |
| point to the previously extracted source files: |
| <literallayout class='monospaced'> |
| $ devtool modify -n <replaceable>recipe srctree</replaceable> |
| </literallayout> |
| </para> |
| |
| <para>Once the command finishes, it creates only |
| an append file for the recipe in the |
| <filename>devtool</filename> workspace. |
| The recipe and the source code remain in their |
| original locations. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Edit the Source</emphasis>: |
| Once you have used the |
| <filename>devtool modify</filename> command, you are |
| free to make changes to the source files. |
| You can use any editor you like to make and save |
| your source code modifications. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Build the Recipe or Rebuild the Image</emphasis>: |
| The next step you take depends on what you are going |
| to do with the new code.</para> |
| |
| <para>If you need to eventually move the build output |
| to the target hardware, use the following |
| <filename>devtool</filename> command: |
| <literallayout class='monospaced'> |
| $ devtool build <replaceable>recipe</replaceable> |
| </literallayout></para> |
| |
| <para>On the other hand, if you want an image to |
| contain the recipe's packages from the workspace |
| for immediate deployment onto a device (e.g. for |
| testing purposes), you can use |
| the <filename>devtool build-image</filename> command: |
| <literallayout class='monospaced'> |
| $ devtool build-image <replaceable>image</replaceable> |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Deploy the Build Output</emphasis>: |
| When you use the <filename>devtool build</filename> |
| command to build out your recipe, you probably want to |
| see if the resulting build output works as expected |
| on target hardware. |
| <note> |
| This step assumes you have a previously built |
| image that is already either running in QEMU or |
| running on actual hardware. |
| Also, it is assumed that for deployment of the image |
| to the target, SSH is installed in the image and if |
| the image is running on real hardware that you have |
| network access to and from your development machine. |
| </note> |
| You can deploy your build output to that target |
| hardware by using the |
| <filename>devtool deploy-target</filename> command: |
| <literallayout class='monospaced'> |
| $ devtool deploy-target <replaceable>recipe target</replaceable> |
| </literallayout> |
| The <replaceable>target</replaceable> is a live target |
| machine running as an SSH server.</para> |
| |
| <para>You can, of course, use other methods to deploy |
| the image you built using the |
| <filename>devtool build-image</filename> command to |
| actual hardware. |
| <filename>devtool</filename> does not provide |
| a specific command to deploy the image to actual |
| hardware. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Finish Your Work With the Recipe</emphasis>: |
| The <filename>devtool finish</filename> command creates |
| any patches corresponding to commits in the local |
| Git repository, updates the recipe to point to them |
| (or creates a <filename>.bbappend</filename> file to do |
| so, depending on the specified destination layer), and |
| then resets the recipe so that the recipe is built |
| normally rather than from the workspace. |
| <literallayout class='monospaced'> |
| $ devtool finish <replaceable>recipe layer</replaceable> |
| </literallayout> |
| <note> |
| Any changes you want to turn into patches must be |
| staged and committed within the local Git |
| repository before you use the |
| <filename>devtool finish</filename> command. |
| </note></para> |
| |
| <para>Because there is no need to move the recipe, |
| <filename>devtool finish</filename> either updates the |
| original recipe in the original layer or the command |
| creates a <filename>.bbappend</filename> file in a |
| different layer as provided by |
| <replaceable>layer</replaceable>.</para> |
| |
| <para>As a final process of the |
| <filename>devtool finish</filename> command, the state |
| of the standard layers and the upstream source is |
| restored so that you can build the recipe from those |
| areas rather than from the workspace. |
| <note> |
| You can use the <filename>devtool reset</filename> |
| command to put things back should you decide you |
| do not want to proceed with your work. |
| If you do use this command, realize that the source |
| tree is preserved. |
| </note> |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'> |
| <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title> |
| |
| <para> |
| The <filename>devtool upgrade</filename> command upgrades |
| an existing recipe to that of a more up-to-date version |
| found upstream. |
| Throughout the life of software, recipes continually undergo |
| version upgrades by their upstream publishers. |
| You can use the <filename>devtool upgrade</filename> |
| workflow to make sure your recipes you are using for builds |
| are up-to-date with their upstream counterparts. |
| <note> |
| Several methods exist by which you can upgrade recipes - |
| <filename>devtool upgrade</filename> happens to be one. |
| You can read about all the methods by which you can |
| upgrade recipes in the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>" |
| section of the Yocto Project Development Tasks Manual. |
| </note> |
| </para> |
| |
| <para> |
| The <filename>devtool upgrade</filename> command is flexible |
| enough to allow you to specify source code revision and |
| versioning schemes, extract code into or out of the |
| <filename>devtool</filename> |
| <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>, |
| and work with any source file forms that the fetchers support. |
| </para> |
| |
| <para> |
| The following diagram shows the common development flow |
| used with the <filename>devtool upgrade</filename> command: |
| </para> |
| |
| <para> |
| <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" /> |
| </para> |
| |
| <para> |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Initiate the Upgrade</emphasis>: |
| The top part of the flow shows the typical scenario by |
| which you use the <filename>devtool upgrade</filename> |
| command. |
| The following conditions exist: |
| <itemizedlist> |
| <listitem><para> |
| The recipe exists in a local layer external |
| to the <filename>devtool</filename> workspace. |
| </para></listitem> |
| <listitem><para> |
| The source files for the new release |
| exist in the same location pointed to by |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| in the recipe (e.g. a tarball with the new |
| version number in the name, or as a different |
| revision in the upstream Git repository). |
| </para></listitem> |
| </itemizedlist> |
| A common situation is where third-party software has |
| undergone a revision so that it has been upgraded. |
| The recipe you have access to is likely in your own |
| layer. |
| Thus, you need to upgrade the recipe to use the |
| newer version of the software: |
| <literallayout class='monospaced'> |
| $ devtool upgrade -V <replaceable>version recipe</replaceable> |
| </literallayout> |
| By default, the <filename>devtool upgrade</filename> |
| command extracts source code into the |
| <filename>sources</filename> directory in the |
| <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>. |
| If you want the code extracted to any other location, |
| you need to provide the |
| <replaceable>srctree</replaceable> positional argument |
| with the command as follows: |
| <literallayout class='monospaced'> |
| $ devtool upgrade -V <replaceable>version recipe srctree</replaceable> |
| </literallayout> |
| <note> |
| In this example, the "-V" option specifies the new |
| version. |
| If you don't use "-V", the command upgrades the |
| recipe to the latest version. |
| </note> |
| If the source files pointed to by the |
| <filename>SRC_URI</filename> statement in the recipe |
| are in a Git repository, you must provide the "-S" |
| option and specify a revision for the software.</para> |
| |
| <para>Once <filename>devtool</filename> locates the |
| recipe, it uses the <filename>SRC_URI</filename> |
| variable to locate the source code and any local patch |
| files from other developers. |
| The result is that the command sets up the source |
| code, the new version of the recipe, and an append file |
| all within the workspace. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Resolve any Conflicts created by the Upgrade</emphasis>: |
| Conflicts could exist due to the software being |
| upgraded to a new version. |
| Conflicts occur if your recipe specifies some patch |
| files in <filename>SRC_URI</filename> that conflict |
| with changes made in the new version of the software. |
| For such cases, you need to resolve the conflicts |
| by editing the source and following the normal |
| <filename>git rebase</filename> conflict resolution |
| process.</para> |
| |
| <para>Before moving onto the next step, be sure to |
| resolve any such conflicts created through use of a |
| newer or different version of the software. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Build the Recipe or Rebuild the Image</emphasis>: |
| The next step you take depends on what you are going |
| to do with the new code.</para> |
| |
| <para>If you need to eventually move the build output |
| to the target hardware, use the following |
| <filename>devtool</filename> command: |
| <literallayout class='monospaced'> |
| $ devtool build <replaceable>recipe</replaceable> |
| </literallayout></para> |
| |
| <para>On the other hand, if you want an image to |
| contain the recipe's packages from the workspace |
| for immediate deployment onto a device (e.g. for |
| testing purposes), you can use |
| the <filename>devtool build-image</filename> command: |
| <literallayout class='monospaced'> |
| $ devtool build-image <replaceable>image</replaceable> |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Deploy the Build Output</emphasis>: |
| When you use the <filename>devtool build</filename> |
| command or <filename>bitbake</filename> to build |
| your recipe, you probably want to see if the resulting |
| build output works as expected on target hardware. |
| <note> |
| This step assumes you have a previously built |
| image that is already either running in QEMU or |
| running on actual hardware. |
| Also, it is assumed that for deployment of the |
| image to the target, SSH is installed in the image |
| and if the image is running on real hardware that |
| you have network access to and from your |
| development machine. |
| </note> |
| You can deploy your build output to that target |
| hardware by using the |
| <filename>devtool deploy-target</filename> command: |
| <literallayout class='monospaced'> |
| $ devtool deploy-target <replaceable>recipe target</replaceable> |
| </literallayout> |
| The <replaceable>target</replaceable> is a live target |
| machine running as an SSH server.</para> |
| |
| <para>You can, of course, also deploy the image you |
| build using the |
| <filename>devtool build-image</filename> command |
| to actual hardware. |
| However, <filename>devtool</filename> does not provide |
| a specific command that allows you to do this. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Finish Your Work With the Recipe</emphasis>: |
| The <filename>devtool finish</filename> command creates |
| any patches corresponding to commits in the local |
| Git repository, moves the new recipe to a more |
| permanent layer, and then resets the recipe so that |
| the recipe is built normally rather than from the |
| workspace. |
| If you specify a destination layer that is the same as |
| the original source, then the old version of the |
| recipe and associated files will be removed prior to |
| adding the new version. |
| <literallayout class='monospaced'> |
| $ devtool finish <replaceable>recipe layer</replaceable> |
| </literallayout> |
| <note> |
| Any changes you want to turn into patches must be |
| committed to the Git repository in the source tree. |
| </note></para> |
| |
| <para>As a final process of the |
| <filename>devtool finish</filename> command, the state |
| of the standard layers and the upstream source is |
| restored so that you can build the recipe from those |
| areas rather than the workspace. |
| <note> |
| You can use the <filename>devtool reset</filename> |
| command to put things back should you decide you |
| do not want to proceed with your work. |
| If you do use this command, realize that the source |
| tree is preserved. |
| </note> |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| </section> |
| |
| <section id='sdk-a-closer-look-at-devtool-add'> |
| <title>A Closer Look at <filename>devtool add</filename></title> |
| |
| <para> |
| The <filename>devtool add</filename> command automatically creates |
| a recipe based on the source tree you provide with the command. |
| Currently, the command has support for the following: |
| <itemizedlist> |
| <listitem><para> |
| Autotools (<filename>autoconf</filename> and |
| <filename>automake</filename>) |
| </para></listitem> |
| <listitem><para> |
| CMake |
| </para></listitem> |
| <listitem><para> |
| Scons |
| </para></listitem> |
| <listitem><para> |
| <filename>qmake</filename> |
| </para></listitem> |
| <listitem><para> |
| Plain <filename>Makefile</filename> |
| </para></listitem> |
| <listitem><para> |
| Out-of-tree kernel module |
| </para></listitem> |
| <listitem><para> |
| Binary package (i.e. "-b" option) |
| </para></listitem> |
| <listitem><para> |
| Node.js module |
| </para></listitem> |
| <listitem><para> |
| Python modules that use <filename>setuptools</filename> |
| or <filename>distutils</filename> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| Apart from binary packages, the determination of how a source tree |
| should be treated is automatic based on the files present within |
| that source tree. |
| For example, if a <filename>CMakeLists.txt</filename> file is found, |
| then the source tree is assumed to be using |
| CMake and is treated accordingly. |
| <note> |
| In most cases, you need to edit the automatically generated |
| recipe in order to make it build properly. |
| Typically, you would go through several edit and build cycles |
| until the recipe successfully builds. |
| Once the recipe builds, you could use possible further |
| iterations to test the recipe on the target device. |
| </note> |
| </para> |
| |
| <para> |
| The remainder of this section covers specifics regarding how parts |
| of the recipe are generated. |
| </para> |
| |
| <section id='sdk-name-and-version'> |
| <title>Name and Version</title> |
| |
| <para> |
| If you do not specify a name and version on the command |
| line, <filename>devtool add</filename> uses various metadata |
| within the source tree in an attempt to determine |
| the name and version of the software being built. |
| Based on what the tool determines, <filename>devtool</filename> |
| sets the name of the created recipe file accordingly. |
| </para> |
| |
| <para> |
| If <filename>devtool</filename> cannot determine the name and |
| version, the command prints an error. |
| For such cases, you must re-run the command and provide |
| the name and version, just the name, or just the version as |
| part of the command line. |
| </para> |
| |
| <para> |
| Sometimes the name or version determined from the source tree |
| might be incorrect. |
| For such a case, you must reset the recipe: |
| <literallayout class='monospaced'> |
| $ devtool reset -n <replaceable>recipename</replaceable> |
| </literallayout> |
| After running the <filename>devtool reset</filename> command, |
| you need to run <filename>devtool add</filename> again and |
| provide the name or the version. |
| </para> |
| </section> |
| |
| <section id='sdk-dependency-detection-and-mapping'> |
| <title>Dependency Detection and Mapping</title> |
| |
| <para> |
| The <filename>devtool add</filename> command attempts to |
| detect build-time dependencies and map them to other recipes |
| in the system. |
| During this mapping, the command fills in the names of those |
| recipes as part of the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> |
| variable within the recipe. |
| If a dependency cannot be mapped, <filename>devtool</filename> |
| places a comment in the recipe indicating such. |
| The inability to map a dependency can result from naming not |
| being recognized or because the dependency simply is not |
| available. |
| For cases where the dependency is not available, you must use |
| the <filename>devtool add</filename> command to add an |
| additional recipe that satisfies the dependency. |
| Once you add that recipe, you need to update the |
| <filename>DEPENDS</filename> variable in the original recipe |
| to include the new recipe. |
| </para> |
| |
| <para> |
| If you need to add runtime dependencies, you can do so by |
| adding the following to your recipe: |
| <literallayout class='monospaced'> |
| RDEPENDS_${PN} += "<replaceable>dependency1 dependency2 ...</replaceable>" |
| </literallayout> |
| <note> |
| The <filename>devtool add</filename> command often cannot |
| distinguish between mandatory and optional dependencies. |
| Consequently, some of the detected dependencies might |
| in fact be optional. |
| When in doubt, consult the documentation or the configure |
| script for the software the recipe is building for further |
| details. |
| In some cases, you might find you can substitute the |
| dependency with an option that disables the associated |
| functionality passed to the configure script. |
| </note> |
| </para> |
| </section> |
| |
| <section id='sdk-license-detection'> |
| <title>License Detection</title> |
| |
| <para> |
| The <filename>devtool add</filename> command attempts to |
| determine if the software you are adding is able to be |
| distributed under a common, open-source license. |
| If so, the command sets the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> |
| value accordingly. |
| You should double-check the value added by the command against |
| the documentation or source files for the software you are |
| building and, if necessary, update that |
| <filename>LICENSE</filename> value. |
| </para> |
| |
| <para> |
| The <filename>devtool add</filename> command also sets the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> |
| value to point to all files that appear to be license-related. |
| Realize that license statements often appear in comments at |
| the top of source files or within the documentation. |
| In such cases, the command does not recognize those license |
| statements. |
| Consequently, you might need to amend the |
| <filename>LIC_FILES_CHKSUM</filename> variable to point to one |
| or more of those comments if present. |
| Setting <filename>LIC_FILES_CHKSUM</filename> is particularly |
| important for third-party software. |
| The mechanism attempts to ensure correct licensing should you |
| upgrade the recipe to a newer upstream version in future. |
| Any change in licensing is detected and you receive an error |
| prompting you to check the license text again. |
| </para> |
| |
| <para> |
| If the <filename>devtool add</filename> command cannot |
| determine licensing information, <filename>devtool</filename> |
| sets the <filename>LICENSE</filename> value to "CLOSED" and |
| leaves the <filename>LIC_FILES_CHKSUM</filename> value unset. |
| This behavior allows you to continue with development even |
| though the settings are unlikely to be correct in all cases. |
| You should check the documentation or source files for the |
| software you are building to determine the actual license. |
| </para> |
| </section> |
| |
| <section id='sdk-adding-makefile-only-software'> |
| <title>Adding Makefile-Only Software</title> |
| |
| <para> |
| The use of Make by itself is very common in both proprietary |
| and open-source software. |
| Unfortunately, Makefiles are often not written with |
| cross-compilation in mind. |
| Thus, <filename>devtool add</filename> often cannot do very |
| much to ensure that these Makefiles build correctly. |
| It is very common, for example, to explicitly call |
| <filename>gcc</filename> instead of using the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> |
| variable. |
| Usually, in a cross-compilation environment, |
| <filename>gcc</filename> is the compiler for the build host |
| and the cross-compiler is named something similar to |
| <filename>arm-poky-linux-gnueabi-gcc</filename> and might |
| require arguments (e.g. to point to the associated sysroot |
| for the target machine). |
| </para> |
| |
| <para> |
| When writing a recipe for Makefile-only software, keep the |
| following in mind: |
| <itemizedlist> |
| <listitem><para> |
| You probably need to patch the Makefile to use |
| variables instead of hardcoding tools within the |
| toolchain such as <filename>gcc</filename> and |
| <filename>g++</filename>. |
| </para></listitem> |
| <listitem><para> |
| The environment in which Make runs is set up with |
| various standard variables for compilation (e.g. |
| <filename>CC</filename>, <filename>CXX</filename>, and |
| so forth) in a similar manner to the environment set |
| up by the SDK's environment setup script. |
| One easy way to see these variables is to run the |
| <filename>devtool build</filename> command on the |
| recipe and then look in |
| <filename>oe-logs/run.do_compile</filename>. |
| Towards the top of this file, a list of environment |
| variables exists that are being set. |
| You can take advantage of these variables within the |
| Makefile. |
| </para></listitem> |
| <listitem><para> |
| If the Makefile sets a default for a variable using "=", |
| that default overrides the value set in the environment, |
| which is usually not desirable. |
| For this case, you can either patch the Makefile |
| so it sets the default using the "?=" operator, or |
| you can alternatively force the value on the |
| <filename>make</filename> command line. |
| To force the value on the command line, add the |
| variable setting to |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink> |
| or |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> |
| within the recipe. |
| Here is an example using <filename>EXTRA_OEMAKE</filename>: |
| <literallayout class='monospaced'> |
| EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" |
| </literallayout> |
| In the above example, single quotes are used around the |
| variable settings as the values are likely to contain |
| spaces because required default options are passed to |
| the compiler. |
| </para></listitem> |
| <listitem><para> |
| Hardcoding paths inside Makefiles is often problematic |
| in a cross-compilation environment. |
| This is particularly true because those hardcoded paths |
| often point to locations on the build host and thus |
| will either be read-only or will introduce |
| contamination into the cross-compilation because they |
| are specific to the build host rather than the target. |
| Patching the Makefile to use prefix variables or other |
| path variables is usually the way to handle this |
| situation. |
| </para></listitem> |
| <listitem><para> |
| Sometimes a Makefile runs target-specific commands such |
| as <filename>ldconfig</filename>. |
| For such cases, you might be able to apply patches that |
| remove these commands from the Makefile. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='sdk-adding-native-tools'> |
| <title>Adding Native Tools</title> |
| |
| <para> |
| Often, you need to build additional tools that run on the |
| <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink> |
| as opposed to the target. |
| You should indicate this requirement by using one of the |
| following methods when you run |
| <filename>devtool add</filename>: |
| <itemizedlist> |
| <listitem><para> |
| Specify the name of the recipe such that it ends |
| with "-native". |
| Specifying the name like this produces a recipe that |
| only builds for the build host. |
| </para></listitem> |
| <listitem><para> |
| Specify the "‐‐also-native" option with the |
| <filename>devtool add</filename> command. |
| Specifying this option creates a recipe file that still |
| builds for the target but also creates a variant with |
| a "-native" suffix that builds for the build host. |
| </para></listitem> |
| </itemizedlist> |
| <note> |
| If you need to add a tool that is shipped as part of a |
| source tree that builds code for the target, you can |
| typically accomplish this by building the native and target |
| parts separately rather than within the same compilation |
| process. |
| Realize though that with the "‐‐also-native" |
| option, you can add the tool using just one recipe file. |
| </note> |
| </para> |
| </section> |
| |
| <section id='sdk-adding-node-js-modules'> |
| <title>Adding Node.js Modules</title> |
| |
| <para> |
| You can use the <filename>devtool add</filename> command two |
| different ways to add Node.js modules: 1) Through |
| <filename>npm</filename> and, 2) from a repository or local |
| source. |
| </para> |
| |
| <para> |
| Use the following form to add Node.js modules through |
| <filename>npm</filename>: |
| <literallayout class='monospaced'> |
| $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" |
| </literallayout> |
| The name and version parameters are mandatory. |
| Lockdown and shrinkwrap files are generated and pointed to by |
| the recipe in order to freeze the version that is fetched for |
| the dependencies according to the first time. |
| This also saves checksums that are verified on future fetches. |
| Together, these behaviors ensure the reproducibility and |
| integrity of the build. |
| <note><title>Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| You must use quotes around the URL. |
| The <filename>devtool add</filename> does not require |
| the quotes, but the shell considers ";" as a splitter |
| between multiple commands. |
| Thus, without the quotes, |
| <filename>devtool add</filename> does not receive the |
| other parts, which results in several "command not |
| found" errors. |
| </para></listitem> |
| <listitem><para> |
| In order to support adding Node.js modules, a |
| <filename>nodejs</filename> recipe must be part |
| of your SDK. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| </para> |
| |
| <para> |
| As mentioned earlier, you can also add Node.js modules |
| directly from a repository or local source tree. |
| To add modules this way, use <filename>devtool add</filename> |
| in the following form: |
| <literallayout class='monospaced'> |
| $ devtool add https://github.com/diversario/node-ssdp |
| </literallayout> |
| In this example, <filename>devtool</filename> fetches the |
| specified Git repository, detects the code as Node.js |
| code, fetches dependencies using <filename>npm</filename>, and |
| sets |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| accordingly. |
| </para> |
| </section> |
| </section> |
| |
| <section id='sdk-working-with-recipes'> |
| <title>Working With Recipes</title> |
| |
| <para> |
| When building a recipe using the |
| <filename>devtool build</filename> command, the typical build |
| progresses as follows: |
| <orderedlist> |
| <listitem><para> |
| Fetch the source |
| </para></listitem> |
| <listitem><para> |
| Unpack the source |
| </para></listitem> |
| <listitem><para> |
| Configure the source |
| </para></listitem> |
| <listitem><para> |
| Compile the source |
| </para></listitem> |
| <listitem><para> |
| Install the build output |
| </para></listitem> |
| <listitem><para> |
| Package the installed output |
| </para></listitem> |
| </orderedlist> |
| For recipes in the workspace, fetching and unpacking is disabled |
| as the source tree has already been prepared and is persistent. |
| Each of these build steps is defined as a function (task), usually |
| with a "do_" prefix (e.g. |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>, |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>, |
| and so forth). |
| These functions are typically shell scripts but can instead be |
| written in Python. |
| </para> |
| |
| <para> |
| If you look at the contents of a recipe, you will see that the |
| recipe does not include complete instructions for building the |
| software. |
| Instead, common functionality is encapsulated in classes inherited |
| with the <filename>inherit</filename> directive. |
| This technique leaves the recipe to describe just the things that |
| are specific to the software being built. |
| A |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink> |
| class exists that is implicitly inherited by all recipes and |
| provides the functionality that most recipes typically need. |
| </para> |
| |
| <para> |
| The remainder of this section presents information useful when |
| working with recipes. |
| </para> |
| |
| <section id='sdk-finding-logs-and-work-files'> |
| <title>Finding Logs and Work Files</title> |
| |
| <para> |
| After the first run of the <filename>devtool build</filename> |
| command, recipes that were previously created using the |
| <filename>devtool add</filename> command or whose sources were |
| modified using the <filename>devtool modify</filename> |
| command contain symbolic links created within the source tree: |
| <itemizedlist> |
| <listitem><para> |
| <filename>oe-logs</filename>: |
| This link points to the directory in which log files |
| and run scripts for each build step are created. |
| </para></listitem> |
| <listitem><para> |
| <filename>oe-workdir</filename>: |
| This link points to the temporary work area for the |
| recipe. |
| The following locations under |
| <filename>oe-workdir</filename> are particularly |
| useful: |
| <itemizedlist> |
| <listitem><para> |
| <filename>image/</filename>: |
| Contains all of the files installed during |
| the |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> |
| stage. |
| Within a recipe, this directory is referred |
| to by the expression |
| <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>. |
| </para></listitem> |
| <listitem><para> |
| <filename>sysroot-destdir/</filename>: |
| Contains a subset of files installed within |
| <filename>do_install</filename> that have |
| been put into the shared sysroot. |
| For more information, see the |
| "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>" |
| section. |
| </para></listitem> |
| <listitem><para> |
| <filename>packages-split/</filename>: |
| Contains subdirectories for each package |
| produced by the recipe. |
| For more information, see the |
| "<link linkend='sdk-packaging'>Packaging</link>" |
| section. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| </itemizedlist> |
| You can use these links to get more information on what is |
| happening at each build step. |
| </para> |
| </section> |
| |
| <section id='sdk-setting-configure-arguments'> |
| <title>Setting Configure Arguments</title> |
| |
| <para> |
| If the software your recipe is building uses GNU autoconf, |
| then a fixed set of arguments is passed to it to enable |
| cross-compilation plus any extras specified by |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink> |
| or |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> |
| set within the recipe. |
| If you wish to pass additional options, add them to |
| <filename>EXTRA_OECONF</filename> or |
| <filename>PACKAGECONFIG_CONFARGS</filename>. |
| Other supported build tools have similar variables |
| (e.g. |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink> |
| for CMake, |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink> |
| for Scons, and so forth). |
| If you need to pass anything on the <filename>make</filename> |
| command line, you can use <filename>EXTRA_OEMAKE</filename> or the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> |
| variables to do so. |
| </para> |
| |
| <para> |
| You can use the <filename>devtool configure-help</filename> command |
| to help you set the arguments listed in the previous paragraph. |
| The command determines the exact options being passed, and shows |
| them to you along with any custom arguments specified through |
| <filename>EXTRA_OECONF</filename> or |
| <filename>PACKAGECONFIG_CONFARGS</filename>. |
| If applicable, the command also shows you the output of the |
| configure script's "‐‐help" option as a reference. |
| </para> |
| </section> |
| |
| <section id='sdk-sharing-files-between-recipes'> |
| <title>Sharing Files Between Recipes</title> |
| |
| <para> |
| Recipes often need to use files provided by other recipes on |
| the |
| <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>. |
| For example, an application linking to a common library needs |
| access to the library itself and its associated headers. |
| The way this access is accomplished within the extensible SDK is |
| through the sysroot. |
| One sysroot exists per "machine" for which the SDK is being |
| built. |
| In practical terms, this means a sysroot exists for the target |
| machine, and a sysroot exists for the build host. |
| </para> |
| |
| <para> |
| Recipes should never write files directly into the sysroot. |
| Instead, files should be installed into standard locations |
| during the |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> |
| task within the |
| <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename> |
| directory. |
| A subset of these files automatically goes into the sysroot. |
| The reason for this limitation is that almost all files that go |
| into the sysroot are cataloged in manifests in order to ensure |
| they can be removed later when a recipe is modified or removed. |
| Thus, the sysroot is able to remain free from stale files. |
| </para> |
| </section> |
| |
| <section id='sdk-packaging'> |
| <title>Packaging</title> |
| |
| <para> |
| Packaging is not always particularly relevant within the |
| extensible SDK. |
| However, if you examine how build output gets into the final image |
| on the target device, it is important to understand packaging |
| because the contents of the image are expressed in terms of |
| packages and not recipes. |
| </para> |
| |
| <para> |
| During the |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> |
| task, files installed during the |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> |
| task are split into one main package, which is almost always |
| named the same as the recipe, and into several other packages. |
| This separation exists because not all of those installed files |
| are useful in every image. |
| For example, you probably do not need any of the documentation |
| installed in a production image. |
| Consequently, for each recipe the documentation files are |
| separated into a <filename>-doc</filename> package. |
| Recipes that package software containing optional modules or |
| plugins might undergo additional package splitting as well. |
| </para> |
| |
| <para> |
| After building a recipe, you can see where files have gone by |
| looking in the <filename>oe-workdir/packages-split</filename> |
| directory, which contains a subdirectory for each package. |
| Apart from some advanced cases, the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink> |
| and |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink> |
| variables controls splitting. |
| The <filename>PACKAGES</filename> variable lists all of the |
| packages to be produced, while the <filename>FILES</filename> |
| variable specifies which files to include in each package by |
| using an override to specify the package. |
| For example, <filename>FILES_${PN}</filename> specifies the |
| files to go into the main package (i.e. the main package has |
| the same name as the recipe and |
| <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> |
| evaluates to the recipe name). |
| The order of the <filename>PACKAGES</filename> value is |
| significant. |
| For each installed file, the first package whose |
| <filename>FILES</filename> value matches the file is the |
| package into which the file goes. |
| Defaults exist for both the <filename>PACKAGES</filename> and |
| <filename>FILES</filename> variables. |
| Consequently, you might find you do not even need to set these |
| variables in your recipe unless the software the recipe is |
| building installs files into non-standard locations. |
| </para> |
| </section> |
| </section> |
| |
| <section id='sdk-restoring-the-target-device-to-its-original-state'> |
| <title>Restoring the Target Device to its Original State</title> |
| |
| <para> |
| If you use the <filename>devtool deploy-target</filename> |
| command to write a recipe's build output to the target, and |
| you are working on an existing component of the system, then you |
| might find yourself in a situation where you need to restore the |
| original files that existed prior to running the |
| <filename>devtool deploy-target</filename> command. |
| Because the <filename>devtool deploy-target</filename> command |
| backs up any files it overwrites, you can use the |
| <filename>devtool undeploy-target</filename> command to restore |
| those files and remove any other files the recipe deployed. |
| Consider the following example: |
| <literallayout class='monospaced'> |
| $ devtool undeploy-target lighttpd root@192.168.7.2 |
| </literallayout> |
| If you have deployed multiple applications, you can remove them |
| all using the "-a" option thus restoring the target device to its |
| original state: |
| <literallayout class='monospaced'> |
| $ devtool undeploy-target -a root@192.168.7.2 |
| </literallayout> |
| Information about files deployed to the target as well as any |
| backed up files are stored on the target itself. |
| This storage, of course, requires some additional space |
| on the target machine. |
| <note> |
| The <filename>devtool deploy-target</filename> and |
| <filename>devtool undeploy-target</filename> commands do not |
| currently interact with any package management system on the |
| target device (e.g. RPM or OPKG). |
| Consequently, you should not intermingle |
| <filename>devtool deploy-target</filename> and package |
| manager operations on the target device. |
| Doing so could result in a conflicting set of files. |
| </note> |
| </para> |
| </section> |
| |
| <section id='sdk-installing-additional-items-into-the-extensible-sdk'> |
| <title>Installing Additional Items Into the Extensible SDK</title> |
| |
| <para> |
| Out of the box the extensible SDK typically only comes with a small |
| number of tools and libraries. |
| A minimal SDK starts mostly empty and is populated on-demand. |
| Sometimes you must explicitly install extra items into the SDK. |
| If you need these extra items, you can first search for the items |
| using the <filename>devtool search</filename> command. |
| For example, suppose you need to link to libGL but you are not sure |
| which recipe provides libGL. |
| You can use the following command to find out: |
| <literallayout class='monospaced'> |
| $ devtool search libGL |
| mesa A free implementation of the OpenGL API |
| </literallayout> |
| Once you know the recipe (i.e. <filename>mesa</filename> in this |
| example), you can install it: |
| <literallayout class='monospaced'> |
| $ devtool sdk-install mesa |
| </literallayout> |
| By default, the <filename>devtool sdk-install</filename> command |
| assumes the item is available in pre-built form from your SDK |
| provider. |
| If the item is not available and it is acceptable to build the item |
| from source, you can add the "-s" option as follows: |
| <literallayout class='monospaced'> |
| $ devtool sdk-install -s mesa |
| </literallayout> |
| It is important to remember that building the item from source |
| takes significantly longer than installing the pre-built artifact. |
| Also, if no recipe exists for the item you want to add to the SDK, |
| you must instead add the item using the |
| <filename>devtool add</filename> command. |
| </para> |
| </section> |
| |
| <section id='sdk-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> |
| 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'> |
| $ 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> |
| |
| <para> |
| You might need to produce an SDK that contains your own custom |
| libraries. |
| A good example would be if you were a vendor with customers that |
| use your SDK to build their own platform-specific software and |
| those customers need an SDK that has custom libraries. |
| In such a case, you can produce a derivative SDK based on the |
| currently installed SDK fairly easily by following these steps: |
| <orderedlist> |
| <listitem><para> |
| If necessary, install an extensible SDK that |
| you want to use as a base for your derivative SDK. |
| </para></listitem> |
| <listitem><para> |
| Source the environment script for the SDK. |
| </para></listitem> |
| <listitem><para> |
| Add the extra libraries or other components you want by |
| using the <filename>devtool add</filename> command. |
| </para></listitem> |
| <listitem><para> |
| Run the <filename>devtool build-sdk</filename> command. |
| </para></listitem> |
| </orderedlist> |
| The previous steps take the recipes added to the workspace and |
| construct a new SDK installer that contains those recipes and the |
| resulting binary artifacts. |
| The recipes go into their own separate layer in the constructed |
| derivative SDK, which leaves the workspace clean and ready for |
| users to add their own recipes. |
| </para> |
| </section> |
| </chapter> |
| <!-- |
| vim: expandtab tw=80 ts=4 |
| --> |