diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index c781286df3..9f993d21e3 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml | |||
@@ -5163,6 +5163,171 @@ | |||
5163 | </para> | 5163 | </para> |
5164 | </section> | 5164 | </section> |
5165 | 5165 | ||
5166 | <section id='dev-building'> | ||
5167 | <title>Building</title> | ||
5168 | |||
5169 | <para> | ||
5170 | This section describes various build procedures. | ||
5171 | For example, the steps needed for a simple build, a target that | ||
5172 | uses multiple configurations, building an image for more than | ||
5173 | one machine, and so forth. | ||
5174 | </para> | ||
5175 | |||
5176 | <section id='dev-building-a-simple-image'> | ||
5177 | <title>Building a Simple Image</title> | ||
5178 | |||
5179 | <para> | ||
5180 | In the development environment, you need to build an image | ||
5181 | whenever you change hardware support, add or change system | ||
5182 | libraries, or add or change services that have dependencies. | ||
5183 | Several methods exist that allow you to build an image within | ||
5184 | the Yocto Project. | ||
5185 | This section presents the basic steps you need to build a | ||
5186 | simple image using BitBake from a build host running Linux. | ||
5187 | <note><title>Notes</title> | ||
5188 | <itemizedlist> | ||
5189 | <listitem><para> | ||
5190 | For information on how to build an image using | ||
5191 | <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>, | ||
5192 | see the | ||
5193 | <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>. | ||
5194 | </para></listitem> | ||
5195 | <listitem><para> | ||
5196 | For information on how to use | ||
5197 | <filename>devtool</filename> to build images, see | ||
5198 | the | ||
5199 | "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow</ulink>" | ||
5200 | section in the Yocto Project Application | ||
5201 | Development and the Extensible Software Development | ||
5202 | Kit (eSDK) manual. | ||
5203 | </para></listitem> | ||
5204 | <listitem><para> | ||
5205 | For a quick example on how to build an image using | ||
5206 | the OpenEmbedded build system, see the | ||
5207 | <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink> | ||
5208 | document. | ||
5209 | </para></listitem> | ||
5210 | </itemizedlist> | ||
5211 | </note> | ||
5212 | </para> | ||
5213 | |||
5214 | <para> | ||
5215 | The build process creates an entire Linux distribution from | ||
5216 | source and places it in your | ||
5217 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> | ||
5218 | under <filename>tmp/deploy/images</filename>. | ||
5219 | For detailed information on the build process using BitBake, | ||
5220 | see the | ||
5221 | "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>" | ||
5222 | section in the Yocto Project Overview and Concepts Manual. | ||
5223 | </para> | ||
5224 | |||
5225 | <para> | ||
5226 | The following figure and list overviews the build process: | ||
5227 | <imagedata fileref="figures/bitbake-build-flow.png" width="7in" depth="4in" align="center" scalefit="1" /> | ||
5228 | <orderedlist> | ||
5229 | <listitem><para> | ||
5230 | <emphasis>Set up Your Host Development System to Support | ||
5231 | Development Using the Yocto Project</emphasis>: | ||
5232 | See the | ||
5233 | "<link linkend='dev-manual-start'>Setting Up to Use the Yocto Project</link>" | ||
5234 | section for options on how to get a build host ready to | ||
5235 | use the Yocto Project. | ||
5236 | </para></listitem> | ||
5237 | <listitem><para> | ||
5238 | <emphasis>Initialize the Build Environment:</emphasis> | ||
5239 | Initialize the build environment by sourcing the build | ||
5240 | environment script (i.e. | ||
5241 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>): | ||
5242 | <literallayout class='monospaced'> | ||
5243 | $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>] | ||
5244 | </literallayout></para> | ||
5245 | |||
5246 | <para>When you use the initialization script, the | ||
5247 | OpenEmbedded build system uses | ||
5248 | <filename>build</filename> as the default Build | ||
5249 | Directory in your current work directory. | ||
5250 | You can use a <replaceable>build_dir</replaceable> | ||
5251 | argument with the script to specify a different build | ||
5252 | directory. | ||
5253 | <note><title>Tip</title> | ||
5254 | A common practice is to use a different Build | ||
5255 | Directory for different targets. | ||
5256 | For example, <filename>~/build/x86</filename> for a | ||
5257 | <filename>qemux86</filename> target, and | ||
5258 | <filename>~/build/arm</filename> for a | ||
5259 | <filename>qemuarm</filename> target. | ||
5260 | </note> | ||
5261 | </para></listitem> | ||
5262 | <listitem><para> | ||
5263 | <emphasis>Make Sure Your <filename>local.conf</filename> | ||
5264 | File is Correct:</emphasis> | ||
5265 | Ensure the <filename>conf/local.conf</filename> | ||
5266 | configuration file, which is found in the Build | ||
5267 | Directory, is set up how you want it. | ||
5268 | This file defines many aspects of the build environment | ||
5269 | including the target machine architecture through the | ||
5270 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable, | ||
5271 | the packaging format used during the build | ||
5272 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>), | ||
5273 | and a centralized tarball download directory through the | ||
5274 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> variable. | ||
5275 | </para></listitem> | ||
5276 | <listitem><para> | ||
5277 | <emphasis>Build the Image:</emphasis> | ||
5278 | Build the image using the <filename>bitbake</filename> | ||
5279 | command: | ||
5280 | <literallayout class='monospaced'> | ||
5281 | $ bitbake <replaceable>target</replaceable> | ||
5282 | </literallayout> | ||
5283 | <note> | ||
5284 | For information on BitBake, see the | ||
5285 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
5286 | </note> | ||
5287 | The <replaceable>target</replaceable> is the name of the | ||
5288 | recipe you want to build. | ||
5289 | Common targets are the images in | ||
5290 | <filename>meta/recipes-core/images</filename>, | ||
5291 | <filename>meta/recipes-sato/images</filename>, and so | ||
5292 | forth all found in the | ||
5293 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. | ||
5294 | Or, the target can be the name of a recipe for a | ||
5295 | specific piece of software such as BusyBox. | ||
5296 | For more details about the images the OpenEmbedded build | ||
5297 | system supports, see the | ||
5298 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | ||
5299 | chapter in the Yocto Project Reference Manual.</para> | ||
5300 | |||
5301 | <para>As an example, the following command builds the | ||
5302 | <filename>core-image-minimal</filename> image: | ||
5303 | <literallayout class='monospaced'> | ||
5304 | $ bitbake core-image-minimal | ||
5305 | </literallayout> | ||
5306 | Once an image has been built, it often needs to be | ||
5307 | installed. | ||
5308 | The images and kernels built by the OpenEmbedded | ||
5309 | build system are placed in the Build Directory in | ||
5310 | <filename class="directory">tmp/deploy/images</filename>. | ||
5311 | For information on how to run pre-built images such as | ||
5312 | <filename>qemux86</filename> and <filename>qemuarm</filename>, | ||
5313 | see the | ||
5314 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | ||
5315 | manual. | ||
5316 | For information about how to install these images, | ||
5317 | see the documentation for your particular board or | ||
5318 | machine. | ||
5319 | </para></listitem> | ||
5320 | </orderedlist> | ||
5321 | </para> | ||
5322 | </section> | ||
5323 | </section> | ||
5324 | |||
5325 | |||
5326 | |||
5327 | |||
5328 | |||
5329 | |||
5330 | |||
5166 | <section id='platdev-building-targets-with-multiple-configurations'> | 5331 | <section id='platdev-building-targets-with-multiple-configurations'> |
5167 | <title>Building Targets with Multiple Configurations</title> | 5332 | <title>Building Targets with Multiple Configurations</title> |
5168 | 5333 | ||