diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 87f14a046e..a710efe6d5 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5973,6 +5973,180 @@ Gateways via their Web Interfaces"
+
+ Building Images for More than One Machine
+
+
+ A common scenario developers face is creating images for several
+ different machines that use the same software environment.
+ In this situation, it is tempting to set the
+ tunings and optimization flags for each build specifically for
+ the targeted hardware (i.e. "maxing out" the tunings).
+ Doing so can considerably add to build times and package feed
+ maintenance collectively for the machines.
+ For example, selecting tunes that are extremely specific to a
+ CPU core used in a system might enable some micro optimizations
+ in GCC for that particular system but would otherwise not gain
+ you much of a performance difference across the other systems
+ as compared to using a more general tuning across all the builds.
+ Another example is setting
+ DEFAULTTUNE
+ specifically for each machine's build.
+ Rather than "max out" each build's tunings, you can take steps that
+ cause the OpenEmbedded build system to reuse software across the
+ various machines where it makes sense.
+
+
+ If build speed and package feed maintenance are considerations,
+ you should consider the points in this section that can help you
+ optimize your tunings to best consider build times and package
+ feed maintenance.
+
+ Share the Build Directory:
+ If at all possible, share the
+ TMPDIR
+ across builds.
+ The Yocto Project supports switching between different
+ MACHINE
+ values in the same TMPDIR.
+ This practice is well supported and regularly used by
+ developers when building for multiple machines.
+ When you use the same TMPDIR for
+ multiple machine builds, the OpenEmbedded build system can
+ reuse the existing native and often cross-recipes for
+ multiple machines.
+ Thus, build time decreases.
+
+ If
+ DISTRO
+ settings change or fundamental configuration settings
+ such as the filesystem layout, you need to work with
+ a clean TMPDIR.
+ Sharing TMPDIR under these
+ circumstances might work but since it is not
+ guaranteed, you should use a clean
+ TMPDIR.
+
+
+ Enable the Appropriate Package Architecture:
+ By default, the OpenEmbedded build system enables three
+ levels of package architectures: "all", "tune" or "package",
+ and "machine".
+ Any given recipe usually selects one of these package
+ architectures (types) for its output.
+ Depending for what a given recipe creates packages, making
+ sure you enable the appropriate package architecture can
+ directly impact the build time.
+ A recipe that just generates scripts can enable
+ "all" architecture because there are no binaries to build.
+ To specifically enable "all" architecture, be sure your
+ recipe inherits the
+ allarch
+ class.
+ This class is useful for "all" architectures because it
+ contains many other variables that can be used across
+ multiple architectures.
+ If your recipe needs to generate packages that are
+ machine-specific or when one of the build or runtime
+ dependencies is already machine-architecture dependent,
+ which makes your recipe also machine-architecture dependent,
+ make sure your recipe enables the "machine" package
+ architecture through the
+ MACHINE_ARCH
+ variable:
+
+ PACKAGE_ARCH = "${MACHINE_ARCH}"
+
+ If you select a specific tuning for the recipe,
+ the OpenEmbedded build system enables the package
+ architecture defined by that tuning file.
+ When you do not specifically enable a package
+ architecture through the
+ PACKAGE_ARCH,
+ The OpenEmbedded build system defaults to the
+ TUNE_ARCH
+ setting:
+
+ PACKAGE_ARCH == TUNE_ARCH
+
+
+ Choose a Generic Tuning File if Possible:
+ Some tunes are more generic and can run on multiple targets
+ (e.g. an armv5 set of packages could
+ run on armv6 and
+ armv7 processors in most cases).
+ Similarly, i486 binaries could work
+ on i586 and higher processors.
+ If you select the same tune for several different
+ machines, the OpenEmbedded build system reuses software
+ previously built, thus speeding up the overall build time.
+ Realize that even though a new sysroot for each machine is
+ generated, the software is not recompiled and only one
+ package feed exists.
+
+ Manage Granular Level Packaging:
+ Sometimes cases exist where where injecting another level
+ of package architecture beyond the three higher levels
+ noted earlier can be useful.
+ For example, consider the emgd
+ graphics stack in the
+ meta-intel layer.
+ In this layer, a subset of software exists that is
+ compiled against something different from the rest of the
+ generic packages.
+ You can examine the key code in the
+ Source Repositories
+ in classes/emgd-gl.bbclass.
+ For a specific set of packages, the code redefines
+ PACKAGE_ARCH.
+ PACKAGE_EXTRA_ARCHS
+ is then appended with this extra tune name in
+ meta-intel-emgd.inc.
+ The result is that when searching for packages, the
+ build system uses a four-level search and the packages
+ in this new level are preferred as compared to the standard
+ tune.
+ The overall result is that the build system reuses most
+ software from the common tune except for specific cases
+ as needed.
+
+ Use Tools to Debug Issues:
+ Sometimes you can run into situations where software is
+ being rebuilt when you think it should not be.
+ For example, the OpenEmbedded build system might not be
+ using shared state between machines when you think it
+ should be.
+ These types of situations are usually due to references
+ to variables such as MACHINE
+ in code that is supposed to only be "tune" specific.
+
+ Patches to fix any issues identified are most welcome
+ as these issues occasionally do occur.
+
+ For such cases, you can use some tools to help you
+ sort out the situation:
+
+ sstate-diff-machines.sh:
+ You can find this tool in the
+ scripts directory of the
+ Source Repositories.
+ See the comments in the script for information on
+ how to use the tool.
+
+ BitBake's "-S printdiff" Option:
+ Using this option causes BitBake to try to
+ establish the closest signature match it can
+ (e.g. in the shared state cache) and then run
+ bitbake-diffsigs over the
+ matches to determine the stamps and delta where
+ these two stamp trees diverge.
+
+
+
+
+
+
+