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 :term:`PN`, the variables :term:`STAMP`, :term:`T`, and :term:`B`, prevent more 213 than one recipe from working. You can fix this by either setting :term:`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 :term:`PN`. You will also need to include :term:`PN` as part of the :term:`STAMP`, 217 :term:`T`, and :term:`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 :term:`LAYERSERIES_COMPAT` in this particular case, because we 323 are using bitbake without OpenEmbedded. 324 You should usually just use :term:`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