summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-08-17 12:46:47 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-08-28 10:30:43 +0100
commitf08a41e9ef681905f4642f59d62d59ade8543450 (patch)
tree306a42ab58a03554c2ba1a3b51c447024f46544e /documentation/dev-manual
parent48b17b2bfe489d68ffd1bf18e0eda6314bb94019 (diff)
downloadpoky-f08a41e9ef681905f4642f59d62d59ade8543450.tar.gz
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 <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml274
-rw-r--r--documentation/dev-manual/figures/multiconfig_files.pngbin0 -> 18611 bytes
2 files changed, 189 insertions, 85 deletions
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 @@
5325 <title>Building Images for Multiple Targets Using Multiple Configurations</title> 5325 <title>Building Images for Multiple Targets Using Multiple Configurations</title>
5326 5326
5327 <para> 5327 <para>
5328 Bitbake also has functionality that allows you to build 5328 You can use a single <filename>bitbake</filename> command
5329 multiple targets at the same time, where each target uses 5329 to build multiple images for different targets where each
5330 a different configuration. 5330 image requires a different configuration (multiple
5331 configuration builds).
5332 The builds, in this scenario, are sometimes referred to as
5333 "multiconfigs", and this section uses that term throughout.
5331 </para> 5334 </para>
5332 5335
5333 <para> 5336 <para>
5334 In order to accomplish this, you setup each of the configurations 5337 This section describes how to set up for multiple
5335 you need to use in parallel by placing the configuration files in 5338 configuration builds and how to account for cross-build
5336 your current build directory alongside the usual 5339 dependencies between the multiconfigs.
5337 <filename>local.conf</filename> file.
5338 </para> 5340 </para>
5339 5341
5340 <para> 5342 <section id='dev-setting-up-and-running-a-multiple-configuration-build'>
5341 Follow these guidelines to create an environment that supports 5343 <title>Setting Up and Running a Multiple Configuration Build</title>
5342 multiple configurations:
5343 <itemizedlist>
5344 <listitem><para>
5345 <emphasis>Create Configuration Files</emphasis>:
5346 You need to create a single configuration file for each
5347 configuration for which you want to add support.
5348 These files would contain lines such as the following:
5349 <literallayout class='monospaced'>
5350 MACHINE = "A"
5351 </literallayout>
5352 The files would contain any other variables that can
5353 be set and built in the same directory.
5354 <note>
5355 You can change the
5356 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
5357 to not conflict.
5358 </note></para>
5359 5344
5360 <para> 5345 <para>
5361 Furthermore, the configuration file must be located in the 5346 To accomplish a multiple configuration build, you must
5362 current build directory in a directory named 5347 define each target's configuration separately using
5363 <filename>multiconfig</filename> under the build's 5348 a parallel configuration file in the
5364 <filename>conf</filename> directory where 5349 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
5365 <filename>local.conf</filename> resides. 5350 and you must follow a required file hierarchy.
5366 The reason for this restriction is because the 5351 Additionally, you must enable the multiple configuration
5367 <filename>BBPATH</filename> variable is not constructed 5352 builds in your <filename>local.conf</filename> file.
5368 until the layers are parsed. 5353 </para>
5369 Consequently, using the configuration file as a
5370 pre-configuration file is not possible unless it is
5371 located in the current working directory.
5372 </para></listitem>
5373 <listitem><para>
5374 <emphasis>Add the BitBake Multi-Config Variable to you Local Configuration File</emphasis>:
5375 Use the
5376 <filename>BBMULTICONFIG</filename>
5377 variable in your <filename>conf/local.conf</filename>
5378 configuration file to specify each separate configuration.
5379 For example, the following line tells BitBake it should load
5380 <filename>conf/multiconfig/configA.conf</filename>,
5381 <filename>conf/multiconfig/configB.conf</filename>, and
5382 <filename>conf/multiconfig/configC.conf</filename>.
5383 <literallayout class='monospaced'>
5384 BBMULTICONFIG = "configA configB configC"
5385 </literallayout>
5386 </para></listitem>
5387 <listitem><para>
5388 <emphasis>Launch BitBake</emphasis>:
5389 Use the following BitBake command form to launch the
5390 build:
5391 <literallayout class='monospaced'>
5392 $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
5393 </literallayout>
5394 Following is an example that supports building a minimal
5395 image for configuration A alongside a standard
5396 <filename>core-image-sato</filename>, which takes its
5397 configuration from <filename>local.conf</filename>:
5398 <literallayout class='monospaced'>
5399 $ bitbake multiconfig:configA:core-image-minimal core-image-sato
5400 </literallayout>
5401 </para></listitem>
5402 </itemizedlist>
5403 </para>
5404 5354
5405 <para> 5355 <para>
5406 Support for multiple configurations in this current release of 5356 Follow these steps to set up and execute multiple
5407 the Yocto Project (&DISTRO_NAME; &DISTRO;) has some known issues: 5357 configuration builds:
5408 <itemizedlist> 5358 <itemizedlist>
5409 <listitem><para> 5359 <listitem><para>
5410 No inter-multi-configuration dependencies exist. 5360 <emphasis>Create Separate Configuration Files</emphasis>:
5411 </para></listitem> 5361 You need to create a single configuration file for
5412 <listitem><para> 5362 each build target (each multiconfig).
5413 Shared State (sstate) optimizations do not exist. 5363 Minimally, each configuration file must define the
5414 Consequently, if the build uses the same object twice 5364 machine and the temporary directory BitBake uses
5365 for the build.
5366 You must not overlap the temporary directories
5367 used during the build.</para>
5368
5369 <para>Here is an example showing the minimal
5370 statements needed in a configuration file for
5371 a "qemux86" target whose temporary build directory
5372 is <filename>tmpmultix86</filename>:
5373 <literallayout class='monospaced'>
5374 MACHINE="qemux86"
5375 TMPDIR="${TOPDIR}/tmpmultix86"
5376 </literallayout></para>
5377
5378 <para>The location for these multiconfig
5379 configuration files is specific.
5380 They must reside in the current build directory in
5381 a sub-directory of <filename>conf</filename> named
5382 <filename>multiconfig</filename>.
5383 Following is an example that defines two
5384 configuration files for the "x86" and "arm"
5385 multiconfigs:
5386 <imagedata fileref="figures/multiconfig_files.png" align="center" width="4in" depth="3in" />
5387 </para>
5388
5389 <para>The reason for this required file hierarchy
5390 is because the <filename>BBPATH</filename> variable
5391 is not constructed until the layers are parsed.
5392 Consequently, using the configuration file as a
5393 pre-configuration file is not possible unless it is
5394 located in the current working directory.
5395 </para></listitem>
5396 <listitem><para>
5397 <emphasis>Add the BitBake Multi-configuration Variable to the Local Configuration File</emphasis>:
5398 Use the
5399 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></ulink>
5400 variable in your
5401 <filename>conf/local.conf</filename> configuration
5402 file to specify each multiconfig.
5403 Continuing with the example from the previous
5404 figure, the <filename>BBMULTICONFIG</filename>
5405 variable needs to enable two multiconfigs: "x86"
5406 and "arm" by specifying each configuration file:
5407 <literallayout class='monospaced'>
5408 BBMULTICONFIG = "x86 arm"
5409 </literallayout>
5410 </para></listitem>
5411 <listitem><para>
5412 <emphasis>Launch BitBake</emphasis>:
5413 Use the following BitBake command form to launch the
5414 multiple configuration build:
5415 <literallayout class='monospaced'>
5416 $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
5417 </literallayout>
5418 For the example in this section, the following
5419 command applies:
5420 <literallayout class='monospaced'>
5421 $ bitbake multiconfig:x86:core-image-minimal multiconfig:arm:core-image-sato
5422 </literallayout>
5423 The previous BitBake command builds a
5424 <filename>core-image-minimal</filename> image that
5425 is configured through the
5426 <filename>x86.conf</filename> configuration file
5427 and builds a <filename>core-image-sato</filename>
5428 image that is configured through the
5429 <filename>arm.conf</filename> configuration file.
5430 </para></listitem>
5431 </itemizedlist>
5432 <note>
5433 Support for multiple configuration builds in the
5434 Yocto Project &DISTRO; (&DISTRO_NAME;) Release does
5435 not include Shared State (sstate) optimizations.
5436 Consequently, if a build uses the same object twice
5415 in, for example, two different 5437 in, for example, two different
5416 <filename>TMPDIR</filename> directories, the build 5438 <filename>TMPDIR</filename> directories, the build
5417 will either load from an existing sstate cache at the 5439 either loads from an existing sstate cache for that
5418 start or build the object twice. 5440 build at the start or builds the object fresh.
5419 </para></listitem> 5441 </note>
5420 </itemizedlist> 5442 </para>
5421 </para> 5443 </section>
5444
5445 <section id='dev-enabling-multiple-configuration-build-dependencies'>
5446 <title>Enabling Multiple Configuration Build Dependencies</title>
5447
5448 <para>
5449 Sometimes dependencies can exist between targets
5450 (multiconfigs) in a multiple configuration build.
5451 For example, suppose that in order to build a
5452 <filename>core-image-sato</filename> image for an "x86"
5453 multiconfig, the root filesystem of an "arm"
5454 multiconfig must exist.
5455 This dependency is essentially that the
5456 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image</filename></ulink>
5457 task in the <filename>core-image-sato</filename> recipe
5458 depends on the completion of the
5459 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>
5460 task of the <filename>core-image-minimal</filename>
5461 recipe.
5462 </para>
5463
5464 <para>
5465 To enable dependencies in a multiple configuration
5466 build, you must declare the dependencies in the recipe
5467 using the following statement form:
5468 <literallayout class='monospaced'>
5469 <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>"
5470 </literallayout>
5471 <note>
5472 Dependencies can be on tasks or packages.
5473 </note>
5474 To better show how to use this statement, consider the
5475 example scenario from the first paragraph of this section.
5476 The following statement needs to be added to the recipe
5477 that builds the <filename>core-image-sato</filename>
5478 image:
5479 <literallayout class='monospaced'>
5480 do_image[mcdepends] = "multiconfig:x86:arm:core-image-minimal:do_rootfs"
5481 </literallayout>
5482 In this example, the
5483 <replaceable>from_multiconfig</replaceable> is "x86".
5484 The <replaceable>to_multiconfig</replaceable> is "arm".
5485 The task on which the <filename>do_image</filename> task
5486 in the recipe depends is the <filename>do_rootfs</filename>
5487 task from the <filename>core-image-minimal</filename>
5488 recipe associated with the "arm" multiconfig.
5489 </para>
5490
5491 <para>
5492 Once you set up this dependency, you can build the
5493 "x86" multiconfig using a BitBake command as follows:
5494 <literallayout class='monospaced'>
5495 $ bitbake multiconfig:x86:core-image-sato
5496 </literallayout>
5497 This command executes all the tasks needed to create
5498 the <filename>core-image-sato</filename> image for the
5499 "x86" multiconfig.
5500 Because of the dependency, BitBake also executes through
5501 the <filename>do_rootfs</filename> task for the "arm"
5502 multiconfig build.
5503 </para>
5504
5505 <para>
5506 Having a recipe depend on the root filesystem of another
5507 build might not seem that useful.
5508 Consider this change to the statement in the
5509 <filename>core-image-sato</filename> recipe:
5510 <literallayout class='monospaced'>
5511 do_image[mcdepends] = "multiconfig:x86:arm:core-image-minimal:do_image"
5512 </literallayout>
5513 In this case, BitBake must create the
5514 <filename>core-image-minimal</filename> image for the
5515 "arm" build since the "x86" build depends on it.
5516 </para>
5517
5518 <para>
5519 Because "x86" and "arm" are enabled for multiple
5520 configuration builds and have separate configuration
5521 files, BitBake places the artifacts for each build in the
5522 respective temporary build directories (i.e.
5523 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
5524 </para>
5525 </section>
5422 </section> 5526 </section>
5423 5527
5424 <section id='building-an-initramfs-image'> 5528 <section id='building-an-initramfs-image'>
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
--- /dev/null
+++ b/documentation/dev-manual/figures/multiconfig_files.png
Binary files differ