From be3c73bc02da6f1bb2698a5d8ddee1c4fdd0ba58 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 22 Oct 2012 13:16:49 -0700 Subject: documentation: dev-manual - Final changes before 1.3 lockdown. Made minor changes as needed due to some new sections, links, and capitalization standards. (From yocto-docs rev: bc966e5a78dadd14ecf1896a36e40a9b256bae77) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 32 ++++++------- documentation/dev-manual/dev-manual-model.xml | 35 ++++++++------- documentation/dev-manual/dev-manual-newbie.xml | 52 ++++++++++++---------- documentation/dev-manual/dev-manual-start.xml | 31 ++++++------- 4 files changed, 79 insertions(+), 71 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 20742ad539..b909305f68 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -208,7 +208,7 @@ To enable your layer, simply add your layer's path to the BBLAYERS variable in your conf/bblayers.conf file, which is found in the - build directory. + Build Directory. The following example shows how to enable a layer named meta-mylayer: LCONF_VERSION = "6" @@ -315,7 +315,7 @@ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - PRINC := "${@int(PRINC) + 1}" + PRINC := "${@int(PRINC) + 2}" This example adds or overrides files in SRC_URI @@ -581,7 +581,7 @@ You can also add more features by configuring the EXTRA_IMAGE_FEATURES variable in the local.conf file found in the Source Directory - located in the build directory. + located in the Build Directory. @@ -1240,7 +1240,7 @@ combination of multiple libraries you want to build. You accomplish this through your local.conf configuration file in the - build directory. + Build Directory. An example configuration would be as follows: MACHINE = "qemux86-64" @@ -1285,7 +1285,7 @@ A unique architecture is defined for the Multilib packages, along with creating a unique deploy folder under tmp/deploy/rpm in the - build directory. + Build Directory. For example, consider lib32 in a qemux86-64 image. The possible architectures in the system are "all", "qemux86_64", @@ -1407,7 +1407,7 @@ Saving the selections updates the .config configuration file. This is the file that the OpenEmbedded build system uses to configure the kernel during the build. - You can find and examine this file in the build directory in + You can find and examine this file in the Build Directory in tmp/work/. The actual .config is located in the area where the specific kernel is built. @@ -1463,7 +1463,7 @@ placed where the OpenEmbedded build system can find and apply them. Syntactically, the configuration statement is identical to what would appear in the .config file, which is in the - build directory in + Build Directory in tmp/work/<arch>-poky-linux/linux-yocto-<release-specific-string>/linux-<arch>-<build-type>. @@ -1801,7 +1801,7 @@ Build for the Correct Target Architecture: Your selected MACHINE - definition within the local.conf file in the build directory + definition within the local.conf file in the Build Directory specifies the target architecture used when building the Linux kernel. By default, MACHINE is set to qemux86, which specifies a 32-bit @@ -1847,12 +1847,12 @@ Clean up: Be sure to clean the shared state out by running the - cleansstate BitBake task as follows from your build directory: + cleansstate BitBake task as follows from your Build Directory: $ bitbake -c cleansstate linux-yocto Never remove any files by hand from the tmp/deploy - directory inside the build directory. + directory inside the Build Directory. Always use the various BitBake clean tasks to clear out previous build artifacts. @@ -2022,7 +2022,7 @@ By default, the OpenEmbedded build system does its work from within the - build directory. + Build Directory. The build process involves fetching the source files, unpacking them, and then patching them if necessary before the build takes place. @@ -2058,17 +2058,17 @@ It is important to know that the externalsrc.bbclass assumes that the - source directory S and the build directory + source directory S and the Build Directory B are different even though by default these directories are the same. This assumption is important because it supports building different variants of the recipe by using the BBCLASSEXTEND variable. - You could allow the build directory to be the same as the source directory but you would + You could allow the Build Directory to be the same as the source directory but you would not be able to build more than one variant of the recipe. Consequently, if you are building multiple variants of the recipe, you need to establish a - build directory that is different than the source directory. + Build Directory that is different than the source directory. @@ -2114,7 +2114,7 @@ To enable this behavior, simply add the following to the local.conf configuration file found in the - build directory: + Build Directory: SRCREV_pn-<PN> = "${AUTOREV}" @@ -2545,7 +2545,7 @@ - Downloaded archives reside in the build directory in + Downloaded archives reside in the Build Directory in /tmp and are cleared up when they are no longer in use. diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 4452d2a4e2..c14c524aa5 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -236,7 +236,7 @@ "Patching the Kernel" section for an example that changes the source code of the kernel. For information on how to configure the kernel, see the - "Configuring the Kernel section. + "Configuring the Kernel" section.
@@ -347,7 +347,8 @@ What happens during the build? When you build the kernel on your development system, all files needed for the build are taken from the source repositories pointed to by the - SRC_URI variable and gathered in a temporary work area + SRC_URI variable + and gathered in a temporary work area where they are subsequently used to create the unique kernel. Thus, in a sense, the process constructs a local source tree specific to your kernel to generate the new kernel image - a source generator if you will. @@ -394,8 +395,8 @@ "The Packages" sections both in the Yocto Project Quick Start for requirements. Establish a local copy of project files on your - system: Having the source - directory on your system gives you access to the build process and tools + system: Having the Source + Directory on your system gives you access to the build process and tools you need. For information on how to get these files, see the bulleted item "Yocto Project Release" earlier in this manual. @@ -439,7 +440,7 @@ .config. Try to resist the temptation of directly editing the .config file found in the - build directory at + Build Directory at tmp/sysroots/<machine-name>/kernel. Doing so, can produce unexpected results when the OpenEmbedded build system regenerates the configuration file. @@ -986,10 +987,10 @@ Build System Derived Toolchain: Select this mode if the cross-toolchain has been installed and built - as part of the build directory. + as part of the Build Directory. When you select Build system derived toolchain, you are using the toolchain bundled - inside the build directory. + inside the Build Directory. @@ -1008,9 +1009,9 @@ However, doing so is discouraged. If you are using a system-derived toolchain, the path you provide for the Toolchain Root Location - field is the build directory. + field is the Build Directory. See the "Using - BitBake and the build directory" section in the Yocto Project Application + BitBake and the Build Directory" section in the Yocto Project Application Developer's Guide for information on how to install the toolchain into the build directory. Specify the Sysroot Location: @@ -1053,7 +1054,7 @@ directory. and specify any custom options. If you selected Build system derived toolchain, the target kernel you built will be located in the - build directory in tmp/deploy/images directory. + Build Directory in tmp/deploy/images directory. If you selected Standalone pre-built toolchain, the pre-built image you downloaded is located in the directory you specified when you downloaded the image. @@ -1409,7 +1410,7 @@ directory. Select your Yocto Bitbake Commander project. Select Project -> Launch HOB. - Enter the build directory where you want to put your final images. + Enter the Build Directory where you want to put your final images. Click OK to launch Hob. Use Hob to customize and build your own images. For information on Hob, see the @@ -1480,7 +1481,7 @@ directory. to figure out your solution. After you have initially built the package, you can iteratively tweak the source code, which is located in the - build directory, and then + Build Directory, and then you can force a re-compile and quickly test your altered code. Once you settle on a solution, you can then preserve your changes in the form of patches. @@ -1494,7 +1495,7 @@ directory. During a build, the unpacked temporary source code used by recipes - to build packages is available in the build directory as + to build packages is available in the Build Directory as defined by the S variable. Below is the default value for the S variable as defined in the @@ -1528,7 +1529,7 @@ directory. Let's look at an example without variables. Assuming a top-level Source Directory named poky - and a default build directory of poky/build, + and a default Build Directory of poky/build, the following is the work directory for the acl recipe that creates the acl package: @@ -1543,7 +1544,7 @@ directory. ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} Again, assuming top-level Source Directory named poky - and a default build directory of poky/build, the + and a default Build Directory of poky/build, the following are the work and temporary source directories, respectively, for the acl package that is being built for a MIPS-based device: @@ -1591,7 +1592,7 @@ directory. Find the Source Code: The temporary source code used by the OpenEmbedded build system is kept in the - build directory. + Build Directory. See the "Finding the Temporary Source Code" section to learn how to locate the directory that has the temporary source code for a @@ -1689,7 +1690,7 @@ directory. Find the Source Code: The temporary source code used by the OpenEmbedded build system is kept in the - build directory. + Build Directory. See the "Finding the Temporary Source Code" section to learn how to locate the directory that has the temporary source code for a diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index 20cf234a6b..bb01131c05 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -130,7 +130,7 @@ From the interface, you can click on any particular item in the "Name" column and see the URL at the bottom of the page that you need to set up a Git repository for that particular item. - Having a local Git repository of the source directory (poky) allows you to + Having a local Git repository of the Source Directory (poky) allows you to make changes, contribute to the history, and ultimately enhance the Yocto Project's tools, Board Support Packages, and so forth. @@ -148,7 +148,7 @@ download page and get a tarball of the release. You can also go to this site to download any supported BSP tarballs. - Unpacking the tarball gives you a hierarchical source directory that lets you develop + Unpacking the tarball gives you a hierarchical Source Directory that lets you develop using the Yocto Project. @@ -220,31 +220,31 @@ Build Directory: This term refers to the area used by the OpenEmbedded build system for builds. The area is created when you source the setup - environment script that is found in the source directory - (i.e. oe-init-build-env). + environment script that is found in the Source Directory + (i.e. &OE_INIT_FILE;). The TOPDIR - variable points to the build directory. + variable points to the Build Directory. - You have a lot of flexibility when creating the build directory. + You have a lot of flexibility when creating the Build Directory. Following are some examples that show how to create the directory: - Create the build directory in your current working directory + Create the Build Directory in your current working directory and name it build. This is the default behavior. - $ source oe-init-build-env + $ source &OE_INIT_PATH; Provide a directory path and specifically name the build directory. - This next example creates a build directory named YP-&POKYVERSION; + This next example creates a Build Directory named YP-&POKYVERSION; in your home directory within the directory mybuilds. If mybuilds does not exist, the directory is created for you: $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION; - Provide an existing directory to use as the build directory. + Provide an existing directory to use as the Build Directory. This example uses the existing mybuilds directory - as the build directory. + as the Build Directory. $ source &OE_INIT_PATH; $HOME/mybuilds/ @@ -254,7 +254,7 @@ this term refers to the OpenEmbedded build system used by the project. This build system is based on the project known as "Poky." For some historical information about Poky, see the - poky term further along in this section. + Poky term further along in this section. Classes: Files that provide for logic encapsulation and inheritance allowing commonly used patterns to be defined once and easily used @@ -264,14 +264,14 @@ Configuration File: Configuration information in various .conf files provides global definitions of variables. The conf/local.conf configuration file in the - build directory + 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 - source directory, define + Source Directory, 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). @@ -332,7 +332,7 @@ the Yocto Project's build system. Within the Yocto Project source repositories, poky exists as a separate Git repository that can be cloned to yield a local copy on the host system. - Thus, "poky" can refer to the local copy of the source directory used to develop within + Thus, "poky" can refer to the local copy of the Source Directory used to develop within the Yocto Project. Recipe: A set of instructions for building packages. A recipe describes where you get source code and which patches to apply. @@ -349,15 +349,15 @@ Sometimes you might here the term "poky directory" used to refer to this directory structure. - The source directory contains BitBake, Documentation, metadata and + The Source Directory contains BitBake, Documentation, metadata and other files that all support the Yocto Project. - Consequently, you must have the source directory in place on your development + Consequently, you must have the Source Directory in place on your development system in order to do any development using the Yocto Project. - For tarball expansion, the name of the top-level directory of the source directory + For tarball expansion, the name of the top-level directory of the Source Directory is derived from the Yocto Project release tarball. For example, downloading and unpacking &YOCTO_POKY_TARBALL; - results in a source directory whose top-level folder is named + results in a Source Directory whose top-level folder is named &YOCTO_POKY;. If you create a local copy of the Git repository, then you can name the repository anything you like. @@ -366,15 +366,15 @@ So, for example, cloning the poky Git repository results in a local Git repository whose top-level folder is also named poky. - It is important to understand the differences between the source directory created + It is important to understand the differences between the Source Directory created by unpacking a released 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 release - a fixed release point. - Any changes you make to your local files in the source directory are on top of the release. + Any changes you make to your local files in the Source Directory are on top of the release. On the other hand, when you clone the poky Git repository, you have an active development repository. - In this case, any local changes you make to the source directory can be later applied + In this case, any local changes you make to the Source Directory can be later applied to active development branches of the upstream poky Git repository. @@ -438,7 +438,7 @@ meta/files/common-licenses. Once the build completes, the list of all licenses found and used during that build are kept in the - build directory at + Build Directory at tmp/deploy/images/licenses. @@ -466,6 +466,12 @@ here. This wiki page discusses the license infrastructure used by the Yocto Project. + + + For information that can help you to maintain compliance with various open source licensing + during the lifecycle of a product created using the Yocto Project, see the + "Maintaining Open Source License Compliance During Your Product's Lifecycle" section. +
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml index e55a07d87a..11d4adca9f 100644 --- a/documentation/dev-manual/dev-manual-start.xml +++ b/documentation/dev-manual/dev-manual-start.xml @@ -56,8 +56,9 @@ OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project and officially supported. For a list of the distributions under validation and their status, see the - Distribution - Support wiki page. + "Supported Linux Distributions" section + in the Yocto Project Reference Manual and the wiki page at + Distribution Support. You should also have about 100 gigabytes of free disk space for building images. @@ -69,12 +70,12 @@ for the supported distributions. Yocto Project Release: You need a release of the Yocto Project. - You set up a with local source directory + You set up a with local Source Directory one of two ways depending on whether you are going to contribute back into the Yocto Project or not. Regardless of the method you use, this manual refers to the resulting local - hierarchical set of files as the "source directory." + hierarchical set of files as the "Source Directory." Tarball Extraction: If you are not going to contribute @@ -83,7 +84,7 @@ Once you have the tarball, just extract it into a directory of your choice. For example, the following command extracts the Yocto Project &DISTRO; release tarball - into the current working directory and sets up the local source directory + into the current working directory and sets up the local Source Directory with a top-level folder named &YOCTO_POKY;: $ tar xfj &YOCTO_POKY_TARBALL; @@ -125,11 +126,11 @@ You can find Git repositories of supported Yocto Project Kernels organized under "Yocto Linux Kernel" in the Yocto Project Source Repositories at . - This setup involves creating a bare clone of the Yocto Project kernel and then + This setup can involve creating a bare clone of the Yocto Project kernel and then copying that cloned repository. You can create the bare clone and the copy of the bare clone anywhere you like. For simplicity, it is recommended that you create these structures outside of the - source directory (usually poky). + Source Directory (usually poky). As an example, the following transcript shows how to create the bare clone of the linux-yocto-3.4 kernel and then create a copy of that clone. @@ -168,9 +169,9 @@ You can find the poky-extras Git Repository in the "Yocto Metadata Layers" area of the Yocto Project Source Repositories at . - It is good practice to create this Git repository inside the source directory. + It is good practice to create this Git repository inside the Source Directory. Following is an example that creates the poky-extras Git - repository inside the source directory, which is named poky + repository inside the Source Directory, which is named poky in this case: $ cd ~/poky @@ -192,7 +193,7 @@ layer. You can get set up for BSP development one of two ways: tarball extraction or with a local Git repository. - It is a good idea to use the same method that you used to set up the source directory. + It is a good idea to use the same method that you used to set up the Source Directory. Regardless of the method you use, the Yocto Project uses the following BSP layer naming scheme: @@ -218,13 +219,13 @@ Again, this method just produces a snapshot of the BSP layer in the form of a hierarchical directory structure. Git Repository Method: If you are working - with a local Git repository for your source directory, you should also use this method + with a local Git repository for your Source Directory, you should also use this method to set up the meta-intel Git repository. You can locate the meta-intel Git repository in the "Yocto Metadata Layers" area of the Yocto Project Source Repositories at . Typically, you set up the meta-intel Git repository inside - the source directory. + the Source Directory. For example, the following transcript shows the steps to clone the meta-intel Git repository inside the local poky Git repository. @@ -266,13 +267,13 @@ The build process is as follows: - Make sure you have set up the source directory described in the + Make sure you have set up the Source Directory described in the previous section. Initialize the build environment by sourcing a build environment script. Optionally ensure the conf/local.conf configuration file, which is found in the - build directory, + Build Directory, is set up how you want it. This file defines many aspects of the build environment including the target machine architecture through the @@ -298,7 +299,7 @@ Another option you have to get started is to use pre-built binaries. The Yocto Project provides many types of binaries with each release. - See the Images + See the "Images" chapter in the Yocto Project Reference Manual for descriptions of the types of binaries that ship with a Yocto Project release. -- cgit v1.2.3-54-g00ecf