summaryrefslogtreecommitdiffstats
path: root/poky/bitbake/doc
diff options
context:
space:
mode:
authorBrad Bishop <bradleyb@fuzziesquirrel.com>2018-12-16 17:11:34 -0800
committerBrad Bishop <bradleyb@fuzziesquirrel.com>2019-01-08 18:21:44 -0500
commit1a4b7ee28bf7413af6513fb45ad0d0736048f866 (patch)
tree79f6d8ea698cab8f2eaf4f54b793d2ca7a1451ce /poky/bitbake/doc
parent5b9ede0403237c7dace972affa65cf64a1aadd0e (diff)
downloadtalos-openbmc-1a4b7ee28bf7413af6513fb45ad0d0736048f866.tar.gz
talos-openbmc-1a4b7ee28bf7413af6513fb45ad0d0736048f866.zip
reset upstream subtrees to yocto 2.6
Reset the following subtrees on thud HEAD: poky: 87e3a9739d meta-openembedded: 6094ae18c8 meta-security: 31dc4e7532 meta-raspberrypi: a48743dc36 meta-xilinx: c42016e2e6 Also re-apply backports that didn't make it into thud: poky: 17726d0 systemd-systemctl-native: handle Install wildcards meta-openembedded: 4321a5d libtinyxml2: update to 7.0.1 042f0a3 libcereal: Add native and nativesdk classes e23284f libcereal: Allow empty package 030e8d4 rsyslog: curl-less build with fmhttp PACKAGECONFIG 179a1b9 gtest: update to 1.8.1 Squashed OpenBMC subtree compatibility updates: meta-aspeed: Brad Bishop (1): aspeed: add yocto 2.6 compatibility meta-ibm: Brad Bishop (1): ibm: prepare for yocto 2.6 meta-ingrasys: Brad Bishop (1): ingrasys: set layer compatibility to yocto 2.6 meta-openpower: Brad Bishop (1): openpower: set layer compatibility to yocto 2.6 meta-phosphor: Brad Bishop (3): phosphor: set layer compatibility to thud phosphor: libgpg-error: drop patches phosphor: react to fitimage artifact rename Ed Tanous (4): Dropbear: upgrade options for latest upgrade yocto2.6: update openssl options busybox: remove upstream watchdog patch systemd: Rebase CONFIG_CGROUP_BPF patch Change-Id: I7b1fe71cca880d0372a82d94b5fd785323e3a9e7 Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Diffstat (limited to 'poky/bitbake/doc')
-rw-r--r--poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml170
-rw-r--r--poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml65
-rw-r--r--poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml102
-rw-r--r--poky/bitbake/doc/bitbake-user-manual/figures/bb_multiconfig_files.pngbin0 -> 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".
+ "&nbsp;&nbsp;789 123456&nbsp;&nbsp;&nbsp;&nbsp;"
+ and <filename>FOO2</filename> becomes
+ "&nbsp;&nbsp;ghi abcdef&nbsp;&nbsp;&nbsp;&nbsp;".
</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
new file mode 100644
index 000000000..041f06403
--- /dev/null
+++ b/poky/bitbake/doc/bitbake-user-manual/figures/bb_multiconfig_files.png
Binary files differ
OpenPOWER on IntegriCloud