diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2016-03-02 08:48:50 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2016-03-23 21:56:07 +0000 |
commit | 0bb6e48a334d8ab7bedb7da9444a3a1b812ef996 (patch) | |
tree | e9d613f7153b7453fd2e7606278378258a8e8ddc | |
parent | 5a647013e52a25843aef17947c442cdbfb794fd3 (diff) | |
download | openembedded-core-contrib-0bb6e48a334d8ab7bedb7da9444a3a1b812ef996.tar.gz |
sdk-manual: WIP on the book.
(From yocto-docs rev: 140577dd1f91c096152354e711709efe64bbcd0e)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/sdk-manual/sdk-appendix-obtain.xml | 256 | ||||
-rw-r--r-- | documentation/sdk-manual/sdk-extensible.xml | 566 | ||||
-rw-r--r-- | documentation/sdk-manual/sdk-using.xml | 297 |
3 files changed, 998 insertions, 121 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml index eada4cc8ed..8b245615c9 100644 --- a/documentation/sdk-manual/sdk-appendix-obtain.xml +++ b/documentation/sdk-manual/sdk-appendix-obtain.xml @@ -6,26 +6,210 @@ <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> @@ -70,6 +254,48 @@ </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 diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml index c238dee382..bc9ccd28d3 100644 --- a/documentation/sdk-manual/sdk-extensible.xml +++ b/documentation/sdk-manual/sdk-extensible.xml @@ -6,69 +6,537 @@ <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> diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml index 66f2c0ed9d..f2acaa7fc4 100644 --- a/documentation/sdk-manual/sdk-using.xml +++ b/documentation/sdk-manual/sdk-using.xml @@ -23,8 +23,9 @@ <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. @@ -37,46 +38,6 @@ 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 @@ -161,15 +122,16 @@ 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> @@ -180,17 +142,16 @@ 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> @@ -221,11 +182,11 @@ 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: @@ -256,6 +217,228 @@ </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> |