doc/bitbake-user-manual/bitbake-user-manual-intro.rst

9 Welcome to the BitBake User Manual. This manual provides information on
10 the BitBake tool. The information attempts to be as independent as
11 possible regarding systems that use BitBake, such as OpenEmbedded and
21 Fundamentally, BitBake is a generic task execution engine that allows
24 BitBake's main users, OpenEmbedded, takes this core and builds embedded
27 Conceptually, BitBake is similar to GNU Make in some regards but has
30 -  BitBake executes tasks according to the provided metadata that builds up
34    files. The metadata provides BitBake with instructions on what tasks
37 -  BitBake includes a fetcher library for obtaining source code from
46 -  BitBake includes a client/server abstraction and can be used from a
53 BitBake was originally a part of the OpenEmbedded project. It was
58 -  BitBake, a generic task executor
60 -  OpenEmbedded, a metadata set utilized by BitBake
62 Today, BitBake is the primary basis of the
68 Prior to BitBake, no other build tool adequately met the needs of an
74 Some important original goals for BitBake were:
101 -  Be easy to use BitBake to collaborate between multiple projects for
119 BitBake satisfies all the original requirements and many more with
122 priorities. BitBake is highly extensible and supports embedded Python
130 BitBake is a program written in the Python language. At the highest
131 level, BitBake interprets metadata, decides what tasks are required to
132 run, and executes those tasks. Similar to GNU Make, BitBake controls how
134 while BitBake uses "recipes".
136 BitBake extends the capabilities of a simple tool like GNU Make by
141 understood in order to better leverage the power of BitBake.
146 BitBake Recipes, which are denoted by the file extension ``.bb``, are
147 the most basic metadata files. These recipe files provide BitBake with
170 Within the context of BitBake, or any project utilizing BitBake as its
191 configuration file is the sample ``bitbake.conf`` file, which is located
192 within the BitBake source tree ``conf`` directory.
198 information that is useful to share between metadata files. The BitBake
228 accomplish this through a recipe that is a BitBake append
239 BitBake expects every append file to have a corresponding recipe file.
275 Obtaining BitBake
278 You can obtain BitBake several different ways:
280 -  **Cloning BitBake:** Using Git to clone the BitBake source code
281    repository is the recommended method for obtaining BitBake. Cloning
283    stable branches and the master branch. Once you have cloned BitBake,
285    master branch is for BitBake development and might contain less
288    You usually need a version of BitBake that matches the metadata you
292    Here is an example that clones the BitBake repository::
294      $ git clone git://git.openembedded.org/bitbake
296    This command clones the BitBake
297    Git repository into a directory called ``bitbake``. Alternatively,
299    want to call the new directory something other than ``bitbake``. Here
302      $ git clone git://git.openembedded.org/bitbake bbdev
305    This method is not recommended because the BitBake version that is
307    behind a snapshot of the BitBake repository.
309 -  **Taking a snapshot of BitBake:** Downloading a snapshot of BitBake
311    release of BitBake.
316          method for getting BitBake. Cloning the repository makes it easier
319    The following example downloads a snapshot of BitBake version 1.17.0::
321      $ wget https://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
322      $ tar zxpvf bitbake-1.17.0.tar.gz
325    the tar utility, you have a directory entitled ``bitbake-1.17.0``.
327 -  **Using the BitBake that Comes With Your Build Checkout:** A final
328    possibility for getting a copy of BitBake is that it already comes
329    with your checkout of a larger BitBake-based build system, such as
332    checkout will already include a version of BitBake that has been
334    information on how to check out a particular BitBake-based build
339 The BitBake Command
342 The ``bitbake`` command is the primary interface to the BitBake tool.
343 This section presents the BitBake command syntax and provides several
349 Following is the usage and syntax for BitBake::
351    $ bitbake -h
352    Usage: bitbake [options] [recipename/target recipe:do_task ...]
380                            Read the specified file before bitbake.conf.
382                            Read the specified file after bitbake.conf.
425      --server-only         Run bitbake without a UI, only starting a server
427      -B BIND, --bind=BIND  The name/address for the bitbake xmlrpc server to bind
430                            Set timeout to unload bitbake server due to
441      -m, --kill-server     Terminate any running bitbake server.
443      --status-only         Check the status of the remote bitbake server.
445                            Writes the event log of the build to a bitbake event
460 This section presents some examples showing how to use BitBake.
468 specify the file in question, and BitBake parses it and executes the
469 specified task. If you do not specify a task, BitBake executes the
470 default task, which is "build". BitBake obeys inter-task dependencies
476   $ bitbake -b foo_1.0.bb
480   $ bitbake -b foo.bb -c clean
493 tell BitBake what files are available and, of those, which you want to
499 The ``bitbake`` command, when not using "--buildfile" or "-b" only
504   $ bitbake foo
507 package name and also uses the "-c" option to tell BitBake to just
510   $ bitbake -c clean foo
515 The BitBake command line supports specifying different tasks for
518 ``mysecondrecipe`` and you needed BitBake to run ``taskA`` for the first
521   $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
526 BitBake is able to generate dependency graphs using the ``dot`` syntax.
530 When you generate a dependency graph, BitBake writes two files to the
534    dependencies match BitBake's internal task execution list.
540 BitBake omits them from the graph. Leaving this information out can
547   $ bitbake -g foo
549   $ bitbake -g -I virtual/kernel -I eglibc foo
554 BitBake is able to build multiple images or packages using a single
575 temporary directory BitBake uses for the build. Suggested practice
580 enable BitBake to perform multiple configuration builds. Enabling is
586 enables BitBake to perform multiple configuration builds and specifies
591 Once the target configuration files are in place and BitBake has been
595   $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ]
599   $ bitbake mc::target mc:target1:target mc:target2:target
634 using a BitBake command as follows::
636   $ bitbake mc:target1:image1
639 multiconfig. Because of the dependency, BitBake also executes through
648 In this case, BitBake must create ``image2`` for the "target2" build since
652 builds and have separate configuration files, BitBake places the