From 70e006ec0ce2b0edc6b4811100f80b15c447dced Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 20 Jul 2011 14:49:06 -0700 Subject: documentation/dev-manual/dev-manual-cases.xml: partial edits to procedures Partial stuff as I am working through the BSP example trying to use git clone instead of git init per Darren Hart's suggestion. (From yocto-docs rev: e829d761575786093c9ac1f1b901a2151011ce9d) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-cases.xml | 318 ++++++++++++-------------- 1 file changed, 145 insertions(+), 173 deletions(-) diff --git a/documentation/dev-manual/dev-manual-cases.xml b/documentation/dev-manual/dev-manual-cases.xml index d57f0eabff..83b02b1435 100644 --- a/documentation/dev-manual/dev-manual-cases.xml +++ b/documentation/dev-manual/dev-manual-cases.xml @@ -58,8 +58,14 @@ Here are the basic steps involved in creating a BSP: - Be sure you are set up to use Yocto Project (see - Getting Started with the Yocto Project). + Be sure your host development system is set up to support + development using the Yocto Project. + See + + The Linux Distributions section and + + The Packages section both + in the Yocto Project Quick Start for requirements. Choose a BSP available with Yocto Project that most closely represents your hardware. Get set up with a base BSP. @@ -84,20 +90,11 @@
Setting Up Yocto Project - - For general host development system preparation such as package requirements and - operating system requirements, see - Getting Started with the Yocto Project)Chapter 2 of - this manual or the - - Yocto Project Quick Start. - - You need to have the Yocto Project source tree available on your host system. - You can get that through tarball extraction or by initializing and checking out the - Yocto Project Git repository. - Typically, checking out the Git repository is the method to use. + You can get that 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 @@ -105,68 +102,48 @@ download page. If you download the tarball you can extract it into any directory you want using the tar command. - For example, the following commands extract the 1.0.1 release tarball into - /usr/local/yocto with the Yocto Project source directory as - poky.bernard.5.0.1.tar.bz2: + 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: - /usr/local/yocto$ tar xfj poky.bernard.5.0.1.tar.bz2 + $ tar xfj poky.bernard.5.0.1.tar.bz2 - The following transcript shows how to initialize a Git repository and checkout the - Yocto Project source tree: + 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: - /usr/local/yocto$ git init - Initialized empty Git repository in /usr/local/yocto/.git - /usr/local/yocto$ git remote add poky git://git.yoctoproject.org/poky.git - /usr/local/yocto$ git remote update - Fetching poky - remote: Counting objects: 106111, done. - remote: Compressing objects: 100% (36106/36106), done. - remote: Total 106111 (delta 72275), reused 99193 (delta 66808) - Receiving objects: 100% (106111/106111), 69.51 MiB | 518 KiB/s, done. - Resolving deltas: 100% (72275/72275), done. - From git://git.yoctoproject.org/poky - * [new branch] 1.1_M1 -> poky/1.1_M1 - * [new branch] 1.1_M2 -> poky/1.1_M2 - * [new branch] bernard -> poky/bernard - * [new branch] blinky -> poky/blinky - * [new branch] clyde -> poky/clyde - * [new branch] elroy -> poky/elroy - * [new branch] green -> poky/green - * [new branch] laverne -> poky/laverne - * [new branch] master -> poky/master - * [new branch] pinky -> poky/pinky - * [new branch] purple -> poky/purple - * [new tag] 1.1_M1.final -> 1.1_M1.final - * [new tag] 1.1_M2.rc1 -> 1.1_M2.rc1 - * [new tag] bernard-5.0.1 -> bernard-5.0.1 - * [new tag] pinky-3.1.2 -> pinky-3.1.2 - From git://git.yoctoproject.org/poky - * [new tag] 1.1_M1.rc1 -> 1.1_M1.rc1 - * [new tag] 1.1_M1.rc2 -> 1.1_M1.rc2 - * [new tag] bernard-1.0rc1 -> bernard-1.0rc1 - * [new tag] bernard-5.0 -> bernard-5.0 - * [new tag] bernard-5.0-alpha -> bernard-5.0-alpha - * [new tag] bernard-5.0rc1 -> bernard-5.0rc1 - * [new tag] bernard-5.0rc2 -> bernard-5.0rc2 - * [new tag] laverne-4.0 -> laverne-4.0 - * [new tag] laverne-4.0.1 -> laverne-4.0.1 - * [new tag] m4 -> m4 - * [new tag] purple-3.2 -> purple-3.2 - * [new tag] purple-3.2.1 -> purple-3.2.1 + $ git clone git://git.yoctoproject.org/poky + Initialized empty Git repository in /home/scottrif/poky/.git/ + remote: Counting objects: 107624, done. + remote: Compressing objects: 100% (37128/37128), done. + remote: Total 107624 (delta 73393), reused 99851 (delta 67287) + Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done. + Resolving deltas: 100% (73393/73393), done. - Once you have the repository set up, you have many development branches from which - you can work. + Once you have the repository set up you have many development branches from which + you can work. + From inside the repository you can see the branch names and the tag names used + in the Git repository using either of the following two commands: + + $ git branch -a + $ git tag -l + For this example we are going to use the Yocto Project 1.0.1 Release, - which maps to the Bernard 5.0.1 tag in Git. + which maps to the bernard branch in the repository. + These commands create a local branch named bernard + that tracks the remote branch of the same name. - /usr/local/yocto$ git checkout -b Bernard-5.0.1 bernard-5.0.1 - Switched to a new branch 'bernard-5.0.1' + + $ cd poky + $ git checkout -b bernard + Switched to a new branch 'bernard'
@@ -211,58 +188,53 @@ - If you are using tarball extraction then 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 - meta-<BSP_name>. - The following command extracts the Crown Bay BSP into a directory named - meta-crownbay: + If you are using tarball extraction then 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 + meta-<BSP_name>. + The following command extracts the Crown Bay BSP into the current directory and names it + meta-crownbay: - /usr/local$ tar xjf crownbay-noemgd-bernard-5.0.1.tar.bz2 + $ tar xjf crownbay-noemgd-bernard-5.0.1.tar.bz2 - If you initialized a Yocto Project Git repository then you need to do the same for the - BSP, which is located in the meta-intel Git repository. - The meta-intel repository contains all the metadata that supports BSP creation. + 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. + The meta-intel repository contains all the metadata + that supports BSP creation. - The following transcript shows the steps to create and set up the meta-intel Git - repository inside the Yocto Project Git repository: + The following transcript shows the steps to clone the meta-intel + Git repository inside the poky Git repository created earlier in this + example. + While this example establishes the meta-intel Git repository inside + the poky Git repository, you are not required to have + meta-intel inside of poky: - /usr/local/yocto$ mkdir meta-intel - /usr/local/yocto$ cd meta-intel - /usr/local/yocto/meta-intel$ git init - Initialized empty Git repository in /usr/local/yocto/meta-intel/.git/ - /usr/local/yocto/meta-intel$ git remote add meta-intel \ git://git.yoctoproject.org/meta-intel.git - /usr/local/yocto/meta-intel$ git remote update - Fetching meta-intel - remote: Counting objects: 1240, done. - remote: Compressing objects: 100% (1008/1008), done. - remote: Total 1240 (delta 513), reused 85 (delta 27) - Receiving objects: 100% (1240/1240), 1.55 MiB | 510 KiB/s, done. - Resolving deltas: 100% (513/513), done. - From git://git.yoctoproject.org/meta-intel - * [new branch] 1.1_M1 -> meta-intel/1.1_M1 - * [new branch] 1.1_M2 -> meta-intel/1.1_M2 - * [new branch] bernard -> meta-intel/bernard - * [new branch] dvhart/n450 -> meta-intel/dvhart/n450 - * [new branch] laverne -> meta-intel/laverne - * [new branch] master -> meta-intel/master + $cd poky + $ git clone git://git.yoctoproject.org/meta-intel.git + Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/ + remote: Counting objects: 1325, done. + remote: Compressing objects: 100% (1078/1078), done. + remote: Total 1325 (delta 546), reused 85 (delta 27) + Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done. + Resolving deltas: 100% (546/546), done. - Once you have the repository set up, you have many development branches from - which you can work. - For this example we are going to use Bernard 5.0. + Because meta-intel is its own Git repository you will want + to be sure you are in the appropriate branch for your work. + For this example we are going to use the bernard branch. - /usr/local/yocto/meta-intel$ git checkout -b Bernard-5.0.1 meta-intel/bernard - Branch Bernard-5.0.1 set up to track remote branch bernard from meta-intel. - Switched to a new branch 'bernard-5.0.1' + $ cd meta-intel + $ git checkout -b bernard + Switched to a new branch 'bernard' @@ -271,20 +243,20 @@ 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 - new layer for your BSP. + Now that you have the Yocto Project and base BSP source you need to create a + new layer for your BSP. - 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. - In fact, a BSP is, in itself, a special type of layer. - Consider an application as another example that illustrates a layer. - Suppose you are creating an application that has library or other dependencies in - order for it to compile and run. - The layer, in this case, would be where all the recipes that define those dependencies - are kept. The key point for a layer is that it is an isolated area that contains - all the relevant information for the project that the Yocto Project build system knows about. + 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. + In fact, a BSP is, in itself, a special type of layer. + Consider an application as another example that illustrates a layer. + Suppose you are creating an application that has library or other dependencies in + order for it to compile and run. + The layer, in this case, would be where all the recipes that define those dependencies + are kept. The key point for a layer is that it is an isolated area that contains + all the relevant information for the project that the Yocto Project build system knows about. @@ -312,7 +284,8 @@ In the standard layout you will notice a suggested hierarchy for BSP kernel recipes, graphics recipes, and configuration information. You can see the standard layout for the Crown Bay BSP in this example by examining the - directory structure of meta-crownbay. + directory structure of the meta-crownbay layer inside the + meta-intel Git repository. @@ -321,11 +294,12 @@ For this example the new layer is named meta-mymachine. The name must follow the BSP layer naming convention, which is meta-<name>. - The following example assumes a meta-intel Git repository. + The following example assumes your working directory is meta-intel + inside the meta-intel Git repository. If you downloaded and expanded a Crown Bay tarball then you simply copy the resulting meta-crownbay directory structure to a location of your choice: - /usr/local/yocto/meta-intel$ cp -a meta-crownbay/ meta-mymachine + $ cp -a meta-crownbay/ meta-mymachine @@ -351,8 +325,8 @@ The following two commands result in a single machine configuration file named mymachine.conf. - /usr/local/yocto/meta-intel$ rm meta-mymachine/conf/machine/crownbay.conf - /usr/local/yocto/meta-intel$ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \ + $ rm meta-mymachine/conf/machine/crownbay.conf + $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \ meta-mymachine/conf/machine/mymachine.conf @@ -373,9 +347,9 @@ statements we need to know which kernel we are using. The PREFERRED_PROVIDER_virtual/kernel statement in the file specifies the kernel we are going to use. - We are going to use linux-yocto-stable. + We are going to use linux-yocto. The SRCREV statement pairs point to the exact machine branch - (commit) and meta branch in the Git repository. + (commit) and meta branch in the poky Git repository. Right now the SRCREV variables are as follows in mymachine.conf: @@ -486,10 +460,8 @@ the remaining one that supports no EMGD. These commands take care of the new layer’s BSP recipes: - /usr/local/yocto/meta-intel$ rm -rf \ - meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay - /usr/local/yocto/meta-intel$ mv \ - meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \ + $ rm -rf meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay + $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \ meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine @@ -498,8 +470,7 @@ For this example we want to remove anything that supports EMGD. The following command cleans up the recipes-graphics directory: - /usr/local/yocto/meta-intel$ rm –rf \ - meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-emgd* + $ rm –rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-emgd* @@ -509,8 +480,7 @@ However, we still need to rename a directory in the layer. This command applies the final change to the recipes-graphics directory: - /usr/local/yocto/meta-intel$ mv \ - meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \ + $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \ meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine @@ -522,11 +492,9 @@ The other files all support the EMGD feature of Crown Bay. These commands clean up the directory: - /usr/local/yocto/meta-intel$ rm –rf meta-mymachine/recipes-kernel/linux/linux-yocto - /usr/local/yocto/meta-intel$ rm –rf \ - meta-mymachine/recipes-kernel/linux/linux-yocto-stable - /usr/local/yocto/meta-intel$ rm \ - meta-mymachine/recipes-kernel/linux/linux-yocto_git.bbappend + $ rm –rf meta-mymachine/recipes-kernel/linux/linux-yocto + $ rm –rf meta-mymachine/recipes-kernel/linux/linux-yocto-stable + $ rm meta-mymachine/recipes-kernel/linux/linux-yocto_git.bbappend @@ -595,18 +563,20 @@ Get the environment ready for the build by sourcing the environment script. - The environment script is in the Yocto Project source directory and has the string + The environment script is in the Yocto Project source directory + (poky in this example) and has the string init-build-env in the file’s name. For this example, the following command gets the build environment ready: - /usr/local/yocto$ source oe-init-build-env yocto-build + $ source oe-init-build-env yocto-build 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. 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. - The build directory contains a conf directory that contains + If you do not provide a name for the build directory it defaults to + build. + The build directory contains a conf directory that has two configuration files you will need to check: bblayers.conf and local.conf. Check and edit the resulting local.conf file. @@ -625,11 +595,10 @@ Update the bblayers.conf file so that it includes the path to your new BSP layer. In this example you need to include the pathname to meta-mymachine. - For example, if you created a Yocto Project Git repository named - yocto in /usr/local then the + For this example the BBLAYERS variable in the file would need to include the following path: - /usr/local/yocto/meta-intel/meta-mymachine + $HOME/poky/meta-intel/meta-mymachine @@ -661,7 +630,7 @@ You can find these recipes in the meta/recipes-core/images and meta/recipes-sato/images directories of the Yocto Project source - tree or Git repository. + tree (the poky Git repository in this example). Although the recipe names are somewhat explanatory, here is a list that describes them: Base – A foundational basic image without support @@ -709,7 +678,7 @@ For example, moving your working directory around could cause problems. Here is the command for this example: -/usr/local/yocto/yocto-build$ bitbake –k poky-image-sato-live + $ bitbake –k poky-image-sato-live @@ -806,48 +775,50 @@ -
- Modifying a Kernel +
+ Modifying a Kernel Example The remainder of this section presents a simple example that modifies a kernel. For the purpose of this example we are going to base our new kernel on the current Linux Yocto 2.6.37 release. + - - [WRITER'S NOTE: This section is a second example that focuses on just modifying the kernel. - I don't have any information on this yet. - + + [WRITER'S NOTE: This section is a second example that focuses on just modifying the kernel. + I don't have any information on this yet. + - - Here are some points to consider though: - - Reference Darren's presentation - - here - Reference Getting Started with the Yocto Project - section to get set up at minimum. - Are there extra steps I need specific to kernel development to get started? - What do I do to get set up? - Is it a matter of just installing YP and having some pieces together? - What are the pieces? - Where do I get the base kernel to start with? - Do I install the appropriate toolchain? - What kernel git repository do I use? - What is the conversion script? - What does it do? - What do I have to do to integrate the kernel layer? - What do I use to integrate the kernel layer? - HOB? - Do I just Bitbake it? - Using the System Image Creator.] - - + + Here are some points to consider though: + + Reference Darren's presentation + + here + Reference Getting Started with the Yocto Project + section to get set up at minimum. + Are there extra steps I need specific to kernel development to get started? + What do I do to get set up? + Is it a matter of just installing YP and having some pieces together? + What are the pieces? + Where do I get the base kernel to start with? + Do I install the appropriate toolchain? + What kernel git repository do I use? + What is the conversion script? + What does it do? + What do I have to do to integrate the kernel layer? + What do I use to integrate the kernel layer? + HOB? + Do I just Bitbake it? + Using the System Image Creator.] + + +
@@ -861,7 +832,8 @@ User-space Application Development scenario overview. Using the Yocto Eclipse Plug-in. Back-door support. - I feel there is more to this area than we have captured during our two review meetings.] + I feel there is more to this area than we have captured during our two + review meetings.] -- cgit v1.2.3-54-g00ecf