diff options
Diffstat (limited to 'doc/bitbake-user-manual/bitbake-user-manual-hello.xml')
| -rw-r--r-- | doc/bitbake-user-manual/bitbake-user-manual-hello.xml | 513 |
1 files changed, 0 insertions, 513 deletions
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-hello.xml b/doc/bitbake-user-manual/bitbake-user-manual-hello.xml deleted file mode 100644 index 11eb36aaf..000000000 --- a/doc/bitbake-user-manual/bitbake-user-manual-hello.xml +++ /dev/null @@ -1,513 +0,0 @@ -<!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> |