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