From e77f5649e08f96d2480567a515fd73d3f21cccd3 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 22 Jul 2011 14:05:31 -0700 Subject: documentation/dev-manual/dev-manual-cases.xml: partial - edits to clean terms up. I made a pass through the chapter to try and lessen the confusion over yp files in a git repo verses those unpacked from a tarball. Also tried to write the example for the 1.1 release but I don't have the real software yet and can't supply actual names of files. (From yocto-docs rev: 2ad973bd1f17005a3922651060d025795634d222) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-cases.xml | 171 ++++++++++++++------------ 1 file changed, 89 insertions(+), 82 deletions(-) (limited to 'documentation') diff --git a/documentation/dev-manual/dev-manual-cases.xml b/documentation/dev-manual/dev-manual-cases.xml index 727995800d..bb8389bc10 100644 --- a/documentation/dev-manual/dev-manual-cases.xml +++ b/documentation/dev-manual/dev-manual-cases.xml @@ -6,9 +6,10 @@ Development Cases - For the purposes of this manual we are going to focus on two common development cases or groupings: + Many development cases exist for which you can use the Yocto Project. + However, for the purposes of this manual we are going to focus on two common development cases or groupings: System Development and User Application Development. - System Development covers Board Support Package (BSP) development and kernel image modification. + System Development covers Board Support Package (BSP) development and kernel modification. User Application Development covers development of applications that you intend to run on some target hardware. @@ -46,14 +47,10 @@ Thus, the package, when compiled into the new image, supports the operation of the board. - - Packages consist of recipes. - Recipes are sets of instructions for building a package. - The recipes describe where to get source code and what patches to apply. - Recipes also describe dependencies for libraries or for other recipes. - They also contain configuration and compilation options. - Recipes are logical units of execution. - + + For a brief list of terms used when describing the development process in the Yocto Project, + see Yocto Project Terms in this manual. + Here are the basic steps involved in creating a BSP: @@ -74,8 +71,8 @@ for your recipes. Make configuration and recipe changes to your new BSP layer. Prepare for the build. - Select and configure the kernel. (WRITER'S NOTE: Not sure on this step). - Identify the machine branch in the Git repository. + Select and configure the kernel. + Identify the machine branch. Build the image. You can view a video presentation of the BSP creation process @@ -92,30 +89,29 @@ Setting Up Yocto Project - You need to have the Yocto Project source tree available on your host system. - You can get that through tarball extraction or by cloning the poky + You need to have the Yocto Project files available on your host system. + You can get files through tarball extraction or by cloning the poky Git repository. Typically, cloning the Git repository is the method to use. This allows you to maintain a complete history of changes and facilitates you contributing back to the Yocto Project. - However, if you just want the source you can download the Yocto Project Release - tarball from the + However, if you just want a hierarchical file structure that contains the recipes + and metadata that let you develop you can download tarballs from the download page. - If you download the tarball you can extract it into any directory you want using the + If you download a tarball you can extract it into any directory you want using the tar command. - For example, the following command extracts the Yocto Project 1.0.1 release tarball - (bernard 5.0.1) into - the current working directory and sets up a Yocto Project source directory named - bernard.5.0.1: + For example, the following command extracts the Yocto Project 1.1_M2 release tarball + into the current working directory and sets up a file structure whose top-level + directory is named poky-1.1: - $ tar xfj poky.bernard.5.0.1.tar.bz2 + $ tar xfj poky-1.1.tar.bz2 The following transcript shows how to clone the poky Git repository into the current working directory. - The command creates the Git repository in a directory named poky: + The command creates the repository in a directory named poky: $ git clone git://git.yoctoproject.org/poky Initialized empty Git repository in /home/scottrif/poky/.git/ @@ -143,8 +139,8 @@ $ cd poky - $ git checkout -b bernard origin/bernard - Switched to a new branch 'bernard' + $ git checkout -b 1.1 origin/1.1 + Switched to a new branch '1.1' [WRITER'S NOTE: I NEED THE REAL BRANCH NAMES IN THE EXAMPLE.] @@ -164,18 +160,19 @@ At this point you need to understand your target hardware well enough to determine which - existing BSP most closely matches it. + existing BSP it most closely matches. Things to consider are your hardware’s on-board features such as CPU type and graphics support. You should look at the README files for supported BSPs to get an idea of which one you could use. - A generic Atom-based BSP to consider is the Crown Bay with no Intel® Embedded Media - Graphics Driver (EMGD) support. - That is the BSP that this example is going to use. + A generic Atom-based BSP to consider is the 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.” + download page and click + on “BSP Downloads.” @@ -184,13 +181,15 @@ You need to have the base BSP layer on your development system. - Like the Yocto Project source tree you can get the BSP layer one of two ways: - download the tarball and extract it, or initialize a Git repository and check out the BSP. - You should use the same method that you used for the Yocto Project source tree. + Like the Yocto Project's poky Git repository you can get the BSP + layer one of two ways: + download the BSP tarball and extract it, or set up a local Git repository that + has the Yocto Project BSP layers. + You should use the same method that you used to get the Yocto Project files earlier. - If you are using tarball extraction then simply download the tarball for the base + If you are using tarball extraction, simply download the tarball for the base BSP you chose in the previous step and then extract it into any directory you choose using the tar command. Upon extraction, the BSP source directory (layer) will be named @@ -198,14 +197,14 @@ The following command extracts the Crown Bay BSP into the current directory and names it meta-crownbay: - $ tar xjf crownbay-noemgd-bernard-5.0.1.tar.bz2 + $ tar xjf crownbay-noemgd-1.1.tar.bz2 If you cloned a Yocto Project Git repository (poky) then you need to do the same for the - BSP, which is located in the meta-intel Git repository. + BSP, which is located in Yocto Project's meta-intel Git repository. The meta-intel repository contains all the metadata that supports BSP creation. When you set up the meta-intel Git repository you can @@ -236,7 +235,7 @@ For this example we are going to use the [NEED BRANCH] branch. $ cd meta-intel - $ git checkout -b bernard origin/bernard + $ git checkout -b 1.1 origin/1.1 Switched to a new branch 'bernard' [WRITER'S NOTE: I NEED THE REAL BRANCH NAMES IN THE EXAMPLE.] @@ -247,7 +246,7 @@ Making a Copy of the Base BSP to Create Your New BSP Layer - Now that you have the Yocto Project and base BSP source you need to create a + Now that you have the Yocto Project and base BSP files you need to create a new layer for your BSP. @@ -268,34 +267,36 @@ Yocto Project release: atom-pc, beagleboard, mpc8315e, and routerstationpro. The recipes and configurations for these four BSPs are located and dispersed - within meta-yocto, which can be found in the Yocto Project source directory. + within meta-yocto, which can be found in the + area you unpacked the Yocto Project release tarball or set up your local + poky Git repository. Consequently, they are not totally isolated in the spirit of layers unless you think of meta-yocto as a layer itself. On the other hand, the Yocto Project has isolated BSP layers within - meta-intel for the Crown Bay, Emenlow, Jasper Forest, N450, and - Sugar Bay. - [WRITER'S NOTE: meta-yocto, meta, and - meta-intel need some explanation. - Not sure about the relationship of meta-yocto as compared to meta-intel.] + meta-intel Git repository for the Crown Bay, Emenlow, Jasper Forest, + N450, and Sugar Bay. + If you are not using a meta-intel Git repository then you would + downloaded a tarball for one of these isolated BSP layers. When you set up a layer for a new BSP you should follow a standard layout. - This layout is described in + This layout is described in the Example Filesystem Layout section of the Board Support Package (BSP) Development Guide. - In the standard layout you will notice a suggested hierarchy for BSP kernel recipes, - graphics recipes, and configuration information. + 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 - meta-intel Git repository. + meta-intel Git repository or the area where you unpacked the + Crown Bay BSP tarball. To create your BSP layer you simply copy the meta-crownbay layer to a new layer. - For this example the new layer is named meta-mymachine. + For this example the new layer will be named meta-mymachine. The name must follow the BSP layer naming convention, which is meta-<name>. The following example assumes your working directory is meta-intel @@ -358,7 +359,7 @@ Layer Configuration File section in the Board Support Packages (BSP) Development Guide for more information on this configuration file. - Basically, we are removing statements that support EMGD and changing the ones that support no EMGD. + Basically, we are changing the existing statements to work with our BSP. @@ -385,20 +386,20 @@ The standard BSP structure has areas for BSP, graphics, core, and kernel recipes. When you create a BSP you use these areas for appropriate recipes and append files. Recipes take the form of .bb files. - If you want to leverage off of existing recipes elsewhere in the Yocto Project - source tree but change them you can use .bbappend files. - All new recipes and append files for your layer go in the layer’s + If you want to leverage the existing recipes the Yocto Project build system uses + but change those recipes you can use .bbappend files. + All new recipes and append files for your layer must go in the layer’s recipes-bsp, recipes-kernel, recipes-core, and recipes-graphics directories. - First, let us look at recipes-bsp. + First, let's look at recipes-bsp. For this example we are not adding any new BSP recipes. And, we only need to remove the formfactor we do not want and change the name of - the remaining one that supports no EMGD. - These commands take care of the new layer’s BSP recipes: + the remaining one that doesn't support EMGD. + These commands take care of the recipes-bsp recipes: $ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/*emgd* $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \ @@ -407,7 +408,7 @@ - Now let us look at recipes-graphics. + Now let's look at recipes-graphics. For this example we want to remove anything that supports EMGD and be sure to rename remaining directories appropriately. The following commands clean up the recipes-graphics directory: @@ -421,14 +422,15 @@ At this point the recipes-graphics directory just has files that - support Video Electronics Standards Association (VESA) graphics modes. + support Video Electronics Standards Association (VESA) graphics modes and not EMGD. - Now let us look at changes in recipes-core. + Now let's look at changes in recipes-core. The file task-core-tools.bbappend in recipes-core/tasks appends the similarly named recipe - located in the Yocto Project Git repository at meta/recipes-core/tasks. + located in the poky Git repository at + meta/recipes-core/tasks. The "append" file in our layer right now is Crown Bay-specific and supports EMGD and non-EMGD. Here are the contents of the file: @@ -449,16 +451,16 @@ - Finally, let us look at recipes-kernel changes. + Finally, let's look at recipes-kernel changes. Recall that the BSP uses the linux-yocto kernel as determined earlier in the mymachine.conf. The recipe for that kernel is located is not located in the - BSP layer but rather in Yocto Project Git repository at + BSP layer but rather in the poky Git repository at meta/recipes-kernel/linux and is named linux-yocto-2.6.37.bb. The SRCREV_machine and SRCREV_meta - statements point to the exact commits in the Yocto Project Git repository from - which the source for the kernel can be found. + statements point to the exact commits in the poky Git repository + that identify the right kernel for our hardware. @@ -471,8 +473,8 @@ - The SRCREV statements in the "append" file currently point - to the kernel that supports the Crown Bay BSP with and without EMGD support. + The SRCREV statements in the "append" file currently identify + the kernel that supports the Crown Bay BSP with and without EMGD support. Here are the statements: SRCREV_machine_pn-linux-yocto_crownbay ?= \ @@ -489,21 +491,20 @@ You will notice that there are two pairs of SRCREV statements. - The top pair points to a kernel that supports + The top pair identifies the kernel that supports EMGD, which we don’t care about in this example. - The bottom pair points to the kernel that we will use: + The bottom pair identifies the kernel that we will use: linux-yocto. At this point though, the unique commit strings all are still associated with - Crown Bay. + Crown Bay and not meta-mymachine. - So the next changes we make modify this linux-yocto-2.6.37.bbappend - file. - First, we delete the two SRCREV statements that support + To fix this situation in linux-yocto-2.6.37.bbappend + we delete the two SRCREV statements that support EMGD (the top pair). - Next, we change the remaining pair to specify mymachine - and then we insert the commit identifier to point to the kernel in which we + We also change the remaining pair to specify mymachine + and insert the commit identifiers to identify the kernel in which we are interested, which will be based on the atom-pc-standard kernel. Here are the final SRCREV statements: @@ -542,10 +543,10 @@ - Also in the linux-yocto-2.6.47.bbappend file are + Also in the linux-yocto-2.6.37.bbappend file are COMPATIBLE_MACHINE, KMACHINE, and KERNEL_FEATURES statements. - Again, there are two sets of these: one for EMGD support and one for non-EMGD support. + Two sets of these exist: one set supports EMGD and one set does not. Because we are not interested in supporting EMGD those three can be deleted. The remaining three must be changed so that mymachine replaces crownbay-noemgd and crownbay. @@ -571,7 +572,7 @@ of any new recipes you might need. In this example, it was simply a matter of ridding the new layer meta-machine of any code that supported the EMGD features - and making sure we were pointing to the kernel that supports our example, which + and making sure we were identifying the kernel that supports our example, which is the atom-pc-standard kernel. We did not introduce any new recipes to the layer. @@ -606,8 +607,10 @@ Get the environment ready for the build by sourcing the environment script. - The environment script is in the Yocto Project source directory - (poky in this example) and has the string + The environment script is in the top-level of the poky + Git repository or the top-level directory in which you unpacked the Yocto Project + release tarball. + The script has the string init-build-env in the file’s name. For this example, the following command gets the build environment ready: @@ -615,7 +618,7 @@ When you source the script a build directory is created in the current working directory. - In our example we were in the Yocto Project source directory. + In our example we were in the poky directory. Thus, entering the previous command created the yocto-build directory. If you do not provide a name for the build directory it defaults to build. @@ -671,10 +674,14 @@ starts the process off of building the type of image you want. + + [WRITER'S NOTE: Consider moving this to the Poky Reference Manual.] + + You can find these recipes in the meta/recipes-core/images and - meta/recipes-sato/images directories of the Yocto Project source - tree (the poky Git repository in this example). + meta/recipes-sato/images directories of your local Yocto Project + file structure (Git repository or extracted release tarball). Although the recipe names are somewhat explanatory, here is a list that describes them: Base – A foundational basic image without support -- cgit v1.2.3-54-g00ecf