Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/sdk-manual/sdk-working-projects.xml b/poky/documentation/sdk-manual/sdk-working-projects.xml
new file mode 100644
index 0000000..070d903
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-working-projects.xml
@@ -0,0 +1,511 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='sdk-working-projects'>
+
+ <title>Using the SDK Toolchain Directly</title>
+
+ <para>
+ You can use the SDK toolchain directly with Makefile and
+ Autotools-based projects.
+ </para>
+
+ <section id='autotools-based-projects'>
+ <title>Autotools-Based Projects</title>
+
+ <para>
+ 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>
+
+ <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
+ "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>
+ 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>
+ <emphasis><filename>configure.ac</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ AC_INIT(hello,0.1)
+ AM_INIT_AUTOMAKE([foreign])
+ AC_PROG_CC
+ 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>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>
+ 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>
+ <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>
+ 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>
+ 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> 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 setup script.
+ </para></listitem>
+ <listitem><para>
+ <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 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 environment variables being
+ overwritten.
+ In this case, the command-line content is used.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ 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>
+<!--
+vim: expandtab tw=80 ts=4
+-->