diff --git a/documentation/Makefile b/documentation/Makefile
index e41d5a0f60..093422f69f 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -165,6 +165,7 @@ TARFILES = dev-style.css dev-manual.html \
TARFILES = dev-style.css dev-manual.html figures/buildhistory-web.png \
figures/dev-title.png figures/buildhistory.png \
figures/recipe-workflow.png figures/bitbake-build-flow.png \
+ figures/multiconfig_files.png \
eclipse
endif
@@ -261,7 +262,7 @@ TARFILES = mega-manual.html mega-style.css \
figures/image-generation.png figures/key-dev-elements.png\
figures/sdk-generation.png figures/recipe-workflow.png \
figures/build-workspace-directory.png figures/mega-title.png \
- figures/toaster-title.png figures/hosted-service.png \
+ figures/toaster-title.png figures/hosted-service.png figures/multiconfig_files.png \
figures/simple-configuration.png figures/poky-reference-distribution.png \
figures/compatible-layers.png figures/import-layer.png figures/new-project.png \
figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index ed53fb68a6..2a93ce9c2d 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5325,100 +5325,204 @@
Building Images for Multiple Targets Using Multiple Configurations
- 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 bitbake 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.
- 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
- local.conf file.
+ This section describes how to set up for multiple
+ configuration builds and how to account for cross-build
+ dependencies between the multiconfigs.
-
- Follow these guidelines to create an environment that supports
- multiple configurations:
-
-
- Create Configuration Files:
- 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:
-
- MACHINE = "A"
-
- The files would contain any other variables that can
- be set and built in the same directory.
-
- You can change the
- TMPDIR
- to not conflict.
-
+
+ Setting Up and Running a Multiple Configuration Build
-
- Furthermore, the configuration file must be located in the
- current build directory in a directory named
- multiconfig under the build's
- conf directory where
- local.conf resides.
- The reason for this restriction is because the
- BBPATH 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.
-
-
- Add the BitBake Multi-Config Variable to you Local Configuration File:
- Use the
- BBMULTICONFIG
- variable in your conf/local.conf
- configuration file to specify each separate configuration.
- For example, the following line tells BitBake it should load
- conf/multiconfig/configA.conf,
- conf/multiconfig/configB.conf, and
- conf/multiconfig/configC.conf.
-
- BBMULTICONFIG = "configA configB configC"
-
-
-
- Launch BitBake:
- Use the following BitBake command form to launch the
- build:
-
+
+ To accomplish a multiple configuration build, you must
+ define each target's configuration separately using
+ a parallel configuration file in the
+ Build Directory,
+ and you must follow a required file hierarchy.
+ Additionally, you must enable the multiple configuration
+ builds in your local.conf file.
+
+
+
+ Follow these steps to set up and execute multiple
+ configuration builds:
+
+
+ Create Separate Configuration Files:
+ 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.
+
+ Here is an example showing the minimal
+ statements needed in a configuration file for
+ a "qemux86" target whose temporary build directory
+ is tmpmultix86:
+
+ MACHINE="qemux86"
+ TMPDIR="${TOPDIR}/tmpmultix86"
+
+
+ The location for these multiconfig
+ configuration files is specific.
+ They must reside in the current build directory in
+ a sub-directory of conf named
+ multiconfig.
+ Following is an example that defines two
+ configuration files for the "x86" and "arm"
+ multiconfigs:
+
+
+
+ The reason for this required file hierarchy
+ is because the BBPATH 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.
+
+
+ Add the BitBake Multi-configuration Variable to the Local Configuration File:
+ Use the
+ BBMULTICONFIG
+ variable in your
+ conf/local.conf configuration
+ file to specify each multiconfig.
+ Continuing with the example from the previous
+ figure, the BBMULTICONFIG
+ variable needs to enable two multiconfigs: "x86"
+ and "arm" by specifying each configuration file:
+
+ BBMULTICONFIG = "x86 arm"
+
+
+
+ Launch BitBake:
+ Use the following BitBake command form to launch the
+ multiple configuration build:
+
$ bitbake [multiconfig:multiconfigname:]target [[[multiconfig:multiconfigname:]target] ... ]
-
- Following is an example that supports building a minimal
- image for configuration A alongside a standard
- core-image-sato, which takes its
- configuration from local.conf:
-
- $ bitbake multiconfig:configA:core-image-minimal core-image-sato
-
-
-
-
-
-
- Support for multiple configurations in this current release of
- the Yocto Project (&DISTRO_NAME; &DISTRO;) has some known issues:
-
-
- No inter-multi-configuration dependencies exist.
-
-
- Shared State (sstate) optimizations do not exist.
- Consequently, if the build uses the same object twice
+
+ For the example in this section, the following
+ command applies:
+
+ $ bitbake multiconfig:x86:core-image-minimal multiconfig:arm:core-image-sato
+
+ The previous BitBake command builds a
+ core-image-minimal image that
+ is configured through the
+ x86.conf configuration file
+ and builds a core-image-sato
+ image that is configured through the
+ arm.conf configuration file.
+
+
+
+ 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
TMPDIR directories, the build
- will either load from an existing sstate cache at the
- start or build the object twice.
-
-
-
+ either loads from an existing sstate cache for that
+ build at the start or builds the object fresh.
+
+
+
+
+
+ Enabling Multiple Configuration Build Dependencies
+
+
+ Sometimes dependencies can exist between targets
+ (multiconfigs) in a multiple configuration build.
+ For example, suppose that in order to build a
+ core-image-sato image for an "x86"
+ multiconfig, the root filesystem of an "arm"
+ multiconfig must exist.
+ This dependency is essentially that the
+ do_image
+ task in the core-image-sato recipe
+ depends on the completion of the
+ do_rootfs
+ task of the core-image-minimal
+ recipe.
+
+
+
+ To enable dependencies in a multiple configuration
+ build, you must declare the dependencies in the recipe
+ using the following statement form:
+
+ task_or_package[mcdepends] = "multiconfig:from_multiconfig:to_multiconfig:recipe_name:task_or_package_on_which_to_depend"
+
+
+ Dependencies can be on tasks or packages.
+
+ 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 core-image-sato
+ image:
+
+ do_image[mcdepends] = "multiconfig:x86:arm:core-image-minimal:do_rootfs"
+
+ In this example, the
+ from_multiconfig is "x86".
+ The to_multiconfig is "arm".
+ The task on which the do_image task
+ in the recipe depends is the do_rootfs
+ task from the core-image-minimal
+ recipe associated with the "arm" multiconfig.
+
+
+
+ Once you set up this dependency, you can build the
+ "x86" multiconfig using a BitBake command as follows:
+
+ $ bitbake multiconfig:x86:core-image-sato
+
+ This command executes all the tasks needed to create
+ the core-image-sato image for the
+ "x86" multiconfig.
+ Because of the dependency, BitBake also executes through
+ the do_rootfs task for the "arm"
+ multiconfig build.
+
+
+
+ Having a recipe depend on the root filesystem of another
+ build might not seem that useful.
+ Consider this change to the statement in the
+ core-image-sato recipe:
+
+ do_image[mcdepends] = "multiconfig:x86:arm:core-image-minimal:do_image"
+
+ In this case, BitBake must create the
+ core-image-minimal image for the
+ "arm" build since the "x86" build depends on it.
+
+
+
+ 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.
+ TMPDIR.
+
+
diff --git a/documentation/dev-manual/figures/multiconfig_files.png b/documentation/dev-manual/figures/multiconfig_files.png
new file mode 100644
index 0000000000..0b59338b3a
Binary files /dev/null and b/documentation/dev-manual/figures/multiconfig_files.png differ
diff --git a/documentation/mega-manual/figures/multiconfig_files.png b/documentation/mega-manual/figures/multiconfig_files.png
new file mode 100644
index 0000000000..0b59338b3a
Binary files /dev/null and b/documentation/mega-manual/figures/multiconfig_files.png differ