diff options
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.xml | 334 |
1 files changed, 334 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..3215e49a28 --- /dev/null +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml @@ -0,0 +1,334 @@ +<!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 + -rwxrwxr-x. 1 wmat wmat 3195 Jan 31 11:57 setup.py + -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> + The recommended method to run BitBake is from a directory of your + choice. + The directory can be within your home directory or in + <filename>/usr/local</filename>, + depending on your preference. + </para> + + <para> + First, run BitBake to make sure it's working. + From the BitBake source code directory, issue the following command: + <literallayout class='monospaced'> + $ ./bin/bitbake --version + BitBake Build Tool Core version 1.19.0, bitbake version + 1.19.0 + </literallayout> + You are now ready to use BitBake. + </para> + + <para> + A final step to make development easier is to add the executable + binary to your environment <filename>PATH</filename>. + 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> using this form: + <literallayout class='monospaced'> + $ export PATH=<path-to-bitbake-executable>:$PATH + </literallayout> + This will add the directory to the beginning of your + <filename>PATH</filename> environment variable. + You should now be able to enter the <filename>bitbake</filename> + command at the command line to run BitBake. + </para> + + <para> + For a more permanent solution assuming you are running the BASH + shell, edit <filename>~/.bashrc</filename> and add the following to the end + of that file: + <literallayout class='monospaced'> + PATH=<path-to-bitbake-executable>:$PATH + </literallayout> + </para> + + <para> + If you're a Vim user, you will find useful + Vim configuration contributions in the + <filename>contrib/vim</filename> directory. + Copy the files from that directory to your + <filename>/home/yourusername/.vim</filename> + directory. + If that directory does not exist, create it, and then + restart Vim. + </para> + </section> + + <section id='the-hello-world-example'> + <title>The Hello World Example</title> + + <para> + The following example leaps directly into how BitBake + works. + While every attempt is made to explain what is happening, + not everything can be covered. + You can find further information in the + "<link linkend='bitbake-user-manual-metadata'>Syntax and Operators</link>" + chapter. + </para> + + <para> + The overall goal of this exercise is to build a + complete "Hello World" example utilizing task and layer + concepts. + This is how modern projects such as OpenEmbedded and + the Yocto Project utilize BitBake, therefore it + provides an excellent starting point for understanding + BitBake. + </para> + + <para> + It should be noted that this chapter was inspired by + and draws heavily from several sources: + <itemizedlist> + <listitem><para> + <ulink href="http://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html">Mailing List post - The BitBake equivalent of "Hello, World!"</ulink> + </para></listitem> + <listitem><para> + <ulink href="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> + </para></listitem> + </itemizedlist> + </para> + + <section id='a-reverse-walk-through'> + <title>A Reverse Walk-Through</title> + + <para> + A good way to understand anything is to walk through the steps + that take you to where you want to be and observe first + principles. + BitBake allows us to do this through the + <filename>-D</filename> or <filename>Debug</filename> + command-line parameter. + </para> + + <para> + The goal is to eventually compile a "Hello World" example. + However, it is unknown what is needed 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> + 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 ~/dev/hello && cd ~/dev/hello + </literallayout> + Within this new, empty directory, run BitBake with + debugging output and see what happens: + <literallayout class='monospaced'> + $ bitbake -DDD + The BBPATH variable is not set + DEBUG: Removed the following variables from the environment: + GNOME_DESKTOP_SESSION_ID, LESSOPEN, WINDOWID, + GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, + XDG_SESSION_PATH, XAUTHORITY, LANGUAGE, SESSION_MANAGER, + SHLVL, MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, TEXTDOMAIN, + GPG_AGENT_INFO, SSH_AUTH_SOCK, XDG_RUNTIME_DIR, + COMPIZ_BIN_PATH, GDMSESSION, DEFAULTS_PATH, TEXTDOMAINDIR, + XDG_SEAT_PATH, XDG_CONFIG_DIRS, XDG_CURRENT_DESKTOP, + DBUS_SESSION_BUS_ADDRESS, _, XDG_SESSION_COOKIE, + DESKTOP_SESSION, LESSCLOSE, GNOME_KEYRING_PID, + UBUNTU_MENUPROXY, OLDPWD, GTK_MODULES, 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 + "<filename>The BBPATH variable is not set</filename>" + is relevant and you need to rectify it by setting + <link linkend='var-BBPATH'><filename>BBPATH</filename></link>. + </para> + + <para> + When you run BitBake, it begins looking for metadata files. + The <filename>BBPATH</filename> variable is what tells + BitBake where to look. + You could set <filename>BBPATH</filename> in the same manner + that you set <filename>PATH</filename> as shown earlier. + However, it is much more flexible to set the + <link linkend='var-BBPATH'><filename>BBPATH</filename></link> + variable for each project. + </para> + + <para> + 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> + + <para> + It is standard practice to organize the project's directory tree + to include both a <filename>conf/</filename> and + <filename>classes/</filename> directory. + You need to add those directories to your project: + <literallayout class='monospaced'> + $ mkdir conf classes + </literallayout> + Once those directories are in place, you can copy the + sample configuration files provided in the + BitBake source tree to their appropriate directories. + First, change to the BitBake source tree directory and + then copy the directories: + <literallayout class='monospaced'> + cp conf/bitbake.conf ~/dev/hello/conf/ + cp classes/base.bbclass ~/dev/hello/classes/ + </literallayout> + At this point your project directory structure should look like + the following: + <literallayout class='monospaced'> + ~/dev/hello$ tree + . + |-- classes + | +-- base.bbclass + +-- conf + +-- bitbake.conf + </literallayout> + </para> + + <para> + Once you have copied these files into your project, you + can now get back to resolving the <filename>BBPATH</filename> + issue. + </para> + + <para> + The first configuration file that BitBake looks for is always + <filename>bblayers.conf</filename>. + With this knowledge, you know that to resolve your + <filename>BBPATH</filename> error you can add a + <filename>conf/bblayers.conf</filename> file to the + project source tree and populate it with the + <filename>BBPATH</filename> variable declaration. + </para> + + <para> + From your project source tree: + <literallayout class='monospaced'> + $ vim conf/bblayers.conf + </literallayout> + Now add the following to the empty + <filename>bblayers.conf</filename> file: + <literallayout class='monospaced'> + BBPATH := "${TOPDIR}" + </literallayout> + </para> + + <para> + Now, from the root of your project directory, run BitBake + again and see what happens: + <literallayout class='monospaced'> + $ bitbake -DDD + Nothing to do. Use 'bitbake world' to build everything, or run + 'bitbake --help' for usage information. + DEBUG: Removed the following variables from the environment: + GNOME_DESKTOP_SESSION_ID, LESSOPEN, WINDOWID, + GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, + XDG_SESSION_PATH, XAUTHORITY, LANGUAGE, SESSION_MANAGER, + SHLVL, MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, TEXTDOMAIN, + GPG_AGENT_INFO, SSH_AUTH_SOCK, XDG_RUNTIME_DIR, + COMPIZ_BIN_PATH, GDMSESSION, DEFAULTS_PATH, TEXTDOMAINDIR, + XDG_SEAT_PATH, XDG_CONFIG_DIRS, XDG_CURRENT_DESKTOP, + DBUS_SESSION_BUS_ADDRESS, _, XDG_SESSION_COOKIE, + DESKTOP_SESSION, LESSCLOSE, GNOME_KEYRING_PID, UBUNTU_MENUPROXY, + OLDPWD, GTK_MODULES, XDG_DATA_DIRS, COLORTERM, LS_COLORS + DEBUG: Found bblayers.conf (/home/wmat/dev/hello/conf/ + bblayers.conf) + DEBUG: LOAD /home/wmat/dev/hello/conf/bblayers.conf + DEBUG: LOAD /home/wmat/dev/hello/conf/bitbake.conf + DEBUG: BB configuration INHERITs:0: inheriting /home/wmat/dev/ + hello/classes/base.bbclass + DEBUG: BB /home/wmat/dev/hello/classes/base.bbclass: handle + (data, include) + DEBUG: LOAD /home/wmat/dev/hello/classes/base.bbclass + DEBUG: Clearing SRCREV cache due to cache policy of: clear + DEBUG: Using cache in '/home/wmat/dev/hello/tmp/cache/ + local_file_checksum_cache.dat' + DEBUG: Using cache in '/home/wmat/dev/hello/tmp/cache/ + bb_codeparser.dat' + </literallayout> + <note> + From this point forward in the example, the environment + variable removal messages are ignored and omitted. + Examine the relevant DEBUG messages: + </note> + </para> + </section> + </section> +</appendix> |