From 437791a23d7b82e23f63956857deb3ed5c4e3a21 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 14 Jan 2014 07:27:59 -0600 Subject: bitbake: user-manual-hello.xml: Added new chapter for "Hello World Example" This file was evidently a "working" file and not included in the manual at the point Bill left off. The wmat branch, however, had a load of commits dedicated to this file. Rather than attempt to replay them all one-by-one, I simply copied the file from the wmat branch and hand-inserted the changes to make it equal to what was there. Note also that I re-formatted the file to have the same formatting standards I use in the YP manuals. (Bitbake rev: 9ddbf31ba7d05a596ca53b8ed78d94221850894b) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- bitbake/doc/user-manual/user-manual-hello.xml | 321 ++++++++++++++++++++++++++ 1 file changed, 321 insertions(+) create mode 100644 bitbake/doc/user-manual/user-manual-hello.xml (limited to 'bitbake/doc') diff --git a/bitbake/doc/user-manual/user-manual-hello.xml b/bitbake/doc/user-manual/user-manual-hello.xml new file mode 100644 index 0000000..77869f8 --- /dev/null +++ b/bitbake/doc/user-manual/user-manual-hello.xml @@ -0,0 +1,321 @@ + + + + A BitBake Hello World + +
+ BitBake Hello World + + + The simplest example commonly used to demonstrate any new + programming language or tool is the + Hello World + example. + This chapter demonstrates, in tutorial form, Hello + World within the context of BitBake. + This tutorial describes how to create a new Project + and the applicable metadata files necessary to allow + BitBake to build it. + +
+ +
+ Obtaining BitBake + + + Please refer to Chapter 1 Section 1.7 for the various methods to + obtain BitBake. + Once the source code is on your machine the BitBake directory will + appear as follows: + + $ 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 + + + + + At this point you should have BitBake extracted or cloned to + a directory and it should match the directory tree above. + Please note that you'll see your username wherever + "wmat" appears above. + +
+ +
+ Setting Up the BitBake Environment + + + The recommended method to run BitBake is from a directory of your + choice. + The directory can be within your home directory or in + /usr/local, + depending on your preference. + Let's run BitBake now to make sure it's working. + + + + From the BitBake source code directory, issue the following command: + + $ ./bin/bitbake --version + BitBake Build Tool Core version 1.19.0, bitbake version + 1.19.0 + + You're now ready to use BitBake. + + + + A final step to make development easier is to add the executable + binary to your environment PATH. + First, have a look at your current PATH variable. + If I check mine, I get: + + $ echo $PATH + /home/wmat/bin:/usr/lib/lightdm/lightdm:/usr/local/sbin:/usr/local/bin: + /usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games + + Now add the directory location for the BitBake binary to the PATH + with: + + $ export PATH={path to the bitbake executable}:$PATH + + This will add the directory to the beginning of your PATH environment + variable. + For example, on my machine: + + $ export PATH=/media/wmat/Backups/dev/bitbake/bin:$PATH + /media/wmat/Backups/dev/bitbake/bin:/home/wmat/bin: + /usr/lib/lightdm/lightdm:/usr/local/sbin:/usr/local/bin: + /usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games + + Now, you should be able to simply enter the + bitbake + command at the command line to run bitbake. + For a more permanent solution and assuming you are running the BASH + shell, edit ~/.bashrc and add the following to the end + of that file: + + PATH={path to the bitbake executable}:$PATH + + + + + Note that if you're a Vim user, you will find useful + Vim configuration contributions in the + contrib/vim directory. + Copy the files from that directory to your + /home/yourusername/.vim + directory. + If it doesn't exist, create it, and restart Vim. + +
+ +
+ The Hello World Example + + + The following example leaps directly into how BitBake + works. + Every attempt is made to explain what is happening, + however, further information can be found in the + Metadata chapter. + + + + The overall goal of this exercise is to create a Hello + World example utilizing concepts used to + build and construct a complete example application + including Tasks and Layers. + This is how modern projects such as OpenEmbedded and + the Yocto Project utilize BitBake, therefore it + provides an excellent starting point for understanding + BitBake. + + + + It should be noted that this chapter was inspired by + and draws heavily from several sources: + + + Mailing List post - The BitBake equivalent of "Hello, World!" + + + Hambedded Linux blog post - From Bitbake Hello World to an Image + + + + +
+ A Reverse Walkthrough + + + One of the best means to understand anything is to walk + through the steps to where we want to be by observing first + principles. + BitBake allows us to do this through the -D or Debug command + line parameter. + We know we want to eventually compile a HelloWorld example, but + we don't know what we need to do that. + Remember that BitBake utilizes three types of metadata files: + Configuration Files, Classes, and Recipes. + But where do they go, how does BitBake find them, etc. etc.? + Hopefully we can use BitBake's error messaging to figure this + out and better understand exactly what's going on. + + + + First, let's begin by setting up a directory for our HelloWorld + project. + I'll do this in my home directory and change into that + directory: + + $ mkdir ~/dev/hello && cd ~/dev/hello + + Within this new, empty directory, let's run BitBake with + Debugging output and see what happens: + + $ 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 + + The majority of this output is specific to environment variables + that are not directly relevant to BitBake. + However, the very + first message The BBPATH variable is not set + is and needs to be rectified. + So how do we set the BBPATH + variable? + + + + When BitBake is run it begins looking for metadata files. + The BBPATH variable is what tells BitBake where to look. + It is possible to set BBPATH as an environment variable as you + did above for the BitBake exexcutable's PATH. + However, it's much more flexible to set the BBPATH variable for + each project, as this allows for greater flexibility. + + + + Without BBPATH Bitbake will not find any .conf + files or recipe files at all. + It will also not find bitbake.conf. + Note the reference to conf/. + It is standard practice to organize the project's directory tree + to include a conf/ and a + classes/ directory. + Add those now to your project directory: + + $ mkdir conf classes + + Now let's copy the sample configuration files provided in the + BitBake source tree to their appropriate conf and classes + directory. + Change to the BitBake source tree directory and: + + cp conf/bitbake.conf ~/dev/hello/conf/ + cp classes/base.bbclass ~/dev/hello/classes/ + + At this point your project directory structure should look like + the following: + + ~/dev/hello$ tree + . + ├── classes + │   └── base.bbclass + └── conf + └── bitbake.conf + + + + + But what about BBPATH, we still haven't set it? + + + + The first configuration file that BitBake looks for is always + bblayers.conf. + With this knowledge we know that to resolve our BBPATH error we + can add a conf/bblayers.conf file to our + project source tree and populate it with the BBPATH variable + declaration. + From your project source tree: + + $ vim conf/bblayers.conf + + Add the following to the empty bblayers.conf file: + + BBPATH := "${TOPDIR}" + + + + + Now from the root of our project directory, let's run BitBake + again and see what happens: + + $ 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' + + + From this point forward, the environment variable + removal messages will be ignored and omitted. + Let's examine the relevant DEBUG messages: + + +
+
+ -- cgit v1.1