| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| |
| <appendix id='hello-world-example'> |
| <title>Hello World Example</title> |
| |
| <section id='bitbake-hello-world'> |
| <title>BitBake Hello World</title> |
| |
| <para> |
| The simplest example commonly used to demonstrate any new |
| programming language or tool is the |
| "<ulink url="http://en.wikipedia.org/wiki/Hello_world_program">Hello World</ulink>" |
| example. |
| This appendix demonstrates, in tutorial form, Hello |
| World within the context of BitBake. |
| The tutorial describes how to create a new project |
| and the applicable metadata files necessary to allow |
| BitBake to build it. |
| </para> |
| </section> |
| |
| <section id='example-obtaining-bitbake'> |
| <title>Obtaining BitBake</title> |
| |
| <para> |
| See the |
| "<link linkend='obtaining-bitbake'>Obtaining BitBake</link>" |
| section for information on how to obtain BitBake. |
| Once you have the source code on your machine, the BitBake directory |
| appears as follows: |
| <literallayout class='monospaced'> |
| $ ls -al |
| total 100 |
| drwxrwxr-x. 9 wmat wmat 4096 Jan 31 13:44 . |
| drwxrwxr-x. 3 wmat wmat 4096 Feb 4 10:45 .. |
| -rw-rw-r--. 1 wmat wmat 365 Nov 26 04:55 AUTHORS |
| drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 bin |
| drwxrwxr-x. 4 wmat wmat 4096 Jan 31 13:44 build |
| -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog |
| drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 classes |
| drwxrwxr-x. 2 wmat wmat 4096 Nov 26 04:55 conf |
| drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 contrib |
| -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING |
| drwxrwxr-x. 3 wmat wmat 4096 Nov 26 04:55 doc |
| -rw-rw-r--. 1 wmat wmat 69 Nov 26 04:55 .gitignore |
| -rw-rw-r--. 1 wmat wmat 849 Nov 26 04:55 HEADER |
| drwxrwxr-x. 5 wmat wmat 4096 Jan 31 13:44 lib |
| -rw-rw-r--. 1 wmat wmat 195 Nov 26 04:55 MANIFEST.in |
| -rw-rw-r--. 1 wmat wmat 2887 Nov 26 04:55 TODO |
| </literallayout> |
| </para> |
| |
| <para> |
| At this point, you should have BitBake cloned to |
| a directory that matches the previous listing except for |
| dates and user names. |
| </para> |
| </section> |
| |
| <section id='setting-up-the-bitbake-environment'> |
| <title>Setting Up the BitBake Environment</title> |
| |
| <para> |
| First, you need to be sure that you can run BitBake. |
| Set your working directory to where your local BitBake |
| files are and run the following command: |
| <literallayout class='monospaced'> |
| $ ./bin/bitbake --version |
| BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0 |
| </literallayout> |
| The console output tells you what version you are running. |
| </para> |
| |
| <para> |
| The recommended method to run BitBake is from a directory of your |
| choice. |
| To be able to run BitBake from any directory, you need to add the |
| executable binary to your binary to your shell's environment |
| <filename>PATH</filename> variable. |
| First, look at your current <filename>PATH</filename> variable |
| by entering the following: |
| <literallayout class='monospaced'> |
| $ echo $PATH |
| </literallayout> |
| Next, add the directory location for the BitBake binary to the |
| <filename>PATH</filename>. |
| Here is an example that adds the |
| <filename>/home/scott-lenovo/bitbake/bin</filename> directory |
| to the front of the <filename>PATH</filename> variable: |
| <literallayout class='monospaced'> |
| $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH |
| </literallayout> |
| You should now be able to enter the <filename>bitbake</filename> |
| command from the command line while working from any directory. |
| </para> |
| </section> |
| |
| <section id='the-hello-world-example'> |
| <title>The Hello World Example</title> |
| |
| <para> |
| The overall goal of this exercise is to build a |
| complete "Hello World" example utilizing task and layer |
| concepts. |
| Because this is how modern projects such as OpenEmbedded and |
| the Yocto Project utilize BitBake, the example |
| provides an excellent starting point for understanding |
| BitBake. |
| </para> |
| |
| <para> |
| To help you understand how to use BitBake to build targets, |
| the example starts with nothing but the <filename>bitbake</filename> |
| command, which causes BitBake to fail and report problems. |
| The example progresses by adding pieces to the build to |
| eventually conclude with a working, minimal "Hello World" |
| example. |
| </para> |
| |
| <para> |
| While every attempt is made to explain what is happening during |
| the example, the descriptions cannot cover everything. |
| You can find further information throughout this manual. |
| Also, you can actively participate in the |
| <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'></ulink> |
| discussion mailing list about the BitBake build tool. |
| </para> |
| |
| <note> |
| This example was inspired by and drew heavily from |
| <ulink url="http://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html">Mailing List post - The BitBake equivalent of "Hello, World!"</ulink>. |
| </note> |
| |
| <para> |
| As stated earlier, the goal of this example |
| is to eventually compile "Hello World". |
| However, it is unknown what BitBake needs and what you have |
| to provide in order to achieve that goal. |
| Recall that BitBake utilizes three types of metadata files: |
| <link linkend='configuration-files'>Configuration Files</link>, |
| <link linkend='classes'>Classes</link>, and |
| <link linkend='recipes'>Recipes</link>. |
| But where do they go? |
| How does BitBake find them? |
| BitBake's error messaging helps you answer these types of questions |
| and helps you better understand exactly what is going on. |
| </para> |
| |
| <para> |
| Following is the complete "Hello World" example. |
| </para> |
| |
| <orderedlist> |
| <listitem><para><emphasis>Create a Project Directory:</emphasis> |
| First, set up a directory for the "Hello World" project. |
| Here is how you can do so in your home directory: |
| <literallayout class='monospaced'> |
| $ mkdir ~/hello |
| $ cd ~/hello |
| </literallayout> |
| This is the directory that BitBake will use to do all of |
| its work. |
| You can use this directory to keep all the metafiles needed |
| by BitBake. |
| Having a project directory is a good way to isolate your |
| project. |
| </para></listitem> |
| <listitem><para><emphasis>Run Bitbake:</emphasis> |
| At this point, you have nothing but a project directory. |
| Run the <filename>bitbake</filename> command and see what |
| it does: |
| <literallayout class='monospaced'> |
| $ bitbake |
| The BBPATH variable is not set and bitbake did not |
| find a conf/bblayers.conf file in the expected location. |
| Maybe you accidentally invoked bitbake from the wrong directory? |
| DEBUG: Removed the following variables from the environment: |
| GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP, |
| GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy, |
| XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL, |
| MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR, |
| GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID, |
| XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS, |
| _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH, |
| UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS |
| </literallayout> |
| The majority of this output is specific to environment variables |
| that are not directly relevant to BitBake. |
| However, the very first message regarding the |
| <filename>BBPATH</filename> variable and the |
| <filename>conf/bblayers.conf</filename> file |
| is relevant.</para> |
| <para> |
| When you run BitBake, it begins looking for metadata files. |
| The |
| <link linkend='var-bb-BBPATH'><filename>BBPATH</filename></link> |
| variable is what tells BitBake where to look for those files. |
| <filename>BBPATH</filename> is not set and you need to set it. |
| Without <filename>BBPATH</filename>, Bitbake cannot |
| find any configuration files (<filename>.conf</filename>) |
| or recipe files (<filename>.bb</filename>) at all. |
| BitBake also cannot find the <filename>bitbake.conf</filename> |
| file. |
| </para></listitem> |
| <listitem><para><emphasis>Setting <filename>BBPATH</filename>:</emphasis> |
| For this example, you can set <filename>BBPATH</filename> |
| in the same manner that you set <filename>PATH</filename> |
| earlier in the appendix. |
| You should realize, though, that it is much more flexible to set the |
| <filename>BBPATH</filename> variable up in a configuration |
| file for each project.</para> |
| <para>From your shell, enter the following commands to set and |
| export the <filename>BBPATH</filename> variable: |
| <literallayout class='monospaced'> |
| $ BBPATH="<replaceable>projectdirectory</replaceable>" |
| $ export BBPATH |
| </literallayout> |
| Use your actual project directory in the command. |
| BitBake uses that directory to find the metadata it needs for |
| your project. |
| <note> |
| When specifying your project directory, do not use the |
| tilde ("~") character as BitBake does not expand that character |
| as the shell would. |
| </note> |
| </para></listitem> |
| <listitem><para><emphasis>Run Bitbake:</emphasis> |
| Now that you have <filename>BBPATH</filename> defined, run |
| the <filename>bitbake</filename> command again: |
| <literallayout class='monospaced'> |
| $ bitbake |
| ERROR: Traceback (most recent call last): |
| File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped |
| return func(fn, *args) |
| File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file |
| return bb.parse.handle(fn, data, include) |
| File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle |
| return h['handle'](fn, data, include) |
| File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle |
| abs_fn = resolve_file(fn, data) |
| File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file |
| raise IOError("file %s not found in %s" % (fn, bbpath)) |
| IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello |
| |
| ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello |
| </literallayout> |
| This sample output shows that BitBake could not find the |
| <filename>conf/bitbake.conf</filename> file in the project |
| directory. |
| This file is the first thing BitBake must find in order |
| to build a target. |
| And, since the project directory for this example is |
| empty, you need to provide a <filename>conf/bitbake.conf</filename> |
| file. |
| </para></listitem> |
| <listitem><para><emphasis>Creating <filename>conf/bitbake.conf</filename>:</emphasis> |
| The <filename>conf/bitbake.conf</filename> includes a number of |
| configuration variables BitBake uses for metadata and recipe |
| files. |
| For this example, you need to create the file in your project directory |
| and define some key BitBake variables. |
| For more information on the <filename>bitbake.conf</filename> file, |
| see |
| <ulink url='http://git.openembedded.org/bitbake/tree/conf/bitbake.conf'></ulink>. |
| </para> |
| <para>Use the following commands to create the <filename>conf</filename> |
| directory in the project directory: |
| <literallayout class='monospaced'> |
| $ mkdir conf |
| </literallayout> |
| From within the <filename>conf</filename> directory, use |
| some editor to create the <filename>bitbake.conf</filename> |
| so that it contains the following: |
| <literallayout class='monospaced'> |
| <link linkend='var-bb-PN'>PN</link> = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" |
| </literallayout> |
| <literallayout class='monospaced'> |
| TMPDIR = "${<link linkend='var-bb-TOPDIR'>TOPDIR</link>}/tmp" |
| <link linkend='var-bb-CACHE'>CACHE</link> = "${TMPDIR}/cache" |
| <link linkend='var-bb-STAMP'>STAMP</link> = "${TMPDIR}/${PN}/stamps" |
| <link linkend='var-bb-T'>T</link> = "${TMPDIR}/${PN}/work" |
| <link linkend='var-bb-B'>B</link> = "${TMPDIR}/${PN}" |
| </literallayout> |
| <note> |
| Without a value for <filename>PN</filename>, the |
| variables <filename>STAMP</filename>, |
| <filename>T</filename>, and <filename>B</filename>, |
| prevent more than one recipe from working. You can fix |
| this by either setting <filename>PN</filename> to have |
| a value similar to what OpenEmbedded and BitBake use |
| in the default <filename>bitbake.conf</filename> file |
| (see previous example). Or, by manually updating each |
| recipe to set <filename>PN</filename>. You will also |
| need to include <filename>PN</filename> as part of the |
| <filename>STAMP</filename>, <filename>T</filename>, and |
| <filename>B</filename> variable definitions in the |
| <filename>local.conf</filename> file. |
| </note> |
| The <filename>TMPDIR</filename> variable establishes a directory |
| that BitBake uses for build output and intermediate files other |
| than the cached information used by the |
| <link linkend='setscene'>Setscene</link> process. |
| Here, the <filename>TMPDIR</filename> directory is set to |
| <filename>hello/tmp</filename>. |
| <note><title>Tip</title> |
| You can always safely delete the <filename>tmp</filename> |
| directory in order to rebuild a BitBake target. |
| The build process creates the directory for you |
| when you run BitBake. |
| </note></para> |
| <para>For information about each of the other variables defined in this |
| example, click on the links to take you to the definitions in |
| the glossary. |
| </para></listitem> |
| <listitem><para><emphasis>Run Bitbake:</emphasis> |
| After making sure that the <filename>conf/bitbake.conf</filename> |
| file exists, you can run the <filename>bitbake</filename> |
| command again: |
| <literallayout class='monospaced'> |
| $ bitbake |
| ERROR: Traceback (most recent call last): |
| File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped |
| return func(fn, *args) |
| File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit |
| bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data) |
| File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit |
| include(fn, file, lineno, d, "inherit") |
| File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include |
| raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno) |
| ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass |
| |
| ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass |
| </literallayout> |
| In the sample output, BitBake could not find the |
| <filename>classes/base.bbclass</filename> file. |
| You need to create that file next. |
| </para></listitem> |
| <listitem><para><emphasis>Creating <filename>classes/base.bbclass</filename>:</emphasis> |
| BitBake uses class files to provide common code and functionality. |
| The minimally required class for BitBake is the |
| <filename>classes/base.bbclass</filename> file. |
| The <filename>base</filename> class is implicitly inherited by |
| every recipe. |
| BitBake looks for the class in the <filename>classes</filename> |
| directory of the project (i.e <filename>hello/classes</filename> |
| in this example). |
| </para> |
| <para>Create the <filename>classes</filename> directory as follows: |
| <literallayout class='monospaced'> |
| $ cd $HOME/hello |
| $ mkdir classes |
| </literallayout> |
| Move to the <filename>classes</filename> directory and then |
| create the <filename>base.bbclass</filename> file by inserting |
| this single line: |
| <literallayout class='monospaced'> |
| addtask build |
| </literallayout> |
| The minimal task that BitBake runs is the |
| <filename>do_build</filename> task. |
| This is all the example needs in order to build the project. |
| Of course, the <filename>base.bbclass</filename> can have much |
| more depending on which build environments BitBake is |
| supporting. |
| </para></listitem> |
| <listitem><para><emphasis>Run Bitbake:</emphasis> |
| After making sure that the <filename>classes/base.bbclass</filename> |
| file exists, you can run the <filename>bitbake</filename> |
| command again: |
| <literallayout class='monospaced'> |
| $ bitbake |
| Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information. |
| </literallayout> |
| BitBake is finally reporting no errors. |
| However, you can see that it really does not have anything |
| to do. |
| You need to create a recipe that gives BitBake something to do. |
| </para></listitem> |
| <listitem><para><emphasis>Creating a Layer:</emphasis> |
| While it is not really necessary for such a small example, |
| it is good practice to create a layer in which to keep your |
| code separate from the general metadata used by BitBake. |
| Thus, this example creates and uses a layer called "mylayer". |
| <note> |
| You can find additional information on layers in the |
| "<link linkend='layers'>Layers</link>" section. |
| </note></para> |
| |
| <para>Minimally, you need a recipe file and a layer configuration |
| file in your layer. |
| The configuration file needs to be in the <filename>conf</filename> |
| directory inside the layer. |
| Use these commands to set up the layer and the <filename>conf</filename> |
| directory: |
| <literallayout class='monospaced'> |
| $ cd $HOME |
| $ mkdir mylayer |
| $ cd mylayer |
| $ mkdir conf |
| </literallayout> |
| Move to the <filename>conf</filename> directory and create a |
| <filename>layer.conf</filename> file that has the following: |
| <literallayout class='monospaced'> |
| BBPATH .= ":${<link linkend='var-bb-LAYERDIR'>LAYERDIR</link>}" |
| |
| <link linkend='var-bb-BBFILES'>BBFILES</link> += "${LAYERDIR}/*.bb" |
| |
| <link linkend='var-bb-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link> += "mylayer" |
| <link linkend='var-bb-BBFILE_PATTERN'>BBFILE_PATTERN_mylayer</link> := "^${LAYERDIR_RE}/" |
| </literallayout> |
| For information on these variables, click the links |
| to go to the definitions in the glossary.</para> |
| <para>You need to create the recipe file next. |
| Inside your layer at the top-level, use an editor and create |
| a recipe file named <filename>printhello.bb</filename> that |
| has the following: |
| <literallayout class='monospaced'> |
| <link linkend='var-bb-DESCRIPTION'>DESCRIPTION</link> = "Prints Hello World" |
| <link linkend='var-bb-PN'>PN</link> = 'printhello' |
| <link linkend='var-bb-PV'>PV</link> = '1' |
| |
| python do_build() { |
| bb.plain("********************"); |
| bb.plain("* *"); |
| bb.plain("* Hello, World! *"); |
| bb.plain("* *"); |
| bb.plain("********************"); |
| } |
| </literallayout> |
| The recipe file simply provides a description of the |
| recipe, the name, version, and the <filename>do_build</filename> |
| task, which prints out "Hello World" to the console. |
| For more information on these variables, follow the links |
| to the glossary. |
| </para></listitem> |
| <listitem><para><emphasis>Run Bitbake With a Target:</emphasis> |
| Now that a BitBake target exists, run the command and provide |
| that target: |
| <literallayout class='monospaced'> |
| $ cd $HOME/hello |
| $ bitbake printhello |
| ERROR: no recipe files to build, check your BBPATH and BBFILES? |
| |
| Summary: There was 1 ERROR message shown, returning a non-zero exit code. |
| </literallayout> |
| We have created the layer with the recipe and the layer |
| configuration file but it still seems that BitBake cannot |
| find the recipe. |
| BitBake needs a <filename>conf/bblayers.conf</filename> that |
| lists the layers for the project. |
| Without this file, BitBake cannot find the recipe. |
| </para></listitem> |
| <listitem><para><emphasis>Creating <filename>conf/bblayers.conf</filename>:</emphasis> |
| BitBake uses the <filename>conf/bblayers.conf</filename> file |
| to locate layers needed for the project. |
| This file must reside in the <filename>conf</filename> directory |
| of the project (i.e. <filename>hello/conf</filename> for this |
| example).</para> |
| <para>Set your working directory to the <filename>hello/conf</filename> |
| directory and then create the <filename>bblayers.conf</filename> |
| file so that it contains the following: |
| <literallayout class='monospaced'> |
| BBLAYERS ?= " \ |
| /home/<you>/mylayer \ |
| " |
| </literallayout> |
| You need to provide your own information for |
| <filename>you</filename> in the file. |
| </para></listitem> |
| <listitem><para><emphasis>Run Bitbake With a Target:</emphasis> |
| Now that you have supplied the <filename>bblayers.conf</filename> |
| file, run the <filename>bitbake</filename> command and provide |
| the target: |
| <literallayout class='monospaced'> |
| $ bitbake printhello |
| Parsing recipes: 100% |##################################################################################| |
| Time: 00:00:00 |
| Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors. |
| NOTE: Resolving any missing task queue dependencies |
| NOTE: Preparing RunQueue |
| NOTE: Executing RunQueue Tasks |
| ******************** |
| * * |
| * Hello, World! * |
| * * |
| ******************** |
| NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded. |
| </literallayout> |
| BitBake finds the <filename>printhello</filename> recipe and |
| successfully runs the task. |
| <note> |
| After the first execution, re-running |
| <filename>bitbake printhello</filename> again will not |
| result in a BitBake run that prints the same console |
| output. |
| The reason for this is that the first time the |
| <filename>printhello.bb</filename> recipe's |
| <filename>do_build</filename> task executes |
| successfully, BitBake writes a stamp file for the task. |
| Thus, the next time you attempt to run the task |
| using that same <filename>bitbake</filename> command, |
| BitBake notices the stamp and therefore determines |
| that the task does not need to be re-run. |
| If you delete the <filename>tmp</filename> directory |
| or run <filename>bitbake -c clean printhello</filename> |
| and then re-run the build, the "Hello, World!" message will |
| be printed again. |
| </note> |
| </para></listitem> |
| </orderedlist> |
| </section> |
| </appendix> |