diff options
Diffstat (limited to 'poky/bitbake/doc')
6 files changed, 152 insertions, 41 deletions
diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml index 46dafeee3..e4251dff5 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml @@ -113,7 +113,7 @@ </para> <para> - Prior to parsing configuration files, Bitbake looks + Prior to parsing configuration files, BitBake looks at certain variables, including: <itemizedlist> <listitem><para> @@ -339,7 +339,7 @@ <link linkend='var-bb-BB_HASHCONFIG_WHITELIST'><filename>BB_HASHCONFIG_WHITELIST</filename></link>) and then checking if the checksum matches. If that checksum matches what is in the cache and the recipe - and class files have not changed, Bitbake is able to use + and class files have not changed, BitBake is able to use the cache. BitBake then reloads the cached information about the recipe instead of reparsing it from scratch. @@ -429,7 +429,7 @@ The default <link linkend='var-bb-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link> is the provider with the same name as the target. - Bitbake iterates through each target it needs to build and + BitBake iterates through each target it needs to build and resolves them and their dependencies using this process. </para> @@ -618,12 +618,12 @@ <para> Tasks can be either a shell task or a Python task. For shell tasks, BitBake writes a shell script to - <filename>${</filename><link linkend='var-bb-T'><filename>T</filename></link><filename>}/run.do_taskname.pid</filename> + <filename>${</filename><link linkend='var-bb-T'><filename>T</filename></link><filename>}/run.do_taskname.<replaceable>pid</replaceable></filename> and then executes the script. The generated shell script contains all the exported variables, and the shell functions with all variables expanded. Output from the shell script goes to the file - <filename>${T}/log.do_taskname.pid</filename>. + <filename>${T}/log.do_taskname.<replaceable>pid</replaceable></filename>. Looking at the expanded shell functions in the run file and the output in the log files is a useful debugging technique. </para> @@ -821,7 +821,7 @@ <para> It is worth noting that BitBake's "-S" option lets you - debug Bitbake's processing of signatures. + debug BitBake's processing of signatures. The options passed to -S allow different debugging modes to be used, either using BitBake's own debug functions or possibly those defined in the metadata/signature handler @@ -929,4 +929,101 @@ section. </para> </section> + + <section id="logging"> + <title>Logging</title> + <para> + In addition to the standard command line option to control how + verbose builds are when execute, bitbake also supports user defined + configuration of the + <ulink url='https://docs.python.org/3/library/logging.html'>Python logging</ulink> + facilities through the + <link linkend="var-bb-BB_LOGCONFIG"><filename>BB_LOGCONFIG</filename></link> + variable. This variable defines a json or yaml + <ulink url='https://docs.python.org/3/library/logging.config.html'>logging configuration</ulink> + that will be intelligently merged into the default configuration. + The logging configuration is merged using the following rules: + <itemizedlist> + <listitem><para> + The user defined configuration will completely replace the default + configuration if top level key + <filename>bitbake_merge</filename> is set to the value + <filename>False</filename>. In this case, all other rules + are ignored. + </para></listitem> + <listitem><para> + The user configuration must have a top level + <filename>version</filename> which must match the value of + the default configuration. + </para></listitem> + <listitem><para> + Any keys defined in the <filename>handlers</filename>, + <filename>formatters</filename>, or <filename>filters</filename>, + will be merged into the same section in the default + configuration, with the user specified keys taking + replacing a default one if there is a conflict. In + practice, this means that if both the default configuration + and user configuration specify a handler named + <filename>myhandler</filename>, the user defined one will + replace the default. To prevent the user from inadvertently + replacing a default handler, formatter, or filter, all of + the default ones are named with a prefix of + "<filename>BitBake.</filename>" + </para></listitem> + <listitem><para> + If a logger is defined by the user with the key + <filename>bitbake_merge</filename> set to + <filename>False</filename>, that logger will be completely + replaced by user configuration. In this case, no other + rules will apply to that logger. + </para></listitem> + <listitem><para> + All user defined <filename>filter</filename> and + <filename>handlers</filename> properties for a given logger + will be merged with corresponding properties from the + default logger. For example, if the user configuration adds + a filter called <filename>myFilter</filename> to the + <filename>BitBake.SigGen</filename>, and the default + configuration adds a filter called + <filename>BitBake.defaultFilter</filename>, both filters + will be applied to the logger + </para></listitem> + </itemizedlist> + </para> + + <para> + As an example, consider the following user logging configuration + file which logs all Hash Equivalence related messages of VERBOSE or + higher to a file called <filename>hashequiv.log</filename> + <literallayout class='monospaced'> + { + "version": 1, + "handlers": { + "autobuilderlog": { + "class": "logging.FileHandler", + "formatter": "logfileFormatter", + "level": "DEBUG", + "filename": "hashequiv.log", + "mode": "w" + } + }, + "formatters": { + "logfileFormatter": { + "format": "%(name)s: %(levelname)s: %(message)s" + } + }, + "loggers": { + "BitBake.SigGen.HashEquiv": { + "level": "VERBOSE", + "handlers": ["autobuilderlog"] + }, + "BitBake.RunQueue.HashEquiv": { + "level": "VERBOSE", + "handlers": ["autobuilderlog"] + } + } + } + </literallayout> + </para> + </section> </chapter> diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml index 684040856..d1bfc2336 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml @@ -139,7 +139,7 @@ </para> <para> - Since network accesses are slow, Bitbake maintains a + Since network accesses are slow, BitBake maintains a cache of files downloaded from the network. Any source files that are not local (i.e. downloaded from the Internet) are placed into the download diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml index 39066e4b1..11eb36aaf 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml @@ -166,7 +166,7 @@ Having a project directory is a good way to isolate your project. </para></listitem> - <listitem><para><emphasis>Run Bitbake:</emphasis> + <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: @@ -197,7 +197,7 @@ <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 + 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> @@ -225,7 +225,7 @@ as the shell would. </note> </para></listitem> - <listitem><para><emphasis>Run Bitbake:</emphasis> + <listitem><para><emphasis>Run BitBake:</emphasis> Now that you have <filename>BBPATH</filename> defined, run the <filename>bitbake</filename> command again: <literallayout class='monospaced'> @@ -313,7 +313,7 @@ example, click on the links to take you to the definitions in the glossary. </para></listitem> - <listitem><para><emphasis>Run Bitbake:</emphasis> + <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: @@ -364,7 +364,7 @@ more depending on which build environments BitBake is supporting. </para></listitem> - <listitem><para><emphasis>Run Bitbake:</emphasis> + <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: @@ -434,7 +434,7 @@ For more information on these variables, follow the links to the glossary. </para></listitem> - <listitem><para><emphasis>Run Bitbake With a Target:</emphasis> + <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'> @@ -468,7 +468,7 @@ 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> + <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: diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml index 8f2a960ca..995c2fa7b 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml @@ -127,7 +127,7 @@ (e.g. Cygwin, the BSDs, and so forth). </para></listitem> <listitem><para> - Be self contained, rather than tightly + Be self-contained, rather than tightly integrated into the build machine's root filesystem. </para></listitem> @@ -221,6 +221,8 @@ them</para></listitem> <listitem><para>How to configure and compile the source code</para></listitem> + <listitem><para>How to assemble the generated artifacts into + one or more installable packages</para></listitem> <listitem><para>Where on the target machine to install the package or packages created</para></listitem> </itemizedlist> @@ -229,7 +231,7 @@ <para> Within the context of BitBake, or any project utilizing BitBake as its build system, files with the <filename>.bb</filename> - extension are referred to as recipes. + extension are referred to as <firstterm>recipes</firstterm>. <note> The term "package" is also commonly used to describe recipes. However, since the same word is used to describe packaged @@ -252,9 +254,9 @@ various configuration variables that govern the project's build process. These files fall into several areas that define - machine configuration options, distribution configuration - options, compiler tuning options, general common - configuration options, and user configuration options. + machine configuration, distribution configuration, + possible compiler tuning, general common + configuration, and user configuration. The main configuration file is the sample <filename>bitbake.conf</filename> file, which is located within the BitBake source tree @@ -292,7 +294,7 @@ Layers allow you to isolate different types of customizations from each other. While you might find it tempting to keep everything in one layer - when working on a single project, the more modular you organize + when working on a single project, the more modular your metadata, the easier it is to cope with future changes. </para> @@ -300,8 +302,8 @@ To illustrate how you can use layers to keep things modular, consider customizations you might make to support a specific target machine. These types of customizations typically reside in a special layer, - rather than a general layer, called a Board Support Package (BSP) - Layer. + rather than a general layer, called a <firstterm>Board Support Package</firstterm> (BSP) + layer. Furthermore, the machine customizations should be isolated from recipes and metadata that support a new GUI environment, for example. @@ -448,7 +450,7 @@ <listitem><para><emphasis>Using the BitBake that Comes With Your Build Checkout:</emphasis> A final possibility for getting a copy of BitBake is that it - already comes with your checkout of a larger Bitbake-based build + already comes with your checkout of a larger BitBake-based build system, such as Poky. Rather than manually checking out individual layers and gluing them together yourself, you can check @@ -692,15 +694,10 @@ </para> <para> - When you generate a dependency graph, BitBake writes three files + When you generate a dependency graph, BitBake writes two files to the current working directory: <itemizedlist> <listitem><para> - <emphasis><filename>recipe-depends.dot</filename>:</emphasis> - Shows dependencies between recipes (i.e. a collapsed version of - <filename>task-depends.dot</filename>). - </para></listitem> - <listitem><para> <emphasis><filename>task-depends.dot</filename>:</emphasis> Shows dependencies between tasks. These dependencies match BitBake's internal task execution list. diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml index 421364c2c..95a8b95b1 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml @@ -5,7 +5,7 @@ <title>Syntax and Operators</title> <para> - Bitbake files have their own syntax. + BitBake files have their own syntax. The syntax has similarities to several other languages but also has some unique features. This section describes the available syntax and operators @@ -294,17 +294,20 @@ rather than when the variable is actually used: <literallayout class='monospaced'> T = "123" - A := "${B} ${A} test ${T}" + A := "test ${T}" T = "456" - B = "${T} bval" + B := "${T} ${C}" C = "cval" C := "${C}append" </literallayout> In this example, <filename>A</filename> contains - "test 123" because <filename>${B}</filename> and - <filename>${A}</filename> at the time of parsing are undefined, - which leaves "test 123". - And, the variable <filename>C</filename> + "test 123", even though the final value of <filename>T</filename> + is "456". + The variable <filename>B</filename> will end up containing "456 cvalappend". + This is because references to undefined variables are preserved as is + during (immediate)expansion. This is in contrast to GNU Make, where undefined + variables expand to nothing. + The variable <filename>C</filename> contains "cvalappend" since <filename>${C}</filename> immediately expands to "cval". </para> @@ -1414,7 +1417,7 @@ </section> <section id='bitbake-style-python-functions-versus-python-functions'> - <title>Bitbake-Style Python Functions Versus Python Functions</title> + <title>BitBake-Style Python Functions Versus Python Functions</title> <para> Following are some important differences between @@ -1864,7 +1867,7 @@ accessing your <filename>$HOME/.ccache</filename> directory. The following command "whitelists" the environment variable - <filename>CCACHE_DIR</filename> causing BitBack to allow that + <filename>CCACHE_DIR</filename> causing BitBake to allow that variable into the datastore: <literallayout class='monospaced'> export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" @@ -1895,7 +1898,7 @@ <para> Sometimes, it is useful to be able to obtain information from the original execution environment. - Bitbake saves a copy of the original environment into + BitBake saves a copy of the original environment into a special variable named <link linkend='var-bb-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>. </para> @@ -2523,6 +2526,9 @@ In the previous example, the <filename>do_packagedata</filename> task of each item in <filename>RDEPENDS</filename> must have completed before <filename>do_package_qa</filename> can execute. + Although <filename>RDEPENDS</filename> contains entries from the + runtime dependency namespace, BitBake knows how to map them back + to the build-time dependency namespace, in which the tasks are defined. </para> </section> @@ -2616,7 +2622,7 @@ <para> It is often necessary to access variables in the BitBake datastore using Python functions. - The Bitbake datastore has an API that allows you this + The BitBake datastore has an API that allows you this access. Here is a list of available operations: </para> diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml index aca6741c2..c4bd1f258 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml @@ -539,6 +539,17 @@ </glossdef> </glossentry> + <glossentry id='var-bb-BB_LOGCONFIG'><glossterm>BB_LOGCONFIG</glossterm> + <glossdef> + <para> + Specifies the name of a config file that contains the user + logging configuration. See + <link linkend="logging">Logging</link> for additional + information + </para> + </glossdef> + </glossentry> + <glossentry id='var-bb-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm> <glossdef> <para> @@ -1780,7 +1791,7 @@ </para> <para> - Bitbake normally issues a warning when building two + BitBake normally issues a warning when building two different recipes where each provides the same output. This scenario is usually something the user does not want. |