documentation: adt-manual - autotools-based projects
Fixes [YOCTO #2645] In the section that describes how to build a toolchain using bitbake meta-toolchain, I updated the note about the MACHINE and SDKMACHINE variables. These needed to be pointed out to the user as important variables for correct settings before generating the toolchain. I added a new section for the autotools-based programs that now includes a simple "Hello World" example. This section precedes the section that describes how to pass host options to configure.sh. (From yocto-docs rev: 9849e7b94d42a851f30f0fba8ae60916697956dd) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
parent
e197fca49c
commit
55530d42e7
|
@ -29,39 +29,168 @@
|
||||||
<title>Autotools-Based Projects</title>
|
<title>Autotools-Based Projects</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
For an Autotools-based project, you can use the cross-toolchain by just
|
Once you have a suitable cross-toolchain installed, it is very easy to
|
||||||
passing the appropriate host option to <filename>configure.sh</filename>.
|
develop a project outside of the OpenEmbedded build system.
|
||||||
The host option you use is derived from the name of the environment setup
|
This section presents a simple "Helloworld" example that shows how
|
||||||
script in <filename>/opt/poky</filename> resulting from installation of the
|
to set up, compile, and run the project.
|
||||||
cross-toolchain tarball.
|
</para>
|
||||||
For example, the host option for an ARM-based target that uses the GNU EABI
|
|
||||||
is <filename>armv5te-poky-linux-gnueabi</filename>.
|
<section id='creating-and-running-a-project-based-on-gnu-autotools'>
|
||||||
Note that the name of the script is
|
<title>Creating and Running a Project Based on GNU Autotools</title>
|
||||||
<filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
|
|
||||||
Thus, the following command works:
|
<para>
|
||||||
<literallayout class='monospaced'>
|
Follow these steps to create a simple autotools-based project:
|
||||||
|
<orderedlist>
|
||||||
|
<listitem><para><emphasis>Create your directory:</emphasis>
|
||||||
|
Create a clean directory for your project and then make
|
||||||
|
that directory your working location:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ mkdir $HOME/helloworld
|
||||||
|
$ cd $HOME/helloworld
|
||||||
|
</literallayout></para></listitem>
|
||||||
|
<listitem><para><emphasis>Populate the directory:</emphasis>
|
||||||
|
Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
|
||||||
|
and <filename>configure.in</filename> files as follows:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>For <filename>hello.c</filename>, include
|
||||||
|
these lines:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
#include <stdio.h>
|
||||||
|
|
||||||
|
main()
|
||||||
|
{
|
||||||
|
printf("Hello World!\n");
|
||||||
|
}
|
||||||
|
</literallayout></para></listitem>
|
||||||
|
<listitem><para>For <filename>Makefile.am</filename>,
|
||||||
|
include these lines:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
bin_PROGRAMS = hello
|
||||||
|
hello_SOURCES = hello.c
|
||||||
|
</literallayout></para></listitem>
|
||||||
|
<listitem><para>For <filename>configure.in</filename>,
|
||||||
|
include these lines:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
AC_INIT(hello.c)
|
||||||
|
AM_INIT_AUTOMAKE(hello,0.1)
|
||||||
|
AC_PROG_CC
|
||||||
|
AC_CONFIG_HEADERS(config.h)
|
||||||
|
AC_PROG_INSTALL
|
||||||
|
AC_OUTPUT(Makefile)
|
||||||
|
</literallayout></para></listitem>
|
||||||
|
</itemizedlist></para></listitem>
|
||||||
|
<listitem><para><emphasis>Source the cross-toolchain
|
||||||
|
environment setup file:</emphasis>
|
||||||
|
Installation of the cross-toolchain creates a cross-toolchain
|
||||||
|
environment setup script in <filename>/opt/poky/<release></filename>.
|
||||||
|
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 for an environment setup using the
|
||||||
|
32-bit Intel x86 Architecture and using 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 <filename>aclocal.m4</filename>
|
||||||
|
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 ChangLog
|
||||||
|
</literallayout></para></listitem>
|
||||||
|
<listitem><para><emphasis>Generate the <filename>configure</filename>
|
||||||
|
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:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ ./configure ${CONFIGURE_FLAGS}
|
||||||
|
</literallayout></para></listitem>
|
||||||
|
<listitem><para><emphasis>Make and install the project:</emphasis>
|
||||||
|
These two commands generate and install the project into the
|
||||||
|
destination directory:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ make
|
||||||
|
$ make install DESTDIR=./tmp
|
||||||
|
</literallayout></para></listitem>
|
||||||
|
<listitem><para><emphasis>Verify the installation:</emphasis>
|
||||||
|
This command is a simple way to verify the installation
|
||||||
|
of your project.
|
||||||
|
Running the command prints the architecture on which
|
||||||
|
the binary file can run.
|
||||||
|
This architecture should be the same architecture that
|
||||||
|
the installed cross-toolchain supports.
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ file ./tmp/usr/local/bin/hello
|
||||||
|
</literallayout></para></listitem>
|
||||||
|
<listitem><para><emphasis>Execute your project:</emphasis>
|
||||||
|
To execute the project in the shell, simply enter the name.
|
||||||
|
You could also copy the binary to the actual target hardware
|
||||||
|
and run the project there as well:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ ./hello
|
||||||
|
</literallayout>
|
||||||
|
As expected, the project displays the "Hello World!" message.
|
||||||
|
</para></listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id='passing-host-options'>
|
||||||
|
<title>Passing Host Options</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For an Autotools-based project, you can use the cross-toolchain by just
|
||||||
|
passing the appropriate host option to <filename>configure.sh</filename>.
|
||||||
|
The host option you use is derived from the name of the environment setup
|
||||||
|
script in <filename>/opt/poky</filename> resulting from installation of the
|
||||||
|
cross-toolchain tarball.
|
||||||
|
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:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
$ configure --host=armv5te-poky-linux-gnueabi \
|
$ configure --host=armv5te-poky-linux-gnueabi \
|
||||||
--with-libtool-sysroot=<sysroot-dir>
|
--with-libtool-sysroot=<sysroot-dir>
|
||||||
</literallayout>
|
</literallayout>
|
||||||
</para>
|
</para>
|
||||||
<para>
|
|
||||||
This single command updates your project and rebuilds it using the appropriate
|
<para>
|
||||||
cross-toolchain tools.
|
This single command updates your project and rebuilds it using the appropriate
|
||||||
</para>
|
cross-toolchain tools.
|
||||||
<note>
|
<note>
|
||||||
If <filename>configure</filename> script results in problems recognizing the
|
If <filename>configure</filename> script results in problems recognizing the
|
||||||
<filename>--with-libtool-sysroot=<sysroot-dir></filename> option,
|
<filename>--with-libtool-sysroot=<sysroot-dir></filename> option,
|
||||||
regenerate the script to enable the support by doing the following and then
|
regenerate the script to enable the support by doing the following and then
|
||||||
re-running the script:
|
re-running the script:
|
||||||
<literallayout class='monospaced'>
|
<literallayout class='monospaced'>
|
||||||
$ libtoolize --automake
|
$ libtoolize --automake
|
||||||
$ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
|
$ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
|
||||||
[-I <dir_containing_your_project-specific_m4_macros>]
|
[-I <dir_containing_your_project-specific_m4_macros>]
|
||||||
$ autoconf
|
$ autoconf
|
||||||
$ autoheader
|
$ autoheader
|
||||||
$ automake -a
|
$ automake -a
|
||||||
</literallayout>
|
</literallayout>
|
||||||
</note>
|
</note>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section id='makefile-based-projects'>
|
<section id='makefile-based-projects'>
|
||||||
|
|
|
@ -18,7 +18,7 @@
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The following list describes installation methods that set up varying degrees of tool
|
The following list describes installation methods that set up varying degrees of tool
|
||||||
availabiltiy on your system.
|
availability on your system.
|
||||||
Regardless of the installation method you choose,
|
Regardless of the installation method you choose,
|
||||||
you must <filename>source</filename> the cross-toolchain
|
you must <filename>source</filename> the cross-toolchain
|
||||||
environment setup script before you use a toolchain.
|
environment setup script before you use a toolchain.
|
||||||
|
@ -258,9 +258,17 @@
|
||||||
<filename>bitbake meta-toolchain</filename>.</para>
|
<filename>bitbake meta-toolchain</filename>.</para>
|
||||||
<para>Use the appropriate <filename>bitbake</filename> command only after you have
|
<para>Use the appropriate <filename>bitbake</filename> command only after you have
|
||||||
sourced the <filename>&OE_INIT_PATH;</filename> script located in the Source
|
sourced the <filename>&OE_INIT_PATH;</filename> script located in the Source
|
||||||
Directory.
|
Directory and you have made sure your <filename>conf/local.conf</filename>
|
||||||
When the <filename>bitbake</filename> command completes, the toolchain installer will
|
variables are correct.
|
||||||
be in <filename>tmp/deploy/sdk</filename> in the Build Directory.
|
In particular, you need to be sure the
|
||||||
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
|
||||||
|
variable matches the architecture for which you are building and that the
|
||||||
|
<filename>SDKMACHINE</filename> variable is correctly set if you are building
|
||||||
|
a toolchain for an architecture that differs from your current
|
||||||
|
development host machine.</para>
|
||||||
|
<para>When the <filename>bitbake</filename> command completes, the
|
||||||
|
toolchain installer will be in <filename>tmp/deploy/sdk</filename> in the
|
||||||
|
Build Directory.
|
||||||
</para></note>
|
</para></note>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para>Once you have the installer, run it to install the toolchain.
|
<listitem><para>Once you have the installer, run it to install the toolchain.
|
||||||
|
|
Loading…
Reference in New Issue