<title>Building Images for Multiple Targets Using Multiple Configurations</title>
<para>
- Bitbake also has functionality that allows you to build
- multiple targets at the same time, where each target uses
- a different configuration.
+ You can use a single <filename>bitbake</filename> command
+ to build multiple images for different targets where each
+ image requires a different configuration (multiple
+ configuration builds).
+ The builds, in this scenario, are sometimes referred to as
+ "multiconfigs", and this section uses that term throughout.
</para>
<para>
- In order to accomplish this, you setup each of the configurations
- you need to use in parallel by placing the configuration files in
- your current build directory alongside the usual
- <filename>local.conf</filename> file.
+ This section describes how to set up for multiple
+ configuration builds and how to account for cross-build
+ dependencies between the multiconfigs.
</para>
- <para>
- Follow these guidelines to create an environment that supports
- multiple configurations:
- <itemizedlist>
- <listitem><para>
- <emphasis>Create Configuration Files</emphasis>:
- You need to create a single configuration file for each
- configuration for which you want to add support.
- These files would contain lines such as the following:
- <literallayout class='monospaced'>
- MACHINE = "A"
- </literallayout>
- The files would contain any other variables that can
- be set and built in the same directory.
- <note>
- You can change the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
- to not conflict.
- </note></para>
+ <section id='dev-setting-up-and-running-a-multiple-configuration-build'>
+ <title>Setting Up and Running a Multiple Configuration Build</title>
- <para>
- Furthermore, the configuration file must be located in the
- current build directory in a directory named
- <filename>multiconfig</filename> under the build's
- <filename>conf</filename> directory where
- <filename>local.conf</filename> resides.
- The reason for this restriction 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></listitem>
- <listitem><para>
- <emphasis>Add the BitBake Multi-Config Variable to you Local Configuration File</emphasis>:
- Use the
- <filename>BBMULTICONFIG</filename>
- variable in your <filename>conf/local.conf</filename>
- configuration file to specify each separate configuration.
- For example, the following line tells BitBake it should load
- <filename>conf/multiconfig/configA.conf</filename>,
- <filename>conf/multiconfig/configB.conf</filename>, and
- <filename>conf/multiconfig/configC.conf</filename>.
- <literallayout class='monospaced'>
- BBMULTICONFIG = "configA configB configC"
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Launch BitBake</emphasis>:
- Use the following BitBake command form to launch the
- build:
- <literallayout class='monospaced'>
- $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
- </literallayout>
- Following is an example that supports building a minimal
- image for configuration A alongside a standard
- <filename>core-image-sato</filename>, which takes its
- configuration from <filename>local.conf</filename>:
- <literallayout class='monospaced'>
- $ bitbake multiconfig:configA:core-image-minimal core-image-sato
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para>
+ <para>
+ To accomplish a multiple configuration build, you must
+ define each target's configuration separately using
+ a parallel configuration file in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+ and you must follow a required file hierarchy.
+ Additionally, you must enable the multiple configuration
+ builds in your <filename>local.conf</filename> file.
+ </para>
- <para>
- Support for multiple configurations in this current release of
- the Yocto Project (&DISTRO_NAME; &DISTRO;) has some known issues:
- <itemizedlist>
- <listitem><para>
- No inter-multi-configuration dependencies exist.
- </para></listitem>
- <listitem><para>
- Shared State (sstate) optimizations do not exist.
- Consequently, if the build uses the same object twice
+ <para>
+ Follow these steps to set up and execute multiple
+ configuration builds:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Create Separate Configuration Files</emphasis>:
+ You need to create a single configuration file for
+ each build target (each multiconfig).
+ Minimally, each configuration file must define the
+ machine and the temporary directory BitBake uses
+ for the build.
+ You must not overlap the temporary directories
+ used during the build.</para>
+
+ <para>Here is an example showing the minimal
+ statements needed in a configuration file for
+ a "qemux86" target whose temporary build directory
+ is <filename>tmpmultix86</filename>:
+ <literallayout class='monospaced'>
+ MACHINE="qemux86"
+ TMPDIR="${TOPDIR}/tmpmultix86"
+ </literallayout></para>
+
+ <para>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 that defines two
+ configuration files for the "x86" and "arm"
+ multiconfigs:
+ <imagedata fileref="figures/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></listitem>
+ <listitem><para>
+ <emphasis>Add the BitBake Multi-configuration Variable to the Local Configuration File</emphasis>:
+ Use the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></ulink>
+ variable in your
+ <filename>conf/local.conf</filename> configuration
+ file to specify each multiconfig.
+ Continuing with the example from the previous
+ figure, the <filename>BBMULTICONFIG</filename>
+ variable needs to enable two multiconfigs: "x86"
+ and "arm" by specifying each configuration file:
+ <literallayout class='monospaced'>
+ BBMULTICONFIG = "x86 arm"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Launch BitBake</emphasis>:
+ Use the following BitBake command form to launch the
+ multiple configuration build:
+ <literallayout class='monospaced'>
+ $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
+ </literallayout>
+ For the example in this section, the following
+ command applies:
+ <literallayout class='monospaced'>
+ $ bitbake multiconfig:x86:core-image-minimal multiconfig:arm:core-image-sato
+ </literallayout>
+ The previous BitBake command builds a
+ <filename>core-image-minimal</filename> image that
+ is configured through the
+ <filename>x86.conf</filename> configuration file
+ and builds a <filename>core-image-sato</filename>
+ image that is configured through the
+ <filename>arm.conf</filename> configuration file.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ Support for multiple configuration builds in the
+ Yocto Project &DISTRO; (&DISTRO_NAME;) Release does
+ not include Shared State (sstate) optimizations.
+ Consequently, if a build uses the same object twice
in, for example, two different
<filename>TMPDIR</filename> directories, the build
- will either load from an existing sstate cache at the
- start or build the object twice.
- </para></listitem>
- </itemizedlist>
- </para>
+ either loads from an existing sstate cache for that
+ build at the start or builds the object fresh.
+ </note>
+ </para>
+ </section>
+
+ <section id='dev-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 a
+ <filename>core-image-sato</filename> image for an "x86"
+ multiconfig, the root filesystem of an "arm"
+ multiconfig must exist.
+ This dependency is essentially that the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image</filename></ulink>
+ task in the <filename>core-image-sato</filename> recipe
+ depends on the completion of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>
+ task of the <filename>core-image-minimal</filename>
+ recipe.
+ </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_or_package_on_which_to_depend</replaceable>"
+ </literallayout>
+ <note>
+ Dependencies can be on tasks or packages.
+ </note>
+ To better show how to use this statement, consider the
+ example scenario from the first paragraph of this section.
+ The following statement needs to be added to the recipe
+ that builds the <filename>core-image-sato</filename>
+ image:
+ <literallayout class='monospaced'>
+ do_image[mcdepends] = "multiconfig:x86:arm:core-image-minimal:do_rootfs"
+ </literallayout>
+ In this example, the
+ <replaceable>from_multiconfig</replaceable> is "x86".
+ The <replaceable>to_multiconfig</replaceable> is "arm".
+ The task on which the <filename>do_image</filename> task
+ in the recipe depends is the <filename>do_rootfs</filename>
+ task from the <filename>core-image-minimal</filename>
+ recipe associated with the "arm" multiconfig.
+ </para>
+
+ <para>
+ Once you set up this dependency, you can build the
+ "x86" multiconfig using a BitBake command as follows:
+ <literallayout class='monospaced'>
+ $ bitbake multiconfig:x86:core-image-sato
+ </literallayout>
+ This command executes all the tasks needed to create
+ the <filename>core-image-sato</filename> image for the
+ "x86" multiconfig.
+ Because of the dependency, BitBake also executes through
+ the <filename>do_rootfs</filename> task for the "arm"
+ 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
+ <filename>core-image-sato</filename> recipe:
+ <literallayout class='monospaced'>
+ do_image[mcdepends] = "multiconfig:x86:arm:core-image-minimal:do_image"
+ </literallayout>
+ In this case, BitBake must create the
+ <filename>core-image-minimal</filename> image for the
+ "arm" build since the "x86" build depends on it.
+ </para>
+
+ <para>
+ Because "x86" and "arm" are enabled for multiple
+ configuration builds and have separate configuration
+ files, BitBake places the artifacts for each build in the
+ respective temporary build directories (i.e.
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
+ </para>
+ </section>
</section>
<section id='building-an-initramfs-image'>
projects / thirdparty / openembedded / openembedded-core-contrib.git / commitdiff
