1 files changed, 154 insertions, 25 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-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'>