diff options
author | Brad Bishop <bradleyb@fuzziesquirrel.com> | 2018-06-25 12:45:53 -0400 |
---|---|---|
committer | Brad Bishop <bradleyb@fuzziesquirrel.com> | 2018-06-27 14:38:15 -0400 |
commit | 316dfdd917bec6a218f431211d28bf8df6b6fb0f (patch) | |
tree | 5541073f9851f44c2bd67b4959dc776ee3c3810f /import-layers/yocto-poky/documentation/sdk-manual | |
parent | 36acd3e888044dea2ac0b2946f15616f968388c9 (diff) | |
download | blackbird-openbmc-316dfdd917bec6a218f431211d28bf8df6b6fb0f.tar.gz blackbird-openbmc-316dfdd917bec6a218f431211d28bf8df6b6fb0f.zip |
Yocto 2.5
Move OpenBMC to Yocto 2.5(sumo)
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Change-Id: I5c5ad6904a16e14c1c397f0baf10c9d465594a78
Diffstat (limited to 'import-layers/yocto-poky/documentation/sdk-manual')
14 files changed, 1398 insertions, 1010 deletions
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-autotools-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-autotools-flow.png Binary files differnew file mode 100644 index 000000000..ec6685f8b --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-autotools-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png Binary files differindex 985ac331f..e7d6173d2 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png Binary files differindex fd684ffbe..18ba8b7e6 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png Binary files differindex 65474dad0..7d4f395e2 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-makefile-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-makefile-flow.png Binary files differnew file mode 100644 index 000000000..0ccb4180a --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-makefile-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml index 587526f65..5b56e738d 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml @@ -387,8 +387,9 @@ have set <filename>SDK_EXT_TYPE</filename> to "minimal", which by default, excludes the toolchain. Also, it is helpful if you are building a small SDK for use with - an IDE, such as Eclipse, or some other tool where you do not want - to take extra steps to install a toolchain. + an IDE, such as <trademark class='trade'>Eclipse</trademark>, or some + other tool where you do not want to take extra steps to install a + toolchain. </para> </section> </appendix> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-neon.xml index 2d80f644d..f648047ef 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-neon.xml @@ -2,14 +2,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<appendix id='sdk-appendix-latest-yp-eclipse-plug-in'> - <title>Using Eclipse Mars</title> +<appendix id='sdk-appendix-neon-yp-eclipse-plug-in'> + <title>Using <trademark class='trade'>Eclipse</trademark> Neon</title> <para> - This release of the Yocto Project supports both the Neon and Mars + This release of the Yocto Project supports both the Oxygen and Neon versions of the Eclipse IDE. This appendix presents information that describes how to obtain and - configure the Mars version of Eclipse. + configure the Neon version of Eclipse. It also provides a basic project example that you can work through from start to finish. For general information on using the Eclipse IDE and the Yocto @@ -18,13 +18,13 @@ Chapter. </para> - <section id='mars-setting-up-the-eclipse-ide'> - <title>Setting Up the Mars Version of the Eclipse IDE</title> + <section id='neon-setting-up-the-eclipse-ide'> + <title>Setting Up the Neon Version of the Eclipse IDE</title> <para> To develop within the Eclipse IDE, you need to do the following: <orderedlist> - <listitem><para>Install the Mars version of the Eclipse + <listitem><para>Install the Neon version of the Eclipse IDE.</para></listitem> <listitem><para>Configure the Eclipse IDE. </para></listitem> @@ -41,65 +41,49 @@ </note> </para> - <section id='mars-installing-eclipse-ide'> - <title>Installing the Mars Eclipse IDE</title> + <section id='neon-installing-eclipse-ide'> + <title>Installing the Neon Eclipse IDE</title> <para> Follow these steps to locate, install, and configure - Mars Eclipse: + Neon Eclipse: <orderedlist> - <listitem><para><emphasis>Locate the Mars Download:</emphasis> + <listitem><para><emphasis>Locate the Neon Download:</emphasis> Open a browser and go to - <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/mars/</ulink>. + <ulink url='http://www.eclipse.org/neon/'>http://www.eclipse.org/neon/</ulink>. </para></listitem> <listitem><para><emphasis>Download the Tarball:</emphasis> - Click the "Download" button and then use the "Linux - for Eclipse IDE for C++ Developers" - appropriate for your development system - (e.g. - <ulink url='http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/mars/2/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz'>64-bit under Linux for Eclipse IDE for C++ Developers</ulink> - if your development system is a Linux 64-bit machine. + Click the "Download" button and then use the "Eclipse + IDE for C/C++ Developers" + appropriate for your development system. </para></listitem> <listitem><para><emphasis>Unpack the Tarball:</emphasis> Move to a clean directory and unpack the tarball. Here is an example: <literallayout class='monospaced'> $ cd ~ - $ tar -xzvf ~/Downloads/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz + $ tar -xzvf ~/Downloads/eclipse-cpp-neon-3-linux-gtk-x86_64.tar.gz </literallayout> Everything unpacks into a folder named "Eclipse". </para></listitem> <listitem><para><emphasis>Launch Eclipse:</emphasis> - Double click the "Eclipse" file in the folder to - launch Eclipse. - <note> - If you experience a NullPointer Exception after - launch Eclipse or the debugger from within Eclipse, - try adding the following - to your <filename>eclipse.ini</filename> file, - which is located in the directory in which you - unpacked the Eclipse tar file: - <literallayout class='monospaced'> - --launcher.GTK_version - 2 - </literallayout> - Alternatively, you can export the - <filename>SWT_GTK</filename> variable in your - shell as follows: - <literallayout class='monospaced'> - $ export SWT_GTK3=0 - </literallayout> - </note> + The following commands launch Eclipse assuming you + unpacked it in your home directory: + <literallayout class='monospaced'> + $ cd ~/eclipse + $ ./eclipse + </literallayout> + Accept the default "workspace" once Eclipse launches. </para></listitem> </orderedlist> </para> </section> - <section id='mars-configuring-the-mars-eclipse-ide'> - <title>Configuring the Mars Eclipse IDE</title> + <section id='neon-configuring-the-neon-eclipse-ide'> + <title>Configuring the Neon Eclipse IDE</title> <para> - Follow these steps to configure the Mars Eclipse IDE. + Follow these steps to configure the Neon Eclipse IDE. <note> Depending on how you installed Eclipse and what you have already done, some of the options will not appear. @@ -114,13 +98,15 @@ the "Help" pull-down menu. </para></listitem> <listitem><para>Select - "Mars - http://download.eclipse.org/releases/mars" + "Neon - http://download.eclipse.org/releases/neon" from the "Work with:" pull-down menu. </para></listitem> <listitem><para>Expand the box next to - "Linux Tools" and select "C/C++ Remote - (Over TCF/TE) Run/Debug Launcher" and - "TM Terminal". + "Linux Tools" and select the following + <literallayout class='monospaced'> + C/C++ Remote (Over TCF/TE) Run/Debug Launcher + TM Terminal + </literallayout> </para></listitem> <listitem><para>Expand the box next to "Mobile and Device Development" and select the following @@ -135,9 +121,8 @@ </para></listitem> <listitem><para>Expand the box next to "Programming Languages" and select the - following boxes: + following box: <literallayout class='monospaced'> - C/C++ Autotools Support C/C++ Development Tools SDK </literallayout> </para></listitem> @@ -149,8 +134,8 @@ </para> </section> - <section id='mars-installing-the-eclipse-yocto-plug-in'> - <title>Installing or Accessing the Mars Eclipse Yocto Plug-in</title> + <section id='neon-installing-the-eclipse-yocto-plug-in'> + <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title> <para> You can install the Eclipse Yocto Plug-in into the Eclipse @@ -159,11 +144,11 @@ install the plug-in from the latest source code. </para> - <section id='mars-new-software'> + <section id='neon-new-software'> <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> <para> - To install the Mars Eclipse Yocto Plug-in from the update + To install the Neon Eclipse Yocto Plug-in from the update site, follow these steps: <orderedlist> <listitem><para>Start up the Eclipse IDE. @@ -175,7 +160,7 @@ area. </para></listitem> <listitem><para>Enter - <filename>&ECLIPSE_DL_PLUGIN_URL;/mars</filename> + <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename> in the URL field and provide a meaningful name in the "Name" field. </para></listitem> @@ -204,15 +189,15 @@ </para> </section> - <section id='mars-zip-file-method'> + <section id='neon-zip-file-method'> <title>Installing the Plug-in Using the Latest Source Code</title> <para> - To install the Mars Eclipse Yocto Plug-in from the latest + To install the Neon Eclipse Yocto Plug-in from the latest source code, follow these steps: <orderedlist> <listitem><para>Be sure your development system - has JDK 1.7+ + has JDK 1.8+ </para></listitem> <listitem><para>install X11-related packages: <literallayout class='monospaced'> @@ -223,15 +208,18 @@ repository with: <literallayout class='monospaced'> $ cd ~ - $ git clone git://git.yoctoproject.org/eclipse-poky + $ git clone git://git.yoctoproject.org/eclipse-yocto </literallayout> </para></listitem> <listitem><para>Use Git to checkout the correct tag: <literallayout class='monospaced'> - $ cd ~/eclipse-poky - $ git checkout mars/yocto-&DISTRO; + $ cd ~/eclipse-yocto + $ git checkout neon/yocto-&DISTRO; </literallayout> + This creates a local tag named + <filename>neon/yocto-&DISTRO;</filename> based on + the branch <filename>origin/neon-master</filename>. This puts you in a detached HEAD state, which is fine since you are only going to be building and not developing. @@ -262,10 +250,10 @@ <para> Following is an example: <literallayout class='monospaced'> - $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l mars/yocto-&DISTRO; master yocto-&DISTRO; 2>&1 | tee build.log + $ ECLIPSE_HOME=/home/scottrif/eclipse-yocto/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&1 | tee build.log </literallayout> The previous example command adds the tag you - need for <filename>mars/yocto-&DISTRO;</filename> + need for <filename>neon/yocto-&DISTRO;</filename> to <filename>HEAD</filename>, then tells the build script to use the local (-l) Git checkout for the build. @@ -316,16 +304,16 @@ <para> At this point you should be able to configure the Eclipse Yocto Plug-in as described in the - "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>" + "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" section.</para> </section> </section> - <section id='mars-configuring-the-eclipse-yocto-plug-in'> - <title>Configuring the Mars Eclipse Yocto Plug-in</title> + <section id='neon-configuring-the-eclipse-yocto-plug-in'> + <title>Configuring the Neon Eclipse Yocto Plug-in</title> <para> - Configuring the Mars Eclipse Yocto Plug-in involves setting the + Configuring the Neon Eclipse Yocto Plug-in involves setting the Cross Compiler options and the Target options. The configurations you choose become the default settings for all projects. @@ -355,7 +343,7 @@ </note> </para> - <section id='mars-configuring-the-cross-compiler-options'> + <section id='neon-configuring-the-cross-compiler-options'> <title>Configuring the Cross-Compiler Options</title> <para> @@ -467,9 +455,9 @@ If the architecture you need is not listed in the menu, you will need to build the image. See the - "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" - section of the Yocto Project Quick Start for - more information. + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>" + section of the Yocto Project Development Tasks + Manual for more information. You can also see the <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. </para></listitem> @@ -477,7 +465,7 @@ </para> </section> - <section id='mars-configuring-the-target-options'> + <section id='neon-configuring-the-target-options'> <title>Configuring the Target Options</title> <para> @@ -547,7 +535,7 @@ </section> </section> - <section id='mars-creating-the-project'> + <section id='neon-creating-the-project'> <title>Creating the Project</title> <para> @@ -562,7 +550,7 @@ <note> Do not use special characters in project names (e.g. spaces, underscores, etc.). Doing so can - cause configuration to fail. + cause the configuration to fail. </note> </para> @@ -591,7 +579,7 @@ <listitem><para>Click "Finish". </para></listitem> <listitem><para>If the "open perspective" prompt appears, - click "Yes" so that you in the C/C++ perspective. + click "Yes" so that you are in the C/C++ perspective. </para></listitem> <listitem><para>The left-hand navigation pane shows your project. @@ -602,12 +590,12 @@ </para> </section> - <section id='mars-configuring-the-cross-toolchains'> + <section id='neon-configuring-the-cross-toolchains'> <title>Configuring the Cross-Toolchains</title> <para> The earlier section, - "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>", + "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>", sets up the default project configurations. You can override these settings for a given project by following these steps: @@ -621,7 +609,7 @@ Options for a project are inherited from settings you provided using the Preferences Dialog as described earlier in the - "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>" section. + "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" section. The Yocto Project Settings Dialog allows you to override those default settings for a given project. </para></listitem> @@ -646,7 +634,7 @@ </para> </section> - <section id='mars-building-the-project'> + <section id='neon-building-the-project'> <title>Building the Project</title> <para> @@ -691,7 +679,7 @@ </para> </section> - <section id='mars-starting-qemu-in-user-space-nfs-mode'> + <section id='neon-starting-qemu-in-user-space-nfs-mode'> <title>Starting QEMU in User-Space NFS Mode</title> <para> @@ -761,7 +749,7 @@ </para> </section> - <section id='mars-deploying-and-debugging-the-application'> + <section id='neon-deploying-and-debugging-the-application'> <title>Deploying and Debugging the Application</title> <para> @@ -845,7 +833,8 @@ which is the default for QEMU x86-64 SDK images provided by the Yocto Project, in the "Remote Absolute File Path for C/C++ Application" field, browse to - <filename>/home/root</filename>. + <filename>/home/root/</filename><replaceable>ProjectName</replaceable> + (e.g. <filename>/home/root/hello</filename>). You could also browse to any other path you have write access to on the target such as <filename>/usr/bin</filename>. @@ -893,7 +882,7 @@ </para> </section> - <section id='mars-using-Linuxtools'> + <section id='neon-using-Linuxtools'> <title>Using Linuxtools</title> <para> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml index ab9055e62..aa06358a0 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml @@ -105,7 +105,7 @@ <emphasis>Set Up the Build Environment:</emphasis> Be sure you are set up to use BitBake in a shell. See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>" + "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>" section in the Yocto Project Development Tasks Manual for information on how to get a build host ready that is either a native Linux machine or a machine that uses CROPS. @@ -203,7 +203,7 @@ <listitem><para> For additional information on building the installer, see the - <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an <trademark class='trade'>Eclipse</trademark> Debug Capable Image</ulink> wiki page. </para></listitem> </itemizedlist> @@ -327,7 +327,7 @@ <para>Following is an example command that extracts the root filesystem from a previously built root filesystem image that was downloaded from the - <ulink url='&YOCTO_DOCS_REF_URL;#index-downloads'>Index of Releases</ulink>. + <ulink url='&YOCTO_DOCS_OM_URL;#index-downloads'>Index of Releases</ulink>. This command extracts the root filesystem into the <filename>core2-64-sato</filename> directory: <literallayout class='monospaced'> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml index bdb8344cb..3eb85e8ab 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml @@ -19,8 +19,8 @@ <para> The following figure and supporting list summarize the - application development general workflow that employs both the - SDK Eclipse. + general workflow for application development that uses the + SDK within the Eclipse IDE. </para> <para> @@ -31,9 +31,8 @@ <para> <orderedlist> <listitem><para> - <emphasis>Prepare the host system for the Yocto - Project</emphasis>: - See + <emphasis>Prepare the Host System for the Yocto Project</emphasis>: + See the "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" and "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" @@ -43,8 +42,8 @@ <filename>xterm</filename> package installed. </para></listitem> <listitem><para> - <emphasis>Secure the Yocto Project kernel target - image</emphasis>: + <emphasis>Secure the Yocto Project Kernel Target + Image</emphasis>: You must have a target kernel image that has been built using the OpenEmbedded build system.</para> <para>Depending on whether the Yocto Project has a @@ -66,7 +65,8 @@ <filename>machines/qemu</filename></ulink> if your target architecture is supported and you are going to develop and test your application - using the QEMU emulator. + using the + <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>QEMU Emulator</ulink>. </para></listitem> <listitem><para> Build your image if you cannot find a pre-built @@ -91,8 +91,8 @@ section. </para></listitem> <listitem><para> - <emphasis>Secure the target root filesystem - and the Cross-development toolchain</emphasis>: + <emphasis>Secure the Target Root Filesystem + and the Cross-Development Toolchain</emphasis>: You need to find and download the appropriate root filesystem and the cross-development toolchain.</para> <para>You can find the tarballs for the root filesystem @@ -118,22 +118,19 @@ section. Another helpful resource for building an installer is the - <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + "<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>" wiki page. </note> </para></listitem> <listitem><para> - <emphasis>Create and build your application</emphasis>: + <emphasis>Create and Build Your Application</emphasis>: At this point, you need to have source files for your application. Once you have the files, you can use the Eclipse IDE to import them and build the project. - If you are not using Eclipse, you need to use the - cross-development tools you have installed to create - the image.</para></listitem> + </para></listitem> <listitem><para> - <emphasis>Deploy the image with the - application</emphasis>: + <emphasis>Deploy the Image With the Application</emphasis>: Using the Eclipse IDE, you can deploy your image to the hardware or to QEMU through the project's preferences. You can also use Eclipse to load and test your image @@ -144,7 +141,7 @@ for information on using QEMU. </para></listitem> <listitem><para> - <emphasis>Test and debug the application</emphasis>: + <emphasis>Test and Debug the Application</emphasis>: Once your application is deployed, you need to test it. Within the Eclipse IDE, you can use the debugging environment along with supported performance enhancing @@ -179,25 +176,25 @@ collection of power data, collection of latency data, and collection of performance data. <note> - This release of the Yocto Project supports both the Neon - and Mars versions of the Eclipse IDE. - This section provides information on how to use the Neon + This release of the Yocto Project supports both the Oxygen + and Neon versions of the Eclipse IDE. + This section provides information on how to use the Oxygen release with the Yocto Project. - For information on how to use the Mars version of Eclipse + For information on how to use the Neon version of Eclipse with the Yocto Project, see - "<link linkend='sdk-appendix-latest-yp-eclipse-plug-in'>Appendix C</link>. + "<link linkend='sdk-appendix-neon-yp-eclipse-plug-in'>Appendix D</link>". </note> </para> - <section id='neon-setting-up-the-eclipse-ide'> - <title>Setting Up the Neon Version of the Eclipse IDE</title> + <section id='oxygen-setting-up-the-eclipse-ide'> + <title>Setting Up the Oxygen Version of the Eclipse IDE</title> <para> To develop within the Eclipse IDE, you need to do the following: <orderedlist> <listitem><para> - Install the Neon version of the Eclipse IDE. + Install the Oxygen version of the Eclipse IDE. </para></listitem> <listitem><para> Configure the Eclipse IDE. @@ -217,17 +214,17 @@ </note> </para> - <section id='neon-installing-eclipse-ide'> - <title>Installing the Neon Eclipse IDE</title> + <section id='oxygen-installing-eclipse-ide'> + <title>Installing the Oxygen Eclipse IDE</title> <para> Follow these steps to locate, install, and configure - Neon Eclipse: + Oxygen Eclipse: <orderedlist> <listitem><para> - <emphasis>Locate the Neon Download:</emphasis> + <emphasis>Locate the Oxygen Download:</emphasis> Open a browser and go to - <ulink url='http://www.eclipse.org/neon/'>http://www.eclipse.org/neon/</ulink>. + <ulink url='http://www.eclipse.org/oxygen/'>http://www.eclipse.org/oxygen/</ulink>. </para></listitem> <listitem><para> <emphasis>Download the Tarball:</emphasis> @@ -262,36 +259,50 @@ </para></listitem> <listitem><para> <emphasis>Install the Software:</emphasis> - Accept the default "cpp-neon" directory and - click "Install". - Accept any license agreements and approve any - certificates. + Click "Install" to begin the installation. + Accept all the certificates and any license + agreements. + Click "Install" again to finish the installation. </para></listitem> <listitem><para> - <emphasis>Launch Neon:</emphasis> - Click the "Launch" button and accept the - default "workspace". + <emphasis>Launch Oxygen:</emphasis> + Accept the default "workspace" and click the + "Launch" button. + You should see the Eclipse welcome page from which + can click "workbench" to enter your workspace. </para></listitem> </orderedlist> </para> </section> - <section id='neon-configuring-the-mars-eclipse-ide'> - <title>Configuring the Neon Eclipse IDE</title> + <section id='oxygen-configuring-the-eclipse-ide'> + <title>Configuring the Oxygen Eclipse IDE</title> <para> - Follow these steps to configure the Neon Eclipse IDE. - <note> - Depending on how you installed Eclipse and what - you have already done, some of the options will - not appear. - If you cannot find an option as directed by the - manual, it has already been installed. + Follow these steps to configure the Oxygen Eclipse IDE. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Depending on how you installed Eclipse and what + you have already done, some of the options will + not appear. + If you cannot find an option as directed by the + manual, it has already been installed. + </para></listitem> + <listitem><para> + If you want to see all items regardless of + whether they are installed or not, deselect the + "Hide items that are already installed" + check box. + </para></listitem> + </itemizedlist> </note> <orderedlist> <listitem><para> Be sure Eclipse is running and you are in your workbench. + Just click "workbench" if you are not in your + default workspace. </para></listitem> <listitem><para> Select "Install New Software" from the "Help" @@ -299,7 +310,7 @@ </para></listitem> <listitem><para> Select - "Neon - http://download.eclipse.org/releases/neon" + "Oxygen - http://download.eclipse.org/releases/oxygen" from the "Work with:" pull-down menu. </para></listitem> <listitem><para> @@ -331,28 +342,29 @@ </para></listitem> <listitem><para> Complete the installation by clicking through - appropriate "Next" and "Finish" buttons. + appropriate "Next" and "Finish" buttons and then + restart the Eclipse IDE. </para></listitem> </orderedlist> </para> </section> - <section id='neon-installing-the-eclipse-yocto-plug-in'> - <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title> + <section id='oxygen-installing-the-eclipse-yocto-plug-in'> + <title>Installing or Accessing the Oxygen Eclipse Yocto Plug-in</title> <para> You can install the Eclipse Yocto Plug-in into the Eclipse IDE one of two ways: use the Yocto Project's - Eclipse Update site to install the pre-built plug-in + Eclipse Update site to install the pre-built plug-in, or build and install the plug-in from the latest source code. </para> - <section id='neon-new-software'> + <section id='oxygen-new-software'> <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> <para> - To install the Neon Eclipse Yocto Plug-in from the + To install the Oxygen Eclipse Yocto Plug-in from the update site, follow these steps: <orderedlist> <listitem><para> @@ -367,17 +379,15 @@ </para></listitem> <listitem><para> Enter - <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename> + <filename>&ECLIPSE_DL_PLUGIN_URL;/oxygen</filename> in the URL field and provide a meaningful name in the "Name" field. </para></listitem> <listitem><para> - Click "OK" to have the entry added - to the "Work with:" drop-down list. - </para></listitem> - <listitem><para> - Select the entry for the plug-in - from the "Work with:" drop-down list. + Click "OK" to have the entry automatically + populate the "Work with:" field and to have + the items for installation appear in the window + below. </para></listitem> <listitem><para> Check the boxes next to the following: @@ -401,16 +411,21 @@ </para> </section> - <section id='neon-zip-file-method'> + <section id='oxygen-zip-file-method'> <title>Installing the Plug-in Using the Latest Source Code</title> <para> - To install the Neon Eclipse Yocto Plug-in from the + To install the Oxygen Eclipse Yocto Plug-in from the latest source code, follow these steps: <orderedlist> <listitem><para> - Be sure your development system - has JDK 1.8+ + Be sure your build host has JDK version 1.8 + or greater. + On a Linux build host you can determine the + version using the following command: + <literallayout class='monospaced'> + $ java -version + </literallayout> </para></listitem> <listitem><para> Install X11-related packages: @@ -423,19 +438,19 @@ Git repository with: <literallayout class='monospaced'> $ cd ~ - $ git clone git://git.yoctoproject.org/eclipse-poky + $ git clone git://git.yoctoproject.org/eclipse-yocto </literallayout> </para></listitem> <listitem><para> Use Git to create the correct tag: <literallayout class='monospaced'> - $ cd ~/eclipse-poky - $ git checkout neon/yocto-&DISTRO; + $ cd ~/eclipse-yocto + $ git checkout -b oxygen/&DISTRO_NAME_NO_CAP; remotes/origin/oxygen/&DISTRO_NAME_NO_CAP; </literallayout> This creates a local tag named - <filename>neon/yocto-&DISTRO;</filename> + <filename>oxygen/&DISTRO_NAME_NO_CAP;</filename> based on the branch - <filename>origin/neon-master</filename>. + <filename>origin/oxygen/&DISTRO_NAME_NO_CAP;</filename>. You are put into a detached HEAD state, which is fine since you are only going to be building and not developing. @@ -469,11 +484,11 @@ <para> Following is an example: <literallayout class='monospaced'> - $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&1 | tee build.log + $ ECLIPSE_HOME=/home/scottrif/eclipse-yocto/scripts/eclipse ./build.sh -l oxygen/&DISTRO_NAME_NO_CAP; master yocto-&DISTRO; 2>&1 | tee build.log </literallayout> The previous example command adds the tag you need for - <filename>mars/yocto-&DISTRO;</filename> + <filename>oxygen/&DISTRO_NAME_NO_CAP;</filename> to <filename>HEAD</filename>, then tells the build script to use the local (-l) Git checkout for the build. @@ -533,17 +548,17 @@ <para> At this point you should be able to configure the Eclipse Yocto Plug-in as described in the - "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" + "<link linkend='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen Eclipse Yocto Plug-in</link>" section. </para> </section> </section> - <section id='neon-configuring-the-eclipse-yocto-plug-in'> - <title>Configuring the Neon Eclipse Yocto Plug-in</title> + <section id='oxygen-configuring-the-eclipse-yocto-plug-in'> + <title>Configuring the Oxygen Eclipse Yocto Plug-in</title> <para> - Configuring the Neon Eclipse Yocto Plug-in involves + Configuring the Oxygen Eclipse Yocto Plug-in involves setting the Cross Compiler options and the Target options. The configurations you choose become the default @@ -555,7 +570,7 @@ <para> To start, you need to do the following from within the Eclipse IDE: - <itemizedlist> + <orderedlist> <listitem><para> Choose "Preferences" from the "Window" menu to display the Preferences Dialog. @@ -564,7 +579,7 @@ Click "Yocto Project SDK" to display the configuration screen. </para></listitem> - </itemizedlist> + </orderedlist> The following sub-sections describe how to configure the plug-in. <note> @@ -572,12 +587,12 @@ example for preparing a QEMU image for use with Eclipse is referenced as the "wiki" and is linked to the example on the - <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + "<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>" wiki page. </note> </para> - <section id='neon-configuring-the-cross-compiler-options'> + <section id='oxygen-configuring-the-cross-compiler-options'> <title>Configuring the Cross-Compiler Options</title> <para> @@ -682,8 +697,7 @@ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. If so, the <filename>MY_QEMU_ROOTFS</filename> - directory is found in the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + directory is found in the Build Directory and you would browse to and select that directory (e.g. <filename>/home/scottrif/poky/build/MY_QEMU_ROOTFS</filename>). @@ -708,9 +722,9 @@ in the menu, you will need to build the image. See the - "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" - section of the Yocto Project Quick Start - for more information. + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>" + section of the Yocto Project Development Tasks + Manual for more information. You can also see the <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. </para></listitem> @@ -718,7 +732,7 @@ </para> </section> - <section id='neon-configuring-the-target-options'> + <section id='oxygen-configuring-the-target-options'> <title>Configuring the Target Options</title> <para> @@ -787,14 +801,14 @@ </para> <para> - Click the "Apply" and "OK" to save your plug-in + Click "Apply and Close" to save your plug-in configurations. </para> </section> </section> </section> - <section id='neon-creating-the-project'> + <section id='oxygen-creating-the-project'> <title>Creating the Project</title> <para> @@ -818,20 +832,22 @@ display the source code, follow these steps: <orderedlist> <listitem><para> - Select "C Project" from the "File -> New" menu. + Select "C/C++ Project" from the "File -> New" menu. + </para></listitem> + <listitem><para> + Select "C Managed Build" from the available options and + click "Next". </para></listitem> <listitem><para> - Expand - <filename>Yocto Project SDK Autotools Project</filename>. + Expand "Yocto Project SDK Autotools Project". </para></listitem> <listitem><para> - Select <filename>Hello World ANSI C Autotools Projects</filename>. + Select "Hello World ANSI C Autotools Projects". This is an Autotools-based project based on a Yocto template. </para></listitem> <listitem><para> - Put a name in the - <filename>Project name:</filename> field. + Put a name in the "Project name:" field. Do not use hyphens as part of the name (e.g. <filename>hello</filename>). </para></listitem> @@ -857,12 +873,12 @@ </para> </section> - <section id='neon-configuring-the-cross-toolchains'> + <section id='oxygen-configuring-the-cross-toolchains'> <title>Configuring the Cross-Toolchains</title> <para> The earlier section, - "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>", + "<link linkend='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen Eclipse Yocto Plug-in</link>", sets up the default project configurations. You can override these settings for a given project by following these steps: @@ -877,7 +893,7 @@ Target Options for a project are inherited from settings you provided using the Preferences Dialog as described earlier in the - "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" + "<link linkend='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen Eclipse Yocto Plug-in</link>" section. The Yocto Project Settings Dialog allows you to override those default settings for a given @@ -885,21 +901,15 @@ </para></listitem> <listitem><para> Make or verify your configurations for the - project and click "OK". + project and click "Apply and Close". </para></listitem> <listitem><para> - Right-click in the navigation pane and - select "Reconfigure Project" from the pop-up menu. + Right-click in the navigation pane and select + "Reconfigure Project" from the pop-up menu. This selection reconfigures the project by running - <filename>autogen.sh</filename> in the workspace - for your project. - The script also runs - <filename>libtoolize</filename>, - <filename>aclocal</filename>, - <filename>autoconf</filename>, - <filename>autoheader</filename>, - <filename>automake --a</filename>, and - <filename>./configure</filename>. + <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>Autotools GNU utility programs</ulink> + such as Autoconf, Automake, and so forth in the + workspace for your project. Click on the "Console" tab beneath your source code to see the results of reconfiguring your project. </para></listitem> @@ -907,13 +917,14 @@ </para> </section> - <section id='neon-building-the-project'> + <section id='oxygen-building-the-project'> <title>Building the Project</title> <para> To build the project select "Build All" from the "Project" menu. The console should update and you can note the - cross-compiler you are using. + cross-compiler you are using (i.e. + <filename>i586-poky-linux-gcc</filename> in this example). <note> When building "Yocto Project SDK Autotools" projects, the Eclipse IDE might display error messages for @@ -929,12 +940,12 @@ Select the project. </para></listitem> <listitem><para> - Select "Folder" from the - <filename>File > New</filename> menu. + Select "Folder" from the "File -> New" menu. </para></listitem> <listitem><para> - In the "New Folder" Dialog, select "Link to - alternate location (linked folder)". + In the "New Folder" Dialog, click the "Advanced" + button and then activate "Link to + alternate location (linked folder)" button. </para></listitem> <listitem><para> Click "Browse" to navigate to the include @@ -943,9 +954,6 @@ configuration preferences. </para></listitem> <listitem><para> - Click "OK". - </para></listitem> - <listitem><para> Click "Finish" to save the linked folder. </para></listitem> </orderedlist> @@ -953,7 +961,7 @@ </para> </section> - <section id='neon-starting-qemu-in-user-space-nfs-mode'> + <section id='oxygen-starting-qemu-in-user-space-nfs-mode'> <title>Starting QEMU in User-Space NFS Mode</title> <para> @@ -987,8 +995,8 @@ <filename>rpcbind</filename>, follow the suggestions to get the service running. As an example, on a new Ubuntu 16.04 LTS - installation, you must do the following in - order to get QEMU to launch: + installation, you must do the following in a new + shell in order to get QEMU to launch: <literallayout class='monospaced'> $ sudo apt-get install rpcbind </literallayout> @@ -1032,7 +1040,7 @@ </para> </section> - <section id='neon-deploying-and-debugging-the-application'> + <section id='oxygen-deploying-and-debugging-the-application'> <title>Deploying and Debugging the Application</title> <para> @@ -1186,7 +1194,7 @@ </para> </section> - <section id='neon-using-Linuxtools'> + <section id='oxygen-using-Linuxtools'> <title>Using Linuxtools</title> <para> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml index 444d816a7..5215a9d09 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml @@ -28,7 +28,7 @@ In addition to the functionality available through <filename>devtool</filename>, you can alternatively make use of the toolchain directly, for example from Makefile, Autotools, and - Eclipse-based projects. + <trademark class='trade'>Eclipse</trademark>-based projects. See the "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>" chapter for more information. @@ -54,29 +54,29 @@ </para> </section> - <section id='sdk-setting-up-to-use-the-extensible-sdk'> - <title>Setting Up to Use the Extensible SDK</title> + <section id='sdk-installing-the-extensible-sdk'> + <title>Installing the Extensible SDK</title> <para> - The first thing you need to do is install the SDK on your host - development machine by running the <filename>*.sh</filename> - installation script. + The first thing you need to do is install the SDK on your + <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink> + by running the <filename>*.sh</filename> installation script. </para> <para> You can download a tarball installer, which includes the pre-built toolchain, the <filename>runqemu</filename> script, the internal build system, <filename>devtool</filename>, - and support files from the appropriate directory under - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. - Toolchains are available for 32-bit and 64-bit x86 development - systems from the <filename>i686</filename> and - <filename>x86_64</filename> directories, respectively. + and support files from the appropriate + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink> + directory within the Index of Releases. + Toolchains are available for several 32-bit and 64-bit + architectures with the <filename>x86_64</filename> directories, + respectively. The toolchains the Yocto Project provides are based off the - <filename>core-image-sato</filename> image and contain + <filename>core-image-sato</filename> and + <filename>core-image-minimal</filename> images and contain libraries appropriate for developing against that image. - Each type of development system supports five or more target - architectures. </para> <para> @@ -85,6 +85,7 @@ filename and then is immediately followed by a string representing the target architecture. An extensible SDK has the string "-ext" as part of the name. + Following is the general form: <literallayout class='monospaced'> poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh @@ -93,14 +94,15 @@ i686 or x86_64. - <replaceable>image_type</replaceable> is the image for which the SDK was built. + <replaceable>image_type</replaceable> is the image for which the SDK was built: + + core-image-sato or core-image-minimal <replaceable>arch</replaceable> is a string representing the tuned target architecture: - i586, x86_64, powerpc, mips, armv7a or armv5te + aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon - <replaceable>release_version</replaceable> is a string representing the release number of the - Yocto Project: + <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project: &DISTRO;, &DISTRO;+snapshot </literallayout> @@ -131,9 +133,10 @@ home directory. You can choose to install the extensible SDK in any location when you run the installer. - However, the location you choose needs to be writable for whichever - users need to use the SDK, since files will need to be written - under that directory during the normal course of operation. + However, because files need to be written under that directory + during the normal course of operation, the location you choose + for installation must be writable for whichever + users need to use the SDK. </para> <para> @@ -141,28 +144,34 @@ toolchain tarball for a 64-bit x86 development host system and a 64-bit x86 target architecture. The example assumes the SDK installer is located in - <filename>~/Downloads/</filename>. + <filename>~/Downloads/</filename> and has execution rights. <note> If you do not have write permissions for the directory into which you are installing the SDK, the installer notifies you and exits. - Be sure you have write permissions in the directory and - run the installer again. + For that case, set up the proper permissions in the directory + and run the installer again. </note> <literallayout class='monospaced'> - $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh - Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO; - =================================================================================== + $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh + Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5 + ========================================================================== Enter target directory for SDK (default: ~/poky_sdk): You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y - Extracting SDK......................................................................done + Extracting SDK..............done Setting it up... Extracting buildtools... Preparing build system... + Parsing recipes: 100% |##################################################################| Time: 0:00:52 + Initialising tasks: 100% |###############################################################| Time: 0:00:00 + Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00 + Loading cache: 100% |####################################################################| Time: 0:00:00 + Initialising tasks: 100% |###############################################################| Time: 0:00:00 done SDK has been successfully set up and is ready to be used. Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux + </literallayout> </para> </section> @@ -172,7 +181,7 @@ <para> Once you have the SDK installed, you must run the SDK environment - setup script before you can actually use it. + setup script before you can actually use the SDK. This setup script resides in the directory you chose when you installed the SDK, which is either the default <filename>poky_sdk</filename> directory or the directory you @@ -196,32 +205,13 @@ SDK environment now set up; additionally you may now run devtool to perform development tasks. Run devtool --help for further details. </literallayout> - When you run the setup script, many environment variables are - defined: - <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation - <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler - <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler - <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor - <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler - <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker - <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger - <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols - <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib' - <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy' - <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump' - <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar' - <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm' - <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools - <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure - <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags - <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags - <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link - <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags - </literallayout> + Running the setup script defines many environment variables needed + in order to use the SDK (e.g. <filename>PATH</filename>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>, + and so forth). + If you want to see all the environment variables the script + exports, examine the installation file itself. </para> </section> @@ -240,15 +230,15 @@ the extensible SDK. You can use <filename>devtool</filename> to help you easily develop any project whose build output must be part of an - image built using the OpenEmbedded build system. + image built using the build system. </note> </para> <para> The <filename>devtool</filename> command line is organized similarly to - <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> in that it has a - number of sub-commands for each function. + <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> in that it + has a number of sub-commands for each function. You can run <filename>devtool --help</filename> to see all the commands. <note> @@ -260,8 +250,8 @@ </para> <para> - Three <filename>devtool</filename> subcommands that provide - entry-points into development are: + Three <filename>devtool</filename> subcommands exist that provide + entry-points into development: <itemizedlist> <listitem><para> <emphasis><filename>devtool add</filename></emphasis>: @@ -278,17 +268,17 @@ an updated set of source files. </para></listitem> </itemizedlist> - As with the OpenEmbedded build system, "recipes" represent software - packages within <filename>devtool</filename>. + As with the build system, "recipes" represent software packages + within <filename>devtool</filename>. When you use <filename>devtool add</filename>, a recipe is automatically created. When you use <filename>devtool modify</filename>, the specified - existing recipe is used in order to determine where to get the source - code and how to patch it. + existing recipe is used in order to determine where to get the + source code and how to patch it. In both cases, an environment is set up so that when you build the recipe a source tree that is under your control is used in order to allow you to make changes to the source as desired. - By default, both new recipes and the source go into a "workspace" + By default, new recipes and the source go into a "workspace" directory under the SDK. </para> @@ -335,10 +325,10 @@ generate a recipe based on existing source code.</para> <para>In a shared development environment, it is - typical where other developers are responsible for + typical for other developers to be responsible for various areas of source code. As a developer, you are probably interested in using - that source code as part of your development using + that source code as part of your development within the Yocto Project. All you need is access to the code, a recipe, and a controlled area in which to do your work.</para> @@ -346,138 +336,164 @@ <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: + <listitem><para> + <emphasis>Left</emphasis>: + The left scenario in the figure represents a + common situation where the source code does not + exist locally and needs to be extracted. + In this situation, the source code is extracted + to the default workspace - you do not + want the files in some specific location + outside of the workspace. + Thus, everything you need will be located in + the workspace: <literallayout class='monospaced'> $ devtool add <replaceable>recipe fetchuri</replaceable> </literallayout> With this command, <filename>devtool</filename> - 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. + extracts the upstream source files into a local + Git repository within the + <filename>sources</filename> folder. + The command then creates a recipe named + <replaceable>recipe</replaceable> and a + corresponding append file in the workspace. + If you do not provide + <replaceable>recipe</replaceable>, the command + makes an attempt to determine the recipe name. </para></listitem> - <listitem><para><emphasis>Middle</emphasis>: - The middle scenario also represents a situation where - the source code does not exist locally. + <listitem><para> + <emphasis>Middle</emphasis>: + The middle scenario in the figure also + represents a situation where the source code + does not exist locally. In this case, the code is again upstream and needs to be extracted to some local area - this time outside of the default workspace. - If required, <filename>devtool</filename> - always creates - a Git repository locally during the extraction. + <note> + If required, <filename>devtool</filename> + always creates + a Git repository locally during the + extraction. + </note> Furthermore, the first positional argument - <replaceable>srctree</replaceable> in this case - identifies where the + <replaceable>srctree</replaceable> in this + case identifies where the <filename>devtool add</filename> command will locate the extracted code outside of the - workspace: + workspace. + You need to specify an empty directory: <literallayout class='monospaced'> $ devtool add <replaceable>recipe srctree fetchuri</replaceable> </literallayout> In summary, the source code is pulled from - <replaceable>fetchuri</replaceable> and extracted - into the location defined by + <replaceable>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>Within workspace, + <filename>devtool</filename> creates a + recipe named <replaceable>recipe</replaceable> + along with an associated append file. </para></listitem> - <listitem><para><emphasis>Right</emphasis>: - The right scenario represents a situation - where the source tree (srctree) has been + <listitem><para> + <emphasis>Right</emphasis>: + The right scenario in the figure represents a + situation where the + <replaceable>srctree</replaceable> has been previously prepared outside of the - <filename>devtool</filename> workspace. - </para> + <filename>devtool</filename> workspace.</para> - <para>The following command names the recipe - and identifies where the existing source tree - is located: + <para>The following command provides a new + recipe name and identifies the existing source + tree location: <literallayout class='monospaced'> $ devtool add <replaceable>recipe srctree</replaceable> </literallayout> - The command examines the source code and creates - a recipe for it placing the recipe into the - workspace.</para> + The command examines the source code and + creates a recipe named + <replaceable>recipe</replaceable> for the code + and places the recipe into the workspace. + </para> - <para>Because the extracted source code already exists, - <filename>devtool</filename> does not try to - relocate it into the workspace - just the new - the recipe is placed in the workspace.</para> + <para>Because the extracted source code already + exists, <filename>devtool</filename> does not + try to relocate the source code into the + workspace - only the new recipe is placed + in the workspace.</para> <para>Aside from a recipe folder, the command - also creates an append folder and places an initial - <filename>*.bbappend</filename> within. + also creates an associated append folder and + places an initial + <filename>*.bbappend</filename> file within. </para></listitem> </itemizedlist> </para></listitem> - <listitem><para><emphasis>Edit the Recipe</emphasis>: - At this point, you can use <filename>devtool edit-recipe</filename> + <listitem><para> + <emphasis>Edit the Recipe</emphasis>: + You can use <filename>devtool edit-recipe</filename> to open up the editor as defined by the <filename>$EDITOR</filename> environment variable and modify the file: <literallayout class='monospaced'> $ devtool edit-recipe <replaceable>recipe</replaceable> </literallayout> - From within the editor, you can make modifications to the - recipe that take affect when you build it later. + 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>: + <listitem><para> + <emphasis>Build the Recipe or Rebuild the Image</emphasis>: + The next step you take depends on what you are going + to do with the new code.</para> + + <para>If you need to eventually move the build output + to the target hardware, use the following + <filename>devtool</filename> command: <literallayout class='monospaced'> $ devtool build <replaceable>recipe</replaceable> </literallayout></para> + <para>On the other hand, if you want an image to - contain the recipe's packages for immediate deployment - onto a device (e.g. for testing purposes), you can use + contain the recipe's packages from the workspace + for immediate deployment onto a device (e.g. for + testing purposes), you can use the <filename>devtool build-image</filename> command: <literallayout class='monospaced'> $ devtool build-image <replaceable>image</replaceable> </literallayout> </para></listitem> - <listitem><para><emphasis>Deploy the Build Output</emphasis>: + <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. + see if the resulting build output works as expected + on the target hardware. <note> This step assumes you have a previously built image that is already either running in QEMU or - 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. + is running on actual hardware. + Also, it is assumed that for deployment of the + image to the target, SSH is installed in the image + and, if the image is running on real hardware, + you have network access to and from your + development machine. </note> - You can deploy your build output to that target hardware by - using the <filename>devtool deploy-target</filename> command: + 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. + The <replaceable>target</replaceable> is a live target + machine running as an SSH server.</para> + + <para>You can, of course, also deploy the image you + build to actual hardware by using the + <filename>devtool build-image</filename> command. + However, <filename>devtool</filename> does not provide + a specific command that allows you to deploy the + image to actual hardware. </para></listitem> <listitem><para> <emphasis>Finish Your Work With the Recipe</emphasis>: @@ -494,8 +510,9 @@ committed to the Git repository in the source tree. </note></para> - <para>As mentioned, the <filename>devtool finish</filename> - command moves the final recipe to its permanent layer. + <para>As mentioned, the + <filename>devtool finish</filename> command moves the + final recipe to its permanent layer. </para> <para>As a final process of the @@ -520,21 +537,20 @@ <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. + way to work on existing code that already has a local recipe in + place that is used to build the software. + The command is flexible enough to allow you to extract code + from an upstream source, specify the existing recipe, and + keep track of and gather any patch files from other developers + that are associated with the code. </para> <para> Depending on your particular scenario, the arguments and options you use with <filename>devtool modify</filename> form different combinations. - The following diagram shows common development flows - you would use with the <filename>devtool modify</filename> - command: + The following diagram shows common development flows for the + <filename>devtool modify</filename> command: </para> <para> @@ -543,140 +559,181 @@ <para> <orderedlist> - <listitem><para><emphasis>Preparing to Modify the Code</emphasis>: + <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 + <listitem><para> + The recipe exists locally in a layer external to the <filename>devtool</filename> workspace. </para></listitem> - <listitem><para>The source files exist upstream in an + <listitem><para> + The source files exist either upstream in an un-extracted state or locally in a previously extracted state. </para></listitem> </itemizedlist> The typical situation is where another developer has - created some layer for use with the Yocto Project and + created a layer for use with the Yocto Project and their recipe already resides in that layer. Furthermore, their source code is readily available either upstream or locally. <itemizedlist> - <listitem><para><emphasis>Left</emphasis>: - The left scenario represents a common situation - where the source code does not exist locally - and needs to be extracted. + <listitem><para> + <emphasis>Left</emphasis>: + The left scenario in the figure represents a + common situation where the source code does + not exist locally and it needs to be extracted + from an upstream source. In this situation, the source is extracted - into the default workspace location. + into the default <filename>devtool</filename> + workspace location. The recipe, in this scenario, is in its own layer outside the workspace (i.e. <filename>meta-</filename><replaceable>layername</replaceable>). </para> - <para>The following command identifies the recipe - and by default extracts the source files: + <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 + Once <filename>devtool</filename>locates the + recipe, <filename>devtool</filename> uses the + recipe's <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - 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. + statements to locate the source code and any + local patch files from other developers.</para> + + <para>With this scenario, no + <replaceable>srctree</replaceable> argument + exists. + Consequently, the default behavior of the + <filename>devtool modify</filename> command is + to extract the source files pointed to by the + <filename>SRC_URI</filename> statements into a + local Git structure. + Furthermore, the location for the extracted + source is the default area within the + <filename>devtool</filename> workspace. + The result is that the command sets up both + the source code and an append file within the + workspace while the recipe remains in its + original location. </para></listitem> - <listitem><para><emphasis>Middle</emphasis>: - The middle scenario represents a situation where - the source code also does not exist locally. + <listitem><para> + <emphasis>Middle</emphasis>: + The middle scenario in the figure represents a + situation where the source code also does not + exist locally. In this case, the code is again upstream and needs to be extracted to some local area as a Git repository. - The recipe, in this scenario, is again in its own - layer outside the workspace.</para> + The recipe, in this scenario, is again local + and in its own layer outside the workspace. + </para> <para>The following command tells <filename>devtool</filename> what recipe with - which to work and, in this case, identifies a local - area for the extracted source files that is outside - of the default workspace: + which to work and, in this case, identifies a + local area for the extracted source files that + is outside of the default + <filename>devtool</filename> workspace: <literallayout class='monospaced'> $ devtool modify <replaceable>recipe srctree</replaceable> </literallayout> + <note> + You cannot provide a URL for + <replaceable>srctree</replaceable> using + the <filename>devtool</filename> command. + </note> As with all extractions, the command uses - the recipe's <filename>SRC_URI</filename> 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 - to place the extracted source.</para> - - <para>Within workspace, <filename>devtool</filename> - creates an append file for the recipe. + the recipe's <filename>SRC_URI</filename> + statements to locate the source files and any + associated patch files. + Once the files are located, the command by + default extracts them into + <replaceable>srctree</replaceable>.</para> + + <para>Within workspace, + <filename>devtool</filename> creates an append + file for the recipe. The recipe remains in its original location but - the source files are extracted to the location you - provided with <replaceable>srctree</replaceable>. + the source files are extracted to the location + you provide 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. + <listitem><para> + <emphasis>Right</emphasis>: + The right scenario in the figure represents a + situation where the source tree + (<replaceable>srctree</replaceable>) already + exists locally as a previously extracted Git + structure outside of the + <filename>devtool</filename> workspace. In this example, the recipe also exists - elsewhere in its own layer. + elsewhere locally in its own layer. </para> <para>The following command tells <filename>devtool</filename> the recipe - with which to work, uses the "-n" option to indicate - source does not need to be extracted, and uses - <replaceable>srctree</replaceable> to point to the - previously extracted source files: + 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. + an append file for the recipe in the + <filename>devtool</filename> workspace. The recipe and the source code remain in their original locations. </para></listitem> </itemizedlist> </para></listitem> - <listitem><para><emphasis>Edit the Source</emphasis>: - Once you have used the <filename>devtool modify</filename> - command, you are free to make changes to the source - files. + <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. + <listitem><para> + <emphasis>Build the Recipe or Rebuild the Image</emphasis>: + The next step you take depends on what you are going + to do with the new code.</para> + + <para>If you need to eventually move the build output + to the target hardware, use the following + <filename>devtool</filename> command: + <literallayout class='monospaced'> + $ devtool build <replaceable>recipe</replaceable> + </literallayout></para> + + <para>On the other hand, if you want an image to + contain the recipe's packages from the workspace + for immediate deployment onto a device (e.g. for + testing purposes), you can use + the <filename>devtool build-image</filename> command: + <literallayout class='monospaced'> + $ devtool build-image <replaceable>image</replaceable> + </literallayout> </para></listitem> - <listitem><para><emphasis>Deploy the Build Output</emphasis>: + <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. + 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 @@ -686,19 +743,22 @@ 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: + 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. + The <replaceable>target</replaceable> is a live target + machine running as an SSH server.</para> + + <para>You can, of course, use other methods to deploy + the image you built using the + <filename>devtool build-image</filename> command to + actual hardware. + <filename>devtool</filename> does not provide + a specific command to deploy the image to actual + hardware. </para></listitem> <listitem><para> <emphasis>Finish Your Work With the Recipe</emphasis>: @@ -707,28 +767,30 @@ Git repository, updates the recipe to point to them (or creates a <filename>.bbappend</filename> file to do so, depending on the specified destination layer), and - then resets the recipe so that the recipe is built normally - rather than from the workspace. + then resets the recipe so that the recipe is built + normally rather than from the workspace. <literallayout class='monospaced'> $ devtool finish <replaceable>recipe layer</replaceable> </literallayout> <note> Any changes you want to turn into patches must be - committed to the Git repository in the source tree. + staged and committed within the local Git + repository before you use the + <filename>devtool finish</filename> command. </note></para> <para>Because there is no need to move the recipe, <filename>devtool finish</filename> either updates the original recipe in the original layer or the command - creates a <filename>.bbappend</filename> in a different - layer as provided by <replaceable>layer</replaceable>. - </para> + creates a <filename>.bbappend</filename> file in a + different layer as provided by + <replaceable>layer</replaceable>.</para> <para>As a final process of the <filename>devtool finish</filename> command, the state of the standard layers and the upstream source is restored so that you can build the recipe from those - areas rather than the workspace. + areas rather than from the workspace. <note> You can use the <filename>devtool reset</filename> command to put things back should you decide you @@ -745,22 +807,36 @@ <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title> <para> - The <filename>devtool upgrade</filename> command updates - an existing recipe so that you can build it for an updated - set of source files. - The command is flexible enough to allow you to specify - source code revision and versioning schemes, extract code into - or out of the <filename>devtool</filename> workspace, and - work with any source file forms that the fetchers support. + The <filename>devtool upgrade</filename> command upgrades + an existing recipe to that of a more up-to-date version + found upstream. + Throughout the life of software, recipes continually undergo + version upgrades by their upstream publishers. + You can use the <filename>devtool upgrade</filename> + workflow to make sure your recipes you are using for builds + are up-to-date with their upstream counterparts. + <note> + Several methods exist by which you can upgrade recipes - + <filename>devtool upgrade</filename> happens to be one. + You can read about all the methods by which you can + upgrade recipes in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>" + section of the Yocto Project Development Tasks Manual. + </note> </para> <para> - Depending on your particular scenario, the arguments and options - you use with <filename>devtool upgrade</filename> form different - combinations. - The following diagram shows a common development flow - you would use with the <filename>devtool modify</filename> - command: + The <filename>devtool upgrade</filename> command is flexible + enough to allow you to specify source code revision and + versioning schemes, extract code into or out of the + <filename>devtool</filename> + <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>, + and work with any source file forms that the fetchers support. + </para> + + <para> + The following diagram shows the common development flow + used with the <filename>devtool upgrade</filename> command: </para> <para> @@ -769,110 +845,142 @@ <para> <orderedlist> - <listitem><para><emphasis>Initiate the Upgrade</emphasis>: - The top part of the flow shows a typical scenario by which - you could use <filename>devtool upgrade</filename>. + <listitem><para> + <emphasis>Initiate the Upgrade</emphasis>: + The top part of the flow shows the typical scenario by + which you use the <filename>devtool upgrade</filename> + command. The following conditions exist: <itemizedlist> - <listitem><para>The recipe exists in some layer external + <listitem><para> + The recipe exists in a local layer external to the <filename>devtool</filename> workspace. </para></listitem> - <listitem><para>The source files for the new release - exist adjacent to the same location pointed to by + <listitem><para> + The source files for the new release + exist in the same location pointed to by <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - in the recipe (e.g. a tarball with the new version - number in the name, or as a different revision in - the upstream Git repository). + in the recipe (e.g. a tarball with the new + version number in the name, or as a different + revision in the upstream Git repository). </para></listitem> </itemizedlist> A common situation is where third-party software has undergone a revision so that it has been upgraded. - The recipe you have access to is likely in your own layer. + The recipe you have access to is likely in your own + layer. Thus, you need to upgrade the recipe to use the newer version of the software: <literallayout class='monospaced'> $ devtool upgrade -V <replaceable>version recipe</replaceable> </literallayout> - By default, the <filename>devtool upgrade</filename> command - extracts source code into the <filename>sources</filename> - directory in the workspace. - If you want the code extracted to any other location, you - need to provide the <replaceable>srctree</replaceable> - positional argument with the command as follows: + By default, the <filename>devtool upgrade</filename> + command extracts source code into the + <filename>sources</filename> directory in the + <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>. + If you want the code extracted to any other location, + you need to provide the + <replaceable>srctree</replaceable> positional argument + with the command as follows: <literallayout class='monospaced'> $ devtool upgrade -V <replaceable>version recipe srctree</replaceable> </literallayout> - Also, in this example, the "-V" option is used to specify - the new version. + <note> + In this example, the "-V" option specifies the new + version. + If you don't use "-V", the command upgrades the + recipe to the latest version. + </note> If the source files pointed to by the - <filename>SRC_URI</filename> statement in the recipe are - in a Git repository, you must provide the "-S" option and - specify a revision for the software.</para> - - <para>Once <filename>devtool</filename> locates the recipe, - it uses the <filename>SRC_URI</filename> variable to locate - the source code and any local patch files from other - developers are located. + <filename>SRC_URI</filename> statement in the recipe + are in a Git repository, you must provide the "-S" + option and specify a revision for the software.</para> + + <para>Once <filename>devtool</filename> locates the + recipe, it uses the <filename>SRC_URI</filename> + variable to locate the source code and any local patch + files from other developers. The result is that the command sets up the source code, the new version of the recipe, and an append file all within the workspace. </para></listitem> - <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>: - At this point, there could be some conflicts due to the - software being upgraded to a new version. - This would occur if your recipe specifies some patch files in - <filename>SRC_URI</filename> that conflict with changes - made in the new version of the software. - If this is the case, you need to resolve the conflicts + <listitem><para> + <emphasis>Resolve any Conflicts created by the Upgrade</emphasis>: + Conflicts could exist due to the software being + upgraded to a new version. + Conflicts occur if your recipe specifies some patch + files in <filename>SRC_URI</filename> that conflict + with changes made in the new version of the software. + For such cases, you need to resolve the conflicts by editing the source and following the normal <filename>git rebase</filename> conflict resolution process.</para> - <para>Before moving onto the next step, be sure to resolve any - such conflicts created through use of a newer or different - version of the software. + + <para>Before moving onto the next step, be sure to + resolve any such conflicts created through use of a + newer or different version of the software. </para></listitem> - <listitem><para><emphasis>Build the Recipe</emphasis>: - Once you have your recipe in order, you can build it. - You can either use <filename>devtool build</filename> or - <filename>bitbake</filename>. - Either method produces build output that is stored - in - <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. + <listitem><para> + <emphasis>Build the Recipe or Rebuild the Image</emphasis>: + The next step you take depends on what you are going + to do with the new code.</para> + + <para>If you need to eventually move the build output + to the target hardware, use the following + <filename>devtool</filename> command: + <literallayout class='monospaced'> + $ devtool build <replaceable>recipe</replaceable> + </literallayout></para> + + <para>On the other hand, if you want an image to + contain the recipe's packages from the workspace + for immediate deployment onto a device (e.g. for + testing purposes), you can use + the <filename>devtool build-image</filename> command: + <literallayout class='monospaced'> + $ devtool build-image <replaceable>image</replaceable> + </literallayout> </para></listitem> - <listitem><para><emphasis>Deploy the Build Output</emphasis>: + <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. + command or <filename>bitbake</filename> to build + your recipe, you probably want to see if the resulting + build output works as expected on target hardware. <note> This step assumes you have a previously built image that is already either running in QEMU or running on actual hardware. - Also, it is assumed that for deployment of the image - to the target, SSH is installed in the image and if - the image is running on real hardware that you have - network access to and from your development machine. + 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: + 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 + 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. + However, <filename>devtool</filename> does not provide + a specific command that allows you to do this. </para></listitem> <listitem><para> <emphasis>Finish Your Work With the Recipe</emphasis>: The <filename>devtool finish</filename> command creates any patches corresponding to commits in the local - Git repository, moves the new recipe to a more permanent - layer, and then resets the recipe so that the recipe is - built normally rather than from the workspace. + Git repository, moves the new recipe to a more + permanent layer, and then resets the recipe so that + the recipe is built normally rather than from the + workspace. If you specify a destination layer that is the same as the original source, then the old version of the recipe and associated files will be removed prior to @@ -884,6 +992,7 @@ Any changes you want to turn into patches must be committed to the Git repository in the source tree. </note></para> + <para>As a final process of the <filename>devtool finish</filename> command, the state of the standard layers and the upstream source is @@ -906,8 +1015,8 @@ <title>A Closer Look at <filename>devtool add</filename></title> <para> - The <filename>devtool add</filename> command automatically creates a - recipe based on the source tree with which you provide it. + The <filename>devtool add</filename> command automatically creates + a recipe based on the source tree you provide with the command. Currently, the command has support for the following: <itemizedlist> <listitem><para> @@ -953,8 +1062,8 @@ In most cases, you need to edit the automatically generated recipe in order to make it build properly. Typically, you would go through several edit and build cycles - until you can build the recipe. - Once the recipe can be built, you could use possible further + until the recipe successfully builds. + Once the recipe builds, you could use possible further iterations to test the recipe on the target device. </note> </para> @@ -969,15 +1078,19 @@ <para> If you do not specify a name and version on the command - line, <filename>devtool add</filename> attempts to determine - the name and version of the software being built from - various metadata within the source tree. - Furthermore, the command sets the name of the created recipe - file accordingly. - If the name or version cannot be determined, the - <filename>devtool add</filename> command prints an error and - you must re-run the command with both the name and version - or just the name or version specified. + line, <filename>devtool add</filename> uses various metadata + within the source tree in an attempt to determine + the name and version of the software being built. + Based on what the tool determines, <filename>devtool</filename> + sets the name of the created recipe file accordingly. + </para> + + <para> + If <filename>devtool</filename> cannot determine the name and + version, the command prints an error. + For such cases, you must re-run the command and provide + the name and version, just the name, or just the version as + part of the command line. </para> <para> @@ -1001,26 +1114,27 @@ detect build-time dependencies and map them to other recipes in the system. During this mapping, the command fills in the names of those - recipes in the + recipes as part of the <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> - value within the recipe. - If a dependency cannot be mapped, then a comment is placed in - the recipe indicating such. - The inability to map a dependency might be caused because the - naming is not recognized or because the dependency simply is - not available. + variable within the recipe. + If a dependency cannot be mapped, <filename>devtool</filename> + places a comment in the recipe indicating such. + The inability to map a dependency can result from naming not + being recognized or because the dependency simply is not + available. For cases where the dependency is not available, you must use the <filename>devtool add</filename> command to add an - additional recipe to satisfy the dependency and then come - back to the first recipe and add its name to - <filename>DEPENDS</filename>. + additional recipe that satisfies the dependency. + Once you add that recipe, you need to update the + <filename>DEPENDS</filename> variable in the original recipe + to include the new recipe. </para> <para> If you need to add runtime dependencies, you can do so by adding the following to your recipe: <literallayout class='monospaced'> - RDEPENDS_${PN} += "dependency1 dependency2 ..." + RDEPENDS_${PN} += "<replaceable>dependency1 dependency2 ...</replaceable>" </literallayout> <note> The <filename>devtool add</filename> command often cannot @@ -1031,7 +1145,7 @@ script for the software the recipe is building for further details. In some cases, you might find you can substitute the - dependency for an option to disable the associated + dependency with an option that disables the associated functionality passed to the configure script. </note> </para> @@ -1043,20 +1157,24 @@ <para> The <filename>devtool add</filename> command attempts to determine if the software you are adding is able to be - distributed under a common open-source license and sets the + distributed under a common, open-source license. + If so, the command sets the <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> value accordingly. - You should double-check this value against the documentation - or source files for the software you are building and update - that <filename>LICENSE</filename> value if necessary. + You should double-check the value added by the command against + the documentation or source files for the software you are + building and, if necessary, update that + <filename>LICENSE</filename> value. </para> <para> The <filename>devtool add</filename> command also sets the <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> value to point to all files that appear to be license-related. - However, license statements often appear in comments at the top - of source files or within documentation. + Realize that license statements often appear in comments at + the top of source files or within the documentation. + In such cases, the command does not recognize those license + statements. Consequently, you might need to amend the <filename>LIC_FILES_CHKSUM</filename> variable to point to one or more of those comments if present. @@ -1070,14 +1188,13 @@ <para> If the <filename>devtool add</filename> command cannot - determine licensing information, the - <filename>LICENSE</filename> value is set to "CLOSED" and the - <filename>LIC_FILES_CHKSUM</filename> value remains unset. - This behavior allows you to continue with development but is - unlikely to be correct in all cases. - Consequently, you should check the documentation or source - files for the software you are building to determine the actual - license. + determine licensing information, <filename>devtool</filename> + sets the <filename>LICENSE</filename> value to "CLOSED" and + leaves the <filename>LIC_FILES_CHKSUM</filename> value unset. + This behavior allows you to continue with development even + though the settings are unlikely to be correct in all cases. + You should check the documentation or source files for the + software you are building to determine the actual license. </para> </section> @@ -1085,8 +1202,8 @@ <title>Adding Makefile-Only Software</title> <para> - The use of <filename>make</filename> by itself is very common - in both proprietary and open source software. + The use of Make by itself is very common in both proprietary + and open-source software. Unfortunately, Makefiles are often not written with cross-compilation in mind. Thus, <filename>devtool add</filename> often cannot do very @@ -1099,7 +1216,7 @@ <filename>gcc</filename> is the compiler for the build host and the cross-compiler is named something similar to <filename>arm-poky-linux-gnueabi-gcc</filename> and might - require some arguments (e.g. to point to the associated sysroot + require arguments (e.g. to point to the associated sysroot for the target machine). </para> @@ -1114,18 +1231,17 @@ <filename>g++</filename>. </para></listitem> <listitem><para> - The environment in which <filename>make</filename> runs - is set up with various standard variables for - compilation (e.g. <filename>CC</filename>, - <filename>CXX</filename>, and so forth) in a similar - manner to the environment set up by the SDK's - environment setup script. + The environment in which Make runs is set up with + various standard variables for compilation (e.g. + <filename>CC</filename>, <filename>CXX</filename>, and + so forth) in a similar manner to the environment set + up by the SDK's environment setup script. One easy way to see these variables is to run the <filename>devtool build</filename> command on the recipe and then look in <filename>oe-logs/run.do_compile</filename>. - Towards the top of this file you will see a list of - environment variables that are being set. + Towards the top of this file, a list of environment + variables exists that are being set. You can take advantage of these variables within the Makefile. </para></listitem> @@ -1133,7 +1249,7 @@ If the Makefile sets a default for a variable using "=", that default overrides the value set in the environment, which is usually not desirable. - In this situation, you can either patch the Makefile + For this case, you can either patch the Makefile so it sets the default using the "?=" operator, or you can alternatively force the value on the <filename>make</filename> command line. @@ -1158,16 +1274,17 @@ This is particularly true because those hardcoded paths often point to locations on the build host and thus will either be read-only or will introduce - contamination into the cross-compilation by virtue of - being specific to the build host rather than the target. + contamination into the cross-compilation because they + are specific to the build host rather than the target. Patching the Makefile to use prefix variables or other - path variables is usually the way to handle this. + path variables is usually the way to handle this + situation. </para></listitem> <listitem><para> Sometimes a Makefile runs target-specific commands such as <filename>ldconfig</filename>. - For such cases, you might be able to simply apply - patches that remove these commands from the Makefile. + For such cases, you might be able to apply patches that + remove these commands from the Makefile. </para></listitem> </itemizedlist> </para> @@ -1178,9 +1295,11 @@ <para> Often, you need to build additional tools that run on the - build host system as opposed to the target. - You should indicate this using one of the following methods - when you run <filename>devtool add</filename>: + <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink> + as opposed to the target. + You should indicate this requirement by using one of the + following methods when you run + <filename>devtool add</filename>: <itemizedlist> <listitem><para> Specify the name of the recipe such that it ends @@ -1202,8 +1321,8 @@ typically accomplish this by building the native and target parts separately rather than within the same compilation process. - Realize though that with the "‐‐also-native" option, you - can add the tool using just one recipe file. + Realize though that with the "‐‐also-native" + option, you can add the tool using just one recipe file. </note> </para> </section> @@ -1244,11 +1363,9 @@ found" errors. </para></listitem> <listitem><para> - In order to support adding - Node.js modules, a - <filename>nodejs</filename> recipe must be part of your - SDK in order to provide Node.js - itself. + In order to support adding Node.js modules, a + <filename>nodejs</filename> recipe must be part + of your SDK. </para></listitem> </itemizedlist> </note> @@ -1257,14 +1374,15 @@ <para> As mentioned earlier, you can also add Node.js modules directly from a repository or local source tree. - To add modules this way, use <filename>devtool add</filename> in - the following form: + To add modules this way, use <filename>devtool add</filename> + in the following form: <literallayout class='monospaced'> $ devtool add https://github.com/diversario/node-ssdp </literallayout> - In this example, <filename>devtool</filename> fetches the specified - Git repository, detects that the code is Node.js code, fetches - dependencies using <filename>npm</filename>, and sets + In this example, <filename>devtool</filename> fetches the + specified Git repository, detects the code as Node.js + code, fetches dependencies using <filename>npm</filename>, and + sets <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> accordingly. </para> @@ -1275,8 +1393,9 @@ <title>Working With Recipes</title> <para> - When building a recipe with <filename>devtool build</filename>, the - typical build progression is as follows: + When building a recipe using the + <filename>devtool build</filename> command, the typical build + progresses as follows: <orderedlist> <listitem><para> Fetch the source @@ -1288,7 +1407,7 @@ Configure the source </para></listitem> <listitem><para> - Compiling the source + Compile the source </para></listitem> <listitem><para> Install the build output @@ -1299,10 +1418,13 @@ </orderedlist> For recipes in the workspace, fetching and unpacking is disabled as the source tree has already been prepared and is persistent. - Each of these build steps is defined as a function, usually with a - "do_" prefix. - These functions are typically shell scripts but can instead be written - in Python. + Each of these build steps is defined as a function (task), usually + with a "do_" prefix (e.g. + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>, + and so forth). + These functions are typically shell scripts but can instead be + written in Python. </para> <para> @@ -1310,12 +1432,13 @@ recipe does not include complete instructions for building the software. Instead, common functionality is encapsulated in classes inherited - with the <filename>inherit</filename> directive, leaving the recipe - to describe just the things that are specific to the software to be - built. - A <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink> - class exists that is implicitly inherited by all recipes and provides - the functionality that most typical recipes need. + with the <filename>inherit</filename> directive. + This technique leaves the recipe to describe just the things that + are specific to the software being built. + A + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink> + class exists that is implicitly inherited by all recipes and + provides the functionality that most recipes typically need. </para> <para> @@ -1327,46 +1450,57 @@ <title>Finding Logs and Work Files</title> <para> - When you are debugging a recipe that you previously created using - <filename>devtool add</filename> or whose source you are modifying - by using the <filename>devtool modify</filename> command, after - the first run of <filename>devtool build</filename>, you will - find some symbolic links created within the source tree: - <filename>oe-logs</filename>, which points to the directory in - which log files and run scripts for each build step are created - and <filename>oe-workdir</filename>, which points to the temporary - work area for the recipe. - You can use these links to get more information on what is - happening at each build step. - </para> - - <para> - These locations under <filename>oe-workdir</filename> are - particularly useful: + After the first run of the <filename>devtool build</filename> + command, recipes that were previously created using the + <filename>devtool add</filename> command or whose sources were + modified using the <filename>devtool modify</filename> + command contain symbolic links created within the source tree: <itemizedlist> - <listitem><para><filename>image/</filename>: - Contains all of the files installed at the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> - stage. - Within a recipe, this directory is referred to by the - expression - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>. - </para></listitem> - <listitem><para><filename>sysroot-destdir/</filename>: - Contains a subset of files installed within - <filename>do_install</filename> that have been put into the - shared sysroot. - For more information, see the - "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>" - section. + <listitem><para> + <filename>oe-logs</filename>: + This link points to the directory in which log files + and run scripts for each build step are created. </para></listitem> - <listitem><para><filename>packages-split/</filename>: - Contains subdirectories for each package produced by the + <listitem><para> + <filename>oe-workdir</filename>: + This link points to the temporary work area for the recipe. - For more information, see the - "<link linkend='sdk-packaging'>Packaging</link>" section. + The following locations under + <filename>oe-workdir</filename> are particularly + useful: + <itemizedlist> + <listitem><para> + <filename>image/</filename>: + Contains all of the files installed during + the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + stage. + Within a recipe, this directory is referred + to by the expression + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>. + </para></listitem> + <listitem><para> + <filename>sysroot-destdir/</filename>: + Contains a subset of files installed within + <filename>do_install</filename> that have + been put into the shared sysroot. + For more information, see the + "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>" + section. + </para></listitem> + <listitem><para> + <filename>packages-split/</filename>: + Contains subdirectories for each package + produced by the recipe. + For more information, see the + "<link linkend='sdk-packaging'>Packaging</link>" + section. + </para></listitem> + </itemizedlist> </para></listitem> </itemizedlist> + You can use these links to get more information on what is + happening at each build step. </para> </section> @@ -1413,12 +1547,14 @@ <para> Recipes often need to use files provided by other recipes on - the build host. + the + <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>. For example, an application linking to a common library needs access to the library itself and its associated headers. The way this access is accomplished within the extensible SDK is through the sysroot. - One sysroot exists per "machine" for which the SDK is being built. + One sysroot exists per "machine" for which the SDK is being + built. In practical terms, this means a sysroot exists for the target machine, and a sysroot exists for the build host. </para> @@ -1431,7 +1567,7 @@ task within the <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename> directory. - A subset of these files automatically go into the sysroot. + A subset of these files automatically goes into the sysroot. The reason for this limitation is that almost all files that go into the sysroot are cataloged in manifests in order to ensure they can be removed later when a recipe is modified or removed. @@ -1456,20 +1592,20 @@ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> task, files installed during the <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> - task are split into one main package, which is almost always named - the same as the recipe, and several other packages. - This separation is done because not all of those installed files - are always useful in every image. + task are split into one main package, which is almost always + named the same as the recipe, and into several other packages. + This separation exists because not all of those installed files + are useful in every image. For example, you probably do not need any of the documentation installed in a production image. - Consequently, for each recipe the documentation files are separated - into a <filename>-doc</filename> package. - Recipes that package software that has optional modules or - plugins might do additional package splitting as well. + Consequently, for each recipe the documentation files are + separated into a <filename>-doc</filename> package. + Recipes that package software containing optional modules or + plugins might undergo additional package splitting as well. </para> <para> - After building a recipe you can see where files have gone by + After building a recipe, you can see where files have gone by looking in the <filename>oe-workdir/packages-split</filename> directory, which contains a subdirectory for each package. Apart from some advanced cases, the @@ -1479,17 +1615,18 @@ variables controls splitting. The <filename>PACKAGES</filename> variable lists all of the packages to be produced, while the <filename>FILES</filename> - variable specifies which files to include in each package, + variable specifies which files to include in each package by using an override to specify the package. - For example, <filename>FILES_${PN}</filename> specifies the files - to go into the main package (i.e. the main package is named the - same as the recipe and + For example, <filename>FILES_${PN}</filename> specifies the + files to go into the main package (i.e. the main package has + the same name as the recipe and <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> evaluates to the recipe name). - The order of the <filename>PACKAGES</filename> value is significant. + The order of the <filename>PACKAGES</filename> value is + significant. For each installed file, the first package whose - <filename>FILES</filename> value matches the file is the package - into which the file goes. + <filename>FILES</filename> value matches the file is the + package into which the file goes. Defaults exist for both the <filename>PACKAGES</filename> and <filename>FILES</filename> variables. Consequently, you might find you do not even need to set these @@ -1511,29 +1648,29 @@ <filename>devtool deploy-target</filename> command. Because the <filename>devtool deploy-target</filename> command backs up any files it overwrites, you can use the - <filename>devtool undeploy-target</filename> to restore those files - and remove any other files the recipe deployed. + <filename>devtool undeploy-target</filename> command to restore + those files and remove any other files the recipe deployed. Consider the following example: <literallayout class='monospaced'> $ devtool undeploy-target lighttpd root@192.168.7.2 </literallayout> If you have deployed multiple applications, you can remove them - all at once thus restoring the target device back to its + all using the "-a" option thus restoring the target device to its original state: <literallayout class='monospaced'> $ devtool undeploy-target -a root@192.168.7.2 </literallayout> Information about files deployed to the target as well as any backed up files are stored on the target itself. - This storage of course requires some additional space + This storage, of course, requires some additional space on the target machine. <note> The <filename>devtool deploy-target</filename> and - <filename>devtool undeploy-target</filename> command do not + <filename>devtool undeploy-target</filename> commands do not currently interact with any package management system on the target device (e.g. RPM or OPKG). - Consequently, you should not intermingle operations - <filename>devtool deploy-target</filename> and the package + Consequently, you should not intermingle + <filename>devtool deploy-target</filename> and package manager operations on the target device. Doing so could result in a conflicting set of files. </note> @@ -1544,16 +1681,14 @@ <title>Installing Additional Items Into the Extensible SDK</title> <para> - The extensible SDK typically only comes with a small number of tools - and libraries out of the box. - If you have a minimal SDK, then it starts mostly empty and is - populated on-demand. - However, sometimes you will need to explicitly install extra items - into the SDK. + Out of the box the extensible SDK typically only comes with a small + number of tools and libraries. + A minimal SDK starts mostly empty and is populated on-demand. + Sometimes you must explicitly install extra items into the SDK. If you need these extra items, you can first search for the items using the <filename>devtool search</filename> command. For example, suppose you need to link to libGL but you are not sure - which recipe provides it. + which recipe provides libGL. You can use the following command to find out: <literallayout class='monospaced'> $ devtool search libGL @@ -1564,17 +1699,19 @@ <literallayout class='monospaced'> $ devtool sdk-install mesa </literallayout> - By default, the <filename>devtool sdk-install</filename> assumes the - item is available in pre-built form from your SDK provider. + By default, the <filename>devtool sdk-install</filename> command + assumes the item is available in pre-built form from your SDK + provider. If the item is not available and it is acceptable to build the item from source, you can add the "-s" option as follows: <literallayout class='monospaced'> $ devtool sdk-install -s mesa </literallayout> - It is important to remember that building the item from source takes - significantly longer than installing the pre-built artifact. - Also, if no recipe exists for the item you want to add to the SDK, you - must instead add it using the <filename>devtool add</filename> command. + It is important to remember that building the item from source + takes significantly longer than installing the pre-built artifact. + Also, if no recipe exists for the item you want to add to the SDK, + you must instead add the item using the + <filename>devtool add</filename> command. </para> </section> @@ -1612,31 +1749,34 @@ <para> You might need to produce an SDK that contains your own custom - libraries for sending to a third party (e.g., if you are a vendor with - customers needing to build their own software for the target platform). - If that is the case, then you can produce a derivative SDK based on - the currently installed SDK fairly easily. - Use these steps: + libraries. + A good example would be if you were a vendor with customers that + use your SDK to build their own platform-specific software and + those customers need an SDK that has custom libraries. + In such a case, you can produce a derivative SDK based on the + currently installed SDK fairly easily by following these steps: <orderedlist> - <listitem><para>If necessary, install an extensible SDK that + <listitem><para> + If necessary, install an extensible SDK that you want to use as a base for your derivative SDK. </para></listitem> - <listitem><para>Source the environment script for the SDK. + <listitem><para> + Source the environment script for the SDK. </para></listitem> - <listitem><para>Add the extra libraries or other components - you want by using the <filename>devtool add</filename> - command. + <listitem><para> + Add the extra libraries or other components you want by + using the <filename>devtool add</filename> command. </para></listitem> - <listitem><para>Run the <filename>devtool build-sdk</filename> - command. + <listitem><para> + Run the <filename>devtool build-sdk</filename> command. </para></listitem> </orderedlist> - The above procedure takes the recipes added to the workspace and - constructs a new SDK installer containing those recipes and the + The previous steps take the recipes added to the workspace and + construct a new SDK installer that contains those recipes and the resulting binary artifacts. The recipes go into their own separate layer in the constructed - derivative SDK, leaving the workspace clean and ready for users - to add their own recipes. + derivative SDK, which leaves the workspace clean and ready for + users to add their own recipes. </para> </section> </chapter> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml index b6925fa26..8642be61a 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml @@ -31,15 +31,18 @@ <para> All SDKs consist of the following: <itemizedlist> - <listitem><para><emphasis>Cross-Development Toolchain</emphasis>: + <listitem><para> + <emphasis>Cross-Development Toolchain</emphasis>: This toolchain contains a compiler, debugger, and various miscellaneous tools. </para></listitem> - <listitem><para><emphasis>Libraries, Headers, and Symbols</emphasis>: + <listitem><para> + <emphasis>Libraries, Headers, and Symbols</emphasis>: The libraries, headers, and symbols are specific to the image (i.e. they match the image). </para></listitem> - <listitem><para><emphasis>Environment Setup Script</emphasis>: + <listitem><para> + <emphasis>Environment Setup Script</emphasis>: This <filename>*.sh</filename> file, once run, sets up the cross-development environment by defining variables and preparing for SDK use. @@ -48,7 +51,7 @@ </para> <para> - Additionally an extensible SDK has tools that allow you to easily add + Additionally, an extensible SDK has tools that allow you to easily add new applications and libraries to an image, modify the source of an existing component, test changes on the target hardware, and easily integrate an application into the @@ -81,14 +84,15 @@ 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. + Understand, however, that every target still needs a sysroot because + those binaries are target-specific. </para> <para> The SDK development environment consists of the following: <itemizedlist> - <listitem><para>The self-contained SDK, which is an + <listitem><para> + The self-contained SDK, which is an architecture-specific cross-toolchain and matching sysroots (target and native) all built by the OpenEmbedded build system (e.g. the SDK). @@ -100,21 +104,24 @@ Additionally, the extensible SDK contains the <filename>devtool</filename> functionality. </para></listitem> - <listitem><para>The Quick EMUlator (QEMU), which lets you simulate + <listitem><para> + The Quick EMUlator (QEMU), which lets you simulate target hardware. QEMU is not literally part of the SDK. You must build and include this emulator separately. However, QEMU plays an important role in the development process that revolves around use of the SDK. </para></listitem> - <listitem><para>The Eclipse IDE Yocto Plug-in. + <listitem><para> + The Eclipse IDE Yocto Plug-in. This plug-in is available for you if you are an Eclipse user. In the same manner as QEMU, the plug-in is not literally part of the SDK but is rather available for use as part of the development process. </para></listitem> - <listitem><para>Various performance-related + <listitem><para> + Various performance-related <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink> that can enhance your development experience. These tools are also separate from the actual SDK but can be @@ -192,11 +199,11 @@ </tgroup> </informaltable> <literallayout class='monospaced'> - * Extensible SDK will contain the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default. + * Extensible SDK contains the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default. - ** Sysroot is managed through use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries. + ** Sysroot is managed through the use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries. - *** Runtime package management can be added to the standard SDK but it is not supported by default. + *** You can add runtime package management to the standard SDK but it is not supported by default. **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install. </literallayout> @@ -216,7 +223,7 @@ This toolchain is created by running a SDK installer script or through a <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> - that is based on your Metadata configuration or extension for + that is based on your metadata configuration or extension for your targeted device. The cross-toolchain works with a matching target sysroot. </para> @@ -230,7 +237,7 @@ for generating binaries that run on the target architecture. The target sysroot is based on the target root filesystem image that is built by the OpenEmbedded build system and uses the same - Metadata configuration used to build the cross-toolchain. + metadata configuration used to build the cross-toolchain. </para> </section> @@ -240,7 +247,8 @@ <para> The QEMU emulator allows you to simulate your hardware while running your application or image. - QEMU is not part of the SDK but is made available a number of ways: + QEMU is not part of the SDK but is made available a number of + different ways: <itemizedlist> <listitem><para> If you have cloned the <filename>poky</filename> Git @@ -265,7 +273,7 @@ </section> <section id='eclipse-overview'> - <title>Eclipse Yocto Plug-in</title> + <title><trademark class='trade'>Eclipse</trademark> Yocto Plug-in</title> <para> The Eclipse IDE is a popular development environment and it fully @@ -285,8 +293,8 @@ Previous releases of the Eclipse Yocto Plug-in supported "user-space tools" (i.e. LatencyTOP, PowerTOP, Perf, SystemTap, and Lttng-ust) that also added to the development experience. - These tools have been deprecated beginning with this release - of the plug-in. + These tools have been deprecated with the release of the + Eclipse Yocto Plug-in. </note> </para> @@ -335,14 +343,18 @@ <para> You just need to follow these general steps: <orderedlist> - <listitem><para><emphasis>Install the SDK for your target hardware:</emphasis> + <listitem><para> + <emphasis>Install the SDK for your target hardware:</emphasis> For information on how to install the SDK, see the "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" - section.</para></listitem> - <listitem><para><emphasis>Download or Build the Target Image:</emphasis> + section. + </para></listitem> + <listitem><para> + <emphasis>Download or Build the Target Image:</emphasis> The Yocto Project supports several target architectures and has many pre-built kernel images and root filesystem images.</para> + <para>If you are going to develop your application on hardware, go to the <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> @@ -356,6 +368,7 @@ so forth. Be sure to get the files you need for your particular development process.</para> + <para>If you are going to develop your application and then run and test it using the QEMU emulator, go to the <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink> @@ -364,35 +377,35 @@ target architecture (e.g. <filename>qemux86_64</filename> for an <trademark class='registered'>Intel</trademark>-based 64-bit architecture). - Download kernel, root filesystem, and any other files you + Download the kernel, root filesystem, and any other files you need for your process. <note> - To use the root filesystem in QEMU, you - need to extract it. + To use the root filesystem in QEMU, you need to extract it. See the "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section for information on how to extract the root filesystem. </note> </para></listitem> - <listitem><para><emphasis>Develop and Test your - Application:</emphasis> At this point, you have the tools - to develop your application. - If you need to separately install and use the QEMU - emulator, you can go to + <listitem><para> + <emphasis>Develop and Test your Application:</emphasis> + At this point, you have the tools to develop your application. + If you need to separately install and use the QEMU emulator, + you can go to <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink> to download and learn about the emulator. See the "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" chapter in the Yocto Project Development Tasks Manual for information on using QEMU within the Yocto - Project.</para></listitem> + Project. + </para></listitem> </orderedlist> </para> <para> - The remainder of this manual describes how to use both the standard - SDK and the extensible SDK. + The remainder of this manual describes how to use the extensible + and standard SDKs. Information also exists in appendix form that describes how you can build, install, and modify an SDK. </para> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml index 7fc0472cd..e858b9b1c 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml @@ -52,14 +52,9 @@ <revremark>Released with the Yocto Project 2.4 Release.</revremark> </revision> <revision> - <revnumber>2.4.1</revnumber> - <date>January 2018</date> - <revremark>Released with the Yocto Project 2.4.1 Release.</revremark> - </revision> - <revision> - <revnumber>2.4.2</revnumber> - <date>March 2018</date> - <revremark>Released with the Yocto Project 2.4.2 Release.</revremark> + <revnumber>2.5</revnumber> + <date>May 2018</date> + <revremark>Released with the Yocto Project 2.5 Release.</revremark> </revision> </revhistory> @@ -81,27 +76,38 @@ manual is for the &YOCTO_DOC_VERSION; release of the Yocto Project. To be sure you have the latest version of the manual - for this release, use the manual from the - <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + for this release, go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and select the manual from that site. + Manuals from the site are more up-to-date than manuals + derived from the Yocto Project released TAR files. </para></listitem> <listitem><para> - For manuals associated with other releases of the Yocto - Project, go to the + If you located this manual through a web search, the + version of the manual might not be the one you want + (e.g. the search might have returned a manual much + older than the Yocto Project version with which you + are working). + You can see all Yocto Project major releases by + visiting the + <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink> + page. + If you need a version of this manual for a different + Yocto Project release, visit the <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> - and use the drop-down "Active Releases" button - and choose the manual associated with the desired - Yocto Project. + and select the manual set by using the + "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE" + pull-down menus. </para></listitem> <listitem><para> - To report any inaccuracies or problems with this - manual, send an email to the Yocto Project - discussion group at - <filename>yocto@yoctoproject.com</filename> or log into - the freenode <filename>#yocto</filename> channel. - </para></listitem> + To report any inaccuracies or problems with this + manual, send an email to the Yocto Project + discussion group at + <filename>yocto@yoctoproject.com</filename> or log into + the freenode <filename>#yocto</filename> channel. + </para></listitem> </itemizedlist> </note> - </legalnotice> </bookinfo> @@ -122,7 +128,7 @@ <xi:include href="sdk-appendix-customizing-standard.xml"/> - <xi:include href="sdk-appendix-mars.xml"/> + <xi:include href="sdk-appendix-neon.xml"/> <!-- <index id='index'> <title>Index</title> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml index 7281e83ef..dd220c340 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml @@ -19,9 +19,9 @@ <para> You can use a standard SDK to work on Makefile, Autotools, and - Eclipse-based projects. + <trademark class='trade'>Eclipse</trademark>-based projects. See the - "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>" + "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>" chapter for more information. </para> @@ -53,24 +53,24 @@ <title>Installing the SDK</title> <para> - The first thing you need to do is install the SDK on your host - development machine by running the <filename>*.sh</filename> - installation script. + The first thing you need to do is install the SDK on your + <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink> + by running the <filename>*.sh</filename> installation script. </para> <para> You can download a tarball installer, which includes the pre-built toolchain, the <filename>runqemu</filename> - script, and support files from the appropriate directory under - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. - Toolchains are available for 32-bit and 64-bit x86 development - systems from the <filename>i686</filename> and - <filename>x86_64</filename> directories, respectively. + script, and support files from the appropriate + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink> + directory within the Index of Releases. + Toolchains are available for several 32-bit and 64-bit + architectures with the <filename>x86_64</filename> directories, + respectively. The toolchains the Yocto Project provides are based off the - <filename>core-image-sato</filename> image and contain + <filename>core-image-sato</filename> and + <filename>core-image-minimal</filename> images and contain libraries appropriate for developing against that image. - Each type of development system supports five or more target - architectures. </para> <para> @@ -86,14 +86,15 @@ i686 or x86_64. - <replaceable>image_type</replaceable> is the image for which the SDK was built. + <replaceable>image_type</replaceable> is the image for which the SDK was built: + + core-image-minimal or core-image-sato. <replaceable>arch</replaceable> is a string representing the tuned target architecture: - i586, x86_64, powerpc, mips, armv7a or armv5te + aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon. - <replaceable>release_version</replaceable> is a string representing the release number of the - Yocto Project: + <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project: &DISTRO;, &DISTRO;+snapshot </literallayout> @@ -120,38 +121,36 @@ <para> The SDK and toolchains are self-contained and by default are - installed 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 SDK - installer script so that it is executable: - <literallayout class='monospaced'> - $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout> - </note> + installed into the <filename>poky_sdk</filename> folder in your + home directory. + You can choose to install the extensible SDK in any location when + you run the installer. + However, because files need to be written under that directory + during the normal course of operation, the location you choose + for installation must be writable for whichever + users need to use the SDK. </para> <para> The following command shows how to run the installer given a toolchain tarball for a 64-bit x86 development host system and - a 32-bit x86 target architecture. + a 64-bit x86 target architecture. The example assumes the SDK installer is located in - <filename>~/Downloads/</filename>. + <filename>~/Downloads/</filename> and has execution rights. <note> If you do not have write permissions for the directory into which you are installing the SDK, the installer notifies you and exits. - Be sure you have write permissions in the directory and - run the installer again. + For that case, set up the proper permissions in the directory + and run the installer again. </note> <literallayout class='monospaced'> - $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh Poky (Yocto Project Reference Distro) SDK installer version &DISTRO; =============================================================== Enter target directory for SDK (default: /opt/poky/&DISTRO;): You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed[Y/n]? Y - Extracting SDK.......................................................................done + 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. @@ -172,12 +171,11 @@ <para> Once you have the SDK installed, you must run the SDK environment - setup script before you can actually use it. + setup script before you can actually use the SDK. This setup script resides in the directory you chose when you - installed the SDK. - For information on where this setup script can reside, see the - "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>" - Appendix. + installed the SDK, which is either the default + <filename>/opt/poky/&DISTRO;</filename> directory or the directory + you chose during installation. </para> <para> @@ -186,9 +184,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 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: + As an example, the following commands set the working directory + to where the SDK was installed and then source the environment + setup script. + In this example, the setup script is for an IA-based + target machine using i586 tuning: <literallayout class='monospaced'> $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux </literallayout> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml index 6965e3f28..d8cc4229d 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml @@ -8,7 +8,7 @@ <para> You can use the SDK toolchain directly with Makefile, - Autotools, and <trademark class='trade'>Eclipse</trademark> based + Autotools, and <trademark class='trade'>Eclipse</trademark>-based projects. This chapter covers the first two, while the "<link linkend='sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>" @@ -19,263 +19,494 @@ <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. + Once you have a suitable + <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchain</ulink> + installed, it is very easy to develop a project using the + <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>GNU Autotools-based</ulink> + workflow, which is outside of the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>. </para> - <section id='creating-and-running-a-project-based-on-gnu-autotools'> - <title>Creating and Running a Project Based on GNU Autotools</title> + <para> + The following figure presents a simple Autotools workflow. + <imagedata fileref="figures/sdk-autotools-flow.png" width="7in" height="8in" align="center" /> + </para> - <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'> + <para> + Follow these steps to create a simple Autotools-based + "Hello World" project: + <note> + For more information on the GNU Autotools workflow, + see the same example on the + <ulink url='https://developer.gnome.org/anjuta-build-tutorial/stable/create-autotools.html.en'>GNOME Developer</ulink> + site. + </note> + <orderedlist> + <listitem><para> + <emphasis>Create a Working Directory and Populate It:</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.ac</filename> files as follows: - <itemizedlist> - <listitem><para> - For <filename>hello.c</filename>, include - these lines: - <literallayout class='monospaced'> + </literallayout> + After setting up the directory, populate it with files + needed for the flow. + You need a project source file, a file to help with + configuration, and a file to help create the Makefile, + and a README file: + <filename>hello.c</filename>, + <filename>configure.ac</filename>, + <filename>Makefile.am</filename>, and + <filename>README</filename>, respectively.</para> + + <para> Use the following command to create an empty README + file, which is required by GNU Coding Standards: + <literallayout class='monospaced'> + $ touch README + </literallayout> + Create the remaining three files as follows: + <itemizedlist> + <listitem><para> + <emphasis><filename>hello.c</filename>:</emphasis> + <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'> + </literallayout> + </para></listitem> + <listitem><para> + <emphasis><filename>configure.ac</filename>:</emphasis> + <literallayout class='monospaced'> AC_INIT(hello,0.1) AM_INIT_AUTOMAKE([foreign]) 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> - As described earlier in the manual, installing the - cross-toolchain creates a cross-toolchain - environment setup script in the directory that the SDK - 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 SDK installation directory that uses the - 32-bit Intel x86 Architecture and the - &DISTRO_NAME; Yocto Project release: - <literallayout class='monospaced'> + AC_CONFIG_FILES(Makefile) + AC_OUTPUT + </literallayout> + </para></listitem> + <listitem><para> + <emphasis><filename>Makefile.am</filename>:</emphasis> + <literallayout class='monospaced'> + bin_PROGRAMS = hello + hello_SOURCES = hello.c + </literallayout> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Source the Cross-Toolchain + Environment Setup File:</emphasis> + As described earlier in the manual, installing the + cross-toolchain creates a cross-toolchain + environment setup script in the directory that the SDK + 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". + For this example, the command sources a script from the + default SDK 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'> + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Create the <filename>configure</filename> Script:</emphasis> + Use the <filename>autoreconf</filename> command to + generate the <filename>configure</filename> script. + <literallayout class='monospaced'> + $ autoreconf + </literallayout> + The <filename>autoreconf</filename> tool takes care + of running the other Autotools such as + <filename>aclocal</filename>, + <filename>autoconf</filename>, and + <filename>automake</filename>. + <note> + If you get errors from + <filename>configure.ac</filename>, which + <filename>autoreconf</filename> runs, that indicate + missing files, you can use the "-i" option, which + ensures missing auxiliary files are copied to the build + host. + </note> + </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'> + </literallayout> + 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> + </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'> + </literallayout> + <note> + To learn about environment variables established + when you run the cross-toolchain environment setup + script and how they are used or overridden when + the Makefile, see the + "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>" + section. + </note> + This next 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> + </para></listitem> + <listitem><para> + <emphasis>Execute Your Project:</emphasis> + To execute the project, you would need to run it on your + target hardware. + If your target hardware happens to be your build host, + you could run the project as follows: <literallayout class='monospaced'> - $ libtoolize --automake - $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>] - $ autoconf - $ autoheader - $ automake -a + $ ./tmp/usr/local/bin/hello </literallayout> - </note> - </para> - </section> + As expected, the project displays the "Hello World!" + message. + </para></listitem> + </orderedlist> + </para> </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. + Simple Makefile-based projects use and interact with the + cross-toolchain environment variables established when you run + the cross-toolchain environment setup script. + The environment variables 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/&DISTRO;/sysroots/i586-poky-linux - <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/&DISTRO;/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: + This section presents a simple Makefile development flow and + provides an example that lets you see how you can use + cross-toolchain environment variables and Makefile variables + during development. + <imagedata fileref="figures/sdk-makefile-flow.png" width="6in" height="7in" align="center" /> + </para> + + <para> + The main point of this section is to explain the following three + cases regarding variable behavior: <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> Map to Equivalent + Environment Variables Set in the SDK Setup Script:</emphasis> + Because matching variables are not specifically set in the <filename>Makefile</filename>, the variables retain their - values based on the environment. + values based on the environment setup script. </para></listitem> <listitem><para> - <emphasis>Case 2 - Variables Set in the - <filename>Makefile</filename>:</emphasis> - Specifically setting variables in the + <emphasis>Case 2 - Variables Are Set in the Makefile that + Map to Equivalent Environment Variables from the SDK + Setup Script:</emphasis> + Specifically setting matching variables in the <filename>Makefile</filename> during the build results in the environment settings of the variables being overwritten. + In this case, the variables you set in the + <filename>Makefile</filename> are used. </para></listitem> <listitem><para> - <emphasis>Case 3 - Variables Set when the - <filename>Makefile</filename> is Executed from the - Command Line:</emphasis> + <emphasis>Case 3 - Variables Are Set Using the Command Line + that Map to Equivalent Environment Variables from the + SDK Setup Script:</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>. + command line results in the environment variables being + overwritten. + In this case, the command-line content is used. </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. + Regardless of how you set your variables, if you use + the "-e" option with <filename>make</filename>, the + variables from the SDK setup script take precedence: + <literallayout class='monospaced'> + $ make -e <replaceable>target</replaceable> + </literallayout> </note> </para> + + <para> + The remainder of this section presents a simple Makefile example + that demonstrates these variable behaviors. + </para> + + <para> + In a new shell environment variables are not established for the + SDK until you run the setup script. + For example, the following commands show a null value for the + compiler variable (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>). + <literallayout class='monospaced'> + $ echo ${CC} + + $ + </literallayout> + Running the SDK setup script for a 64-bit build host and an + i586-tuned target architecture for a + <filename>core-image-sato</filename> image using the current + &DISTRO; Yocto Project release and then echoing that variable + shows the value established through the script: + <literallayout class='monospaced'> + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + $ echo ${CC} + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux + </literallayout> + </para> + + <para> + To illustrate variable use, work through this simple "Hello World!" + example: + <orderedlist> + <listitem><para> + <emphasis>Create a Working Directory and Populate It:</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> + After setting up the directory, populate it with files + needed for the flow. + You need a <filename>main.c</filename> file from which you + call your function, a <filename>module.h</filename> file + to contain headers, and a <filename>module.c</filename> + that defines your function. + </para> + + <para>Create the three files as follows: + <itemizedlist> + <listitem><para> + <emphasis><filename>main.c</filename>:</emphasis> + <literallayout class='monospaced'> + #include "module.h" + void sample_func(); + int main() + { + sample_func(); + return 0; + } + </literallayout> + </para></listitem> + <listitem><para> + <emphasis><filename>module.h</filename>:</emphasis> + <literallayout class='monospaced'> + #include <stdio.h> + void sample_func(); + </literallayout> + </para></listitem> + <listitem><para> + <emphasis><filename>module.c</filename>:</emphasis> + <literallayout class='monospaced'> + #include "module.h" + void sample_func() + { + printf("Hello World!"); + printf("\n"); + } + </literallayout> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Source the Cross-Toolchain Environment Setup File:</emphasis> + As described earlier in the manual, installing the + cross-toolchain creates a cross-toolchain environment setup + script in the directory that the SDK 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". + For this example, the command sources a script from the + default SDK 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>Create the <filename>Makefile</filename>:</emphasis> + For this example, the Makefile contains two lines that + can be used to set the <filename>CC</filename> variable. + One line is identical to the value that is set when you + run the SDK environment setup script, and the other line + sets <filename>CC</filename> to "gcc", the default GNU + compiler on the build host: + <literallayout class='monospaced'> + # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux + # CC="gcc" + all: main.o module.o + ${CC} main.o module.o -o target_bin + main.o: main.c module.h + ${CC} -I . -c main.c + module.o: module.c module.h + ${CC} -I . -c module.c + clean: + rm -rf *.o + rm target_bin + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Make the Project:</emphasis> + Use the <filename>make</filename> command to create the + binary output file. + Because variables are commented out in the Makefile, + the value used for <filename>CC</filename> is the value + set when the SDK environment setup file was run: + <literallayout class='monospaced'> + $ make + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin + </literallayout> + From the results of the previous command, you can see that + the compiler used was the compiler established through + the <filename>CC</filename> variable defined in the + setup script.</para> + + <para>You can override the <filename>CC</filename> + environment variable with the same variable as set from + the Makefile by uncommenting the line in the Makefile + and running <filename>make</filename> again. + <literallayout class='monospaced'> + $ make clean + rm -rf *.o + rm target_bin + # + # Edit the Makefile by uncommenting the line that sets CC to "gcc" + # + $ make + gcc -I . -c main.c + gcc -I . -c module.c + gcc main.o module.o -o target_bin + </literallayout> + As shown in the previous example, the cross-toolchain + compiler is not used. + Rather, the default compiler is used.</para> + + <para>This next case shows how to override a variable + by providing the variable as part of the command line. + Go into the Makefile and re-insert the comment character + so that running <filename>make</filename> uses + the established SDK compiler. + However, when you run <filename>make</filename>, use a + command-line argument to set <filename>CC</filename> + to "gcc": + <literallayout class='monospaced'> + $ make clean + rm -rf *.o + rm target_bin + # + # Edit the Makefile to comment out the line setting CC to "gcc" + # + $ make + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin + $ make clean + rm -rf *.o + rm target_bin + $ make CC="gcc" + gcc -I . -c main.c + gcc -I . -c module.c + gcc main.o module.o -o target_bin + </literallayout> + In the previous case, the command-line argument overrides + the SDK environment variable.</para> + + <para>In this last case, edit Makefile again to use the + "gcc" compiler but then use the "-e" option on the + <filename>make</filename> command line: + <literallayout class='monospaced'> + $ make clean + rm -rf *.o + rm target_bin + # + # Edit the Makefile to use "gcc" + # + $ make + gcc -I . -c main.c + gcc -I . -c module.c + gcc main.o module.o -o target_bin + $ make clean + rm -rf *.o + rm target_bin + $ make -e + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c + i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin + </literallayout> + In the previous case, the "-e" option forces + <filename>make</filename> to use the SDK environment + variables regardless of the values in the Makefile. + </para></listitem> + <listitem><para> + <emphasis>Execute Your Project:</emphasis> + To execute the project (i.e. + <filename>target_bin</filename>), use the following + command: + <literallayout class='monospaced'> + $ ./target_bin + Hello World! + </literallayout> + <note> + If you used the cross-toolchain compiler to build + <filename>target_bin</filename> and your build host + differs in architecture from that of the target + machine, you need to run your project on the target + device. + </note> + As expected, the project displays the "Hello World!" + message. + </para></listitem> + </orderedlist> + </para> </section> </chapter> <!-- |