335 lines
14 KiB
XML
335 lines
14 KiB
XML
<!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>
|