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