summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-11-14 11:36:19 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-12-03 13:52:55 +0000
commit55530d42e70ec1ceb8e68cbd4165fd96c358a29e (patch)
tree5499a4dcbe1669b2388d639b9153bfee2511a7cb /documentation
parente197fca49c2ccb95ac6ec0868d4f0af877592e89 (diff)
downloadpoky-55530d42e70ec1ceb8e68cbd4165fd96c358a29e.tar.gz
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>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/adt-manual/adt-command.xml179
-rw-r--r--documentation/adt-manual/adt-prepare.xml16
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 @@
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 &lt;stdio.h&gt;
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/&lt;release&gt;</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=&lt;sysroot-dir&gt; 171 --with-libtool-sysroot=&lt;sysroot-dir&gt;
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=&lt;sysroot-dir&gt;</filename> option, 180 <filename>--with-libtool-sysroot=&lt;sysroot-dir&gt;</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 &lt;dir_containing_your_project-specific_m4_macros&gt;] 186 [-I &lt;dir_containing_your_project-specific_m4_macros&gt;]
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.
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 06:18:22 +0000