From 4cd882b9d05f503ee58f78cceebaa9e63dc2048f Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 19 Feb 2014 16:15:38 -0600 Subject: bitbake: user-manual: Added "Hello World" Appendix. I took Bill's chapter and made it into an appendix. I did some re-writing to make it not so much like a getting-started feel, although it still leans way that way for an appendix. The content is not complete. Had to add in a line to the user-manual.xml file so that the new appendix would be part of the book. Had to use a different form of the command in the user-manual-cusomization.xsl file in order to not through a bunch of errors for an unrecognized parameter value. I commented out the existing one. (Bitbake rev: 80e9306c288ca2ab42585f99fb0f396253cb8253) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../doc/user-manual/user-manual-customization.xsl | 3 +- bitbake/doc/user-manual/user-manual-hello.xml | 213 +++++++++++---------- bitbake/doc/user-manual/user-manual.xml | 2 + 3 files changed, 117 insertions(+), 101 deletions(-) (limited to 'bitbake/doc') diff --git a/bitbake/doc/user-manual/user-manual-customization.xsl b/bitbake/doc/user-manual/user-manual-customization.xsl index 7d06e39d4d..a8ec28ae20 100644 --- a/bitbake/doc/user-manual/user-manual-customization.xsl +++ b/bitbake/doc/user-manual/user-manual-customization.xsl @@ -5,9 +5,10 @@ - + + A diff --git a/bitbake/doc/user-manual/user-manual-hello.xml b/bitbake/doc/user-manual/user-manual-hello.xml index 77869f80dd..5a616e07b3 100644 --- a/bitbake/doc/user-manual/user-manual-hello.xml +++ b/bitbake/doc/user-manual/user-manual-hello.xml @@ -1,8 +1,8 @@ - - A BitBake Hello World + + Hello World Example
BitBake Hello World @@ -12,22 +12,23 @@ programming language or tool is the Hello World example. - This chapter demonstrates, in tutorial form, Hello + This appendix demonstrates, in tutorial form, Hello World within the context of BitBake. - This tutorial describes how to create a new Project + The 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: + See the + "Obtaining BitBake" + section for information on how to obtain BitBake. + Once you have the source code on your machine, the BitBake directory + appears as follows: $ ls -al total 100 @@ -52,10 +53,9 @@ - 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. + At this point, you should have BitBake cloned to + a directory that matches the previous listing except for + dates and user names.
@@ -68,62 +68,56 @@ 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. + First, run BitBake 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. + You are 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: + First, look at your current PATH variable + by entering the following: $ 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: + Next, add the directory location for the BitBake binary to the + PATH using this form: - $ export PATH={path to the bitbake executable}:$PATH + $ export PATH=<path-to-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 + This will add the directory to the beginning of your + PATH environment variable. + You should now be able to enter the bitbake + command at the command line to run BitBake. + + + + For a more permanent solution 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 + PATH=<path-to-bitbake-executable>:$PATH - Note that if you're a Vim user, you will find useful + 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. + If that directory does not exist, create it, and then + restart Vim.
@@ -133,16 +127,17 @@ 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. + While every attempt is made to explain what is happening, + not everything can be covered. + You can find further information in the + "Syntax and Operators" + 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. + 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 @@ -162,34 +157,39 @@ -
- A Reverse Walkthrough +
+ A Reverse Walk-Through - One of the best means to understand anything is to walk - through the steps to where we want to be by observing first + 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 -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. + BitBake allows us to do this through the + -D or Debug + command-line parameter. + + + + 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: + Configuration Files, + Classes, and + Recipes. + 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. - 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: + First, set up a directory for the "Hello World" project. + Here is how you can do so in your home directory: $ mkdir ~/dev/hello && cd ~/dev/hello - Within this new, empty directory, let's run BitBake with - Debugging output and see what happens: + Within this new, empty directory, run BitBake with + debugging output and see what happens: $ bitbake -DDD The BBPATH variable is not set @@ -208,38 +208,44 @@ 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? + However, the very first message + "The BBPATH variable is not set" + is relevant and you need to rectify it by setting + BBPATH. + + + + When you run BitBake, it begins looking for metadata files. + The BBPATH variable is what tells + BitBake where to look. + You could set BBPATH in the same manner + that you set PATH as shown earlier. + However, it is much more flexible to set the + BBPATH + variable for each project. - 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 cannot + find any configuration files (.conf) + or recipe files (.bb) at all. + BitBake also cannot find the bitbake.conf + file. - 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 + to include both a conf/ and classes/ directory. - Add those now to your project directory: + You need to add those directories to your project: $ 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: + 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: cp conf/bitbake.conf ~/dev/hello/conf/ cp classes/base.bbclass ~/dev/hello/classes/ @@ -249,36 +255,43 @@ ~/dev/hello$ tree . - ├── classes - │   └── base.bbclass - └── conf - └── bitbake.conf + |-- classes + |   +-- base.bbclass + +-- conf + +-- bitbake.conf - But what about BBPATH, we still haven't set it? + Once you have copied these files into your project, you + can now get back to resolving the BBPATH + issue. 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. + With this knowledge, you know that to resolve your + BBPATH error you can add a + conf/bblayers.conf file to the + 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: + Now add the following to the empty + bblayers.conf file: BBPATH := "${TOPDIR}" - Now from the root of our project directory, let's run BitBake + Now, from the root of your project directory, run BitBake again and see what happens: $ bitbake -DDD @@ -311,11 +324,11 @@ bb_codeparser.dat' - From this point forward, the environment variable - removal messages will be ignored and omitted. - Let's examine the relevant DEBUG messages: + From this point forward in the example, the environment + variable removal messages are ignored and omitted. + Examine the relevant DEBUG messages:
- + diff --git a/bitbake/doc/user-manual/user-manual.xml b/bitbake/doc/user-manual/user-manual.xml index ba690ab243..76c3edf527 100644 --- a/bitbake/doc/user-manual/user-manual.xml +++ b/bitbake/doc/user-manual/user-manual.xml @@ -85,4 +85,6 @@ + + -- cgit v1.2.3-54-g00ecf