Yocto 2.5
Move OpenBMC to Yocto 2.5(sumo)
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Change-Id: I5c5ad6904a16e14c1c397f0baf10c9d465594a78
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
new file mode 100644
index 0000000..ec6685f
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-autotools-flow.png
Binary files differ
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
index 985ac33..e7d6173 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
Binary files differ
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
index fd684ff..18ba8b7 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
Binary files differ
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
index 65474da..7d4f395 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
Binary files differ
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
new file mode 100644
index 0000000..0ccb418
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-makefile-flow.png
Binary files differ
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 587526f..5b56e73 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
similarity index 89%
rename from import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml
rename to import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-neon.xml
index 2d80f64..f648047 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 ab9055e..aa06358 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 bdb8344..3eb85e8 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>
- Expand
- <filename>Yocto Project SDK Autotools Project</filename>.
+ Select "C Managed Build" from the available options and
+ click "Next".
</para></listitem>
<listitem><para>
- Select <filename>Hello World ANSI C Autotools Projects</filename>.
+ Expand "Yocto Project SDK Autotools Project".
+ </para></listitem>
+ <listitem><para>
+ 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 444d816..5215a9d 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>
+ The <replaceable>target</replaceable> is a live target
+ machine running as an SSH server.</para>
- <para>You can, of course, also deploy the image you build
- using the <filename>devtool build-image</filename> command
- to actual hardware.
- However, <filename>devtool</filename> does not provide a
- specific command that allows you to do this.
+ <para>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>
+ 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.
+ <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>
+ The <replaceable>target</replaceable> is a live target
+ machine running as an SSH server.</para>
- <para>You can, of course, also deploy the image you build
- using the <filename>devtool build-image</filename> command
- to actual hardware.
- However, <filename>devtool</filename> does not provide a
- specific command that allows you to do this.
+ <para>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>
+ <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.
+ <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>.
+ <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>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
+ <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 b6925fa..8642be6 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 7fc0472..e858b9b 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>.
- </para></listitem>
- <listitem><para>
- For manuals associated with other releases of the Yocto
- Project, go to the
+ for this release, go to 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 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>
- 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>
+ 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 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>
</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 7281e83..dd220c3 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 6965e3f..d8cc422 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'>
- $ file ./tmp/usr/local/bin/hello
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Execute your project:</emphasis>
- To execute the project in the shell, simply enter
- the name.
- You could also copy the binary to the actual target
- hardware and run the project there as well:
- <literallayout class='monospaced'>
- $ ./hello
- </literallayout>
- As expected, the project displays the "Hello World!"
- message.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='passing-host-options'>
- <title>Passing Host Options</title>
-
- <para>
- For an Autotools-based project, you can use the cross-toolchain
- by just passing the appropriate host option to
- <filename>configure.sh</filename>.
- The host option you use is derived from the name of the
- environment setup script found in the directory in which you
- installed the cross-toolchain.
- For example, the host option for an ARM-based target that uses
- the GNU EABI is <filename>armv5te-poky-linux-gnueabi</filename>.
- You will notice that the name of the script is
- <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
- Thus, the following command works to update your project and
- rebuild it using the appropriate cross-toolchain tools:
- <literallayout class='monospaced'>
- $ ./configure --host=armv5te-poky-linux-gnueabi \
- --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
- </literallayout>
- <note>
- If the <filename>configure</filename> script results in
- problems recognizing the
- <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable>
- option, regenerate the script to enable the support by
- doing the following and then run the script again:
- <literallayout class='monospaced'>
- $ libtoolize --automake
- $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
- $ autoconf
- $ autoheader
- $ automake -a
</literallayout>
- </note>
- </para>
- </section>
+ <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, 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'>
+ $ ./tmp/usr/local/bin/hello
+ </literallayout>
+ 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>
<!--
