From 7b5215b8869f5953d2892872d90f333c3c5ab5e4 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 8 Feb 2012 17:05:44 -0600 Subject: 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 Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-newbie.xml | 236 +++++++++++++------------ 1 file changed, 125 insertions(+), 111 deletions(-) (limited to 'documentation/dev-manual') 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 @@ Following is a list of terms and definitions users new to the Yocto Project development environment might find helpful. While some of these terms are universal, the list includes them just in case: - - Append Files: Files that append build information to - a recipe file. - Information in append files overrides the information in the similarly-named recipe file. - Append files use the .bbappend filename suffix. - BitBake: The task executor and scheduler used by - the Yocto Project to build images. - For more information on BitBake, see the - BitBake documentation. - Classes: Files that provide for logic encapsulation - and inheritance allowing commonly used patterns to be defined once and easily used - in multiple recipes. - Class files end with the .bbclass filename extension. - Configuration File: Configuration information in various - .conf files provides global definitions of variables. - The conf/local.conf configuration file in the Yocto Project - build directory contains user-defined variables that affect each build. - The meta-yocto/conf/distro/poky.conf configuration file - defines Yocto ‘distro’ configuration - variables used only when building with this policy. - Machine configuration files, which - are located throughout the Yocto Project file structure, define - variables for specific hardware and are only used when building for that target - (e.g. the machine/beagleboard.conf configuration file defines - variables for the Texas Instruments ARM Cortex-A8 development board). - Configuration files end with a .conf filename extension. - Cross-Development Toolchain: A collection of software development - tools and utilities that allow you to develop software for targeted architectures. - This toolchain contains cross-compilers, linkers, and debuggers that are specific to - an architecture. - You can use the Yocto Project to build cross-development toolchains in tarball form that when - unpacked contain the development tools you need to cross-compile and test your software. - The Yocto Project ships with images that contain toolchains for supported architectures - as well. - Sometimes this toolchain is referred to as the meta-toolchain. - Image: An image is the result produced when - BitBake processes a given collection of recipes and related metadata. - Images are the binary output that runs on specific hardware and for specific - use cases. - For a list of the supported image types that the Yocto Project provides, see the - "Reference: Images" - appendix in The Yocto Project Reference Manual. - Layer: A collection of recipes representing the core, - a BSP, or an application stack. - Metadata: The files that BitBake parses when building an image. - Metadata includes recipes, classes, and configuration files. - OE-Core: A core set of metadata originating - with OpenEmbedded (OE) that is shared between OE and the Yocto Project. - This metadata is found in the meta directory of the Yocto Project - files. - Package: The packaged output from a baked recipe. - A package is generally the compiled binaries produced from the recipe's sources. - You ‘bake’ something by running it through BitBake. - Poky: The build tool that the Yocto Project - uses to create images. - Recipe: A set of instructions for building packages. - A recipe describes where you get source code and which patches to apply. - Recipes describe dependencies for libraries or for other recipes, and they - also contain configuration and compilation options. - Recipes contain the logical unit of execution, the software/images to build, and - use the .bb file extension. - Tasks: Arbitrary groups of software Recipes. - You simply use Tasks to hold recipes that, when built, usually accomplish a single task. - For example, a task could contain the recipes for a company’s proprietary or value-add software. - Or, the task could contain the recipes that enable graphics. - A task is really just another recipe. - Because task files are recipes, they end with the .bb filename - extension. - Upstream: A reference to source code or repositories - that are not local to the development system but located in a master area that is controlled - by the maintainer of the source code. - For example, in order for a developer to work on a particular piece of code, they need to - first get a copy of it from an "upstream" source. - - Yocto Project Files: + + Append Files: Files that append build information to + a recipe file. + Information in append files overrides the information in the similarly-named recipe file. + Append files use the .bbappend filename suffix. + + BitBake: The task executor and scheduler used by + the Yocto Project to build images. + For more information on BitBake, see the + BitBake documentation. + Classes: Files that provide for logic encapsulation + and inheritance allowing commonly used patterns to be defined once and easily used + in multiple recipes. + Class files end with the .bbclass filename extension. + + Configuration File: Configuration information in various + .conf files provides global definitions of variables. + The conf/local.conf configuration file in the Yocto Project + build directory contains user-defined variables that affect each build. + The meta-yocto/conf/distro/poky.conf configuration file + defines Yocto ‘distro’ configuration + variables used only when building with this policy. + Machine configuration files, which + are located throughout the Yocto Project file structure, define + variables for specific hardware and are only used when building for that target + (e.g. the machine/beagleboard.conf configuration file defines + variables for the Texas Instruments ARM Cortex-A8 development board). + Configuration files end with a .conf filename extension. + + Cross-Development Toolchain: + A collection of software development + tools and utilities that allow you to develop software for targeted architectures. + This toolchain contains cross-compilers, linkers, and debuggers that are specific to + an architecture. + You can use the Yocto Project to build cross-development toolchains in tarball form that when + unpacked contain the development tools you need to cross-compile and test your software. + The Yocto Project ships with images that contain toolchains for supported architectures + as well. + Sometimes this toolchain is referred to as the meta-toolchain. + Image: An image is the result produced when + BitBake processes a given collection of recipes and related metadata. + Images are the binary output that runs on specific hardware and for specific + use cases. + For a list of the supported image types that the Yocto Project provides, see the + "Reference: Images" + appendix in The Yocto Project Reference Manual. + Layer: A collection of recipes representing the core, + a BSP, or an application stack. + Metadata: The files that BitBake parses when building an image. + Metadata includes recipes, classes, and configuration files. + OE-Core: A core set of metadata originating + with OpenEmbedded (OE) that is shared between OE and the Yocto Project. + This metadata is found in the meta directory of the Yocto Project + files. + Package: The packaged output from a baked recipe. + A package is generally the compiled binaries produced from the recipe's sources. + You ‘bake’ something by running it through BitBake. + Poky: The build tool that the Yocto Project + uses to create images. + Recipe: A set of instructions for building packages. + A recipe describes where you get source code and which patches to apply. + Recipes describe dependencies for libraries or for other recipes, and they + also contain configuration and compilation options. + Recipes contain the logical unit of execution, the software/images to build, and + use the .bb file extension. + Tasks: Arbitrary groups of software Recipes. + You simply use Tasks to hold recipes that, when built, usually accomplish a single task. + For example, a task could contain the recipes for a company’s proprietary or value-add software. + Or, the task could contain the recipes that enable graphics. + A task is really just another recipe. + Because task files are recipes, they end with the .bb filename + extension. + Upstream: A reference to source code or repositories + that are not local to the development system but located in a master area that is controlled + by the maintainer of the source code. + For example, in order for a developer to work on a particular piece of code, they need to + first get a copy of it from an "upstream" source. + + Yocto Project Files: This term refers to the directory structure created as a result of either downloading and unpacking a Yocto Project release tarball or setting up a Git repository by cloning git://git.yoctoproject.org/poky. - Sometimes the term "the Yocto Project Files structure" is used as well. - + Sometimes the term "the Yocto Project Files structure" is used as well. - - The Yocto Project files contain BitBake, Documentation, metadata and + The Yocto Project files contain BitBake, Documentation, metadata and other files that all support the development environment. Consequently, you must have the Yocto Project files in place on your development - system in order to do any development using the Yocto Project. - + system in order to do any development using the Yocto Project. - - The name of the top-level directory of the Yocto Project file structure + The name of the top-level directory of the Yocto Project file structure is derived from the Yocto Project release tarball. For example, downloading and unpacking poky-edison-6.0.tar.bz2 results in a Yocto Project file structure whose Yocto Project source directory is named poky-edison-6.0. If you create a Git repository, then you can name the repository anything you like. - By default, your local Git repository is named poky. - + By default, your local Git repository is named poky. - - It is important to understand the differences between Yocto Project Files created + It is important to understand the differences between Yocto Project Files created by unpacking a release tarball as compared to cloning git://git.yoctoproject.org/poky. When you unpack a tarball, you have an exact copy of the files based on the time of @@ -237,7 +235,9 @@ Any changes you make to your local Yocto Project files are on top of the release. On the other hand, when you clone the Yocto Project Git repository, you have an active development repository. - In this case, any local changes you make to the Yocto Project can be later applied to active + creates a build directory named YP-6.0 + in your home directory within the directory mybuilds. + If mybuilds 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 development branches of the upstream Yocto Project Git repository. If you want to track a set of local changes while starting from the same point as a release tarball, you can create a local Git branch that @@ -245,34 +245,48 @@ You do this using Git tags that are part of the repository. For more information on concepts, see the section "Repositories, Tags, and Branches". - + - - You can find instruction on how to set up the Yocto Project files on your + You can find instruction on how to set up the Yocto Project files on your host development system by reading the "Getting - Setup" section. - - - Yocto Project Build Directory: - This term refers to the area used by the Yocto Project for builds. - The area is created when you source the Yocto Project setup - environment script that is found in the Yocto Project files area. - (e.g. oe-init-build-env). - You can create the Yocto Project build directory anywhere you want on your - development system. - Here is an example that creates the directory in mybuilds - and names the Yocto Project build directory YP-6.0: - + Setup" section. + + Yocto Project Build Directory: + This term refers to the area used by the Yocto Project for builds. + The area is created when you source the Yocto Project setup + environment script that is found in the Yocto Project files area + (i.e. oe-init-build-env). + The TOPDIR variable points to the build directory. + + You have a lot of flexibility when creating the Yocto Project Build Directory. + Following are some examples that show how to create the directory: + + Create the build directory in your current working directory + and name it build. + This is the default behavior. + + $ cd ~/poky + $ source oe-init-build-env + + Provide a directory path and specifically name the build + directory. + This next example creates a build directory named YP-6.0 + in your home directory within the directory mybuilds. + If mybuilds does not exist, the directory is created for you: + $ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/YP-6.0 - - If you don't specifically name the directory, BitBake creates it - in the current directory and uses the name build. - Also, if you supply an existing directory, then BitBake uses that - directory as the Yocto Project build directory and populates the build hierarchy - beneath it. - + + Provide an existing directory to use as the build directory. + This example uses the existing mybuilds directory + as the build directory. + + $ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/ + + + + -- cgit v1.2.3-54-g00ecf