<title>Obtaining the SDK</title>
-<section id='sdk-appendix-obtain-manual-development-notes'>
- <title>Manual Development Notes for Scott and Paul</title>
+<section id='sdk-locating-pre-built-sdk-installers'>
+ <title>Locating Pre-Built SDK Installers</title>
- <para role='writernotes'>
- This chapter is going to cover details about the installed SDK and perhaps
- stuff on locating it (e.g. the naming scheme used to identify the
- <filename>.sh</filename> installation script.
+ <para>
+ You can use existing, pre-built toolchains by locating and running
+ an SDK installer script that ships with the Yocto Project.
+ Using this method, you select and download an architecture-specific
+ toolchain installer and then run the script to hand-install the
+ toolchain.
+ </para>
+
+ <para>
+ You can find SDK installers here:
+ <itemizedlist>
+ <listitem><para><emphasis>Standard SDK Installers</emphasis>
+ Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
+ and find the folder that matches your host development system
+ (i.e. <filename>i686</filename> for 32-bit machines or
+ <filename>x86_64</filename> for 64-bit machines).</para>
+
+ <para>Go into that folder and download the toolchain installer
+ whose name includes the appropriate target architecture.
+ The toolchains provided by the Yocto Project are based off of
+ the <filename>core-image-sato</filename> image and contain
+ libraries appropriate for developing against that image.
+ For example, if your host development system is a 64-bit x86
+ system and you are going to use your cross-toolchain for a
+ 32-bit x86 target, go into the <filename>x86_64</filename>
+ folder and download the following installer:
+ <literallayout class='monospaced'>
+ poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Extensible SDK Installers</emphasis>
+ Installers for the extensible SDK are in
+ <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='sdk-optionally-building-a-toolchain-installer'>
+ <title>Optionally Building a Toolchain Installer</title>
+
+ <para>
+ As an alternative to locating and downloading a toolchain installer,
+ you can build the toolchain installer if you have a
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+ <note>
+ Although not the preferred method, it is also possible to use
+ <filename>bitbake meta-toolchain</filename> to build the toolchain
+ installer.
+ If you do use this method, you must separately install and extract
+ the target sysroot.
+ For information on how to install the sysroot, see the
+ "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
+ section.
+ </note>
+ </para>
+
+ <para>
+ To build the toolchain installer for a standard SDK and populate
+ the SDK image, use the following command:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>image</replaceable> -c populate_sdk
+ </literallayout>
+ You can do the same for the extensible SDK using this command:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext
+ </literallayout>
+ These commands result in a toolchain installer that contains the sysroot
+ that matches your target root filesystem.
+ </para>
+
+ <para>
+ Another powerful feature is that the toolchain is completely
+ self-contained.
+ The binaries are linked against their own copy of
+ <filename>libc</filename>, which results in no dependencies
+ on the target system.
+ To achieve this, the pointer to the dynamic loader is
+ configured at install time since that path cannot be dynamically
+ altered.
+ This is the reason for a wrapper around the
+ <filename>populate_sdk</filename> and
+ <filename>populate_sdk_ext</filename> archives.
</para>
- <para role='writernotes'>
- The idea here is to gather all the current information in the regular
- YP doc set that describes how to locate, download, or build out the SDK.
+ <para>
+ Another feature is that only one set of cross-canadian toolchain
+ binaries are produced per architecture.
+ This feature takes advantage of the fact that the target hardware can
+ be passed to <filename>gcc</filename> as a set of compiler options.
+ Those options are set up by the environment script and contained in
+ variables such as
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
+ This reduces the space needed for the tools.
+ Understand, however, that a sysroot is still needed for every target
+ since those binaries are target-specific.
+ </para>
+
+ <para>
+ Remember, before using any BitBake command, you
+ must source the build environment setup script
+ (i.e.
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
+ located in the Source Directory and you must make sure your
+ <filename>conf/local.conf</filename> variables are correct.
+ In particular, you need to be sure the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ variable matches the architecture for which you are building and that
+ the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
+ variable is correctly set if you are building a toolchain designed to
+ run on an architecture that differs from your current development host
+ machine (i.e. the build machine).
</para>
- <para role='writernotes'>
- One thing that needs discussed is any differences between getting the
- standard SDK as compared to the extended SDK.
- Do we have pre-build extensible SDKs laying around?
- Where do we get any pre-built SDKs from?
- Show the methods by which the user builds out the SDK?
+ <para>
+ When the <filename>bitbake</filename> command completes, the toolchain
+ installer will be in
+ <filename>tmp/deploy/sdk</filename> in the Build Directory.
+ <note>
+ By default, this toolchain does not build static binaries.
+ If you want to use the toolchain to build these types of libraries,
+ you need to be sure your image has the appropriate static
+ development libraries.
+ Use the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
+ variable inside your <filename>local.conf</filename> file to
+ install the appropriate library packages.
+ Following is an example using <filename>glibc</filename> static
+ development libraries:
+ <literallayout class='monospaced'>
+ IMAGE_INSTALL_append = " glibc-staticdev"
+ </literallayout>
+ </note>
+ </para>
+</section>
+
+<section id='sdk-extracting-the-root-filesystem'>
+ <title>Extracting the Root Filesystem</title>
+
+ <para>
+ After installing the toolchain or building it using BitBake,
+ you need a root filesystem, which you need to separately extract.
+ </para>
+
+ <para>
+ Here are some cases where you need to extract the root filesystem:
+ <itemizedlist>
+ <listitem><para>You want to boot the image using NFS.
+ </para></listitem>
+ <listitem><para>You want to use the root filesystem as the
+ target sysroot.
+ For example, the Eclipse IDE environment with the Eclipse
+ Yocto Plug-in installed allows you to use QEMU to boot
+ under NFS.</para></listitem>
+ <listitem><para>You want to develop your target application
+ using the root filesystem as the target sysroot.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ To extract the root filesystem, first <filename>source</filename>
+ the cross-development environment setup script to establish
+ necessary environment variables.
+ If you built the toolchain in the Build Directory, you will find
+ the toolchain environment script in the
+ <filename>tmp</filename> directory.
+ If you installed the toolchain by hand, the environment setup
+ script is located in <filename>/opt/poky/&DISTRO;</filename>.
+ </para>
+
+ <para>
+ After sourcing the environment script, use the
+ <filename>runqemu-extract-sdk</filename> command and provide the
+ filesystem image.
+ </para>
+
+ <para>
+ Following is an example.
+ The second command sets up the environment.
+ In this case, the setup script is located in the
+ <filename>/opt/poky/&DISTRO;</filename> directory.
+ The third command extracts the root filesystem from a previously
+ built filesystem that is located in the
+ <filename>~/Downloads</filename> directory.
+ Furthermore, this command extracts the root filesystem into the
+ <filename>qemux86-sato</filename> directory:
+ <literallayout class='monospaced'>
+ $ cd ~
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ $ runqemu-extract-sdk \
+ ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
+ $HOME/qemux86-sato
+ </literallayout>
+ You could now point to the target sysroot at
+ <filename>qemux86-sato</filename>.
</para>
</section>
</para>
</section>
+<section id='sdk-installed-extensible-sdk-directory-structure'>
+ <title>Installed Extensible SDK Directory Structure</title>
+
+ <para>
+ The following figure shows the resulting directory structure after
+ you install the Extensible SDK by running the <filename>.sh</filename>
+ SDK installation script:
+ </para>
+
+ <para>
+ <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="60" align="center" />
+ </para>
+
+ <para>
+ The installed directory structure for the extensible SDK is quite
+ different than the installed structure for the standard SDK.
+ The extensible SDK does not separate host and target parts in the
+ same manner as does the standard SDK.
+ The extensible SDK uses an embedded copy of the build system, which
+ has its own sysroots.
+ </para>
+
+ <para>
+ Of note in the directory structure are an environment setup script
+ for the SDK, a configuration file for the target, a version file for
+ the target, and a log file for the build system preparation script run
+ by the installer.
+ </para>
+
+ <para>
+ Within the figure, italicized text is used to indicate replaceable
+ portions of the file or directory name.
+ For example,
+ <replaceable>install_dir</replaceable> is the directory where the SDK
+ is installed, which is <filename>poky_sdk</filename> by default.
+ <replaceable>target</replaceable> represents the target
+ architecture (e.g. <filename>i586</filename>) and
+ <replaceable>host</replaceable> represents the development system's
+ architecture (e.g. <filename>x86_64</filename>).
+ </para>
+</section>
+
</appendix>
<!--
vim: expandtab tw=80 ts=4
<title>Using the Extensible SDK</title>
-<para role='writernotes'>
- This chapter describes what you need on your machine in order to use
- an extensible SDK.
- The chapter does not repeat information that also applies to using the
- standard SDK.
- The chapter also includes procedures of tasks you can perform using
- an extensible SDK.
- <note>
- The tasks you can perform using a standard SDK are also available
- using an extensible SDK.
- For information on using the standard SDK, see the
- "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>"
- chapter.
- </note>
+<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 build system.
</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>
- <para role='writernotes'>
- Here is a list of items I think need addressed in this section:
+ <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 role='writernotes'><emphasis>Cover differences in the development
- that might be impacted because they are using an extensible
- SDK</emphasis></para>
- <para role='writernotes'>Presumably, the various development scenarios are
- covered regarding setup in the previous chapter.
- Are these impacted because the developer is going to now be
- using an extensible SDK?
- If so, what are the implications?
+ <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.
</para></listitem>
- <listitem><para role='writernotes'><emphasis>What new recommendations exist now that
- the developer is going to be using an extensible SDK?</emphasis></para>
- <para role='writernotes'>We should cover the most common development scenarios
- that apply when using an extensible SDK.
- Is there a recommended development flow we want to present
- when using an extensible SDK?
- What conditions in a development scenario warrant use of
- the extensible SDK as compared to the standard SDK?
- </para></listitem>
- <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set
- up the extensible SDK?</emphasis></para>
- <para role='writernotes'>Is it just a matter of building out the SDK using
- <filename>bitbake -c populate_sdk_ext</filename>?
- Is there a pre-built extensible SDK laying around they can
- find and download if they are using a machine that does not
- have YP installed, which would prevent them from building their
- own SDK?
+ <listitem><para><emphasis>Build Tools and Build System:</emphasis>
+ The extensible SDK installer performs additional tasks as
+ compared to the standard SDK installer.
+ The extensible SDK installer extracts build tools specific
+ to the SDK and the installer also prepares the build system.
+ Here is example output for running the extensible SDK
+ installer:
+ <literallayout class='monospaced'>
+ $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.1+snapshot.sh
+ Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.1+snapshot
+ ===================================================================================
+ 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:
+ <literallayout class='monospaced'>
+ $ 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='sdk-using-the-extensible-sdk-to-task-1'>
- <title>Using the Extensible SDK to <replaceable>item 1</replaceable></title>
+<section id='sdk-use-devtool-to-add-an-application'>
+ <title>Use <filename>devtool add</filename> to Add an Application</title>
- <para role='writernotes'>
- Describe the specific task you are going to accomplish with the
- extensible SDK.
- Provide a diagram showing the rough flow of the task.
- Provide specific steps using a real example that works through the
- task.
+ <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.
+ As always, if required <filename>devtool</filename> 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>:
+ <note>
+ You could use <filename>bitbake</filename> to build
+ the recipe as well.
+ </note>
+ <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>Optionally Update the Recipe With Patch Files</emphasis>:
+ Once you are satisfied with the recipe, if you have made
+ any changes to the source tree that you want to have
+ applied by the recipe, you need to generate patches
+ from those changes.
+ You do this before moving the recipe
+ to its final layer and cleaning up the workspace area
+ <filename>devtool</filename> uses.
+ This optional step is especially relevant if you are
+ using or adding third-party software.</para>
+ <para>To convert commits created using Git to patch files,
+ use the <filename>devtool update-recipe</filename> command.
+ <note>
+ Any changes you want to turn into patches must be
+ committed to the Git repository in the source tree.
+ </note>
+ <literallayout class='monospaced'>
+ $ devtool update-recipe <replaceable>recipe</replaceable>
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
+ Before cleaning up the workspace, you need to move the
+ final recipe to its permanent layer.
+ You must do this before using the
+ <filename>devtool reset</filename> command if you want to
+ retain the recipe.
+ </para></listitem>
+ <listitem><para><emphasis>Reset the Recipe</emphasis>:
+ As a final step, you can restore the state such that
+ standard layers and the upstream source is used to build
+ the recipe rather than data in the workspace.
+ To reset the recipe, use the <filename>devtool reset</filename>
+ command:
+ <literallayout class='monospaced'>
+ $ devtool reset <replaceable>recipe</replaceable>
+ </literallayout>
+ </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.
+ 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>Optionally Create Patch Files for Your Changes</emphasis>:
+ After you have debugged your changes, you can
+ use <filename>devtool update-recipe</filename> to
+ generate patch files for all the commits you have
+ made.
+ <note>
+ Patch files are generated only for changes
+ you have committed.
+ </note>
+ <literallayout class='monospaced'>
+ $ devtool update-recipe <replaceable>recipe</replaceable>
+ </literallayout>
+ By default, the
+ <filename>devtool update-recipe</filename> command
+ creates the patch files in a folder named the same
+ as the recipe beneath the folder in which the recipe
+ resides, and updates the recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ statement to point to the generated patch files.
+ <note>
+ You can use the
+ "--append <replaceable>LAYERDIR</replaceable>"
+ option to cause the command to create append files
+ in a specific layer rather than the default
+ recipe layer.
+ </note>
+ </para></listitem>
+ <listitem><para><emphasis>Restore the Workspace</emphasis>:
+ The <filename>devtool reset</filename> restores the
+ state so that standard layers and upstream sources are
+ used to build the recipe rather than what is in the
+ workspace.
+ <literallayout class='monospaced'>
+ $ devtool reset <replaceable>recipe</replaceable>
+ </literallayout>
+ </para></listitem>
+ </orderedlist>
</para>
</section>
<section id='sdk-standard-sdk-intro'>
<title>Why use the Standard SDK and What is in It?</title>
- <para role='writernotes'>
- <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
+ <para>
+ Fundamentally, the standard SDK exists so that you can access
+ cross-development tools.
This paragraph describes why you use the Standard SDK.
Probably need to compare that against why you would not be interested
in the extensible SDK here as well.
If there is more detail, I need to know about it.
</para>
- <para role='writernotes'>
- <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
- Here is a list of items I think need addressed in these early
- sections:
- <itemizedlist>
- <listitem><para role='writernotes'><emphasis>What is your situation?</emphasis></para>
- <para role='writernotes'>In other words, is the developer on a machine that
- has YP on it?
- Are they on a machine that does not?
- Is the image they are developing against available as a
- pre-built, down-loadable image and can they get it?</para>
- <para role='writernotes'>Depending on the scenario, there are different ways
- to make sure the machine they are using is ready to use a
- standard SDK.
- I think we need to cover the various situations in this
- section.
- </para></listitem>
- <listitem><para role='writernotes'><emphasis>What are the recommendations?</emphasis></para>
- <para role='writernotes'>What is the most common development scenario?
- Is there a recommended development flow we want to present
- when using a standard SDK?
- What conditions in a development scenario warrant use of
- just the standard SDK as compared to the extensible SDK?
- </para></listitem>
- <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set up
- the standard SDK?</emphasis></para>
- <para role='writernotes'>There is a ton of setup information in the
- current ADT manual regarding getting, building, and installing
- an SDK.
- We would ignore the stuff about the ADT installer script
- since I presume that is going away.
- But, there are steps to download and existing
- <filename>.sh</filename> install script, build out the
- toolchains assuming your system has YP on it and you can run
- BitBake, getting the root filesystem, getting an image so you
- run QEMU on your system, etc.
- </para></listitem>
- </itemizedlist>
- </para>
-
<para>
The installed Standard SDK consists of several files and directories.
Basically, it contains an SDK environment setup script, some
into <filename>/opt/poky</filename>.
However, when you run the SDK installer, you can choose an
installation directory.
+ <note>
+ You must change the permissions on the toolchain
+ installer script so that it is executable.
+ </note>
</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 32-bit x86 target architecture.
- When you run the installer, the script prompts you for a
- system password so that you permissions can change enabling
- you to run the installer script.
The example assumes the toolchain installer is located in
<filename>~/Downloads/</filename>.
<note>
run the installer again.
</note>
<literallayout class='monospaced'>
- $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
- Poky (Yocto Project Reference Distro) SDK installer version 2.1+snapshot
- ========================================================================
- Enter target directory for SDK (default: /opt/poky/2.1+snapshot):
- You are about to install the SDK to "/opt/poky/2.1+snapshot". Proceed[Y/n]? Y
- [sudo] password for scottrif:
- Extracting SDK.......................done
+ $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh
+ Poky (Yocto Project Reference Distro) SDK installer version 2.0
+ ===============================================================
+ Enter target directory for SDK (default: /opt/poky/2.1):
+ You are about to install the SDK to "/opt/poky/2.1". Proceed[Y/n]? Y
+ Extracting SDK.......................................................................done
Setting it up...done
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
- $ . /opt/poky/2.1+snapshot/environment-setup-i586-poky-linux
+ $ . /opt/poky/2.1/environment-setup-i586-poky-linux
</literallayout>
</para>
Environment setup scripts begin with the string
"<filename>environment-setup</filename>" and include as part of their
name the tuned target architecture.
- For example, the setup script for an IA-based target machine using
- i586 tuning and located in the default SDK installation
- directory is as follows:
+ For example, the command to source a setup script for an IA-based
+ target machine using i586 tuning and located in the default SDK
+ installation directory is as follows:
<literallayout class='monospaced'>
- $ source /opt/poky/&DISTRO;+snapshot/environment-setup-i586-poky-linux
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
</literallayout>
When you run the setup script, many environment variables are
defined:
</para>
</section>
+<section id='autotools-based-projects'>
+ <title>Autotools-Based Projects</title>
+
+ <para>
+ Once you have a suitable cross-toolchain installed, it is very easy to
+ develop a project outside of the OpenEmbedded build system.
+ This section presents a simple "Helloworld" example that shows how
+ to set up, compile, and run the project.
+ </para>
+
+ <section id='creating-and-running-a-project-based-on-gnu-autotools'>
+ <title>Creating and Running a Project Based on GNU Autotools</title>
+
+ <para>
+ Follow these steps to create a simple Autotools-based project:
+ <orderedlist>
+ <listitem><para><emphasis>Create your directory:</emphasis>
+ Create a clean directory for your project and then make
+ that directory your working location:
+ <literallayout class='monospaced'>
+ $ mkdir $HOME/helloworld
+ $ cd $HOME/helloworld
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Populate the directory:</emphasis>
+ Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
+ and <filename>configure.in</filename> files as follows:
+ <itemizedlist>
+ <listitem><para>For <filename>hello.c</filename>, include
+ these lines:
+ <literallayout class='monospaced'>
+ #include <stdio.h>
+
+ main()
+ {
+ printf("Hello World!\n");
+ }
+ </literallayout></para></listitem>
+ <listitem><para>For <filename>Makefile.am</filename>,
+ include these lines:
+ <literallayout class='monospaced'>
+ bin_PROGRAMS = hello
+ hello_SOURCES = hello.c
+ </literallayout></para></listitem>
+ <listitem><para>For <filename>configure.in</filename>,
+ include these lines:
+ <literallayout class='monospaced'>
+ AC_INIT(hello.c)
+ AM_INIT_AUTOMAKE(hello,0.1)
+ AC_PROG_CC
+ AC_PROG_INSTALL
+ AC_OUTPUT(Makefile)
+ </literallayout></para></listitem>
+ </itemizedlist></para></listitem>
+ <listitem><para><emphasis>Source the cross-toolchain
+ environment setup file:</emphasis>
+ Installation of the cross-toolchain creates a cross-toolchain
+ environment setup script in the directory that the ADT
+ was installed.
+ Before you can use the tools to develop your project, you must
+ source this setup script.
+ The script begins with the string "environment-setup" and contains
+ the machine architecture, which is followed by the string
+ "poky-linux".
+ Here is an example that sources a script from the
+ default ADT installation directory that uses the
+ 32-bit Intel x86 Architecture and the
+ &DISTRO_NAME; Yocto Project release:
+ <literallayout class='monospaced'>
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Generate the local aclocal.m4
+ files and create the configure script:</emphasis>
+ The following GNU Autotools generate the local
+ <filename>aclocal.m4</filename> files and create the
+ configure script:
+ <literallayout class='monospaced'>
+ $ aclocal
+ $ autoconf
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Generate files needed by GNU
+ coding standards:</emphasis>
+ GNU coding standards require certain files in order for the
+ project to be compliant.
+ This command creates those files:
+ <literallayout class='monospaced'>
+ $ touch NEWS README AUTHORS ChangeLog
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Generate the configure
+ file:</emphasis>
+ This command generates the <filename>configure</filename>:
+ <literallayout class='monospaced'>
+ $ automake -a
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Cross-compile the project:</emphasis>
+ This command compiles the project using the cross-compiler.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
+ environment variable provides the minimal arguments for
+ GNU configure:
+ <literallayout class='monospaced'>
+ $ ./configure ${CONFIGURE_FLAGS}
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Make and install the project:</emphasis>
+ These two commands generate and install the project into the
+ destination directory:
+ <literallayout class='monospaced'>
+ $ make
+ $ make install DESTDIR=./tmp
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Verify the installation:</emphasis>
+ This command is a simple way to verify the installation
+ of your project.
+ Running the command prints the architecture on which
+ the binary file can run.
+ This architecture should be the same architecture that
+ the installed cross-toolchain supports.
+ <literallayout class='monospaced'>
+ $ file ./tmp/usr/local/bin/hello
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Execute your project:</emphasis>
+ To execute the project in the shell, simply enter the name.
+ You could also copy the binary to the actual target hardware
+ and run the project there as well:
+ <literallayout class='monospaced'>
+ $ ./hello
+ </literallayout>
+ As expected, the project displays the "Hello World!" message.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='passing-host-options'>
+ <title>Passing Host Options</title>
+
+ <para>
+ For an Autotools-based project, you can use the cross-toolchain by just
+ passing the appropriate host option to <filename>configure.sh</filename>.
+ The host option you use is derived from the name of the environment setup
+ script found in the directory in which you installed the cross-toolchain.
+ For example, the host option for an ARM-based target that uses the GNU EABI
+ is <filename>armv5te-poky-linux-gnueabi</filename>.
+ You will notice that the name of the script is
+ <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
+ Thus, the following command works to update your project and
+ rebuild it using the appropriate cross-toolchain tools:
+ <literallayout class='monospaced'>
+ $ ./configure --host=armv5te-poky-linux-gnueabi \
+ --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
+ </literallayout>
+ <note>
+ If the <filename>configure</filename> script results in problems recognizing the
+ <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option,
+ regenerate the script to enable the support by doing the following and then
+ run the script again:
+ <literallayout class='monospaced'>
+ $ libtoolize --automake
+ $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
+ [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
+ $ autoconf
+ $ autoheader
+ $ automake -a
+ </literallayout>
+ </note>
+ </para>
+ </section>
+</section>
+
+<section id='makefile-based-projects'>
+ <title>Makefile-Based Projects</title>
+
+ <para>
+ For Makefile-based projects, the cross-toolchain environment variables
+ established by running the cross-toolchain environment setup script
+ are subject to general <filename>make</filename> rules.
+ </para>
+
+ <para>
+ To illustrate this, consider the following four cross-toolchain
+ environment variables:
+ <literallayout class='monospaced'>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
+ </literallayout>
+ Now, consider the following three cases:
+ <itemizedlist>
+ <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis>
+ Because these variables are not specifically set in the
+ <filename>Makefile</filename>, the variables retain their
+ values based on the environment.
+ </para></listitem>
+ <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis>
+ Specifically setting variables in the
+ <filename>Makefile</filename> during the build results in the
+ environment settings of the variables being overwritten.
+ </para></listitem>
+ <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis>
+ Executing the <filename>Makefile</filename> from the command
+ line results in the variables being overwritten with
+ command-line content regardless of what is being set in the
+ <filename>Makefile</filename>.
+ In this case, environment variables are not considered unless
+ you use the "-e" flag during the build:
+ <literallayout class='monospaced'>
+ $ make -e <replaceable>file</replaceable>
+ </literallayout>
+ If you use this flag, then the environment values of the
+ variables override any variables specifically set in the
+ <filename>Makefile</filename>.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ For the list of variables set up by the cross-toolchain environment
+ setup script, see the
+ "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
+ section.
+ </note>
+ </para>
+</section>
+
<section id='sdk-using-the-sdk-to-task-1'>
<title>Using the SDK to <replaceable>item 1</replaceable></title>
projects / thirdparty / openembedded / openembedded-core-contrib.git / commitdiff
