summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml
diff options
context:
space:
mode:
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml506
1 files changed, 506 insertions, 0 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml
new file mode 100644
index 0000000000..4ce7ed9f8c
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml
@@ -0,0 +1,506 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='hello-world-example'>
5 <title>Hello World Example</title>
6
7 <section id='bitbake-hello-world'>
8 <title>BitBake Hello World</title>
9
10 <para>
11 The simplest example commonly used to demonstrate any new
12 programming language or tool is the
13 "<ulink url="http://en.wikipedia.org/wiki/Hello_world_program">Hello World</ulink>"
14 example.
15 This appendix demonstrates, in tutorial form, Hello
16 World within the context of BitBake.
17 The tutorial describes how to create a new project
18 and the applicable metadata files necessary to allow
19 BitBake to build it.
20 </para>
21 </section>
22
23 <section id='example-obtaining-bitbake'>
24 <title>Obtaining BitBake</title>
25
26 <para>
27 See the
28 "<link linkend='obtaining-bitbake'>Obtaining BitBake</link>"
29 section for information on how to obtain BitBake.
30 Once you have the source code on your machine, the BitBake directory
31 appears as follows:
32 <literallayout class='monospaced'>
33 $ ls -al
34 total 100
35 drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 .
36 drwxrwxr-x. 3 wmat wmat 4096 Feb 4 10:45 ..
37 -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS
38 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin
39 drwxrwxr-x. 4 wmat wmat 4096 Jan 31 13:44 build
40 -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog
41 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes
42 drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 conf
43 drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 contrib
44 -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
45 drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc
46 -rw-rw-r--. 1 wmat wmat 69 Nov 26 04:55 .gitignore
47 -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER
48 drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib
49 -rw-rw-r--. 1 wmat wmat 195 Nov 26 04:55 MANIFEST.in
50 -rwxrwxr-x. 1 wmat wmat 3195 Jan 31 11:57 setup.py
51 -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 TODO
52 </literallayout>
53 </para>
54
55 <para>
56 At this point, you should have BitBake cloned to
57 a directory that matches the previous listing except for
58 dates and user names.
59 </para>
60 </section>
61
62 <section id='setting-up-the-bitbake-environment'>
63 <title>Setting Up the BitBake Environment</title>
64
65 <para>
66 First, you need to be sure that you can run BitBake.
67 Set your working directory to where your local BitBake
68 files are and run the following command:
69 <literallayout class='monospaced'>
70 $ ./bin/bitbake --version
71 BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
72 </literallayout>
73 The console output tells you what version you are running.
74 </para>
75
76 <para>
77 The recommended method to run BitBake is from a directory of your
78 choice.
79 To be able to run BitBake from any directory, you need to add the
80 executable binary to your binary to your shell's environment
81 <filename>PATH</filename> variable.
82 First, look at your current <filename>PATH</filename> variable
83 by entering the following:
84 <literallayout class='monospaced'>
85 $ echo $PATH
86 </literallayout>
87 Next, add the directory location for the BitBake binary to the
88 <filename>PATH</filename>.
89 Here is an example that adds the
90 <filename>/home/scott-lenovo/bitbake/bin</filename> directory
91 to the front of the <filename>PATH</filename> variable:
92 <literallayout class='monospaced'>
93 $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
94 </literallayout>
95 You should now be able to enter the <filename>bitbake</filename>
96 command from the command line while working from any directory.
97 </para>
98 </section>
99
100 <section id='the-hello-world-example'>
101 <title>The Hello World Example</title>
102
103 <para>
104 The overall goal of this exercise is to build a
105 complete "Hello World" example utilizing task and layer
106 concepts.
107 Because this is how modern projects such as OpenEmbedded and
108 the Yocto Project utilize BitBake, the example
109 provides an excellent starting point for understanding
110 BitBake.
111 </para>
112
113 <para>
114 To help you understand how to use BitBake to build targets,
115 the example starts with nothing but the <filename>bitbake</filename>
116 command, which causes BitBake to fail and report problems.
117 The example progresses by adding pieces to the build to
118 eventually conclude with a working, minimal "Hello World"
119 example.
120 </para>
121
122 <para>
123 While every attempt is made to explain what is happening during
124 the example, the descriptions cannot cover everything.
125 You can find further information throughout this manual.
126 Also, you can actively participate in the
127 <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'></ulink>
128 discussion mailing list about the BitBake build tool.
129 </para>
130
131 <note>
132 This example was inspired by and drew heavily from these sources:
133 <itemizedlist>
134 <listitem><para>
135 <ulink url="http://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html">Mailing List post - The BitBake equivalent of "Hello, World!"</ulink>
136 </para></listitem>
137 <listitem><para>
138 <ulink url="http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/">Hambedded Linux blog post - From Bitbake Hello World to an Image</ulink>
139 </para></listitem>
140 </itemizedlist>
141 </note>
142
143 <para>
144 As stated earlier, the goal of this example
145 is to eventually compile "Hello World".
146 However, it is unknown what BitBake needs and what you have
147 to provide in order to achieve that goal.
148 Recall that BitBake utilizes three types of metadata files:
149 <link linkend='configuration-files'>Configuration Files</link>,
150 <link linkend='classes'>Classes</link>, and
151 <link linkend='recipes'>Recipes</link>.
152 But where do they go?
153 How does BitBake find them?
154 BitBake's error messaging helps you answer these types of questions
155 and helps you better understand exactly what is going on.
156 </para>
157
158 <para>
159 Following is the complete "Hello World" example.
160 </para>
161
162 <orderedlist>
163 <listitem><para><emphasis>Create a Project Directory:</emphasis>
164 First, set up a directory for the "Hello World" project.
165 Here is how you can do so in your home directory:
166 <literallayout class='monospaced'>
167 $ mkdir ~/hello
168 $ cd ~/hello
169 </literallayout>
170 This is the directory that BitBake will use to do all of
171 its work.
172 You can use this directory to keep all the metafiles needed
173 by BitBake.
174 Having a project directory is a good way to isolate your
175 project.
176 </para></listitem>
177 <listitem><para><emphasis>Run Bitbake:</emphasis>
178 At this point, you have nothing but a project directory.
179 Run the <filename>bitbake</filename> command and see what
180 it does:
181 <literallayout class='monospaced'>
182 $ bitbake
183 The BBPATH variable is not set and bitbake did not
184 find a conf/bblayers.conf file in the expected location.
185 Maybe you accidentally invoked bitbake from the wrong directory?
186 DEBUG: Removed the following variables from the environment:
187 GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
188 GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
189 XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
190 MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
191 GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
192 XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
193 _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
194 UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS
195 </literallayout>
196 The majority of this output is specific to environment variables
197 that are not directly relevant to BitBake.
198 However, the very first message regarding the
199 <filename>BBPATH</filename> variable and the
200 <filename>conf/bblayers.conf</filename> file
201 is relevant.</para>
202 <para>
203 When you run BitBake, it begins looking for metadata files.
204 The
205 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
206 variable is what tells BitBake where to look for those files.
207 <filename>BBPATH</filename> is not set and you need to set it.
208 Without <filename>BBPATH</filename>, Bitbake cannot
209 find any configuration files (<filename>.conf</filename>)
210 or recipe files (<filename>.bb</filename>) at all.
211 BitBake also cannot find the <filename>bitbake.conf</filename>
212 file.
213 </para></listitem>
214 <listitem><para><emphasis>Setting <filename>BBPATH</filename>:</emphasis>
215 For this example, you can set <filename>BBPATH</filename>
216 in the same manner that you set <filename>PATH</filename>
217 earlier in the appendix.
218 You should realize, though, that it is much more flexible to set the
219 <filename>BBPATH</filename> variable up in a configuration
220 file for each project.</para>
221 <para>From your shell, enter the following commands to set and
222 export the <filename>BBPATH</filename> variable:
223 <literallayout class='monospaced'>
224 $ BBPATH="&lt;projectdirectory&gt;"
225 $ export BBPATH
226 </literallayout>
227 Use your actual project directory in the command.
228 BitBake uses that directory to find the metadata it needs for
229 your project.
230 <note>
231 When specifying your project directory, do not use the
232 tilde ("~") character as BitBake does not expand that character
233 as the shell would.
234 </note>
235 </para></listitem>
236 <listitem><para><emphasis>Run Bitbake:</emphasis>
237 Now that you have <filename>BBPATH</filename> defined, run
238 the <filename>bitbake</filename> command again:
239 <literallayout class='monospaced'>
240 $ bitbake
241 ERROR: Traceback (most recent call last):
242 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
243 return func(fn, *args)
244 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file
245 return bb.parse.handle(fn, data, include)
246 File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle
247 return h['handle'](fn, data, include)
248 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle
249 abs_fn = resolve_file(fn, data)
250 File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file
251 raise IOError("file %s not found in %s" % (fn, bbpath))
252 IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello
253
254 ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello
255 </literallayout>
256 This sample output shows that BitBake could not find the
257 <filename>conf/bitbake.conf</filename> file in the project
258 directory.
259 This file is the first thing BitBake must find in order
260 to build a target.
261 And, since the project directory for this example is
262 empty, you need to provide a <filename>conf/bitbake.conf</filename>
263 file.
264 </para></listitem>
265 <listitem><para><emphasis>Creating <filename>conf/bitbake.conf</filename>:</emphasis>
266 The <filename>conf/bitbake.conf</filename> includes a number of
267 configuration variables BitBake uses for metadata and recipe
268 files.
269 For this example, you need to create the file in your project directory
270 and define some key BitBake variables.
271 For more information on the <filename>bitbake.conf</filename>,
272 see
273 <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#an-overview-of-bitbakeconf'></ulink>
274 </para>
275 <para>Use the following commands to create the <filename>conf</filename>
276 directory in the project directory:
277 <literallayout class='monospaced'>
278 $ mkdir conf
279 </literallayout>
280 From within the <filename>conf</filename> directory, use
281 some editor to create the <filename>bitbake.conf</filename>
282 so that it contains the following:
283 <literallayout class='monospaced'>
284 TMPDIR = "${<link linkend='var-TOPDIR'>TOPDIR</link>}/tmp"
285 <link linkend='var-CACHE'>CACHE</link> = "${TMPDIR}/cache"
286 <link linkend='var-STAMP'>STAMP</link> = "${TMPDIR}/stamps"
287 <link linkend='var-T'>T</link> = "${TMPDIR}/work"
288 <link linkend='var-B'>B</link> = "${TMPDIR}"
289 </literallayout>
290 The <filename>TMPDIR</filename> variable establishes a directory
291 that BitBake uses for build output and intermediate files (other
292 than the cached information used by the
293 <link linkend='setscene'>Setscene</link> process.
294 Here, the <filename>TMPDIR</filename> directory is set to
295 <filename>hello/tmp</filename>.
296 <note><title>Tip</title>
297 You can always safely delete the <filename>tmp</filename>
298 directory in order to rebuild a BitBake target.
299 The build process creates the directory for you
300 when you run BitBake.
301 </note></para>
302 <para>For information about each of the other variables defined in this
303 example, click on the links to take you to the definitions in
304 the glossary.
305 </para></listitem>
306 <listitem><para><emphasis>Run Bitbake:</emphasis>
307 After making sure that the <filename>conf/bitbake.conf</filename>
308 file exists, you can run the <filename>bitbake</filename>
309 command again:
310 <literallayout class='monospaced'>
311$ bitbake
312ERROR: Traceback (most recent call last):
313 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
314 return func(fn, *args)
315 File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
316 bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
317 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
318 include(fn, file, lineno, d, "inherit")
319 File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
320 raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
321ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
322
323ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
324 </literallayout>
325 In the sample output, BitBake could not find the
326 <filename>classes/base.bbclass</filename> file.
327 You need to create that file next.
328 </para></listitem>
329 <listitem><para><emphasis>Creating <filename>classes/base.bbclass</filename>:</emphasis>
330 BitBake uses class files to provide common code and functionality.
331 The minimally required class for BitBake is the
332 <filename>classes/base.bbclass</filename> file.
333 The <filename>base</filename> class is implicitly inherited by
334 every recipe.
335 BitBake looks for the class in the <filename>classes</filename>
336 directory of the project (i.e <filename>hello/classes</filename>
337 in this example).
338 </para>
339 <para>Create the <filename>classes</filename> directory as follows:
340 <literallayout class='monospaced'>
341 $ cd $HOME/hello
342 $ mkdir classes
343 </literallayout>
344 Move to the <filename>classes</filename> directory and then
345 create the <filename>base.bbclass</filename> file by inserting
346 this single line:
347 <literallayout class='monospaced'>
348 addtask build
349 </literallayout>
350 The minimal task that BitBake runs is the
351 <filename>do_build</filename> task.
352 This is all the example needs in order to build the project.
353 Of course, the <filename>base.bbclass</filename> can have much
354 more depending on which build environments BitBake is
355 supporting.
356 For more information on the <filename>base.bbclass</filename> file,
357 you can look at
358 <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#tasks'></ulink>.
359 </para></listitem>
360 <listitem><para><emphasis>Run Bitbake:</emphasis>
361 After making sure that the <filename>classes/base.bbclass</filename>
362 file exists, you can run the <filename>bitbake</filename>
363 command again:
364 <literallayout class='monospaced'>
365 $ bitbake
366 Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
367 </literallayout>
368 BitBake is finally reporting no errors.
369 However, you can see that it really does not have anything
370 to do.
371 You need to create a recipe that gives BitBake something to do.
372 </para></listitem>
373 <listitem><para><emphasis>Creating a Layer:</emphasis>
374 While it is not really necessary for such a small example,
375 it is good practice to create a layer in which to keep your
376 code separate from the general metadata used by BitBake.
377 Thus, this example creates and uses a layer called "mylayer".
378 <note>
379 You can find additional information on adding a layer at
380 <ulink url='http://hambedded.org/blog/2012/11/24/from-bitbake-hello-world-to-an-image/#adding-an-example-layer'></ulink>.
381 </note>
382 </para>
383 <para>Minimally, you need a recipe file and a layer configuration
384 file in your layer.
385 The configuration file needs to be in the <filename>conf</filename>
386 directory inside the layer.
387 Use these commands to set up the layer and the <filename>conf</filename>
388 directory:
389 <literallayout class='monospaced'>
390 $ cd $HOME
391 $ mkdir mylayer
392 $ cd mylayer
393 $ mkdir conf
394 </literallayout>
395 Move to the <filename>conf</filename> directory and create a
396 <filename>layer.conf</filename> file that has the following:
397 <literallayout class='monospaced'>
398 BBPATH .= ":${<link linkend='var-LAYERDIR'>LAYERDIR</link>}"
399
400 <link linkend='var-BBFILES'>BBFILES</link> += "${LAYERDIR}/*.bb"
401
402 <link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link> += "mylayer"
403 <link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN_mylayer</link> := "^${LAYERDIR}/"
404 </literallayout>
405 For information on these variables, click the links
406 to go to the definitions in the glossary.</para>
407 <para>You need to create the recipe file next.
408 Inside your layer at the top-level, use an editor and create
409 a recipe file named <filename>printhello.bb</filename> that
410 has the following:
411 <literallayout class='monospaced'>
412 <link linkend='var-DESCRIPTION'>DESCRIPTION</link> = "Prints Hello World"
413 <link linkend='var-PN'>PN</link> = 'printhello'
414 <link linkend='var-PV'>PV</link> = '1'
415
416 python do_build() {
417 bb.plain("********************");
418 bb.plain("* *");
419 bb.plain("* Hello, World! *");
420 bb.plain("* *");
421 bb.plain("********************");
422 }
423 </literallayout>
424 The recipe file simply provides a description of the
425 recipe, the name, version, and the <filename>do_build</filename>
426 task, which prints out "Hello World" to the console.
427 For more information on these variables, follow the links
428 to the glossary.
429 </para></listitem>
430 <listitem><para><emphasis>Run Bitbake With a Target:</emphasis>
431 Now that a BitBake target exists, run the command and provide
432 that target:
433 <literallayout class='monospaced'>
434 $ cd $HOME/hello
435 $ bitbake printhello
436 ERROR: no recipe files to build, check your BBPATH and BBFILES?
437
438 Summary: There was 1 ERROR message shown, returning a non-zero exit code.
439 </literallayout>
440 We have created the layer with the recipe and the layer
441 configuration file but it still seems that BitBake cannot
442 find the recipe.
443 BitBake needs a <filename>conf/bblayers.conf</filename> that
444 lists the layers for the project.
445 Without this file, BitBake cannot find the recipe.
446 </para></listitem>
447 <listitem><para><emphasis>Creating <filename>conf/bblayers.conf</filename>:</emphasis>
448 BitBake uses the <filename>conf/bblayers.conf</filename> file
449 to locate layers needed for the project.
450 This file must reside in the <filename>conf</filename> directory
451 of the project (i.e. <filename>hello/conf</filename> for this
452 example).</para>
453 <para>Set your working directory to the <filename>hello/conf</filename>
454 directory and then create the <filename>bblayers.conf</filename>
455 file so that it contains the following:
456 <literallayout class='monospaced'>
457 BBLAYERS ?= " \
458 /home/&lt;you&gt;/mylayer \
459 "
460 </literallayout>
461 You need to provide your own information for
462 <filename>you</filename> in the file.
463 </para></listitem>
464 <listitem><para><emphasis>Run Bitbake With a Target:</emphasis>
465 Now that you have supplied the <filename>bblayers.conf</filename>
466 file, run the <filename>bitbake</filename> command and provide
467 the target:
468 <literallayout class='monospaced'>
469 $ bitbake printhello
470 Parsing recipes: 100% |##################################################################################|
471 Time: 00:00:00
472 Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
473 NOTE: Resolving any missing task queue dependencies
474 NOTE: Preparing runqueue
475 NOTE: Executing RunQueue Tasks
476 ********************
477 * *
478 * Hello, World! *
479 * *
480 ********************
481 NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.
482 </literallayout>
483 BitBake finds the <filename>printhello</filename> recipe and
484 successfully runs the task.
485 <note>
486 After the first execution, re-running
487 <filename>bitbake printhello</filename> again will not
488 result in a BitBake run that prints the same console
489 output.
490 The reason for this is that the first time the
491 <filename>printhello.bb</filename> recipe's
492 <filename>do_build</filename> task executes
493 successfully, BitBake writes a stamp file for the task.
494 Thus, the next time you attempt to run the task
495 using that same <filename>bitbake</filename> command,
496 BitBake notices the stamp and therefore determines
497 that the task does not need to be re-run.
498 If you delete the <filename>tmp</filename> directory
499 or run <filename>bitbake -c clean printhello</filename>
500 and then re-run the build, the "Hello, World!" message will
501 be printed again.
502 </note>
503 </para></listitem>
504 </orderedlist>
505 </section>
506</appendix>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-19 19:51:11 +0000