summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-05-16 14:23:23 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-05-24 17:16:35 +0100
commitcbda3472e371c24a38d1e7b49cd718fffd6ddb25 (patch)
tree2dbc3f81219c6cbece89ead0576b0b95d6a61a26 /documentation/dev-manual
parentcd9affa63523fa4077b426b08fb340d20972ac8e (diff)
downloadpoky-cbda3472e371c24a38d1e7b49cd718fffd6ddb25.tar.gz
dev-manual: Moved the "Simple Build" section
I had a section on building an image up in chapter that talks about getting set up to use YP. I moved the build section to a new parent section that will hold topics on building various things. I renamed the section to "Building a Simple Image". I had to fix several links in the sdk-manual, overview-manual, and dev-manual. (From yocto-docs rev: c119fc7c6148e7b08acad374fe2981842e9462a3) 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.xml165
-rw-r--r--documentation/dev-manual/dev-manual-start.xml140
2 files changed, 165 insertions, 140 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
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index a1b502b8eb..201cbe7340 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -1080,146 +1080,6 @@
1080 </section> 1080 </section>
1081</section> 1081</section>
1082 1082
1083<section id='dev-building-an-image'>
1084 <title>Building an Image</title>
1085
1086 <para>
1087 In the development environment, you need to build an image whenever
1088 you change hardware support, add or change system libraries, or add
1089 or change services that have dependencies.
1090 Several methods exist that allow you to build an image within the
1091 Yocto Project.
1092 This section shows you how to build an image using BitBake from a
1093 Linux host.
1094 <note><title>Notes</title>
1095 <itemizedlist>
1096 <listitem><para>
1097 For information on how to build an image using
1098 <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>,
1099 see the
1100 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
1101 </para></listitem>
1102 <listitem><para>
1103 For information on how to use
1104 <filename>devtool</filename> to build images, see the
1105 "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow</ulink>"
1106 section in the Yocto Project Application Development and
1107 the Extensible Software Development Kit (eSDK) manual.
1108 </para></listitem>
1109 <listitem><para>
1110 For a quick example on how to build an image using the
1111 OpenEmbedded build system, see the
1112 <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
1113 document.
1114 </para></listitem>
1115 </itemizedlist>
1116 </note>
1117 </para>
1118
1119 <para>
1120 The build process creates an entire Linux distribution from source
1121 and places it in your
1122 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
1123 under <filename>tmp/deploy/images</filename>.
1124 For detailed information on the build process using BitBake, see the
1125 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
1126 section in the Yocto Project Overview and Concepts Manual.
1127 </para>
1128
1129 <para>
1130 The following figure and list overviews the build process:
1131 <imagedata fileref="figures/bitbake-build-flow.png" width="7in" depth="4in" align="center" scalefit="1" />
1132 <orderedlist>
1133 <listitem><para>
1134 <emphasis>Set up Your Host Development System to Support
1135 Development Using the Yocto Project</emphasis>:
1136 See the
1137 "<link linkend='dev-manual-start'>Setting Up to Use the Yocto Project</link>"
1138 section for options on how to get a build host ready to use
1139 the Yocto Project.
1140 </para></listitem>
1141 <listitem><para>
1142 <emphasis>Initialize the Build Environment:</emphasis>
1143 Initialize the build environment by sourcing the build
1144 environment script (i.e.
1145 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>):
1146 <literallayout class='monospaced'>
1147 $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>]
1148 </literallayout></para>
1149
1150 <para>When you use the initialization script, the
1151 OpenEmbedded build system uses <filename>build</filename> as
1152 the default Build Directory in your current work directory.
1153 You can use a <replaceable>build_dir</replaceable> argument
1154 with the script to specify a different build directory.
1155 <note><title>Tip</title>
1156 A common practice is to use a different Build Directory for
1157 different targets.
1158 For example, <filename>~/build/x86</filename> for a
1159 <filename>qemux86</filename> target, and
1160 <filename>~/build/arm</filename> for a
1161 <filename>qemuarm</filename> target.
1162 </note>
1163 </para></listitem>
1164 <listitem><para>
1165 <emphasis>Make Sure Your <filename>local.conf</filename>
1166 File is Correct:</emphasis>
1167 Ensure the <filename>conf/local.conf</filename> configuration
1168 file, which is found in the Build Directory,
1169 is set up how you want it.
1170 This file defines many aspects of the build environment
1171 including the target machine architecture through the
1172 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
1173 the packaging format used during the build
1174 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>),
1175 and a centralized tarball download directory through the
1176 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> variable.
1177 </para></listitem>
1178 <listitem><para>
1179 <emphasis>Build the Image:</emphasis>
1180 Build the image using the <filename>bitbake</filename> command:
1181 <literallayout class='monospaced'>
1182 $ bitbake <replaceable>target</replaceable>
1183 </literallayout>
1184 <note>
1185 For information on BitBake, see the
1186 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
1187 </note>
1188 The <replaceable>target</replaceable> is the name of the
1189 recipe you want to build.
1190 Common targets are the images in
1191 <filename>meta/recipes-core/images</filename>,
1192 <filename>meta/recipes-sato/images</filename>, etc. all found
1193 in the
1194 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
1195 Or, the target can be the name of a recipe for a specific
1196 piece of software such as BusyBox.
1197 For more details about the images the OpenEmbedded build
1198 system supports, see the
1199 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1200 chapter in the Yocto Project Reference Manual.</para>
1201
1202 <para>As an example, the following command builds the
1203 <filename>core-image-minimal</filename> image:
1204 <literallayout class='monospaced'>
1205 $ bitbake core-image-minimal
1206 </literallayout>
1207 Once an image has been built, it often needs to be installed.
1208 The images and kernels built by the OpenEmbedded build system
1209 are placed in the Build Directory in
1210 <filename class="directory">tmp/deploy/images</filename>.
1211 For information on how to run pre-built images such as
1212 <filename>qemux86</filename> and <filename>qemuarm</filename>,
1213 see the
1214 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
1215 manual.
1216 For information about how to install these images, see the
1217 documentation for your particular board or machine.
1218 </para></listitem>
1219 </orderedlist>
1220 </para>
1221</section>
1222
1223<section id='speeding-up-the-build'> 1083<section id='speeding-up-the-build'>
1224 <title>Speeding Up the Build</title> 1084 <title>Speeding Up the Build</title>
1225 1085
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-10 17:31:18 +0000