summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-06-04 15:36:27 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-06-15 11:26:46 +0100
commit61a7ab26ee4c71508480709e2c863cb9ecc7e376 (patch)
treebfbede84bf3c51dbc65489dc109ccaf847d0ad21 /documentation
parent9da094bb75e6221968070c3db1be8e1ac1706ce1 (diff)
downloadpoky-61a7ab26ee4c71508480709e2c863cb9ecc7e376.tar.gz
sdk-manual: Updated the Autotools workflow example.
Did a re-write of this section with better explanations. I also pulled the bit about passing parameters to the configure script into the step that talks about that. (From yocto-docs rev: 79432ba0eb0cc2f6bdb3410fbf99f227fb666b2c) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/sdk-manual/sdk-working-projects.xml332
1 files changed, 167 insertions, 165 deletions
diff --git a/documentation/sdk-manual/sdk-working-projects.xml b/documentation/sdk-manual/sdk-working-projects.xml
index 2e232a5041..7aa43b3921 100644
--- a/documentation/sdk-manual/sdk-working-projects.xml
+++ b/documentation/sdk-manual/sdk-working-projects.xml
@@ -21,202 +21,204 @@
21 <para> 21 <para>
22 Once you have a suitable 22 Once you have a suitable
23 <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchain</ulink> 23 <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchain</ulink>
24 installed, it is very easy to develop a project outside of the 24 installed, it is very easy to develop a project using the
25 <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>GNU Autotools-based</ulink>
26 workflow, which is outside of the
25 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>. 27 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
26 This section presents a simple "Helloworld" example that shows how
27 to set up, compile, and run the project.
28 </para> 28 </para>
29 29
30 <section id='creating-and-running-a-project-based-on-gnu-autotools'> 30 <para>
31 <title>Creating and Running a Project Based on GNU Autotools</title> 31 The following figure presents a simple Autotools workflow.
32 <imagedata fileref="figures/sdk-autotools-flow.png" width="7in" height="8in" align="center" />
33 </para>
32 34
33 <para> 35 <para>
34 Follow these steps to create a simple 36 Follow these steps to create a simple Autotools-based
35 <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>GNU Autotools-based</ulink> 37 "Hello World" project:
36 project: 38 <note>
37 <orderedlist> 39 For more information on the GNU Autotools workflow,
38 <listitem><para> 40 see the same example on the
39 <emphasis>Create Your Directory:</emphasis> 41 <ulink url='https://developer.gnome.org/anjuta-build-tutorial/stable/create-autotools.html.en'>GNOME Developer</ulink>
40 Create a clean directory for your project and then make 42 site.
41 that directory your working location: 43 </note>
42 <literallayout class='monospaced'> 44 <orderedlist>
45 <listitem><para>
46 <emphasis>Create a Working Directory and Populate It:</emphasis>
47 Create a clean directory for your project and then make
48 that directory your working location.
49 <literallayout class='monospaced'>
43 $ mkdir $HOME/helloworld 50 $ mkdir $HOME/helloworld
44 $ cd $HOME/helloworld 51 $ cd $HOME/helloworld
45 </literallayout> 52 </literallayout>
46 </para></listitem> 53 After setting up the directory, populate it with three
47 <listitem><para> 54 simple files needed for the flow.
48 <emphasis>Populate the Directory:</emphasis> 55 You need a project source file, a file to help with
49 Create <filename>hello.c</filename>, 56 configuration, and a file to help create the Makefile:
50 <filename>Makefile.am</filename>, 57 <filename>hello.c</filename>,
51 and <filename>configure.ac</filename> files as follows: 58 <filename>configure.ac</filename>, and
52 <itemizedlist> 59 <filename>Makefile.am</filename>, respectively:
53 <listitem><para> 60 <itemizedlist>
54 For <filename>hello.c</filename>, include 61 <listitem><para>
55 these lines: 62 <emphasis><filename>hello.c</filename>:</emphasis>
56 <literallayout class='monospaced'> 63 <literallayout class='monospaced'>
57 #include &lt;stdio.h&gt; 64 #include &lt;stdio.h&gt;
58 65
59 main() 66 main()
60 { 67 {
61 printf("Hello World!\n"); 68 printf("Hello World!\n");
62 } 69 }
63 </literallayout> 70 </literallayout>
64 </para></listitem> 71 </para></listitem>
65 <listitem><para> 72 <listitem><para>
66 For <filename>Makefile.am</filename>, 73 <emphasis><filename>configure.ac</filename>:</emphasis>
67 include these lines: 74 <literallayout class='monospaced'>
68 <literallayout class='monospaced'>
69 bin_PROGRAMS = hello
70 hello_SOURCES = hello.c
71 </literallayout>
72 </para></listitem>
73 <listitem><para>
74 For <filename>configure.ac</filename>,
75 include these lines:
76 <literallayout class='monospaced'>
77 AC_INIT(hello,0.1) 75 AC_INIT(hello,0.1)
78 AM_INIT_AUTOMAKE([foreign]) 76 AM_INIT_AUTOMAKE([foreign])
79 AC_PROG_CC 77 AC_PROG_CC
80 AC_CONFIG_FILES(Makefile) 78 AC_CONFIG_FILES(Makefile)
81 AC_OUTPUT 79 AC_OUTPUT
82 </literallayout> 80 </literallayout>
83 </para></listitem> 81 </para></listitem>
84 </itemizedlist> 82 <listitem><para>
85 </para></listitem> 83 <emphasis><filename>Makefile.am</filename>:</emphasis>
86 <listitem><para> 84 <literallayout class='monospaced'>
87 <emphasis>Source the Cross-Toolchain 85 bin_PROGRAMS = hello
88 Environment Setup File:</emphasis> 86 hello_SOURCES = hello.c
89 As described earlier in the manual, installing the 87 </literallayout>
90 cross-toolchain creates a cross-toolchain 88 </para></listitem>
91 environment setup script in the directory that the SDK 89 </itemizedlist>
92 was installed. 90 </para></listitem>
93 Before you can use the tools to develop your project, 91 <listitem><para>
94 you must source this setup script. 92 <emphasis>Source the Cross-Toolchain
95 The script begins with the string "environment-setup" 93 Environment Setup File:</emphasis>
96 and contains the machine architecture, which is 94 As described earlier in the manual, installing the
97 followed by the string "poky-linux". 95 cross-toolchain creates a cross-toolchain
98 Here is an example that sources a script from the 96 environment setup script in the directory that the SDK
99 default SDK installation directory that uses the 97 was installed.
100 32-bit Intel x86 Architecture and the 98 Before you can use the tools to develop your project,
101 &DISTRO_NAME; Yocto Project release: 99 you must source this setup script.
102 <literallayout class='monospaced'> 100 The script begins with the string "environment-setup"
101 and contains the machine architecture, which is
102 followed by the string "poky-linux".
103 For this example, the command sources a script from the
104 default SDK installation directory that uses the
105 32-bit Intel x86 Architecture and the
106 &DISTRO_NAME; Yocto Project release:
107 <literallayout class='monospaced'>
103 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux 108 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
104 </literallayout> 109 </literallayout>
105 </para></listitem> 110 </para></listitem>
106 <listitem><para> 111 <listitem><para>
107 <emphasis>Generate the Local <filename>aclocal.m4</filename> 112 <emphasis>Generate the Local <filename>aclocal.m4</filename> Files:</emphasis>
108 Files and Create the <filename>configure</filename> Script:</emphasis> 113 The following command generates the local
109 The following GNU Autotools generate the local 114 <filename>aclocal.m4</filename> files, which are used
110 <filename>aclocal.m4</filename> files and create the 115 later with the <filename>autoconf</filename> command:
111 <filename>configure</filename> script: 116 <literallayout class='monospaced'>
112 <literallayout class='monospaced'>
113 $ aclocal 117 $ aclocal
118 </literallayout>
119 </para></listitem>
120 <listitem><para>
121 <emphasis>Create the <filename>configure</filename> Script:</emphasis>
122 The following command creates the
123 <filename>configure</filename> script:
124 <literallayout class='monospaced'>
114 $ autoconf 125 $ autoconf
115 </literallayout> 126 </literallayout>
116 </para></listitem> 127 </para></listitem>
117 <listitem><para> 128 <listitem><para>
118 <emphasis>Generate Files Needed by GNU Coding 129 <emphasis>Generate Files Needed by GNU Coding
119 Standards:</emphasis> 130 Standards:</emphasis>
120 GNU coding standards require certain files in order 131 GNU coding standards require certain files in order
121 for the project to be compliant. 132 for the project to be compliant.
122 This command creates those files: 133 This command creates those files:
123 <literallayout class='monospaced'> 134 <literallayout class='monospaced'>
124 $ touch NEWS README AUTHORS ChangeLog 135 $ touch NEWS README AUTHORS ChangeLog
125 </literallayout> 136 </literallayout>
126 </para></listitem> 137 </para></listitem>
127 <listitem><para> 138 <listitem><para>
128 <emphasis>Generate the Configure File:</emphasis> 139 <emphasis>Generate the <filename>Makefile.in</filename> File:</emphasis>
129 This command generates the 140 This command generates the
130 <filename>configure</filename>: 141 <filename>Makefile.in</filename>, which is used later
131 <literallayout class='monospaced'> 142 during cross-compilation:
143 <literallayout class='monospaced'>
132 $ automake -a 144 $ automake -a
133 </literallayout> 145 </literallayout>
134 </para></listitem> 146 </para></listitem>
135 <listitem><para> 147 <listitem><para>
136 <emphasis>Cross-Compile the Project:</emphasis> 148 <emphasis>Cross-Compile the Project:</emphasis>
137 This command compiles the project using the 149 This command compiles the project using the
138 cross-compiler. 150 cross-compiler.
139 The 151 The
140 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> 152 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
141 environment variable provides the minimal arguments for 153 environment variable provides the minimal arguments for
142 GNU configure: 154 GNU configure:
143 <literallayout class='monospaced'> 155 <literallayout class='monospaced'>
144 $ ./configure ${CONFIGURE_FLAGS} 156 $ ./configure ${CONFIGURE_FLAGS}
145 </literallayout> 157 </literallayout>
146 </para></listitem> 158 For an Autotools-based project, you can use the
147 <listitem><para> 159 cross-toolchain by just passing the appropriate host
148 <emphasis>Make and Install the Project:</emphasis> 160 option to <filename>configure.sh</filename>.
149 These two commands generate and install the project 161 The host option you use is derived from the name of the
150 into the destination directory: 162 environment setup script found in the directory in which you
151 <literallayout class='monospaced'> 163 installed the cross-toolchain.
152 $ make 164 For example, the host option for an ARM-based target that uses
153 $ make install DESTDIR=./tmp 165 the GNU EABI is
154 </literallayout> 166 <filename>armv5te-poky-linux-gnueabi</filename>.
155 </para></listitem> 167 You will notice that the name of the script is
156 <listitem><para> 168 <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
157 <emphasis>Verify the Installation:</emphasis> 169 Thus, the following command works to update your project
158 This command is a simple way to verify the installation 170 and rebuild it using the appropriate cross-toolchain tools:
159 of your project. 171 <literallayout class='monospaced'>
160 Running the command prints the architecture on which
161 the binary file can run.
162 This architecture should be the same architecture that
163 the installed cross-toolchain supports.
164 <literallayout class='monospaced'>
165 $ file ./tmp/usr/local/bin/hello
166 </literallayout>
167 </para></listitem>
168 <listitem><para>
169 <emphasis>Execute Your Project:</emphasis>
170 To execute the project in the shell, simply enter
171 the name.
172 You could also copy the binary to the actual target
173 hardware and run the project there as well:
174 <literallayout class='monospaced'>
175 $ ./hello
176 </literallayout>
177 As expected, the project displays the "Hello World!"
178 message.
179 </para></listitem>
180 </orderedlist>
181 </para>
182 </section>
183
184 <section id='passing-host-options'>
185 <title>Passing Host Options</title>
186
187 <para>
188 For an Autotools-based project, you can use the cross-toolchain
189 by just passing the appropriate host option to
190 <filename>configure.sh</filename>.
191 The host option you use is derived from the name of the
192 environment setup script found in the directory in which you
193 installed the cross-toolchain.
194 For example, the host option for an ARM-based target that uses
195 the GNU EABI is <filename>armv5te-poky-linux-gnueabi</filename>.
196 You will notice that the name of the script is
197 <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
198 Thus, the following command works to update your project and
199 rebuild it using the appropriate cross-toolchain tools:
200 <literallayout class='monospaced'>
201 $ ./configure --host=armv5te-poky-linux-gnueabi \ 172 $ ./configure --host=armv5te-poky-linux-gnueabi \
202 --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable> 173 --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
203 </literallayout> 174 </literallayout>
204 <note> 175 <note>
205 If the <filename>configure</filename> script results in 176 If the <filename>configure</filename> script results in
206 problems recognizing the 177 problems recognizing the
207 <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> 178 <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable>
208 option, regenerate the script to enable the support by 179 option, regenerate the script to enable the support by
209 doing the following and then run the script again: 180 doing the following and then run the script again:
210 <literallayout class='monospaced'> 181 <literallayout class='monospaced'>
211 $ libtoolize --automake 182 $ libtoolize --automake
212 $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>] 183 $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
213 $ autoconf 184 $ autoconf
214 $ autoheader 185 $ autoheader
215 $ automake -a 186 $ automake -a
187 </literallayout>
188 </note>
189 </para></listitem>
190 <listitem><para>
191 <emphasis>Make and Install the Project:</emphasis>
192 These two commands generate and install the project
193 into the destination directory:
194 <literallayout class='monospaced'>
195 $ make
196 $ make install DESTDIR=./tmp
216 </literallayout> 197 </literallayout>
217 </note> 198 This next command is a simple way to verify the
218 </para> 199 installation of your project.
219 </section> 200 Running the command prints the architecture on which
201 the binary file can run.
202 This architecture should be the same architecture that
203 the installed cross-toolchain supports.
204 <literallayout class='monospaced'>
205 $ file ./tmp/usr/local/bin/hello
206 </literallayout>
207 </para></listitem>
208 <listitem><para>
209 <emphasis>Execute Your Project:</emphasis>
210 To execute the project in the shell, simply enter
211 the name.
212 You could also copy the binary to the actual target
213 hardware and run the project there as well:
214 <literallayout class='monospaced'>
215 $ ./hello
216 </literallayout>
217 As expected, the project displays the "Hello World!"
218 message.
219 </para></listitem>
220 </orderedlist>
221 </para>
220 </section> 222 </section>
221 223
222 <section id='makefile-based-projects'> 224 <section id='makefile-based-projects'>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-02 21:09:31 +0000