diff options
Diffstat (limited to 'documentation/dev-manual/building.rst')
| -rw-r--r-- | documentation/dev-manual/building.rst | 156 |
1 files changed, 2 insertions, 154 deletions
diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst index 4770a5a184..807c665f68 100644 --- a/documentation/dev-manual/building.rst +++ b/documentation/dev-manual/building.rst | |||
| @@ -113,160 +113,8 @@ The following figure and list overviews the build process: | |||
| 113 | Building Images for Multiple Targets Using Multiple Configurations | 113 | Building Images for Multiple Targets Using Multiple Configurations |
| 114 | ================================================================== | 114 | ================================================================== |
| 115 | 115 | ||
| 116 | You can use a single ``bitbake`` command to build multiple images or | 116 | See the :doc:`multiconfig` section of the Yocto Project Development Tasks |
| 117 | packages for different targets where each image or package requires a | 117 | Manual. |
| 118 | different configuration (multiple configuration builds). The builds, in | ||
| 119 | this scenario, are sometimes referred to as "multiconfigs", and this | ||
| 120 | section uses that term throughout. | ||
| 121 | |||
| 122 | This section describes how to set up for multiple configuration builds | ||
| 123 | and how to account for cross-build dependencies between the | ||
| 124 | multiconfigs. | ||
| 125 | |||
| 126 | Setting Up and Running a Multiple Configuration Build | ||
| 127 | ----------------------------------------------------- | ||
| 128 | |||
| 129 | To accomplish a multiple configuration build, you must define each | ||
| 130 | target's configuration separately using a parallel configuration file in | ||
| 131 | the :term:`Build Directory` or configuration directory within a layer, and you | ||
| 132 | must follow a required file hierarchy. Additionally, you must enable the | ||
| 133 | multiple configuration builds in your ``local.conf`` file. | ||
| 134 | |||
| 135 | Follow these steps to set up and execute multiple configuration builds: | ||
| 136 | |||
| 137 | - *Create Separate Configuration Files*: You need to create a single | ||
| 138 | configuration file for each build target (each multiconfig). | ||
| 139 | The configuration definitions are implementation dependent but often | ||
| 140 | each configuration file will define the machine and the | ||
| 141 | temporary directory BitBake uses for the build. Whether the same | ||
| 142 | temporary directory (:term:`TMPDIR`) can be shared will depend on what is | ||
| 143 | similar and what is different between the configurations. Multiple MACHINE | ||
| 144 | targets can share the same (:term:`TMPDIR`) as long as the rest of the | ||
| 145 | configuration is the same, multiple :term:`DISTRO` settings would need separate | ||
| 146 | (:term:`TMPDIR`) directories. | ||
| 147 | |||
| 148 | For example, consider a scenario with two different multiconfigs for the same | ||
| 149 | :term:`MACHINE`: "qemux86" built | ||
| 150 | for two distributions such as "poky" and "poky-lsb". In this case, | ||
| 151 | you would need to use the different :term:`TMPDIR`. | ||
| 152 | |||
| 153 | Here is an example showing the minimal statements needed in a | ||
| 154 | configuration file for a "qemux86" target whose temporary build | ||
| 155 | directory is ``tmpmultix86``:: | ||
| 156 | |||
| 157 | MACHINE = "qemux86" | ||
| 158 | TMPDIR = "${TOPDIR}/tmpmultix86" | ||
| 159 | |||
| 160 | The location for these multiconfig configuration files is specific. | ||
| 161 | They must reside in the current :term:`Build Directory` in a sub-directory of | ||
| 162 | ``conf`` named ``multiconfig`` or within a layer's ``conf`` directory | ||
| 163 | under a directory named ``multiconfig``. Here is an example that defines | ||
| 164 | two configuration files for the "x86" and "arm" multiconfigs: | ||
| 165 | |||
| 166 | .. image:: figures/multiconfig_files.png | ||
| 167 | :align: center | ||
| 168 | :width: 50% | ||
| 169 | |||
| 170 | The usual :term:`BBPATH` search path is used to locate multiconfig files in | ||
| 171 | a similar way to other conf files. | ||
| 172 | |||
| 173 | - *Add the BitBake Multi-configuration Variable to the Local | ||
| 174 | Configuration File*: Use the | ||
| 175 | :term:`BBMULTICONFIG` | ||
| 176 | variable in your ``conf/local.conf`` configuration file to specify | ||
| 177 | each multiconfig. Continuing with the example from the previous | ||
| 178 | figure, the :term:`BBMULTICONFIG` variable needs to enable two | ||
| 179 | multiconfigs: "x86" and "arm" by specifying each configuration file:: | ||
| 180 | |||
| 181 | BBMULTICONFIG = "x86 arm" | ||
| 182 | |||
| 183 | .. note:: | ||
| 184 | |||
| 185 | A "default" configuration already exists by definition. This | ||
| 186 | configuration is named: "" (i.e. empty string) and is defined by | ||
| 187 | the variables coming from your ``local.conf`` | ||
| 188 | file. Consequently, the previous example actually adds two | ||
| 189 | additional configurations to your build: "arm" and "x86" along | ||
| 190 | with "". | ||
| 191 | |||
| 192 | - *Launch BitBake*: Use the following BitBake command form to launch | ||
| 193 | the multiple configuration build:: | ||
| 194 | |||
| 195 | $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ] | ||
| 196 | |||
| 197 | For the example in this section, the following command applies:: | ||
| 198 | |||
| 199 | $ bitbake mc:x86:core-image-minimal mc:arm:core-image-sato mc::core-image-base | ||
| 200 | |||
| 201 | The previous BitBake command builds a ``core-image-minimal`` image | ||
| 202 | that is configured through the ``x86.conf`` configuration file, a | ||
| 203 | ``core-image-sato`` image that is configured through the ``arm.conf`` | ||
| 204 | configuration file and a ``core-image-base`` that is configured | ||
| 205 | through your ``local.conf`` configuration file. | ||
| 206 | |||
| 207 | .. note:: | ||
| 208 | |||
| 209 | Support for multiple configuration builds in the Yocto Project &DISTRO; | ||
| 210 | (&DISTRO_NAME;) Release does not include Shared State (sstate) | ||
| 211 | optimizations. Consequently, if a build uses the same object twice | ||
| 212 | in, for example, two different :term:`TMPDIR` | ||
| 213 | directories, the build either loads from an existing sstate cache for | ||
| 214 | that build at the start or builds the object fresh. | ||
| 215 | |||
| 216 | Enabling Multiple Configuration Build Dependencies | ||
| 217 | -------------------------------------------------- | ||
| 218 | |||
| 219 | Sometimes dependencies can exist between targets (multiconfigs) in a | ||
| 220 | multiple configuration build. For example, suppose that in order to | ||
| 221 | build a ``core-image-sato`` image for an "x86" multiconfig, the root | ||
| 222 | filesystem of an "arm" multiconfig must exist. This dependency is | ||
| 223 | essentially that the | ||
| 224 | :ref:`ref-tasks-image` task in the | ||
| 225 | ``core-image-sato`` recipe depends on the completion of the | ||
| 226 | :ref:`ref-tasks-rootfs` task of the | ||
| 227 | ``core-image-minimal`` recipe. | ||
| 228 | |||
| 229 | To enable dependencies in a multiple configuration build, you must | ||
| 230 | declare the dependencies in the recipe using the following statement | ||
| 231 | form:: | ||
| 232 | |||
| 233 | task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" | ||
| 234 | |||
| 235 | To better show how to use this statement, consider the example scenario | ||
| 236 | from the first paragraph of this section. The following statement needs | ||
| 237 | to be added to the recipe that builds the ``core-image-sato`` image:: | ||
| 238 | |||
| 239 | do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs" | ||
| 240 | |||
| 241 | In this example, the `from_multiconfig` is "x86". The `to_multiconfig` is "arm". The | ||
| 242 | task on which the :ref:`ref-tasks-image` task in the recipe depends is the | ||
| 243 | :ref:`ref-tasks-rootfs` task from the ``core-image-minimal`` recipe associated | ||
| 244 | with the "arm" multiconfig. | ||
| 245 | |||
| 246 | Once you set up this dependency, you can build the "x86" multiconfig | ||
| 247 | using a BitBake command as follows:: | ||
| 248 | |||
| 249 | $ bitbake mc:x86:core-image-sato | ||
| 250 | |||
| 251 | This command executes all the tasks needed to create the | ||
| 252 | ``core-image-sato`` image for the "x86" multiconfig. Because of the | ||
| 253 | dependency, BitBake also executes through the :ref:`ref-tasks-rootfs` task for the | ||
| 254 | "arm" multiconfig build. | ||
| 255 | |||
| 256 | Having a recipe depend on the root filesystem of another build might not | ||
| 257 | seem that useful. Consider this change to the statement in the | ||
| 258 | ``core-image-sato`` recipe:: | ||
| 259 | |||
| 260 | do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image" | ||
| 261 | |||
| 262 | In this case, BitBake must | ||
| 263 | create the ``core-image-minimal`` image for the "arm" build since the | ||
| 264 | "x86" build depends on it. | ||
| 265 | |||
| 266 | Because "x86" and "arm" are enabled for multiple configuration builds | ||
| 267 | and have separate configuration files, BitBake places the artifacts for | ||
| 268 | each build in the respective temporary build directories (i.e. | ||
| 269 | :term:`TMPDIR`). | ||
| 270 | 118 | ||
| 271 | Building an Initial RAM Filesystem (Initramfs) Image | 119 | Building an Initial RAM Filesystem (Initramfs) Image |
| 272 | ==================================================== | 120 | ==================================================== |
