diff options
Diffstat (limited to 'poky/bitbake/doc/bitbake-user-manual')
| -rw-r--r-- | poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml | 170 | ||||
| -rw-r--r-- | poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml | 65 | ||||
| -rw-r--r-- | poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml | 102 | ||||
| -rw-r--r-- | poky/bitbake/doc/bitbake-user-manual/figures/bb_multiconfig_files.png | bin | 0 -> 19991 bytes |
4 files changed, 322 insertions, 15 deletions
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 4cf0ed9d1..f7d312a32 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 @@ -342,13 +342,14 @@ <para> When you name an append file, you can use the - wildcard character (%) to allow for matching recipe names. + "<filename>%</filename>" wildcard character to allow for matching + recipe names. For example, suppose you have an append file named as follows: <literallayout class='monospaced'> busybox_1.21.%.bbappend </literallayout> - That append file would match any <filename>busybox_1.21.x.bb</filename> + That append file would match any <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename> version of the recipe. So, the append file would match the following recipe names: <literallayout class='monospaced'> @@ -356,6 +357,14 @@ busybox_1.21.2.bb busybox_1.21.3.bb </literallayout> + <note><title>Important</title> + The use of the "<filename>%</filename>" character + is limited in that it only works directly in front of the + <filename>.bbappend</filename> portion of the append file's + name. + You cannot use the wildcard character in any other + location of the name. + </note> If the <filename>busybox</filename> recipe was updated to <filename>busybox_1.3.0.bb</filename>, the append name would not match. @@ -723,6 +732,163 @@ </literallayout> </para> </section> + + <section id='executing-a-multiple-configuration-build'> + <title>Executing a Multiple Configuration Build</title> + + <para> + BitBake is able to build multiple images or packages + using a single command where the different targets + require different configurations (multiple configuration + builds). + Each target, in this scenario, is referred to as a + "multiconfig". + </para> + + <para> + To accomplish a multiple configuration build, you must + define each target's configuration separately using + a parallel configuration file in the build directory. + The location for these multiconfig configuration files + is specific. + They must reside in the current build directory in + a sub-directory of <filename>conf</filename> named + <filename>multiconfig</filename>. + Following is an example for two separate targets: + <imagedata fileref="figures/bb_multiconfig_files.png" align="center" width="4in" depth="3in" /> + </para> + + <para> + The reason for this required file hierarchy + is because the <filename>BBPATH</filename> variable + is not constructed until the layers are parsed. + Consequently, using the configuration file as a + pre-configuration file is not possible unless it is + located in the current working directory. + </para> + + <para> + Minimally, each configuration file must define the + machine and the temporary directory BitBake uses + for the build. + Suggested practice dictates that you do not + overlap the temporary directories used during the + builds. + </para> + + <para> + Aside from separate configuration files for each + target, you must also enable BitBake to perform multiple + configuration builds. + Enabling is accomplished by setting the + <link linkend='var-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></link> + variable in the <filename>local.conf</filename> + configuration file. + As an example, suppose you had configuration files + for <filename>target1</filename> and + <filename>target2</filename> defined in the build + directory. + The following statement in the + <filename>local.conf</filename> file both enables + BitBake to perform multiple configuration builds and + specifies the two multiconfigs: + <literallayout class='monospaced'> + BBMULTICONFIG = "target1 target2" + </literallayout> + </para> + + <para> + Once the target configuration files are in place and + BitBake has been enabled to perform multiple configuration + builds, use the following command form to start the + builds: + <literallayout class='monospaced'> + $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ] + </literallayout> + Here is an example for two multiconfigs: + <filename>target1</filename> and + <filename>target2</filename>: + <literallayout class='monospaced'> + $ bitbake multiconfig:target1:<replaceable>target</replaceable> multiconfig:target2:<replaceable>target</replaceable> + </literallayout> + </para> + </section> + + <section id='bb-enabling-multiple-configuration-build-dependencies'> + <title>Enabling Multiple Configuration Build Dependencies</title> + + <para> + Sometimes dependencies can exist between targets + (multiconfigs) in a multiple configuration build. + For example, suppose that in order to build an image + for a particular architecture, the root filesystem of + another build for a different architecture needs to + exist. + In other words, the image for the first multiconfig depends + on the root filesystem of the second multiconfig. + This dependency is essentially that the task in the recipe + that builds one multiconfig is dependent on the + completion of the task in the recipe that builds + another multiconfig. + </para> + + <para> + To enable dependencies in a multiple configuration + build, you must declare the dependencies in the recipe + using the following statement form: + <literallayout class='monospaced'> + <replaceable>task_or_package</replaceable>[mcdepends] = "multiconfig:<replaceable>from_multiconfig</replaceable>:<replaceable>to_multiconfig</replaceable>:<replaceable>recipe_name</replaceable>:<replaceable>task_on_which_to_depend</replaceable>" + </literallayout> + To better show how to use this statement, consider an + example with two multiconfigs: <filename>target1</filename> + and <filename>target2</filename>: + <literallayout class='monospaced'> + <replaceable>image_task</replaceable>[mcdepends] = "multiconfig:target1:target2:<replaceable>image2</replaceable>:<replaceable>rootfs_task</replaceable>" + </literallayout> + In this example, the + <replaceable>from_multiconfig</replaceable> is "target1" and + the <replaceable>to_multiconfig</replaceable> is "target2". + The task on which the image whose recipe contains + <replaceable>image_task</replaceable> depends on the + completion of the <replaceable>rootfs_task</replaceable> + used to build out <replaceable>image2</replaceable>, which + is associated with the "target2" multiconfig. + </para> + + <para> + Once you set up this dependency, you can build the + "target1" multiconfig using a BitBake command as follows: + <literallayout class='monospaced'> + $ bitbake multiconfig:target1:<replaceable>image1</replaceable> + </literallayout> + This command executes all the tasks needed to create + <replaceable>image1</replaceable> for the "target1" + multiconfig. + Because of the dependency, BitBake also executes through + the <replaceable>rootfs_task</replaceable> for the "target2" + multiconfig build. + </para> + + <para> + Having a recipe depend on the root filesystem of another + build might not seem that useful. + Consider this change to the statement in the + <replaceable>image1</replaceable> recipe: + <literallayout class='monospaced'> + <replaceable>image_task</replaceable>[mcdepends] = "multiconfig:target1:target2:<replaceable>image2</replaceable>:<replaceable>image_task</replaceable>" + </literallayout> + In this case, BitBake must create + <replaceable>image2</replaceable> for the "target2" + build since the "target1" build depends on it. + </para> + + <para> + Because "target1" and "target2" are enabled for multiple + configuration builds and have separate configuration + files, BitBake places the artifacts for each build in the + respective temporary build directories. + </para> + </section> </section> </section> </chapter> 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 b4fc64e75..2490f6e4b 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 @@ -342,7 +342,7 @@ <para> When you use this syntax, BitBake expects one or more strings. - Surrounding spaces are removed as well. + Surrounding spaces and spacing are preserved. Here is an example: <literallayout class='monospaced'> FOO = "123 456 789 123456 123 456 123 456" @@ -352,8 +352,9 @@ FOO2_remove = "abc def" </literallayout> The variable <filename>FOO</filename> becomes - "789 123456" and <filename>FOO2</filename> becomes - "ghi abcdef". + " 789 123456 " + and <filename>FOO2</filename> becomes + " ghi abcdef ". </para> <para> @@ -1929,6 +1930,38 @@ not careful. </note> </para></listitem> + <listitem><para><emphasis><filename>[number_threads]</filename>:</emphasis> + Limits tasks to a specific number of simultaneous threads + during execution. + This varflag is useful when your build host has a large number + of cores but certain tasks need to be rate-limited due to various + kinds of resource constraints (e.g. to avoid network throttling). + <filename>number_threads</filename> works similarly to the + <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> + variable but is task-specific.</para> + + <para>Set the value globally. + For example, the following makes sure the + <filename>do_fetch</filename> task uses no more than two + simultaneous execution threads: + <literallayout class='monospaced'> + do_fetch[number_threads] = "2" + </literallayout> + <note><title>Warnings</title> + <itemizedlist> + <listitem><para> + Setting the varflag in individual recipes rather + than globally can result in unpredictable behavior. + </para></listitem> + <listitem><para> + Setting the varflag to a value greater than the + value used in the <filename>BB_NUMBER_THREADS</filename> + variable causes <filename>number_threads</filename> + to have no effect. + </para></listitem> + </itemizedlist> + </note> + </para></listitem> <listitem><para><emphasis><filename>[postfuncs]</filename>:</emphasis> List of functions to call after the completion of the task. </para></listitem> @@ -2719,4 +2752,30 @@ </itemizedlist> </para> </section> + + <section id='wildcard-support-in-variables'> + <title>Wildcard Support in Variables</title> + + <para> + Support for wildcard use in variables varies depending on the + context in which it is used. + For example, some variables and file names allow limited use of + wildcards through the "<filename>%</filename>" and + "<filename>*</filename>" characters. + Other variables or names support Python's + <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink> + syntax, + <ulink url='https://docs.python.org/3/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink> + syntax, or + <ulink url='https://docs.python.org/3/library/re.html#re'><filename>Regular Expression (re)</filename></ulink> + syntax. + </para> + + <para> + For variables that have wildcard suport, the + documentation describes which form of wildcard, its + use, and its limitations. + </para> + </section> + </chapter> 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 0313359d9..a84b2bc99 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 @@ -115,7 +115,8 @@ is either not set or set to "0". </para></listitem> <listitem><para> - Limited support for wildcard matching against the + Limited support for the "<filename>*</filename>" + wildcard character for matching against the beginning of host names exists. For example, the following setting matches <filename>git.gnu.org</filename>, @@ -124,6 +125,20 @@ <literallayout class='monospaced'> BB_ALLOWED_NETWORKS = "*.gnu.org" </literallayout> + <note><title>Important</title> + <para>The use of the "<filename>*</filename>" + character only works at the beginning of + a host name and it must be isolated from + the remainder of the host name. + You cannot use the wildcard character in any + other location of the name or combined with + the front part of the name.</para> + + <para>For example, + <filename>*.foo.bar</filename> is supported, + while <filename>*aa.foo.bar</filename> is not. + </para> + </note> </para></listitem> <listitem><para> Mirrors not in the host list are skipped and @@ -646,10 +661,10 @@ <glossdef> <para> Contains the name of the currently executing task. - The value does not include the "do_" prefix. + The value includes the "do_" prefix. For example, if the currently executing task is <filename>do_config</filename>, the value is - "config". + "do_config". </para> </glossdef> </glossentry> @@ -1082,7 +1097,19 @@ <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm> <glossdef> - <para>List of recipe files BitBake uses to build software.</para> + <para> + A space-separated list of recipe files BitBake uses to + build software. + </para> + + <para> + When specifying recipe files, you can pattern match using + Python's + <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink> + syntax. + For details on the syntax, see the documentation by + following the previous link. + </para> </glossdef> </glossentry> @@ -1166,15 +1193,19 @@ match any of the expressions. It is as if BitBake does not see them at all. Consequently, matching files are not parsed or otherwise - used by BitBake.</para> + used by BitBake. + </para> + <para> The values you provide are passed to Python's regular expression compiler. + Consequently, the syntax follows Python's Regular + Expression (re) syntax. The expressions are compared against the full paths to the files. For complete syntax information, see Python's documentation at - <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>. + <ulink url='http://docs.python.org/3/library/re.html#re'></ulink>. </para> <para> @@ -1205,6 +1236,45 @@ </glossdef> </glossentry> + <glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm> + <info> + BBMULTICONFIG[doc] = "Enables BitBake to perform multiple configuration builds and lists each separate configuration (multiconfig)." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Enables BitBake to perform multiple configuration builds + and lists each separate configuration (multiconfig). + You can use this variable to cause BitBake to build + multiple targets where each target has a separate + configuration. + Define <filename>BBMULTICONFIG</filename> in your + <filename>conf/local.conf</filename> configuration file. + </para> + + <para> + As an example, the following line specifies three + multiconfigs, each having a separate configuration file: + <literallayout class='monospaced'> + BBMULTIFONFIG = "configA configB configC" + </literallayout> + Each configuration file you use must reside in the + build directory within a directory named + <filename>conf/multiconfig</filename> (e.g. + <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>). + </para> + + <para> + For information on how to use + <filename>BBMULTICONFIG</filename> in an environment that + supports building targets with multiple configurations, + see the + "<link linkend='executing-a-multiple-configuration-build'>Executing a Multiple Configuration Build</link>" + section. + </para> + </glossdef> + </glossentry> + <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> <glossdef> <para> @@ -1894,15 +1964,27 @@ you want to select, and you should set <link linkend='var-PV'><filename>PV</filename></link> accordingly for precedence. - You can use the "<filename>%</filename>" character as a - wildcard to match any number of characters, which can be - useful when specifying versions that contain long revision - numbers that could potentially change. + </para> + + <para> + The <filename>PREFERRED_VERSION</filename> variable + supports limited wildcard use through the + "<filename>%</filename>" character. + You can use the character to match any number of + characters, which can be useful when specifying versions + that contain long revision numbers that potentially change. Here are two examples: <literallayout class='monospaced'> PREFERRED_VERSION_python = "2.7.3" PREFERRED_VERSION_linux-yocto = "4.12%" </literallayout> + <note><title>Important</title> + The use of the "<filename>%</filename>" character + is limited in that it only works at the end of the + string. + You cannot use the wildcard character in any other + location of the string. + </note> </para> </glossdef> </glossentry> diff --git a/poky/bitbake/doc/bitbake-user-manual/figures/bb_multiconfig_files.png b/poky/bitbake/doc/bitbake-user-manual/figures/bb_multiconfig_files.png Binary files differnew file mode 100644 index 000000000..041f06403 --- /dev/null +++ b/poky/bitbake/doc/bitbake-user-manual/figures/bb_multiconfig_files.png |
