summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-newbie.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-02-08 17:05:44 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-03-08 12:07:54 -0800
commit7b5215b8869f5953d2892872d90f333c3c5ab5e4 (patch)
tree5fb84e48595844655244ffb07390b0614d9089e0 /documentation/dev-manual/dev-manual-newbie.xml
parent1e608088cd902cb7b726d918d67c2879294c2e74 (diff)
downloadpoky-7b5215b8869f5953d2892872d90f333c3c5ab5e4.tar.gz
documentation/dev-manual/dev-manual-newbie.xml: edits to build dir term
I beefed up the definition for the term "Yocto Project Build Directory." I included the TOPDIR role and also expanded the discussion on how it is created and the control the user has over it. (From yocto-docs rev: d00f30708ccd5fb9e1fc3c8e5240e0ab7a892fe0) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-newbie.xml')
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml236
1 files changed, 125 insertions, 111 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 05dccc9745..6017ae9ede 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -130,106 +130,104 @@
130 Following is a list of terms and definitions users new to the Yocto Project development 130 Following is a list of terms and definitions users new to the Yocto Project development
131 environment might find helpful. 131 environment might find helpful.
132 While some of these terms are universal, the list includes them just in case: 132 While some of these terms are universal, the list includes them just in case:
133 <itemizedlist> 133 <itemizedlist>
134 <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to 134 <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
135 a recipe file. 135 a recipe file.
136 Information in append files overrides the information in the similarly-named recipe file. 136 Information in append files overrides the information in the similarly-named recipe file.
137 Append files use the <filename>.bbappend</filename> filename suffix.</para></listitem> 137 Append files use the <filename>.bbappend</filename> filename suffix.
138 <listitem><para><emphasis>BitBake:</emphasis> The task executor and scheduler used by 138 </para></listitem>
139 the Yocto Project to build images. 139 <listitem><para><emphasis>BitBake:</emphasis> The task executor and scheduler used by
140 For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'> 140 the Yocto Project to build images.
141 BitBake documentation</ulink>.</para></listitem> 141 For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'>
142 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation 142 BitBake documentation</ulink>.</para></listitem>
143 and inheritance allowing commonly used patterns to be defined once and easily used 143 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
144 in multiple recipes. 144 and inheritance allowing commonly used patterns to be defined once and easily used
145 Class files end with the <filename>.bbclass</filename> filename extension.</para></listitem> 145 in multiple recipes.
146 <listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various 146 Class files end with the <filename>.bbclass</filename> filename extension.
147 <filename>.conf</filename> files provides global definitions of variables. 147 </para></listitem>
148 The <filename>conf/local.conf</filename> configuration file in the Yocto Project 148 <listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various
149 build directory contains user-defined variables that affect each build. 149 <filename>.conf</filename> files provides global definitions of variables.
150 The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file 150 The <filename>conf/local.conf</filename> configuration file in the Yocto Project
151 defines Yocto ‘distro’ configuration 151 build directory contains user-defined variables that affect each build.
152 variables used only when building with this policy. 152 The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file
153 Machine configuration files, which 153 defines Yocto ‘distro’ configuration
154 are located throughout the Yocto Project file structure, define 154 variables used only when building with this policy.
155 variables for specific hardware and are only used when building for that target 155 Machine configuration files, which
156 (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines 156 are located throughout the Yocto Project file structure, define
157 variables for the Texas Instruments ARM Cortex-A8 development board). 157 variables for specific hardware and are only used when building for that target
158 Configuration files end with a <filename>.conf</filename> filename extension.</para></listitem> 158 (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines
159 <listitem><para><emphasis>Cross-Development Toolchain:</emphasis> A collection of software development 159 variables for the Texas Instruments ARM Cortex-A8 development board).
160 tools and utilities that allow you to develop software for targeted architectures. 160 Configuration files end with a <filename>.conf</filename> filename extension.
161 This toolchain contains cross-compilers, linkers, and debuggers that are specific to 161 </para></listitem>
162 an architecture. 162 <listitem><para><emphasis>Cross-Development Toolchain:</emphasis>
163 You can use the Yocto Project to build cross-development toolchains in tarball form that when 163 A collection of software development
164 unpacked contain the development tools you need to cross-compile and test your software. 164 tools and utilities that allow you to develop software for targeted architectures.
165 The Yocto Project ships with images that contain toolchains for supported architectures 165 This toolchain contains cross-compilers, linkers, and debuggers that are specific to
166 as well. 166 an architecture.
167 Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem> 167 You can use the Yocto Project to build cross-development toolchains in tarball form that when
168 <listitem><para><emphasis>Image:</emphasis> An image is the result produced when 168 unpacked contain the development tools you need to cross-compile and test your software.
169 BitBake processes a given collection of recipes and related metadata. 169 The Yocto Project ships with images that contain toolchains for supported architectures
170 Images are the binary output that runs on specific hardware and for specific 170 as well.
171 use cases. 171 Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem>
172 For a list of the supported image types that the Yocto Project provides, see the 172 <listitem><para><emphasis>Image:</emphasis> An image is the result produced when
173 "<ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>" 173 BitBake processes a given collection of recipes and related metadata.
174 appendix in The Yocto Project Reference Manual.</para></listitem> 174 Images are the binary output that runs on specific hardware and for specific
175 <listitem><para><emphasis>Layer:</emphasis> A collection of recipes representing the core, 175 use cases.
176 a BSP, or an application stack.</para></listitem> 176 For a list of the supported image types that the Yocto Project provides, see the
177 <listitem><para><emphasis>Metadata:</emphasis> The files that BitBake parses when building an image. 177 "<ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>"
178 Metadata includes recipes, classes, and configuration files.</para></listitem> 178 appendix in The Yocto Project Reference Manual.</para></listitem>
179 <listitem><para><emphasis>OE-Core:</emphasis> A core set of metadata originating 179 <listitem><para><emphasis>Layer:</emphasis> A collection of recipes representing the core,
180 with OpenEmbedded (OE) that is shared between OE and the Yocto Project. 180 a BSP, or an application stack.</para></listitem>
181 This metadata is found in the <filename>meta</filename> directory of the Yocto Project 181 <listitem><para><emphasis>Metadata:</emphasis> The files that BitBake parses when building an image.
182 files.</para></listitem> 182 Metadata includes recipes, classes, and configuration files.</para></listitem>
183 <listitem><para><emphasis>Package:</emphasis> The packaged output from a baked recipe. 183 <listitem><para><emphasis>OE-Core:</emphasis> A core set of metadata originating
184 A package is generally the compiled binaries produced from the recipe's sources. 184 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
185 You ‘bake’ something by running it through BitBake.</para></listitem> 185 This metadata is found in the <filename>meta</filename> directory of the Yocto Project
186 <listitem><para><emphasis>Poky:</emphasis> The build tool that the Yocto Project 186 files.</para></listitem>
187 uses to create images.</para></listitem> 187 <listitem><para><emphasis>Package:</emphasis> The packaged output from a baked recipe.
188 <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages. 188 A package is generally the compiled binaries produced from the recipe's sources.
189 A recipe describes where you get source code and which patches to apply. 189 You ‘bake’ something by running it through BitBake.</para></listitem>
190 Recipes describe dependencies for libraries or for other recipes, and they 190 <listitem><para><emphasis>Poky:</emphasis> The build tool that the Yocto Project
191 also contain configuration and compilation options. 191 uses to create images.</para></listitem>
192 Recipes contain the logical unit of execution, the software/images to build, and 192 <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages.
193 use the <filename>.bb</filename> file extension.</para></listitem> 193 A recipe describes where you get source code and which patches to apply.
194 <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes. 194 Recipes describe dependencies for libraries or for other recipes, and they
195 You simply use Tasks to hold recipes that, when built, usually accomplish a single task. 195 also contain configuration and compilation options.
196 For example, a task could contain the recipes for a company’s proprietary or value-add software. 196 Recipes contain the logical unit of execution, the software/images to build, and
197 Or, the task could contain the recipes that enable graphics. 197 use the <filename>.bb</filename> file extension.</para></listitem>
198 A task is really just another recipe. 198 <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes.
199 Because task files are recipes, they end with the <filename>.bb</filename> filename 199 You simply use Tasks to hold recipes that, when built, usually accomplish a single task.
200 extension.</para></listitem> 200 For example, a task could contain the recipes for a company’s proprietary or value-add software.
201 <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories 201 Or, the task could contain the recipes that enable graphics.
202 that are not local to the development system but located in a master area that is controlled 202 A task is really just another recipe.
203 by the maintainer of the source code. 203 Because task files are recipes, they end with the <filename>.bb</filename> filename
204 For example, in order for a developer to work on a particular piece of code, they need to 204 extension.</para></listitem>
205 first get a copy of it from an "upstream" source.</para></listitem> 205 <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
206 <listitem> 206 that are not local to the development system but located in a master area that is controlled
207 <para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis> 207 by the maintainer of the source code.
208 For example, in order for a developer to work on a particular piece of code, they need to
209 first get a copy of it from an "upstream" source.</para></listitem>
210 <listitem>
211 <para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis>
208 This term refers to the directory structure created as a result of either downloading 212 This term refers to the directory structure created as a result of either downloading
209 and unpacking a Yocto Project release tarball or setting up a Git repository 213 and unpacking a Yocto Project release tarball or setting up a Git repository
210 by cloning <filename>git://git.yoctoproject.org/poky</filename>. 214 by cloning <filename>git://git.yoctoproject.org/poky</filename>.
211 Sometimes the term "the Yocto Project Files structure" is used as well. 215 Sometimes the term "the Yocto Project Files structure" is used as well.</para>
212 </para>
213 216
214 <para> 217 <para>The Yocto Project files contain BitBake, Documentation, metadata and
215 The Yocto Project files contain BitBake, Documentation, metadata and
216 other files that all support the development environment. 218 other files that all support the development environment.
217 Consequently, you must have the Yocto Project files in place on your development 219 Consequently, you must have the Yocto Project files in place on your development
218 system in order to do any development using the Yocto Project. 220 system in order to do any development using the Yocto Project.</para>
219 </para>
220 221
221 <para> 222 <para>The name of the top-level directory of the Yocto Project file structure
222 The name of the top-level directory of the Yocto Project file structure
223 is derived from the Yocto Project release tarball. 223 is derived from the Yocto Project release tarball.
224 For example, downloading and unpacking <filename>poky-edison-6.0.tar.bz2</filename> 224 For example, downloading and unpacking <filename>poky-edison-6.0.tar.bz2</filename>
225 results in a Yocto Project file structure whose Yocto Project source directory is named 225 results in a Yocto Project file structure whose Yocto Project source directory is named
226 <filename>poky-edison-6.0</filename>. 226 <filename>poky-edison-6.0</filename>.
227 If you create a Git repository, then you can name the repository anything you like. 227 If you create a Git repository, then you can name the repository anything you like.
228 By default, your local Git repository is named <filename>poky</filename>. 228 By default, your local Git repository is named <filename>poky</filename>.</para>
229 </para>
230 229
231 <para> 230 <para>It is important to understand the differences between Yocto Project Files created
232 It is important to understand the differences between Yocto Project Files created
233 by unpacking a release tarball as compared to cloning 231 by unpacking a release tarball as compared to cloning
234 <filename>git://git.yoctoproject.org/poky</filename>. 232 <filename>git://git.yoctoproject.org/poky</filename>.
235 When you unpack a tarball, you have an exact copy of the files based on the time of 233 When you unpack a tarball, you have an exact copy of the files based on the time of
@@ -237,7 +235,9 @@
237 Any changes you make to your local Yocto Project files are on top of the release. 235 Any changes you make to your local Yocto Project files are on top of the release.
238 On the other hand, when you clone the Yocto Project Git repository, you have an 236 On the other hand, when you clone the Yocto Project Git repository, you have an
239 active development repository. 237 active development repository.
240 In this case, any local changes you make to the Yocto Project can be later applied to active 238 creates a build directory named <filename>YP-6.0</filename>
239 in your home directory within the directory <filename>mybuilds</filename>.
240 If <filename>mybuilds</filename> does not exist it is created for you. In this case, any local changes you make to the Yocto Project can be later applied to active
241 development branches of the upstream Yocto Project Git repository. 241 development branches of the upstream Yocto Project Git repository.
242 If you want to track a set of local changes while starting from the same point 242 If you want to track a set of local changes while starting from the same point
243 as a release tarball, you can create a local Git branch that 243 as a release tarball, you can create a local Git branch that
@@ -245,34 +245,48 @@
245 You do this using Git tags that are part of the repository. 245 You do this using Git tags that are part of the repository.
246 For more information on concepts, see the section 246 For more information on concepts, see the section
247 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>". 247 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>".
248 </para> 248 </para>
249 249
250 <para> 250 <para>You can find instruction on how to set up the Yocto Project files on your
251 You can find instruction on how to set up the Yocto Project files on your
252 host development system by reading 251 host development system by reading
253 the 252 the
254 "<ulink url='http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#getting-setup'>Getting 253 "<ulink url='http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#getting-setup'>Getting
255 Setup</ulink>" section. 254 Setup</ulink>" section.</para></listitem>
256 </para> 255 <listitem>
257 </listitem> 256 <para id='yocto-project-build-directory'><emphasis>Yocto Project Build Directory:</emphasis>
258 <listitem><para id='yocto-project-build-directory'><emphasis>Yocto Project Build Directory:</emphasis> 257 This term refers to the area used by the Yocto Project for builds.
259 This term refers to the area used by the Yocto Project for builds. 258 The area is created when you <filename>source</filename> the Yocto Project setup
260 The area is created when you <filename>source</filename> the Yocto Project setup 259 environment script that is found in the Yocto Project files area
261 environment script that is found in the Yocto Project files area. 260 (i.e. <filename>oe-init-build-env</filename>).
262 (e.g. <filename>oe-init-build-env</filename>). 261 The <filename>TOPDIR</filename> variable points to the build directory.</para>
263 You can create the Yocto Project build directory anywhere you want on your 262
264 development system. 263 <para>You have a lot of flexibility when creating the Yocto Project Build Directory.
265 Here is an example that creates the directory in <filename>mybuilds</filename> 264 Following are some examples that show how to create the directory:
266 and names the Yocto Project build directory <filename>YP-6.0</filename>: 265 <itemizedlist>
267 <literallayout class='monospaced'> 266 <listitem><para>Create the build directory in your current working directory
267 and name it <filename>build</filename>.
268 This is the default behavior.
269 <literallayout class='monospaced'>
270 $ cd ~/poky
271 $ source oe-init-build-env
272 </literallayout></para></listitem>
273 <listitem><para>Provide a directory path and specifically name the build
274 directory.
275 This next example creates a build directory named <filename>YP-6.0</filename>
276 in your home directory within the directory <filename>mybuilds</filename>.
277 If <filename>mybuilds</filename> does not exist, the directory is created for you:
278 <literallayout class='monospaced'>
268 $ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/YP-6.0 279 $ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/YP-6.0
269 </literallayout> 280 </literallayout></para></listitem>
270 If you don't specifically name the directory, BitBake creates it 281 <listitem><para>Provide an existing directory to use as the build directory.
271 in the current directory and uses the name <filename>build</filename>. 282 This example uses the existing <filename>mybuilds</filename> directory
272 Also, if you supply an existing directory, then BitBake uses that 283 as the build directory.
273 directory as the Yocto Project build directory and populates the build hierarchy 284 <literallayout class='monospaced'>
274 beneath it.</para></listitem> 285 $ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/
275 </itemizedlist> 286 </literallayout></para></listitem>
287 </itemizedlist>
288 </para></listitem>
289 </itemizedlist>
276 </para> 290 </para>
277</section> 291</section>
278 292