diff options
Diffstat (limited to 'poky/bitbake/doc/bitbake-user-manual')
6 files changed, 146 insertions, 33 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..6c5234ed9 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> @@ -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..f5526c053 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 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..10b588352 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> @@ -2616,7 +2619,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. |