From f08a41e9ef681905f4642f59d62d59ade8543450 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 17 Aug 2018 12:46:47 -0700 Subject: dev-manual, Makefile: Created new section on multi-config build deps Rewrote the section on setting up and executing multi-config builds. Broke the section into two sub-sections. One is for the standard information that was there for setting up a multi-config build. A new section was for the cross-build dependencies in multi-config builds. Part of the re-write included creating a new figure that shows the configuration file hierarchy needed for these types of builds. So, new figure added to both the dev-manual and the mega-manual figures directories. Finally, the Makefile needed updated to account for the new figures. (From yocto-docs rev: dc158e97c216aa6e7fa3755164409d581f8569c5) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/Makefile | 3 +- .../dev-manual/dev-manual-common-tasks.xml | 274 ++++++++++++++------- .../dev-manual/figures/multiconfig_files.png | Bin 0 -> 18611 bytes .../mega-manual/figures/multiconfig_files.png | Bin 0 -> 18611 bytes 4 files changed, 191 insertions(+), 86 deletions(-) create mode 100644 documentation/dev-manual/figures/multiconfig_files.png create mode 100644 documentation/mega-manual/figures/multiconfig_files.png (limited to 'documentation') 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: - - $ 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 - - - - + + 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. + - - 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 + + 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] ... ] + + 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 -- cgit v1.2.3-54-g00ecf