From ed26c02ac6cb435137ffaafddcd71fa5d7658076 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 14 Jun 2012 11:24:48 -0700 Subject: documentation/dev-manual/dev-manual-model.xml: 1.1.2 variables and updates First pass at implementing the poky.ent variables. Also updated text in spots. (From yocto-docs rev: bd91876ea4aa06088f43951e7c988d7445e46de0) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 184 ++++++++++++++------------ 1 file changed, 100 insertions(+), 84 deletions(-) diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 10206cbd79..30142a61b3 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -1,5 +1,6 @@ +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[ %poky; ] > @@ -23,9 +24,8 @@ "Kernel Modification Example" appendix. For a user-space application development example that uses the Eclipse IDE, - see the - - The Yocto Project Application Development Toolkit (ADT) User's Guide. + see The Yocto Project Application Development + Toolkit (ADT) User's Guide.
@@ -35,8 +35,8 @@ System development involves modification or creation of an image that you want to run on a specific hardware target. Usually, when you want to create an image that runs on embedded hardware, the image does - not require the same amount of features that a full-fledged Linux distribution provides. - Thus, you can create a much smaller image that is designed to just use the hardware + not require the same number of features that a full-fledged Linux distribution provides. + Thus, you can create a much smaller image that is designed to use only the hardware features for your particular hardware. @@ -50,8 +50,8 @@ Developing a Board Support Package (BSP) - A BSP is a package of recipes that, when applied, during a build results in - an image you can run on a particular board. + A BSP is a packageof recipes that, when applied, during a build results in + an image that you can run on a particular board. Thus, the package, when compiled into the new image, supports the operation of the board. @@ -61,8 +61,8 @@ - The remainder of this section presents the basic steps to create a BSP basing it on an - existing BSP that ships with the Yocto Project. + The remainder of this section presents the basic steps used to create a BSP + based on an existing BSP that ships with the Yocto Project. You can reference the "BSP Development Example" appendix for a detailed example that uses the Crown Bay BSP as a base BSP from which to start. @@ -79,18 +79,19 @@ Set up your host development system to support development using the Yocto Project: See the - "The Linux Distributions" and the - "The Packages" sections both + "The Linux Distributions" + and the + "The Packages" sections both in the Yocto Project Quick Start for requirements. Establish a local copy of the Yocto Project files on your system: You need to have the Yocto Project files available on your host system. Having the Yocto Project files on your system gives you access to the build - process and tools you need. + process and to the tools you need. For information on how to get these files, see the "Getting Setup" section. Establish a local copy of the base BSP files: Having the BSP files on your system gives you access to the build - process and tools you need for creating a BSP. + process and to the tools you need for creating a BSP. For information on how to get these files, see the "Getting Setup" section. Choose a Yocto Project-supported BSP as your base BSP: @@ -111,13 +112,15 @@ Crown Bay that does not support the Intel Embedded Media Graphics Driver (EMGD). The remainder of this example uses that base BSP. - To see the supported BSPs, go to the Yocto Project - download page and click - on “BSP Downloads.” + To see the supported BSPs, go to the + Download page on the Yocto Project + website and click on “BSP Downloads.” Create your own BSP layer: Layers are ideal for isolating and storing work for a given piece of hardware. - A layer is really just a location or area in which you place the recipes for your BSP. + A layer is really just a location or area in which you place the recipes for your BSP. In fact, a BSP is, in itself, a special type of layer. + + Another example that illustrates a layer is an application. Suppose you are creating an application that has library or other dependencies in order for it to compile and run. @@ -137,16 +140,17 @@ N450, and Sugar Bay are isolated. When you set up a layer for a new BSP, you should follow a standard layout. This layout is described in the section - "Example Filesystem Layout" section of the Board Support Package (BSP) Development Guide. + "Example Filesystem Layout" + section of the Board Support Package (BSP) Development Guide. In the standard layout, you will notice a suggested structure for recipes and configuration information. You can see the standard layout for the Crown Bay BSP in this example by examining the directory structure of the meta-crownbay layer inside the local Yocto Project files. Make configuration changes to your new BSP - layer: The standard BSP layer structure organizes the files you need to edit in - conf and several recipes-* directories within the - BSP layer. + layer: The standard BSP layer structure organizes the files you need + to edit in conf and several recipes-* + directories within the BSP layer. Configuration changes identify where your new layer is on the local system and identify which kernel you are going to use. @@ -160,7 +164,8 @@ You need to get the build environment ready by sourcing an environment setup script and you need to be sure two key configuration files are configured appropriately. The entire process for building an image is overviewed in the section - "Building an Image" section of the Yocto Project Quick Start. + "Building an Image" section + of the Yocto Project Quick Start. You might want to reference this information. Build the image: The Yocto Project uses the BitBake tool to build images based on the type of image you want to create. @@ -168,8 +173,8 @@ here. The build process supports several types of images to satisfy different needs. See the - "Reference: Images" - appendix in The Yocto Project Reference Manual for information on + "Reference: Images" appendix + in The Yocto Project Reference Manual for information on supported images. @@ -178,10 +183,10 @@ You can view a video presentation on "Building Custom Embedded Images with Yocto" at Free Electrons. You can also find supplemental information in - + The Board Support Package (BSP) Development Guide. Finally, there is wiki page write up of the example also located - + here that you might find helpful.
@@ -191,7 +196,7 @@ Kernel modification involves changing the Linux Yocto kernel, which could involve changing - configuration variables as well as adding new kernel recipes. + configuration options as well as adding new kernel recipes. Configuration changes can be added in the form of configuration fragments, while recipe modification comes through the kernel's recipes-kernel area in a kernel layer you create. @@ -201,7 +206,7 @@ The remainder of this section presents a high-level overview of the Linux Yocto kernel architecture and the steps to modify the Linux Yocto kernel. For a complete discussion of the kernel, see - + The Yocto Project Kernel Architecture and Use Manual. You can reference the appendix "Kernel Modification Example" @@ -212,39 +217,41 @@ Kernel Overview - When one thinks of the source files for a kernel they usually think of a fixed structure - of files that contain kernel patches. - The Yocto Project, however, employs mechanisims, that in a sense, result in a kernel source + Traditionally, when one thinks of a patched kernel, they think of a base kernel + source tree and a fixed structure that contains kernel patches. + The Yocto Project, however, employs mechanisms, that in a sense, result in a kernel source generator. By the end of this section, this analogy will become clearer. You can find a web interface to the Linux Yocto kernel source repositories at - . + . If you look at the interface, you will see to the left a grouping of Git repositories titled "Yocto Linux Kernel." - Within this group, you will find the four different kernels supported by + Within this group, you will find several kernels supported by the Yocto Project: linux-yocto-2.6.34 - The stable Linux Yocto kernel that is based on the Linux 2.6.34 release. linux-yocto-2.6.37 - The stable Linux Yocto kernel that is based on the Linux 2.6.37 release. - linux-yocto-3.0 - The - stable Linux Yocto kernel to use with the Yocto Project current (master) development. - This kernel is based on the Linux 3.0 release. + linux-yocto-3.0 - The stable + Linux Yocto kernel that is based on the Linux 3.0 release. linux-yocto-3.0-1.1.x - The - stable Linux Yocto kernel to use with the Yocto Project Release 1.1.x. - This kernel is based on the Linux 3.0 release. + stable Linux Yocto kernel to use with the Yocto Project Release 1.1.x. This kernel + is based on the Linux 3.0 release + linux-yocto-3.2 - The + stable Linux Yocto kernel to use with the Yocto Project Release 1.2. This kernel + is based on the Linux 3.2 release linux-yocto-dev - A development kernel based on the latest upstream release candidate available. - The kernels are maintained using the Git application that, in a sense, structures - them in a "tree" complete with branches and leaves. + The kernels are maintained using the Git revision control system + that structures them using the familiar "tree", "branch", and "leaf" scheme. Branches represent diversions from general code to more specific code, while leaves represent the end-points for a complete and unique kernel whose source files when gathered from the root of the tree to the leaf accumulate to create the files @@ -257,7 +264,7 @@ Within the figure, the "Kernel.org Branch Point" represents the point in the tree - where a supported base kernel diverges from the Linux kernel. + where a supported base kernel is modified from the Linux kernel. For example, this could be the branch point for the linux-yocto-3.0 kernel. Thus, everything further to the right in the structure is based on the @@ -271,14 +278,14 @@ The overall result is a Git-maintained repository from which all the supported - Yocto Project kernels can be derived for all the supported Yocto Project devices. + Yocto Project kernel types can be derived for all the supported Yocto Project devices. A big advantage to this scheme is the sharing of common features by keeping them in "larger" branches within the tree. This practice eliminates redundant storage of similar features shared among kernels. - Keep in mind the figure does not take into account all four supported Linux Yocto + Keep in mind the figure does not take into account all the supported Linux Yocto kernel types, but rather shows a single generic kernel just for conceptual purposes. Also keep in mind that this structure represents the Yocto Project source repositories that are either pulled from during the build or established on the host development system @@ -353,11 +360,11 @@ Again, for a complete discussion of the Yocto Project kernel's architcture and its branching strategy, - see the + see The Yocto Project Kernel Architecture and Use Manual. - Also, you can reference - Modifying the Kernel Source Code - for a detailed example that modifies the kernel. + You can also reference the + "Modifying the Kernel Source Code" + section for a detailed example that modifies the kernel. @@ -377,8 +384,8 @@ Set up your host development system to support development using the Yocto Project: See - "The Linux Distributions" and - "The Packages" sections both + "The Linux Distributions" and + "The Packages" sections both in the Yocto Project Quick Start for requirements. Establish a local copy of the Yocto Project files on your system: Having the Yocto Project files on your system gives you access to @@ -394,7 +401,10 @@ Project files Git repository. For information on how to get these files, see the bulleted item "The poky-extras Git Repository" - earlier in this manual. + earlier in this manual. + While it is certainly possible to modify the kernel without involving + a local Git repository, the suggested workflow for kernel modification + using the Yocto Project does use a Git repository. Establish a local copy of the Linux Yocto kernel files on your system: In order to make modifications to the kernel you need two things: a bare clone of the Linux Yocto kernel you are modifying and @@ -416,7 +426,7 @@ Once the changes are made, you need to use Git commands to commit the changes and then push them to the bare clone. Make kernel configuration changes - to your local kernel layer if applicable: + if applicable: If your situation calls for changing the kernel's configuration, you can use menuconfig to enable and disable kernel configurations. @@ -424,11 +434,18 @@ configuration changes you are making to the kernel. When saved, changes using menuconfig update the kernel's .config. - As an alternative method to changing the kernel's configuration, you can simply - edit the .config found in the Yocto Project build - directory at tmp/sysroots/<machine-name>/kernel - directly. - Add new kernel recipes if applicable: The standard + Try to resist the temptation of directly editing the .config + file found in the Yocto Project build directory at + tmp/sysroots/<machine-name>/kernel. + Doing so, can produce unexpected results when the Yocto Project build system + regenerates the configuration file. + Once you are satisfied with the configuration changes made using + menuconfig, you can directly examine the + .config file against a saved original and gather those + changes into a config fragment to be referenced from within the kernel's + .bbappend file. + Add or extend kernel recipes if applicable: + The standard layer structure organizes recipe files inside the meta-kernel-dev layer that is within the poky-extras Git repository. @@ -440,14 +457,15 @@ Prepare for the build: Once you have made all the changes to your kernel (configurations, source code changes, recipe additions, or recipe changes), there remains a few things - you need to do in order for the Yocto Project build system to create your image. + you need to do in order for the Yocto Project build system (BitBake) to create your image. If you have not done so, you need to get the build environment ready by sourcing the environment setup script described earlier. You also need to be sure two key configuration files (local.conf and bblayers.conf) are configured appropriately. The entire process for building an image is overviewed in the - "Building an Image" section of the Yocto Project Quick Start. + "Building an Image" + section of the Yocto Project Quick Start. You might want to reference this information. Also, you should look at the detailed examples found in the appendices at at the end of this manual. @@ -458,8 +476,8 @@ here. The build process supports several types of images to satisfy different needs. See the appendix - "Reference: Images" - in The Yocto Project Reference Manual for information on supported images. + "Reference: Images" in + The Yocto Project Reference Manual for information on supported images. Make your configuration changes available in the kernel layer: Up to this point, all the configuration changes to the kernel have been done and tested iteratively. @@ -467,10 +485,10 @@ which allows you to distribute the layer. If applicable, share your in-tree changes: If the changes you made - are suited for all Linux Yocto users, you might want to push the changes to a - contribution area for the Linux Yocto Git repository. - Once the changes are pushed, you can request that they - be pulled into the master branch of the kernel tree. + are suited for all Linux Yocto users, you might want to send them on for inclusion + into the Linux Yocto Git repository. + If the changes are accepted, the Yocto Project Maintainer pulls them into + the master branch of the kernel tree. Doing so makes them available to everyone using the kernel. @@ -509,7 +527,7 @@ provides an overview of the general development process. If you want to see a detailed example of the process as it is used from within the Eclipse IDE, see - + The Application Development Toolkit (ADT) User's Manual. @@ -526,8 +544,8 @@ Prepare the Host System for the Yocto Project: See - "The Linux Distributions" and - "The Packages" sections both + "The Linux Distributions" and + "The Packages" sections both in the Yocto Project Quick Start for requirements.