diff options
| author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2011-07-27 10:39:56 -0700 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2011-08-04 15:06:46 +0100 |
| commit | 5b8301a3b835890808e22d0fe34caac5ae5071d6 (patch) | |
| tree | e1b9f6fd39a7379e6fe6fc1ac581fe88c3642844 /documentation | |
| parent | b67922f0c3ef71629a880ec618e632c7c2bf4c13 (diff) | |
| download | poky-5b8301a3b835890808e22d0fe34caac5ae5071d6.tar.gz | |
documentation/dev-manual/dev-manual-cases.xml: generalized the BSP case
Because the BSP example is now in an appendix, I re-wrote this section
to overview the case.
(From yocto-docs rev: c0d88c6050bd17d65d8fe8c8abb227998fd4c11e)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/dev-manual/dev-manual-cases.xml | 842 |
1 files changed, 155 insertions, 687 deletions
diff --git a/documentation/dev-manual/dev-manual-cases.xml b/documentation/dev-manual/dev-manual-cases.xml index 28d48d0c9e..ebc8eeca1e 100644 --- a/documentation/dev-manual/dev-manual-cases.xml +++ b/documentation/dev-manual/dev-manual-cases.xml | |||
| @@ -15,6 +15,11 @@ | |||
| 15 | </para> | 15 | </para> |
| 16 | 16 | ||
| 17 | <para> | 17 | <para> |
| 18 | This chapter presents an overview of the primary cases. | ||
| 19 | Supsequent appendices in the manual provide detailed explanations of the examples. | ||
| 20 | </para> | ||
| 21 | |||
| 22 | <para> | ||
| 18 | [WRITERS NOTE: What is undetermined at this point is how much of the entire development process | 23 | [WRITERS NOTE: What is undetermined at this point is how much of the entire development process |
| 19 | we include in this particular chapter. | 24 | we include in this particular chapter. |
| 20 | In other words, do we cover debugging and emulation steps here on a case-specific basis? | 25 | In other words, do we cover debugging and emulation steps here on a case-specific basis? |
| @@ -53,701 +58,164 @@ | |||
| 53 | </note> | 58 | </note> |
| 54 | 59 | ||
| 55 | <para> | 60 | <para> |
| 61 | The remainder of this section presents the basic steps to create a BSP basing it on an | ||
| 62 | existing BSP that ships with the Yocto Project. | ||
| 63 | You can reference <xref linkend='dev-manual-bsp-appendix'>BSP Development Case</xref> | ||
| 64 | for a detailed example that uses the Crown Bay BSP as a base BSP from which to start. | ||
| 65 | </para> | ||
| 66 | |||
| 67 | <para> | ||
| 56 | Here are the basic steps involved in creating a BSP: | 68 | Here are the basic steps involved in creating a BSP: |
| 57 | <orderedlist> | 69 | <orderedlist> |
| 58 | <listitem><para>Be sure your host development system is set up to support | 70 | <listitem><para><emphasis>Set up your host development system to support |
| 59 | development using the Yocto Project. | 71 | development using the Yocto Project</emphasis>: See |
| 60 | See | ||
| 61 | <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'> | 72 | <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'> |
| 62 | The Linux Distributions</ulink> section and | 73 | The Linux Distributions</ulink> section and |
| 63 | <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'> | 74 | <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'> |
| 64 | The Packages</ulink> section both | 75 | The Packages</ulink> section both |
| 65 | in the Yocto Project Quick Start for requirements. | 76 | in the Yocto Project Quick Start for requirements. |
| 66 | You will also need a release of Yocto Project installed on the host.</para></listitem> | 77 | You will also need a release of Yocto Project installed on the host.</para></listitem> |
| 67 | <listitem><para>Choose a BSP available with Yocto Project that most closely represents | 78 | <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your |
| 68 | your hardware.</para></listitem> | 79 | system</emphasis>: You need to have the Yocto Project files available on your host system. |
| 69 | <listitem><para>Get set up with a base BSP.</para></listitem> | 80 | Having the Yocto Project files on your system gives you access to the build |
| 70 | <listitem><para>Make a copy of the existing BSP and isolate your work by creating a layer | 81 | process and tools you need. |
| 71 | for your recipes.</para></listitem> | 82 | For information on how to get these files, see the |
| 72 | <listitem><para>Make configuration and recipe changes to your new BSP layer.</para></listitem> | 83 | <xref linkend='getting-setup'>Getting Setup</xref> section in this manual.</para></listitem> |
| 73 | <listitem><para>Prepare for the build.</para></listitem> | 84 | <listitem><para><emphasis>Choose a Yocto Project-supported BSP as your base BSP</emphasis>: |
| 74 | <listitem><para>Select and configure the kernel.</para></listitem> | 85 | The Yocto Project ships with several BSPs that support various hardware. |
| 75 | <listitem><para>Identify the machine branch.</para></listitem> | 86 | It is best to base your new BSP on an existing BSP rather than create all the |
| 76 | <listitem><para>Build the image.</para></listitem> | 87 | recipes and configuration files from scratch. |
| 88 | While it is possible to create everything from scratch, basing your new BSP | ||
| 89 | on something that is close is much easier. | ||
| 90 | Or, at a minimum, it gives you some structure with which to start.</para> | ||
| 91 | <para>At this point you need to understand your target hardware well enough to determine which | ||
| 92 | existing BSP it most closely matches. | ||
| 93 | Things to consider are your hardware’s on-board features such as CPU type and graphics support. | ||
| 94 | You should look at the README files for supported BSPs to get an idea of which one | ||
| 95 | you could use. | ||
| 96 | A generic Atom-based BSP to consider is the Crown Bay that does not support | ||
| 97 | the Intel® Embedded Media Graphics Driver (EMGD). | ||
| 98 | The remainder of this example uses that base BSP.</para> | ||
| 99 | <para>To see the supported BSPs, go to the Yocto Project | ||
| 100 | <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click | ||
| 101 | on “BSP Downloads.”</para></listitem> | ||
| 102 | <listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>: Having | ||
| 103 | the BSP files on your system gives you access to the build | ||
| 104 | process and tools you need. | ||
| 105 | For information on how to get these files, see | ||
| 106 | <xref linkend='getting-setup'>Getting Setup</xref> earlier in this manual.</para></listitem> | ||
| 107 | <listitem><para><emphasis>Create your own BSP layer</emphasis>: Layers are ideal for | ||
| 108 | isolating and storing work for a given piece of hardware. | ||
| 109 | A layer is really just a location or area in which you place the recipes for your BSP. | ||
| 110 | In fact, a BSP is, in itself, a special type of layer. | ||
| 111 | Consider an application as another example that illustrates a layer. | ||
| 112 | Suppose you are creating an application that has library or other dependencies in | ||
| 113 | order for it to compile and run. | ||
| 114 | The layer, in this case, would be where all the recipes that define those dependencies | ||
| 115 | are kept. The key point for a layer is that it is an isolated area that contains | ||
| 116 | all the relevant information for the project that the Yocto Project build | ||
| 117 | system knows about.</para> | ||
| 118 | <note>The Yocto Project supports four BSPs that are part of the | ||
| 119 | Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>, | ||
| 120 | <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>. | ||
| 121 | The recipes and configurations for these four BSPs are located and dispersed | ||
| 122 | within local Yocto Project files. | ||
| 123 | Consequently, they are not totally isolated in the spirit of layers unless you think | ||
| 124 | of <filename>meta-yocto</filename> as a layer itself. | ||
| 125 | On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest, | ||
| 126 | N450, and Sugar Bay are isolated.</note> | ||
| 127 | <para>When you set up a layer for a new BSP you should follow a standard layout. | ||
| 128 | This layout is described in the | ||
| 129 | <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'> | ||
| 130 | Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development | ||
| 131 | Guide. | ||
| 132 | In the standard layout you will notice a suggested structure for recipes and | ||
| 133 | configuration information. | ||
| 134 | You can see the standard layout for the Crown Bay BSP in this example by examining the | ||
| 135 | directory structure of the <filename>meta-crownbay</filename> layer inside the | ||
| 136 | local Yocto Project files.</para></listitem> | ||
| 137 | <listitem><para><emphasis>Make configuration and recipe changes to your new BSP | ||
| 138 | layer</emphasis>: The standard BSP layer structure organizes the files you need to edit in | ||
| 139 | <filename>conf</filename> and several <filename>recipes-*</filename> within the | ||
| 140 | BSP layer.</para> | ||
| 141 | <para>Configuration changes identify where your new layer is on the local system | ||
| 142 | and identify which kernel you are going to use. | ||
| 143 | Recipe changes include altering recipes (<filename>.bb</filename> files), removing | ||
| 144 | recipes you don't use, and adding new recipes that you need to support your hardware. | ||
| 145 | </para></listitem> | ||
| 146 | <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the | ||
| 147 | changes to your BSP layer there remains a few things | ||
| 148 | you need to do for the Yocto Project build system in order for it to create your image. | ||
| 149 | You need to get the build environment ready by sourcing an environment setup script | ||
| 150 | and you need to be sure two key configuration files are configured appropriately.</para> | ||
| 151 | <para>The entire process for building an image is overviewed in the | ||
| 152 | <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'> | ||
| 153 | Building an Image</ulink> section of the Yocto Project Quick Start. | ||
| 154 | You might want to reference this information.</para></listitem> | ||
| 155 | <listitem><para><emphasis>Build the image</emphasis>: The Yocto Project uses the BitBake | ||
| 156 | tool to build images based on the type of image | ||
| 157 | you want to create. | ||
| 158 | You can find more information on BitBake | ||
| 159 | <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> | ||
| 160 | <para>The build process supports several types of images to satisfy different needs. | ||
| 161 | When you issue the BitBake command you provide a “top-level” recipe that essentially | ||
| 162 | starts the process off of building the type of image you want.</para> | ||
| 163 | <para>[WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]</para> | ||
| 164 | <para>You can find these recipes in the <filename>meta/recipes-core/images</filename> and | ||
| 165 | <filename>meta/recipes-sato/images</filename> directories of your local Yocto Project | ||
| 166 | file structure (Git repository or extracted release tarball). | ||
| 167 | Although the recipe names are somewhat explanatory, here is a list that describes them: | ||
| 168 | <itemizedlist> | ||
| 169 | <listitem><para><emphasis>Base</emphasis> – A foundational basic image without support | ||
| 170 | for X that can be reasonably used for customization.</para></listitem> | ||
| 171 | <listitem><para><emphasis>Core</emphasis> – A foundational basic image with support for | ||
| 172 | X that can be reasonably used for customization.</para></listitem> | ||
| 173 | <listitem><para><emphasis>Direct Disk</emphasis> – An image that you can copy directory to | ||
| 174 | the disk of the target device.</para></listitem> | ||
| 175 | <listitem><para><emphasis>Live</emphasis> – An image you can run from a USB device or from | ||
| 176 | a CD without having to first install something.</para></listitem> | ||
| 177 | <listitem><para><emphasis>Minimal</emphasis> – A small image without a GUI. | ||
| 178 | This image is not much more than a kernel with a shell.</para></listitem> | ||
| 179 | <listitem><para><emphasis>Minimal Development</emphasis> – A Minimal image suitable for | ||
| 180 | development work.</para></listitem> | ||
| 181 | <listitem><para><emphasis>Minimal Direct Disk</emphasis> – A Minimal Direct | ||
| 182 | Disk image.</para></listitem> | ||
| 183 | <listitem><para><emphasis>Minimal RAM-based Initial Root Filesystem</emphasis> – | ||
| 184 | A minimal image | ||
| 185 | that has the <filename>initramfs</filename> as part of the kernel, which allows the | ||
| 186 | system to find the first “init” program more efficiently.</para></listitem> | ||
| 187 | <listitem><para><emphasis>Minimal Live</emphasis> – A Minimal Live image.</para></listitem> | ||
| 188 | <listitem><para><emphasis>Minimal MTD Utilities</emphasis> – A minimal image that has support | ||
| 189 | for the MTD utilities, which let the user interact with the MTD subsystem in | ||
| 190 | the kernel to perform operations on flash devices.</para></listitem> | ||
| 191 | <listitem><para><emphasis>Sato</emphasis> – An image with Sato support, a mobile environment | ||
| 192 | and visual style that works well with mobile devices.</para></listitem> | ||
| 193 | <listitem><para><emphasis>Sato Development</emphasis> – A Sato image suitable for | ||
| 194 | development work.</para></listitem> | ||
| 195 | <listitem><para><emphasis>Sato Direct Disk</emphasis> – A Sato Direct | ||
| 196 | Disk image.</para></listitem> | ||
| 197 | <listitem><para><emphasis>Sato Live</emphasis> – A Sato Live image.</para></listitem> | ||
| 198 | <listitem><para><emphasis>Sato SDK</emphasis> – A Sato image that includes the Yocto Project | ||
| 199 | toolchain and development libraries.</para></listitem> | ||
| 200 | <listitem><para><emphasis>Sato SDK Direct Disk</emphasis> – A Sato SDK Direct | ||
| 201 | Disk image.</para></listitem> | ||
| 202 | <listitem><para><emphasis>Sato SDK Live</emphasis> – A Sato SDK Live | ||
| 203 | image.</para></listitem> | ||
| 204 | </itemizedlist> | ||
| 205 | </para></listitem> | ||
| 77 | </orderedlist> | 206 | </orderedlist> |
| 78 | You can view a video presentation of the BSP creation process | ||
| 79 | <ulink url='http://free-electrons.com/blog/elc-2011-videos'>here</ulink>. | ||
| 80 | You can also find supplemental information in the | ||
| 81 | <ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'> | ||
| 82 | Board Support Package (BSP) Development Guide</ulink>. | ||
| 83 | Finally, there is wiki page write up of the example located | ||
| 84 | <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'> | ||
| 85 | here</ulink> you might find helpful. | ||
| 86 | </para> | 207 | </para> |
| 87 | 208 | ||
| 88 | <section id='setting-up-yocto-project'> | 209 | <para> |
| 89 | <title>Setting Up Yocto Project</title> | 210 | You can view a video presentation of the BSP creation process |
| 90 | 211 | <ulink url='http://free-electrons.com/blog/elc-2011-videos'>here</ulink>. | |
| 91 | <para> | 212 | You can also find supplemental information in the |
| 92 | You need to have the Yocto Project files available on your host system. | 213 | <ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'> |
| 93 | You can get files through tarball extraction or by cloning the <filename>poky</filename> | 214 | Board Support Package (BSP) Development Guide</ulink>. |
| 94 | Git repository. | 215 | Finally, there is wiki page write up of the example located |
| 95 | Typically, cloning the Git repository is the method to use. | 216 | <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'> |
| 96 | This allows you to maintain a complete history of changes and facilitates you | 217 | here</ulink> you might find helpful. |
| 97 | contributing back to the Yocto Project. | 218 | </para> |
| 98 | However, if you just want a hierarchical file structure that contains the recipes | ||
| 99 | and metadata that let you develop you can download tarballs from the | ||
| 100 | <ulink url='http://yoctoproject.org/download'>download page</ulink>. | ||
| 101 | </para> | ||
| 102 | |||
| 103 | <para> | ||
| 104 | Regardless of the method you use this manual will refer to the resulting | ||
| 105 | hierarchical set of files as "the local Yocto Project files." | ||
| 106 | </para> | ||
| 107 | |||
| 108 | <para> | ||
| 109 | [WRITER'S NOTE: I need to substitute correct and actual filenames for the | ||
| 110 | 1.1 release throughout this example once they become available.] | ||
| 111 | </para> | ||
| 112 | |||
| 113 | <para> | ||
| 114 | If you download a tarball you can extract it into any directory you want using the | ||
| 115 | tar command. | ||
| 116 | For example, the following command extracts the Yocto Project 1.1 release tarball | ||
| 117 | into the current working directory and sets up a file structure whose top-level | ||
| 118 | directory is named <filename>poky-1.1</filename>: | ||
| 119 | <literallayout class='monospaced'> | ||
| 120 | $ tar xfj poky-1.1.tar.bz2 | ||
| 121 | </literallayout> | ||
| 122 | </para> | ||
| 123 | |||
| 124 | <para> | ||
| 125 | The following transcript shows how to clone the <filename>poky</filename> Git repository | ||
| 126 | into the current working directory. | ||
| 127 | The command creates the repository in a directory named <filename>poky</filename>: | ||
| 128 | <literallayout class='monospaced'> | ||
| 129 | $ git clone git://git.yoctoproject.org/poky | ||
| 130 | Initialized empty Git repository in /home/scottrif/poky/.git/ | ||
| 131 | remote: Counting objects: 107624, done. | ||
| 132 | remote: Compressing objects: 100% (37128/37128), done. | ||
| 133 | remote: Total 107624 (delta 73393), reused 99851 (delta 67287) | ||
| 134 | Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done. | ||
| 135 | Resolving deltas: 100% (73393/73393), done. | ||
| 136 | </literallayout> | ||
| 137 | </para> | ||
| 138 | |||
| 139 | <para> | ||
| 140 | Once you have the local <filename>poky</filename> Git repository set up, | ||
| 141 | you have many development branches from which you can work. | ||
| 142 | From inside the repository you can see the branch names and the tag names used | ||
| 143 | in the Git repository using either of the following two commands: | ||
| 144 | <literallayout class='monospaced'> | ||
| 145 | $ git branch -a | ||
| 146 | $ git tag -l | ||
| 147 | </literallayout> | ||
| 148 | For this example we are going to use the Yocto Project 1.1 Release, | ||
| 149 | which maps to the <filename>1.1</filename> branch in the repository. | ||
| 150 | These commands create a local branch named <filename>1.1</filename> | ||
| 151 | that tracks the remote branch of the same name. | ||
| 152 | <literallayout class='monospaced'> | ||
| 153 | |||
| 154 | $ cd poky | ||
| 155 | $ git checkout -b 1.1 origin/1.1 | ||
| 156 | Switched to a new branch '1.1' | ||
| 157 | </literallayout> | ||
| 158 | </para> | ||
| 159 | </section> | ||
| 160 | |||
| 161 | <section id='choosing-a-base-bsp'> | ||
| 162 | <title>Choosing a Base BSP</title> | ||
| 163 | |||
| 164 | <para> | ||
| 165 | The Yocto Project ships with several BSPs that support various hardware. | ||
| 166 | It is best to base your new BSP on an existing BSP rather than create all the | ||
| 167 | recipes and configuration files from scratch. | ||
| 168 | While it is possible to create everything from scratch, basing your new BSP | ||
| 169 | on something that is close is much easier. | ||
| 170 | Or, at a minimum, it gives you some structure with which to start. | ||
| 171 | </para> | ||
| 172 | |||
| 173 | <para> | ||
| 174 | At this point you need to understand your target hardware well enough to determine which | ||
| 175 | existing BSP it most closely matches. | ||
| 176 | Things to consider are your hardware’s on-board features such as CPU type and graphics support. | ||
| 177 | You should look at the README files for supported BSPs to get an idea of which one | ||
| 178 | you could use. | ||
| 179 | A generic Atom-based BSP to consider is the Crown Bay that does not support | ||
| 180 | the Intel® Embedded Media Graphics Driver (EMGD). | ||
| 181 | The remainder of this example uses that base BSP. | ||
| 182 | </para> | ||
| 183 | |||
| 184 | <para> | ||
| 185 | To see the supported BSPs, go to the Yocto Project | ||
| 186 | <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click | ||
| 187 | on “BSP Downloads.” | ||
| 188 | </para> | ||
| 189 | </section> | ||
| 190 | |||
| 191 | <section id='getting-your-base-bsp'> | ||
| 192 | <title>Getting Your Base BSP</title> | ||
| 193 | |||
| 194 | <para> | ||
| 195 | You need to have the base BSP layer on your development system. | ||
| 196 | Like the local Yocto Project files, you can get the BSP | ||
| 197 | layer one of two ways: | ||
| 198 | download the BSP tarball and extract it, or set up a local Git repository that | ||
| 199 | has the Yocto Project BSP layers. | ||
| 200 | You should use the same method that you used to get the local Yocto Project files earlier. | ||
| 201 | </para> | ||
| 202 | |||
| 203 | <para> | ||
| 204 | If you are using tarball extraction, simply download the tarball for the base | ||
| 205 | BSP you chose in the previous step and then extract it into any directory | ||
| 206 | you choose using the tar command. | ||
| 207 | Upon extraction, the BSP source directory (layer) will be named | ||
| 208 | <filename>meta-<BSP_name></filename>. | ||
| 209 | The following command extracts the Crown Bay BSP into the current directory and names it | ||
| 210 | <filename>meta-crownbay</filename>: | ||
| 211 | <literallayout class='monospaced'> | ||
| 212 | $ tar xjf crownbay-noemgd-1.1.tar.bz2 | ||
| 213 | </literallayout> | ||
| 214 | </para> | ||
| 215 | |||
| 216 | <para> | ||
| 217 | If you cloned a <filename>poky</filename> Git repository | ||
| 218 | then you need to set up a different local Git repository | ||
| 219 | (<filename>meta-intel</filename>) for the BSP. | ||
| 220 | The <filename>meta-intel</filename> Git repository contains all the metadata | ||
| 221 | that supports BSP creation. | ||
| 222 | When you set up the <filename>meta-intel</filename> Git repository you can | ||
| 223 | set it up anywhere you want. | ||
| 224 | We will set up the repository inside the | ||
| 225 | <filename>poky</filename> Git repository in this example. | ||
| 226 | </para> | ||
| 227 | |||
| 228 | <para> | ||
| 229 | The following transcript shows the steps to clone the <filename>meta-intel</filename> | ||
| 230 | Git repository inside the <filename>poky</filename> Git repository created earlier in this | ||
| 231 | example. | ||
| 232 | <literallayout class='monospaced'> | ||
| 233 | $cd poky | ||
| 234 | $ git clone git://git.yoctoproject.org/meta-intel.git | ||
| 235 | Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/ | ||
| 236 | remote: Counting objects: 1325, done. | ||
| 237 | remote: Compressing objects: 100% (1078/1078), done. | ||
| 238 | remote: Total 1325 (delta 546), reused 85 (delta 27) | ||
| 239 | Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done. | ||
| 240 | Resolving deltas: 100% (546/546), done. | ||
| 241 | </literallayout> | ||
| 242 | </para> | ||
| 243 | |||
| 244 | <para> | ||
| 245 | Because <filename>meta-intel</filename> is its own Git repository you will want | ||
| 246 | to be sure you are in the appropriate branch for your work. | ||
| 247 | For this example we are going to use the <filename>1.1</filename> branch. | ||
| 248 | <literallayout class='monospaced'> | ||
| 249 | $ cd meta-intel | ||
| 250 | $ git checkout -b 1.1 origin/1.1 | ||
| 251 | Switched to a new branch 'bernard' | ||
| 252 | </literallayout> | ||
| 253 | </para> | ||
| 254 | </section> | ||
| 255 | |||
| 256 | <section id='making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer'> | ||
| 257 | <title>Making a Copy of the Base BSP to Create Your New BSP Layer</title> | ||
| 258 | |||
| 259 | <para> | ||
| 260 | Now that you have the local Yocto Project files and the base BSP files you need to create a | ||
| 261 | new layer for your BSP. | ||
| 262 | </para> | ||
| 263 | |||
| 264 | <para> | ||
| 265 | Layers are ideal for isolating and storing work for a given piece of hardware. | ||
| 266 | A layer is really just a location or area in which you place the recipes for your BSP. | ||
| 267 | In fact, a BSP is, in itself, a special type of layer. | ||
| 268 | Consider an application as another example that illustrates a layer. | ||
| 269 | Suppose you are creating an application that has library or other dependencies in | ||
| 270 | order for it to compile and run. | ||
| 271 | The layer, in this case, would be where all the recipes that define those dependencies | ||
| 272 | are kept. The key point for a layer is that it is an isolated area that contains | ||
| 273 | all the relevant information for the project that the Yocto Project build system knows about. | ||
| 274 | </para> | ||
| 275 | |||
| 276 | <note> | ||
| 277 | The Yocto Project supports four BSPs that are part of the | ||
| 278 | Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>, | ||
| 279 | <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>. | ||
| 280 | The recipes and configurations for these four BSPs are located and dispersed | ||
| 281 | within local Yocto Project files. | ||
| 282 | Consequently, they are not totally isolated in the spirit of layers unless you think | ||
| 283 | of <filename>meta-yocto</filename> as a layer itself. | ||
| 284 | On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest, | ||
| 285 | N450, and Sugar Bay are isolated. | ||
| 286 | </note> | ||
| 287 | |||
| 288 | <para> | ||
| 289 | When you set up a layer for a new BSP you should follow a standard layout. | ||
| 290 | This layout is described in the | ||
| 291 | <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'> | ||
| 292 | Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development | ||
| 293 | Guide. | ||
| 294 | In the standard layout you will notice a suggested structure for recipes and | ||
| 295 | configuration information. | ||
| 296 | You can see the standard layout for the Crown Bay BSP in this example by examining the | ||
| 297 | directory structure of the <filename>meta-crownbay</filename> layer inside the | ||
| 298 | local Yocto Project files. | ||
| 299 | </para> | ||
| 300 | |||
| 301 | <para> | ||
| 302 | To create your BSP layer you simply copy the <filename>meta-crownbay</filename> | ||
| 303 | layer to a new layer. | ||
| 304 | For this example the new layer will be named <filename>meta-mymachine</filename>. | ||
| 305 | The name must follow the BSP layer naming convention, which is | ||
| 306 | <filename>meta-<name></filename>. | ||
| 307 | The following example assumes your working directory is <filename>meta-intel</filename> | ||
| 308 | inside the local Yocto Project files. | ||
| 309 | If you downloaded and expanded a Crown Bay tarball then you simply copy the resulting | ||
| 310 | <filename>meta-crownbay</filename> directory structure to a location of your choice. | ||
| 311 | Good practice for a Git repository, however, is to just copy the new layer alongside | ||
| 312 | the existing | ||
| 313 | BSP layers in the <filename>meta-intel</filename> Git repository: | ||
| 314 | <literallayout class='monospaced'> | ||
| 315 | $ cp -a meta-crownbay/ meta-mymachine | ||
| 316 | </literallayout> | ||
| 317 | </para> | ||
| 318 | </section> | ||
| 319 | |||
| 320 | <section id='making-changes-to-your-bsp'> | ||
| 321 | <title>Making Changes to Your BSP</title> | ||
| 322 | |||
| 323 | <para> | ||
| 324 | Right now you have two identical BSP layers with different names: | ||
| 325 | <filename>meta-crownbay</filename> and <filename>meta-mymachine</filename>. | ||
| 326 | You need to change your configurations so that they work for your new BSP and | ||
| 327 | your particular hardware. | ||
| 328 | We will look first at the configurations, which are all done in the layer’s | ||
| 329 | <filename>conf</filename> directory. | ||
| 330 | </para> | ||
| 331 | |||
| 332 | <para> | ||
| 333 | First, since in this example the new BSP will not support EMGD we will get rid of the | ||
| 334 | <filename>crownbay.conf</filename> file and then rename the | ||
| 335 | <filename>crownbay-noemgd.conf</filename> file to <filename>mymachine.conf</filename>. | ||
| 336 | Much of what we do in the configuration directory is designed to help the Yocto Project | ||
| 337 | build system work with the new layer and to be able to find and use the right software. | ||
| 338 | The following two commands result in a single machine configuration file named | ||
| 339 | <filename>mymachine.conf</filename>. | ||
| 340 | <literallayout class='monospaced'> | ||
| 341 | $ rm meta-mymachine/conf/machine/crownbay.conf | ||
| 342 | $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \ | ||
| 343 | meta-mymachine/conf/machine/mymachine.conf | ||
| 344 | </literallayout> | ||
| 345 | </para> | ||
| 346 | |||
| 347 | <para> | ||
| 348 | The next step makes changes to <filename>mymachine.conf</filename> itself. | ||
| 349 | The only changes needed for this example are changes to the comment lines. | ||
| 350 | Here we simply substitute the Crown Bay name with an appropriate name. | ||
| 351 | </para> | ||
| 352 | |||
| 353 | <para> | ||
| 354 | Note that inside the <filename>mymachine.conf</filename> is the | ||
| 355 | <filename>PREFERRED_PROVIDER_virtual/kernel</filename> statement. | ||
| 356 | This statement identifies the kernel that the BSP is going to use. | ||
| 357 | In this case the BSP is using <filename>linux-yocto</filename>, which is the | ||
| 358 | current Linux Yocto kernel based on the Linux 2.6.37 release. | ||
| 359 | </para> | ||
| 360 | |||
| 361 | <para> | ||
| 362 | The next configuration file in the new BSP layer we need to edit is <filename>layer.conf</filename>. | ||
| 363 | This file identifies build information needed for the new layer. | ||
| 364 | You can see the | ||
| 365 | <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout-layer'> | ||
| 366 | Layer Configuration File</ulink> section in the Board Support Packages (BSP) Development Guide | ||
| 367 | for more information on this configuration file. | ||
| 368 | Basically, we are changing the existing statements to work with our BSP. | ||
| 369 | </para> | ||
| 370 | |||
| 371 | <para> | ||
| 372 | The file contains these statements that reference the Crown Bay BSP: | ||
| 373 | <literallayout class='monospaced'> | ||
| 374 | BBFILE_COLLECTIONS += "crownbay" | ||
| 375 | BBFILE_PATTERN_crownbay := "^${LAYERDIR}/" | ||
| 376 | BBFILE_PRIORITY_crownbay = "6" | ||
| 377 | </literallayout> | ||
| 378 | </para> | ||
| 379 | |||
| 380 | <para> | ||
| 381 | Simply substitute the machine string name <filename>crownbay</filename> | ||
| 382 | with the new machine name <filename>mymachine</filename> to get the following: | ||
| 383 | <literallayout class='monospaced'> | ||
| 384 | BBFILE_COLLECTIONS_mymachine += "mymachine" | ||
| 385 | BBFILE_PATTERN_mymachine := "^${LAYERDIR}/" | ||
| 386 | BBFILE_PRIORITY_mymachine = "6" | ||
| 387 | </literallayout> | ||
| 388 | </para> | ||
| 389 | |||
| 390 | <para> | ||
| 391 | Now we will take a look at the recipes in your new layer. | ||
| 392 | The standard BSP structure has areas for BSP, graphics, core, and kernel recipes. | ||
| 393 | When you create a BSP you use these areas for appropriate recipes and append files. | ||
| 394 | Recipes take the form of <filename>.bb</filename> files. | ||
| 395 | If you want to leverage the existing recipes the Yocto Project build system uses | ||
| 396 | but change those recipes you can use <filename>.bbappend</filename> files. | ||
| 397 | All new recipes and append files for your layer must go in the layer’s | ||
| 398 | <filename>recipes-bsp</filename>, <filename>recipes-kernel</filename>, | ||
| 399 | <filename>recipes-core</filename>, and | ||
| 400 | <filename>recipes-graphics</filename> directories. | ||
| 401 | </para> | ||
| 402 | |||
| 403 | <para> | ||
| 404 | First, let's look at <filename>recipes-bsp</filename>. | ||
| 405 | For this example we are not adding any new BSP recipes. | ||
| 406 | And, we only need to remove the formfactor we do not want and change the name of | ||
| 407 | the remaining one that doesn't support EMGD. | ||
| 408 | These commands take care of the <filename>recipes-bsp</filename> recipes: | ||
| 409 | <literallayout class='monospaced'> | ||
| 410 | $ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/*emgd* | ||
| 411 | $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \ | ||
| 412 | meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine | ||
| 413 | </literallayout> | ||
| 414 | </para> | ||
| 415 | |||
| 416 | <para> | ||
| 417 | Now let's look at <filename>recipes-graphics</filename>. | ||
| 418 | For this example we want to remove anything that supports EMGD and | ||
| 419 | be sure to rename remaining directories appropriately. | ||
| 420 | The following commands clean up the <filename>recipes-graphics</filename> directory: | ||
| 421 | <literallayout class='monospaced'> | ||
| 422 | $ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-emgd* | ||
| 423 | $ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay | ||
| 424 | $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \ | ||
| 425 | meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine | ||
| 426 | </literallayout> | ||
| 427 | </para> | ||
| 428 | |||
| 429 | <para> | ||
| 430 | At this point the <filename>recipes-graphics</filename> directory just has files that | ||
| 431 | support Video Electronics Standards Association (VESA) graphics modes and not EMGD. | ||
| 432 | </para> | ||
| 433 | |||
| 434 | <para> | ||
| 435 | Now let's look at changes in <filename>recipes-core</filename>. | ||
| 436 | The file <filename>task-core-tools.bbappend</filename> in | ||
| 437 | <filename>recipes-core/tasks</filename> appends the similarly named recipe | ||
| 438 | located in the local Yocto Project files at | ||
| 439 | <filename>meta/recipes-core/tasks</filename>. | ||
| 440 | The "append" file in our layer right now is Crown Bay-specific and supports | ||
| 441 | EMGD and non-EMGD. | ||
| 442 | Here are the contents of the file: | ||
| 443 | <literallayout class='monospaced'> | ||
| 444 | RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap" | ||
| 445 | RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap" | ||
| 446 | </literallayout> | ||
| 447 | </para> | ||
| 448 | |||
| 449 | <para> | ||
| 450 | The <filename>RRECOMMENDS</filename> statements list packages that | ||
| 451 | extend usability. | ||
| 452 | The first <filename>RRECOMMENDS</filename> statement can be removed, while the | ||
| 453 | second one can be changed to reflect <filename>meta-mymachine</filename>: | ||
| 454 | <literallayout class='monospaced'> | ||
| 455 | RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap" | ||
| 456 | </literallayout> | ||
| 457 | </para> | ||
| 458 | |||
| 459 | <para> | ||
| 460 | Finally, let's look at <filename>recipes-kernel</filename> changes. | ||
| 461 | Recall that the BSP uses the <filename>linux-yocto</filename> kernel as determined | ||
| 462 | earlier in the <filename>mymachine.conf</filename>. | ||
| 463 | The recipe for that kernel is not located in the | ||
| 464 | BSP layer but rather in the local Yocto Project files at | ||
| 465 | <filename>meta/recipes-kernel/linux</filename> and is | ||
| 466 | named <filename>linux-yocto-2.6.37.bb</filename>. | ||
| 467 | The <filename>SRCREV_machine</filename> and <filename>SRCREV_meta</filename> | ||
| 468 | statements point to the exact commits used by the Yocto Project development team | ||
| 469 | in their source repositories that identify the right kernel for our hardware. | ||
| 470 | </para> | ||
| 471 | |||
| 472 | <para> | ||
| 473 | However, in the <filename>meta-mymachine</filename> layer in | ||
| 474 | <filename>recipes-kernel/linux</filename> resides a <filename>.bbappend</filename> | ||
| 475 | file named <filename>linux-yocto-2.6.37.bbappend</filename> that | ||
| 476 | is appended to the recipe of the same name in <filename>meta/recipes-kernel/link</filename>. | ||
| 477 | Thus, the <filename>SRCREV</filename> statements in the "append" file override | ||
| 478 | the more general statements found in <filename>meta</filename>. | ||
| 479 | </para> | ||
| 480 | |||
| 481 | <para> | ||
| 482 | The <filename>SRCREV</filename> statements in the "append" file currently identify | ||
| 483 | the kernel that supports the Crown Bay BSP with and without EMGD support. | ||
| 484 | Here are the statements: | ||
| 485 | <literallayout class='monospaced'> | ||
| 486 | SRCREV_machine_pn-linux-yocto_crownbay ?= \ | ||
| 487 | "372c0ab135978bd8ca3a77c88816a25c5ed8f303" | ||
| 488 | SRCREV_meta_pn-linux-yocto_crownbay ?= \ | ||
| 489 | "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b" | ||
| 490 | |||
| 491 | SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= \ | ||
| 492 | "372c0ab135978bd8ca3a77c88816a25c5ed8f303" | ||
| 493 | SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \ | ||
| 494 | "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b" | ||
| 495 | </literallayout> | ||
| 496 | </para> | ||
| 497 | |||
| 498 | <para> | ||
| 499 | You will notice that there are two pairs of <filename>SRCREV</filename> statements. | ||
| 500 | The top pair identifies the kernel that supports | ||
| 501 | EMGD, which we don’t care about in this example. | ||
| 502 | The bottom pair identifies the kernel that we will use: | ||
| 503 | <filename>linux-yocto</filename>. | ||
| 504 | At this point though, the unique commit strings all are still associated with | ||
| 505 | Crown Bay and not <filename>meta-mymachine</filename>. | ||
| 506 | </para> | ||
| 507 | |||
| 508 | <para> | ||
| 509 | To fix this situation in <filename>linux-yocto-2.6.37.bbappend</filename> | ||
| 510 | we delete the two <filename>SRCREV</filename> statements that support | ||
| 511 | EMGD (the top pair). | ||
| 512 | We also change the remaining pair to specify <filename>mymachine</filename> | ||
| 513 | and insert the commit identifiers to identify the kernel in which we | ||
| 514 | are interested, which will be based on the <filename>atom-pc-standard</filename> | ||
| 515 | kernel. | ||
| 516 | Here are the final <filename>SRCREV</filename> statements: | ||
| 517 | <literallayout class='monospaced'> | ||
| 518 | SRCREV_machine_pn-linux-yocto-_mymachine ?= \ | ||
| 519 | "fce17f046d3756045e4dfb49221d1cf60fcae329" | ||
| 520 | SRCREV_meta_pn-linux-yocto-stable_mymachine ?= \ | ||
| 521 | "84f1a422d7e21fbc23a687035bdf9d42471f19e0" | ||
| 522 | </literallayout> | ||
| 523 | </para> | ||
| 524 | |||
| 525 | <para> | ||
| 526 | If you are familiar with Git repositories you probably won’t have trouble locating the | ||
| 527 | exact commit strings in the Yocto Project source repositories you need to change | ||
| 528 | the <filename>SRCREV</filename> statements. | ||
| 529 | You can find all the <filename>machine</filename> and <filename>meta</filename> | ||
| 530 | branch points (commits) for the <filename>linux-yocto-2.6.37</filename> kernel | ||
| 531 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.37'>here</ulink>. | ||
| 532 | </para> | ||
| 533 | |||
| 534 | <para> | ||
| 535 | If you need a little more assistance after going to the link then do the following: | ||
| 536 | <orderedlist> | ||
| 537 | <listitem><para>Expand the list of branches by clicking <filename>[…]</filename></para></listitem> | ||
| 538 | <listitem><para>Click on the <filename>yocto/standard/common-pc/atom-pc</filename> | ||
| 539 | branch</para></listitem> | ||
| 540 | <listitem><para>Click on the commit column header to view the top commit</para></listitem> | ||
| 541 | <listitem><para>Copy the commit string for use in the | ||
| 542 | <filename>linux-yocto-2.6.37.bbappend</filename> file</para></listitem> | ||
| 543 | </orderedlist> | ||
| 544 | </para> | ||
| 545 | |||
| 546 | <para> | ||
| 547 | For the <filename>SRCREV</filename> statement that points to the <filename>meta</filename> | ||
| 548 | branch use the same procedure except expand the <filename>meta</filename> | ||
| 549 | branch in step 2 above. | ||
| 550 | </para> | ||
| 551 | |||
| 552 | <para> | ||
| 553 | Also in the <filename>linux-yocto-2.6.37.bbappend</filename> file are | ||
| 554 | <filename>COMPATIBLE_MACHINE</filename>, <filename>KMACHINE</filename>, | ||
| 555 | and <filename>KERNEL_FEATURES</filename> statements. | ||
| 556 | Two sets of these exist: one set supports EMGD and one set does not. | ||
| 557 | Because we are not interested in supporting EMGD those three can be deleted. | ||
| 558 | The remaining three must be changed so that <filename>mymachine</filename> replaces | ||
| 559 | <filename>crownbay-noemgd</filename> and <filename>crownbay</filename>. | ||
| 560 | Here is the final <filename>linux-yocto-2.6.37.bbappend</filename> file after all | ||
| 561 | the edits: | ||
| 562 | <literallayout class='monospaced'> | ||
| 563 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
| 564 | |||
| 565 | COMPATIBLE_MACHINE_mymachine = "mymachine" | ||
| 566 | KMACHINE_mymachine = "yocto/standard/mymachine" | ||
| 567 | KERNEL_FEATURES_append_mymachine += " cfg/smp.scc" | ||
| 568 | |||
| 569 | SRCREV_machine_pn-linux-yocto_mymachine ?= \ | ||
| 570 | "fce17f046d3756045e4dfb49221d1cf60fcae329" | ||
| 571 | SRCREV_meta_pn-linux-yocto_mymachine ?= \ | ||
| 572 | "84f1a422d7e21fbc23a687035bdf9d42471f19e0" | ||
| 573 | </literallayout> | ||
| 574 | </para> | ||
| 575 | |||
| 576 | <para> | ||
| 577 | In summary, the edits to the layer’s recipe files result in removal of any files and | ||
| 578 | statements that do not support your targeted hardware in addition to the inclusion | ||
| 579 | of any new recipes you might need. | ||
| 580 | In this example, it was simply a matter of ridding the new layer | ||
| 581 | <filename>meta-machine</filename> of any code that supported the EMGD features | ||
| 582 | and making sure we were identifying the kernel that supports our example, which | ||
| 583 | is the <filename>atom-pc-standard</filename> kernel. | ||
| 584 | We did not introduce any new recipes to the layer. | ||
| 585 | </para> | ||
| 586 | |||
| 587 | <para> | ||
| 588 | Finally, it is also important to update the layer’s <filename>README</filename> | ||
| 589 | file so that the information in it reflects your BSP. | ||
| 590 | </para> | ||
| 591 | </section> | ||
| 592 | |||
| 593 | <section id='preparing-for-the-build'> | ||
| 594 | <title>Preparing for the Build</title> | ||
| 595 | |||
| 596 | <para> | ||
| 597 | Once you have made all the changes to your BSP layer there remains a few things | ||
| 598 | you need to do for the Yocto Project build system in order for it to create your image. | ||
| 599 | You need to get the build environment ready by sourcing an environment setup script | ||
| 600 | and you need to be sure two key configuration files are configured appropriately. | ||
| 601 | </para> | ||
| 602 | |||
| 603 | <para> | ||
| 604 | The entire process for building an image is overviewed in the | ||
| 605 | <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'> | ||
| 606 | Building an Image</ulink> section of the Yocto Project Quick Start. | ||
| 607 | You might want to reference this information. | ||
| 608 | The remainder of this section will apply to our example of the | ||
| 609 | <filename>meta-mymachine</filename> layer. | ||
| 610 | </para> | ||
| 611 | |||
| 612 | <para> | ||
| 613 | To get ready to build your image that uses the new layer you need to do the following: | ||
| 614 | <orderedlist> | ||
| 615 | <listitem><para>Get the environment ready for the build by sourcing the environment | ||
| 616 | script. | ||
| 617 | The environment script is in the top-level of the local Yocto Project files | ||
| 618 | directory structure. | ||
| 619 | The script has the string | ||
| 620 | <filename>init-build-env</filename> in the file’s name. | ||
| 621 | For this example, the following command gets the build environment ready: | ||
| 622 | <literallayout class='monospaced'> | ||
| 623 | $ source oe-init-build-env yocto-build | ||
| 624 | </literallayout> | ||
| 625 | When you source the script a build directory is created in the current | ||
| 626 | working directory. | ||
| 627 | In our example we were in the <filename>poky</filename> directory. | ||
| 628 | Thus, entering the previous command created the <filename>yocto-build</filename> directory. | ||
| 629 | If you do not provide a name for the build directory it defaults to | ||
| 630 | <filename>build</filename>. | ||
| 631 | The <filename>yocot-build</filename> directory contains a | ||
| 632 | <filename>conf</filename> directory that has | ||
| 633 | two configuration files you will need to check: <filename>bblayers.conf</filename> | ||
| 634 | and <filename>local.conf</filename>.</para></listitem> | ||
| 635 | <listitem><para>Check and edit the resulting <filename>local.conf</filename> file. | ||
| 636 | This file minimally identifies the machine for which to build the image by | ||
| 637 | configuring the <filename>MACHINE</filename> variable. | ||
| 638 | For this example you must set the variable to mymachine as follows: | ||
| 639 | <literallayout class='monospaced'> | ||
| 640 | MACHINE ??= “mymachine” | ||
| 641 | </literallayout> | ||
| 642 | You should also be sure any other variables in which you are interested are set. | ||
| 643 | Some variables to consider are <filename>BB_NUMBER_THREADS</filename> | ||
| 644 | and <filename>PARALLEL_MAKE</filename>, both of which can greatly reduce your build time | ||
| 645 | if you are using a multi-threaded development system (e.g. values of | ||
| 646 | <filename>8</filename> and <filename>j 6</filename>, respectively are optimal | ||
| 647 | for a development machine that has four available cores).</para></listitem> | ||
| 648 | <listitem><para>Update the <filename>bblayers.conf</filename> file so that it includes | ||
| 649 | the path to your new BSP layer. | ||
| 650 | In this example you need to include the pathname to <filename>meta-mymachine</filename>. | ||
| 651 | For this example the | ||
| 652 | <filename>BBLAYERS</filename> variable in the file would need to include the following path: | ||
| 653 | <literallayout class='monospaced'> | ||
| 654 | $HOME/poky/meta-intel/meta-mymachine | ||
| 655 | </literallayout></para></listitem> | ||
| 656 | </orderedlist> | ||
| 657 | </para> | ||
| 658 | |||
| 659 | <para> | ||
| 660 | The appendix | ||
| 661 | <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-variables-glos'> | ||
| 662 | Reference: Variables Glossary</ulink> in the Yocto Project Reference Manual has more information | ||
| 663 | on configuration variables. | ||
| 664 | </para> | ||
| 665 | </section> | ||
| 666 | |||
| 667 | <section id='building-the-image'> | ||
| 668 | <title>Building the Image</title> | ||
| 669 | |||
| 670 | <para> | ||
| 671 | The Yocto Project uses the BitBake tool to build images based on the type of image | ||
| 672 | you want to create. | ||
| 673 | You can find more information on BitBake | ||
| 674 | <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>. | ||
| 675 | </para> | ||
| 676 | |||
| 677 | <para> | ||
| 678 | The build process supports several types of images to satisfy different needs. | ||
| 679 | When you issue the BitBake command you provide a “top-level” recipe that essentially | ||
| 680 | starts the process off of building the type of image you want. | ||
| 681 | </para> | ||
| 682 | |||
| 683 | <para> | ||
| 684 | [WRITER'S NOTE: Consider moving this to the Poky Reference Manual.] | ||
| 685 | </para> | ||
| 686 | |||
| 687 | <para> | ||
| 688 | You can find these recipes in the <filename>meta/recipes-core/images</filename> and | ||
| 689 | <filename>meta/recipes-sato/images</filename> directories of your local Yocto Project | ||
| 690 | file structure (Git repository or extracted release tarball). | ||
| 691 | Although the recipe names are somewhat explanatory, here is a list that describes them: | ||
| 692 | <itemizedlist> | ||
| 693 | <listitem><para><emphasis>Base</emphasis> – A foundational basic image without support | ||
| 694 | for X that can be reasonably used for customization.</para></listitem> | ||
| 695 | <listitem><para><emphasis>Core</emphasis> – A foundational basic image with support for | ||
| 696 | X that can be reasonably used for customization.</para></listitem> | ||
| 697 | <listitem><para><emphasis>Direct Disk</emphasis> – An image that you can copy directory to | ||
| 698 | the disk of the target device.</para></listitem> | ||
| 699 | <listitem><para><emphasis>Live</emphasis> – An image you can run from a USB device or from | ||
| 700 | a CD without having to first install something.</para></listitem> | ||
| 701 | <listitem><para><emphasis>Minimal</emphasis> – A small image without a GUI. | ||
| 702 | This image is not much more than a kernel with a shell.</para></listitem> | ||
| 703 | <listitem><para><emphasis>Minimal Development</emphasis> – A Minimal image suitable for | ||
| 704 | development work.</para></listitem> | ||
| 705 | <listitem><para><emphasis>Minimal Direct Disk</emphasis> – A Minimal Direct Disk image.</para></listitem> | ||
| 706 | <listitem><para><emphasis>Minimal RAM-based Initial Root Filesystem</emphasis> – A minimal image | ||
| 707 | that has the <filename>initramfs</filename> as part of the kernel, which allows the | ||
| 708 | system to find the first “init” program more efficiently.</para></listitem> | ||
| 709 | <listitem><para><emphasis>Minimal Live</emphasis> – A Minimal Live image.</para></listitem> | ||
| 710 | <listitem><para><emphasis>Minimal MTD Utilities</emphasis> – A minimal image that has support | ||
| 711 | for the MTD utilities, which let the user interact with the MTD subsystem in | ||
| 712 | the kernel to perform operations on flash devices.</para></listitem> | ||
| 713 | <listitem><para><emphasis>Sato</emphasis> – An image with Sato support, a mobile environment | ||
| 714 | and visual style that works well with mobile devices.</para></listitem> | ||
| 715 | <listitem><para><emphasis>Sato Development</emphasis> – A Sato image suitable for | ||
| 716 | development work.</para></listitem> | ||
| 717 | <listitem><para><emphasis>Sato Direct Disk</emphasis> – A Sato Direct Disk image.</para></listitem> | ||
| 718 | <listitem><para><emphasis>Sato Live</emphasis> – A Sato Live image.</para></listitem> | ||
| 719 | <listitem><para><emphasis>Sato SDK</emphasis> – A Sato image that includes the Yocto Project | ||
| 720 | toolchain and development libraries.</para></listitem> | ||
| 721 | <listitem><para><emphasis>Sato SDK Direct Disk</emphasis> – A Sato SDK Direct | ||
| 722 | Disk image.</para></listitem> | ||
| 723 | <listitem><para><emphasis>Sato SDK Live</emphasis> – A Sato SDK Live image.</para></listitem> | ||
| 724 | </itemizedlist> | ||
| 725 | </para> | ||
| 726 | |||
| 727 | <para> | ||
| 728 | The remainder of this section applies to our example of the <filename>meta-mymachine</filename> layer. | ||
| 729 | </para> | ||
| 730 | |||
| 731 | <para> | ||
| 732 | To build the image for our <filename>meta-mymachine</filename> BSP enter the following command | ||
| 733 | from the same shell from which you ran the setup script. | ||
| 734 | You should run the <filename>bitbake</filename> command without any intervening shell commands. | ||
| 735 | For example, moving your working directory around could cause problems. | ||
| 736 | Here is the command for this example: | ||
| 737 | <literallayout class='monospaced'> | ||
| 738 | $ bitbake –k core-image-sato-live | ||
| 739 | </literallayout> | ||
| 740 | </para> | ||
| 741 | |||
| 742 | <para> | ||
| 743 | This command specifies an image that has Sato support and that can be run from a USB device or | ||
| 744 | from a CD without having to first install anything. | ||
| 745 | The build process takes significant time and includes thousands of tasks, which are reported | ||
| 746 | at the console. | ||
| 747 | If the build results in any type of error you should check for misspellings in the | ||
| 748 | files you changed or problems with your host development environment such as missing packages. | ||
| 749 | </para> | ||
| 750 | </section> | ||
| 751 | </section> | 219 | </section> |
| 752 | 220 | ||
| 753 | <section id='modifying-a-kernel-kernel-example'> | 221 | <section id='modifying-a-kernel-kernel-example'> |
| @@ -883,9 +351,9 @@ | |||
| 883 | 351 | ||
| 884 | <para> | 352 | <para> |
| 885 | You need to have the Yocto Project files available on your host system. | 353 | You need to have the Yocto Project files available on your host system. |
| 886 | The process is identical to that described in getting the files in section | 354 | The process is identical to that described in the |
| 887 | <xref linkend='setting-up-yocto-project'>"Setting Up Yocto Project"</xref> for | 355 | <xref linkend='getting-setup'>"Getting Setup"</xref> section earlier in this |
| 888 | the BSP development case. | 356 | manual. |
| 889 | Be sure to either set up a local Git repository for <filename>poky</filename> | 357 | Be sure to either set up a local Git repository for <filename>poky</filename> |
| 890 | or download and unpack the Yocto Project release tarball. | 358 | or download and unpack the Yocto Project release tarball. |
| 891 | </para> | 359 | </para> |