2 files changed, 166 insertions, 29 deletions
diff --git a/documentation/adt-manual/adt-command.xml b/documentation/adt-manual/adt-command.xml
index 4000c924c3..d010aad591 100644
--- a/documentation/adt-manual/adt-command.xml
+++ b/documentation/adt-manual/adt-command.xml
@@ -29,39 +29,168 @@
 <title>Autotools-Based Projects</title>
    <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 &lt;stdio.h&gt;
+     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/&lt;release&gt;</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 \
        --with-libtool-sysroot=&lt;sysroot-dir&gt;
-        </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=&lt;sysroot-dir&gt;</filename> option, 
+                <filename>--with-libtool-sysroot=&lt;sysroot-dir&gt;</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
     $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
        [-I &lt;dir_containing_your_project-specific_m4_macros&gt;]
     $ autoconf
     $ autoheader
     $ automake -a
-        </literallayout>
+                </literallayout>
-    </note>       
+            </note>    
+        </para>
+    </section>   
 </section>
 <section id='makefile-based-projects'>
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
index 3fd231c6a0..040618482f 100644
--- a/documentation/adt-manual/adt-prepare.xml
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -18,7 +18,7 @@
    <para>
        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,
        you must <filename>source</filename> the cross-toolchain
        environment setup script before you use a toolchain.
@@ -258,9 +258,17 @@
                        <filename>bitbake meta-toolchain</filename>.</para>
                        <para>Use the appropriate <filename>bitbake</filename> command only after you have 
                        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></listitem>
                <listitem><para>Once you have the installer, run it to install the toolchain.

diff --git a/documentation/adt-manual/adt-command.xml b/documentation/adt-manual/adt-command.xml index 4000c924c3..d010aad591 100644 --- a/documentation/adt-manual/adt-command.xml +++ b/documentation/adt-manual/adt-command.xml
@@ -29,39 +29,168 @@
29	<title>Autotools-Based Projects</title>	29	<title>Autotools-Based Projects</title>
30		30
31	<para>	31	<para>
32	For an Autotools-based project, you can use the cross-toolchain by just	32	Once you have a suitable cross-toolchain installed, it is very easy to
33	passing the appropriate host option to <filename>configure.sh</filename>.	33	develop a project outside of the OpenEmbedded build system.
34	The host option you use is derived from the name of the environment setup	34	This section presents a simple "Helloworld" example that shows how
35	script in <filename>/opt/poky</filename> resulting from installation of the	35	to set up, compile, and run the project.
36	cross-toolchain tarball.	36	</para>
37	For example, the host option for an ARM-based target that uses the GNU EABI	37
38	is <filename>armv5te-poky-linux-gnueabi</filename>.	38	<section id='creating-and-running-a-project-based-on-gnu-autotools'>
39	Note that the name of the script is	39	<title>Creating and Running a Project Based on GNU Autotools</title>
40	<filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.	40
41	Thus, the following command works:	41	<para>
42	<literallayout class='monospaced'>	42	Follow these steps to create a simple autotools-based project:
		43	<orderedlist>
		44	<listitem><para><emphasis>Create your directory:</emphasis>
		45	Create a clean directory for your project and then make
		46	that directory your working location:
		47	<literallayout class='monospaced'>
		48	$ mkdir $HOME/helloworld
		49	$ cd $HOME/helloworld
		50	</literallayout></para></listitem>
		51	<listitem><para><emphasis>Populate the directory:</emphasis>
		52	Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
		53	and <filename>configure.in</filename> files as follows:
		54	<itemizedlist>
		55	<listitem><para>For <filename>hello.c</filename>, include
		56	these lines:
		57	<literallayout class='monospaced'>
		58	#include <stdio.h>
		59
		60	main()
		61	{
		62	printf("Hello World!\n");
		63	}
		64	</literallayout></para></listitem>
		65	<listitem><para>For <filename>Makefile.am</filename>,
		66	include these lines:
		67	<literallayout class='monospaced'>
		68	bin_PROGRAMS = hello
		69	hello_SOURCES = hello.c
		70	</literallayout></para></listitem>
		71	<listitem><para>For <filename>configure.in</filename>,
		72	include these lines:
		73	<literallayout class='monospaced'>
		74	AC_INIT(hello.c)
		75	AM_INIT_AUTOMAKE(hello,0.1)
		76	AC_PROG_CC
		77	AC_CONFIG_HEADERS(config.h)
		78	AC_PROG_INSTALL
		79	AC_OUTPUT(Makefile)
		80	</literallayout></para></listitem>
		81	</itemizedlist></para></listitem>
		82	<listitem><para><emphasis>Source the cross-toolchain
		83	environment setup file:</emphasis>
		84	Installation of the cross-toolchain creates a cross-toolchain
		85	environment setup script in <filename>/opt/poky/<release></filename>.
		86	Before you can use the tools to develop your project, you must
		87	source this setup script.
		88	The script begins with the string "environment-setup" and contains
		89	the machine architecture, which is followed by the string
		90	"poky-linux".
		91	Here is an example for an environment setup using the
		92	32-bit Intel x86 Architecture and using the
		93	&DISTRO_NAME; Yocto Project release:
		94	<literallayout class='monospaced'>
		95	$ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
		96	</literallayout></para></listitem>
		97	<listitem><para><emphasis>Generate the local <filename>aclocal.m4</filename>
		98	files and create the configure script:</emphasis>
		99	The following GNU Autotools generate the local
		100	<filename>aclocal.m4</filename> files and create the
		101	configure script:
		102	<literallayout class='monospaced'>
		103	$ aclocal
		104	$ autoconf
		105	</literallayout></para></listitem>
		106	<listitem><para><emphasis>Generate files needed by GNU
		107	coding standards:</emphasis>
		108	GNU coding standards require certain files in order for the
		109	project to be compliant.
		110	This command creates those files:
		111	<literallayout class='monospaced'>
		112	$ touch NEWS README AUTHORS ChangLog
		113	</literallayout></para></listitem>
		114	<listitem><para><emphasis>Generate the <filename>configure</filename>
		115	file:</emphasis>
		116	This command generates the <filename>configure</filename>:
		117	<literallayout class='monospaced'>
		118	$ automake -a
		119	</literallayout></para></listitem>
		120	<listitem><para><emphasis>Cross-compile the project:</emphasis>
		121	This command compiles the project using the cross-compiler:
		122	<literallayout class='monospaced'>
		123	$ ./configure ${CONFIGURE_FLAGS}
		124	</literallayout></para></listitem>
		125	<listitem><para><emphasis>Make and install the project:</emphasis>
		126	These two commands generate and install the project into the
		127	destination directory:
		128	<literallayout class='monospaced'>
		129	$ make
		130	$ make install DESTDIR=./tmp
		131	</literallayout></para></listitem>
		132	<listitem><para><emphasis>Verify the installation:</emphasis>
		133	This command is a simple way to verify the installation
		134	of your project.
		135	Running the command prints the architecture on which
		136	the binary file can run.
		137	This architecture should be the same architecture that
		138	the installed cross-toolchain supports.
		139	<literallayout class='monospaced'>
		140	$ file ./tmp/usr/local/bin/hello
		141	</literallayout></para></listitem>
		142	<listitem><para><emphasis>Execute your project:</emphasis>
		143	To execute the project in the shell, simply enter the name.
		144	You could also copy the binary to the actual target hardware
		145	and run the project there as well:
		146	<literallayout class='monospaced'>
		147	$ ./hello
		148	</literallayout>
		149	As expected, the project displays the "Hello World!" message.
		150	</para></listitem>
		151	</orderedlist>
		152	</para>
		153	</section>
		154
		155	<section id='passing-host-options'>
		156	<title>Passing Host Options</title>
		157
		158	<para>
		159	For an Autotools-based project, you can use the cross-toolchain by just
		160	passing the appropriate host option to <filename>configure.sh</filename>.
		161	The host option you use is derived from the name of the environment setup
		162	script in <filename>/opt/poky</filename> resulting from installation of the
		163	cross-toolchain tarball.
		164	For example, the host option for an ARM-based target that uses the GNU EABI
		165	is <filename>armv5te-poky-linux-gnueabi</filename>.
		166	You will notice that the name of the script is
		167	<filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
		168	Thus, the following command works:
		169	<literallayout class='monospaced'>
43	$ configure --host=armv5te-poky-linux-gnueabi \	170	$ configure --host=armv5te-poky-linux-gnueabi \
44	--with-libtool-sysroot=<sysroot-dir>	171	--with-libtool-sysroot=<sysroot-dir>
45	</literallayout>	172	</literallayout>
46	</para>	173	</para>
47	<para>	174
48	This single command updates your project and rebuilds it using the appropriate	175	<para>
49	cross-toolchain tools.	176	This single command updates your project and rebuilds it using the appropriate
50	</para>	177	cross-toolchain tools.
51	<note>	178	<note>
52	If <filename>configure</filename> script results in problems recognizing the	179	If <filename>configure</filename> script results in problems recognizing the
53	<filename>--with-libtool-sysroot=<sysroot-dir></filename> option,	180	<filename>--with-libtool-sysroot=<sysroot-dir></filename> option,
54	regenerate the script to enable the support by doing the following and then	181	regenerate the script to enable the support by doing the following and then
55	re-running the script:	182	re-running the script:
56	<literallayout class='monospaced'>	183	<literallayout class='monospaced'>
57	$ libtoolize --automake	184	$ libtoolize --automake
58	$ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \	185	$ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
59	[-I <dir_containing_your_project-specific_m4_macros>]	186	[-I <dir_containing_your_project-specific_m4_macros>]
60	$ autoconf	187	$ autoconf
61	$ autoheader	188	$ autoheader
62	$ automake -a	189	$ automake -a
63	</literallayout>	190	</literallayout>
64	</note>	191	</note>
		192	</para>
		193	</section>
65	</section>	194	</section>
66		195
67	<section id='makefile-based-projects'>	196	<section id='makefile-based-projects'>


diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml index 3fd231c6a0..040618482f 100644 --- a/documentation/adt-manual/adt-prepare.xml +++ b/documentation/adt-manual/adt-prepare.xml
@@ -18,7 +18,7 @@
18		18
19	<para>	19	<para>
20	The following list describes installation methods that set up varying degrees of tool	20	The following list describes installation methods that set up varying degrees of tool
21	availabiltiy on your system.	21	availability on your system.
22	Regardless of the installation method you choose,	22	Regardless of the installation method you choose,
23	you must <filename>source</filename> the cross-toolchain	23	you must <filename>source</filename> the cross-toolchain
24	environment setup script before you use a toolchain.	24	environment setup script before you use a toolchain.
@@ -258,9 +258,17 @@
258	<filename>bitbake meta-toolchain</filename>.</para>	258	<filename>bitbake meta-toolchain</filename>.</para>
259	<para>Use the appropriate <filename>bitbake</filename> command only after you have	259	<para>Use the appropriate <filename>bitbake</filename> command only after you have
260	sourced the <filename>&OE_INIT_PATH;</filename> script located in the Source	260	sourced the <filename>&OE_INIT_PATH;</filename> script located in the Source
261	Directory.	261	Directory and you have made sure your <filename>conf/local.conf</filename>
262	When the <filename>bitbake</filename> command completes, the toolchain installer will	262	variables are correct.
263	be in <filename>tmp/deploy/sdk</filename> in the Build Directory.	263	In particular, you need to be sure the
		264	<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
		265	variable matches the architecture for which you are building and that the
		266	<filename>SDKMACHINE</filename> variable is correctly set if you are building
		267	a toolchain for an architecture that differs from your current
		268	development host machine.</para>
		269	<para>When the <filename>bitbake</filename> command completes, the
		270	toolchain installer will be in <filename>tmp/deploy/sdk</filename> in the
		271	Build Directory.
264	</para></note>	272	</para></note>
265	</para></listitem>	273	</para></listitem>
266	<listitem><para>Once you have the installer, run it to install the toolchain.	274	<listitem><para>Once you have the installer, run it to install the toolchain.