summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-07-08 21:42:32 +0300
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-08-13 13:18:38 +0100
commit95cdad1c2edd8f4698a245ad88e2bccb0cf93e6d (patch)
tree8512729b5bbaa456237435d0ede335090a76a2d2 /documentation/ref-manual
parent482943bd2cd8b5a39dd8d8aa3ad1111fa3c72038 (diff)
downloadpoky-95cdad1c2edd8f4698a245ad88e2bccb0cf93e6d.tar.gz
ref-manual: Start of new section on deeper look into dev env.
Start of the new section on the closer look into the development environment. (From yocto-docs rev: e1f1cee951433144d1adedcb4f0bbc8d8296c444) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/technical-details.xml210
1 files changed, 210 insertions, 0 deletions
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 17f96b52ff..583d204566 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -153,6 +153,216 @@
153 </section> 153 </section>
154</section> 154</section>
155 155
156<section id="a-closer-look-at-the-yocto-project-development-environment">
157 <title>A Closer Look at the Yocto Project Development Environment</title>
158
159 <para>
160 This section is a work-in-progress for an expanded discussion of the
161 Yocto Project Development Environment.
162 The section is rooted in the figure found in the
163 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-intro'>Introducing the Yocto Project Development Environment</ulink>"
164 section of the Yocto Project Quick Start.
165 This expanded discussion presents a deeper level of detail regarding
166 sources of input, generated output, and controlling
167 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>.
168 </para>
169
170 <para>
171 I will either replicate the exact figure from the YP Quick Start here
172 or I will create a more simplified version that can be used as the
173 top-level diagram from which to base subsequent sections and expanded
174 illustrations.
175 </para>
176
177 <para>
178 [NEED REPEATED FIGURE HERE OR A NEW FIGURE]
179 </para>
180
181 <para>
182 This paragraph will introduce the main blocks of the preceding figure
183 to overview and organize the remainder of the section:
184 <itemizedlist>
185 <listitem><para><emphasis>User Configuration:</emphasis>
186 Methods by with the user can directly control the build
187 process.</para></listitem>
188 <listitem><para><emphasis>Metadata Layers:</emphasis>
189 Various layers that provide software, machine, and
190 distro Metadata.</para></listitem>
191 <listitem><para><emphasis>Soure Files:</emphasis>
192 Upstream releases, local projects, and SCMs.</para></listitem>
193 <listitem><para><emphasis>Build System:</emphasis>
194 Processes inside the BitBake "box".
195 This block expands on how BitBake fetches source, applies
196 patches, completes compilation, analyzes output for package
197 generation, creates and tests packages, generates images, and
198 generates cross-development tools.</para></listitem>
199 <listitem><para><emphasis>Package Feeds</emphasis>
200 Package feeds into the BitBake process.</para></listitem>
201 <listitem><para><emphasis>Images</emphasis>
202 Images produced by the development process.
203 Where do they go?
204 Can you mess with them (i.e. freely delete them or move them?).
205 </para></listitem>
206 <listitem><para><emphasis>Application Development SDK</emphasis>
207 Cross-development tools that are produced along with an image
208 or separately with BitBake.</para></listitem>
209 </itemizedlist>
210 </para>
211
212 <section id="user-configuration">
213 <title>User Configuration</title>
214
215 <para>
216 User configuration affects how you define the build.
217 The following figure shows an expanded representation of the
218 user configuration in the Yocto Project development environment:
219 </para>
220
221 <mediaobject>
222 <imageobject>
223 <imagedata fileref="figures/user-configuration.png"
224 format="PNG" align='center' scalefit='1' width="100%"/>
225 </imageobject>
226 </mediaobject>
227
228 <para>
229 BitBake needs some basic configuration files in order to complete
230 a build.
231 These files are <filename>*.conf</filename> files and the
232 minimally necessary ones reside as example files in the
233 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
234 For simplicity, this section refers to the Source Directory as
235 the "Poky Directory."
236 <note>
237 Poky is primarily an aggregation of existing repositories and
238 is not actual canonical upstream source for anything.
239 </note>
240 When you clone the <filename>poky</filename> Git repository or you
241 download and unpack a Yocto Project release, you can set up the
242 Source Directory to be named anything you want.
243 Here, though, we will assume that you have a cloned repository that
244 has the default name <filename>poky</filename>.
245 </para>
246
247 <para>
248 The <filename>meta-yocto</filename> layer inside Poky contains
249 a <filename>conf</filename> directory that has example
250 configuration files.
251 These example files are used as a basis for creating actual
252 configuration files when you source the build environment
253 script <filename>oe-init-build-env</filename>.
254 <note>
255 The <filename>oe-init-build-env</filename> script also exists
256 in the <filename>meta</filename> directory of the OE-Core
257 root directory.
258 Both scripts look for sample configuration files through
259 a <filename>$TEMPLATECONF</filename> variable.
260 When using the Yocto Project Development Environment,
261 that location resolves to the samples found in the
262 <filename>poky/meta-yocto/conf</filename> directory.
263 </note>
264 </para>
265
266 <para>
267 When you source the build environment script, it creates a
268 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
269 that BitBake uses as the area in which it does all its work
270 during builds.
271 The Build Directory has a <filename>conf</filename> directory that
272 contains default versions of your <filename>local.conf</filename>
273 and <filename>bblayers.conf</filename> configuration files.
274 These default configuration files are created by
275 <filename>oe-init-build-env</filename> only if versions of these
276 files do not already exist in the Build Directory you specify
277 when you run the script.
278 </para>
279
280 <para>
281 The <filename>local.conf</filename> file provides many
282 basic variables that define your build.
283 Here is a list of a few.
284 To see the default configurations in a <filename>local.conf</filename>
285 file created by the build environment script, see the
286 <filename>local.conf.sample</filename> in the
287 <filename>meta-yocto</filename> layer:
288 <itemizedlist>
289 <listitem><para><emphasis>Parallelism Options:</emphasis>
290 Controlled by the
291 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
292 and
293 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
294 variables.</para></listitem>
295 <listitem><para><emphasis>Target Machine Selection:</emphasis>
296 Controlled by the
297 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
298 variable.</para></listitem>
299 <listitem><para><emphasis>Download Directory:</emphasis>
300 Controlled by the
301 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
302 variable.</para></listitem>
303 <listitem><para><emphasis>Shared State Directory:</emphasis>
304 Controlled by the
305 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
306 variable.</para></listitem>
307 <listitem><para><emphasis>Build Output:</emphasis>
308 Controlled by the
309 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
310 variable.</para></listitem>
311 </itemizedlist>
312 </para>
313
314 <para>
315 The <filename>bblayers.conf</filename> file tells BitBake what
316 layers you want it to consider during the build.
317 The list of layers includes default layers needed by the build
318 system.
319 You have to manually add any custom layers that you have created.
320 You can find more information on working with the
321 <filename>bblayers.conf</filename> file in the
322 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
323 section in the Yocto Project Development Manual.
324 </para>
325
326 <para>
327 The files <filename>site.conf</filename> and
328 <filename>auto.conf</filename> are not created by the environment
329 initialization script.
330 If you want these configuration files, you must create them
331 yourself.
332 Here a bit about what these files do:
333 <itemizedlist>
334 <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
335 I don't really know what this does.
336 All I know is that if you want it, you need to hand-create
337 it.
338 I need some information on it.</para></listitem>
339 <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
340 This file is not hand-created.
341 Rather, the file is usually created and written to by
342 an autobuilder.
343 The settings put into the file are typically the same as
344 you would find in the <filename>local.conf</filename>
345 or <filename>site.conf</filename> files.
346 </para></listitem>
347 </itemizedlist>
348 </para>
349
350 <para>
351 All configuration files can undergo edits to further define
352 the build.
353 This process is represented by the "User Configuration Edits"
354 box in the figure.
355 </para>
356
357 <para>
358 When you launch your build with the
359 <filename>bitbake &lt;target&gt;</filename> command, BitBake
360 draws on the user configurations you have provided in your
361 Build Directory.
362 </para>
363 </section>
364</section>
365
156<section id="cross-development-toolchain-generation"> 366<section id="cross-development-toolchain-generation">
157 <title>Cross-Development Toolchain Generation</title> 367 <title>Cross-Development Toolchain Generation</title>
158 368