diff options
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 1582 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual-intro.xml | 96 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual-kernel-appendix-orig.xml | 232 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 1128 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 848 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual-start.xml | 238 | ||||
-rw-r--r-- | documentation/dev-manual/dev-manual.xml | 18 |
7 files changed, 2071 insertions, 2071 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 1e2ddefda0..6c406dad53 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml | |||
@@ -8,8 +8,8 @@ | |||
8 | <para> | 8 | <para> |
9 | This chapter describes standard tasks such as adding new | 9 | This chapter describes standard tasks such as adding new |
10 | software packages, extending or customizing images, and porting work to | 10 | software packages, extending or customizing images, and porting work to |
11 | new hardware (adding a new machine). | 11 | new hardware (adding a new machine). |
12 | The chapter also describes how to combine multiple | 12 | The chapter also describes how to combine multiple |
13 | versions of library files into a single image, how to handle a package name alias, and | 13 | versions of library files into a single image, how to handle a package name alias, and |
14 | gives advice about how to make changes to the Yocto Project to achieve the best results. | 14 | gives advice about how to make changes to the Yocto Project to achieve the best results. |
15 | </para> | 15 | </para> |
@@ -18,8 +18,8 @@ | |||
18 | <title>Understanding and Creating Layers</title> | 18 | <title>Understanding and Creating Layers</title> |
19 | 19 | ||
20 | <para> | 20 | <para> |
21 | The OpenEmbedded build system supports organizing <link linkend='metadata'>metadata</link> | 21 | The OpenEmbedded build system supports organizing <link linkend='metadata'>metadata</link> |
22 | into multiple layers. | 22 | into multiple layers. |
23 | Layers allow you to isolate different types of customizations from each other. | 23 | Layers allow you to isolate different types of customizations from each other. |
24 | You might find it tempting to keep everything in one layer when working on a single project. | 24 | You might find it tempting to keep everything in one layer when working on a single project. |
25 | However, the more modular you organize your metadata, the easier it is to cope with future changes. | 25 | However, the more modular you organize your metadata, the easier it is to cope with future changes. |
@@ -28,14 +28,14 @@ | |||
28 | <para> | 28 | <para> |
29 | To illustrate how layers are used to keep things modular, consider machine customizations. | 29 | To illustrate how layers are used to keep things modular, consider machine customizations. |
30 | These types of customizations typically reside in a BSP Layer. | 30 | These types of customizations typically reside in a BSP Layer. |
31 | Furthermore, the machine customizations should be isolated from recipes and metadata that support | 31 | Furthermore, the machine customizations should be isolated from recipes and metadata that support |
32 | a new GUI environment, for example. | 32 | a new GUI environment, for example. |
33 | This situation gives you a couple of layers: one for the machine configurations, and one for the | 33 | This situation gives you a couple of layers: one for the machine configurations, and one for the |
34 | GUI environment. | 34 | GUI environment. |
35 | It is important to understand, however, that the BSP layer can still make machine-specific | 35 | It is important to understand, however, that the BSP layer can still make machine-specific |
36 | additions to recipes within the GUI environment layer without polluting the GUI layer itself | 36 | additions to recipes within the GUI environment layer without polluting the GUI layer itself |
37 | with those machine-specific changes. | 37 | with those machine-specific changes. |
38 | You can accomplish this through a recipe that is a BitBake append | 38 | You can accomplish this through a recipe that is a BitBake append |
39 | (<filename>.bbappend</filename>) file, which is described later in this section. | 39 | (<filename>.bbappend</filename>) file, which is described later in this section. |
40 | </para> | 40 | </para> |
41 | 41 | ||
@@ -50,17 +50,17 @@ | |||
50 | You can easily identify a layer in the Source Directory by its folder name. | 50 | You can easily identify a layer in the Source Directory by its folder name. |
51 | Folders that are layers begin with the string <filename>meta</filename>. | 51 | Folders that are layers begin with the string <filename>meta</filename>. |
52 | For example, when you set up the <link linkend='source-directory'>Source Directory</link> | 52 | For example, when you set up the <link linkend='source-directory'>Source Directory</link> |
53 | structure, you will see several layers: <filename>meta</filename>, | 53 | structure, you will see several layers: <filename>meta</filename>, |
54 | <filename>meta-hob</filename>, <filename>meta-skeleton</filename>, | 54 | <filename>meta-hob</filename>, <filename>meta-skeleton</filename>, |
55 | <filename>meta-yocto</filename>, and <filename>meta-yocto-bsp</filename>. | 55 | <filename>meta-yocto</filename>, and <filename>meta-yocto-bsp</filename>. |
56 | Each of these folders is a layer. | 56 | Each of these folders is a layer. |
57 | </para> | 57 | </para> |
58 | 58 | ||
59 | <para> | 59 | <para> |
60 | Furthermore, if you set up a local copy of the <filename>meta-intel</filename> Git repository | 60 | Furthermore, if you set up a local copy of the <filename>meta-intel</filename> Git repository |
61 | and then explore that folder, you will discover many BSP layers within the | 61 | and then explore that folder, you will discover many BSP layers within the |
62 | <filename>meta-intel</filename> layer. | 62 | <filename>meta-intel</filename> layer. |
63 | For more information on BSP layers, see the | 63 | For more information on BSP layers, see the |
64 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" | 64 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" |
65 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. | 65 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. |
66 | </para> | 66 | </para> |
@@ -73,14 +73,14 @@ | |||
73 | It is very easy to create your own layer to use with the OpenEmbedded build system. | 73 | It is very easy to create your own layer to use with the OpenEmbedded build system. |
74 | Follow these general steps to create your layer: | 74 | Follow these general steps to create your layer: |
75 | <orderedlist> | 75 | <orderedlist> |
76 | <listitem><para><emphasis>Check Existing Layers:</emphasis> Before creating a new layer, | 76 | <listitem><para><emphasis>Check Existing Layers:</emphasis> Before creating a new layer, |
77 | you should be sure someone has not already created a layer containing the metadata | 77 | you should be sure someone has not already created a layer containing the metadata |
78 | you need. | 78 | you need. |
79 | You can see the | 79 | You can see the |
80 | <ulink url='&OE_HOME_URL;/wiki/LayerIndex'><filename>LayerIndex</filename></ulink> | 80 | <ulink url='&OE_HOME_URL;/wiki/LayerIndex'><filename>LayerIndex</filename></ulink> |
81 | for a list of layers from the OpenEmbedded community that can be used in the | 81 | for a list of layers from the OpenEmbedded community that can be used in the |
82 | Yocto Project.</para></listitem> | 82 | Yocto Project.</para></listitem> |
83 | <listitem><para><emphasis>Create a Directory:</emphasis> Create the directory | 83 | <listitem><para><emphasis>Create a Directory:</emphasis> Create the directory |
84 | for your layer. | 84 | for your layer. |
85 | Traditionally, prepend the name of the folder with the string | 85 | Traditionally, prepend the name of the folder with the string |
86 | <filename>meta</filename>. | 86 | <filename>meta</filename>. |
@@ -92,9 +92,9 @@ | |||
92 | </literallayout></para></listitem> | 92 | </literallayout></para></listitem> |
93 | <listitem><para><emphasis>Create a Layer Configuration File:</emphasis> Inside your new | 93 | <listitem><para><emphasis>Create a Layer Configuration File:</emphasis> Inside your new |
94 | layer folder, you need to create a <filename>conf/layer.conf</filename> file. | 94 | layer folder, you need to create a <filename>conf/layer.conf</filename> file. |
95 | It is easiest to take an existing layer configuration file and copy that to your | 95 | It is easiest to take an existing layer configuration file and copy that to your |
96 | layer's <filename>conf</filename> directory and then modify the file as needed.</para> | 96 | layer's <filename>conf</filename> directory and then modify the file as needed.</para> |
97 | <para>The <filename>meta-yocto/conf/layer.conf</filename> file demonstrates the | 97 | <para>The <filename>meta-yocto/conf/layer.conf</filename> file demonstrates the |
98 | required syntax: | 98 | required syntax: |
99 | <literallayout class='monospaced'> | 99 | <literallayout class='monospaced'> |
100 | # We have a conf and classes directory, add to BBPATH | 100 | # We have a conf and classes directory, add to BBPATH |
@@ -106,47 +106,47 @@ | |||
106 | 106 | ||
107 | BBFILE_COLLECTIONS += "yocto" | 107 | BBFILE_COLLECTIONS += "yocto" |
108 | BBFILE_PATTERN_yocto := "^${LAYERDIR}/" | 108 | BBFILE_PATTERN_yocto := "^${LAYERDIR}/" |
109 | BBFILE_PRIORITY_yocto = "5" | 109 | BBFILE_PRIORITY_yocto = "5" |
110 | </literallayout></para> | 110 | </literallayout></para> |
111 | <para>In the previous example, the recipes for the layers are added to | 111 | <para>In the previous example, the recipes for the layers are added to |
112 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>. | 112 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>. |
113 | The | 113 | The |
114 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename> | 114 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename> |
115 | variable is then appended with the layer name. | 115 | variable is then appended with the layer name. |
116 | The | 116 | The |
117 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename> | 117 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename> |
118 | variable is set to a regular expression and is used to match files | 118 | variable is set to a regular expression and is used to match files |
119 | from <filename>BBFILES</filename> into a particular layer. | 119 | from <filename>BBFILES</filename> into a particular layer. |
120 | In this case, immediate expansion of | 120 | In this case, immediate expansion of |
121 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename> | 121 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename> |
122 | sets <filename>BBFILE_PATTERN</filename> to the layer's path. | 122 | sets <filename>BBFILE_PATTERN</filename> to the layer's path. |
123 | The | 123 | The |
124 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename> | 124 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename> |
125 | variable then assigns a priority to the layer. | 125 | variable then assigns a priority to the layer. |
126 | Applying priorities is useful in situations where the same package might appear in multiple | 126 | Applying priorities is useful in situations where the same package might appear in multiple |
127 | layers and allows you to choose what layer should take precedence.</para> | 127 | layers and allows you to choose what layer should take precedence.</para> |
128 | <para>Note the use of the | 128 | <para>Note the use of the |
129 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename> | 129 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename> |
130 | variable with the immediate expansion operator. | 130 | variable with the immediate expansion operator. |
131 | The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and | 131 | The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and |
132 | requires the immediate expansion operator so that BitBake does not wait to expand the variable | 132 | requires the immediate expansion operator so that BitBake does not wait to expand the variable |
133 | when it's parsing a different directory.</para> | 133 | when it's parsing a different directory.</para> |
134 | <para>Through the use of the <filename>BBPATH</filename> variable, | 134 | <para>Through the use of the <filename>BBPATH</filename> variable, |
135 | BitBake locates <filename>.bbclass</filename> files, configuration | 135 | BitBake locates <filename>.bbclass</filename> files, configuration |
136 | files, and files that are included with <filename>include</filename> | 136 | files, and files that are included with <filename>include</filename> |
137 | and <filename>require</filename> statements. | 137 | and <filename>require</filename> statements. |
138 | For these cases, BitBake uses the first file with the matching name found in | 138 | For these cases, BitBake uses the first file with the matching name found in |
139 | <filename>BBPATH</filename>. | 139 | <filename>BBPATH</filename>. |
140 | This is similar to the way the <filename>PATH</filename> variable is used for binaries. | 140 | This is similar to the way the <filename>PATH</filename> variable is used for binaries. |
141 | We recommend, therefore, that you use unique <filename>.bbclass</filename> | 141 | We recommend, therefore, that you use unique <filename>.bbclass</filename> |
142 | and configuration file names in your custom layer.</para></listitem> | 142 | and configuration file names in your custom layer.</para></listitem> |
143 | <listitem><para><emphasis>Add Content:</emphasis> Depending on the type of layer, | 143 | <listitem><para><emphasis>Add Content:</emphasis> Depending on the type of layer, |
144 | add the content. | 144 | add the content. |
145 | If the layer adds support for a machine, add the machine configuration in | 145 | If the layer adds support for a machine, add the machine configuration in |
146 | a <filename>conf/machine/</filename> file within the layer. | 146 | a <filename>conf/machine/</filename> file within the layer. |
147 | If the layer adds distro policy, add the distro configuration in a | 147 | If the layer adds distro policy, add the distro configuration in a |
148 | <filename>conf/distro/</filename> file with the layer. | 148 | <filename>conf/distro/</filename> file with the layer. |
149 | If the layer introduces new recipes, put the recipes you need in | 149 | If the layer introduces new recipes, put the recipes you need in |
150 | <filename>recipes-*</filename> subdirectories within the layer. | 150 | <filename>recipes-*</filename> subdirectories within the layer. |
151 | <note>In order to be compliant with the Yocto Project, a layer must contain | 151 | <note>In order to be compliant with the Yocto Project, a layer must contain |
152 | a <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink> | 152 | a <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink> |
@@ -157,45 +157,45 @@ | |||
157 | <para> | 157 | <para> |
158 | To create layers that are easier to maintain, you should consider the following: | 158 | To create layers that are easier to maintain, you should consider the following: |
159 | <itemizedlist> | 159 | <itemizedlist> |
160 | <listitem><para>Avoid "overlaying" entire recipes from other layers in your | 160 | <listitem><para>Avoid "overlaying" entire recipes from other layers in your |
161 | configuration. | 161 | configuration. |
162 | In other words, don't copy an entire recipe into your layer and then modify it. | 162 | In other words, don't copy an entire recipe into your layer and then modify it. |
163 | Use <filename>.bbappend</filename> files to override the parts of the | 163 | Use <filename>.bbappend</filename> files to override the parts of the |
164 | recipe you need to modify.</para></listitem> | 164 | recipe you need to modify.</para></listitem> |
165 | <listitem><para>Avoid duplicating include files. | 165 | <listitem><para>Avoid duplicating include files. |
166 | Use <filename>.bbappend</filename> files for each recipe that uses an include | 166 | Use <filename>.bbappend</filename> files for each recipe that uses an include |
167 | file. | 167 | file. |
168 | Or, if you are introducing a new recipe that requires the included file, use the | 168 | Or, if you are introducing a new recipe that requires the included file, use the |
169 | path relative to the original layer directory to refer to the file. | 169 | path relative to the original layer directory to refer to the file. |
170 | For example, use <filename>require recipes-core/somepackage/somefile.inc</filename> | 170 | For example, use <filename>require recipes-core/somepackage/somefile.inc</filename> |
171 | instead of <filename>require somefile.inc</filename>. | 171 | instead of <filename>require somefile.inc</filename>. |
172 | If you're finding you have to overlay the include file, it could indicate a | 172 | If you're finding you have to overlay the include file, it could indicate a |
173 | deficiency in the include file in the layer to which it originally belongs. | 173 | deficiency in the include file in the layer to which it originally belongs. |
174 | If this is the case, you need to address that deficiency instead of overlaying | 174 | If this is the case, you need to address that deficiency instead of overlaying |
175 | the include file. | 175 | the include file. |
176 | For example, consider how Qt 4 database support plug-ins are configured. | 176 | For example, consider how Qt 4 database support plug-ins are configured. |
177 | The Source Directory does not have | 177 | The Source Directory does not have |
178 | MySQL or PostgreSQL, however OpenEmbedded's | 178 | MySQL or PostgreSQL, however OpenEmbedded's |
179 | layer <filename>meta-oe</filename> does. | 179 | layer <filename>meta-oe</filename> does. |
180 | Consequently, <filename>meta-oe</filename> uses <filename>.bbappend</filename> | 180 | Consequently, <filename>meta-oe</filename> uses <filename>.bbappend</filename> |
181 | files to modify the <filename>QT_SQL_DRIVER_FLAGS</filename> variable to enable | 181 | files to modify the <filename>QT_SQL_DRIVER_FLAGS</filename> variable to enable |
182 | the appropriate plugins. | 182 | the appropriate plugins. |
183 | This variable was added to the <filename>qt4.inc</filename> include file in | 183 | This variable was added to the <filename>qt4.inc</filename> include file in |
184 | the Source Directory specifically to allow the <filename>meta-oe</filename> layer | 184 | the Source Directory specifically to allow the <filename>meta-oe</filename> layer |
185 | to be able to control which plugins are built.</para></listitem> | 185 | to be able to control which plugins are built.</para></listitem> |
186 | </itemizedlist> | 186 | </itemizedlist> |
187 | </para> | 187 | </para> |
188 | 188 | ||
189 | <para> | 189 | <para> |
190 | We also recommend the following: | 190 | We also recommend the following: |
191 | <itemizedlist> | 191 | <itemizedlist> |
192 | <listitem><para>Store custom layers in a Git repository that uses the | 192 | <listitem><para>Store custom layers in a Git repository that uses the |
193 | <filename>meta-<layer_name></filename> format.</para></listitem> | 193 | <filename>meta-<layer_name></filename> format.</para></listitem> |
194 | <listitem><para>Clone the repository alongside other <filename>meta</filename> | 194 | <listitem><para>Clone the repository alongside other <filename>meta</filename> |
195 | directories in the | 195 | directories in the |
196 | <link linkend='source-directory'>Source Directory</link>.</para></listitem> | 196 | <link linkend='source-directory'>Source Directory</link>.</para></listitem> |
197 | </itemizedlist> | 197 | </itemizedlist> |
198 | Following these recommendations keeps your Source Directory and | 198 | Following these recommendations keeps your Source Directory and |
199 | its configuration entirely inside the Yocto Project's core base. | 199 | its configuration entirely inside the Yocto Project's core base. |
200 | </para> | 200 | </para> |
201 | </section> | 201 | </section> |
@@ -205,10 +205,10 @@ | |||
205 | 205 | ||
206 | <para> | 206 | <para> |
207 | Before the OpenEmbedded build system can use your new layer, you need to enable it. | 207 | Before the OpenEmbedded build system can use your new layer, you need to enable it. |
208 | To enable your layer, simply add your layer's path to the | 208 | To enable your layer, simply add your layer's path to the |
209 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename> | 209 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename> |
210 | variable in your <filename>conf/bblayers.conf</filename> file, which is found in the | 210 | variable in your <filename>conf/bblayers.conf</filename> file, which is found in the |
211 | <link linkend='build-directory'>Build Directory</link>. | 211 | <link linkend='build-directory'>Build Directory</link>. |
212 | The following example shows how to enable a layer named <filename>meta-mylayer</filename>: | 212 | The following example shows how to enable a layer named <filename>meta-mylayer</filename>: |
213 | <literallayout class='monospaced'> | 213 | <literallayout class='monospaced'> |
214 | LCONF_VERSION = "6" | 214 | LCONF_VERSION = "6" |
@@ -226,15 +226,15 @@ | |||
226 | BBLAYERS_NON_REMOVABLE ?= " \ | 226 | BBLAYERS_NON_REMOVABLE ?= " \ |
227 | $HOME/poky/meta \ | 227 | $HOME/poky/meta \ |
228 | $HOME/poky/meta-yocto \ | 228 | $HOME/poky/meta-yocto \ |
229 | " | 229 | " |
230 | </literallayout> | 230 | </literallayout> |
231 | </para> | 231 | </para> |
232 | 232 | ||
233 | <para> | 233 | <para> |
234 | BitBake parses each <filename>conf/layer.conf</filename> file as specified in the | 234 | BitBake parses each <filename>conf/layer.conf</filename> file as specified in the |
235 | <filename>BBLAYERS</filename> variable within the <filename>conf/bblayers.conf</filename> | 235 | <filename>BBLAYERS</filename> variable within the <filename>conf/bblayers.conf</filename> |
236 | file. | 236 | file. |
237 | During the processing of each <filename>conf/layer.conf</filename> file, BitBake adds the | 237 | During the processing of each <filename>conf/layer.conf</filename> file, BitBake adds the |
238 | recipes, classes and configurations contained within the particular layer to the source | 238 | recipes, classes and configurations contained within the particular layer to the source |
239 | directory. | 239 | directory. |
240 | </para> | 240 | </para> |
@@ -245,43 +245,43 @@ | |||
245 | 245 | ||
246 | <para> | 246 | <para> |
247 | Recipes used to append metadata to other recipes are called BitBake append files. | 247 | Recipes used to append metadata to other recipes are called BitBake append files. |
248 | BitBake append files use the <filename>.bbappend</filename> file type suffix, while | 248 | BitBake append files use the <filename>.bbappend</filename> file type suffix, while |
249 | the corresponding recipes to which metadata is being appended use the | 249 | the corresponding recipes to which metadata is being appended use the |
250 | <filename>.bb</filename> file type suffix. | 250 | <filename>.bb</filename> file type suffix. |
251 | </para> | 251 | </para> |
252 | 252 | ||
253 | <para> | 253 | <para> |
254 | A <filename>.bbappend</filename> file allows your layer to make additions or | 254 | A <filename>.bbappend</filename> file allows your layer to make additions or |
255 | changes to the content of another layer's recipe without having to copy the other | 255 | changes to the content of another layer's recipe without having to copy the other |
256 | recipe into your layer. | 256 | recipe into your layer. |
257 | Your <filename>.bbappend</filename> file resides in your layer, while the underlying | 257 | Your <filename>.bbappend</filename> file resides in your layer, while the underlying |
258 | <filename>.bb</filename> recipe file to which you are appending metadata | 258 | <filename>.bb</filename> recipe file to which you are appending metadata |
259 | resides in a different layer. | 259 | resides in a different layer. |
260 | </para> | 260 | </para> |
261 | 261 | ||
262 | <para> | 262 | <para> |
263 | Append files files must have the same name as the corresponding recipe. | 263 | Append files files must have the same name as the corresponding recipe. |
264 | For example, the append file <filename>someapp_&DISTRO;.bbappend</filename> must | 264 | For example, the append file <filename>someapp_&DISTRO;.bbappend</filename> must |
265 | apply to <filename>someapp_&DISTRO;.bb</filename>. | 265 | apply to <filename>someapp_&DISTRO;.bb</filename>. |
266 | This means the original recipe and append file names are version number specific. | 266 | This means the original recipe and append file names are version number specific. |
267 | If the corresponding recipe is renamed to update to a newer version, the | 267 | If the corresponding recipe is renamed to update to a newer version, the |
268 | underlying <filename>.bbappend</filename> file must be renamed as well. | 268 | underlying <filename>.bbappend</filename> file must be renamed as well. |
269 | During the build process, BitBake displays an error on starting if it detects a | 269 | During the build process, BitBake displays an error on starting if it detects a |
270 | <filename>.bbappend</filename> file that does not have a corresponding recipe | 270 | <filename>.bbappend</filename> file that does not have a corresponding recipe |
271 | with a matching name. | 271 | with a matching name. |
272 | </para> | 272 | </para> |
273 | 273 | ||
274 | <para> | 274 | <para> |
275 | Being able to append information to an existing recipe not only avoids duplication, | 275 | Being able to append information to an existing recipe not only avoids duplication, |
276 | but also automatically applies recipe changes in a different layer to your layer. | 276 | but also automatically applies recipe changes in a different layer to your layer. |
277 | If you were copying recipes, you would have to manually merge changes as they occur. | 277 | If you were copying recipes, you would have to manually merge changes as they occur. |
278 | </para> | 278 | </para> |
279 | 279 | ||
280 | <para> | 280 | <para> |
281 | As an example, consider the main formfactor recipe and a corresponding formfactor | 281 | As an example, consider the main formfactor recipe and a corresponding formfactor |
282 | append file both from the | 282 | append file both from the |
283 | <link linkend='source-directory'>Source Directory</link>. | 283 | <link linkend='source-directory'>Source Directory</link>. |
284 | Here is the main formfactor recipe, which is named <filename>formfactor_0.0.bb</filename> and | 284 | Here is the main formfactor recipe, which is named <filename>formfactor_0.0.bb</filename> and |
285 | located in the meta layer at <filename>meta/recipes-bsp/formfactor</filename>: | 285 | located in the meta layer at <filename>meta/recipes-bsp/formfactor</filename>: |
286 | <literallayout class='monospaced'> | 286 | <literallayout class='monospaced'> |
287 | DESCRIPTION = "Device formfactor information" | 287 | DESCRIPTION = "Device formfactor information" |
@@ -306,32 +306,32 @@ | |||
306 | fi | 306 | fi |
307 | } | 307 | } |
308 | </literallayout> | 308 | </literallayout> |
309 | Here is the append file, which is named <filename>formfactor_0.0.bbappend</filename> and is from the | 309 | Here is the append file, which is named <filename>formfactor_0.0.bbappend</filename> and is from the |
310 | Crown Bay BSP Layer named <filename>meta-intel/meta-crownbay</filename>. | 310 | Crown Bay BSP Layer named <filename>meta-intel/meta-crownbay</filename>. |
311 | The file is in <filename>recipes-bsp/formfactor</filename>: | 311 | The file is in <filename>recipes-bsp/formfactor</filename>: |
312 | <literallayout class='monospaced'> | 312 | <literallayout class='monospaced'> |
313 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 313 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" |
314 | 314 | ||
315 | PRINC := "${@int(PRINC) + 2}" | 315 | PRINC := "${@int(PRINC) + 2}" |
316 | </literallayout> | 316 | </literallayout> |
317 | This example adds or overrides files in | 317 | This example adds or overrides files in |
318 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | 318 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
319 | within a <filename>.bbappend</filename> by extending the path BitBake uses to search for files. | 319 | within a <filename>.bbappend</filename> by extending the path BitBake uses to search for files. |
320 | The most reliable way to do this is by prepending the | 320 | The most reliable way to do this is by prepending the |
321 | <filename>FILESEXTRAPATHS</filename> variable. | 321 | <filename>FILESEXTRAPATHS</filename> variable. |
322 | For example, if you have your files in a directory that is named the same as your package | 322 | For example, if you have your files in a directory that is named the same as your package |
323 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>), | 323 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>), |
324 | you can add this directory by adding the following to your <filename>.bbappend</filename> file: | 324 | you can add this directory by adding the following to your <filename>.bbappend</filename> file: |
325 | <literallayout class='monospaced'> | 325 | <literallayout class='monospaced'> |
326 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 326 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" |
327 | </literallayout> | 327 | </literallayout> |
328 | Using the immediate expansion assignment operator <filename>:=</filename> is important because | 328 | Using the immediate expansion assignment operator <filename>:=</filename> is important because |
329 | of the reference to <filename>THISDIR</filename>. | 329 | of the reference to <filename>THISDIR</filename>. |
330 | The trailing colon character is important as it ensures that items in the list remain | 330 | The trailing colon character is important as it ensures that items in the list remain |
331 | colon-separated. | 331 | colon-separated. |
332 | <note>BitBake automatically defines the <filename>THISDIR</filename> variable. | 332 | <note>BitBake automatically defines the <filename>THISDIR</filename> variable. |
333 | You should never set this variable yourself. | 333 | You should never set this variable yourself. |
334 | Using <filename>_prepend</filename> ensures your path will be searched prior to other | 334 | Using <filename>_prepend</filename> ensures your path will be searched prior to other |
335 | paths in the final list. | 335 | paths in the final list. |
336 | </note> | 336 | </note> |
337 | </para> | 337 | </para> |
@@ -342,17 +342,17 @@ | |||
342 | 342 | ||
343 | <para> | 343 | <para> |
344 | Each layer is assigned a priority value. | 344 | Each layer is assigned a priority value. |
345 | Priority values control which layer takes precedence if there are recipe files with | 345 | Priority values control which layer takes precedence if there are recipe files with |
346 | the same name in multiple layers. | 346 | the same name in multiple layers. |
347 | For these cases, the recipe file from the layer with a higher priority number taking precedence. | 347 | For these cases, the recipe file from the layer with a higher priority number taking precedence. |
348 | Priority values also affect the order in which multiple <filename>.bbappend</filename> files | 348 | Priority values also affect the order in which multiple <filename>.bbappend</filename> files |
349 | for the same recipe are applied. | 349 | for the same recipe are applied. |
350 | You can either specify the priority manually, or allow the build system to calculate it | 350 | You can either specify the priority manually, or allow the build system to calculate it |
351 | based on the layer's dependencies. | 351 | based on the layer's dependencies. |
352 | </para> | 352 | </para> |
353 | 353 | ||
354 | <para> | 354 | <para> |
355 | To specify the layer's priority manually, use the | 355 | To specify the layer's priority manually, use the |
356 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink> | 356 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink> |
357 | variable. | 357 | variable. |
358 | For example: | 358 | For example: |
@@ -362,10 +362,10 @@ | |||
362 | </para> | 362 | </para> |
363 | 363 | ||
364 | <note> | 364 | <note> |
365 | <para>It is possible for a recipe with a lower version number | 365 | <para>It is possible for a recipe with a lower version number |
366 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> | 366 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> |
367 | in a layer that has a higher priority to take precedence.</para> | 367 | in a layer that has a higher priority to take precedence.</para> |
368 | <para>Also, the layer priority does not currently affect the precedence order of | 368 | <para>Also, the layer priority does not currently affect the precedence order of |
369 | <filename>.conf</filename> or <filename>.bbclass</filename> files. | 369 | <filename>.conf</filename> or <filename>.bbclass</filename> files. |
370 | Future versions of BitBake might address this.</para> | 370 | Future versions of BitBake might address this.</para> |
371 | </note> | 371 | </note> |
@@ -375,9 +375,9 @@ | |||
375 | <title>Managing Layers</title> | 375 | <title>Managing Layers</title> |
376 | 376 | ||
377 | <para> | 377 | <para> |
378 | You can use the BitBake layer management tool to provide a view into the structure of | 378 | You can use the BitBake layer management tool to provide a view into the structure of |
379 | recipes across a multi-layer project. | 379 | recipes across a multi-layer project. |
380 | Being able to generate output that reports on configured layers with their paths and | 380 | Being able to generate output that reports on configured layers with their paths and |
381 | priorities and on <filename>.bbappend</filename> files and their applicable recipes | 381 | priorities and on <filename>.bbappend</filename> files and their applicable recipes |
382 | can help to reveal potential problems. | 382 | can help to reveal potential problems. |
383 | </para> | 383 | </para> |
@@ -394,11 +394,11 @@ | |||
394 | <listitem><para><filename><emphasis>show-layers:</emphasis></filename> | 394 | <listitem><para><filename><emphasis>show-layers:</emphasis></filename> |
395 | Show the current configured layers.</para></listitem> | 395 | Show the current configured layers.</para></listitem> |
396 | <listitem><para><filename><emphasis>show-recipes:</emphasis></filename> | 396 | <listitem><para><filename><emphasis>show-recipes:</emphasis></filename> |
397 | Lists available recipes and the layers that provide them. | 397 | Lists available recipes and the layers that provide them. |
398 | </para></listitem> | 398 | </para></listitem> |
399 | <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename> | 399 | <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename> |
400 | Lists overlayed recipes. | 400 | Lists overlayed recipes. |
401 | A recipe is overlayed when a recipe with the same name exists in another layer | 401 | A recipe is overlayed when a recipe with the same name exists in another layer |
402 | that has a higher layer priority. | 402 | that has a higher layer priority. |
403 | </para></listitem> | 403 | </para></listitem> |
404 | <listitem><para><filename><emphasis>show-appends:</emphasis></filename> | 404 | <listitem><para><filename><emphasis>show-appends:</emphasis></filename> |
@@ -413,15 +413,15 @@ | |||
413 | <itemizedlist> | 413 | <itemizedlist> |
414 | <listitem><para>Non-recipe files (such as patches) are overwritten. | 414 | <listitem><para>Non-recipe files (such as patches) are overwritten. |
415 | The flatten command shows a warning for these files.</para></listitem> | 415 | The flatten command shows a warning for these files.</para></listitem> |
416 | <listitem><para>Anything beyond the normal layer setup has been added to | 416 | <listitem><para>Anything beyond the normal layer setup has been added to |
417 | the <filename>layer.conf</filename> file. | 417 | the <filename>layer.conf</filename> file. |
418 | Only the lowest priority layer's <filename>layer.conf</filename> is used. | 418 | Only the lowest priority layer's <filename>layer.conf</filename> is used. |
419 | </para></listitem> | 419 | </para></listitem> |
420 | <listitem><para>Overridden and appended items from <filename>.bbappend</filename> | 420 | <listitem><para>Overridden and appended items from <filename>.bbappend</filename> |
421 | files need to be cleaned up. | 421 | files need to be cleaned up. |
422 | The contents of each <filename>.bbappend</filename> end up in the | 422 | The contents of each <filename>.bbappend</filename> end up in the |
423 | flattened recipe. | 423 | flattened recipe. |
424 | However, if there are appended or changed variable values, you need to tidy | 424 | However, if there are appended or changed variable values, you need to tidy |
425 | these up yourself. | 425 | these up yourself. |
426 | Consider the following example. | 426 | Consider the following example. |
427 | Here, the <filename>bitbake-layers</filename> command adds the line | 427 | Here, the <filename>bitbake-layers</filename> command adds the line |
@@ -457,7 +457,7 @@ | |||
457 | <title>Customizing Images</title> | 457 | <title>Customizing Images</title> |
458 | 458 | ||
459 | <para> | 459 | <para> |
460 | You can customize images to satisfy particular requirements. | 460 | You can customize images to satisfy particular requirements. |
461 | This section describes several methods and provides guidelines for each. | 461 | This section describes several methods and provides guidelines for each. |
462 | </para> | 462 | </para> |
463 | 463 | ||
@@ -465,7 +465,7 @@ | |||
465 | <title>Customizing Images Using Custom .bb Files</title> | 465 | <title>Customizing Images Using Custom .bb Files</title> |
466 | 466 | ||
467 | <para> | 467 | <para> |
468 | One way to get additional software into an image is to create a custom image. | 468 | One way to get additional software into an image is to create a custom image. |
469 | The following example shows the form for the two lines you need: | 469 | The following example shows the form for the two lines you need: |
470 | <literallayout class='monospaced'> | 470 | <literallayout class='monospaced'> |
471 | IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2" | 471 | IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2" |
@@ -476,19 +476,19 @@ | |||
476 | 476 | ||
477 | <para> | 477 | <para> |
478 | By creating a custom image, a developer has total control | 478 | By creating a custom image, a developer has total control |
479 | over the contents of the image. | 479 | over the contents of the image. |
480 | It is important to use the correct names of packages in the | 480 | It is important to use the correct names of packages in the |
481 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename> | 481 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename> |
482 | variable. | 482 | variable. |
483 | You must use the OpenEmbedded notation and not the Debian notation for the names | 483 | You must use the OpenEmbedded notation and not the Debian notation for the names |
484 | (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>). | 484 | (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>). |
485 | </para> | 485 | </para> |
486 | 486 | ||
487 | <para> | 487 | <para> |
488 | The other method for creating a custom image is to base it on an existing image. | 488 | The other method for creating a custom image is to base it on an existing image. |
489 | For example, if you want to create an image based on <filename>core-image-sato</filename> | 489 | For example, if you want to create an image based on <filename>core-image-sato</filename> |
490 | but add the additional package <filename>strace</filename> to the image, | 490 | but add the additional package <filename>strace</filename> to the image, |
491 | copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a | 491 | copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a |
492 | new <filename>.bb</filename> and add the following line to the end of the copy: | 492 | new <filename>.bb</filename> and add the following line to the end of the copy: |
493 | <literallayout class='monospaced'> | 493 | <literallayout class='monospaced'> |
494 | IMAGE_INSTALL += "strace" | 494 | IMAGE_INSTALL += "strace" |
@@ -501,22 +501,22 @@ | |||
501 | 501 | ||
502 | <para> | 502 | <para> |
503 | For complex custom images, the best approach is to create a custom package group recipe | 503 | For complex custom images, the best approach is to create a custom package group recipe |
504 | that is used to build the image or images. | 504 | that is used to build the image or images. |
505 | A good example of a package group recipe is | 505 | A good example of a package group recipe is |
506 | <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>. | 506 | <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>. |
507 | The | 507 | The |
508 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> | 508 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> |
509 | variable lists the package group packages you wish to produce. <filename>inherit packagegroup</filename> | 509 | variable lists the package group packages you wish to produce. <filename>inherit packagegroup</filename> |
510 | sets appropriate default values and automatically adds <filename>-dev</filename> | 510 | sets appropriate default values and automatically adds <filename>-dev</filename> |
511 | and <filename>-dbg</filename> complementary | 511 | and <filename>-dbg</filename> complementary |
512 | packages for every package specified in <filename>PACKAGES</filename>. | 512 | packages for every package specified in <filename>PACKAGES</filename>. |
513 | Note that the inherit line should be towards | 513 | Note that the inherit line should be towards |
514 | the top of the recipe, certainly before you set <filename>PACKAGES</filename>. | 514 | the top of the recipe, certainly before you set <filename>PACKAGES</filename>. |
515 | For each package you specify in <filename>PACKAGES</filename>, you can use | 515 | For each package you specify in <filename>PACKAGES</filename>, you can use |
516 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename> | 516 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename> |
517 | and | 517 | and |
518 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename> | 518 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename> |
519 | entries to provide a list of packages the parent task package should contain. | 519 | entries to provide a list of packages the parent task package should contain. |
520 | Following is an example: | 520 | Following is an example: |
521 | <literallayout class='monospaced'> | 521 | <literallayout class='monospaced'> |
522 | DESCRIPTION = "My Custom Package Groups" | 522 | DESCRIPTION = "My Custom Package Groups" |
@@ -546,44 +546,44 @@ | |||
546 | 546 | ||
547 | <para> | 547 | <para> |
548 | In the previous example, two package group packages are created with their dependencies and their | 548 | In the previous example, two package group packages are created with their dependencies and their |
549 | recommended package dependencies listed: <filename>packagegroup-custom-apps</filename>, and | 549 | recommended package dependencies listed: <filename>packagegroup-custom-apps</filename>, and |
550 | <filename>packagegroup-custom-tools</filename>. | 550 | <filename>packagegroup-custom-tools</filename>. |
551 | To build an image using these package group packages, you need to add | 551 | To build an image using these package group packages, you need to add |
552 | <filename>packagegroup-custom-apps</filename> and/or | 552 | <filename>packagegroup-custom-apps</filename> and/or |
553 | <filename>packagegroup-custom-tools</filename> to | 553 | <filename>packagegroup-custom-tools</filename> to |
554 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>. | 554 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>. |
555 | For other forms of image dependencies see the other areas of this section. | 555 | For other forms of image dependencies see the other areas of this section. |
556 | </para> | 556 | </para> |
557 | </section> | 557 | </section> |
558 | 558 | ||
559 | <section id='usingpoky-extend-customimage-imagefeatures'> | 559 | <section id='usingpoky-extend-customimage-imagefeatures'> |
560 | <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and | 560 | <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and |
561 | <filename>EXTRA_IMAGE_FEATURES</filename></title> | 561 | <filename>EXTRA_IMAGE_FEATURES</filename></title> |
562 | 562 | ||
563 | <para> | 563 | <para> |
564 | Ultimately users might want to add extra image features to the set by using the | 564 | Ultimately users might want to add extra image features to the set by using the |
565 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> | 565 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> |
566 | variable. | 566 | variable. |
567 | To create these features, the best reference is | 567 | To create these features, the best reference is |
568 | <filename>meta/classes/core-image.bbclass</filename>, which shows how this is | 568 | <filename>meta/classes/core-image.bbclass</filename>, which shows how this is |
569 | achieved. | 569 | achieved. |
570 | In summary, the file looks at the contents of the | 570 | In summary, the file looks at the contents of the |
571 | <filename>IMAGE_FEATURES</filename> | 571 | <filename>IMAGE_FEATURES</filename> |
572 | variable and then maps that into a set of tasks or packages. | 572 | variable and then maps that into a set of tasks or packages. |
573 | Based on this information, the | 573 | Based on this information, the |
574 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'> IMAGE_INSTALL</ulink></filename> | 574 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'> IMAGE_INSTALL</ulink></filename> |
575 | variable is generated automatically. | 575 | variable is generated automatically. |
576 | Users can add extra features by extending the class or creating a custom class for use | 576 | Users can add extra features by extending the class or creating a custom class for use |
577 | with specialized image <filename>.bb</filename> files. | 577 | with specialized image <filename>.bb</filename> files. |
578 | You can also add more features by configuring the | 578 | You can also add more features by configuring the |
579 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</ulink></filename> | 579 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</ulink></filename> |
580 | variable in the <filename>local.conf</filename> file found in the Source Directory | 580 | variable in the <filename>local.conf</filename> file found in the Source Directory |
581 | located in the Build Directory. | 581 | located in the Build Directory. |
582 | </para> | 582 | </para> |
583 | 583 | ||
584 | <para> | 584 | <para> |
585 | The Yocto Project ships with two SSH servers you can use in your images: | 585 | The Yocto Project ships with two SSH servers you can use in your images: |
586 | Dropbear and OpenSSH. | 586 | Dropbear and OpenSSH. |
587 | Dropbear is a minimal SSH server appropriate for resource-constrained environments, | 587 | Dropbear is a minimal SSH server appropriate for resource-constrained environments, |
588 | while OpenSSH is a well-known standard SSH server implementation. | 588 | while OpenSSH is a well-known standard SSH server implementation. |
589 | By default, the <filename>core-image-sato</filename> image is configured to use Dropbear. | 589 | By default, the <filename>core-image-sato</filename> image is configured to use Dropbear. |
@@ -591,7 +591,7 @@ | |||
591 | images both include OpenSSH. | 591 | images both include OpenSSH. |
592 | The <filename>core-image-minimal</filename> image does not contain an SSH server. | 592 | The <filename>core-image-minimal</filename> image does not contain an SSH server. |
593 | To change these defaults, edit the <filename>IMAGE_FEATURES</filename> variable | 593 | To change these defaults, edit the <filename>IMAGE_FEATURES</filename> variable |
594 | so that it sets the image you are working with to include | 594 | so that it sets the image you are working with to include |
595 | <filename>ssh-server-dropbear</filename> or <filename>ssh-server-openssh</filename>. | 595 | <filename>ssh-server-dropbear</filename> or <filename>ssh-server-openssh</filename>. |
596 | </para> | 596 | </para> |
597 | </section> | 597 | </section> |
@@ -601,16 +601,16 @@ | |||
601 | 601 | ||
602 | <para> | 602 | <para> |
603 | It is possible to customize image contents by using variables from your | 603 | It is possible to customize image contents by using variables from your |
604 | local configuration in your <filename>conf/local.conf</filename> file. | 604 | local configuration in your <filename>conf/local.conf</filename> file. |
605 | Because it is limited to local use, this method generally only allows you to | 605 | Because it is limited to local use, this method generally only allows you to |
606 | add packages and is not as flexible as creating your own customized image. | 606 | add packages and is not as flexible as creating your own customized image. |
607 | When you add packages using local variables this way, you need to realize that | 607 | When you add packages using local variables this way, you need to realize that |
608 | these variable changes affect all images at the same time and might not be | 608 | these variable changes affect all images at the same time and might not be |
609 | what you require. | 609 | what you require. |
610 | </para> | 610 | </para> |
611 | 611 | ||
612 | <para> | 612 | <para> |
613 | The simplest way to add extra packages to all images is by using the | 613 | The simplest way to add extra packages to all images is by using the |
614 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename> | 614 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename> |
615 | variable with the <filename>_append</filename> operator: | 615 | variable with the <filename>_append</filename> operator: |
616 | <literallayout class='monospaced'> | 616 | <literallayout class='monospaced'> |
@@ -624,10 +624,10 @@ | |||
624 | </para> | 624 | </para> |
625 | 625 | ||
626 | <para> | 626 | <para> |
627 | Furthermore, you must use <filename>_append</filename> instead of the <filename>+=</filename> | 627 | Furthermore, you must use <filename>_append</filename> instead of the <filename>+=</filename> |
628 | operator if you want to avoid ordering issues. | 628 | operator if you want to avoid ordering issues. |
629 | The reason for this is because doing so unconditionally appends to the variable and | 629 | The reason for this is because doing so unconditionally appends to the variable and |
630 | avoids ordering problems due to the variable being set in image recipes and | 630 | avoids ordering problems due to the variable being set in image recipes and |
631 | <filename>.bbclass</filename> files with operators like <filename>?=</filename>. | 631 | <filename>.bbclass</filename> files with operators like <filename>?=</filename>. |
632 | Using <filename>_append</filename> ensures the operation takes affect. | 632 | Using <filename>_append</filename> ensures the operation takes affect. |
633 | </para> | 633 | </para> |
@@ -645,8 +645,8 @@ | |||
645 | </para> | 645 | </para> |
646 | 646 | ||
647 | <para> | 647 | <para> |
648 | You can add packages using a similar approach through the | 648 | You can add packages using a similar approach through the |
649 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename> | 649 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename> |
650 | variable. | 650 | variable. |
651 | If you use this variable, only <filename>core-image-*</filename> images are affected. | 651 | If you use this variable, only <filename>core-image-*</filename> images are affected. |
652 | </para> | 652 | </para> |
@@ -657,27 +657,27 @@ | |||
657 | <title>Adding a Package</title> | 657 | <title>Adding a Package</title> |
658 | 658 | ||
659 | <para> | 659 | <para> |
660 | To add a package you need to write a recipe for it. | 660 | To add a package you need to write a recipe for it. |
661 | Writing a recipe means creating a <filename>.bb</filename> file that sets some | 661 | Writing a recipe means creating a <filename>.bb</filename> file that sets some |
662 | variables. | 662 | variables. |
663 | For information on variables that are useful for recipes and for information about recipe naming | 663 | For information on variables that are useful for recipes and for information about recipe naming |
664 | issues, see the | 664 | issues, see the |
665 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>" | 665 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>" |
666 | section of the Yocto Project Reference Manual. | 666 | section of the Yocto Project Reference Manual. |
667 | </para> | 667 | </para> |
668 | 668 | ||
669 | <para> | 669 | <para> |
670 | Before writing a recipe from scratch, it is often useful to check | 670 | Before writing a recipe from scratch, it is often useful to check |
671 | whether someone else has written one already. | 671 | whether someone else has written one already. |
672 | OpenEmbedded is a good place to look as it has a wider scope and range of packages. | 672 | OpenEmbedded is a good place to look as it has a wider scope and range of packages. |
673 | Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes | 673 | Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes |
674 | you find there should work for you. | 674 | you find there should work for you. |
675 | </para> | 675 | </para> |
676 | 676 | ||
677 | <para> | 677 | <para> |
678 | For new packages, the simplest way to add a recipe is to base it on a similar | 678 | For new packages, the simplest way to add a recipe is to base it on a similar |
679 | pre-existing recipe. | 679 | pre-existing recipe. |
680 | The sections that follow provide some examples that show how to add standard | 680 | The sections that follow provide some examples that show how to add standard |
681 | types of packages. | 681 | types of packages. |
682 | </para> | 682 | </para> |
683 | 683 | ||
@@ -685,16 +685,16 @@ | |||
685 | <title>Single .c File Package (Hello World!)</title> | 685 | <title>Single .c File Package (Hello World!)</title> |
686 | 686 | ||
687 | <para> | 687 | <para> |
688 | Building an application from a single file that is stored locally (e.g. under | 688 | Building an application from a single file that is stored locally (e.g. under |
689 | <filename>files/</filename>) requires a recipe that has the file listed in | 689 | <filename>files/</filename>) requires a recipe that has the file listed in |
690 | the | 690 | the |
691 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> | 691 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> |
692 | variable. | 692 | variable. |
693 | Additionally, you need to manually write the <filename>do_compile</filename> and | 693 | Additionally, you need to manually write the <filename>do_compile</filename> and |
694 | <filename>do_install</filename> tasks. | 694 | <filename>do_install</filename> tasks. |
695 | The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> | 695 | The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> |
696 | variable defines the | 696 | variable defines the |
697 | directory containing the source code, which is set to | 697 | directory containing the source code, which is set to |
698 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'> | 698 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'> |
699 | WORKDIR</ulink></filename> in this case - the directory BitBake uses for the build. | 699 | WORKDIR</ulink></filename> in this case - the directory BitBake uses for the build. |
700 | <literallayout class='monospaced'> | 700 | <literallayout class='monospaced'> |
@@ -721,7 +721,7 @@ | |||
721 | 721 | ||
722 | <para> | 722 | <para> |
723 | By default, the <filename>helloworld</filename>, <filename>helloworld-dbg</filename>, | 723 | By default, the <filename>helloworld</filename>, <filename>helloworld-dbg</filename>, |
724 | and <filename>helloworld-dev</filename> packages are built. | 724 | and <filename>helloworld-dev</filename> packages are built. |
725 | For information on how to customize the packaging process, see the | 725 | For information on how to customize the packaging process, see the |
726 | "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application | 726 | "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application |
727 | into Multiple Packages</link>" section. | 727 | into Multiple Packages</link>" section. |
@@ -731,15 +731,15 @@ | |||
731 | <section id='usingpoky-extend-addpkg-autotools'> | 731 | <section id='usingpoky-extend-addpkg-autotools'> |
732 | <title>Autotooled Package</title> | 732 | <title>Autotooled Package</title> |
733 | <para> | 733 | <para> |
734 | Applications that use Autotools such as <filename>autoconf</filename> and | 734 | Applications that use Autotools such as <filename>autoconf</filename> and |
735 | <filename>automake</filename> require a recipe that has a source archive listed in | 735 | <filename>automake</filename> require a recipe that has a source archive listed in |
736 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and | 736 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and |
737 | also inherits Autotools, which instructs BitBake to use the | 737 | also inherits Autotools, which instructs BitBake to use the |
738 | <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps | 738 | <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps |
739 | needed to build an Autotool-based application. | 739 | needed to build an Autotool-based application. |
740 | The result of the build is automatically packaged. | 740 | The result of the build is automatically packaged. |
741 | And, if the application uses NLS for localization, packages with local information are | 741 | And, if the application uses NLS for localization, packages with local information are |
742 | generated (one package per language). | 742 | generated (one package per language). |
743 | Following is one example: (<filename>hello_2.3.bb</filename>) | 743 | Following is one example: (<filename>hello_2.3.bb</filename>) |
744 | <literallayout class='monospaced'> | 744 | <literallayout class='monospaced'> |
745 | DESCRIPTION = "GNU Helloworld application" | 745 | DESCRIPTION = "GNU Helloworld application" |
@@ -755,10 +755,10 @@ | |||
755 | </para> | 755 | </para> |
756 | 756 | ||
757 | <para> | 757 | <para> |
758 | The variable | 758 | The variable |
759 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename> | 759 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename> |
760 | is used to track source license changes as described in the | 760 | is used to track source license changes as described in the |
761 | "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Track License Changes</ulink>" section. | 761 | "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Track License Changes</ulink>" section. |
762 | You can quickly create Autotool-based recipes in a manner similar to the previous example. | 762 | You can quickly create Autotool-based recipes in a manner similar to the previous example. |
763 | </para> | 763 | </para> |
764 | </section> | 764 | </section> |
@@ -768,22 +768,22 @@ | |||
768 | 768 | ||
769 | <para> | 769 | <para> |
770 | Applications that use GNU <filename>make</filename> also require a recipe that has | 770 | Applications that use GNU <filename>make</filename> also require a recipe that has |
771 | the source archive listed in | 771 | the source archive listed in |
772 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>. | 772 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>. |
773 | You do not need to add a <filename>do_compile</filename> step since by default BitBake | 773 | You do not need to add a <filename>do_compile</filename> step since by default BitBake |
774 | starts the <filename>make</filename> command to compile the application. | 774 | starts the <filename>make</filename> command to compile the application. |
775 | If you need additional <filename>make</filename> options you should store them in the | 775 | If you need additional <filename>make</filename> options you should store them in the |
776 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename> | 776 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename> |
777 | variable. | 777 | variable. |
778 | BitBake passes these options into the <filename>make</filename> GNU invocation. | 778 | BitBake passes these options into the <filename>make</filename> GNU invocation. |
779 | Note that a <filename>do_install</filename> task is still required. | 779 | Note that a <filename>do_install</filename> task is still required. |
780 | Otherwise, BitBake runs an empty <filename>do_install</filename> task by default. | 780 | Otherwise, BitBake runs an empty <filename>do_install</filename> task by default. |
781 | </para> | 781 | </para> |
782 | 782 | ||
783 | <para> | 783 | <para> |
784 | Some applications might require extra parameters to be passed to the compiler. | 784 | Some applications might require extra parameters to be passed to the compiler. |
785 | For example, the application might need an additional header path. | 785 | For example, the application might need an additional header path. |
786 | You can accomplish this by adding to the | 786 | You can accomplish this by adding to the |
787 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable. | 787 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable. |
788 | The following example shows this: | 788 | The following example shows this: |
789 | <literallayout class='monospaced'> | 789 | <literallayout class='monospaced'> |
@@ -829,20 +829,20 @@ | |||
829 | 829 | ||
830 | <para> | 830 | <para> |
831 | If your sources are available as a tarball instead of a Git repository, you | 831 | If your sources are available as a tarball instead of a Git repository, you |
832 | will need to provide the URL to the tarball as well as an | 832 | will need to provide the URL to the tarball as well as an |
833 | <filename>md5</filename> or <filename>sha256</filename> sum of | 833 | <filename>md5</filename> or <filename>sha256</filename> sum of |
834 | the download. | 834 | the download. |
835 | Here is an example: | 835 | Here is an example: |
836 | <literallayout class='monospaced'> | 836 | <literallayout class='monospaced'> |
837 | SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2" | 837 | SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2" |
838 | SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b" | 838 | SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b" |
839 | </literallayout> | 839 | </literallayout> |
840 | You can generate the <filename>md5</filename> or <filename>sha256</filename> sums | 840 | You can generate the <filename>md5</filename> or <filename>sha256</filename> sums |
841 | by using the <filename>md5sum</filename> or <filename>sha256sum</filename> commands | 841 | by using the <filename>md5sum</filename> or <filename>sha256sum</filename> commands |
842 | with the target file as the only argument. | 842 | with the target file as the only argument. |
843 | Here is an example: | 843 | Here is an example: |
844 | <literallayout class='monospaced'> | 844 | <literallayout class='monospaced'> |
845 | $ md5sum mtd-utils-1.4.9.tar.bz2 | 845 | $ md5sum mtd-utils-1.4.9.tar.bz2 |
846 | 82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2 | 846 | 82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2 |
847 | </literallayout> | 847 | </literallayout> |
848 | </para> | 848 | </para> |
@@ -851,17 +851,17 @@ | |||
851 | <section id='splitting-an-application-into-multiple-packages'> | 851 | <section id='splitting-an-application-into-multiple-packages'> |
852 | <title>Splitting an Application into Multiple Packages</title> | 852 | <title>Splitting an Application into Multiple Packages</title> |
853 | 853 | ||
854 | <para> | 854 | <para> |
855 | You can use the variables | 855 | You can use the variables |
856 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and | 856 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and |
857 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename> | 857 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename> |
858 | to split an application into multiple packages. | 858 | to split an application into multiple packages. |
859 | </para> | 859 | </para> |
860 | 860 | ||
861 | <para> | 861 | <para> |
862 | Following is an example that uses the <filename>libXpm</filename> recipe. | 862 | Following is an example that uses the <filename>libXpm</filename> recipe. |
863 | By default, this recipe generates a single package that contains the library along | 863 | By default, this recipe generates a single package that contains the library along |
864 | with a few binaries. | 864 | with a few binaries. |
865 | You can modify the recipe to split the binaries into separate packages: | 865 | You can modify the recipe to split the binaries into separate packages: |
866 | <literallayout class='monospaced'> | 866 | <literallayout class='monospaced'> |
867 | require xorg-lib-common.inc | 867 | require xorg-lib-common.inc |
@@ -883,19 +883,19 @@ | |||
883 | 883 | ||
884 | <para> | 884 | <para> |
885 | In the previous example, we want to ship the <filename>sxpm</filename> | 885 | In the previous example, we want to ship the <filename>sxpm</filename> |
886 | and <filename>cxpm</filename> binaries in separate packages. | 886 | and <filename>cxpm</filename> binaries in separate packages. |
887 | Since <filename>bindir</filename> would be packaged into the main | 887 | Since <filename>bindir</filename> would be packaged into the main |
888 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> | 888 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> |
889 | package by default, we prepend the | 889 | package by default, we prepend the |
890 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink> | 890 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink> |
891 | </filename> variable so additional package names are added to the start of list. | 891 | </filename> variable so additional package names are added to the start of list. |
892 | This results in the extra | 892 | This results in the extra |
893 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink>_*</filename> | 893 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink>_*</filename> |
894 | variables then containing information that define which files and | 894 | variables then containing information that define which files and |
895 | directories go into which packages. | 895 | directories go into which packages. |
896 | Files included by earlier packages are skipped by latter packages. | 896 | Files included by earlier packages are skipped by latter packages. |
897 | Thus, the main | 897 | Thus, the main |
898 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> package | 898 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> package |
899 | does not include the above listed files. | 899 | does not include the above listed files. |
900 | </para> | 900 | </para> |
901 | </section> | 901 | </section> |
@@ -903,25 +903,25 @@ | |||
903 | <section id='including-static-library-files'> | 903 | <section id='including-static-library-files'> |
904 | <title>Including Static Library Files</title> | 904 | <title>Including Static Library Files</title> |
905 | 905 | ||
906 | <para> | 906 | <para> |
907 | If you are building a library and the library offers static linking, you can control | 907 | If you are building a library and the library offers static linking, you can control |
908 | which static library files (<filename>*.a</filename> files) get included in the | 908 | which static library files (<filename>*.a</filename> files) get included in the |
909 | built library. | 909 | built library. |
910 | </para> | 910 | </para> |
911 | 911 | ||
912 | <para> | 912 | <para> |
913 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink> | 913 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink> |
914 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink> | 914 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink> |
915 | variables in the | 915 | variables in the |
916 | <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed | 916 | <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed |
917 | by the <filename>do_install</filename> task are packaged. | 917 | by the <filename>do_install</filename> task are packaged. |
918 | By default, the <filename>PACKAGES</filename> variable contains | 918 | By default, the <filename>PACKAGES</filename> variable contains |
919 | <filename>${PN}-staticdev</filename>, which includes all static library files. | 919 | <filename>${PN}-staticdev</filename>, which includes all static library files. |
920 | <note> | 920 | <note> |
921 | Previously released versions of the Yocto Project defined the static library files | 921 | Previously released versions of the Yocto Project defined the static library files |
922 | through <filename>${PN}-dev</filename>. | 922 | through <filename>${PN}-dev</filename>. |
923 | </note> | 923 | </note> |
924 | Following, is part of the BitBake configuration file. | 924 | Following, is part of the BitBake configuration file. |
925 | You can see where the static library files are defined: | 925 | You can see where the static library files are defined: |
926 | <literallayout class='monospaced'> | 926 | <literallayout class='monospaced'> |
927 | PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale" | 927 | PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale" |
@@ -940,14 +940,14 @@ | |||
940 | FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ | 940 | FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ |
941 | ${datadir}/gnome/help" | 941 | ${datadir}/gnome/help" |
942 | SECTION_${PN}-doc = "doc" | 942 | SECTION_${PN}-doc = "doc" |
943 | 943 | ||
944 | FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \ | 944 | FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \ |
945 | ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ | 945 | ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ |
946 | ${datadir}/aclocal ${base_libdir}/*.o" | 946 | ${datadir}/aclocal ${base_libdir}/*.o" |
947 | SECTION_${PN}-dev = "devel" | 947 | SECTION_${PN}-dev = "devel" |
948 | ALLOW_EMPTY_${PN}-dev = "1" | 948 | ALLOW_EMPTY_${PN}-dev = "1" |
949 | RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})" | 949 | RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})" |
950 | 950 | ||
951 | FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a" | 951 | FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a" |
952 | SECTION_${PN}-staticdev = "devel" | 952 | SECTION_${PN}-staticdev = "devel" |
953 | RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})" | 953 | RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})" |
@@ -960,10 +960,10 @@ | |||
960 | 960 | ||
961 | <para> | 961 | <para> |
962 | To add a post-installation script to a package, add a <filename>pkg_postinst_PACKAGENAME() | 962 | To add a post-installation script to a package, add a <filename>pkg_postinst_PACKAGENAME() |
963 | </filename> function to the <filename>.bb</filename> file and use | 963 | </filename> function to the <filename>.bb</filename> file and use |
964 | <filename>PACKAGENAME</filename> as the name of the package you want to attach to the | 964 | <filename>PACKAGENAME</filename> as the name of the package you want to attach to the |
965 | <filename>postinst</filename> script. | 965 | <filename>postinst</filename> script. |
966 | Normally | 966 | Normally |
967 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> | 967 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> |
968 | can be used, which automatically expands to <filename>PACKAGENAME</filename>. | 968 | can be used, which automatically expands to <filename>PACKAGENAME</filename>. |
969 | A post-installation function has the following structure: | 969 | A post-installation function has the following structure: |
@@ -976,18 +976,18 @@ | |||
976 | </para> | 976 | </para> |
977 | 977 | ||
978 | <para> | 978 | <para> |
979 | The script defined in the post-installation function is called when the | 979 | The script defined in the post-installation function is called when the |
980 | root filesystem is created. | 980 | root filesystem is created. |
981 | If the script succeeds, the package is marked as installed. | 981 | If the script succeeds, the package is marked as installed. |
982 | If the script fails, the package is marked as unpacked and the script is | 982 | If the script fails, the package is marked as unpacked and the script is |
983 | executed when the image boots again. | 983 | executed when the image boots again. |
984 | </para> | 984 | </para> |
985 | 985 | ||
986 | <para> | 986 | <para> |
987 | Sometimes it is necessary for the execution of a post-installation | 987 | Sometimes it is necessary for the execution of a post-installation |
988 | script to be delayed until the first boot. | 988 | script to be delayed until the first boot. |
989 | For example, the script might need to be executed on the device itself. | 989 | For example, the script might need to be executed on the device itself. |
990 | To delay script execution until boot time, use the following structure in the | 990 | To delay script execution until boot time, use the following structure in the |
991 | post-installation script: | 991 | post-installation script: |
992 | <literallayout class='monospaced'> | 992 | <literallayout class='monospaced'> |
993 | pkg_postinst_PACKAGENAME () { | 993 | pkg_postinst_PACKAGENAME () { |
@@ -1002,11 +1002,11 @@ | |||
1002 | </para> | 1002 | </para> |
1003 | 1003 | ||
1004 | <para> | 1004 | <para> |
1005 | The previous example delays execution until the image boots again because the | 1005 | The previous example delays execution until the image boots again because the |
1006 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename> | 1006 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename> |
1007 | variable points | 1007 | variable points |
1008 | to the directory containing the image when the root filesystem is created at build time but | 1008 | to the directory containing the image when the root filesystem is created at build time but |
1009 | is unset when executed on the first boot. | 1009 | is unset when executed on the first boot. |
1010 | </para> | 1010 | </para> |
1011 | </section> | 1011 | </section> |
1012 | </section> | 1012 | </section> |
@@ -1015,19 +1015,19 @@ | |||
1015 | <title>Adding a New Machine</title> | 1015 | <title>Adding a New Machine</title> |
1016 | 1016 | ||
1017 | <para> | 1017 | <para> |
1018 | Adding a new machine to the Yocto Project is a straightforward process. | 1018 | Adding a new machine to the Yocto Project is a straightforward process. |
1019 | This section provides information that gives you an idea of the changes you must make. | 1019 | This section provides information that gives you an idea of the changes you must make. |
1020 | The information covers adding machines similar to those the Yocto Project already supports. | 1020 | The information covers adding machines similar to those the Yocto Project already supports. |
1021 | Although well within the capabilities of the Yocto Project, adding a totally new architecture | 1021 | Although well within the capabilities of the Yocto Project, adding a totally new architecture |
1022 | might require | 1022 | might require |
1023 | changes to <filename>gcc/eglibc</filename> and to the site information, which is | 1023 | changes to <filename>gcc/eglibc</filename> and to the site information, which is |
1024 | beyond the scope of this manual. | 1024 | beyond the scope of this manual. |
1025 | </para> | 1025 | </para> |
1026 | 1026 | ||
1027 | <para> | 1027 | <para> |
1028 | For a complete example that shows how to add a new machine, | 1028 | For a complete example that shows how to add a new machine, |
1029 | see the | 1029 | see the |
1030 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" | 1030 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" |
1031 | in the Yocto Project Board Support Package (BSP) Developer's Guide. | 1031 | in the Yocto Project Board Support Package (BSP) Developer's Guide. |
1032 | </para> | 1032 | </para> |
1033 | 1033 | ||
@@ -1053,7 +1053,7 @@ | |||
1053 | </itemizedlist> | 1053 | </itemizedlist> |
1054 | </para> | 1054 | </para> |
1055 | 1055 | ||
1056 | <para> | 1056 | <para> |
1057 | You might also need these variables: | 1057 | You might also need these variables: |
1058 | <itemizedlist> | 1058 | <itemizedlist> |
1059 | <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLE'> | 1059 | <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLE'> |
@@ -1065,9 +1065,9 @@ | |||
1065 | </itemizedlist> | 1065 | </itemizedlist> |
1066 | </para> | 1066 | </para> |
1067 | 1067 | ||
1068 | <para> | 1068 | <para> |
1069 | You can find full details on these variables in the reference section. | 1069 | You can find full details on these variables in the reference section. |
1070 | You can leverage many existing machine <filename>.conf</filename> files from | 1070 | You can leverage many existing machine <filename>.conf</filename> files from |
1071 | <filename>meta/conf/machine/</filename>. | 1071 | <filename>meta/conf/machine/</filename>. |
1072 | </para> | 1072 | </para> |
1073 | </section> | 1073 | </section> |
@@ -1076,37 +1076,37 @@ | |||
1076 | <title>Adding a Kernel for the Machine</title> | 1076 | <title>Adding a Kernel for the Machine</title> |
1077 | 1077 | ||
1078 | <para> | 1078 | <para> |
1079 | The OpenEmbedded build system needs to be able to build a kernel for the machine. | 1079 | The OpenEmbedded build system needs to be able to build a kernel for the machine. |
1080 | You need to either create a new kernel recipe for this machine, or extend an | 1080 | You need to either create a new kernel recipe for this machine, or extend an |
1081 | existing recipe. | 1081 | existing recipe. |
1082 | You can find several kernel examples in the | 1082 | You can find several kernel examples in the |
1083 | Source Directory at <filename>meta/recipes-kernel/linux</filename> | 1083 | Source Directory at <filename>meta/recipes-kernel/linux</filename> |
1084 | that you can use as references. | 1084 | that you can use as references. |
1085 | </para> | 1085 | </para> |
1086 | 1086 | ||
1087 | <para> | 1087 | <para> |
1088 | If you are creating a new recipe, normal recipe-writing rules apply for setting | 1088 | If you are creating a new recipe, normal recipe-writing rules apply for setting |
1089 | up a | 1089 | up a |
1090 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>. | 1090 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>. |
1091 | Thus, you need to specify any necessary patches and set | 1091 | Thus, you need to specify any necessary patches and set |
1092 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> to point at the source code. | 1092 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> to point at the source code. |
1093 | You need to create a <filename>configure</filename> task that configures the | 1093 | You need to create a <filename>configure</filename> task that configures the |
1094 | unpacked kernel with a defconfig. | 1094 | unpacked kernel with a defconfig. |
1095 | You can do this by using a <filename>make defconfig</filename> command or, | 1095 | You can do this by using a <filename>make defconfig</filename> command or, |
1096 | more commonly, by copying in a suitable <filename>defconfig</filename> file and and then running | 1096 | more commonly, by copying in a suitable <filename>defconfig</filename> file and and then running |
1097 | <filename>make oldconfig</filename>. | 1097 | <filename>make oldconfig</filename>. |
1098 | By making use of <filename>inherit kernel</filename> and potentially some of the | 1098 | By making use of <filename>inherit kernel</filename> and potentially some of the |
1099 | <filename>linux-*.inc</filename> files, most other functionality is | 1099 | <filename>linux-*.inc</filename> files, most other functionality is |
1100 | centralized and the the defaults of the class normally work well. | 1100 | centralized and the the defaults of the class normally work well. |
1101 | </para> | 1101 | </para> |
1102 | 1102 | ||
1103 | <para> | 1103 | <para> |
1104 | If you are extending an existing kernel, it is usually a matter of adding a | 1104 | If you are extending an existing kernel, it is usually a matter of adding a |
1105 | suitable defconfig file. | 1105 | suitable defconfig file. |
1106 | The file needs to be added into a location similar to defconfig files | 1106 | The file needs to be added into a location similar to defconfig files |
1107 | used for other machines in a given kernel. | 1107 | used for other machines in a given kernel. |
1108 | A possible way to do this is by listing the file in the | 1108 | A possible way to do this is by listing the file in the |
1109 | <filename>SRC_URI</filename> and adding the machine to the expression in | 1109 | <filename>SRC_URI</filename> and adding the machine to the expression in |
1110 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>: | 1110 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>: |
1111 | <literallayout class='monospaced'> | 1111 | <literallayout class='monospaced'> |
1112 | COMPATIBLE_MACHINE = '(qemux86|qemumips)' | 1112 | COMPATIBLE_MACHINE = '(qemux86|qemumips)' |
@@ -1118,25 +1118,25 @@ | |||
1118 | <title>Adding a Formfactor Configuration File</title> | 1118 | <title>Adding a Formfactor Configuration File</title> |
1119 | 1119 | ||
1120 | <para> | 1120 | <para> |
1121 | A formfactor configuration file provides information about the | 1121 | A formfactor configuration file provides information about the |
1122 | target hardware for which the image is being built and information that | 1122 | target hardware for which the image is being built and information that |
1123 | the build system cannot obtain from other sources such as the kernel. | 1123 | the build system cannot obtain from other sources such as the kernel. |
1124 | Some examples of information contained in a formfactor configuration file include | 1124 | Some examples of information contained in a formfactor configuration file include |
1125 | framebuffer orientation, whether or not the system has a keyboard, | 1125 | framebuffer orientation, whether or not the system has a keyboard, |
1126 | the positioning of the keyboard in relation to the screen, and | 1126 | the positioning of the keyboard in relation to the screen, and |
1127 | the screen resolution. | 1127 | the screen resolution. |
1128 | </para> | 1128 | </para> |
1129 | 1129 | ||
1130 | <para> | 1130 | <para> |
1131 | The build system uses reasonable defaults in most cases, but if customization is | 1131 | The build system uses reasonable defaults in most cases, but if customization is |
1132 | necessary you need to create a <filename>machconfig</filename> file | 1132 | necessary you need to create a <filename>machconfig</filename> file |
1133 | in the <filename>meta/recipes-bsp/formfactor/files</filename> | 1133 | in the <filename>meta/recipes-bsp/formfactor/files</filename> |
1134 | directory. | 1134 | directory. |
1135 | This directory contains directories for specific machines such as | 1135 | This directory contains directories for specific machines such as |
1136 | <filename>qemuarm</filename> and <filename>qemux86</filename>. | 1136 | <filename>qemuarm</filename> and <filename>qemux86</filename>. |
1137 | For information about the settings available and the defaults, see the | 1137 | For information about the settings available and the defaults, see the |
1138 | <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the | 1138 | <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the |
1139 | same area. | 1139 | same area. |
1140 | Following is an example for qemuarm: | 1140 | Following is an example for qemuarm: |
1141 | <literallayout class='monospaced'> | 1141 | <literallayout class='monospaced'> |
1142 | HAVE_TOUCHSCREEN=1 | 1142 | HAVE_TOUCHSCREEN=1 |
@@ -1160,8 +1160,8 @@ | |||
1160 | <para> | 1160 | <para> |
1161 | The build system offers the ability to build libraries with different | 1161 | The build system offers the ability to build libraries with different |
1162 | target optimizations or architecture formats and combine these together | 1162 | target optimizations or architecture formats and combine these together |
1163 | into one system image. | 1163 | into one system image. |
1164 | You can link different binaries in the image | 1164 | You can link different binaries in the image |
1165 | against the different libraries as needed for specific use cases. | 1165 | against the different libraries as needed for specific use cases. |
1166 | This feature is called "Multilib." | 1166 | This feature is called "Multilib." |
1167 | </para> | 1167 | </para> |
@@ -1175,17 +1175,17 @@ | |||
1175 | 1175 | ||
1176 | <para> | 1176 | <para> |
1177 | While the Multilib feature is most commonly used for 32 and 64-bit differences, | 1177 | While the Multilib feature is most commonly used for 32 and 64-bit differences, |
1178 | the approach the build system uses facilitates different target optimizations. | 1178 | the approach the build system uses facilitates different target optimizations. |
1179 | You could compile some binaries to use one set of libraries and other binaries | 1179 | You could compile some binaries to use one set of libraries and other binaries |
1180 | to use other different sets of libraries. | 1180 | to use other different sets of libraries. |
1181 | The libraries could differ in architecture, compiler options, or other | 1181 | The libraries could differ in architecture, compiler options, or other |
1182 | optimizations. | 1182 | optimizations. |
1183 | </para> | 1183 | </para> |
1184 | 1184 | ||
1185 | <para> | 1185 | <para> |
1186 | This section overviews the Multilib process only. | 1186 | This section overviews the Multilib process only. |
1187 | For more details on how to implement Multilib, see the | 1187 | For more details on how to implement Multilib, see the |
1188 | <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki | 1188 | <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki |
1189 | page. | 1189 | page. |
1190 | </para> | 1190 | </para> |
1191 | 1191 | ||
@@ -1200,31 +1200,31 @@ | |||
1200 | 1200 | ||
1201 | <para> | 1201 | <para> |
1202 | In order to enable Multilib, you first need to ensure your recipe is | 1202 | In order to enable Multilib, you first need to ensure your recipe is |
1203 | extended to support multiple libraries. | 1203 | extended to support multiple libraries. |
1204 | Many standard recipes are already extended and support multiple libraries. | 1204 | Many standard recipes are already extended and support multiple libraries. |
1205 | You can check in the <filename>meta/conf/multilib.conf</filename> | 1205 | You can check in the <filename>meta/conf/multilib.conf</filename> |
1206 | configuration file in the Source Directory to see how this is | 1206 | configuration file in the Source Directory to see how this is |
1207 | done using the | 1207 | done using the |
1208 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink> | 1208 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink> |
1209 | variable. | 1209 | variable. |
1210 | Eventually, all recipes will be covered and this list will be unneeded. | 1210 | Eventually, all recipes will be covered and this list will be unneeded. |
1211 | </para> | 1211 | </para> |
1212 | 1212 | ||
1213 | <para> | 1213 | <para> |
1214 | For the most part, the Multilib class extension works automatically to | 1214 | For the most part, the Multilib class extension works automatically to |
1215 | extend the package name from <filename>${PN}</filename> to | 1215 | extend the package name from <filename>${PN}</filename> to |
1216 | <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename> | 1216 | <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename> |
1217 | is the particular multilib (e.g. "lib32-" or "lib64-"). | 1217 | is the particular multilib (e.g. "lib32-" or "lib64-"). |
1218 | Standard variables such as | 1218 | Standard variables such as |
1219 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>, | 1219 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>, |
1220 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>, | 1220 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>, |
1221 | <filename>RPROVIDES</filename>, | 1221 | <filename>RPROVIDES</filename>, |
1222 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>, | 1222 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>, |
1223 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>, | 1223 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>, |
1224 | and <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system. | 1224 | and <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system. |
1225 | If you are extending any manual code in the recipe, you can use the | 1225 | If you are extending any manual code in the recipe, you can use the |
1226 | <filename>${MLPREFIX}</filename> variable to ensure those names are extended | 1226 | <filename>${MLPREFIX}</filename> variable to ensure those names are extended |
1227 | correctly. | 1227 | correctly. |
1228 | This automatic extension code resides in <filename>multilib.bbclass</filename>. | 1228 | This automatic extension code resides in <filename>multilib.bbclass</filename>. |
1229 | </para> | 1229 | </para> |
1230 | </section> | 1230 | </section> |
@@ -1234,10 +1234,10 @@ | |||
1234 | 1234 | ||
1235 | <para> | 1235 | <para> |
1236 | After you have set up the recipes, you need to define the actual | 1236 | After you have set up the recipes, you need to define the actual |
1237 | combination of multiple libraries you want to build. | 1237 | combination of multiple libraries you want to build. |
1238 | You accomplish this through your <filename>local.conf</filename> | 1238 | You accomplish this through your <filename>local.conf</filename> |
1239 | configuration file in the | 1239 | configuration file in the |
1240 | <link linkend='build-directory'>Build Directory</link>. | 1240 | <link linkend='build-directory'>Build Directory</link>. |
1241 | An example configuration would be as follows: | 1241 | An example configuration would be as follows: |
1242 | <literallayout class='monospaced'> | 1242 | <literallayout class='monospaced'> |
1243 | MACHINE = "qemux86-64" | 1243 | MACHINE = "qemux86-64" |
@@ -1247,7 +1247,7 @@ | |||
1247 | IMAGE_INSTALL = "lib32-connman" | 1247 | IMAGE_INSTALL = "lib32-connman" |
1248 | </literallayout> | 1248 | </literallayout> |
1249 | This example enables an | 1249 | This example enables an |
1250 | additional library named <filename>lib32</filename> alongside the | 1250 | additional library named <filename>lib32</filename> alongside the |
1251 | normal target packages. | 1251 | normal target packages. |
1252 | When combining these "lib32" alternatives, the example uses "x86" for tuning. | 1252 | When combining these "lib32" alternatives, the example uses "x86" for tuning. |
1253 | For information on this particular tuning, see | 1253 | For information on this particular tuning, see |
@@ -1256,8 +1256,8 @@ | |||
1256 | 1256 | ||
1257 | <para> | 1257 | <para> |
1258 | The example then includes <filename>lib32-connman</filename> | 1258 | The example then includes <filename>lib32-connman</filename> |
1259 | in all the images, which illustrates one method of including a | 1259 | in all the images, which illustrates one method of including a |
1260 | multiple library dependency. | 1260 | multiple library dependency. |
1261 | You can use a normal image build to include this dependency, | 1261 | You can use a normal image build to include this dependency, |
1262 | for example: | 1262 | for example: |
1263 | <literallayout class='monospaced'> | 1263 | <literallayout class='monospaced'> |
@@ -1275,29 +1275,29 @@ | |||
1275 | 1275 | ||
1276 | <para> | 1276 | <para> |
1277 | Different packaging systems have different levels of native Multilib | 1277 | Different packaging systems have different levels of native Multilib |
1278 | support. | 1278 | support. |
1279 | For the RPM Package Management System, the following implementation details | 1279 | For the RPM Package Management System, the following implementation details |
1280 | exist: | 1280 | exist: |
1281 | <itemizedlist> | 1281 | <itemizedlist> |
1282 | <listitem><para>A unique architecture is defined for the Multilib packages, | 1282 | <listitem><para>A unique architecture is defined for the Multilib packages, |
1283 | along with creating a unique deploy folder under | 1283 | along with creating a unique deploy folder under |
1284 | <filename>tmp/deploy/rpm</filename> in the | 1284 | <filename>tmp/deploy/rpm</filename> in the |
1285 | <link linkend='build-directory'>Build Directory</link>. | 1285 | <link linkend='build-directory'>Build Directory</link>. |
1286 | For example, consider <filename>lib32</filename> in a | 1286 | For example, consider <filename>lib32</filename> in a |
1287 | <filename>qemux86-64</filename> image. | 1287 | <filename>qemux86-64</filename> image. |
1288 | The possible architectures in the system are "all", "qemux86_64", | 1288 | The possible architectures in the system are "all", "qemux86_64", |
1289 | "lib32_qemux86_64", and "lib32_x86".</para></listitem> | 1289 | "lib32_qemux86_64", and "lib32_x86".</para></listitem> |
1290 | <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from | 1290 | <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from |
1291 | <filename>${PN}</filename> during RPM packaging. | 1291 | <filename>${PN}</filename> during RPM packaging. |
1292 | The naming for a normal RPM package and a Multilib RPM package in a | 1292 | The naming for a normal RPM package and a Multilib RPM package in a |
1293 | <filename>qemux86-64</filename> system resolves to something similar to | 1293 | <filename>qemux86-64</filename> system resolves to something similar to |
1294 | <filename>bash-4.1-r2.x86_64.rpm</filename> and | 1294 | <filename>bash-4.1-r2.x86_64.rpm</filename> and |
1295 | <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively. | 1295 | <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively. |
1296 | </para></listitem> | 1296 | </para></listitem> |
1297 | <listitem><para>When installing a Multilib image, the RPM backend first | 1297 | <listitem><para>When installing a Multilib image, the RPM backend first |
1298 | installs the base image and then installs the Multilib libraries. | 1298 | installs the base image and then installs the Multilib libraries. |
1299 | </para></listitem> | 1299 | </para></listitem> |
1300 | <listitem><para>The build system relies on RPM to resolve the identical files in the | 1300 | <listitem><para>The build system relies on RPM to resolve the identical files in the |
1301 | two (or more) Multilib packages.</para></listitem> | 1301 | two (or more) Multilib packages.</para></listitem> |
1302 | </itemizedlist> | 1302 | </itemizedlist> |
1303 | </para> | 1303 | </para> |
@@ -1305,23 +1305,23 @@ | |||
1305 | <para> | 1305 | <para> |
1306 | For the IPK Package Management System, the following implementation details exist: | 1306 | For the IPK Package Management System, the following implementation details exist: |
1307 | <itemizedlist> | 1307 | <itemizedlist> |
1308 | <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from | 1308 | <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from |
1309 | <filename>${PN}</filename> during IPK packaging. | 1309 | <filename>${PN}</filename> during IPK packaging. |
1310 | The naming for a normal RPM package and a Multilib IPK package in a | 1310 | The naming for a normal RPM package and a Multilib IPK package in a |
1311 | <filename>qemux86-64</filename> system resolves to something like | 1311 | <filename>qemux86-64</filename> system resolves to something like |
1312 | <filename>bash_4.1-r2.x86_64.ipk</filename> and | 1312 | <filename>bash_4.1-r2.x86_64.ipk</filename> and |
1313 | <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively. | 1313 | <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively. |
1314 | </para></listitem> | 1314 | </para></listitem> |
1315 | <listitem><para>The IPK deploy folder is not modified with | 1315 | <listitem><para>The IPK deploy folder is not modified with |
1316 | <filename>${MLPREFIX}</filename> because packages with and without | 1316 | <filename>${MLPREFIX}</filename> because packages with and without |
1317 | the Multilib feature can exist in the same folder due to the | 1317 | the Multilib feature can exist in the same folder due to the |
1318 | <filename>${PN}</filename> differences.</para></listitem> | 1318 | <filename>${PN}</filename> differences.</para></listitem> |
1319 | <listitem><para>IPK defines a sanity check for Multilib installation | 1319 | <listitem><para>IPK defines a sanity check for Multilib installation |
1320 | using certain rules for file comparison, overridden, etc. | 1320 | using certain rules for file comparison, overridden, etc. |
1321 | </para></listitem> | 1321 | </para></listitem> |
1322 | </itemizedlist> | 1322 | </itemizedlist> |
1323 | </para> | 1323 | </para> |
1324 | </section> | 1324 | </section> |
1325 | </section> | 1325 | </section> |
1326 | 1326 | ||
1327 | <section id='configuring-the-kernel'> | 1327 | <section id='configuring-the-kernel'> |
@@ -1330,9 +1330,9 @@ | |||
1330 | <para> | 1330 | <para> |
1331 | Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename> | 1331 | Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename> |
1332 | file has all the right information in it for the image you are building. | 1332 | file has all the right information in it for the image you are building. |
1333 | You can use the <filename>menuconfig</filename> tool and configuration fragments to | 1333 | You can use the <filename>menuconfig</filename> tool and configuration fragments to |
1334 | make sure your <filename>.config</filename> file is just how you need it. | 1334 | make sure your <filename>.config</filename> file is just how you need it. |
1335 | This section describes how to use <filename>menuconfig</filename>, create and use | 1335 | This section describes how to use <filename>menuconfig</filename>, create and use |
1336 | configuration fragments, and how to interactively tweak your <filename>.config</filename> | 1336 | configuration fragments, and how to interactively tweak your <filename>.config</filename> |
1337 | file to create the leanest kernel configuration file possible. | 1337 | file to create the leanest kernel configuration file possible. |
1338 | </para> | 1338 | </para> |
@@ -1345,7 +1345,7 @@ | |||
1345 | 1345 | ||
1346 | <section id='using-menuconfig'> | 1346 | <section id='using-menuconfig'> |
1347 | <title>Using <filename>menuconfig</filename></title> | 1347 | <title>Using <filename>menuconfig</filename></title> |
1348 | 1348 | ||
1349 | <para> | 1349 | <para> |
1350 | The easiest way to define kernel configurations is to set them through the | 1350 | The easiest way to define kernel configurations is to set them through the |
1351 | <filename>menuconfig</filename> tool. | 1351 | <filename>menuconfig</filename> tool. |
@@ -1359,28 +1359,28 @@ | |||
1359 | To use the <filename>menuconfig</filename> tool in the Yocto Project development | 1359 | To use the <filename>menuconfig</filename> tool in the Yocto Project development |
1360 | environment, you must build the tool using BitBake. | 1360 | environment, you must build the tool using BitBake. |
1361 | Thus, the environment must be set up using the <filename>&OE_INIT_FILE;</filename> | 1361 | Thus, the environment must be set up using the <filename>&OE_INIT_FILE;</filename> |
1362 | script found in the | 1362 | script found in the |
1363 | <link linkend='build-directory'>Build Directory</link>. | 1363 | <link linkend='build-directory'>Build Directory</link>. |
1364 | The following commands build and invoke <filename>menuconfig</filename> assuming the | 1364 | The following commands build and invoke <filename>menuconfig</filename> assuming the |
1365 | Source Directory top-level folder is <filename>~/poky</filename>: | 1365 | Source Directory top-level folder is <filename>~/poky</filename>: |
1366 | <literallayout class='monospaced'> | 1366 | <literallayout class='monospaced'> |
1367 | $ cd ~/poky | 1367 | $ cd ~/poky |
1368 | $ source oe-init-build-env | 1368 | $ source oe-init-build-env |
1369 | $ bitbake linux-yocto -c menuconfig | 1369 | $ bitbake linux-yocto -c menuconfig |
1370 | </literallayout> | 1370 | </literallayout> |
1371 | Once <filename>menuconfig</filename> comes up, its standard interface allows you to | 1371 | Once <filename>menuconfig</filename> comes up, its standard interface allows you to |
1372 | interactively examine and configure all the kernel configuration parameters. | 1372 | interactively examine and configure all the kernel configuration parameters. |
1373 | After making your changes, simply exit the tool and save your changes to | 1373 | After making your changes, simply exit the tool and save your changes to |
1374 | create an updated version of the <filename>.config</filename> configuration file. | 1374 | create an updated version of the <filename>.config</filename> configuration file. |
1375 | </para> | 1375 | </para> |
1376 | 1376 | ||
1377 | <para> | 1377 | <para> |
1378 | Consider an example that configures the <filename>linux-yocto-3.4</filename> | 1378 | Consider an example that configures the <filename>linux-yocto-3.4</filename> |
1379 | kernel. | 1379 | kernel. |
1380 | The OpenEmbedded build system recognizes this kernel as | 1380 | The OpenEmbedded build system recognizes this kernel as |
1381 | <filename>linux-yocto</filename>. | 1381 | <filename>linux-yocto</filename>. |
1382 | Thus, the following commands from the shell in which you previously sourced the | 1382 | Thus, the following commands from the shell in which you previously sourced the |
1383 | environment initialization script cleans the shared state cache and the | 1383 | environment initialization script cleans the shared state cache and the |
1384 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> | 1384 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> |
1385 | directory and then builds and launches <filename>menuconfig</filename>: | 1385 | directory and then builds and launches <filename>menuconfig</filename>: |
1386 | <literallayout class='monospaced'> | 1386 | <literallayout class='monospaced'> |
@@ -1389,11 +1389,11 @@ | |||
1389 | </para> | 1389 | </para> |
1390 | 1390 | ||
1391 | <para> | 1391 | <para> |
1392 | Once <filename>menuconfig</filename> launches, you use the interface | 1392 | Once <filename>menuconfig</filename> launches, you use the interface |
1393 | to navigate through the selections to find the configuration settings in | 1393 | to navigate through the selections to find the configuration settings in |
1394 | which you are interested. | 1394 | which you are interested. |
1395 | For example, consider the <filename>CONFIG_SMP</filename> configuration setting. | 1395 | For example, consider the <filename>CONFIG_SMP</filename> configuration setting. |
1396 | You can find it at <filename>Processor Type and Features</filename> under | 1396 | You can find it at <filename>Processor Type and Features</filename> under |
1397 | the configuration selection <filename>Symmetric Multi-processing Support</filename>. | 1397 | the configuration selection <filename>Symmetric Multi-processing Support</filename>. |
1398 | After highlighting the selection, you can use the arrow keys to select or deselect | 1398 | After highlighting the selection, you can use the arrow keys to select or deselect |
1399 | the setting. | 1399 | the setting. |
@@ -1402,24 +1402,24 @@ | |||
1402 | 1402 | ||
1403 | <para> | 1403 | <para> |
1404 | Saving the selections updates the <filename>.config</filename> configuration file. | 1404 | Saving the selections updates the <filename>.config</filename> configuration file. |
1405 | This is the file that the OpenEmbedded build system uses to configure the | 1405 | This is the file that the OpenEmbedded build system uses to configure the |
1406 | kernel during the build. | 1406 | kernel during the build. |
1407 | You can find and examine this file in the Build Directory in | 1407 | You can find and examine this file in the Build Directory in |
1408 | <filename>tmp/work/</filename>. | 1408 | <filename>tmp/work/</filename>. |
1409 | The actual <filename>.config</filename> is located in the area where the | 1409 | The actual <filename>.config</filename> is located in the area where the |
1410 | specific kernel is built. | 1410 | specific kernel is built. |
1411 | For example, if you were building a Linux Yocto kernel based on the | 1411 | For example, if you were building a Linux Yocto kernel based on the |
1412 | Linux 3.4 kernel and you were building a QEMU image targeted for | 1412 | Linux 3.4 kernel and you were building a QEMU image targeted for |
1413 | <filename>x86</filename> architecture, the | 1413 | <filename>x86</filename> architecture, the |
1414 | <filename>.config</filename> file would be located here: | 1414 | <filename>.config</filename> file would be located here: |
1415 | <literallayout class='monospaced'> | 1415 | <literallayout class='monospaced'> |
1416 | ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f... | 1416 | ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f... |
1417 | ...656ed30-r1/linux-qemux86-standard-build | 1417 | ...656ed30-r1/linux-qemux86-standard-build |
1418 | </literallayout> | 1418 | </literallayout> |
1419 | <note> | 1419 | <note> |
1420 | The previous example directory is artificially split and many of the characters | 1420 | The previous example directory is artificially split and many of the characters |
1421 | in the actual filename are omitted in order to make it more readable. | 1421 | in the actual filename are omitted in order to make it more readable. |
1422 | Also, depending on the kernel you are using, the exact pathname | 1422 | Also, depending on the kernel you are using, the exact pathname |
1423 | for <filename>linux-yocto-3.4...</filename> might differ. | 1423 | for <filename>linux-yocto-3.4...</filename> might differ. |
1424 | </note> | 1424 | </note> |
1425 | </para> | 1425 | </para> |
@@ -1434,18 +1434,18 @@ | |||
1434 | </para> | 1434 | </para> |
1435 | 1435 | ||
1436 | <para> | 1436 | <para> |
1437 | A good method to isolate changed configurations is to use a combination of the | 1437 | A good method to isolate changed configurations is to use a combination of the |
1438 | <filename>menuconfig</filename> tool and simple shell commands. | 1438 | <filename>menuconfig</filename> tool and simple shell commands. |
1439 | Before changing configurations with <filename>menuconfig</filename>, copy the | 1439 | Before changing configurations with <filename>menuconfig</filename>, copy the |
1440 | existing <filename>.config</filename> and rename it to something else, | 1440 | existing <filename>.config</filename> and rename it to something else, |
1441 | use <filename>menuconfig</filename> to make | 1441 | use <filename>menuconfig</filename> to make |
1442 | as many changes an you want and save them, then compare the renamed configuration | 1442 | as many changes an you want and save them, then compare the renamed configuration |
1443 | file against the newly created file. | 1443 | file against the newly created file. |
1444 | You can use the resulting differences as your base to create configuration fragments | 1444 | You can use the resulting differences as your base to create configuration fragments |
1445 | to permanently save in your kernel layer. | 1445 | to permanently save in your kernel layer. |
1446 | <note> | 1446 | <note> |
1447 | Be sure to make a copy of the <filename>.config</filename> and don't just | 1447 | Be sure to make a copy of the <filename>.config</filename> and don't just |
1448 | rename it. | 1448 | rename it. |
1449 | The build system needs an existing <filename>.config</filename> | 1449 | The build system needs an existing <filename>.config</filename> |
1450 | from which to work. | 1450 | from which to work. |
1451 | </note> | 1451 | </note> |
@@ -1459,13 +1459,13 @@ | |||
1459 | Configuration fragments are simply kernel options that appear in a file | 1459 | Configuration fragments are simply kernel options that appear in a file |
1460 | placed where the OpenEmbedded build system can find and apply them. | 1460 | placed where the OpenEmbedded build system can find and apply them. |
1461 | Syntactically, the configuration statement is identical to what would appear | 1461 | Syntactically, the configuration statement is identical to what would appear |
1462 | in the <filename>.config</filename> file, which is in the | 1462 | in the <filename>.config</filename> file, which is in the |
1463 | <link linkend='build-directory'>Build Directory</link> in | 1463 | <link linkend='build-directory'>Build Directory</link> in |
1464 | <filename>tmp/work/<arch>-poky-linux/linux-yocto-<release-specific-string>/linux-<arch>-<build-type></filename>. | 1464 | <filename>tmp/work/<arch>-poky-linux/linux-yocto-<release-specific-string>/linux-<arch>-<build-type></filename>. |
1465 | </para> | 1465 | </para> |
1466 | 1466 | ||
1467 | <para> | 1467 | <para> |
1468 | It is simple to create a configuration fragment. | 1468 | It is simple to create a configuration fragment. |
1469 | For example, issuing the following from the shell creates a configuration fragment | 1469 | For example, issuing the following from the shell creates a configuration fragment |
1470 | file named <filename>my_smp.cfg</filename> that enables multi-processor support | 1470 | file named <filename>my_smp.cfg</filename> that enables multi-processor support |
1471 | within the kernel: | 1471 | within the kernel: |
@@ -1480,15 +1480,15 @@ | |||
1480 | 1480 | ||
1481 | <para> | 1481 | <para> |
1482 | Where do you put your configuration files? | 1482 | Where do you put your configuration files? |
1483 | You can place these configuration files in the same area pointed to by | 1483 | You can place these configuration files in the same area pointed to by |
1484 | <filename>SRC_URI</filename>. | 1484 | <filename>SRC_URI</filename>. |
1485 | The OpenEmbedded build system will pick up the configuration and add it to the | 1485 | The OpenEmbedded build system will pick up the configuration and add it to the |
1486 | kernel's configuration. | 1486 | kernel's configuration. |
1487 | For example, suppose you had a set of configuration options in a file called | 1487 | For example, suppose you had a set of configuration options in a file called |
1488 | <filename>myconfig.cfg</filename>. | 1488 | <filename>myconfig.cfg</filename>. |
1489 | If you put that file inside a directory named <filename>/linux-yocto</filename> | 1489 | If you put that file inside a directory named <filename>/linux-yocto</filename> |
1490 | that resides in the same directory as the kernel's append file and then add | 1490 | that resides in the same directory as the kernel's append file and then add |
1491 | a <filename>SRC_URI</filename> statement such as the following to the kernel's append file, | 1491 | a <filename>SRC_URI</filename> statement such as the following to the kernel's append file, |
1492 | those configuration options will be picked up and applied when the kernel is built. | 1492 | those configuration options will be picked up and applied when the kernel is built. |
1493 | <literallayout class='monospaced'> | 1493 | <literallayout class='monospaced'> |
1494 | SRC_URI += "file://myconfig.cfg" | 1494 | SRC_URI += "file://myconfig.cfg" |
@@ -1496,10 +1496,10 @@ | |||
1496 | </para> | 1496 | </para> |
1497 | 1497 | ||
1498 | <para> | 1498 | <para> |
1499 | As mentioned earlier, you can group related configurations into multiple files and | 1499 | As mentioned earlier, you can group related configurations into multiple files and |
1500 | name them all in the <filename>SRC_URI</filename> statement as well. | 1500 | name them all in the <filename>SRC_URI</filename> statement as well. |
1501 | For example, you could group separate configurations specifically for Ethernet and graphics | 1501 | For example, you could group separate configurations specifically for Ethernet and graphics |
1502 | into their own files and add those by using a <filename>SRC_URI</filename> statement like the | 1502 | into their own files and add those by using a <filename>SRC_URI</filename> statement like the |
1503 | following in your append file: | 1503 | following in your append file: |
1504 | <literallayout class='monospaced'> | 1504 | <literallayout class='monospaced'> |
1505 | SRC_URI += "file://myconfig.cfg \ | 1505 | SRC_URI += "file://myconfig.cfg \ |
@@ -1513,27 +1513,27 @@ | |||
1513 | <title>Fine-tuning the Kernel Configuration File</title> | 1513 | <title>Fine-tuning the Kernel Configuration File</title> |
1514 | 1514 | ||
1515 | <para> | 1515 | <para> |
1516 | You can make sure the <filename>.config</filename> is as lean or efficient as | 1516 | You can make sure the <filename>.config</filename> is as lean or efficient as |
1517 | possible by reading the output of the kernel configuration fragment audit, | 1517 | possible by reading the output of the kernel configuration fragment audit, |
1518 | noting any issues, making changes to correct the issues, and then repeating. | 1518 | noting any issues, making changes to correct the issues, and then repeating. |
1519 | </para> | 1519 | </para> |
1520 | 1520 | ||
1521 | <para> | 1521 | <para> |
1522 | As part of the kernel build process, the | 1522 | As part of the kernel build process, the |
1523 | <filename>kernel_configcheck</filename> task runs. | 1523 | <filename>kernel_configcheck</filename> task runs. |
1524 | This task validates the kernel configuration by checking the final | 1524 | This task validates the kernel configuration by checking the final |
1525 | <filename>.config</filename> file against the input files. | 1525 | <filename>.config</filename> file against the input files. |
1526 | During the check, the task produces warning messages for the following | 1526 | During the check, the task produces warning messages for the following |
1527 | issues: | 1527 | issues: |
1528 | <itemizedlist> | 1528 | <itemizedlist> |
1529 | <listitem><para>Requested options that did not make the final | 1529 | <listitem><para>Requested options that did not make the final |
1530 | <filename>.config</filename> file.</para></listitem> | 1530 | <filename>.config</filename> file.</para></listitem> |
1531 | <listitem><para>Configuration items that appear twice in the same | 1531 | <listitem><para>Configuration items that appear twice in the same |
1532 | configuration fragment.</para></listitem> | 1532 | configuration fragment.</para></listitem> |
1533 | <listitem><para>Configuration items tagged as 'required' were overridden. | 1533 | <listitem><para>Configuration items tagged as 'required' were overridden. |
1534 | </para></listitem> | 1534 | </para></listitem> |
1535 | <listitem><para>A board overrides a non-board specific option.</para></listitem> | 1535 | <listitem><para>A board overrides a non-board specific option.</para></listitem> |
1536 | <listitem><para>Listed options not valid for the kernel being processed. | 1536 | <listitem><para>Listed options not valid for the kernel being processed. |
1537 | In other words, the option does not appear anywhere.</para></listitem> | 1537 | In other words, the option does not appear anywhere.</para></listitem> |
1538 | </itemizedlist> | 1538 | </itemizedlist> |
1539 | <note> | 1539 | <note> |
@@ -1555,31 +1555,31 @@ | |||
1555 | <listitem><para>Start with a full configuration that you know | 1555 | <listitem><para>Start with a full configuration that you know |
1556 | works - it builds and boots successfully. | 1556 | works - it builds and boots successfully. |
1557 | This configuration file will be your baseline.</para></listitem> | 1557 | This configuration file will be your baseline.</para></listitem> |
1558 | <listitem><para>Separately run the <filename>configme</filename> and | 1558 | <listitem><para>Separately run the <filename>configme</filename> and |
1559 | <filename>kernel_configcheck</filename> tasks.</para></listitem> | 1559 | <filename>kernel_configcheck</filename> tasks.</para></listitem> |
1560 | <listitem><para>Take the resulting list of files from the | 1560 | <listitem><para>Take the resulting list of files from the |
1561 | <filename>kernel_configcheck</filename> task warnings and do the following: | 1561 | <filename>kernel_configcheck</filename> task warnings and do the following: |
1562 | <itemizedlist> | 1562 | <itemizedlist> |
1563 | <listitem><para>Drop values that are redefined in the fragment but do not | 1563 | <listitem><para>Drop values that are redefined in the fragment but do not |
1564 | change the final <filename>.config</filename> file.</para></listitem> | 1564 | change the final <filename>.config</filename> file.</para></listitem> |
1565 | <listitem><para>Analyze and potentially drop values from the | 1565 | <listitem><para>Analyze and potentially drop values from the |
1566 | <filename>.config</filename> file that override required | 1566 | <filename>.config</filename> file that override required |
1567 | configurations.</para></listitem> | 1567 | configurations.</para></listitem> |
1568 | <listitem><para>Analyze and potentially remove non-board specific options. | 1568 | <listitem><para>Analyze and potentially remove non-board specific options. |
1569 | </para></listitem> | 1569 | </para></listitem> |
1570 | <listitem><para>Remove repeated and invalid options.</para></listitem> | 1570 | <listitem><para>Remove repeated and invalid options.</para></listitem> |
1571 | </itemizedlist></para></listitem> | 1571 | </itemizedlist></para></listitem> |
1572 | <listitem><para>After you have worked through the output of the kernel configuration | 1572 | <listitem><para>After you have worked through the output of the kernel configuration |
1573 | audit, you can re-run the <filename>configme</filename> | 1573 | audit, you can re-run the <filename>configme</filename> |
1574 | and <filename>kernel_configcheck</filename> tasks to see the results of your | 1574 | and <filename>kernel_configcheck</filename> tasks to see the results of your |
1575 | changes. | 1575 | changes. |
1576 | If you have more issues, you can deal with them as described in the | 1576 | If you have more issues, you can deal with them as described in the |
1577 | previous step.</para></listitem> | 1577 | previous step.</para></listitem> |
1578 | </orderedlist> | 1578 | </orderedlist> |
1579 | </para> | 1579 | </para> |
1580 | 1580 | ||
1581 | <para> | 1581 | <para> |
1582 | Iteratively working through steps two through four eventually yields | 1582 | Iteratively working through steps two through four eventually yields |
1583 | a minimal, streamlined configuration file. | 1583 | a minimal, streamlined configuration file. |
1584 | Once you have the best <filename>.config</filename>, you can build the Linux | 1584 | Once you have the best <filename>.config</filename>, you can build the Linux |
1585 | Yocto kernel. | 1585 | Yocto kernel. |
@@ -1589,35 +1589,35 @@ | |||
1589 | 1589 | ||
1590 | <section id="patching-the-kernel"> | 1590 | <section id="patching-the-kernel"> |
1591 | <title>Patching the Kernel</title> | 1591 | <title>Patching the Kernel</title> |
1592 | 1592 | ||
1593 | <para> | 1593 | <para> |
1594 | Patching the kernel involves changing or adding configurations to an existing kernel, | 1594 | Patching the kernel involves changing or adding configurations to an existing kernel, |
1595 | changing or adding recipes to the kernel that are needed to support specific hardware features, | 1595 | changing or adding recipes to the kernel that are needed to support specific hardware features, |
1596 | or even altering the source code itself. | 1596 | or even altering the source code itself. |
1597 | <note> | 1597 | <note> |
1598 | You can use the <filename>yocto-kernel</filename> script | 1598 | You can use the <filename>yocto-kernel</filename> script |
1599 | found in the <link linkend='source-directory'>Source Directory</link> | 1599 | found in the <link linkend='source-directory'>Source Directory</link> |
1600 | under <filename>scripts</filename> to manage kernel patches and configuration. | 1600 | under <filename>scripts</filename> to manage kernel patches and configuration. |
1601 | See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>" | 1601 | See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>" |
1602 | section in the Yocto Project Board Support Packages (BSP) Developer's Guide for | 1602 | section in the Yocto Project Board Support Packages (BSP) Developer's Guide for |
1603 | more information.</note> | 1603 | more information.</note> |
1604 | </para> | 1604 | </para> |
1605 | 1605 | ||
1606 | <para> | 1606 | <para> |
1607 | This example creates a simple patch by adding some QEMU emulator console | 1607 | This example creates a simple patch by adding some QEMU emulator console |
1608 | output at boot time through <filename>printk</filename> statements in the kernel's | 1608 | output at boot time through <filename>printk</filename> statements in the kernel's |
1609 | <filename>calibrate.c</filename> source code file. | 1609 | <filename>calibrate.c</filename> source code file. |
1610 | Applying the patch and booting the modified image causes the added | 1610 | Applying the patch and booting the modified image causes the added |
1611 | messages to appear on the emulator's console. | 1611 | messages to appear on the emulator's console. |
1612 | </para> | 1612 | </para> |
1613 | 1613 | ||
1614 | <para> | 1614 | <para> |
1615 | The example assumes a clean build exists for the <filename>qemux86</filename> | 1615 | The example assumes a clean build exists for the <filename>qemux86</filename> |
1616 | machine in a Source Directory named <filename>poky</filename>. | 1616 | machine in a Source Directory named <filename>poky</filename>. |
1617 | Furthermore, the <link linkend='build-directory'>Build Directory</link> is | 1617 | Furthermore, the <link linkend='build-directory'>Build Directory</link> is |
1618 | <filename>build</filename> and is located in <filename>poky</filename> and | 1618 | <filename>build</filename> and is located in <filename>poky</filename> and |
1619 | the kernel is based on the Linux 3.4 kernel. | 1619 | the kernel is based on the Linux 3.4 kernel. |
1620 | For general information on how to configure the most efficient build, see the | 1620 | For general information on how to configure the most efficient build, see the |
1621 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section | 1621 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section |
1622 | in the Yocto Project Quick Start. | 1622 | in the Yocto Project Quick Start. |
1623 | </para> | 1623 | </para> |
@@ -1631,13 +1631,13 @@ | |||
1631 | $cd ~/poky | 1631 | $cd ~/poky |
1632 | $mkdir meta-mylayer | 1632 | $mkdir meta-mylayer |
1633 | </literallayout> | 1633 | </literallayout> |
1634 | Creating a directory that follows the Yocto Project layer naming | 1634 | Creating a directory that follows the Yocto Project layer naming |
1635 | conventions sets up the layer for your changes. | 1635 | conventions sets up the layer for your changes. |
1636 | The layer is where you place your configuration files, append | 1636 | The layer is where you place your configuration files, append |
1637 | files, and patch files. | 1637 | files, and patch files. |
1638 | To learn more about creating a layer and filling it with the | 1638 | To learn more about creating a layer and filling it with the |
1639 | files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding | 1639 | files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding |
1640 | and Creating Layers</link>" section. | 1640 | and Creating Layers</link>" section. |
1641 | </para> | 1641 | </para> |
1642 | </section> | 1642 | </section> |
1643 | 1643 | ||
@@ -1645,55 +1645,55 @@ | |||
1645 | <title>Finding the Kernel Source Code</title> | 1645 | <title>Finding the Kernel Source Code</title> |
1646 | 1646 | ||
1647 | <para> | 1647 | <para> |
1648 | Each time you build a kernel image, the kernel source code is fetched | 1648 | Each time you build a kernel image, the kernel source code is fetched |
1649 | and unpacked into the following directory: | 1649 | and unpacked into the following directory: |
1650 | <literallayout class='monospaced'> | 1650 | <literallayout class='monospaced'> |
1651 | ${S}/linux | 1651 | ${S}/linux |
1652 | </literallayout> | 1652 | </literallayout> |
1653 | See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" | 1653 | See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" |
1654 | section and the | 1654 | section and the |
1655 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable | 1655 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable |
1656 | for more information about where source is kept during a build. | 1656 | for more information about where source is kept during a build. |
1657 | </para> | 1657 | </para> |
1658 | 1658 | ||
1659 | <para> | 1659 | <para> |
1660 | For this example, we are going to patch the | 1660 | For this example, we are going to patch the |
1661 | <filename>init/calibrate.c</filename> file | 1661 | <filename>init/calibrate.c</filename> file |
1662 | by adding some simple console <filename>printk</filename> statements that we can | 1662 | by adding some simple console <filename>printk</filename> statements that we can |
1663 | see when we boot the image using QEMU. | 1663 | see when we boot the image using QEMU. |
1664 | </para> | 1664 | </para> |
1665 | </section> | 1665 | </section> |
1666 | 1666 | ||
1667 | <section id='creating-the-patch'> | 1667 | <section id='creating-the-patch'> |
1668 | <title>Creating the Patch</title> | 1668 | <title>Creating the Patch</title> |
1669 | 1669 | ||
1670 | <para> | 1670 | <para> |
1671 | Two methods exist by which you can create the patch: | 1671 | Two methods exist by which you can create the patch: |
1672 | <link linkend='using-a-git-workflow'>Git workflow</link> and | 1672 | <link linkend='using-a-git-workflow'>Git workflow</link> and |
1673 | <link linkend='using-a-quilt-workflow'>Quilt workflow</link>. | 1673 | <link linkend='using-a-quilt-workflow'>Quilt workflow</link>. |
1674 | For kernel patches, the Git workflow is more appropriate. | 1674 | For kernel patches, the Git workflow is more appropriate. |
1675 | This section assumes the Git workflow and shows the steps specific to | 1675 | This section assumes the Git workflow and shows the steps specific to |
1676 | this example. | 1676 | this example. |
1677 | <orderedlist> | 1677 | <orderedlist> |
1678 | <listitem><para><emphasis>Change the working directory</emphasis>: | 1678 | <listitem><para><emphasis>Change the working directory</emphasis>: |
1679 | Change to where the kernel source code is before making | 1679 | Change to where the kernel source code is before making |
1680 | your edits to the <filename>calibrate.c</filename> file: | 1680 | your edits to the <filename>calibrate.c</filename> file: |
1681 | <literallayout class='monospaced'> | 1681 | <literallayout class='monospaced'> |
1682 | $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux | 1682 | $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux |
1683 | </literallayout> | 1683 | </literallayout> |
1684 | Because you are working in an established Git repository, | 1684 | Because you are working in an established Git repository, |
1685 | you must be in this directory in order to commit your changes | 1685 | you must be in this directory in order to commit your changes |
1686 | and create the patch file. | 1686 | and create the patch file. |
1687 | <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and | 1687 | <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and |
1688 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables | 1688 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables |
1689 | represent the version and revision for the | 1689 | represent the version and revision for the |
1690 | <filename>linux-yocto</filename> recipe. | 1690 | <filename>linux-yocto</filename> recipe. |
1691 | The <filename>PV</filename> variable includes the Git meta and machine | 1691 | The <filename>PV</filename> variable includes the Git meta and machine |
1692 | hashes, which make the directory name longer than you might | 1692 | hashes, which make the directory name longer than you might |
1693 | expect. | 1693 | expect. |
1694 | </note></para></listitem> | 1694 | </note></para></listitem> |
1695 | <listitem><para><emphasis>Edit the source file</emphasis>: | 1695 | <listitem><para><emphasis>Edit the source file</emphasis>: |
1696 | Edit the <filename>init/calibrate.c</filename> file to have the | 1696 | Edit the <filename>init/calibrate.c</filename> file to have the |
1697 | following changes: | 1697 | following changes: |
1698 | <literallayout class='monospaced'> | 1698 | <literallayout class='monospaced'> |
1699 | void __cpuinit calibrate_delay(void) | 1699 | void __cpuinit calibrate_delay(void) |
@@ -1714,7 +1714,7 @@ | |||
1714 | . | 1714 | . |
1715 | </literallayout></para></listitem> | 1715 | </literallayout></para></listitem> |
1716 | <listitem><para><emphasis>Stage and commit your changes</emphasis>: | 1716 | <listitem><para><emphasis>Stage and commit your changes</emphasis>: |
1717 | These Git commands list out the changed file, stage it, and then | 1717 | These Git commands list out the changed file, stage it, and then |
1718 | commit the file: | 1718 | commit the file: |
1719 | <literallayout class='monospaced'> | 1719 | <literallayout class='monospaced'> |
1720 | $ git status | 1720 | $ git status |
@@ -1723,7 +1723,7 @@ | |||
1723 | </literallayout></para></listitem> | 1723 | </literallayout></para></listitem> |
1724 | <listitem><para><emphasis>Generate the patch file</emphasis>: | 1724 | <listitem><para><emphasis>Generate the patch file</emphasis>: |
1725 | This Git command creates the a patch file named | 1725 | This Git command creates the a patch file named |
1726 | <filename>0001-calibrate-Add-printk-example.patch</filename> | 1726 | <filename>0001-calibrate-Add-printk-example.patch</filename> |
1727 | in the current directory. | 1727 | in the current directory. |
1728 | <literallayout class='monospaced'> | 1728 | <literallayout class='monospaced'> |
1729 | $ git format-patch -1 | 1729 | $ git format-patch -1 |
@@ -1747,8 +1747,8 @@ | |||
1747 | $ mkdir recipes-kernel/linux | 1747 | $ mkdir recipes-kernel/linux |
1748 | $ mkdir recipes-kernel/linux/linux-yocto | 1748 | $ mkdir recipes-kernel/linux/linux-yocto |
1749 | </literallayout> | 1749 | </literallayout> |
1750 | The <filename>conf</filename> directory holds your configuration files, while the | 1750 | The <filename>conf</filename> directory holds your configuration files, while the |
1751 | <filename>recipes-kernel</filename> directory holds your append file and | 1751 | <filename>recipes-kernel</filename> directory holds your append file and |
1752 | your patch file.</para></listitem> | 1752 | your patch file.</para></listitem> |
1753 | <listitem><para><emphasis>Create the layer configuration file</emphasis>: | 1753 | <listitem><para><emphasis>Create the layer configuration file</emphasis>: |
1754 | Move to the <filename>meta-mylayer/conf</filename> directory and create | 1754 | Move to the <filename>meta-mylayer/conf</filename> directory and create |
@@ -1765,7 +1765,7 @@ | |||
1765 | BBFILE_PATTERN_mylayer := "^${LAYERDIR}/" | 1765 | BBFILE_PATTERN_mylayer := "^${LAYERDIR}/" |
1766 | BBFILE_PRIORITY_mylayer = "5" | 1766 | BBFILE_PRIORITY_mylayer = "5" |
1767 | </literallayout> | 1767 | </literallayout> |
1768 | Notice <filename>mylayer</filename> as part of the last three | 1768 | Notice <filename>mylayer</filename> as part of the last three |
1769 | statements.</para></listitem> | 1769 | statements.</para></listitem> |
1770 | <listitem><para><emphasis>Create the kernel recipe append file</emphasis>: | 1770 | <listitem><para><emphasis>Create the kernel recipe append file</emphasis>: |
1771 | Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create | 1771 | Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create |
@@ -1775,13 +1775,13 @@ | |||
1775 | 1775 | ||
1776 | SRC_URI += "file://0001-calibrate-Add-printk-example.patch" | 1776 | SRC_URI += "file://0001-calibrate-Add-printk-example.patch" |
1777 | 1777 | ||
1778 | PRINC := "${@int(PRINC) + 1}" | 1778 | PRINC := "${@int(PRINC) + 1}" |
1779 | </literallayout> | 1779 | </literallayout> |
1780 | The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename> | 1780 | The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename> |
1781 | statements enable the OpenEmbedded build system to find the patch file. | 1781 | statements enable the OpenEmbedded build system to find the patch file. |
1782 | </para></listitem> | 1782 | </para></listitem> |
1783 | <listitem><para><emphasis>Put the patch file in your layer</emphasis>: | 1783 | <listitem><para><emphasis>Put the patch file in your layer</emphasis>: |
1784 | Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to | 1784 | Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to |
1785 | the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename> | 1785 | the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename> |
1786 | directory.</para></listitem> | 1786 | directory.</para></listitem> |
1787 | </orderedlist> | 1787 | </orderedlist> |
@@ -1793,25 +1793,25 @@ | |||
1793 | 1793 | ||
1794 | <para> | 1794 | <para> |
1795 | Do the following to make sure the build parameters are set up for the example. | 1795 | Do the following to make sure the build parameters are set up for the example. |
1796 | Once you set up these build parameters, they do not have to change unless you | 1796 | Once you set up these build parameters, they do not have to change unless you |
1797 | change the target architecture of the machine you are building: | 1797 | change the target architecture of the machine you are building: |
1798 | <itemizedlist> | 1798 | <itemizedlist> |
1799 | <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> Your | 1799 | <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> Your |
1800 | selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | 1800 | selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> |
1801 | definition within the <filename>local.conf</filename> file in the Build Directory | 1801 | definition within the <filename>local.conf</filename> file in the Build Directory |
1802 | specifies the target architecture used when building the Linux kernel. | 1802 | specifies the target architecture used when building the Linux kernel. |
1803 | By default, <filename>MACHINE</filename> is set to | 1803 | By default, <filename>MACHINE</filename> is set to |
1804 | <filename>qemux86</filename>, which specifies a 32-bit | 1804 | <filename>qemux86</filename>, which specifies a 32-bit |
1805 | <trademark class='registered'>Intel</trademark> Architecture | 1805 | <trademark class='registered'>Intel</trademark> Architecture |
1806 | target machine suitable for the QEMU emulator.</para></listitem> | 1806 | target machine suitable for the QEMU emulator.</para></listitem> |
1807 | <listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename> | 1807 | <listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename> |
1808 | Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the | 1808 | Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the |
1809 | <filename>bblayers.conf</filename> file found in the | 1809 | <filename>bblayers.conf</filename> file found in the |
1810 | <filename>poky/build/conf</filename> directory needs to have the path to your local | 1810 | <filename>poky/build/conf</filename> directory needs to have the path to your local |
1811 | <filename>meta-mylayer</filename> layer. | 1811 | <filename>meta-mylayer</filename> layer. |
1812 | By default, the <filename>BBLAYERS</filename> variable contains paths to | 1812 | By default, the <filename>BBLAYERS</filename> variable contains paths to |
1813 | <filename>meta</filename>, <filename>meta-yocto</filename>, and | 1813 | <filename>meta</filename>, <filename>meta-yocto</filename>, and |
1814 | <filename>meta-yocto-bsp</filename> in the | 1814 | <filename>meta-yocto-bsp</filename> in the |
1815 | <filename>poky</filename> Git repository. | 1815 | <filename>poky</filename> Git repository. |
1816 | Add the path to your <filename>meta-mylayer</filename> location: | 1816 | Add the path to your <filename>meta-mylayer</filename> location: |
1817 | <literallayout class='monospaced'> | 1817 | <literallayout class='monospaced'> |
@@ -1847,14 +1847,14 @@ | |||
1847 | </literallayout> | 1847 | </literallayout> |
1848 | </para></listitem> | 1848 | </para></listitem> |
1849 | <listitem><para><emphasis>Clean up</emphasis>: | 1849 | <listitem><para><emphasis>Clean up</emphasis>: |
1850 | Be sure to clean the shared state out by running the | 1850 | Be sure to clean the shared state out by running the |
1851 | <filename>cleansstate</filename> BitBake task as follows from your Build Directory: | 1851 | <filename>cleansstate</filename> BitBake task as follows from your Build Directory: |
1852 | <literallayout class='monospaced'> | 1852 | <literallayout class='monospaced'> |
1853 | $ bitbake -c cleansstate linux-yocto | 1853 | $ bitbake -c cleansstate linux-yocto |
1854 | </literallayout></para> | 1854 | </literallayout></para> |
1855 | <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename> | 1855 | <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename> |
1856 | directory inside the Build Directory. | 1856 | directory inside the Build Directory. |
1857 | Always use the various BitBake clean tasks to clear out previous | 1857 | Always use the various BitBake clean tasks to clear out previous |
1858 | build artifacts. | 1858 | build artifacts. |
1859 | </note></para></listitem> | 1859 | </note></para></listitem> |
1860 | <listitem><para><emphasis>Build the image</emphasis>: | 1860 | <listitem><para><emphasis>Build the image</emphasis>: |
@@ -1873,18 +1873,18 @@ | |||
1873 | These steps boot the image and allow you to see the changes | 1873 | These steps boot the image and allow you to see the changes |
1874 | <orderedlist> | 1874 | <orderedlist> |
1875 | <listitem><para><emphasis>Boot the image</emphasis>: | 1875 | <listitem><para><emphasis>Boot the image</emphasis>: |
1876 | Boot the modified image in the QEMU emulator | 1876 | Boot the modified image in the QEMU emulator |
1877 | using this command: | 1877 | using this command: |
1878 | <literallayout class='monospaced'> | 1878 | <literallayout class='monospaced'> |
1879 | $ runqemu qemux86 | 1879 | $ runqemu qemux86 |
1880 | </literallayout></para></listitem> | 1880 | </literallayout></para></listitem> |
1881 | <listitem><para><emphasis>Verify the changes</emphasis>: | 1881 | <listitem><para><emphasis>Verify the changes</emphasis>: |
1882 | Log into the machine using <filename>root</filename> with no password and then | 1882 | Log into the machine using <filename>root</filename> with no password and then |
1883 | use the following shell command to scroll through the console's boot output. | 1883 | use the following shell command to scroll through the console's boot output. |
1884 | <literallayout class='monospaced'> | 1884 | <literallayout class='monospaced'> |
1885 | # dmesg | less | 1885 | # dmesg | less |
1886 | </literallayout> | 1886 | </literallayout> |
1887 | You should see the results of your <filename>printk</filename> statements | 1887 | You should see the results of your <filename>printk</filename> statements |
1888 | as part of the output.</para></listitem> | 1888 | as part of the output.</para></listitem> |
1889 | </orderedlist> | 1889 | </orderedlist> |
1890 | </para> | 1890 | </para> |
@@ -1895,10 +1895,10 @@ | |||
1895 | <title>Updating Existing Images</title> | 1895 | <title>Updating Existing Images</title> |
1896 | 1896 | ||
1897 | <para> | 1897 | <para> |
1898 | Often, rather than re-flashing a new image, you might wish to install updated | 1898 | Often, rather than re-flashing a new image, you might wish to install updated |
1899 | packages into an existing running system. | 1899 | packages into an existing running system. |
1900 | You can do this by first sharing the <filename>tmp/deploy/ipk/</filename> directory | 1900 | You can do this by first sharing the <filename>tmp/deploy/ipk/</filename> directory |
1901 | through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename> | 1901 | through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename> |
1902 | to point at the shared server. | 1902 | to point at the shared server. |
1903 | Following is an example: | 1903 | Following is an example: |
1904 | <literallayout class='monospaced'> | 1904 | <literallayout class='monospaced'> |
@@ -1929,49 +1929,49 @@ | |||
1929 | 1929 | ||
1930 | <para> | 1930 | <para> |
1931 | If a committed change results in changing the package output, | 1931 | If a committed change results in changing the package output, |
1932 | then the value of the | 1932 | then the value of the |
1933 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> | 1933 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> |
1934 | variable needs to be increased | 1934 | variable needs to be increased |
1935 | (or "bumped") as part of that commit. | 1935 | (or "bumped") as part of that commit. |
1936 | For new recipes you should add the <filename>PR</filename> | 1936 | For new recipes you should add the <filename>PR</filename> |
1937 | variable and set its initial value equal to "r0", which is the default. | 1937 | variable and set its initial value equal to "r0", which is the default. |
1938 | Even though the default value is "r0", the practice of adding it to a new recipe makes | 1938 | Even though the default value is "r0", the practice of adding it to a new recipe makes |
1939 | it harder to forget to bump the variable when you make changes | 1939 | it harder to forget to bump the variable when you make changes |
1940 | to the recipe in future. | 1940 | to the recipe in future. |
1941 | </para> | 1941 | </para> |
1942 | 1942 | ||
1943 | <para> | 1943 | <para> |
1944 | If you are sharing a common <filename>.inc</filename> file with multiple recipes, | 1944 | If you are sharing a common <filename>.inc</filename> file with multiple recipes, |
1945 | you can also use the | 1945 | you can also use the |
1946 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename> | 1946 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename> |
1947 | variable to ensure that | 1947 | variable to ensure that |
1948 | the recipes sharing the <filename>.inc</filename> file are rebuilt when the | 1948 | the recipes sharing the <filename>.inc</filename> file are rebuilt when the |
1949 | <filename>.inc</filename> file itself is changed. | 1949 | <filename>.inc</filename> file itself is changed. |
1950 | The <filename>.inc</filename> file must set <filename>INC_PR</filename> | 1950 | The <filename>.inc</filename> file must set <filename>INC_PR</filename> |
1951 | (initially to "r0"), and all recipes referring to it should set <filename>PR</filename> | 1951 | (initially to "r0"), and all recipes referring to it should set <filename>PR</filename> |
1952 | to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. | 1952 | to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. |
1953 | If the <filename>.inc</filename> file is changed then its | 1953 | If the <filename>.inc</filename> file is changed then its |
1954 | <filename>INC_PR</filename> should be incremented. | 1954 | <filename>INC_PR</filename> should be incremented. |
1955 | </para> | 1955 | </para> |
1956 | 1956 | ||
1957 | <para> | 1957 | <para> |
1958 | When upgrading the version of a package, assuming the | 1958 | When upgrading the version of a package, assuming the |
1959 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename> | 1959 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename> |
1960 | changes, the <filename>PR</filename> variable should be reset to "r0" | 1960 | changes, the <filename>PR</filename> variable should be reset to "r0" |
1961 | (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>). | 1961 | (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>). |
1962 | </para> | 1962 | </para> |
1963 | 1963 | ||
1964 | <para> | 1964 | <para> |
1965 | Usually, version increases occur only to packages. | 1965 | Usually, version increases occur only to packages. |
1966 | However, if for some reason <filename>PV</filename> changes but does not | 1966 | However, if for some reason <filename>PV</filename> changes but does not |
1967 | increase, you can increase the | 1967 | increase, you can increase the |
1968 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename> | 1968 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename> |
1969 | variable (Package Epoch). | 1969 | variable (Package Epoch). |
1970 | The <filename>PE</filename> variable defaults to "0". | 1970 | The <filename>PE</filename> variable defaults to "0". |
1971 | </para> | 1971 | </para> |
1972 | 1972 | ||
1973 | <para> | 1973 | <para> |
1974 | Version numbering strives to follow the | 1974 | Version numbering strives to follow the |
1975 | <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'> | 1975 | <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'> |
1976 | Debian Version Field Policy Guidelines</ulink>. | 1976 | Debian Version Field Policy Guidelines</ulink>. |
1977 | These guidelines define how versions are compared and what "increasing" a version means. | 1977 | These guidelines define how versions are compared and what "increasing" a version means. |
@@ -1982,8 +1982,8 @@ | |||
1982 | First, to ensure that when a developer updates and rebuilds, they get all the changes to | 1982 | First, to ensure that when a developer updates and rebuilds, they get all the changes to |
1983 | the repository and do not have to remember to rebuild any sections. | 1983 | the repository and do not have to remember to rebuild any sections. |
1984 | Second, to ensure that target users are able to upgrade their | 1984 | Second, to ensure that target users are able to upgrade their |
1985 | devices using package manager commands such as <filename>opkg upgrade</filename> | 1985 | devices using package manager commands such as <filename>opkg upgrade</filename> |
1986 | (or similar commands for dpkg/apt or rpm-based systems). | 1986 | (or similar commands for dpkg/apt or rpm-based systems). |
1987 | </para> | 1987 | </para> |
1988 | 1988 | ||
1989 | <para> | 1989 | <para> |
@@ -1998,11 +1998,11 @@ | |||
1998 | package in a different distribution. | 1998 | package in a different distribution. |
1999 | The OpenEmbedded build system implements a <filename>distro_check</filename> | 1999 | The OpenEmbedded build system implements a <filename>distro_check</filename> |
2000 | task that automatically connects to major distributions | 2000 | task that automatically connects to major distributions |
2001 | and checks for these situations. | 2001 | and checks for these situations. |
2002 | If the package exists under a different name in a different distribution, you get a | 2002 | If the package exists under a different name in a different distribution, you get a |
2003 | <filename>distro_check</filename> mismatch. | 2003 | <filename>distro_check</filename> mismatch. |
2004 | You can resolve this problem by defining a per-distro recipe name alias using the | 2004 | You can resolve this problem by defining a per-distro recipe name alias using the |
2005 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename> | 2005 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename> |
2006 | variable. | 2006 | variable. |
2007 | </para> | 2007 | </para> |
2008 | 2008 | ||
@@ -2016,19 +2016,19 @@ | |||
2016 | ..." | 2016 | ..." |
2017 | </literallayout> | 2017 | </literallayout> |
2018 | </para> | 2018 | </para> |
2019 | 2019 | ||
2020 | <para> | 2020 | <para> |
2021 | If you have more than one distribution alias, separate them with a space. | 2021 | If you have more than one distribution alias, separate them with a space. |
2022 | Note that the build system currently automatically checks the | 2022 | Note that the build system currently automatically checks the |
2023 | Fedora, OpenSuSE, Debian, Ubuntu, | 2023 | Fedora, OpenSuSE, Debian, Ubuntu, |
2024 | and Mandriva distributions for source package recipes without having to specify them | 2024 | and Mandriva distributions for source package recipes without having to specify them |
2025 | using the <filename>DISTRO_PN_ALIAS</filename> variable. | 2025 | using the <filename>DISTRO_PN_ALIAS</filename> variable. |
2026 | For example, the following command generates a report that lists the Linux distributions | 2026 | For example, the following command generates a report that lists the Linux distributions |
2027 | that include the sources for each of the recipes. | 2027 | that include the sources for each of the recipes. |
2028 | <literallayout class='monospaced'> | 2028 | <literallayout class='monospaced'> |
2029 | $ bitbake world -f -c distro_check | 2029 | $ bitbake world -f -c distro_check |
2030 | </literallayout> | 2030 | </literallayout> |
2031 | The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> | 2031 | The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> |
2032 | file found in the Source Directory. | 2032 | file found in the Source Directory. |
2033 | </para> | 2033 | </para> |
2034 | </section> | 2034 | </section> |
@@ -2037,12 +2037,12 @@ | |||
2037 | <title>Handling Optional Module Packaging</title> | 2037 | <title>Handling Optional Module Packaging</title> |
2038 | 2038 | ||
2039 | <para> | 2039 | <para> |
2040 | Many pieces of software split functionality into optional | 2040 | Many pieces of software split functionality into optional |
2041 | modules (or plugins) and the plugins that are built | 2041 | modules (or plugins) and the plugins that are built |
2042 | might depend on configuration options. | 2042 | might depend on configuration options. |
2043 | To avoid having to duplicate the logic that determines what | 2043 | To avoid having to duplicate the logic that determines what |
2044 | modules are available in your recipe or to avoid having | 2044 | modules are available in your recipe or to avoid having |
2045 | to package each module by hand, the OpenEmbedded build system | 2045 | to package each module by hand, the OpenEmbedded build system |
2046 | provides functionality to handle module packaging dynamically. | 2046 | provides functionality to handle module packaging dynamically. |
2047 | </para> | 2047 | </para> |
2048 | 2048 | ||
@@ -2051,7 +2051,7 @@ | |||
2051 | <itemizedlist> | 2051 | <itemizedlist> |
2052 | <listitem><para>Ensure the module packaging is actually | 2052 | <listitem><para>Ensure the module packaging is actually |
2053 | done</para></listitem> | 2053 | done</para></listitem> |
2054 | <listitem><para>Ensure that any dependencies on optional | 2054 | <listitem><para>Ensure that any dependencies on optional |
2055 | modules from other recipes are satisfied by your recipe | 2055 | modules from other recipes are satisfied by your recipe |
2056 | </para></listitem> | 2056 | </para></listitem> |
2057 | </itemizedlist> | 2057 | </itemizedlist> |
@@ -2062,48 +2062,48 @@ | |||
2062 | 2062 | ||
2063 | <para> | 2063 | <para> |
2064 | To ensure the module packaging actually gets done, you use | 2064 | To ensure the module packaging actually gets done, you use |
2065 | the <filename>do_split_packages</filename> function within | 2065 | the <filename>do_split_packages</filename> function within |
2066 | the <filename>populate_packages</filename> python function | 2066 | the <filename>populate_packages</filename> python function |
2067 | in your recipe. | 2067 | in your recipe. |
2068 | The <filename>do_split_packages</filename> function | 2068 | The <filename>do_split_packages</filename> function |
2069 | searches for a pattern of files or directories under a | 2069 | searches for a pattern of files or directories under a |
2070 | specified path and creates a package for each one it finds | 2070 | specified path and creates a package for each one it finds |
2071 | by appending to the <filename>PACKAGES</filename> variable | 2071 | by appending to the <filename>PACKAGES</filename> variable |
2072 | and setting the appropriate values for | 2072 | and setting the appropriate values for |
2073 | <filename>FILES_packagename</filename>, | 2073 | <filename>FILES_packagename</filename>, |
2074 | <filename>RDEPENDS_packagename</filename>, | 2074 | <filename>RDEPENDS_packagename</filename>, |
2075 | <filename>DESCRIPTION_packagename</filename>, and so forth. | 2075 | <filename>DESCRIPTION_packagename</filename>, and so forth. |
2076 | Here is an example from the <filename>lighttpd</filename> | 2076 | Here is an example from the <filename>lighttpd</filename> |
2077 | recipe: | 2077 | recipe: |
2078 | <literallayout class='monospaced'> | 2078 | <literallayout class='monospaced'> |
2079 | python populate_packages_prepend () { | 2079 | python populate_packages_prepend () { |
2080 | lighttpd_libdir = d.expand('${libdir}') | 2080 | lighttpd_libdir = d.expand('${libdir}') |
2081 | do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$', | 2081 | do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$', |
2082 | 'lighttpd-module-%s', 'Lighttpd module for %s', | 2082 | 'lighttpd-module-%s', 'Lighttpd module for %s', |
2083 | extra_depends='') | 2083 | extra_depends='') |
2084 | } | 2084 | } |
2085 | </literallayout> | 2085 | </literallayout> |
2086 | The previous example specifies a number of things in the | 2086 | The previous example specifies a number of things in the |
2087 | call to <filename>do_split_packages</filename>. | 2087 | call to <filename>do_split_packages</filename>. |
2088 | <itemizedlist> | 2088 | <itemizedlist> |
2089 | <listitem><para>A directory within the files installed | 2089 | <listitem><para>A directory within the files installed |
2090 | by your recipe through <filename>do_install</filename> | 2090 | by your recipe through <filename>do_install</filename> |
2091 | in which to search.</para></listitem> | 2091 | in which to search.</para></listitem> |
2092 | <listitem><para>A regular expression to match module | 2092 | <listitem><para>A regular expression to match module |
2093 | files in that directory. | 2093 | files in that directory. |
2094 | In the example, note the parentheses () that mark | 2094 | In the example, note the parentheses () that mark |
2095 | the part of the expression from which the module | 2095 | the part of the expression from which the module |
2096 | name should be derived.</para></listitem> | 2096 | name should be derived.</para></listitem> |
2097 | <listitem><para>A pattern to use for the package names. | 2097 | <listitem><para>A pattern to use for the package names. |
2098 | </para></listitem> | 2098 | </para></listitem> |
2099 | <listitem><para>A description for each package. | 2099 | <listitem><para>A description for each package. |
2100 | </para></listitem> | 2100 | </para></listitem> |
2101 | <listitem><para>An empty string for | 2101 | <listitem><para>An empty string for |
2102 | <filename>extra_depends</filename>, which disables | 2102 | <filename>extra_depends</filename>, which disables |
2103 | the default dependency on the main | 2103 | the default dependency on the main |
2104 | <filename>lighttpd</filename> package. | 2104 | <filename>lighttpd</filename> package. |
2105 | Thus, if a file in <filename>${libdir}</filename> | 2105 | Thus, if a file in <filename>${libdir}</filename> |
2106 | called <filename>mod_alias.so</filename> is found, | 2106 | called <filename>mod_alias.so</filename> is found, |
2107 | a package called <filename>lighttpd-module-alias</filename> | 2107 | a package called <filename>lighttpd-module-alias</filename> |
2108 | is created for it and the <filename>DESCRIPTION</filename> | 2108 | is created for it and the <filename>DESCRIPTION</filename> |
2109 | is set to "Lighttpd module for alias".</para></listitem> | 2109 | is set to "Lighttpd module for alias".</para></listitem> |
@@ -2111,109 +2111,109 @@ | |||
2111 | </para> | 2111 | </para> |
2112 | 2112 | ||
2113 | <para> | 2113 | <para> |
2114 | Often, packaging modules is as simple as the previous | 2114 | Often, packaging modules is as simple as the previous |
2115 | example. | 2115 | example. |
2116 | However, more advanced options exist that you can employ | 2116 | However, more advanced options exist that you can employ |
2117 | to <filename>do_split_packages</filename> to modify its | 2117 | to <filename>do_split_packages</filename> to modify its |
2118 | behavior. | 2118 | behavior. |
2119 | And, if you need to, you can add more logic by specifying | 2119 | And, if you need to, you can add more logic by specifying |
2120 | a hook function that is called for each package. | 2120 | a hook function that is called for each package. |
2121 | It is also perfectly acceptable to call | 2121 | It is also perfectly acceptable to call |
2122 | <filename>do_split_packages</filename> multiple times if | 2122 | <filename>do_split_packages</filename> multiple times if |
2123 | you have more than one set of modules to package. | 2123 | you have more than one set of modules to package. |
2124 | </para> | 2124 | </para> |
2125 | 2125 | ||
2126 | <para> | 2126 | <para> |
2127 | For more examples that show how to use | 2127 | For more examples that show how to use |
2128 | <filename>do_split_packages</filename>, see the | 2128 | <filename>do_split_packages</filename>, see the |
2129 | <filename>connman.inc</filename> file in the | 2129 | <filename>connman.inc</filename> file in the |
2130 | <filename>meta/recipes-connectivity/connman/</filename> | 2130 | <filename>meta/recipes-connectivity/connman/</filename> |
2131 | directory of the <filename>poky</filename> source repository. | 2131 | directory of the <filename>poky</filename> source repository. |
2132 | You can also find examples in | 2132 | You can also find examples in |
2133 | <filename>meta/classes/kernel.bbclass</filename>. | 2133 | <filename>meta/classes/kernel.bbclass</filename>. |
2134 | </para> | 2134 | </para> |
2135 | 2135 | ||
2136 | <para> | 2136 | <para> |
2137 | Following is a reference that shows | 2137 | Following is a reference that shows |
2138 | <filename>do_split_packages</filename> mandatory and | 2138 | <filename>do_split_packages</filename> mandatory and |
2139 | optional arguments: | 2139 | optional arguments: |
2140 | <literallayout class='monospaced'> | 2140 | <literallayout class='monospaced'> |
2141 | Mandatory arguments | 2141 | Mandatory arguments |
2142 | 2142 | ||
2143 | root | 2143 | root |
2144 | The path in which to search | 2144 | The path in which to search |
2145 | file_regex | 2145 | file_regex |
2146 | Regular expression to match searched files. | 2146 | Regular expression to match searched files. |
2147 | Use parentheses () to mark the part of this | 2147 | Use parentheses () to mark the part of this |
2148 | expression that should be used to derive the | 2148 | expression that should be used to derive the |
2149 | module name (to be substituted where %s is | 2149 | module name (to be substituted where %s is |
2150 | used in other function arguments as noted below) | 2150 | used in other function arguments as noted below) |
2151 | output_pattern | 2151 | output_pattern |
2152 | Pattern to use for the package names. Must | 2152 | Pattern to use for the package names. Must |
2153 | include %s. | 2153 | include %s. |
2154 | description | 2154 | description |
2155 | Description to set for each package. Must | 2155 | Description to set for each package. Must |
2156 | include %s. | 2156 | include %s. |
2157 | 2157 | ||
2158 | Optional arguments | 2158 | Optional arguments |
2159 | 2159 | ||
2160 | postinst | 2160 | postinst |
2161 | Postinstall script to use for all packages | 2161 | Postinstall script to use for all packages |
2162 | (as a string) | 2162 | (as a string) |
2163 | recursive | 2163 | recursive |
2164 | True to perform a recursive search - default | 2164 | True to perform a recursive search - default |
2165 | False | 2165 | False |
2166 | hook | 2166 | hook |
2167 | A hook function to be called for every match. | 2167 | A hook function to be called for every match. |
2168 | The function will be called with the following | 2168 | The function will be called with the following |
2169 | arguments (in the order listed): | 2169 | arguments (in the order listed): |
2170 | 2170 | ||
2171 | f | 2171 | f |
2172 | Full path to the file/directory match | 2172 | Full path to the file/directory match |
2173 | pkg | 2173 | pkg |
2174 | The package name | 2174 | The package name |
2175 | file_regex | 2175 | file_regex |
2176 | As above | 2176 | As above |
2177 | output_pattern | 2177 | output_pattern |
2178 | As above | 2178 | As above |
2179 | modulename | 2179 | modulename |
2180 | The module name derived using file_regex | 2180 | The module name derived using file_regex |
2181 | 2181 | ||
2182 | extra_depends | 2182 | extra_depends |
2183 | Extra runtime dependencies (RDEPENDS) to be | 2183 | Extra runtime dependencies (RDEPENDS) to be |
2184 | set for all packages. The default value of None | 2184 | set for all packages. The default value of None |
2185 | causes a dependency on the main package | 2185 | causes a dependency on the main package |
2186 | (${PN}) - if you do not want this, pass empty | 2186 | (${PN}) - if you do not want this, pass empty |
2187 | string '' for this parameter. | 2187 | string '' for this parameter. |
2188 | aux_files_pattern | 2188 | aux_files_pattern |
2189 | Extra item(s) to be added to FILES for each | 2189 | Extra item(s) to be added to FILES for each |
2190 | package. Can be a single string item or a list | 2190 | package. Can be a single string item or a list |
2191 | of strings for multiple items. Must include %s. | 2191 | of strings for multiple items. Must include %s. |
2192 | postrm | 2192 | postrm |
2193 | postrm script to use for all packages (as a | 2193 | postrm script to use for all packages (as a |
2194 | string) | 2194 | string) |
2195 | allow_dirs | 2195 | allow_dirs |
2196 | True to allow directories to be matched - | 2196 | True to allow directories to be matched - |
2197 | default False | 2197 | default False |
2198 | prepend | 2198 | prepend |
2199 | If True, prepend created packages to PACKAGES | 2199 | If True, prepend created packages to PACKAGES |
2200 | instead of the default False which appends them | 2200 | instead of the default False which appends them |
2201 | match_path | 2201 | match_path |
2202 | match file_regex on the whole relative path to | 2202 | match file_regex on the whole relative path to |
2203 | the root rather than just the file name | 2203 | the root rather than just the file name |
2204 | aux_files_pattern_verbatim | 2204 | aux_files_pattern_verbatim |
2205 | Extra item(s) to be added to FILES for each | 2205 | Extra item(s) to be added to FILES for each |
2206 | package, using the actual derived module name | 2206 | package, using the actual derived module name |
2207 | rather than converting it to something legal | 2207 | rather than converting it to something legal |
2208 | for a package name. Can be a single string item | 2208 | for a package name. Can be a single string item |
2209 | or a list of strings for multiple items. Must | 2209 | or a list of strings for multiple items. Must |
2210 | include %s. | 2210 | include %s. |
2211 | allow_links | 2211 | allow_links |
2212 | True to allow symlinks to be matched - default | 2212 | True to allow symlinks to be matched - default |
2213 | False | 2213 | False |
2214 | </literallayout> | 2214 | </literallayout> |
2215 | </para> | 2215 | </para> |
2216 | </section> | 2216 | </section> |
2217 | 2217 | ||
2218 | <section id='satisfying-dependencies'> | 2218 | <section id='satisfying-dependencies'> |
2219 | <title>Satisfying Dependencies</title> | 2219 | <title>Satisfying Dependencies</title> |
@@ -2221,27 +2221,27 @@ | |||
2221 | <para> | 2221 | <para> |
2222 | The second part for handling optional module packaging | 2222 | The second part for handling optional module packaging |
2223 | is to ensure that any dependencies on optional modules | 2223 | is to ensure that any dependencies on optional modules |
2224 | from other recipes are satisfied by your recipe. | 2224 | from other recipes are satisfied by your recipe. |
2225 | You can be sure these dependencies are satisfied by | 2225 | You can be sure these dependencies are satisfied by |
2226 | using the | 2226 | using the |
2227 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable. | 2227 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable. |
2228 | Here is an example that continues with the | 2228 | Here is an example that continues with the |
2229 | <filename>lighttpd</filename> recipe shown earlier: | 2229 | <filename>lighttpd</filename> recipe shown earlier: |
2230 | <literallayout class='monospaced'> | 2230 | <literallayout class='monospaced'> |
2231 | PACKAGES_DYNAMIC = "lighttpd-module-.*" | 2231 | PACKAGES_DYNAMIC = "lighttpd-module-.*" |
2232 | </literallayout> | 2232 | </literallayout> |
2233 | The name specified in the regular expression can of | 2233 | The name specified in the regular expression can of |
2234 | course be anything. | 2234 | course be anything. |
2235 | In this example, it is <filename>lighttpd-module-</filename> | 2235 | In this example, it is <filename>lighttpd-module-</filename> |
2236 | and is specified as the prefix to ensure that any | 2236 | and is specified as the prefix to ensure that any |
2237 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> | 2237 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> |
2238 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> | 2238 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> |
2239 | on a package name starting with the prefix are satisfied | 2239 | on a package name starting with the prefix are satisfied |
2240 | during build time. | 2240 | during build time. |
2241 | If you are using <filename>do_split_packages</filename> | 2241 | If you are using <filename>do_split_packages</filename> |
2242 | as described in the previous section, the value you put in | 2242 | as described in the previous section, the value you put in |
2243 | <filename>PACKAGES_DYNAMIC</filename> should correspond to | 2243 | <filename>PACKAGES_DYNAMIC</filename> should correspond to |
2244 | the name pattern specified in the call to | 2244 | the name pattern specified in the call to |
2245 | <filename>do_split_packages</filename>. | 2245 | <filename>do_split_packages</filename>. |
2246 | </para> | 2246 | </para> |
2247 | </section> | 2247 | </section> |
@@ -2252,32 +2252,32 @@ | |||
2252 | <title>Building Software from an External Source</title> | 2252 | <title>Building Software from an External Source</title> |
2253 | 2253 | ||
2254 | <para> | 2254 | <para> |
2255 | By default, the OpenEmbedded build system does its work from within the | 2255 | By default, the OpenEmbedded build system does its work from within the |
2256 | <link linkend='build-directory'>Build Directory</link>. | 2256 | <link linkend='build-directory'>Build Directory</link>. |
2257 | The build process involves fetching the source files, unpacking them, and then patching them | 2257 | The build process involves fetching the source files, unpacking them, and then patching them |
2258 | if necessary before the build takes place. | 2258 | if necessary before the build takes place. |
2259 | </para> | 2259 | </para> |
2260 | 2260 | ||
2261 | <para> | 2261 | <para> |
2262 | Situations exist where you might want to build software from source files that are external to | 2262 | Situations exist where you might want to build software from source files that are external to |
2263 | and thus outside of the <link linkend='source-directory'>Source Directory</link>. | 2263 | and thus outside of the <link linkend='source-directory'>Source Directory</link>. |
2264 | For example, suppose you have a project that includes a new BSP with a heavily customized | 2264 | For example, suppose you have a project that includes a new BSP with a heavily customized |
2265 | kernel, a very minimal image, and some new user-space recipes. | 2265 | kernel, a very minimal image, and some new user-space recipes. |
2266 | And, you want to minimize exposing the build system to the | 2266 | And, you want to minimize exposing the build system to the |
2267 | development team so that they can focus on their project and maintain everyone's workflow | 2267 | development team so that they can focus on their project and maintain everyone's workflow |
2268 | as much as possible. | 2268 | as much as possible. |
2269 | In this case, you want a kernel source directory on the development machine where the | 2269 | In this case, you want a kernel source directory on the development machine where the |
2270 | development occurs. | 2270 | development occurs. |
2271 | You want the recipe's | 2271 | You want the recipe's |
2272 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | 2272 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
2273 | variable to point to the external directory and use it as is, not copy it. | 2273 | variable to point to the external directory and use it as is, not copy it. |
2274 | </para> | 2274 | </para> |
2275 | 2275 | ||
2276 | <para> | 2276 | <para> |
2277 | To build from software that comes from an external source, all you need to do is | 2277 | To build from software that comes from an external source, all you need to do is |
2278 | change your recipe so that it inherits the | 2278 | change your recipe so that it inherits the |
2279 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink> | 2279 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink> |
2280 | class and then sets the | 2280 | class and then sets the |
2281 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> | 2281 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> |
2282 | variable to point to your external source code. | 2282 | variable to point to your external source code. |
2283 | Here are the statements to put in your recipe: | 2283 | Here are the statements to put in your recipe: |
@@ -2288,17 +2288,17 @@ | |||
2288 | </para> | 2288 | </para> |
2289 | 2289 | ||
2290 | <para> | 2290 | <para> |
2291 | It is important to know that the <filename>externalsrc.bbclass</filename> assumes that the | 2291 | It is important to know that the <filename>externalsrc.bbclass</filename> assumes that the |
2292 | source directory <filename>S</filename> and the Build Directory | 2292 | source directory <filename>S</filename> and the Build Directory |
2293 | <ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink> | 2293 | <ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink> |
2294 | are different even though by default these directories are the same. | 2294 | are different even though by default these directories are the same. |
2295 | This assumption is important because it supports building different variants of the recipe | 2295 | This assumption is important because it supports building different variants of the recipe |
2296 | by using the | 2296 | by using the |
2297 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink> | 2297 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink> |
2298 | variable. | 2298 | variable. |
2299 | You could allow the Build Directory to be the same as the source directory but you would | 2299 | You could allow the Build Directory to be the same as the source directory but you would |
2300 | not be able to build more than one variant of the recipe. | 2300 | not be able to build more than one variant of the recipe. |
2301 | Consequently, if you are building multiple variants of the recipe, you need to establish a | 2301 | Consequently, if you are building multiple variants of the recipe, you need to establish a |
2302 | Build Directory that is different than the source directory. | 2302 | Build Directory that is different than the source directory. |
2303 | </para> | 2303 | </para> |
2304 | </section> | 2304 | </section> |
@@ -2307,19 +2307,19 @@ | |||
2307 | <title>Excluding Recipes From the Build</title> | 2307 | <title>Excluding Recipes From the Build</title> |
2308 | 2308 | ||
2309 | <para> | 2309 | <para> |
2310 | You might find that there are groups of recipes you want to filter | 2310 | You might find that there are groups of recipes you want to filter |
2311 | out of the build process. | 2311 | out of the build process. |
2312 | For example, recipes you know you will never use or want should not | 2312 | For example, recipes you know you will never use or want should not |
2313 | be part of the build. | 2313 | be part of the build. |
2314 | Removing these recipes from parsing speeds up parts of the build. | 2314 | Removing these recipes from parsing speeds up parts of the build. |
2315 | </para> | 2315 | </para> |
2316 | 2316 | ||
2317 | <para> | 2317 | <para> |
2318 | It is possible to filter or mask out <filename>.bb</filename> and | 2318 | It is possible to filter or mask out <filename>.bb</filename> and |
2319 | <filename>.bbappend</filename> files. | 2319 | <filename>.bbappend</filename> files. |
2320 | You can do this by providing an expression with the | 2320 | You can do this by providing an expression with the |
2321 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'>BBMASK</ulink></filename> | 2321 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'>BBMASK</ulink></filename> |
2322 | variable. | 2322 | variable. |
2323 | Here is an example: | 2323 | Here is an example: |
2324 | <literallayout class='monospaced'> | 2324 | <literallayout class='monospaced'> |
2325 | BBMASK = ".*/meta-mymachine/recipes-maybe/" | 2325 | BBMASK = ".*/meta-mymachine/recipes-maybe/" |
@@ -2334,23 +2334,23 @@ | |||
2334 | <title>Using an External SCM</title> | 2334 | <title>Using an External SCM</title> |
2335 | 2335 | ||
2336 | <para> | 2336 | <para> |
2337 | If you're working on a recipe that pulls from an external Source Code Manager (SCM), it | 2337 | If you're working on a recipe that pulls from an external Source Code Manager (SCM), it |
2338 | is possible to have the OpenEmbedded build system notice new recipe changes added to the | 2338 | is possible to have the OpenEmbedded build system notice new recipe changes added to the |
2339 | SCM and then build the resulting package that depends on the new recipes by using the latest | 2339 | SCM and then build the resulting package that depends on the new recipes by using the latest |
2340 | versions. | 2340 | versions. |
2341 | This only works for SCMs from which it is possible to get a sensible revision number for changes. | 2341 | This only works for SCMs from which it is possible to get a sensible revision number for changes. |
2342 | Currently, you can do this with Apache Subversion (SVN), Git, and Bazaar (BZR) repositories. | 2342 | Currently, you can do this with Apache Subversion (SVN), Git, and Bazaar (BZR) repositories. |
2343 | </para> | 2343 | </para> |
2344 | 2344 | ||
2345 | <para> | 2345 | <para> |
2346 | To enable this behavior, simply add the following to the <filename>local.conf</filename> | 2346 | To enable this behavior, simply add the following to the <filename>local.conf</filename> |
2347 | configuration file found in the | 2347 | configuration file found in the |
2348 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | 2348 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: |
2349 | <literallayout class='monospaced'> | 2349 | <literallayout class='monospaced'> |
2350 | SRCREV_pn-<PN> = "${AUTOREV}" | 2350 | SRCREV_pn-<PN> = "${AUTOREV}" |
2351 | </literallayout> | 2351 | </literallayout> |
2352 | where <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> | 2352 | where <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> |
2353 | is the name of the recipe for which you want to enable automatic source | 2353 | is the name of the recipe for which you want to enable automatic source |
2354 | revision updating. | 2354 | revision updating. |
2355 | </para> | 2355 | </para> |
2356 | </section> | 2356 | </section> |
@@ -2359,64 +2359,64 @@ | |||
2359 | <title>Debugging With the GNU Project Debugger (GDB) Remotely</title> | 2359 | <title>Debugging With the GNU Project Debugger (GDB) Remotely</title> |
2360 | 2360 | ||
2361 | <para> | 2361 | <para> |
2362 | GDB allows you to examine running programs, which in turn helps you to understand and fix problems. | 2362 | GDB allows you to examine running programs, which in turn helps you to understand and fix problems. |
2363 | It also allows you to perform post-mortem style analysis of program crashes. | 2363 | It also allows you to perform post-mortem style analysis of program crashes. |
2364 | GDB is available as a package within the Yocto Project and by default is | 2364 | GDB is available as a package within the Yocto Project and by default is |
2365 | installed in SDK images. | 2365 | installed in SDK images. |
2366 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter | 2366 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter |
2367 | in the Yocto Project Reference Manual for a description of these images. | 2367 | in the Yocto Project Reference Manual for a description of these images. |
2368 | You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>. | 2368 | You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>. |
2369 | </para> | 2369 | </para> |
2370 | 2370 | ||
2371 | <tip> | 2371 | <tip> |
2372 | For best results, install <filename>-dbg</filename> packages for the applications | 2372 | For best results, install <filename>-dbg</filename> packages for the applications |
2373 | you are going to debug. | 2373 | you are going to debug. |
2374 | Doing so makes available extra debug symbols that give you more meaningful output. | 2374 | Doing so makes available extra debug symbols that give you more meaningful output. |
2375 | </tip> | 2375 | </tip> |
2376 | 2376 | ||
2377 | <para> | 2377 | <para> |
2378 | Sometimes, due to memory or disk space constraints, it is not possible | 2378 | Sometimes, due to memory or disk space constraints, it is not possible |
2379 | to use GDB directly on the remote target to debug applications. | 2379 | to use GDB directly on the remote target to debug applications. |
2380 | These constraints arise because GDB needs to load the debugging information and the | 2380 | These constraints arise because GDB needs to load the debugging information and the |
2381 | binaries of the process being debugged. | 2381 | binaries of the process being debugged. |
2382 | Additionally, GDB needs to perform many computations to locate information such as function | 2382 | Additionally, GDB needs to perform many computations to locate information such as function |
2383 | names, variable names and values, stack traces and so forth - even before starting the | 2383 | names, variable names and values, stack traces and so forth - even before starting the |
2384 | debugging process. | 2384 | debugging process. |
2385 | These extra computations place more load on the target system and can alter the | 2385 | These extra computations place more load on the target system and can alter the |
2386 | characteristics of the program being debugged. | 2386 | characteristics of the program being debugged. |
2387 | </para> | 2387 | </para> |
2388 | 2388 | ||
2389 | <para> | 2389 | <para> |
2390 | To help get past the previously mentioned constraints, you can use Gdbserver. | 2390 | To help get past the previously mentioned constraints, you can use Gdbserver. |
2391 | Gdbserver runs on the remote target and does not load any debugging information | 2391 | Gdbserver runs on the remote target and does not load any debugging information |
2392 | from the debugged process. | 2392 | from the debugged process. |
2393 | Instead, a GDB instance processes the debugging information that is run on a | 2393 | Instead, a GDB instance processes the debugging information that is run on a |
2394 | remote computer - the host GDB. | 2394 | remote computer - the host GDB. |
2395 | The host GDB then sends control commands to Gdbserver to make it stop or start the debugged | 2395 | The host GDB then sends control commands to Gdbserver to make it stop or start the debugged |
2396 | program, as well as read or write memory regions of that debugged program. | 2396 | program, as well as read or write memory regions of that debugged program. |
2397 | All the debugging information loaded and processed as well | 2397 | All the debugging information loaded and processed as well |
2398 | as all the heavy debugging is done by the host GDB. | 2398 | as all the heavy debugging is done by the host GDB. |
2399 | Offloading these processes gives the Gdbserver running on the target a chance to remain | 2399 | Offloading these processes gives the Gdbserver running on the target a chance to remain |
2400 | small and fast. | 2400 | small and fast. |
2401 | </para> | 2401 | </para> |
2402 | 2402 | ||
2403 | <para> | 2403 | <para> |
2404 | Because the host GDB is responsible for loading the debugging information and | 2404 | Because the host GDB is responsible for loading the debugging information and |
2405 | for doing the necessary processing to make actual debugging happen, the | 2405 | for doing the necessary processing to make actual debugging happen, the |
2406 | user has to make sure the host can access the unstripped binaries complete | 2406 | user has to make sure the host can access the unstripped binaries complete |
2407 | with their debugging information and also be sure the target is compiled with no optimizations. | 2407 | with their debugging information and also be sure the target is compiled with no optimizations. |
2408 | The host GDB must also have local access to all the libraries used by the | 2408 | The host GDB must also have local access to all the libraries used by the |
2409 | debugged program. | 2409 | debugged program. |
2410 | Because Gdbserver does not need any local debugging information, the binaries on | 2410 | Because Gdbserver does not need any local debugging information, the binaries on |
2411 | the remote target can remain stripped. | 2411 | the remote target can remain stripped. |
2412 | However, the binaries must also be compiled without optimization | 2412 | However, the binaries must also be compiled without optimization |
2413 | so they match the host's binaries. | 2413 | so they match the host's binaries. |
2414 | </para> | 2414 | </para> |
2415 | 2415 | ||
2416 | <para> | 2416 | <para> |
2417 | To remain consistent with GDB documentation and terminology, the binary being debugged | 2417 | To remain consistent with GDB documentation and terminology, the binary being debugged |
2418 | on the remote target machine is referred to as the "inferior" binary. | 2418 | on the remote target machine is referred to as the "inferior" binary. |
2419 | For documentation on GDB see the | 2419 | For documentation on GDB see the |
2420 | <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>. | 2420 | <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>. |
2421 | </para> | 2421 | </para> |
2422 | 2422 | ||
@@ -2424,13 +2424,13 @@ | |||
2424 | <title>Launching Gdbserver on the Target</title> | 2424 | <title>Launching Gdbserver on the Target</title> |
2425 | 2425 | ||
2426 | <para> | 2426 | <para> |
2427 | First, make sure Gdbserver is installed on the target. | 2427 | First, make sure Gdbserver is installed on the target. |
2428 | If it is not, install the package <filename>gdbserver</filename>, which needs the | 2428 | If it is not, install the package <filename>gdbserver</filename>, which needs the |
2429 | <filename>libthread-db1</filename> package. | 2429 | <filename>libthread-db1</filename> package. |
2430 | </para> | 2430 | </para> |
2431 | 2431 | ||
2432 | <para> | 2432 | <para> |
2433 | As an example, to launch Gdbserver on the target and make it ready to "debug" a | 2433 | As an example, to launch Gdbserver on the target and make it ready to "debug" a |
2434 | program located at <filename>/path/to/inferior</filename>, connect | 2434 | program located at <filename>/path/to/inferior</filename>, connect |
2435 | to the target and launch: | 2435 | to the target and launch: |
2436 | <literallayout class='monospaced'> | 2436 | <literallayout class='monospaced'> |
@@ -2438,8 +2438,8 @@ | |||
2438 | </literallayout> | 2438 | </literallayout> |
2439 | Gdbserver should now be listening on port 2345 for debugging | 2439 | Gdbserver should now be listening on port 2345 for debugging |
2440 | commands coming from a remote GDB process that is running on the host computer. | 2440 | commands coming from a remote GDB process that is running on the host computer. |
2441 | Communication between Gdbserver and the host GDB are done using TCP. | 2441 | Communication between Gdbserver and the host GDB are done using TCP. |
2442 | To use other communication protocols, please refer to the | 2442 | To use other communication protocols, please refer to the |
2443 | <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>. | 2443 | <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>. |
2444 | </para> | 2444 | </para> |
2445 | </section> | 2445 | </section> |
@@ -2456,25 +2456,25 @@ | |||
2456 | <title>Building the Cross-GDB Package</title> | 2456 | <title>Building the Cross-GDB Package</title> |
2457 | <para> | 2457 | <para> |
2458 | A suitable GDB cross-binary is required that runs on your host computer but | 2458 | A suitable GDB cross-binary is required that runs on your host computer but |
2459 | also knows about the the ABI of the remote target. | 2459 | also knows about the the ABI of the remote target. |
2460 | You can get this binary from the meta-toolchain. | 2460 | You can get this binary from the meta-toolchain. |
2461 | Here is an example: | 2461 | Here is an example: |
2462 | <literallayout class='monospaced'> | 2462 | <literallayout class='monospaced'> |
2463 | /usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb | 2463 | /usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb |
2464 | </literallayout> | 2464 | </literallayout> |
2465 | where <filename>arm</filename> is the target architecture and | 2465 | where <filename>arm</filename> is the target architecture and |
2466 | <filename>linux-gnueabi</filename> the target ABI. | 2466 | <filename>linux-gnueabi</filename> the target ABI. |
2467 | </para> | 2467 | </para> |
2468 | 2468 | ||
2469 | <para> | 2469 | <para> |
2470 | Alternatively, you can use BitBake to build the <filename>gdb-cross</filename> binary. | 2470 | Alternatively, you can use BitBake to build the <filename>gdb-cross</filename> binary. |
2471 | Here is an example: | 2471 | Here is an example: |
2472 | <literallayout class='monospaced'> | 2472 | <literallayout class='monospaced'> |
2473 | $ bitbake gdb-cross | 2473 | $ bitbake gdb-cross |
2474 | </literallayout> | 2474 | </literallayout> |
2475 | Once the binary is built, you can find it here: | 2475 | Once the binary is built, you can find it here: |
2476 | <literallayout class='monospaced'> | 2476 | <literallayout class='monospaced'> |
2477 | tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb | 2477 | tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb |
2478 | </literallayout> | 2478 | </literallayout> |
2479 | </para> | 2479 | </para> |
2480 | </section> | 2480 | </section> |
@@ -2491,24 +2491,24 @@ | |||
2491 | 2491 | ||
2492 | <para> | 2492 | <para> |
2493 | Perhaps the easiest way is to have an SDK image that corresponds to the plain | 2493 | Perhaps the easiest way is to have an SDK image that corresponds to the plain |
2494 | image installed on the device. | 2494 | image installed on the device. |
2495 | In the case of <filename>core-image-sato</filename>, | 2495 | In the case of <filename>core-image-sato</filename>, |
2496 | <filename>core-image-sato-sdk</filename> would contain suitable symbols. | 2496 | <filename>core-image-sato-sdk</filename> would contain suitable symbols. |
2497 | Because the SDK images already have the debugging symbols installed, it is just a | 2497 | Because the SDK images already have the debugging symbols installed, it is just a |
2498 | question of expanding the archive to some location and then informing GDB. | 2498 | question of expanding the archive to some location and then informing GDB. |
2499 | </para> | 2499 | </para> |
2500 | 2500 | ||
2501 | <para> | 2501 | <para> |
2502 | Alternatively, the OpenEmbedded build system can build a custom directory of files | 2502 | Alternatively, the OpenEmbedded build system can build a custom directory of files |
2503 | for a specific | 2503 | for a specific |
2504 | debugging purpose by reusing its <filename>tmp/rootfs</filename> directory. | 2504 | debugging purpose by reusing its <filename>tmp/rootfs</filename> directory. |
2505 | This directory contains the contents of the last built image. | 2505 | This directory contains the contents of the last built image. |
2506 | This process assumes two things: | 2506 | This process assumes two things: |
2507 | <itemizedlist> | 2507 | <itemizedlist> |
2508 | <listitem><para>The image running on the target was the last image to | 2508 | <listitem><para>The image running on the target was the last image to |
2509 | be built.</para></listitem> | 2509 | be built.</para></listitem> |
2510 | <listitem><para>The package (<filename>foo</filename> in the following | 2510 | <listitem><para>The package (<filename>foo</filename> in the following |
2511 | example) that contains the inferior binary to be debugged has been built | 2511 | example) that contains the inferior binary to be debugged has been built |
2512 | without optimization and has debugging information available.</para></listitem> | 2512 | without optimization and has debugging information available.</para></listitem> |
2513 | </itemizedlist> | 2513 | </itemizedlist> |
2514 | </para> | 2514 | </para> |
@@ -2516,7 +2516,7 @@ | |||
2516 | <para> | 2516 | <para> |
2517 | The following steps show how to build the custom directory of files: | 2517 | The following steps show how to build the custom directory of files: |
2518 | <orderedlist> | 2518 | <orderedlist> |
2519 | <listitem><para>Install the package (<filename>foo</filename> in this case) to | 2519 | <listitem><para>Install the package (<filename>foo</filename> in this case) to |
2520 | <filename>tmp/rootfs</filename>: | 2520 | <filename>tmp/rootfs</filename>: |
2521 | <literallayout class='monospaced'> | 2521 | <literallayout class='monospaced'> |
2522 | $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ | 2522 | $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ |
@@ -2541,10 +2541,10 @@ | |||
2541 | <title>Launch the Host GDB</title> | 2541 | <title>Launch the Host GDB</title> |
2542 | 2542 | ||
2543 | <para> | 2543 | <para> |
2544 | To launch the host GDB, you run the <filename>cross-gdb</filename> binary and provide | 2544 | To launch the host GDB, you run the <filename>cross-gdb</filename> binary and provide |
2545 | the inferior binary as part of the command line. | 2545 | the inferior binary as part of the command line. |
2546 | For example, the following command form continues with the example used in | 2546 | For example, the following command form continues with the example used in |
2547 | the previous section. | 2547 | the previous section. |
2548 | This command form loads the <filename>foo</filename> binary | 2548 | This command form loads the <filename>foo</filename> binary |
2549 | as well as the debugging information: | 2549 | as well as the debugging information: |
2550 | <literallayout class='monospaced'> | 2550 | <literallayout class='monospaced'> |
@@ -2556,18 +2556,18 @@ | |||
2556 | $ set solib-absolute-prefix /path/to/tmp/rootfs | 2556 | $ set solib-absolute-prefix /path/to/tmp/rootfs |
2557 | </literallayout> | 2557 | </literallayout> |
2558 | The pathname <filename>/path/to/tmp/rootfs</filename> must either be | 2558 | The pathname <filename>/path/to/tmp/rootfs</filename> must either be |
2559 | the absolute path to <filename>tmp/rootfs</filename> or the location at which | 2559 | the absolute path to <filename>tmp/rootfs</filename> or the location at which |
2560 | binaries with debugging information reside. | 2560 | binaries with debugging information reside. |
2561 | </para> | 2561 | </para> |
2562 | 2562 | ||
2563 | <para> | 2563 | <para> |
2564 | At this point you can have GDB connect to the Gdbserver that is running | 2564 | At this point you can have GDB connect to the Gdbserver that is running |
2565 | on the remote target by using the following command form: | 2565 | on the remote target by using the following command form: |
2566 | <literallayout class='monospaced'> | 2566 | <literallayout class='monospaced'> |
2567 | $ target remote remote-target-ip-address:2345 | 2567 | $ target remote remote-target-ip-address:2345 |
2568 | </literallayout> | 2568 | </literallayout> |
2569 | The <filename>remote-target-ip-address</filename> is the IP address of the | 2569 | The <filename>remote-target-ip-address</filename> is the IP address of the |
2570 | remote target where the Gdbserver is running. | 2570 | remote target where the Gdbserver is running. |
2571 | Port 2345 is the port on which the GDBSERVER is running. | 2571 | Port 2345 is the port on which the GDBSERVER is running. |
2572 | </para> | 2572 | </para> |
2573 | </section> | 2573 | </section> |
@@ -2578,7 +2578,7 @@ | |||
2578 | <para> | 2578 | <para> |
2579 | You can now proceed with debugging as normal - as if you were debugging | 2579 | You can now proceed with debugging as normal - as if you were debugging |
2580 | on the local machine. | 2580 | on the local machine. |
2581 | For example, to instruct GDB to break in the "main" function and then | 2581 | For example, to instruct GDB to break in the "main" function and then |
2582 | continue with execution of the inferior binary use the following commands | 2582 | continue with execution of the inferior binary use the following commands |
2583 | from within GDB: | 2583 | from within GDB: |
2584 | <literallayout class='monospaced'> | 2584 | <literallayout class='monospaced'> |
@@ -2588,7 +2588,7 @@ | |||
2588 | </para> | 2588 | </para> |
2589 | 2589 | ||
2590 | <para> | 2590 | <para> |
2591 | For more information about using GDB, see the project's online documentation at | 2591 | For more information about using GDB, see the project's online documentation at |
2592 | <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>. | 2592 | <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>. |
2593 | </para> | 2593 | </para> |
2594 | </section> | 2594 | </section> |
@@ -2599,41 +2599,41 @@ | |||
2599 | <title>Profiling with OProfile</title> | 2599 | <title>Profiling with OProfile</title> |
2600 | 2600 | ||
2601 | <para> | 2601 | <para> |
2602 | <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a | 2602 | <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a |
2603 | statistical profiler well suited for finding performance | 2603 | statistical profiler well suited for finding performance |
2604 | bottlenecks in both userspace software and in the kernel. | 2604 | bottlenecks in both userspace software and in the kernel. |
2605 | This profiler provides answers to questions like "Which functions does my application spend | 2605 | This profiler provides answers to questions like "Which functions does my application spend |
2606 | the most time in when doing X?" | 2606 | the most time in when doing X?" |
2607 | Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling | 2607 | Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling |
2608 | applications on target hardware straightforward. | 2608 | applications on target hardware straightforward. |
2609 | </para> | 2609 | </para> |
2610 | 2610 | ||
2611 | <para> | 2611 | <para> |
2612 | To use OProfile, you need an image that has OProfile installed. | 2612 | To use OProfile, you need an image that has OProfile installed. |
2613 | The easiest way to do this is with <filename>tools-profile</filename> in the | 2613 | The easiest way to do this is with <filename>tools-profile</filename> in the |
2614 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable. | 2614 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable. |
2615 | You also need debugging symbols to be available on the system where the analysis | 2615 | You also need debugging symbols to be available on the system where the analysis |
2616 | takes place. | 2616 | takes place. |
2617 | You can gain access to the symbols by using <filename>dbg-pkgs</filename> in the | 2617 | You can gain access to the symbols by using <filename>dbg-pkgs</filename> in the |
2618 | <filename>IMAGE_FEATURES</filename> variable or by | 2618 | <filename>IMAGE_FEATURES</filename> variable or by |
2619 | installing the appropriate <filename>-dbg</filename> packages. | 2619 | installing the appropriate <filename>-dbg</filename> packages. |
2620 | </para> | 2620 | </para> |
2621 | 2621 | ||
2622 | <para> | 2622 | <para> |
2623 | For successful call graph analysis, the binaries must preserve the frame | 2623 | For successful call graph analysis, the binaries must preserve the frame |
2624 | pointer register and should also be compiled with the | 2624 | pointer register and should also be compiled with the |
2625 | <filename>-fno-omit-framepointer</filename> flag. | 2625 | <filename>-fno-omit-framepointer</filename> flag. |
2626 | You can achieve this by setting the | 2626 | You can achieve this by setting the |
2627 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename> | 2627 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename> |
2628 | variable with the following options: | 2628 | variable with the following options: |
2629 | <literallayout class='monospaced'> | 2629 | <literallayout class='monospaced'> |
2630 | -fexpensive-optimizations | 2630 | -fexpensive-optimizations |
2631 | -fno-omit-framepointer | 2631 | -fno-omit-framepointer |
2632 | -frename-registers | 2632 | -frename-registers |
2633 | -O2 | 2633 | -O2 |
2634 | </literallayout> | 2634 | </literallayout> |
2635 | You can also achieve it by setting the | 2635 | You can also achieve it by setting the |
2636 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename> | 2636 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename> |
2637 | variable to "1" in the <filename>local.conf</filename> configuration file. | 2637 | variable to "1" in the <filename>local.conf</filename> configuration file. |
2638 | If you use the <filename>DEBUG_BUILD</filename> variable, | 2638 | If you use the <filename>DEBUG_BUILD</filename> variable, |
2639 | you will also add extra debug information that can make the debug packages large. | 2639 | you will also add extra debug information that can make the debug packages large. |
@@ -2643,7 +2643,7 @@ | |||
2643 | <title>Profiling on the Target</title> | 2643 | <title>Profiling on the Target</title> |
2644 | 2644 | ||
2645 | <para> | 2645 | <para> |
2646 | Using OProfile you can perform all the profiling work on the target device. | 2646 | Using OProfile you can perform all the profiling work on the target device. |
2647 | A simple OProfile session might look like the following: | 2647 | A simple OProfile session might look like the following: |
2648 | </para> | 2648 | </para> |
2649 | 2649 | ||
@@ -2664,19 +2664,19 @@ | |||
2664 | <para> | 2664 | <para> |
2665 | In this example, the <filename>reset</filename> command clears any previously profiled data. | 2665 | In this example, the <filename>reset</filename> command clears any previously profiled data. |
2666 | The next command starts OProfile. | 2666 | The next command starts OProfile. |
2667 | The options used when starting the profiler separate dynamic library data | 2667 | The options used when starting the profiler separate dynamic library data |
2668 | within applications, disable kernel profiling, and enable callgraphing up to | 2668 | within applications, disable kernel profiling, and enable callgraphing up to |
2669 | five levels deep. | 2669 | five levels deep. |
2670 | <note> | 2670 | <note> |
2671 | To profile the kernel, you would specify the | 2671 | To profile the kernel, you would specify the |
2672 | <filename>--vmlinux=/path/to/vmlinux</filename> option. | 2672 | <filename>--vmlinux=/path/to/vmlinux</filename> option. |
2673 | The <filename>vmlinux</filename> file is usually in the source directory in the | 2673 | The <filename>vmlinux</filename> file is usually in the source directory in the |
2674 | <filename>/boot/</filename> directory and must match the running kernel. | 2674 | <filename>/boot/</filename> directory and must match the running kernel. |
2675 | </note> | 2675 | </note> |
2676 | </para> | 2676 | </para> |
2677 | 2677 | ||
2678 | <para> | 2678 | <para> |
2679 | After you perform your profiling tasks, the next command stops the profiler. | 2679 | After you perform your profiling tasks, the next command stops the profiler. |
2680 | After that, you can view results with the <filename>opreport</filename> command with options | 2680 | After that, you can view results with the <filename>opreport</filename> command with options |
2681 | to see the separate library symbols and callgraph information. | 2681 | to see the separate library symbols and callgraph information. |
2682 | </para> | 2682 | </para> |
@@ -2684,19 +2684,19 @@ | |||
2684 | <para> | 2684 | <para> |
2685 | Callgraphing logs information about time spent in functions and about a function's | 2685 | Callgraphing logs information about time spent in functions and about a function's |
2686 | calling function (parent) and called functions (children). | 2686 | calling function (parent) and called functions (children). |
2687 | The higher the callgraphing depth, the more accurate the results. | 2687 | The higher the callgraphing depth, the more accurate the results. |
2688 | However, higher depths also increase the logging overhead. | 2688 | However, higher depths also increase the logging overhead. |
2689 | Consequently, you should take care when setting the callgraphing depth. | 2689 | Consequently, you should take care when setting the callgraphing depth. |
2690 | <note> | 2690 | <note> |
2691 | On ARM, binaries need to have the frame pointer enabled for callgraphing to work. | 2691 | On ARM, binaries need to have the frame pointer enabled for callgraphing to work. |
2692 | To accomplish this use the <filename>-fno-omit-framepointer</filename> option | 2692 | To accomplish this use the <filename>-fno-omit-framepointer</filename> option |
2693 | with <filename>gcc</filename>. | 2693 | with <filename>gcc</filename>. |
2694 | </note> | 2694 | </note> |
2695 | </para> | 2695 | </para> |
2696 | 2696 | ||
2697 | <para> | 2697 | <para> |
2698 | For more information on using OProfile, see the OProfile | 2698 | For more information on using OProfile, see the OProfile |
2699 | online documentation at | 2699 | online documentation at |
2700 | <ulink url="http://oprofile.sourceforge.net/docs/"/>. | 2700 | <ulink url="http://oprofile.sourceforge.net/docs/"/>. |
2701 | </para> | 2701 | </para> |
2702 | </section> | 2702 | </section> |
@@ -2705,15 +2705,15 @@ | |||
2705 | <title>Using OProfileUI</title> | 2705 | <title>Using OProfileUI</title> |
2706 | 2706 | ||
2707 | <para> | 2707 | <para> |
2708 | A graphical user interface for OProfile is also available. | 2708 | A graphical user interface for OProfile is also available. |
2709 | You can download and build this interface from the Yocto Project at | 2709 | You can download and build this interface from the Yocto Project at |
2710 | <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>. | 2710 | <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>. |
2711 | If the "tools-profile" image feature is selected, all necessary binaries | 2711 | If the "tools-profile" image feature is selected, all necessary binaries |
2712 | are installed onto the target device for OProfileUI interaction. | 2712 | are installed onto the target device for OProfileUI interaction. |
2713 | </para> | 2713 | </para> |
2714 | 2714 | ||
2715 | <para> | 2715 | <para> |
2716 | Even though the source directory usually includes all needed patches on the target device, you | 2716 | Even though the source directory usually includes all needed patches on the target device, you |
2717 | might find you need other OProfile patches for recent OProfileUI features. | 2717 | might find you need other OProfile patches for recent OProfileUI features. |
2718 | If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'> | 2718 | If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'> |
2719 | OProfileUI README</ulink> for the most recent information. | 2719 | OProfileUI README</ulink> for the most recent information. |
@@ -2723,18 +2723,18 @@ | |||
2723 | <title>Online Mode</title> | 2723 | <title>Online Mode</title> |
2724 | 2724 | ||
2725 | <para> | 2725 | <para> |
2726 | Using OProfile in online mode assumes a working network connection with the target | 2726 | Using OProfile in online mode assumes a working network connection with the target |
2727 | hardware. | 2727 | hardware. |
2728 | With this connection, you just need to run "oprofile-server" on the device. | 2728 | With this connection, you just need to run "oprofile-server" on the device. |
2729 | By default, OProfile listens on port 4224. | 2729 | By default, OProfile listens on port 4224. |
2730 | <note> | 2730 | <note> |
2731 | You can change the port using the <filename>--port</filename> command-line | 2731 | You can change the port using the <filename>--port</filename> command-line |
2732 | option. | 2732 | option. |
2733 | </note> | 2733 | </note> |
2734 | </para> | 2734 | </para> |
2735 | 2735 | ||
2736 | <para> | 2736 | <para> |
2737 | The client program is called <filename>oprofile-viewer</filename> and its UI is relatively | 2737 | The client program is called <filename>oprofile-viewer</filename> and its UI is relatively |
2738 | straightforward. | 2738 | straightforward. |
2739 | You access key functionality through the buttons on the toolbar, which | 2739 | You access key functionality through the buttons on the toolbar, which |
2740 | are duplicated in the menus. | 2740 | are duplicated in the menus. |
@@ -2746,15 +2746,15 @@ | |||
2746 | </para></listitem> | 2746 | </para></listitem> |
2747 | <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device. | 2747 | <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device. |
2748 | </para></listitem> | 2748 | </para></listitem> |
2749 | <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and | 2749 | <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and |
2750 | downloads the data to the local host. | 2750 | downloads the data to the local host. |
2751 | Stopping the profiler generates the profile and displays it in the viewer. | 2751 | Stopping the profiler generates the profile and displays it in the viewer. |
2752 | </para></listitem> | 2752 | </para></listitem> |
2753 | <listitem><para><emphasis>Download:</emphasis> Downloads the data from the | 2753 | <listitem><para><emphasis>Download:</emphasis> Downloads the data from the |
2754 | target and generates the profile, which appears in the viewer.</para></listitem> | 2754 | target and generates the profile, which appears in the viewer.</para></listitem> |
2755 | <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device. | 2755 | <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device. |
2756 | Resetting the data removes sample information collected from previous | 2756 | Resetting the data removes sample information collected from previous |
2757 | sampling runs. | 2757 | sampling runs. |
2758 | Be sure you reset the data if you do not want to include old sample information. | 2758 | Be sure you reset the data if you do not want to include old sample information. |
2759 | </para></listitem> | 2759 | </para></listitem> |
2760 | <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the | 2760 | <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the |
@@ -2766,45 +2766,45 @@ | |||
2766 | 2766 | ||
2767 | <para> | 2767 | <para> |
2768 | The client downloads the complete 'profile archive' from | 2768 | The client downloads the complete 'profile archive' from |
2769 | the target to the host for processing. | 2769 | the target to the host for processing. |
2770 | This archive is a directory that contains the sample data, the object files, | 2770 | This archive is a directory that contains the sample data, the object files, |
2771 | and the debug information for the object files. | 2771 | and the debug information for the object files. |
2772 | The archive is then converted using the <filename>oparchconv</filename> script, which is | 2772 | The archive is then converted using the <filename>oparchconv</filename> script, which is |
2773 | included in this distribution. | 2773 | included in this distribution. |
2774 | The script uses <filename>opimport</filename> to convert the archive from | 2774 | The script uses <filename>opimport</filename> to convert the archive from |
2775 | the target to something that can be processed on the host. | 2775 | the target to something that can be processed on the host. |
2776 | </para> | 2776 | </para> |
2777 | 2777 | ||
2778 | <para> | 2778 | <para> |
2779 | Downloaded archives reside in the Build Directory in | 2779 | Downloaded archives reside in the Build Directory in |
2780 | <filename>/tmp</filename> and are cleared up when they are no longer in use. | 2780 | <filename>/tmp</filename> and are cleared up when they are no longer in use. |
2781 | </para> | 2781 | </para> |
2782 | 2782 | ||
2783 | <para> | 2783 | <para> |
2784 | If you wish to perform kernel profiling, you need to be sure | 2784 | If you wish to perform kernel profiling, you need to be sure |
2785 | a <filename>vmlinux</filename> file that matches the running kernel is available. | 2785 | a <filename>vmlinux</filename> file that matches the running kernel is available. |
2786 | In the source directory, that file is usually located in | 2786 | In the source directory, that file is usually located in |
2787 | <filename>/boot/vmlinux-KERNELVERSION</filename>, where | 2787 | <filename>/boot/vmlinux-KERNELVERSION</filename>, where |
2788 | <filename>KERNEL-version</filename> is the version of the kernel. | 2788 | <filename>KERNEL-version</filename> is the version of the kernel. |
2789 | The OpenEmbedded build system generates separate <filename>vmlinux</filename> | 2789 | The OpenEmbedded build system generates separate <filename>vmlinux</filename> |
2790 | packages for each kernel it builds. | 2790 | packages for each kernel it builds. |
2791 | Thus, it should just be a question of making sure a matching package is | 2791 | Thus, it should just be a question of making sure a matching package is |
2792 | installed (e.g. <filename>opkg install kernel-vmlinux</filename>. | 2792 | installed (e.g. <filename>opkg install kernel-vmlinux</filename>. |
2793 | The files are automatically installed into development and profiling images | 2793 | The files are automatically installed into development and profiling images |
2794 | alongside OProfile. | 2794 | alongside OProfile. |
2795 | A configuration option exists within the OProfileUI settings page that you can use to | 2795 | A configuration option exists within the OProfileUI settings page that you can use to |
2796 | enter the location of the <filename>vmlinux</filename> file. | 2796 | enter the location of the <filename>vmlinux</filename> file. |
2797 | </para> | 2797 | </para> |
2798 | 2798 | ||
2799 | <para> | 2799 | <para> |
2800 | Waiting for debug symbols to transfer from the device can be slow, and it | 2800 | Waiting for debug symbols to transfer from the device can be slow, and it |
2801 | is not always necessary to actually have them on the device for OProfile use. | 2801 | is not always necessary to actually have them on the device for OProfile use. |
2802 | All that is needed is a copy of the filesystem with the debug symbols present | 2802 | All that is needed is a copy of the filesystem with the debug symbols present |
2803 | on the viewer system. | 2803 | on the viewer system. |
2804 | The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB on the Host Computer</link>" | 2804 | The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB on the Host Computer</link>" |
2805 | section covers how to create such a directory with | 2805 | section covers how to create such a directory with |
2806 | the source directory and how to use the OProfileUI Settings dialog to specify the location. | 2806 | the source directory and how to use the OProfileUI Settings dialog to specify the location. |
2807 | If you specify the directory, it will be used when the file checksums | 2807 | If you specify the directory, it will be used when the file checksums |
2808 | match those on the system you are profiling. | 2808 | match those on the system you are profiling. |
2809 | </para> | 2809 | </para> |
2810 | </section> | 2810 | </section> |
@@ -2829,8 +2829,8 @@ | |||
2829 | </para> | 2829 | </para> |
2830 | 2830 | ||
2831 | <para> | 2831 | <para> |
2832 | In the above example, <filename>my_archive</filename> is the name of the | 2832 | In the above example, <filename>my_archive</filename> is the name of the |
2833 | archive directory where you would like the profile archive to be kept. | 2833 | archive directory where you would like the profile archive to be kept. |
2834 | After the directory is created, you can copy it to another host and load it | 2834 | After the directory is created, you can copy it to another host and load it |
2835 | using <filename>oprofile-viewer</filename> open functionality. | 2835 | using <filename>oprofile-viewer</filename> open functionality. |
2836 | If necessary, the archive is converted. | 2836 | If necessary, the archive is converted. |
@@ -2846,44 +2846,44 @@ | |||
2846 | One of the concerns for a development organization using open source | 2846 | One of the concerns for a development organization using open source |
2847 | software is how to maintain compliance with various open source | 2847 | software is how to maintain compliance with various open source |
2848 | licensing during the lifecycle of the product. | 2848 | licensing during the lifecycle of the product. |
2849 | While this section does not provide legal advice or | 2849 | While this section does not provide legal advice or |
2850 | comprehensively cover all scenarios, it does | 2850 | comprehensively cover all scenarios, it does |
2851 | present methods that you can use to | 2851 | present methods that you can use to |
2852 | assist you in meeting the compliance requirements during a software | 2852 | assist you in meeting the compliance requirements during a software |
2853 | release. | 2853 | release. |
2854 | </para> | 2854 | </para> |
2855 | 2855 | ||
2856 | <para> | 2856 | <para> |
2857 | With hundreds of different open source licenses that the Yocto | 2857 | With hundreds of different open source licenses that the Yocto |
2858 | Project tracks, it is difficult to know the requirements of each | 2858 | Project tracks, it is difficult to know the requirements of each |
2859 | and every license. | 2859 | and every license. |
2860 | However, we can begin to cover the requirements of the major FLOSS licenses, by | 2860 | However, we can begin to cover the requirements of the major FLOSS licenses, by |
2861 | assuming that there are three main areas of concern: | 2861 | assuming that there are three main areas of concern: |
2862 | <itemizedlist> | 2862 | <itemizedlist> |
2863 | <listitem><para>Source code must be provided.</para></listitem> | 2863 | <listitem><para>Source code must be provided.</para></listitem> |
2864 | <listitem><para>License text for the software must be | 2864 | <listitem><para>License text for the software must be |
2865 | provided.</para></listitem> | 2865 | provided.</para></listitem> |
2866 | <listitem><para>Compilation scripts and modifications to the | 2866 | <listitem><para>Compilation scripts and modifications to the |
2867 | source code must be provided. | 2867 | source code must be provided. |
2868 | </para></listitem> | 2868 | </para></listitem> |
2869 | </itemizedlist> | 2869 | </itemizedlist> |
2870 | There are other requirements beyond the scope of these | 2870 | There are other requirements beyond the scope of these |
2871 | three and the methods described in this section | 2871 | three and the methods described in this section |
2872 | (e.g. the mechanism through which source code is distributed). | 2872 | (e.g. the mechanism through which source code is distributed). |
2873 | As different organizations have different methods of complying with | 2873 | As different organizations have different methods of complying with |
2874 | open source licensing, this section is not meant to imply that | 2874 | open source licensing, this section is not meant to imply that |
2875 | there is only one single way to meet your compliance obligations, | 2875 | there is only one single way to meet your compliance obligations, |
2876 | but rather to describe one method of achieving compliance. | 2876 | but rather to describe one method of achieving compliance. |
2877 | </para> | 2877 | </para> |
2878 | 2878 | ||
2879 | <para> | 2879 | <para> |
2880 | The remainder of this section describes methods supported to meet the | 2880 | The remainder of this section describes methods supported to meet the |
2881 | previously mentioned three requirements. | 2881 | previously mentioned three requirements. |
2882 | Once you take steps to meet these requirements, | 2882 | Once you take steps to meet these requirements, |
2883 | and prior to releasing images, sources, and the build system, | 2883 | and prior to releasing images, sources, and the build system, |
2884 | you should audit all artifacts to ensure completeness. | 2884 | you should audit all artifacts to ensure completeness. |
2885 | The Yocto Project generates a license manifest during | 2885 | The Yocto Project generates a license manifest during |
2886 | image creation that is located | 2886 | image creation that is located |
2887 | in <filename>${DEPLOY_DIR}/licenses/<image_name-datestamp></filename> | 2887 | in <filename>${DEPLOY_DIR}/licenses/<image_name-datestamp></filename> |
2888 | to assist with any audits. | 2888 | to assist with any audits. |
2889 | </para> | 2889 | </para> |
@@ -2892,42 +2892,42 @@ | |||
2892 | <title>Providing the Source Code</title> | 2892 | <title>Providing the Source Code</title> |
2893 | 2893 | ||
2894 | <para> | 2894 | <para> |
2895 | Compliance activities should begin before you generate the | 2895 | Compliance activities should begin before you generate the |
2896 | final image. | 2896 | final image. |
2897 | The first thing you should look at is the requirement that | 2897 | The first thing you should look at is the requirement that |
2898 | tops the list for most compliance groups - providing | 2898 | tops the list for most compliance groups - providing |
2899 | the source. | 2899 | the source. |
2900 | The Yocto Project has a few ways of meeting this | 2900 | The Yocto Project has a few ways of meeting this |
2901 | requirement. | 2901 | requirement. |
2902 | </para> | 2902 | </para> |
2903 | 2903 | ||
2904 | <para> | 2904 | <para> |
2905 | One of the easiest ways to meet this requirement is | 2905 | One of the easiest ways to meet this requirement is |
2906 | to provide the entire | 2906 | to provide the entire |
2907 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> | 2907 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> |
2908 | used by the build. | 2908 | used by the build. |
2909 | This method, however, has a few issues. | 2909 | This method, however, has a few issues. |
2910 | The most obvious is the size of the directory since it includes | 2910 | The most obvious is the size of the directory since it includes |
2911 | all sources used in the build and not just the source used in | 2911 | all sources used in the build and not just the source used in |
2912 | the released image. | 2912 | the released image. |
2913 | It will include toolchain source, and other artifacts which | 2913 | It will include toolchain source, and other artifacts which |
2914 | you would not generally release. | 2914 | you would not generally release. |
2915 | But, the more serious issue for most companies is accidental | 2915 | But, the more serious issue for most companies is accidental |
2916 | release of proprietary software. | 2916 | release of proprietary software. |
2917 | The Yocto Project provides an archiver class to help avoid | 2917 | The Yocto Project provides an archiver class to help avoid |
2918 | some of these concerns. | 2918 | some of these concerns. |
2919 | </para> | 2919 | </para> |
2920 | 2920 | ||
2921 | <para> | 2921 | <para> |
2922 | Before you employ <filename>DL_DIR</filename> or the | 2922 | Before you employ <filename>DL_DIR</filename> or the |
2923 | archiver class, you need to decide how you choose to | 2923 | archiver class, you need to decide how you choose to |
2924 | provide source. | 2924 | provide source. |
2925 | The source archiver class can generate tarballs and SRPMs | 2925 | The source archiver class can generate tarballs and SRPMs |
2926 | and can create them with various levels of compliance in mind. | 2926 | and can create them with various levels of compliance in mind. |
2927 | One way of doing this (but certainly not the only way) is to | 2927 | One way of doing this (but certainly not the only way) is to |
2928 | release just the original source as a tarball. | 2928 | release just the original source as a tarball. |
2929 | You can do this by adding the following to the | 2929 | You can do this by adding the following to the |
2930 | <filename>local.conf</filename> file found in the | 2930 | <filename>local.conf</filename> file found in the |
2931 | <link linkend='build-directory'>Build Directory</link>: | 2931 | <link linkend='build-directory'>Build Directory</link>: |
2932 | <literallayout class='monospaced'> | 2932 | <literallayout class='monospaced'> |
2933 | ARCHIVER_MODE ?= "original" | 2933 | ARCHIVER_MODE ?= "original" |
@@ -2937,32 +2937,32 @@ | |||
2937 | SOURCE_ARCHIVE_PACKAGE_TYPE = "tar" | 2937 | SOURCE_ARCHIVE_PACKAGE_TYPE = "tar" |
2938 | </literallayout> | 2938 | </literallayout> |
2939 | During the creation of your image, all GPL | 2939 | During the creation of your image, all GPL |
2940 | or other copyleft licensed source | 2940 | or other copyleft licensed source |
2941 | is placed within subdirectories of | 2941 | is placed within subdirectories of |
2942 | <filename>DEPLOY_DIR/sources</filename> based on the | 2942 | <filename>DEPLOY_DIR/sources</filename> based on the |
2943 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> | 2943 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> |
2944 | for each recipe. | 2944 | for each recipe. |
2945 | Releasing the entire directory enables you to comply with | 2945 | Releasing the entire directory enables you to comply with |
2946 | requirements concerning providing the unmodified source. | 2946 | requirements concerning providing the unmodified source. |
2947 | It is important to note that the size of the directory can | 2947 | It is important to note that the size of the directory can |
2948 | get large. | 2948 | get large. |
2949 | </para> | 2949 | </para> |
2950 | 2950 | ||
2951 | <para> | 2951 | <para> |
2952 | A way to help mitigate the size issue is to only release | 2952 | A way to help mitigate the size issue is to only release |
2953 | tarballs for licenses that require the release of | 2953 | tarballs for licenses that require the release of |
2954 | source. | 2954 | source. |
2955 | Let's assume you are only concerned with GPL code as | 2955 | Let's assume you are only concerned with GPL code as |
2956 | identified with the following: | 2956 | identified with the following: |
2957 | <literallayout class='monospaced'> | 2957 | <literallayout class='monospaced'> |
2958 | $ cd poky/build/tmp/deploy/sources | 2958 | $ cd poky/build/tmp/deploy/sources |
2959 | $ mkdir ~/gpl_source_release | 2959 | $ mkdir ~/gpl_source_release |
2960 | $ for x in `ls|grep GPL`; do cp -R $x/* ~/gpl_source_release; done | 2960 | $ for x in `ls|grep GPL`; do cp -R $x/* ~/gpl_source_release; done |
2961 | </literallayout> | 2961 | </literallayout> |
2962 | At this point, you could create a tarball from the | 2962 | At this point, you could create a tarball from the |
2963 | <filename>gpl_source_release</filename> directory and | 2963 | <filename>gpl_source_release</filename> directory and |
2964 | provide that to the end user. | 2964 | provide that to the end user. |
2965 | This method would be a step toward achieving compliance | 2965 | This method would be a step toward achieving compliance |
2966 | with section 3a of GPLv2 and with section 6 of GPLv3. | 2966 | with section 3a of GPLv2 and with section 6 of GPLv3. |
2967 | </para> | 2967 | </para> |
2968 | </section> | 2968 | </section> |
@@ -2971,12 +2971,12 @@ | |||
2971 | <title>Providing License Text</title> | 2971 | <title>Providing License Text</title> |
2972 | 2972 | ||
2973 | <para> | 2973 | <para> |
2974 | One requirement that is often overlooked is inclusion | 2974 | One requirement that is often overlooked is inclusion |
2975 | of license text. | 2975 | of license text. |
2976 | This requirement also needs to be dealt with prior to | 2976 | This requirement also needs to be dealt with prior to |
2977 | generating the final image. | 2977 | generating the final image. |
2978 | Some licenses require the license text to accompany | 2978 | Some licenses require the license text to accompany |
2979 | the binary. | 2979 | the binary. |
2980 | You can achieve this by adding the following to your | 2980 | You can achieve this by adding the following to your |
2981 | <filename>local.conf</filename> file: | 2981 | <filename>local.conf</filename> file: |
2982 | <literallayout class='monospaced'> | 2982 | <literallayout class='monospaced'> |
@@ -2986,10 +2986,10 @@ | |||
2986 | Adding these statements to the configuration file ensures | 2986 | Adding these statements to the configuration file ensures |
2987 | that the licenses collected during package generation | 2987 | that the licenses collected during package generation |
2988 | are included on your image. | 2988 | are included on your image. |
2989 | As the source archiver has already archived the original | 2989 | As the source archiver has already archived the original |
2990 | unmodified source which would contain the license files, | 2990 | unmodified source which would contain the license files, |
2991 | you would have already met the requirements for inclusion | 2991 | you would have already met the requirements for inclusion |
2992 | of the license information with source as defined by the GPL | 2992 | of the license information with source as defined by the GPL |
2993 | and other open source licenses. | 2993 | and other open source licenses. |
2994 | </para> | 2994 | </para> |
2995 | </section> | 2995 | </section> |
@@ -2998,7 +2998,7 @@ | |||
2998 | <title>Providing Compilation Scripts and Source Code Modifications</title> | 2998 | <title>Providing Compilation Scripts and Source Code Modifications</title> |
2999 | 2999 | ||
3000 | <para> | 3000 | <para> |
3001 | At this point, we have addressed all we need to address | 3001 | At this point, we have addressed all we need to address |
3002 | prior to generating the image. | 3002 | prior to generating the image. |
3003 | The next two requirements are addressed during the final | 3003 | The next two requirements are addressed during the final |
3004 | packaging of the release. | 3004 | packaging of the release. |
@@ -3007,20 +3007,20 @@ | |||
3007 | <para> | 3007 | <para> |
3008 | By releasing the version of the OpenEmbedded build system | 3008 | By releasing the version of the OpenEmbedded build system |
3009 | and the layers used during the build, you will be providing both | 3009 | and the layers used during the build, you will be providing both |
3010 | compilation scripts and the source code modifications in one | 3010 | compilation scripts and the source code modifications in one |
3011 | step. | 3011 | step. |
3012 | </para> | 3012 | </para> |
3013 | 3013 | ||
3014 | <para> | 3014 | <para> |
3015 | If the deployment team has a | 3015 | If the deployment team has a |
3016 | <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink> | 3016 | <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink> |
3017 | and a distro layer, and those those layers are used to patch, | 3017 | and a distro layer, and those those layers are used to patch, |
3018 | compile, package, or modify (in any way) any open source | 3018 | compile, package, or modify (in any way) any open source |
3019 | software included in your released images, you | 3019 | software included in your released images, you |
3020 | may be required to to release those layers under section 3 of | 3020 | may be required to to release those layers under section 3 of |
3021 | GPLv2 or section 1 of GPLv3. | 3021 | GPLv2 or section 1 of GPLv3. |
3022 | One way of doing that is with a clean | 3022 | One way of doing that is with a clean |
3023 | checkout of the version of the Yocto Project and layers used | 3023 | checkout of the version of the Yocto Project and layers used |
3024 | during your build. | 3024 | during your build. |
3025 | Here is an example: | 3025 | Here is an example: |
3026 | <literallayout class='monospaced'> | 3026 | <literallayout class='monospaced'> |
@@ -3033,11 +3033,11 @@ | |||
3033 | # clean up the .git repos | 3033 | # clean up the .git repos |
3034 | $ find . -name ".git" -type d -exec rm -rf {} \; | 3034 | $ find . -name ".git" -type d -exec rm -rf {} \; |
3035 | </literallayout> | 3035 | </literallayout> |
3036 | One thing a development organization might want to consider | 3036 | One thing a development organization might want to consider |
3037 | for end-user convenience is to modify | 3037 | for end-user convenience is to modify |
3038 | <filename>meta-yocto/conf/bblayers.conf.sample</filename> to | 3038 | <filename>meta-yocto/conf/bblayers.conf.sample</filename> to |
3039 | ensure that when the end user utilizes the released build | 3039 | ensure that when the end user utilizes the released build |
3040 | system to build an image, the development organization's | 3040 | system to build an image, the development organization's |
3041 | layers are included in the <filename>bblayers.conf</filename> | 3041 | layers are included in the <filename>bblayers.conf</filename> |
3042 | file automatically: | 3042 | file automatically: |
3043 | <literallayout class='monospaced'> | 3043 | <literallayout class='monospaced'> |
@@ -3061,15 +3061,15 @@ | |||
3061 | " | 3061 | " |
3062 | </literallayout> | 3062 | </literallayout> |
3063 | Creating and providing an archive of the metadata layers | 3063 | Creating and providing an archive of the metadata layers |
3064 | (recipes, configuration files, and so forth) | 3064 | (recipes, configuration files, and so forth) |
3065 | enables you to meet your | 3065 | enables you to meet your |
3066 | requirements to include the scripts to control compilation | 3066 | requirements to include the scripts to control compilation |
3067 | as well as any modifications to the original source. | 3067 | as well as any modifications to the original source. |
3068 | </para> | 3068 | </para> |
3069 | </section> | 3069 | </section> |
3070 | </section> | 3070 | </section> |
3071 | </chapter> | 3071 | </chapter> |
3072 | 3072 | ||
3073 | <!-- | 3073 | <!-- |
3074 | vim: expandtab tw=80 ts=4 | 3074 | vim: expandtab tw=80 ts=4 |
3075 | --> | 3075 | --> |
diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml index 99990c4466..d7b589f187 100644 --- a/documentation/dev-manual/dev-manual-intro.xml +++ b/documentation/dev-manual/dev-manual-intro.xml | |||
@@ -10,19 +10,19 @@ | |||
10 | 10 | ||
11 | <para> | 11 | <para> |
12 | Welcome to the Yocto Project Development Manual! | 12 | Welcome to the Yocto Project Development Manual! |
13 | This manual gives you an idea of how to use the Yocto Project to develop embedded Linux | 13 | This manual gives you an idea of how to use the Yocto Project to develop embedded Linux |
14 | images and user-space applications to run on targeted devices. | 14 | images and user-space applications to run on targeted devices. |
15 | Reading this manual gives you an overview of image, kernel, and user-space application development | 15 | Reading this manual gives you an overview of image, kernel, and user-space application development |
16 | using the Yocto Project. | 16 | using the Yocto Project. |
17 | Because much of the information in this manual is general, it contains many references to other | 17 | Because much of the information in this manual is general, it contains many references to other |
18 | sources where you can find more detail. | 18 | sources where you can find more detail. |
19 | For example, detailed information on Git, repositories and open source in general | 19 | For example, detailed information on Git, repositories and open source in general |
20 | can be found in many places. | 20 | can be found in many places. |
21 | Another example is how to get set up to use the Yocto Project, which our Yocto Project | 21 | Another example is how to get set up to use the Yocto Project, which our Yocto Project |
22 | Quick Start covers. | 22 | Quick Start covers. |
23 | </para> | 23 | </para> |
24 | 24 | ||
25 | <para> | 25 | <para> |
26 | The Yocto Project Development Manual, however, does provide detailed examples | 26 | The Yocto Project Development Manual, however, does provide detailed examples |
27 | on how to change the kernel source code, reconfigure the kernel, and develop | 27 | on how to change the kernel source code, reconfigure the kernel, and develop |
28 | an application using the popular <trademark class='trade'>Eclipse</trademark> IDE. | 28 | an application using the popular <trademark class='trade'>Eclipse</trademark> IDE. |
@@ -35,15 +35,15 @@ | |||
35 | <para> | 35 | <para> |
36 | The following list describes what you can get from this guide: | 36 | The following list describes what you can get from this guide: |
37 | <itemizedlist> | 37 | <itemizedlist> |
38 | <listitem><para>Information that lets you get set | 38 | <listitem><para>Information that lets you get set |
39 | up to develop using the Yocto Project.</para></listitem> | 39 | up to develop using the Yocto Project.</para></listitem> |
40 | <listitem><para>Information to help developers who are new to the open source environment | 40 | <listitem><para>Information to help developers who are new to the open source environment |
41 | and to the distributed revision control system Git, which the Yocto Project | 41 | and to the distributed revision control system Git, which the Yocto Project |
42 | uses.</para></listitem> | 42 | uses.</para></listitem> |
43 | <listitem><para>An understanding of common end-to-end development models and tasks.</para></listitem> | 43 | <listitem><para>An understanding of common end-to-end development models and tasks.</para></listitem> |
44 | <listitem><para>Development case overviews for both system development and user-space | 44 | <listitem><para>Development case overviews for both system development and user-space |
45 | applications.</para></listitem> | 45 | applications.</para></listitem> |
46 | <listitem><para>An overview and understanding of the emulation environment used with | 46 | <listitem><para>An overview and understanding of the emulation environment used with |
47 | the Yocto Project - the Quick EMUlator (QEMU).</para></listitem> | 47 | the Yocto Project - the Quick EMUlator (QEMU).</para></listitem> |
48 | <listitem><para>An understanding of basic kernel architecture and concepts.</para></listitem> | 48 | <listitem><para>An understanding of basic kernel architecture and concepts.</para></listitem> |
49 | <listitem><para>Many references to other sources of related information.</para></listitem> | 49 | <listitem><para>Many references to other sources of related information.</para></listitem> |
@@ -57,18 +57,18 @@ | |||
57 | <para> | 57 | <para> |
58 | This manual will not give you the following: | 58 | This manual will not give you the following: |
59 | <itemizedlist> | 59 | <itemizedlist> |
60 | <listitem><para>Step-by-step instructions if those instructions exist in other Yocto | 60 | <listitem><para>Step-by-step instructions if those instructions exist in other Yocto |
61 | Project documentation. | 61 | Project documentation. |
62 | For example, the Yocto Project Application Developer's Guide contains detailed | 62 | For example, the Yocto Project Application Developer's Guide contains detailed |
63 | instruction on how to run the | 63 | instruction on how to run the |
64 | <ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>, | 64 | <ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>, |
65 | which is used to set up a cross-development environment.</para></listitem> | 65 | which is used to set up a cross-development environment.</para></listitem> |
66 | <listitem><para>Reference material. | 66 | <listitem><para>Reference material. |
67 | This type of material resides in an appropriate reference manual. | 67 | This type of material resides in an appropriate reference manual. |
68 | For example, system variables are documented in the | 68 | For example, system variables are documented in the |
69 | <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem> | 69 | <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem> |
70 | <listitem><para>Detailed public information that is not specific to the Yocto Project. | 70 | <listitem><para>Detailed public information that is not specific to the Yocto Project. |
71 | For example, exhaustive information on how to use Git is covered better through the | 71 | For example, exhaustive information on how to use Git is covered better through the |
72 | Internet than in this manual.</para></listitem> | 72 | Internet than in this manual.</para></listitem> |
73 | </itemizedlist> | 73 | </itemizedlist> |
74 | </para> | 74 | </para> |
@@ -76,56 +76,56 @@ | |||
76 | 76 | ||
77 | <section id='other-information'> | 77 | <section id='other-information'> |
78 | <title>Other Information</title> | 78 | <title>Other Information</title> |
79 | 79 | ||
80 | <para> | 80 | <para> |
81 | Because this manual presents overview information for many different topics, you will | 81 | Because this manual presents overview information for many different topics, you will |
82 | need to supplement it with other information. | 82 | need to supplement it with other information. |
83 | The following list presents other sources of information you might find helpful: | 83 | The following list presents other sources of information you might find helpful: |
84 | <itemizedlist> | 84 | <itemizedlist> |
85 | <listitem><para><emphasis>The <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>: | 85 | <listitem><para><emphasis>The <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>: |
86 | </emphasis> The home page for the Yocto Project provides lots of information on the project | 86 | </emphasis> The home page for the Yocto Project provides lots of information on the project |
87 | as well as links to software and documentation.</para></listitem> | 87 | as well as links to software and documentation.</para></listitem> |
88 | <listitem><para><emphasis> | 88 | <listitem><para><emphasis> |
89 | <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started | 89 | <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started |
90 | with the Yocto Project quickly and start building an image.</para></listitem> | 90 | with the Yocto Project quickly and start building an image.</para></listitem> |
91 | <listitem><para><emphasis> | 91 | <listitem><para><emphasis> |
92 | <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference | 92 | <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference |
93 | guide to the OpenEmbedded build system known as "Poky." | 93 | guide to the OpenEmbedded build system known as "Poky." |
94 | The manual also contains a reference chapter on Board Support Package (BSP) | 94 | The manual also contains a reference chapter on Board Support Package (BSP) |
95 | layout.</para></listitem> | 95 | layout.</para></listitem> |
96 | <listitem><para><emphasis> | 96 | <listitem><para><emphasis> |
97 | <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis> | 97 | <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis> |
98 | This guide provides information that lets you get going with the Application | 98 | This guide provides information that lets you get going with the Application |
99 | Development Toolkit (ADT) and stand-alone cross-development toolchains to | 99 | Development Toolkit (ADT) and stand-alone cross-development toolchains to |
100 | develop projects using the Yocto Project.</para></listitem> | 100 | develop projects using the Yocto Project.</para></listitem> |
101 | <listitem><para><emphasis> | 101 | <listitem><para><emphasis> |
102 | <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis> | 102 | <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis> |
103 | This guide defines the structure for BSP components. | 103 | This guide defines the structure for BSP components. |
104 | Having a commonly understood structure encourages standardization.</para></listitem> | 104 | Having a commonly understood structure encourages standardization.</para></listitem> |
105 | <listitem><para><emphasis> | 105 | <listitem><para><emphasis> |
106 | <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>:</emphasis> | 106 | <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>:</emphasis> |
107 | This manual describes the architecture of the Yocto Project kernel and provides | 107 | This manual describes the architecture of the Yocto Project kernel and provides |
108 | some work flow examples.</para></listitem> | 108 | some work flow examples.</para></listitem> |
109 | <listitem><para><emphasis> | 109 | <listitem><para><emphasis> |
110 | <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'> | 110 | <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'> |
111 | Eclipse IDE Yocto Plug-in</ulink>:</emphasis> A step-by-step instructional video that | 111 | Eclipse IDE Yocto Plug-in</ulink>:</emphasis> A step-by-step instructional video that |
112 | demonstrates how an application developer uses Yocto Plug-in features within | 112 | demonstrates how an application developer uses Yocto Plug-in features within |
113 | the Eclipse IDE.</para></listitem> | 113 | the Eclipse IDE.</para></listitem> |
114 | <listitem><para><emphasis> | 114 | <listitem><para><emphasis> |
115 | <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis> | 115 | <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis> |
116 | A list of commonly asked questions and their answers.</para></listitem> | 116 | A list of commonly asked questions and their answers.</para></listitem> |
117 | <listitem><para><emphasis> | 117 | <listitem><para><emphasis> |
118 | <ulink url='&YOCTO_HOME_URL;/download/yocto/yocto-project-&DISTRO;-release-notes-poky-&POKYVERSION;'> | 118 | <ulink url='&YOCTO_HOME_URL;/download/yocto/yocto-project-&DISTRO;-release-notes-poky-&POKYVERSION;'> |
119 | Release Notes</ulink>:</emphasis> Features, updates and known issues for the current | 119 | Release Notes</ulink>:</emphasis> Features, updates and known issues for the current |
120 | release of the Yocto Project.</para></listitem> | 120 | release of the Yocto Project.</para></listitem> |
121 | <listitem><para><emphasis> | 121 | <listitem><para><emphasis> |
122 | <ulink url='&YOCTO_HOME_URL;/projects/hob'> | 122 | <ulink url='&YOCTO_HOME_URL;/projects/hob'> |
123 | Hob</ulink>:</emphasis> A graphical user interface for BitBake. | 123 | Hob</ulink>:</emphasis> A graphical user interface for BitBake. |
124 | Hob's primary goal is to enable a user to perform common tasks more easily.</para></listitem> | 124 | Hob's primary goal is to enable a user to perform common tasks more easily.</para></listitem> |
125 | <listitem><para><emphasis> | 125 | <listitem><para><emphasis> |
126 | <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'> | 126 | <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'> |
127 | Build Appliance</ulink>:</emphasis> A bootable custom embedded Linux image you can | 127 | Build Appliance</ulink>:</emphasis> A bootable custom embedded Linux image you can |
128 | either build using a non-Linux development system (VMware applications) or download | 128 | either build using a non-Linux development system (VMware applications) or download |
129 | from the Yocto Project website. | 129 | from the Yocto Project website. |
130 | See the <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> | 130 | See the <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> |
131 | page for more information.</para></listitem> | 131 | page for more information.</para></listitem> |
@@ -135,20 +135,20 @@ | |||
135 | If you find problems with the Yocto Project, you should report them using this | 135 | If you find problems with the Yocto Project, you should report them using this |
136 | application.</para></listitem> | 136 | application.</para></listitem> |
137 | <listitem><para><emphasis> | 137 | <listitem><para><emphasis> |
138 | Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing | 138 | Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing |
139 | lists, click on the following URLs and follow the instructions: | 139 | lists, click on the following URLs and follow the instructions: |
140 | <itemizedlist> | 140 | <itemizedlist> |
141 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a | 141 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a |
142 | Yocto Project Discussions mailing list.</para></listitem> | 142 | Yocto Project Discussions mailing list.</para></listitem> |
143 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a | 143 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a |
144 | Yocto Project Discussions mailing list about the Poky build system.</para></listitem> | 144 | Yocto Project Discussions mailing list about the Poky build system.</para></listitem> |
145 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> | 145 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> |
146 | for a mailing list to receive official Yocto Project announcements for developments and | 146 | for a mailing list to receive official Yocto Project announcements for developments and |
147 | as well as Yocto Project milestones.</para></listitem> | 147 | as well as Yocto Project milestones.</para></listitem> |
148 | </itemizedlist></para></listitem> | 148 | </itemizedlist></para></listitem> |
149 | <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis> | 149 | <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis> |
150 | Two IRC channels on freenode are available | 150 | Two IRC channels on freenode are available |
151 | for Yocto Project and Poky discussions: <filename>#yocto</filename> and | 151 | for Yocto Project and Poky discussions: <filename>#yocto</filename> and |
152 | <filename>#poky</filename>, respectively.</para></listitem> | 152 | <filename>#poky</filename>, respectively.</para></listitem> |
153 | <listitem><para><emphasis> | 153 | <listitem><para><emphasis> |
154 | <ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis> | 154 | <ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis> |
@@ -157,30 +157,30 @@ | |||
157 | OpenedHand was acquired by Intel Corporation in 2008.</para></listitem> | 157 | OpenedHand was acquired by Intel Corporation in 2008.</para></listitem> |
158 | <listitem><para><emphasis> | 158 | <listitem><para><emphasis> |
159 | <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis> | 159 | <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis> |
160 | A multinational semiconductor chip manufacturer company whose Software and | 160 | A multinational semiconductor chip manufacturer company whose Software and |
161 | Services Group created and supports the Yocto Project. | 161 | Services Group created and supports the Yocto Project. |
162 | Intel acquired OpenedHand in 2008.</para></listitem> | 162 | Intel acquired OpenedHand in 2008.</para></listitem> |
163 | <listitem><para><emphasis> | 163 | <listitem><para><emphasis> |
164 | <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> | 164 | <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> |
165 | The build system used by the Yocto Project. | 165 | The build system used by the Yocto Project. |
166 | This project is the upstream, generic, embedded distribution from which the Yocto | 166 | This project is the upstream, generic, embedded distribution from which the Yocto |
167 | Project derives its build system (Poky) from and to which it contributes.</para></listitem> | 167 | Project derives its build system (Poky) from and to which it contributes.</para></listitem> |
168 | <listitem><para><emphasis> | 168 | <listitem><para><emphasis> |
169 | <ulink url='http://developer.berlios.de/projects/bitbake/'> | 169 | <ulink url='http://developer.berlios.de/projects/bitbake/'> |
170 | BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system | 170 | BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system |
171 | to process project metadata.</para></listitem> | 171 | to process project metadata.</para></listitem> |
172 | <listitem><para><emphasis> | 172 | <listitem><para><emphasis> |
173 | BitBake User Manual:</emphasis> | 173 | BitBake User Manual:</emphasis> |
174 | A comprehensive guide to the BitBake tool. | 174 | A comprehensive guide to the BitBake tool. |
175 | If you want information on BitBake, see the user manual inculded in the | 175 | If you want information on BitBake, see the user manual inculded in the |
176 | <filename>bitbake/doc/manual</filename> directory of the | 176 | <filename>bitbake/doc/manual</filename> directory of the |
177 | <link linkend='source-directory'>Source Directory</link>.</para></listitem> | 177 | <link linkend='source-directory'>Source Directory</link>.</para></listitem> |
178 | <listitem><para><emphasis> | 178 | <listitem><para><emphasis> |
179 | <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>: | 179 | <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>: |
180 | </emphasis> An open-source machine emulator and virtualizer.</para></listitem> | 180 | </emphasis> An open-source machine emulator and virtualizer.</para></listitem> |
181 | </itemizedlist> | 181 | </itemizedlist> |
182 | </para> | 182 | </para> |
183 | </section> | 183 | </section> |
184 | </chapter> | 184 | </chapter> |
185 | <!-- | 185 | <!-- |
186 | vim: expandtab tw=80 ts=4 | 186 | vim: expandtab tw=80 ts=4 |
diff --git a/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml b/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml index 6ea77d030c..7765feb9c1 100644 --- a/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml +++ b/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml | |||
@@ -7,16 +7,16 @@ | |||
7 | <title>Kernel Modification Example</title> | 7 | <title>Kernel Modification Example</title> |
8 | 8 | ||
9 | <para> | 9 | <para> |
10 | Kernel modification involves changing or adding configurations to an existing kernel, | 10 | Kernel modification involves changing or adding configurations to an existing kernel, |
11 | changing or adding recipes to the kernel that are needed to support specific hardware features, | 11 | changing or adding recipes to the kernel that are needed to support specific hardware features, |
12 | or even altering the source code itself. | 12 | or even altering the source code itself. |
13 | This appendix presents simple examples that modify the kernel source code, | 13 | This appendix presents simple examples that modify the kernel source code, |
14 | change the kernel configuration, and add a kernel source recipe. | 14 | change the kernel configuration, and add a kernel source recipe. |
15 | <note> | 15 | <note> |
16 | You can use the <filename>yocto-kernel</filename> script | 16 | You can use the <filename>yocto-kernel</filename> script |
17 | found in the <link linkend='source-directory'>Source Directory</link> | 17 | found in the <link linkend='source-directory'>Source Directory</link> |
18 | under <filename>scripts</filename> to manage kernel patches and configuration. | 18 | under <filename>scripts</filename> to manage kernel patches and configuration. |
19 | See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>" | 19 | See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>" |
20 | section in the Yocto Project Board Support Packages (BSP) Developer's Guide for | 20 | section in the Yocto Project Board Support Packages (BSP) Developer's Guide for |
21 | more information.</note> | 21 | more information.</note> |
22 | </para> | 22 | </para> |
@@ -25,87 +25,87 @@ | |||
25 | <title>Modifying the Kernel Source Code</title> | 25 | <title>Modifying the Kernel Source Code</title> |
26 | 26 | ||
27 | <para> | 27 | <para> |
28 | This example adds some simple QEMU emulator console output at boot time by | 28 | This example adds some simple QEMU emulator console output at boot time by |
29 | adding <filename>printk</filename> statements to the kernel's | 29 | adding <filename>printk</filename> statements to the kernel's |
30 | <filename>calibrate.c</filename> source code file. | 30 | <filename>calibrate.c</filename> source code file. |
31 | Booting the modified image causes the added messages to appear on the emulator's | 31 | Booting the modified image causes the added messages to appear on the emulator's |
32 | console. | 32 | console. |
33 | </para> | 33 | </para> |
34 | 34 | ||
35 | <section id='understanding-the-files-you-need'> | 35 | <section id='understanding-the-files-you-need'> |
36 | <title>Understanding the Files You Need</title> | 36 | <title>Understanding the Files You Need</title> |
37 | 37 | ||
38 | <para> | 38 | <para> |
39 | Before you modify the kernel, you need to know what Git repositories and file | 39 | Before you modify the kernel, you need to know what Git repositories and file |
40 | structures you need. | 40 | structures you need. |
41 | Briefly, you need the following: | 41 | Briefly, you need the following: |
42 | <itemizedlist> | 42 | <itemizedlist> |
43 | <listitem><para>A local | 43 | <listitem><para>A local |
44 | <link linkend='source-directory'>Source Directory</link> for the | 44 | <link linkend='source-directory'>Source Directory</link> for the |
45 | poky Git repository</para></listitem> | 45 | poky Git repository</para></listitem> |
46 | <listitem><para>Local copies of the | 46 | <listitem><para>Local copies of the |
47 | <link linkend='poky-extras-repo'><filename>poky-extras</filename></link> | 47 | <link linkend='poky-extras-repo'><filename>poky-extras</filename></link> |
48 | Git repository placed within the Source Directory.</para></listitem> | 48 | Git repository placed within the Source Directory.</para></listitem> |
49 | <listitem><para>A bare clone of the | 49 | <listitem><para>A bare clone of the |
50 | <link linkend='local-kernel-files'>Yocto Project Kernel</link> upstream Git | 50 | <link linkend='local-kernel-files'>Yocto Project Kernel</link> upstream Git |
51 | repository to which you want to push your modifications. | 51 | repository to which you want to push your modifications. |
52 | </para></listitem> | 52 | </para></listitem> |
53 | <listitem><para>A copy of that bare clone in which you make your source | 53 | <listitem><para>A copy of that bare clone in which you make your source |
54 | modifications</para></listitem> | 54 | modifications</para></listitem> |
55 | </itemizedlist> | 55 | </itemizedlist> |
56 | </para> | 56 | </para> |
57 | 57 | ||
58 | <para> | 58 | <para> |
59 | The following figure summarizes these four areas. | 59 | The following figure summarizes these four areas. |
60 | Within each rectangular that represents a data structure, a | 60 | Within each rectangular that represents a data structure, a |
61 | host development directory pathname appears at the | 61 | host development directory pathname appears at the |
62 | lower left-hand corner of the box. | 62 | lower left-hand corner of the box. |
63 | These pathnames are the locations used in this example. | 63 | These pathnames are the locations used in this example. |
64 | The figure also provides key statements and commands used during the kernel | 64 | The figure also provides key statements and commands used during the kernel |
65 | modification process: | 65 | modification process: |
66 | </para> | 66 | </para> |
67 | 67 | ||
68 | <para> | 68 | <para> |
69 | <imagedata fileref="figures/kernel-example-repos-generic.png" width="7in" depth="5in" | 69 | <imagedata fileref="figures/kernel-example-repos-generic.png" width="7in" depth="5in" |
70 | align="center" scale="100" /> | 70 | align="center" scale="100" /> |
71 | </para> | 71 | </para> |
72 | 72 | ||
73 | <para> | 73 | <para> |
74 | Here is a brief description of the four areas: | 74 | Here is a brief description of the four areas: |
75 | <itemizedlist> | 75 | <itemizedlist> |
76 | <listitem><para><emphasis>Local Source Directory:</emphasis> | 76 | <listitem><para><emphasis>Local Source Directory:</emphasis> |
77 | This area contains all the metadata that supports building images | 77 | This area contains all the metadata that supports building images |
78 | using the OpenEmbedded build system. | 78 | using the OpenEmbedded build system. |
79 | In this example, the | 79 | In this example, the |
80 | <link linkend='source-directory'>Source Directory</link> also | 80 | <link linkend='source-directory'>Source Directory</link> also |
81 | contains the | 81 | contains the |
82 | <link linkend='build-directory'>Build Directory</link>, | 82 | <link linkend='build-directory'>Build Directory</link>, |
83 | which contains the configuration directory | 83 | which contains the configuration directory |
84 | that lets you control the build. | 84 | that lets you control the build. |
85 | Also in this example, the Source Directory contains local copies of the | 85 | Also in this example, the Source Directory contains local copies of the |
86 | <filename>poky-extras</filename> Git repository.</para> | 86 | <filename>poky-extras</filename> Git repository.</para> |
87 | <para>See the bulleted item | 87 | <para>See the bulleted item |
88 | "<link linkend='local-yp-release'>Yocto Project Release</link>" | 88 | "<link linkend='local-yp-release'>Yocto Project Release</link>" |
89 | for information on how to get these files on your local system.</para></listitem> | 89 | for information on how to get these files on your local system.</para></listitem> |
90 | <listitem><para><emphasis>Local copies of the <filename>poky-extras</filename> Git Repository:</emphasis> | 90 | <listitem><para><emphasis>Local copies of the <filename>poky-extras</filename> Git Repository:</emphasis> |
91 | This area contains the <filename>meta-kernel-dev</filename> layer, | 91 | This area contains the <filename>meta-kernel-dev</filename> layer, |
92 | which is where you make changes that append the kernel build recipes. | 92 | which is where you make changes that append the kernel build recipes. |
93 | You edit <filename>.bbappend</filename> files to locate your | 93 | You edit <filename>.bbappend</filename> files to locate your |
94 | local kernel source files and to identify the kernel being built. | 94 | local kernel source files and to identify the kernel being built. |
95 | This Git repository is a gathering place for extensions to the Yocto Project | 95 | This Git repository is a gathering place for extensions to the Yocto Project |
96 | (or really any) kernel recipes that faciliate the creation and development | 96 | (or really any) kernel recipes that faciliate the creation and development |
97 | of kernel features, BSPs or configurations.</para> | 97 | of kernel features, BSPs or configurations.</para> |
98 | <para>See the bulleted item | 98 | <para>See the bulleted item |
99 | "<link linkend='poky-extras-repo'>The | 99 | "<link linkend='poky-extras-repo'>The |
100 | <filename>poky-extras</filename> Git Repository</link>" | 100 | <filename>poky-extras</filename> Git Repository</link>" |
101 | for information on how to get these files.</para></listitem> | 101 | for information on how to get these files.</para></listitem> |
102 | <listitem><para><emphasis>Bare Clone of the Yocto Project kernel:</emphasis> | 102 | <listitem><para><emphasis>Bare Clone of the Yocto Project kernel:</emphasis> |
103 | This bare Git repository tracks the upstream Git repository of the Linux | 103 | This bare Git repository tracks the upstream Git repository of the Linux |
104 | Yocto kernel source code you are changing. | 104 | Yocto kernel source code you are changing. |
105 | When you modify the kernel you must work through a bare clone. | 105 | When you modify the kernel you must work through a bare clone. |
106 | All source code changes you make to the kernel must be committed and | 106 | All source code changes you make to the kernel must be committed and |
107 | pushed to the bare clone using Git commands. | 107 | pushed to the bare clone using Git commands. |
108 | As mentioned, the <filename>.bbappend</filename> file in the | 108 | As mentioned, the <filename>.bbappend</filename> file in the |
109 | <filename>poky-extras</filename> repository points to the bare clone | 109 | <filename>poky-extras</filename> repository points to the bare clone |
110 | so that the build process can locate the locally changed source files.</para> | 110 | so that the build process can locate the locally changed source files.</para> |
111 | <para>See the bulleted item | 111 | <para>See the bulleted item |
@@ -113,16 +113,16 @@ | |||
113 | for information on how to set up the bare clone. | 113 | for information on how to set up the bare clone. |
114 | </para></listitem> | 114 | </para></listitem> |
115 | <listitem><para><emphasis>Copy of the Yocto Project Kernel Bare Clone:</emphasis> | 115 | <listitem><para><emphasis>Copy of the Yocto Project Kernel Bare Clone:</emphasis> |
116 | This Git repository contains the actual source files that you modify. | 116 | This Git repository contains the actual source files that you modify. |
117 | Any changes you make to files in this location need to ultimately be pushed | 117 | Any changes you make to files in this location need to ultimately be pushed |
118 | to the bare clone using the <filename>git push</filename> command.</para> | 118 | to the bare clone using the <filename>git push</filename> command.</para> |
119 | <para>See the bulleted item | 119 | <para>See the bulleted item |
120 | "<link linkend='local-kernel-files'>Yocto Project Kernel</link>" | 120 | "<link linkend='local-kernel-files'>Yocto Project Kernel</link>" |
121 | for information on how to set up the bare clone. | 121 | for information on how to set up the bare clone. |
122 | <note>Typically, Git workflows follow a scheme where changes made to a local area | 122 | <note>Typically, Git workflows follow a scheme where changes made to a local area |
123 | are pulled into a Git repository. | 123 | are pulled into a Git repository. |
124 | However, because the <filename>git pull</filename> command does not work | 124 | However, because the <filename>git pull</filename> command does not work |
125 | with bare clones, this workflow pushes changes to the | 125 | with bare clones, this workflow pushes changes to the |
126 | repository even though you could use other more complicated methods to | 126 | repository even though you could use other more complicated methods to |
127 | get changes into the bare clone.</note> | 127 | get changes into the bare clone.</note> |
128 | </para></listitem> | 128 | </para></listitem> |
@@ -134,11 +134,11 @@ | |||
134 | <title>Setting Up the Local Source Directory</title> | 134 | <title>Setting Up the Local Source Directory</title> |
135 | 135 | ||
136 | <para> | 136 | <para> |
137 | You can set up the | 137 | You can set up the |
138 | <link linkend='source-directory'>Source Directory</link> | 138 | <link linkend='source-directory'>Source Directory</link> |
139 | through tarball extraction or by | 139 | through tarball extraction or by |
140 | cloning the <filename>poky</filename> Git repository. | 140 | cloning the <filename>poky</filename> Git repository. |
141 | This example uses <filename>poky</filename> as the root directory of the | 141 | This example uses <filename>poky</filename> as the root directory of the |
142 | local Source Directory. | 142 | local Source Directory. |
143 | See the bulleted item | 143 | See the bulleted item |
144 | "<link linkend='local-yp-release'>Yocto Project Release</link>" | 144 | "<link linkend='local-yp-release'>Yocto Project Release</link>" |
@@ -146,17 +146,17 @@ | |||
146 | </para> | 146 | </para> |
147 | 147 | ||
148 | <para> | 148 | <para> |
149 | Once you have Source Directory set up, | 149 | Once you have Source Directory set up, |
150 | you have many development branches from which you can work. | 150 | you have many development branches from which you can work. |
151 | From inside the local repository you can see the branch names and the tag names used | 151 | From inside the local repository you can see the branch names and the tag names used |
152 | in the upstream Git repository by using either of the following commands: | 152 | in the upstream Git repository by using either of the following commands: |
153 | <literallayout class='monospaced'> | 153 | <literallayout class='monospaced'> |
154 | $ cd poky | 154 | $ cd poky |
155 | $ git branch -a | 155 | $ git branch -a |
156 | $ git tag -l | 156 | $ git tag -l |
157 | </literallayout> | 157 | </literallayout> |
158 | This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;", | 158 | This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;", |
159 | which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository. | 159 | which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository. |
160 | The following commands create and checkout the local <filename>&DISTRO_NAME;</filename> | 160 | The following commands create and checkout the local <filename>&DISTRO_NAME;</filename> |
161 | branch: | 161 | branch: |
162 | <literallayout class='monospaced'> | 162 | <literallayout class='monospaced'> |
@@ -171,20 +171,20 @@ | |||
171 | <title>Setting Up the Local poky-extras Git Repository</title> | 171 | <title>Setting Up the Local poky-extras Git Repository</title> |
172 | 172 | ||
173 | <para> | 173 | <para> |
174 | This example creates a local copy of the <filename>poky-extras</filename> Git | 174 | This example creates a local copy of the <filename>poky-extras</filename> Git |
175 | repository inside the <filename>poky</filename> Source Directory. | 175 | repository inside the <filename>poky</filename> Source Directory. |
176 | See the bulleted item "<link linkend='poky-extras-repo'>The | 176 | See the bulleted item "<link linkend='poky-extras-repo'>The |
177 | <filename>poky-extras</filename> Git Repository</link>" | 177 | <filename>poky-extras</filename> Git Repository</link>" |
178 | for information on how to set up a local copy of the | 178 | for information on how to set up a local copy of the |
179 | <filename>poky-extras</filename> repository. | 179 | <filename>poky-extras</filename> repository. |
180 | </para> | 180 | </para> |
181 | 181 | ||
182 | <para> | 182 | <para> |
183 | Because this example uses the Yocto Project &DISTRO; Release code | 183 | Because this example uses the Yocto Project &DISTRO; Release code |
184 | named "&DISTRO_NAME;", which maps to the <filename>&DISTRO_NAME;</filename> | 184 | named "&DISTRO_NAME;", which maps to the <filename>&DISTRO_NAME;</filename> |
185 | branch in the repository, you need to be sure you are using that | 185 | branch in the repository, you need to be sure you are using that |
186 | branch for <filename>poky-extras</filename>. | 186 | branch for <filename>poky-extras</filename>. |
187 | The following commands create and checkout the local | 187 | The following commands create and checkout the local |
188 | branch you are using for the <filename>&DISTRO_NAME;</filename> | 188 | branch you are using for the <filename>&DISTRO_NAME;</filename> |
189 | branch: | 189 | branch: |
190 | <literallayout class='monospaced'> | 190 | <literallayout class='monospaced'> |
@@ -201,25 +201,25 @@ | |||
201 | 201 | ||
202 | <para> | 202 | <para> |
203 | This example modifies the <filename>linux-yocto-3.4</filename> kernel. | 203 | This example modifies the <filename>linux-yocto-3.4</filename> kernel. |
204 | Thus, you need to create a bare clone of that kernel and then make a copy of the | 204 | Thus, you need to create a bare clone of that kernel and then make a copy of the |
205 | bare clone. | 205 | bare clone. |
206 | See the bulleted item | 206 | See the bulleted item |
207 | "<link linkend='local-kernel-files'>Yocto Project Kernel</link>" | 207 | "<link linkend='local-kernel-files'>Yocto Project Kernel</link>" |
208 | for information on how to do that. | 208 | for information on how to do that. |
209 | </para> | 209 | </para> |
210 | 210 | ||
211 | <para> | 211 | <para> |
212 | The bare clone exists for the kernel build tools and simply as the receiving end | 212 | The bare clone exists for the kernel build tools and simply as the receiving end |
213 | of <filename>git push</filename> | 213 | of <filename>git push</filename> |
214 | commands after you make edits and commits inside the copy of the clone. | 214 | commands after you make edits and commits inside the copy of the clone. |
215 | The copy (<filename>my-linux-yocto-3.4-work</filename> in this example) has to have | 215 | The copy (<filename>my-linux-yocto-3.4-work</filename> in this example) has to have |
216 | a local branch created and checked out for your work. | 216 | a local branch created and checked out for your work. |
217 | This example uses <filename>common-pc-base</filename> as the local branch. | 217 | This example uses <filename>common-pc-base</filename> as the local branch. |
218 | The following commands create and checkout the branch: | 218 | The following commands create and checkout the branch: |
219 | <literallayout class='monospaced'> | 219 | <literallayout class='monospaced'> |
220 | $ cd ~/my-linux-yocto-3.4-work | 220 | $ cd ~/my-linux-yocto-3.4-work |
221 | $ git checkout -b standard-common-pc-base origin/standard/common-pc/base | 221 | $ git checkout -b standard-common-pc-base origin/standard/common-pc/base |
222 | Branch standard-common-pc-base set up to track remote branch | 222 | Branch standard-common-pc-base set up to track remote branch |
223 | standard/common-pc/base from origin. | 223 | standard/common-pc/base from origin. |
224 | Switched to a new branch 'standard-common-pc-base' | 224 | Switched to a new branch 'standard-common-pc-base' |
225 | </literallayout> | 225 | </literallayout> |
@@ -230,22 +230,22 @@ | |||
230 | <title>Building and Booting the Default QEMU Kernel Image</title> | 230 | <title>Building and Booting the Default QEMU Kernel Image</title> |
231 | 231 | ||
232 | <para> | 232 | <para> |
233 | Before we make changes to the kernel source files, this example first builds the | 233 | Before we make changes to the kernel source files, this example first builds the |
234 | default image and then boots it inside the QEMU emulator. | 234 | default image and then boots it inside the QEMU emulator. |
235 | <note> | 235 | <note> |
236 | Because a full build can take hours, you should check two variables in the | 236 | Because a full build can take hours, you should check two variables in the |
237 | <filename>build</filename> directory that is created after you source the | 237 | <filename>build</filename> directory that is created after you source the |
238 | <filename>&OE_INIT_FILE;</filename> script. | 238 | <filename>&OE_INIT_FILE;</filename> script. |
239 | You can find these variables | 239 | You can find these variables |
240 | <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename> | 240 | <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename> |
241 | in the <filename>build/conf</filename> directory in the | 241 | in the <filename>build/conf</filename> directory in the |
242 | <filename>local.conf</filename> configuration file. | 242 | <filename>local.conf</filename> configuration file. |
243 | By default, these variables are commented out. | 243 | By default, these variables are commented out. |
244 | If your host development system supports multi-core and multi-thread capabilities, | 244 | If your host development system supports multi-core and multi-thread capabilities, |
245 | you can uncomment these statements and set the variables to significantly shorten | 245 | you can uncomment these statements and set the variables to significantly shorten |
246 | the full build time. | 246 | the full build time. |
247 | As a guideline, set both <filename>BB_NUMBER_THREADS</filename> and | 247 | As a guideline, set both <filename>BB_NUMBER_THREADS</filename> and |
248 | <filename>PARALLEL_MAKE</filename> to twice the number | 248 | <filename>PARALLEL_MAKE</filename> to twice the number |
249 | of cores your machine supports. | 249 | of cores your machine supports. |
250 | </note> | 250 | </note> |
251 | The following two commands <filename>source</filename> the build environment setup script | 251 | The following two commands <filename>source</filename> the build environment setup script |
@@ -255,9 +255,9 @@ | |||
255 | $ cd ~/poky | 255 | $ cd ~/poky |
256 | $ source &OE_INIT_FILE; | 256 | $ source &OE_INIT_FILE; |
257 | You had no conf/local.conf file. This configuration file has therefore been | 257 | You had no conf/local.conf file. This configuration file has therefore been |
258 | created for you with some default values. You may wish to edit it to use a | 258 | created for you with some default values. You may wish to edit it to use a |
259 | different MACHINE (target hardware) or enable parallel build options to take | 259 | different MACHINE (target hardware) or enable parallel build options to take |
260 | advantage of multiple cores for example. See the file for more information as | 260 | advantage of multiple cores for example. See the file for more information as |
261 | common configuration options are commented. | 261 | common configuration options are commented. |
262 | 262 | ||
263 | The Yocto Project has extensive documentation about OE including a reference manual | 263 | The Yocto Project has extensive documentation about OE including a reference manual |
@@ -305,7 +305,7 @@ | |||
305 | before starting the build.</note> | 305 | before starting the build.</note> |
306 | </para> | 306 | </para> |
307 | 307 | ||
308 | <para> | 308 | <para> |
309 | After the build completes, you can start the QEMU emulator using the resulting image | 309 | After the build completes, you can start the QEMU emulator using the resulting image |
310 | <filename>qemux86</filename> as follows: | 310 | <filename>qemux86</filename> as follows: |
311 | <literallayout class='monospaced'> | 311 | <literallayout class='monospaced'> |
@@ -317,9 +317,9 @@ | |||
317 | As the image boots in the emulator, console message and status output appears | 317 | As the image boots in the emulator, console message and status output appears |
318 | across the terminal window. | 318 | across the terminal window. |
319 | Because the output scrolls by quickly, it is difficult to read. | 319 | Because the output scrolls by quickly, it is difficult to read. |
320 | To examine the output, you log into the system using the | 320 | To examine the output, you log into the system using the |
321 | login <filename>root</filename> with no password. | 321 | login <filename>root</filename> with no password. |
322 | Once you are logged in, issue the following command to scroll through the | 322 | Once you are logged in, issue the following command to scroll through the |
323 | console output: | 323 | console output: |
324 | <literallayout class='monospaced'> | 324 | <literallayout class='monospaced'> |
325 | # dmesg | less | 325 | # dmesg | less |
@@ -360,7 +360,7 @@ | |||
360 | </para> | 360 | </para> |
361 | 361 | ||
362 | <para> | 362 | <para> |
363 | Here is the altered code showing five new <filename>printk</filename> statements | 363 | Here is the altered code showing five new <filename>printk</filename> statements |
364 | near the top of the function: | 364 | near the top of the function: |
365 | <literallayout class='monospaced'> | 365 | <literallayout class='monospaced'> |
366 | void __cpuinit calibrate_delay(void) | 366 | void __cpuinit calibrate_delay(void) |
@@ -392,9 +392,9 @@ | |||
392 | </para> | 392 | </para> |
393 | 393 | ||
394 | <para> | 394 | <para> |
395 | Once the source code has been modified, you need to use Git to push the changes to | 395 | Once the source code has been modified, you need to use Git to push the changes to |
396 | the bare clone. | 396 | the bare clone. |
397 | If you do not push the changes, then the OpenEmbedded build system will not pick | 397 | If you do not push the changes, then the OpenEmbedded build system will not pick |
398 | up the changed source files. | 398 | up the changed source files. |
399 | </para> | 399 | </para> |
400 | 400 | ||
@@ -411,43 +411,43 @@ | |||
411 | 411 | ||
412 | <para> | 412 | <para> |
413 | At this point, the source has been changed and pushed. | 413 | At this point, the source has been changed and pushed. |
414 | The example now defines some variables used by the OpenEmbedded build system | 414 | The example now defines some variables used by the OpenEmbedded build system |
415 | to locate your kernel source. | 415 | to locate your kernel source. |
416 | You essentially need to identify where to find the kernel recipe and the changed source code. | 416 | You essentially need to identify where to find the kernel recipe and the changed source code. |
417 | You also need to be sure some basic configurations are in place that identify the | 417 | You also need to be sure some basic configurations are in place that identify the |
418 | type of machine you are building and to help speed up the build should your host support | 418 | type of machine you are building and to help speed up the build should your host support |
419 | multiple-core and thread capabilities. | 419 | multiple-core and thread capabilities. |
420 | </para> | 420 | </para> |
421 | 421 | ||
422 | <para> | 422 | <para> |
423 | Do the following to make sure the build parameters are set up for the example. | 423 | Do the following to make sure the build parameters are set up for the example. |
424 | Once you set up these build parameters, they do not have to change unless you | 424 | Once you set up these build parameters, they do not have to change unless you |
425 | change the target architecture of the machine you are building or you move | 425 | change the target architecture of the machine you are building or you move |
426 | the bare clone, copy of the clone, or the <filename>poky-extras</filename> repository: | 426 | the bare clone, copy of the clone, or the <filename>poky-extras</filename> repository: |
427 | <itemizedlist> | 427 | <itemizedlist> |
428 | <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The | 428 | <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The |
429 | <filename>local.conf</filename> file in the build directory defines the build's | 429 | <filename>local.conf</filename> file in the build directory defines the build's |
430 | target architecture. | 430 | target architecture. |
431 | By default, <filename>MACHINE</filename> is set to | 431 | By default, <filename>MACHINE</filename> is set to |
432 | <filename>qemux86</filename>, which specifies a 32-bit | 432 | <filename>qemux86</filename>, which specifies a 32-bit |
433 | <trademark class='registered'>Intel</trademark> Architecture | 433 | <trademark class='registered'>Intel</trademark> Architecture |
434 | target machine suitable for the QEMU emulator. | 434 | target machine suitable for the QEMU emulator. |
435 | In this example, <filename>MACHINE</filename> is correctly configured. | 435 | In this example, <filename>MACHINE</filename> is correctly configured. |
436 | </para></listitem> | 436 | </para></listitem> |
437 | <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the | 437 | <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the |
438 | <filename>local.conf</filename> file are two variables that can speed your | 438 | <filename>local.conf</filename> file are two variables that can speed your |
439 | build time if your host supports multi-core and multi-thread capabilities: | 439 | build time if your host supports multi-core and multi-thread capabilities: |
440 | <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>. | 440 | <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>. |
441 | If the host system has multiple cores then you can optimize build time | 441 | If the host system has multiple cores then you can optimize build time |
442 | by setting both these variables to twice the number of | 442 | by setting both these variables to twice the number of |
443 | cores.</para></listitem> | 443 | cores.</para></listitem> |
444 | <listitem><para><emphasis>Identify Your <filename>meta-kernel-dev</filename> | 444 | <listitem><para><emphasis>Identify Your <filename>meta-kernel-dev</filename> |
445 | Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the | 445 | Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the |
446 | <filename>bblayers.conf</filename> file found in the | 446 | <filename>bblayers.conf</filename> file found in the |
447 | <filename>poky/build/conf</filename> directory needs to have the path to your local | 447 | <filename>poky/build/conf</filename> directory needs to have the path to your local |
448 | <filename>meta-kernel-dev</filename> layer. | 448 | <filename>meta-kernel-dev</filename> layer. |
449 | By default, the <filename>BBLAYERS</filename> variable contains paths to | 449 | By default, the <filename>BBLAYERS</filename> variable contains paths to |
450 | <filename>meta</filename> and <filename>meta-yocto</filename> in the | 450 | <filename>meta</filename> and <filename>meta-yocto</filename> in the |
451 | <filename>poky</filename> Git repository. | 451 | <filename>poky</filename> Git repository. |
452 | Add the path to your <filename>meta-kernel-dev</filename> location. | 452 | Add the path to your <filename>meta-kernel-dev</filename> location. |
453 | Be sure to substitute your user information in the statement. | 453 | Be sure to substitute your user information in the statement. |
@@ -460,14 +460,14 @@ | |||
460 | /home/scottrif/poky/poky-extras/meta-kernel-dev \ | 460 | /home/scottrif/poky/poky-extras/meta-kernel-dev \ |
461 | " | 461 | " |
462 | </literallayout></para></listitem> | 462 | </literallayout></para></listitem> |
463 | <listitem><para><emphasis>Identify Your Source Files:</emphasis> In the | 463 | <listitem><para><emphasis>Identify Your Source Files:</emphasis> In the |
464 | <filename>linux-yocto_3.4.bbappend</filename> file located in the | 464 | <filename>linux-yocto_3.4.bbappend</filename> file located in the |
465 | <filename>poky-extras/meta-kernel-dev/recipes-kernel/linux</filename> | 465 | <filename>poky-extras/meta-kernel-dev/recipes-kernel/linux</filename> |
466 | directory, you need to identify the location of the | 466 | directory, you need to identify the location of the |
467 | local source code, which in this example is the bare clone named | 467 | local source code, which in this example is the bare clone named |
468 | <filename>linux-yocto-3.4.git</filename>. | 468 | <filename>linux-yocto-3.4.git</filename>. |
469 | To do this, set the <filename>KSRC_linux_yocto</filename> variable to point to your | 469 | To do this, set the <filename>KSRC_linux_yocto</filename> variable to point to your |
470 | local <filename>linux-yocto-3.4.git</filename> Git repository by adding the | 470 | local <filename>linux-yocto-3.4.git</filename> Git repository by adding the |
471 | following statement. | 471 | following statement. |
472 | Also, be sure the <filename>SRC_URI</filename> variable is pointing to | 472 | Also, be sure the <filename>SRC_URI</filename> variable is pointing to |
473 | your kernel source files by removing the comment. | 473 | your kernel source files by removing the comment. |
@@ -480,20 +480,20 @@ | |||
480 | </para> | 480 | </para> |
481 | 481 | ||
482 | <note> | 482 | <note> |
483 | <para>Before attempting to build the modified kernel, there is one more set of changes you | 483 | <para>Before attempting to build the modified kernel, there is one more set of changes you |
484 | need to make in the <filename>meta-kernel-dev</filename> layer. | 484 | need to make in the <filename>meta-kernel-dev</filename> layer. |
485 | Because all the kernel <filename>.bbappend</filename> files are parsed during the | 485 | Because all the kernel <filename>.bbappend</filename> files are parsed during the |
486 | build process regardless of whether you are using them or not, you should either | 486 | build process regardless of whether you are using them or not, you should either |
487 | comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all | 487 | comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all |
488 | unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files | 488 | unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files |
489 | except the one your are using for the build | 489 | except the one your are using for the build |
490 | (i.e. <filename>linux-yocto_3.4.bbappend</filename> in this example).</para> | 490 | (i.e. <filename>linux-yocto_3.4.bbappend</filename> in this example).</para> |
491 | <para>If you do not make one of these two adjustments, your machine will be compatible | 491 | <para>If you do not make one of these two adjustments, your machine will be compatible |
492 | with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer. | 492 | with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer. |
493 | When your machine is comapatible with all the kernel recipes, the build attempts | 493 | When your machine is comapatible with all the kernel recipes, the build attempts |
494 | to build all kernels in the layer. | 494 | to build all kernels in the layer. |
495 | You could end up with build errors blocking your work.</para> | 495 | You could end up with build errors blocking your work.</para> |
496 | </note> | 496 | </note> |
497 | </section> | 497 | </section> |
498 | 498 | ||
499 | <section id='building-and-booting-the-modified-qemu-kernel-image'> | 499 | <section id='building-and-booting-the-modified-qemu-kernel-image'> |
@@ -511,7 +511,7 @@ | |||
511 | $ source &OE_INIT_FILE; | 511 | $ source &OE_INIT_FILE; |
512 | </literallayout> | 512 | </literallayout> |
513 | </para></listitem> | 513 | </para></listitem> |
514 | <listitem><para>Be sure old images are cleaned out by running the | 514 | <listitem><para>Be sure old images are cleaned out by running the |
515 | <filename>cleanall</filename> BitBake task as follows from your build directory: | 515 | <filename>cleanall</filename> BitBake task as follows from your build directory: |
516 | <literallayout class='monospaced'> | 516 | <literallayout class='monospaced'> |
517 | $ bitbake -c cleanall linux-yocto | 517 | $ bitbake -c cleanall linux-yocto |
@@ -524,7 +524,7 @@ | |||
524 | <literallayout class='monospaced'> | 524 | <literallayout class='monospaced'> |
525 | $ bitbake -k core-image-minimal | 525 | $ bitbake -k core-image-minimal |
526 | </literallayout></para></listitem> | 526 | </literallayout></para></listitem> |
527 | <listitem><para>Finally, boot the modified image in the QEMU emulator | 527 | <listitem><para>Finally, boot the modified image in the QEMU emulator |
528 | using this command: | 528 | using this command: |
529 | <literallayout class='monospaced'> | 529 | <literallayout class='monospaced'> |
530 | $ runqemu qemux86 | 530 | $ runqemu qemux86 |
@@ -533,7 +533,7 @@ | |||
533 | </para> | 533 | </para> |
534 | 534 | ||
535 | <para> | 535 | <para> |
536 | Log into the machine using <filename>root</filename> with no password and then | 536 | Log into the machine using <filename>root</filename> with no password and then |
537 | use the following shell command to scroll through the console's boot output. | 537 | use the following shell command to scroll through the console's boot output. |
538 | <literallayout class='monospaced'> | 538 | <literallayout class='monospaced'> |
539 | # dmesg | less | 539 | # dmesg | less |
@@ -541,7 +541,7 @@ | |||
541 | </para> | 541 | </para> |
542 | 542 | ||
543 | <para> | 543 | <para> |
544 | You should see the results of your <filename>printk</filename> statements | 544 | You should see the results of your <filename>printk</filename> statements |
545 | as part of the output. | 545 | as part of the output. |
546 | </para> | 546 | </para> |
547 | </section> | 547 | </section> |
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 3ec9eae37b..442cab3036 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml | |||
@@ -7,41 +7,41 @@ | |||
7 | <title>Common Development Models</title> | 7 | <title>Common Development Models</title> |
8 | 8 | ||
9 | <para> | 9 | <para> |
10 | Many development models exist for which you can use the Yocto Project. | 10 | Many development models exist for which you can use the Yocto Project. |
11 | This chapter overviews simple methods that use tools provided by the | 11 | This chapter overviews simple methods that use tools provided by the |
12 | Yocto Project: | 12 | Yocto Project: |
13 | <itemizedlist> | 13 | <itemizedlist> |
14 | <listitem><para><emphasis>System Development:</emphasis> | 14 | <listitem><para><emphasis>System Development:</emphasis> |
15 | System Development covers Board Support Package (BSP) development and kernel | 15 | System Development covers Board Support Package (BSP) development and kernel |
16 | modification or configuration. | 16 | modification or configuration. |
17 | For an example on how to create a BSP, see the | 17 | For an example on how to create a BSP, see the |
18 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" | 18 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" |
19 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. | 19 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. |
20 | </para></listitem> | 20 | </para></listitem> |
21 | <listitem><para><emphasis>User Application Development:</emphasis> | 21 | <listitem><para><emphasis>User Application Development:</emphasis> |
22 | User Application Development covers development of applications that you intend | 22 | User Application Development covers development of applications that you intend |
23 | to run on some target hardware. | 23 | to run on some target hardware. |
24 | For information on how to set up your host development system for user-space | 24 | For information on how to set up your host development system for user-space |
25 | application development, see the | 25 | application development, see the |
26 | <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>. | 26 | <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>. |
27 | For a simple example of user-space application development using the | 27 | For a simple example of user-space application development using the |
28 | <trademark class='trade'>Eclipse</trademark> IDE, see the | 28 | <trademark class='trade'>Eclipse</trademark> IDE, see the |
29 | "<link linkend='application-development-workflow'>Application | 29 | "<link linkend='application-development-workflow'>Application |
30 | Development Workflow</link>" section. | 30 | Development Workflow</link>" section. |
31 | </para></listitem> | 31 | </para></listitem> |
32 | <listitem><para><emphasis>Temporary Source Code Modification:</emphasis> | 32 | <listitem><para><emphasis>Temporary Source Code Modification:</emphasis> |
33 | Direct modification of temporary source code is a convenient development model | 33 | Direct modification of temporary source code is a convenient development model |
34 | to quickly iterate and develop towards a solution. | 34 | to quickly iterate and develop towards a solution. |
35 | Once the solution has been implemented, you should of course take steps to | 35 | Once the solution has been implemented, you should of course take steps to |
36 | get the changes upstream and applied in the affected recipes.</para></listitem> | 36 | get the changes upstream and applied in the affected recipes.</para></listitem> |
37 | <listitem><para><emphasis>Image Development using Hob:</emphasis> | 37 | <listitem><para><emphasis>Image Development using Hob:</emphasis> |
38 | You can use the <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build | 38 | You can use the <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build |
39 | custom operating system images within the build environment. | 39 | custom operating system images within the build environment. |
40 | Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem> | 40 | Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem> |
41 | <listitem><para><emphasis>Using a Development Shell:</emphasis> | 41 | <listitem><para><emphasis>Using a Development Shell:</emphasis> |
42 | You can use a <filename>devshell</filename> to efficiently debug commands or simply | 42 | You can use a <filename>devshell</filename> to efficiently debug commands or simply |
43 | edit packages. | 43 | edit packages. |
44 | Working inside a development shell is a quick way to set up the OpenEmbedded build | 44 | Working inside a development shell is a quick way to set up the OpenEmbedded build |
45 | environment to work on parts of a project.</para></listitem> | 45 | environment to work on parts of a project.</para></listitem> |
46 | </itemizedlist> | 46 | </itemizedlist> |
47 | </para> | 47 | </para> |
@@ -50,17 +50,17 @@ | |||
50 | <title>System Development Workflow</title> | 50 | <title>System Development Workflow</title> |
51 | 51 | ||
52 | <para> | 52 | <para> |
53 | System development involves modification or creation of an image that you want to run on | 53 | System development involves modification or creation of an image that you want to run on |
54 | a specific hardware target. | 54 | a specific hardware target. |
55 | Usually, when you want to create an image that runs on embedded hardware, the image does | 55 | Usually, when you want to create an image that runs on embedded hardware, the image does |
56 | not require the same number of features that a full-fledged Linux distribution provides. | 56 | not require the same number of features that a full-fledged Linux distribution provides. |
57 | Thus, you can create a much smaller image that is designed to use only the | 57 | Thus, you can create a much smaller image that is designed to use only the |
58 | features for your particular hardware. | 58 | features for your particular hardware. |
59 | </para> | 59 | </para> |
60 | 60 | ||
61 | <para> | 61 | <para> |
62 | To help you understand how system development works in the Yocto Project, this section | 62 | To help you understand how system development works in the Yocto Project, this section |
63 | covers two types of image development: BSP creation and kernel modification or | 63 | covers two types of image development: BSP creation and kernel modification or |
64 | configuration. | 64 | configuration. |
65 | </para> | 65 | </para> |
66 | 66 | ||
@@ -68,19 +68,19 @@ | |||
68 | <title>Developing a Board Support Package (BSP)</title> | 68 | <title>Developing a Board Support Package (BSP)</title> |
69 | 69 | ||
70 | <para> | 70 | <para> |
71 | A BSP is a package of recipes that, when applied during a build, results in | 71 | A BSP is a package of recipes that, when applied during a build, results in |
72 | an image that you can run on a particular board. | 72 | an image that you can run on a particular board. |
73 | Thus, the package when compiled into the new image, supports the operation of the board. | 73 | Thus, the package when compiled into the new image, supports the operation of the board. |
74 | </para> | 74 | </para> |
75 | 75 | ||
76 | <note> | 76 | <note> |
77 | For a brief list of terms used when describing the development process in the Yocto Project, | 77 | For a brief list of terms used when describing the development process in the Yocto Project, |
78 | see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section. | 78 | see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section. |
79 | </note> | 79 | </note> |
80 | 80 | ||
81 | <para> | 81 | <para> |
82 | The remainder of this section presents the basic steps used to create a BSP | 82 | The remainder of this section presents the basic steps used to create a BSP |
83 | using the Yocto Project's | 83 | using the Yocto Project's |
84 | <ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>BSP Tools</ulink>. | 84 | <ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>BSP Tools</ulink>. |
85 | For an example that shows how to create a new layer using the tools, see the | 85 | For an example that shows how to create a new layer using the tools, see the |
86 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" | 86 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" |
@@ -97,73 +97,73 @@ | |||
97 | 97 | ||
98 | <para> | 98 | <para> |
99 | <orderedlist> | 99 | <orderedlist> |
100 | <listitem><para><emphasis>Set up your host development system to support | 100 | <listitem><para><emphasis>Set up your host development system to support |
101 | development using the Yocto Project</emphasis>: See the | 101 | development using the Yocto Project</emphasis>: See the |
102 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" | 102 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" |
103 | and the | 103 | and the |
104 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both | 104 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both |
105 | in the Yocto Project Quick Start for requirements.</para></listitem> | 105 | in the Yocto Project Quick Start for requirements.</para></listitem> |
106 | <listitem><para><emphasis>Establish a local copy of the project files on your | 106 | <listitem><para><emphasis>Establish a local copy of the project files on your |
107 | system</emphasis>: You need this <link linkend='source-directory'>Source | 107 | system</emphasis>: You need this <link linkend='source-directory'>Source |
108 | Directory</link> available on your host system. | 108 | Directory</link> available on your host system. |
109 | Having these files on your system gives you access to the build | 109 | Having these files on your system gives you access to the build |
110 | process and to the tools you need. | 110 | process and to the tools you need. |
111 | For information on how to set up the | 111 | For information on how to set up the |
112 | <link linkend='source-directory'>Source Directory</link>, see the | 112 | <link linkend='source-directory'>Source Directory</link>, see the |
113 | "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> | 113 | "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> |
114 | <listitem><para><emphasis>Establish the <filename>meta-intel</filename> | 114 | <listitem><para><emphasis>Establish the <filename>meta-intel</filename> |
115 | repository on your system</emphasis>: Having local copies of the | 115 | repository on your system</emphasis>: Having local copies of the |
116 | supported BSP layers on your system gives you access to the build | 116 | supported BSP layers on your system gives you access to the build |
117 | process and to the tools you need for creating a BSP. | 117 | process and to the tools you need for creating a BSP. |
118 | For information on how to get these files, see the | 118 | For information on how to get these files, see the |
119 | "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> | 119 | "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> |
120 | <listitem><para><emphasis>Create your own BSP layer using the | 120 | <listitem><para><emphasis>Create your own BSP layer using the |
121 | <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>: | 121 | <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>: |
122 | Layers are ideal for | 122 | Layers are ideal for |
123 | isolating and storing work for a given piece of hardware. | 123 | isolating and storing work for a given piece of hardware. |
124 | A layer is really just a location or area in which you place the recipes for your BSP. | 124 | A layer is really just a location or area in which you place the recipes for your BSP. |
125 | In fact, a BSP is, in itself, a special type of layer. | 125 | In fact, a BSP is, in itself, a special type of layer. |
126 | The simplest way to create a new BSP layer that is compliant with the | 126 | The simplest way to create a new BSP layer that is compliant with the |
127 | Yocto Project is to use the <filename>yocto-bsp</filename> script. | 127 | Yocto Project is to use the <filename>yocto-bsp</filename> script. |
128 | For information about that script, see the | 128 | For information about that script, see the |
129 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" | 129 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" |
130 | section in the Yocto Project Board Support (BSP) Developer's Guide. | 130 | section in the Yocto Project Board Support (BSP) Developer's Guide. |
131 | </para> | 131 | </para> |
132 | <para> | 132 | <para> |
133 | Another example that illustrates a layer is an application. | 133 | Another example that illustrates a layer is an application. |
134 | Suppose you are creating an application that has library or other dependencies in | 134 | Suppose you are creating an application that has library or other dependencies in |
135 | order for it to compile and run. | 135 | order for it to compile and run. |
136 | The layer, in this case, would be where all the recipes that define those dependencies | 136 | The layer, in this case, would be where all the recipes that define those dependencies |
137 | are kept. | 137 | are kept. |
138 | The key point for a layer is that it is an isolated area that contains | 138 | The key point for a layer is that it is an isolated area that contains |
139 | all the relevant information for the project that the OpenEmbedded build | 139 | all the relevant information for the project that the OpenEmbedded build |
140 | system knows about. | 140 | system knows about. |
141 | For more information on layers, see the | 141 | For more information on layers, see the |
142 | "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" | 142 | "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" |
143 | section. | 143 | section. |
144 | For more information on BSP layers, see the | 144 | For more information on BSP layers, see the |
145 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the | 145 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the |
146 | Yocto Project Board Support Package (BSP) Developer's Guide.</para> | 146 | Yocto Project Board Support Package (BSP) Developer's Guide.</para> |
147 | <note>Four BSPs exist that are part of the | 147 | <note>Four BSPs exist that are part of the |
148 | Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>, | 148 | Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>, |
149 | <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>. | 149 | <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>. |
150 | The recipes and configurations for these four BSPs are located and dispersed | 150 | The recipes and configurations for these four BSPs are located and dispersed |
151 | within the <link linkend='source-directory'>Source Directory</link>. | 151 | within the <link linkend='source-directory'>Source Directory</link>. |
152 | On the other hand, BSP layers for Cedar Trail, Chief River, Crown Bay, | 152 | On the other hand, BSP layers for Cedar Trail, Chief River, Crown Bay, |
153 | Crystal Forest, Emenlow, Fish River, Fish River 2, Jasper Forest, N450, | 153 | Crystal Forest, Emenlow, Fish River, Fish River 2, Jasper Forest, N450, |
154 | Romley, sys940x, Sugar Bay, and tlk exist in their own separate layers | 154 | Romley, sys940x, Sugar Bay, and tlk exist in their own separate layers |
155 | within the larger <filename>meta-intel</filename> layer.</note> | 155 | within the larger <filename>meta-intel</filename> layer.</note> |
156 | <para>When you set up a layer for a new BSP, you should follow a standard layout. | 156 | <para>When you set up a layer for a new BSP, you should follow a standard layout. |
157 | This layout is described in the section | 157 | This layout is described in the section |
158 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>" | 158 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>" |
159 | section of the Board Support Package (BSP) Development Guide. | 159 | section of the Board Support Package (BSP) Development Guide. |
160 | In the standard layout, you will notice a suggested structure for recipes and | 160 | In the standard layout, you will notice a suggested structure for recipes and |
161 | configuration information. | 161 | configuration information. |
162 | You can see the standard layout for a BSP by examining | 162 | You can see the standard layout for a BSP by examining |
163 | any supported BSP found in the <filename>meta-intel</filename> layer inside | 163 | any supported BSP found in the <filename>meta-intel</filename> layer inside |
164 | the Source Directory.</para></listitem> | 164 | the Source Directory.</para></listitem> |
165 | <listitem><para><emphasis>Make configuration changes to your new BSP | 165 | <listitem><para><emphasis>Make configuration changes to your new BSP |
166 | layer</emphasis>: The standard BSP layer structure organizes the files you need | 166 | layer</emphasis>: The standard BSP layer structure organizes the files you need |
167 | to edit in <filename>conf</filename> and several <filename>recipes-*</filename> | 167 | to edit in <filename>conf</filename> and several <filename>recipes-*</filename> |
168 | directories within the BSP layer. | 168 | directories within the BSP layer. |
169 | Configuration changes identify where your new layer is on the local system | 169 | Configuration changes identify where your new layer is on the local system |
@@ -171,46 +171,46 @@ | |||
171 | When you run the <filename>yocto-bsp</filename> script you are able to interactively | 171 | When you run the <filename>yocto-bsp</filename> script you are able to interactively |
172 | configure many things for the BSP (e.g. keyboard, touchscreen, and so forth). | 172 | configure many things for the BSP (e.g. keyboard, touchscreen, and so forth). |
173 | </para></listitem> | 173 | </para></listitem> |
174 | <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe | 174 | <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe |
175 | changes include altering recipes (<filename>.bb</filename> files), removing | 175 | changes include altering recipes (<filename>.bb</filename> files), removing |
176 | recipes you don't use, and adding new recipes or append files | 176 | recipes you don't use, and adding new recipes or append files |
177 | (<filename>.bbappend</filename>) that you need to support your hardware. | 177 | (<filename>.bbappend</filename>) that you need to support your hardware. |
178 | </para></listitem> | 178 | </para></listitem> |
179 | <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the | 179 | <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the |
180 | changes to your BSP layer, there remains a few things | 180 | changes to your BSP layer, there remains a few things |
181 | you need to do for the OpenEmbedded build system in order for it to create your image. | 181 | you need to do for the OpenEmbedded build system in order for it to create your image. |
182 | You need to get the build environment ready by sourcing an environment setup script | 182 | You need to get the build environment ready by sourcing an environment setup script |
183 | and you need to be sure two key configuration files are configured appropriately: | 183 | and you need to be sure two key configuration files are configured appropriately: |
184 | the <filename>conf/local.conf</filename> and the | 184 | the <filename>conf/local.conf</filename> and the |
185 | <filename>conf/bblayers.conf</filename> file. | 185 | <filename>conf/bblayers.conf</filename> file. |
186 | You must make the OpenEmbedded build system aware of your new layer. | 186 | You must make the OpenEmbedded build system aware of your new layer. |
187 | See the | 187 | See the |
188 | "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section | 188 | "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section |
189 | for information on how to let the build system know about your new layer.</para> | 189 | for information on how to let the build system know about your new layer.</para> |
190 | <para>The entire process for building an image is overviewed in the section | 190 | <para>The entire process for building an image is overviewed in the section |
191 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section | 191 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section |
192 | of the Yocto Project Quick Start. | 192 | of the Yocto Project Quick Start. |
193 | You might want to reference this information.</para></listitem> | 193 | You might want to reference this information.</para></listitem> |
194 | <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system | 194 | <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system |
195 | uses the BitBake tool to build images based on the type of image you want to create. | 195 | uses the BitBake tool to build images based on the type of image you want to create. |
196 | You can find more information about BitBake in the user manual, which is found in the | 196 | You can find more information about BitBake in the user manual, which is found in the |
197 | <filename>bitbake/doc/manual</filename> directory of the | 197 | <filename>bitbake/doc/manual</filename> directory of the |
198 | <link linkend='source-directory'>Source Directory</link>.</para> | 198 | <link linkend='source-directory'>Source Directory</link>.</para> |
199 | <para>The build process supports several types of images to satisfy different needs. | 199 | <para>The build process supports several types of images to satisfy different needs. |
200 | See the | 200 | See the |
201 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter | 201 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter |
202 | in the Yocto Project Reference Manual for information on | 202 | in the Yocto Project Reference Manual for information on |
203 | supported images.</para></listitem> | 203 | supported images.</para></listitem> |
204 | </orderedlist> | 204 | </orderedlist> |
205 | </para> | 205 | </para> |
206 | 206 | ||
207 | <para> | 207 | <para> |
208 | You can view a video presentation on "Building Custom Embedded Images with Yocto" | 208 | You can view a video presentation on "Building Custom Embedded Images with Yocto" |
209 | at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>. | 209 | at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>. |
210 | You can also find supplemental information in | 210 | You can also find supplemental information in |
211 | <ulink url='&YOCTO_DOCS_BSP_URL;'> | 211 | <ulink url='&YOCTO_DOCS_BSP_URL;'> |
212 | The Board Support Package (BSP) Development Guide</ulink>. | 212 | The Board Support Package (BSP) Development Guide</ulink>. |
213 | Finally, there is wiki page write up of the example also located | 213 | Finally, there is wiki page write up of the example also located |
214 | <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'> | 214 | <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'> |
215 | here</ulink> that you might find helpful. | 215 | here</ulink> that you might find helpful. |
216 | </para> | 216 | </para> |
@@ -221,7 +221,7 @@ | |||
221 | 221 | ||
222 | <para> | 222 | <para> |
223 | Kernel modification involves changing the Yocto Project kernel, which could involve changing | 223 | Kernel modification involves changing the Yocto Project kernel, which could involve changing |
224 | configuration options as well as adding new kernel recipes. | 224 | configuration options as well as adding new kernel recipes. |
225 | Configuration changes can be added in the form of configuration fragments, while recipe | 225 | Configuration changes can be added in the form of configuration fragments, while recipe |
226 | modification comes through the kernel's <filename>recipes-kernel</filename> area | 226 | modification comes through the kernel's <filename>recipes-kernel</filename> area |
227 | in a kernel layer you create. | 227 | in a kernel layer you create. |
@@ -232,10 +232,10 @@ | |||
232 | kernel architecture and the steps to modify the kernel. | 232 | kernel architecture and the steps to modify the kernel. |
233 | For a complete discussion of the kernel, see the | 233 | For a complete discussion of the kernel, see the |
234 | <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>. | 234 | <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>. |
235 | You can reference the | 235 | You can reference the |
236 | "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section | 236 | "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section |
237 | for an example that changes the source code of the kernel. | 237 | for an example that changes the source code of the kernel. |
238 | For information on how to configure the kernel, see the | 238 | For information on how to configure the kernel, see the |
239 | "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section. | 239 | "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section. |
240 | </para> | 240 | </para> |
241 | 241 | ||
@@ -253,25 +253,25 @@ | |||
253 | <para> | 253 | <para> |
254 | You can find a web interface to the Yocto Project kernel source repositories at | 254 | You can find a web interface to the Yocto Project kernel source repositories at |
255 | <ulink url='&YOCTO_GIT_URL;'></ulink>. | 255 | <ulink url='&YOCTO_GIT_URL;'></ulink>. |
256 | If you look at the interface, you will see to the left a grouping of | 256 | If you look at the interface, you will see to the left a grouping of |
257 | Git repositories titled "Yocto Linux Kernel." | 257 | Git repositories titled "Yocto Linux Kernel." |
258 | Within this group, you will find several kernels supported by | 258 | Within this group, you will find several kernels supported by |
259 | the Yocto Project: | 259 | the Yocto Project: |
260 | <itemizedlist> | 260 | <itemizedlist> |
261 | <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The | 261 | <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The |
262 | stable Yocto Project kernel that is based on the Linux 2.6.34 released kernel.</para></listitem> | 262 | stable Yocto Project kernel that is based on the Linux 2.6.34 released kernel.</para></listitem> |
263 | <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The | 263 | <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The |
264 | stable Yocto Project kernel that is based on the Linux 2.6.37 released kernel.</para></listitem> | 264 | stable Yocto Project kernel that is based on the Linux 2.6.37 released kernel.</para></listitem> |
265 | <listitem><para><emphasis><filename>linux-yocto-3.0</filename></emphasis> - The stable | 265 | <listitem><para><emphasis><filename>linux-yocto-3.0</filename></emphasis> - The stable |
266 | Yocto Project kernel that is based on the Linux 3.0 released kernel.</para></listitem> | 266 | Yocto Project kernel that is based on the Linux 3.0 released kernel.</para></listitem> |
267 | <listitem><para><emphasis><filename>linux-yocto-3.0-1.1.x</filename></emphasis> - The | 267 | <listitem><para><emphasis><filename>linux-yocto-3.0-1.1.x</filename></emphasis> - The |
268 | stable Yocto Project kernel to use with the Yocto Project Release 1.1.x. This kernel | 268 | stable Yocto Project kernel to use with the Yocto Project Release 1.1.x. This kernel |
269 | is based on the Linux 3.0 released kernel.</para></listitem> | 269 | is based on the Linux 3.0 released kernel.</para></listitem> |
270 | <listitem><para><emphasis><filename>linux-yocto-3.2</filename></emphasis> - The | 270 | <listitem><para><emphasis><filename>linux-yocto-3.2</filename></emphasis> - The |
271 | stable Yocto Project kernel to use with the Yocto Project Release 1.2. This kernel | 271 | stable Yocto Project kernel to use with the Yocto Project Release 1.2. This kernel |
272 | is based on the Linux 3.2 released kernel.</para></listitem> | 272 | is based on the Linux 3.2 released kernel.</para></listitem> |
273 | <listitem><para><emphasis><filename>linux-yocto-3.4</filename></emphasis> - The | 273 | <listitem><para><emphasis><filename>linux-yocto-3.4</filename></emphasis> - The |
274 | stable Yocto Project kernel to use with the Yocto Project Release 1.3. This kernel | 274 | stable Yocto Project kernel to use with the Yocto Project Release 1.3. This kernel |
275 | is based on the Linux 3.4 released kernel.</para></listitem> | 275 | is based on the Linux 3.4 released kernel.</para></listitem> |
276 | <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development | 276 | <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development |
277 | kernel based on the latest upstream release candidate available.</para></listitem> | 277 | kernel based on the latest upstream release candidate available.</para></listitem> |
@@ -282,24 +282,24 @@ | |||
282 | The kernels are maintained using the Git revision control system | 282 | The kernels are maintained using the Git revision control system |
283 | that structures them using the familiar "tree", "branch", and "leaf" scheme. | 283 | that structures them using the familiar "tree", "branch", and "leaf" scheme. |
284 | Branches represent diversions from general code to more specific code, while leaves | 284 | Branches represent diversions from general code to more specific code, while leaves |
285 | represent the end-points for a complete and unique kernel whose source files | 285 | represent the end-points for a complete and unique kernel whose source files |
286 | when gathered from the root of the tree to the leaf accumulate to create the files | 286 | when gathered from the root of the tree to the leaf accumulate to create the files |
287 | necessary for a specific piece of hardware and its features. | 287 | necessary for a specific piece of hardware and its features. |
288 | The following figure displays this concept: | 288 | The following figure displays this concept: |
289 | <para> | 289 | <para> |
290 | <imagedata fileref="figures/kernel-overview-1.png" | 290 | <imagedata fileref="figures/kernel-overview-1.png" |
291 | width="6in" depth="6in" align="center" scale="100" /> | 291 | width="6in" depth="6in" align="center" scale="100" /> |
292 | </para> | 292 | </para> |
293 | 293 | ||
294 | <para> | 294 | <para> |
295 | Within the figure, the "Kernel.org Branch Point" represents the point in the tree | 295 | Within the figure, the "Kernel.org Branch Point" represents the point in the tree |
296 | where a supported base kernel is modified from the Linux kernel. | 296 | where a supported base kernel is modified from the Linux kernel. |
297 | For example, this could be the branch point for the <filename>linux-yocto-3.0</filename> | 297 | For example, this could be the branch point for the <filename>linux-yocto-3.0</filename> |
298 | kernel. | 298 | kernel. |
299 | Thus, everything further to the right in the structure is based on the | 299 | Thus, everything further to the right in the structure is based on the |
300 | <filename>linux-yocto-3.0</filename> kernel. | 300 | <filename>linux-yocto-3.0</filename> kernel. |
301 | Branch points to right in the figure represent where the | 301 | Branch points to right in the figure represent where the |
302 | <filename>linux-yocto-3.0</filename> kernel is modified for specific hardware | 302 | <filename>linux-yocto-3.0</filename> kernel is modified for specific hardware |
303 | or types of kernels, such as real-time kernels. | 303 | or types of kernels, such as real-time kernels. |
304 | Each leaf thus represents the end-point for a kernel designed to run on a specific | 304 | Each leaf thus represents the end-point for a kernel designed to run on a specific |
305 | targeted device. | 305 | targeted device. |
@@ -308,26 +308,26 @@ | |||
308 | <para> | 308 | <para> |
309 | The overall result is a Git-maintained repository from which all the supported | 309 | The overall result is a Git-maintained repository from which all the supported |
310 | kernel types can be derived for all the supported devices. | 310 | kernel types can be derived for all the supported devices. |
311 | A big advantage to this scheme is the sharing of common features by keeping them in | 311 | A big advantage to this scheme is the sharing of common features by keeping them in |
312 | "larger" branches within the tree. | 312 | "larger" branches within the tree. |
313 | This practice eliminates redundant storage of similar features shared among kernels. | 313 | This practice eliminates redundant storage of similar features shared among kernels. |
314 | </para> | 314 | </para> |
315 | 315 | ||
316 | <note> | 316 | <note> |
317 | Keep in mind the figure does not take into account all the supported Yocto | 317 | Keep in mind the figure does not take into account all the supported Yocto |
318 | Project kernel types, but rather shows a single generic kernel just for conceptual purposes. | 318 | Project kernel types, but rather shows a single generic kernel just for conceptual purposes. |
319 | Also keep in mind that this structure represents the Yocto Project source repositories | 319 | Also keep in mind that this structure represents the Yocto Project source repositories |
320 | that are either pulled from during the build or established on the host development system | 320 | that are either pulled from during the build or established on the host development system |
321 | prior to the build by either cloning a particular kernel's Git repository or by | 321 | prior to the build by either cloning a particular kernel's Git repository or by |
322 | downloading and unpacking a tarball. | 322 | downloading and unpacking a tarball. |
323 | </note> | 323 | </note> |
324 | 324 | ||
325 | <para> | 325 | <para> |
326 | Upstream storage of all the available kernel source code is one thing, while | 326 | Upstream storage of all the available kernel source code is one thing, while |
327 | representing and using the code on your host development system is another. | 327 | representing and using the code on your host development system is another. |
328 | Conceptually, you can think of the kernel source repositories as all the | 328 | Conceptually, you can think of the kernel source repositories as all the |
329 | source files necessary for all the supported kernels. | 329 | source files necessary for all the supported kernels. |
330 | As a developer, you are just interested in the source files for the kernel on | 330 | As a developer, you are just interested in the source files for the kernel on |
331 | on which you are working. | 331 | on which you are working. |
332 | And, furthermore, you need them available on your host system. | 332 | And, furthermore, you need them available on your host system. |
333 | </para> | 333 | </para> |
@@ -337,43 +337,43 @@ | |||
337 | ways. | 337 | ways. |
338 | If you are working in the kernel all the time, you probably would want | 338 | If you are working in the kernel all the time, you probably would want |
339 | to set up your own local Git repository of the kernel tree. | 339 | to set up your own local Git repository of the kernel tree. |
340 | If you just need to make some patches to the kernel, you can get at | 340 | If you just need to make some patches to the kernel, you can get at |
341 | temporary kernel source files extracted and used during the OpenEmbedded | 341 | temporary kernel source files extracted and used during the OpenEmbedded |
342 | build system. | 342 | build system. |
343 | We will just talk about working with the temporary source code. | 343 | We will just talk about working with the temporary source code. |
344 | </para> | 344 | </para> |
345 | 345 | ||
346 | <para> | 346 | <para> |
347 | What happens during the build? | 347 | What happens during the build? |
348 | When you build the kernel on your development system, all files needed for the build | 348 | When you build the kernel on your development system, all files needed for the build |
349 | are taken from the source repositories pointed to by the | 349 | are taken from the source repositories pointed to by the |
350 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable | 350 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable |
351 | and gathered in a temporary work area | 351 | and gathered in a temporary work area |
352 | where they are subsequently used to create the unique kernel. | 352 | where they are subsequently used to create the unique kernel. |
353 | Thus, in a sense, the process constructs a local source tree specific to your | 353 | Thus, in a sense, the process constructs a local source tree specific to your |
354 | kernel to generate the new kernel image - a source generator if you will. | 354 | kernel to generate the new kernel image - a source generator if you will. |
355 | </para> | 355 | </para> |
356 | The following figure shows the temporary file structure | 356 | The following figure shows the temporary file structure |
357 | created on your host system when the build occurs. | 357 | created on your host system when the build occurs. |
358 | This | 358 | This |
359 | <link linkend='build-directory'>Build Directory</link> contains all the | 359 | <link linkend='build-directory'>Build Directory</link> contains all the |
360 | source files used during the build. | 360 | source files used during the build. |
361 | </para> | 361 | </para> |
362 | 362 | ||
363 | <para> | 363 | <para> |
364 | <imagedata fileref="figures/kernel-overview-2-generic.png" | 364 | <imagedata fileref="figures/kernel-overview-2-generic.png" |
365 | width="6in" depth="5in" align="center" scale="100" /> | 365 | width="6in" depth="5in" align="center" scale="100" /> |
366 | </para> | 366 | </para> |
367 | 367 | ||
368 | <para> | 368 | <para> |
369 | Again, for a complete discussion of the Yocto Project kernel's architecture and its | 369 | Again, for a complete discussion of the Yocto Project kernel's architecture and its |
370 | branching strategy, see the | 370 | branching strategy, see the |
371 | <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>. | 371 | <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>. |
372 | You can also reference the | 372 | You can also reference the |
373 | "<link linkend='patching-the-kernel'>Patching the Kernel</link>" | 373 | "<link linkend='patching-the-kernel'>Patching the Kernel</link>" |
374 | section for a detailed example that modifies the kernel. | 374 | section for a detailed example that modifies the kernel. |
375 | </para> | 375 | </para> |
376 | </section> | 376 | </section> |
377 | 377 | ||
378 | <section id='kernel-modification-workflow'> | 378 | <section id='kernel-modification-workflow'> |
379 | <title>Kernel Modification Workflow</title> | 379 | <title>Kernel Modification Workflow</title> |
@@ -383,73 +383,73 @@ | |||
383 | </para> | 383 | </para> |
384 | 384 | ||
385 | <para> | 385 | <para> |
386 | <imagedata fileref="figures/kernel-dev-flow.png" | 386 | <imagedata fileref="figures/kernel-dev-flow.png" |
387 | width="6in" depth="5in" align="center" scalefit="1" /> | 387 | width="6in" depth="5in" align="center" scalefit="1" /> |
388 | </para> | 388 | </para> |
389 | 389 | ||
390 | <para> | 390 | <para> |
391 | <orderedlist> | 391 | <orderedlist> |
392 | <listitem><para><emphasis>Set up your host development system to support | 392 | <listitem><para><emphasis>Set up your host development system to support |
393 | development using the Yocto Project</emphasis>: See | 393 | development using the Yocto Project</emphasis>: See |
394 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and | 394 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and |
395 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both | 395 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both |
396 | in the Yocto Project Quick Start for requirements.</para></listitem> | 396 | in the Yocto Project Quick Start for requirements.</para></listitem> |
397 | <listitem><para><emphasis>Establish a local copy of project files on your | 397 | <listitem><para><emphasis>Establish a local copy of project files on your |
398 | system</emphasis>: Having the <link linkend='source-directory'>Source | 398 | system</emphasis>: Having the <link linkend='source-directory'>Source |
399 | Directory</link> on your system gives you access to the build process and tools | 399 | Directory</link> on your system gives you access to the build process and tools |
400 | you need. | 400 | you need. |
401 | For information on how to get these files, see the bulleted item | 401 | For information on how to get these files, see the bulleted item |
402 | "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual. | 402 | "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual. |
403 | </para></listitem> | 403 | </para></listitem> |
404 | <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>: | 404 | <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>: |
405 | Temporary kernel source files are kept in the Build Directory created by the | 405 | Temporary kernel source files are kept in the Build Directory created by the |
406 | OpenEmbedded build system when you run BitBake. | 406 | OpenEmbedded build system when you run BitBake. |
407 | If you have never built the kernel you are interested in, you need to run | 407 | If you have never built the kernel you are interested in, you need to run |
408 | an initial build to establish local kernel source files.</para> | 408 | an initial build to establish local kernel source files.</para> |
409 | <para>If you are building an image for the first time, you need to get the build | 409 | <para>If you are building an image for the first time, you need to get the build |
410 | environment ready by sourcing | 410 | environment ready by sourcing |
411 | the environment setup script. | 411 | the environment setup script. |
412 | You also need to be sure two key configuration files | 412 | You also need to be sure two key configuration files |
413 | (<filename>local.conf</filename> and <filename>bblayers.conf</filename>) | 413 | (<filename>local.conf</filename> and <filename>bblayers.conf</filename>) |
414 | are configured appropriately.</para> | 414 | are configured appropriately.</para> |
415 | <para>The entire process for building an image is overviewed in the | 415 | <para>The entire process for building an image is overviewed in the |
416 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | 416 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" |
417 | section of the Yocto Project Quick Start. | 417 | section of the Yocto Project Quick Start. |
418 | You might want to reference this information. | 418 | You might want to reference this information. |
419 | You can find more information on BitBake in the user manual, which is found in the | 419 | You can find more information on BitBake in the user manual, which is found in the |
420 | <filename>bitbake/doc/manual</filename> directory of the | 420 | <filename>bitbake/doc/manual</filename> directory of the |
421 | <link linkend='source-directory'>Source Directory</link>.</para> | 421 | <link linkend='source-directory'>Source Directory</link>.</para> |
422 | <para>The build process supports several types of images to satisfy different needs. | 422 | <para>The build process supports several types of images to satisfy different needs. |
423 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in | 423 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in |
424 | the Yocto Project Reference Manual for information on supported images. | 424 | the Yocto Project Reference Manual for information on supported images. |
425 | </para></listitem> | 425 | </para></listitem> |
426 | <listitem><para><emphasis>Make changes to the kernel source code if | 426 | <listitem><para><emphasis>Make changes to the kernel source code if |
427 | applicable</emphasis>: Modifying the kernel does not always mean directly | 427 | applicable</emphasis>: Modifying the kernel does not always mean directly |
428 | changing source files. | 428 | changing source files. |
429 | However, if you have to do this, you make the changes to the files in the | 429 | However, if you have to do this, you make the changes to the files in the |
430 | Build directory.</para></listitem> | 430 | Build directory.</para></listitem> |
431 | <listitem><para><emphasis>Make kernel configuration changes | 431 | <listitem><para><emphasis>Make kernel configuration changes |
432 | if applicable</emphasis>: | 432 | if applicable</emphasis>: |
433 | If your situation calls for changing the kernel's configuration, you can | 433 | If your situation calls for changing the kernel's configuration, you can |
434 | use the <filename>yocto-kernel</filename> script or <filename>menuconfig</filename> | 434 | use the <filename>yocto-kernel</filename> script or <filename>menuconfig</filename> |
435 | to enable and disable kernel configurations. | 435 | to enable and disable kernel configurations. |
436 | Using the script lets you interactively set up kernel configurations. | 436 | Using the script lets you interactively set up kernel configurations. |
437 | Using <filename>menuconfig</filename> allows you to interactively develop and test the | 437 | Using <filename>menuconfig</filename> allows you to interactively develop and test the |
438 | configuration changes you are making to the kernel. | 438 | configuration changes you are making to the kernel. |
439 | When saved, changes using <filename>menuconfig</filename> update the kernel's | 439 | When saved, changes using <filename>menuconfig</filename> update the kernel's |
440 | <filename>.config</filename>. | 440 | <filename>.config</filename>. |
441 | Try to resist the temptation of directly editing the <filename>.config</filename> | 441 | Try to resist the temptation of directly editing the <filename>.config</filename> |
442 | file found in the | 442 | file found in the |
443 | <link linkend='build-directory'>Build Directory</link> at | 443 | <link linkend='build-directory'>Build Directory</link> at |
444 | <filename>tmp/sysroots/<machine-name>/kernel</filename>. | 444 | <filename>tmp/sysroots/<machine-name>/kernel</filename>. |
445 | Doing so, can produce unexpected results when the OpenEmbedded build system | 445 | Doing so, can produce unexpected results when the OpenEmbedded build system |
446 | regenerates the configuration file.</para> | 446 | regenerates the configuration file.</para> |
447 | <para>Once you are satisfied with the configuration changes made using | 447 | <para>Once you are satisfied with the configuration changes made using |
448 | <filename>menuconfig</filename>, you can directly examine the | 448 | <filename>menuconfig</filename>, you can directly examine the |
449 | <filename>.config</filename> file against a saved original and gather those | 449 | <filename>.config</filename> file against a saved original and gather those |
450 | changes into a config fragment to be referenced from within the kernel's | 450 | changes into a config fragment to be referenced from within the kernel's |
451 | <filename>.bbappend</filename> file.</para></listitem> | 451 | <filename>.bbappend</filename> file.</para></listitem> |
452 | <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>: | 452 | <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>: |
453 | Rebuilding the kernel image applies your changes.</para></listitem> | 453 | Rebuilding the kernel image applies your changes.</para></listitem> |
454 | </orderedlist> | 454 | </orderedlist> |
455 | </para> | 455 | </para> |
@@ -461,23 +461,23 @@ | |||
461 | <title>Application Development Workflow</title> | 461 | <title>Application Development Workflow</title> |
462 | 462 | ||
463 | <para> | 463 | <para> |
464 | Application development involves creating an application that you want | 464 | Application development involves creating an application that you want |
465 | to run on your target hardware, which is running a kernel image created using the | 465 | to run on your target hardware, which is running a kernel image created using the |
466 | OpenEmbedded build system. | 466 | OpenEmbedded build system. |
467 | The Yocto Project provides an Application Development Toolkit (ADT) and | 467 | The Yocto Project provides an Application Development Toolkit (ADT) and |
468 | stand-alone cross-development toolchains that | 468 | stand-alone cross-development toolchains that |
469 | facilitate quick development and integration of your application into its run-time environment. | 469 | facilitate quick development and integration of your application into its run-time environment. |
470 | Using the ADT and toolchains, you can compile and link your application. | 470 | Using the ADT and toolchains, you can compile and link your application. |
471 | You can then deploy your application to the actual hardware or to the QEMU emulator for testing. | 471 | You can then deploy your application to the actual hardware or to the QEMU emulator for testing. |
472 | If you are familiar with the popular <trademark class='trade'>Eclipse</trademark> IDE, | 472 | If you are familiar with the popular <trademark class='trade'>Eclipse</trademark> IDE, |
473 | you can use an Eclipse Yocto Plug-in to | 473 | you can use an Eclipse Yocto Plug-in to |
474 | allow you to develop, deploy, and test your application all from within Eclipse. | 474 | allow you to develop, deploy, and test your application all from within Eclipse. |
475 | </para> | 475 | </para> |
476 | 476 | ||
477 | <para> | 477 | <para> |
478 | While we strongly suggest using the ADT to develop your application, this option might not | 478 | While we strongly suggest using the ADT to develop your application, this option might not |
479 | be best for you. | 479 | be best for you. |
480 | If this is the case, you can still use pieces of the Yocto Project for your development process. | 480 | If this is the case, you can still use pieces of the Yocto Project for your development process. |
481 | However, because the process can vary greatly, this manual does not provide detail on the process. | 481 | However, because the process can vary greatly, this manual does not provide detail on the process. |
482 | </para> | 482 | </para> |
483 | 483 | ||
@@ -485,8 +485,8 @@ | |||
485 | <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title> | 485 | <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title> |
486 | 486 | ||
487 | <para> | 487 | <para> |
488 | To help you understand how application development works using the ADT, this section | 488 | To help you understand how application development works using the ADT, this section |
489 | provides an overview of the general development process and a detailed example of the process | 489 | provides an overview of the general development process and a detailed example of the process |
490 | as it is used from within the Eclipse IDE. | 490 | as it is used from within the Eclipse IDE. |
491 | </para> | 491 | </para> |
492 | 492 | ||
@@ -495,94 +495,94 @@ | |||
495 | </para> | 495 | </para> |
496 | 496 | ||
497 | <para> | 497 | <para> |
498 | <imagedata fileref="figures/app-dev-flow.png" | 498 | <imagedata fileref="figures/app-dev-flow.png" |
499 | width="7in" depth="8in" align="center" scale="100" /> | 499 | width="7in" depth="8in" align="center" scale="100" /> |
500 | </para> | 500 | </para> |
501 | 501 | ||
502 | <para> | 502 | <para> |
503 | <orderedlist> | 503 | <orderedlist> |
504 | <listitem><para><emphasis>Prepare the Host System for the Yocto Project</emphasis>: | 504 | <listitem><para><emphasis>Prepare the Host System for the Yocto Project</emphasis>: |
505 | See | 505 | See |
506 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and | 506 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and |
507 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both | 507 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both |
508 | in the Yocto Project Quick Start for requirements.</para></listitem> | 508 | in the Yocto Project Quick Start for requirements.</para></listitem> |
509 | <listitem><para><emphasis>Secure the Yocto Project Kernel Target Image</emphasis>: | 509 | <listitem><para><emphasis>Secure the Yocto Project Kernel Target Image</emphasis>: |
510 | You must have a target kernel image that has been built using the OpenEmbeded | 510 | You must have a target kernel image that has been built using the OpenEmbeded |
511 | build system.</para> | 511 | build system.</para> |
512 | <para>Depending on whether the Yocto Project has a pre-built image that matches your target | 512 | <para>Depending on whether the Yocto Project has a pre-built image that matches your target |
513 | architecture and where you are going to run the image while you develop your application | 513 | architecture and where you are going to run the image while you develop your application |
514 | (QEMU or real hardware), the area from which you get the image differs. | 514 | (QEMU or real hardware), the area from which you get the image differs. |
515 | <itemizedlist> | 515 | <itemizedlist> |
516 | <listitem><para>Download the image from | 516 | <listitem><para>Download the image from |
517 | <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> | 517 | <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> |
518 | if your target architecture is supported and you are going to develop | 518 | if your target architecture is supported and you are going to develop |
519 | and test your application on actual hardware.</para></listitem> | 519 | and test your application on actual hardware.</para></listitem> |
520 | <listitem><para>Download the image from the | 520 | <listitem><para>Download the image from the |
521 | <ulink url='&YOCTO_QEMU_DL_URL;'> | 521 | <ulink url='&YOCTO_QEMU_DL_URL;'> |
522 | <filename>machines/qemu</filename></ulink> if your target architecture is supported | 522 | <filename>machines/qemu</filename></ulink> if your target architecture is supported |
523 | and you are going to develop and test your application using the QEMU | 523 | and you are going to develop and test your application using the QEMU |
524 | emulator.</para></listitem> | 524 | emulator.</para></listitem> |
525 | <listitem><para>Build your image if you cannot find a pre-built image that matches | 525 | <listitem><para>Build your image if you cannot find a pre-built image that matches |
526 | your target architecture. | 526 | your target architecture. |
527 | If your target architecture is similar to a supported architecture, you can | 527 | If your target architecture is similar to a supported architecture, you can |
528 | modify the kernel image before you build it. | 528 | modify the kernel image before you build it. |
529 | See the | 529 | See the |
530 | "<link linkend='patching-the-kernel'>Patching the Kernel</link>" | 530 | "<link linkend='patching-the-kernel'>Patching the Kernel</link>" |
531 | section for an example.</para></listitem> | 531 | section for an example.</para></listitem> |
532 | </itemizedlist></para> | 532 | </itemizedlist></para> |
533 | <para>For information on pre-built kernel image naming schemes for images | 533 | <para>For information on pre-built kernel image naming schemes for images |
534 | that can run on the QEMU emulator, see the | 534 | that can run on the QEMU emulator, see the |
535 | "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>" | 535 | "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>" |
536 | section in the Yocto Project Quick Start.</para></listitem> | 536 | section in the Yocto Project Quick Start.</para></listitem> |
537 | <listitem><para><emphasis>Install the ADT</emphasis>: | 537 | <listitem><para><emphasis>Install the ADT</emphasis>: |
538 | The ADT provides a target-specific cross-development toolchain, the root filesystem, | 538 | The ADT provides a target-specific cross-development toolchain, the root filesystem, |
539 | the QEMU emulator, and other tools that can help you develop your application. | 539 | the QEMU emulator, and other tools that can help you develop your application. |
540 | While it is possible to get these pieces separately, the ADT Installer provides an | 540 | While it is possible to get these pieces separately, the ADT Installer provides an |
541 | easy method. | 541 | easy method. |
542 | You can get these pieces by running an ADT installer script, which is configurable. | 542 | You can get these pieces by running an ADT installer script, which is configurable. |
543 | For information on how to install the ADT, see the | 543 | For information on how to install the ADT, see the |
544 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>" | 544 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>" |
545 | section | 545 | section |
546 | in the Yocto Project Application Developer's Guide.</para></listitem> | 546 | in the Yocto Project Application Developer's Guide.</para></listitem> |
547 | <listitem><para><emphasis>If Applicable, Secure the Target Root Filesystem | 547 | <listitem><para><emphasis>If Applicable, Secure the Target Root Filesystem |
548 | and the Cross-development Toolchain</emphasis>: | 548 | and the Cross-development Toolchain</emphasis>: |
549 | If you choose not to install the ADT using the ADT Installer, | 549 | If you choose not to install the ADT using the ADT Installer, |
550 | you need to find and download the appropriate root filesystem and | 550 | you need to find and download the appropriate root filesystem and |
551 | the cross-development toolchain.</para> | 551 | the cross-development toolchain.</para> |
552 | <para>You can find the tarballs for the root filesystem in the same area used | 552 | <para>You can find the tarballs for the root filesystem in the same area used |
553 | for the kernel image. | 553 | for the kernel image. |
554 | Depending on the type of image you are running, the root filesystem you need differs. | 554 | Depending on the type of image you are running, the root filesystem you need differs. |
555 | For example, if you are developing an application that runs on an image that | 555 | For example, if you are developing an application that runs on an image that |
556 | supports Sato, you need to get root filesystem that supports Sato.</para> | 556 | supports Sato, you need to get root filesystem that supports Sato.</para> |
557 | <para>You can find the cross-development toolchains at | 557 | <para>You can find the cross-development toolchains at |
558 | <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>. | 558 | <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>. |
559 | Be sure to get the correct toolchain for your development host and your | 559 | Be sure to get the correct toolchain for your development host and your |
560 | target architecture. | 560 | target architecture. |
561 | See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" | 561 | See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" |
562 | section in the Yocto Project Application Developer's Guide for information | 562 | section in the Yocto Project Application Developer's Guide for information |
563 | and the | 563 | and the |
564 | "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>" | 564 | "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>" |
565 | in the Yocto Project Quick Start for information on finding and installing | 565 | in the Yocto Project Quick Start for information on finding and installing |
566 | the correct toolchain based on your host development system and your target | 566 | the correct toolchain based on your host development system and your target |
567 | architecture. | 567 | architecture. |
568 | </para></listitem> | 568 | </para></listitem> |
569 | <listitem><para><emphasis>Create and Build your Application</emphasis>: | 569 | <listitem><para><emphasis>Create and Build your Application</emphasis>: |
570 | At this point, you need to have source files for your application. | 570 | At this point, you need to have source files for your application. |
571 | Once you have the files, you can use the Eclipse IDE to import them and build the | 571 | Once you have the files, you can use the Eclipse IDE to import them and build the |
572 | project. | 572 | project. |
573 | If you are not using Eclipse, you need to use the cross-development tools you have | 573 | If you are not using Eclipse, you need to use the cross-development tools you have |
574 | installed to create the image.</para></listitem> | 574 | installed to create the image.</para></listitem> |
575 | <listitem><para><emphasis>Deploy the Image with the Application</emphasis>: | 575 | <listitem><para><emphasis>Deploy the Image with the Application</emphasis>: |
576 | If you are using the Eclipse IDE, you can deploy your image to the hardware or to | 576 | If you are using the Eclipse IDE, you can deploy your image to the hardware or to |
577 | QEMU through the project's preferences. | 577 | QEMU through the project's preferences. |
578 | If you are not using the Eclipse IDE, then you need to deploy the application | 578 | If you are not using the Eclipse IDE, then you need to deploy the application |
579 | to the hardware using other methods. | 579 | to the hardware using other methods. |
580 | Or, if you are using QEMU, you need to use that tool and load your image in for testing. | 580 | Or, if you are using QEMU, you need to use that tool and load your image in for testing. |
581 | </para></listitem> | 581 | </para></listitem> |
582 | <listitem><para><emphasis>Test and Debug the Application</emphasis>: | 582 | <listitem><para><emphasis>Test and Debug the Application</emphasis>: |
583 | Once your application is deployed, you need to test it. | 583 | Once your application is deployed, you need to test it. |
584 | Within the Eclipse IDE, you can use the debugging environment along with the | 584 | Within the Eclipse IDE, you can use the debugging environment along with the |
585 | set of user-space tools installed along with the ADT to debug your application. | 585 | set of user-space tools installed along with the ADT to debug your application. |
586 | Of course, the same user-space tools are available separately if you choose | 586 | Of course, the same user-space tools are available separately if you choose |
587 | not to use the Eclipse IDE.</para></listitem> | 587 | not to use the Eclipse IDE.</para></listitem> |
588 | </orderedlist> | 588 | </orderedlist> |
@@ -593,7 +593,7 @@ | |||
593 | <title>Working Within Eclipse</title> | 593 | <title>Working Within Eclipse</title> |
594 | 594 | ||
595 | <para> | 595 | <para> |
596 | The Eclipse IDE is a popular development environment and it fully supports | 596 | The Eclipse IDE is a popular development environment and it fully supports |
597 | development using the Yocto Project. | 597 | development using the Yocto Project. |
598 | <note>This release of the Yocto Project supports both the Juno and Indigo versions | 598 | <note>This release of the Yocto Project supports both the Juno and Indigo versions |
599 | of the Eclipse IDE. | 599 | of the Eclipse IDE. |
@@ -601,21 +601,21 @@ | |||
601 | </note> | 601 | </note> |
602 | </para> | 602 | </para> |
603 | 603 | ||
604 | <para> | 604 | <para> |
605 | When you install and configure the Eclipse Yocto Project Plug-in into | 605 | When you install and configure the Eclipse Yocto Project Plug-in into |
606 | the Eclipse IDE, you maximize your Yocto Project experience. | 606 | the Eclipse IDE, you maximize your Yocto Project experience. |
607 | Installing and configuring the Plug-in results in an environment that | 607 | Installing and configuring the Plug-in results in an environment that |
608 | has extensions specifically designed to let you more easily develop software. | 608 | has extensions specifically designed to let you more easily develop software. |
609 | These extensions allow for cross-compilation, deployment, and execution of | 609 | These extensions allow for cross-compilation, deployment, and execution of |
610 | your output into a QEMU emulation session. | 610 | your output into a QEMU emulation session. |
611 | You can also perform cross-debugging and profiling. | 611 | You can also perform cross-debugging and profiling. |
612 | The environment also supports a suite of tools that allows you to perform | 612 | The environment also supports a suite of tools that allows you to perform |
613 | remote profiling, tracing, collection of power data, collection of | 613 | remote profiling, tracing, collection of power data, collection of |
614 | latency data, and collection of performance data. | 614 | latency data, and collection of performance data. |
615 | </para> | 615 | </para> |
616 | 616 | ||
617 | <para> | 617 | <para> |
618 | This section describes how to install and configure the Eclipse IDE | 618 | This section describes how to install and configure the Eclipse IDE |
619 | Yocto Plug-in and how to use it to develop your application. | 619 | Yocto Plug-in and how to use it to develop your application. |
620 | </para> | 620 | </para> |
621 | 621 | ||
@@ -641,10 +641,10 @@ | |||
641 | <title>Installing the Eclipse IDE</title> | 641 | <title>Installing the Eclipse IDE</title> |
642 | 642 | ||
643 | <para> | 643 | <para> |
644 | It is recommended that you have the Juno 4.2 version of the | 644 | It is recommended that you have the Juno 4.2 version of the |
645 | Eclipse IDE installed on your development system. | 645 | Eclipse IDE installed on your development system. |
646 | However, if you currently have the Indigo 3.7.2 version installed and you do | 646 | However, if you currently have the Indigo 3.7.2 version installed and you do |
647 | not want to upgrade the IDE, you can configure Indigo to work with the | 647 | not want to upgrade the IDE, you can configure Indigo to work with the |
648 | Yocto Project. | 648 | Yocto Project. |
649 | See the | 649 | See the |
650 | "<link linkend='configuring-the-eclipse-ide-indigo'>Configuring the Eclipse IDE (Indigo)</link>" | 650 | "<link linkend='configuring-the-eclipse-ide-indigo'>Configuring the Eclipse IDE (Indigo)</link>" |
@@ -652,19 +652,19 @@ | |||
652 | </para> | 652 | </para> |
653 | 653 | ||
654 | <para> | 654 | <para> |
655 | If you don’t have the Juno 4.2 Eclipse IDE installed, you can find the tarball at | 655 | If you don’t have the Juno 4.2 Eclipse IDE installed, you can find the tarball at |
656 | <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. | 656 | <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. |
657 | From that site, choose the Eclipse Classic version particular to your development | 657 | From that site, choose the Eclipse Classic version particular to your development |
658 | host. | 658 | host. |
659 | This version contains the Eclipse Platform, the Java Development | 659 | This version contains the Eclipse Platform, the Java Development |
660 | Tools (JDT), and the Plug-in Development Environment. | 660 | Tools (JDT), and the Plug-in Development Environment. |
661 | </para> | 661 | </para> |
662 | 662 | ||
663 | <para> | 663 | <para> |
664 | Once you have downloaded the tarball, extract it into a clean | 664 | Once you have downloaded the tarball, extract it into a clean |
665 | directory. | 665 | directory. |
666 | For example, the following commands unpack and install the | 666 | For example, the following commands unpack and install the |
667 | downloaded Eclipse IDE tarball into a clean directory | 667 | downloaded Eclipse IDE tarball into a clean directory |
668 | using the default name <filename>eclipse</filename>: | 668 | using the default name <filename>eclipse</filename>: |
669 | <literallayout class='monospaced'> | 669 | <literallayout class='monospaced'> |
670 | $ cd ~ | 670 | $ cd ~ |
@@ -674,12 +674,12 @@ | |||
674 | 674 | ||
675 | <para> | 675 | <para> |
676 | If you have the Indigo 3.7.2 Eclipse IDE already installed and you want to use that | 676 | If you have the Indigo 3.7.2 Eclipse IDE already installed and you want to use that |
677 | version, one issue exists that you need to be aware of regarding the Java | 677 | version, one issue exists that you need to be aware of regarding the Java |
678 | Virtual machine’s garbage collection (GC) process. | 678 | Virtual machine’s garbage collection (GC) process. |
679 | The GC process does not clean up the permanent generation | 679 | The GC process does not clean up the permanent generation |
680 | space (PermGen). | 680 | space (PermGen). |
681 | This space stores metadata descriptions of classes. | 681 | This space stores metadata descriptions of classes. |
682 | The default value is set too small and it could trigger an | 682 | The default value is set too small and it could trigger an |
683 | out-of-memory error such as the following: | 683 | out-of-memory error such as the following: |
684 | <literallayout class='monospaced'> | 684 | <literallayout class='monospaced'> |
685 | Java.lang.OutOfMemoryError: PermGen space | 685 | Java.lang.OutOfMemoryError: PermGen space |
@@ -692,7 +692,7 @@ | |||
692 | 692 | ||
693 | <para> | 693 | <para> |
694 | To fix this issue, you can use the <filename>--vmargs</filename> | 694 | To fix this issue, you can use the <filename>--vmargs</filename> |
695 | option when you start the Indigo 3.7.2 Eclipse IDE | 695 | option when you start the Indigo 3.7.2 Eclipse IDE |
696 | to increase the size of the permanent generation space: | 696 | to increase the size of the permanent generation space: |
697 | <literallayout class='monospaced'> | 697 | <literallayout class='monospaced'> |
698 | eclipse --vmargs --XX:PermSize=256M | 698 | eclipse --vmargs --XX:PermSize=256M |
@@ -705,24 +705,24 @@ | |||
705 | 705 | ||
706 | <para> | 706 | <para> |
707 | This section presents the steps needed to configure the Juno 4.2 Eclipse IDE. | 707 | This section presents the steps needed to configure the Juno 4.2 Eclipse IDE. |
708 | If you are using Indigo 3.7.2, see the | 708 | If you are using Indigo 3.7.2, see the |
709 | "<link linkend='configuring-the-eclipse-ide-indigo'>Configuring the Eclipse IDE (Indigo)</link>". | 709 | "<link linkend='configuring-the-eclipse-ide-indigo'>Configuring the Eclipse IDE (Indigo)</link>". |
710 | </para> | 710 | </para> |
711 | 711 | ||
712 | <para> | 712 | <para> |
713 | Before installing and configuring the Eclipse Yocto Plug-in, you need to configure | 713 | Before installing and configuring the Eclipse Yocto Plug-in, you need to configure |
714 | the Juno 4.2 Eclipse IDE. | 714 | the Juno 4.2 Eclipse IDE. |
715 | Follow these general steps: | 715 | Follow these general steps: |
716 | <orderedlist> | 716 | <orderedlist> |
717 | <listitem><para>Start the Eclipse IDE.</para></listitem> | 717 | <listitem><para>Start the Eclipse IDE.</para></listitem> |
718 | <listitem><para>Make sure you are in your Workbench and select | 718 | <listitem><para>Make sure you are in your Workbench and select |
719 | "Install New Software" from the "Help" pull-down menu. | 719 | "Install New Software" from the "Help" pull-down menu. |
720 | </para></listitem> | 720 | </para></listitem> |
721 | <listitem><para>Select <filename>Juno - &ECLIPSE_JUNO_URL;</filename> | 721 | <listitem><para>Select <filename>Juno - &ECLIPSE_JUNO_URL;</filename> |
722 | from the "Work with:" pull-down menu.</para></listitem> | 722 | from the "Work with:" pull-down menu.</para></listitem> |
723 | <listitem><para>Expand the box next to "Linux Tools" and select the | 723 | <listitem><para>Expand the box next to "Linux Tools" and select the |
724 | "LTTng - Linux Tracing Toolkit" boxes.</para></listitem> | 724 | "LTTng - Linux Tracing Toolkit" boxes.</para></listitem> |
725 | <listitem><para>Expand the box next to "Mobile and Device Development" and select the | 725 | <listitem><para>Expand the box next to "Mobile and Device Development" and select the |
726 | following boxes: | 726 | following boxes: |
727 | <itemizedlist> | 727 | <itemizedlist> |
728 | <listitem><para><filename>C/C++ Remote Launch</filename></para></listitem> | 728 | <listitem><para><filename>C/C++ Remote Launch</filename></para></listitem> |
@@ -745,17 +745,17 @@ | |||
745 | 745 | ||
746 | <para> | 746 | <para> |
747 | This section presents the steps needed to configure the Indigo 3.7.2 Eclipse IDE. | 747 | This section presents the steps needed to configure the Indigo 3.7.2 Eclipse IDE. |
748 | If you are using Juno 4.2, see the | 748 | If you are using Juno 4.2, see the |
749 | "<link linkend='configuring-the-eclipse-ide-juno'>Configuring the Eclipse IDE (Juno)</link>". | 749 | "<link linkend='configuring-the-eclipse-ide-juno'>Configuring the Eclipse IDE (Juno)</link>". |
750 | </para> | 750 | </para> |
751 | 751 | ||
752 | <para> | 752 | <para> |
753 | Before installing and configuring the Eclipse Yocto Plug-in, you need to configure | 753 | Before installing and configuring the Eclipse Yocto Plug-in, you need to configure |
754 | the Indigo 3.7.2 Eclipse IDE. | 754 | the Indigo 3.7.2 Eclipse IDE. |
755 | Follow these general steps: | 755 | Follow these general steps: |
756 | <orderedlist> | 756 | <orderedlist> |
757 | <listitem><para>Start the Eclipse IDE.</para></listitem> | 757 | <listitem><para>Start the Eclipse IDE.</para></listitem> |
758 | <listitem><para>Make sure you are in your Workbench and select | 758 | <listitem><para>Make sure you are in your Workbench and select |
759 | "Install New Software" from the "Help" pull-down menu. | 759 | "Install New Software" from the "Help" pull-down menu. |
760 | </para></listitem> | 760 | </para></listitem> |
761 | <listitem><para>Select <filename>indigo - &ECLIPSE_INDIGO_URL;</filename> | 761 | <listitem><para>Select <filename>indigo - &ECLIPSE_INDIGO_URL;</filename> |
@@ -763,14 +763,14 @@ | |||
763 | <listitem><para>Expand the box next to <filename>Programming Languages</filename> | 763 | <listitem><para>Expand the box next to <filename>Programming Languages</filename> |
764 | and select the <filename>Autotools Support for CDT (incubation)</filename> | 764 | and select the <filename>Autotools Support for CDT (incubation)</filename> |
765 | and <filename>C/C++ Development Tools</filename> boxes.</para></listitem> | 765 | and <filename>C/C++ Development Tools</filename> boxes.</para></listitem> |
766 | <listitem><para>Expand the box next to "Linux Tools" and select the | 766 | <listitem><para>Expand the box next to "Linux Tools" and select the |
767 | "LTTng - Linux Tracing Toolkit(incubation)" boxes.</para></listitem> | 767 | "LTTng - Linux Tracing Toolkit(incubation)" boxes.</para></listitem> |
768 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> | 768 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> |
769 | <listitem><para>After the Eclipse IDE restarts and from the Workbench, select | 769 | <listitem><para>After the Eclipse IDE restarts and from the Workbench, select |
770 | "Install New Software" from the "Help" pull-down menu.</para></listitem> | 770 | "Install New Software" from the "Help" pull-down menu.</para></listitem> |
771 | <listitem><para>Click the | 771 | <listitem><para>Click the |
772 | "Available Software Sites" link.</para></listitem> | 772 | "Available Software Sites" link.</para></listitem> |
773 | <listitem><para>Check the box next to | 773 | <listitem><para>Check the box next to |
774 | <filename>&ECLIPSE_UPDATES_URL;</filename> | 774 | <filename>&ECLIPSE_UPDATES_URL;</filename> |
775 | and click "OK".</para></listitem> | 775 | and click "OK".</para></listitem> |
776 | <listitem><para>Select <filename>&ECLIPSE_UPDATES_URL;</filename> | 776 | <listitem><para>Select <filename>&ECLIPSE_UPDATES_URL;</filename> |
@@ -778,13 +778,13 @@ | |||
778 | <listitem><para>Check the box next to <filename>TM and RSE Main Features</filename>. | 778 | <listitem><para>Check the box next to <filename>TM and RSE Main Features</filename>. |
779 | </para></listitem> | 779 | </para></listitem> |
780 | <listitem><para>Expand the box next to <filename>TM and RSE Optional Add-ons</filename> | 780 | <listitem><para>Expand the box next to <filename>TM and RSE Optional Add-ons</filename> |
781 | and select every item except <filename>RSE Unit Tests</filename> and | 781 | and select every item except <filename>RSE Unit Tests</filename> and |
782 | <filename>RSE WinCE Services (incubation)</filename>.</para></listitem> | 782 | <filename>RSE WinCE Services (incubation)</filename>.</para></listitem> |
783 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> | 783 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> |
784 | <listitem><para>If necessary, select | 784 | <listitem><para>If necessary, select |
785 | "Install New Software" from the "Help" pull-down menu so you can click the | 785 | "Install New Software" from the "Help" pull-down menu so you can click the |
786 | "Available Software Sites" link again.</para></listitem> | 786 | "Available Software Sites" link again.</para></listitem> |
787 | <listitem><para>After clicking "Available Software Sites", check the box next to | 787 | <listitem><para>After clicking "Available Software Sites", check the box next to |
788 | <filename>http://download.eclipse.org/tools/cdt/releases/indigo</filename> | 788 | <filename>http://download.eclipse.org/tools/cdt/releases/indigo</filename> |
789 | and click "OK".</para></listitem> | 789 | and click "OK".</para></listitem> |
790 | <listitem><para>Select <filename>&ECLIPSE_INDIGO_CDT_URL;</filename> | 790 | <listitem><para>Select <filename>&ECLIPSE_INDIGO_CDT_URL;</filename> |
@@ -792,7 +792,7 @@ | |||
792 | <listitem><para>Check the box next to <filename>CDT Main Features</filename>. | 792 | <listitem><para>Check the box next to <filename>CDT Main Features</filename>. |
793 | </para></listitem> | 793 | </para></listitem> |
794 | <listitem><para>Expand the box next to <filename>CDT Optional Features</filename> | 794 | <listitem><para>Expand the box next to <filename>CDT Optional Features</filename> |
795 | and select <filename>C/C++ Remote Launch</filename> and | 795 | and select <filename>C/C++ Remote Launch</filename> and |
796 | <filename>Target Communication Framework (incubation)</filename>.</para></listitem> | 796 | <filename>Target Communication Framework (incubation)</filename>.</para></listitem> |
797 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> | 797 | <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> |
798 | </orderedlist> | 798 | </orderedlist> |
@@ -807,7 +807,7 @@ | |||
807 | one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in, | 807 | one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in, |
808 | or build and install the plug-in from the latest source code. | 808 | or build and install the plug-in from the latest source code. |
809 | If you don't want to permanently install the plug-in but just want to try it out | 809 | If you don't want to permanently install the plug-in but just want to try it out |
810 | within the Eclipse environment, you can import the plug-in project from the | 810 | within the Eclipse environment, you can import the plug-in project from the |
811 | Yocto Project's Source Repositories. | 811 | Yocto Project's Source Repositories. |
812 | </para> | 812 | </para> |
813 | 813 | ||
@@ -815,22 +815,22 @@ | |||
815 | <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> | 815 | <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> |
816 | 816 | ||
817 | <para> | 817 | <para> |
818 | To install the Eclipse Yocto Plug-in from the update site, | 818 | To install the Eclipse Yocto Plug-in from the update site, |
819 | follow these steps: | 819 | follow these steps: |
820 | <orderedlist> | 820 | <orderedlist> |
821 | <listitem><para>Start up the Eclipse IDE.</para></listitem> | 821 | <listitem><para>Start up the Eclipse IDE.</para></listitem> |
822 | <listitem><para>In Eclipse, select "Install New Software" from the "Help" menu.</para></listitem> | 822 | <listitem><para>In Eclipse, select "Install New Software" from the "Help" menu.</para></listitem> |
823 | <listitem><para>Click "Add..." in the "Work with:" area.</para></listitem> | 823 | <listitem><para>Click "Add..." in the "Work with:" area.</para></listitem> |
824 | <listitem><para>Enter | 824 | <listitem><para>Enter |
825 | <filename>&ECLIPSE_DL_PLUGIN_URL;</filename> | 825 | <filename>&ECLIPSE_DL_PLUGIN_URL;</filename> |
826 | in the URL field and provide a meaningful name in the "Name" field.</para></listitem> | 826 | in the URL field and provide a meaningful name in the "Name" field.</para></listitem> |
827 | <listitem><para>Click "OK" to have the entry added to the "Work with:" | 827 | <listitem><para>Click "OK" to have the entry added to the "Work with:" |
828 | drop-down list.</para></listitem> | 828 | drop-down list.</para></listitem> |
829 | <listitem><para>Select the entry for the plug-in from the "Work with:" drop-down | 829 | <listitem><para>Select the entry for the plug-in from the "Work with:" drop-down |
830 | list.</para></listitem> | 830 | list.</para></listitem> |
831 | <listitem><para>Check the box next to <filename>Development tools and SDKs for Yocto Linux</filename>. | 831 | <listitem><para>Check the box next to <filename>Development tools and SDKs for Yocto Linux</filename>. |
832 | </para></listitem> | 832 | </para></listitem> |
833 | <listitem><para>Complete the remaining software installation steps and | 833 | <listitem><para>Complete the remaining software installation steps and |
834 | then restart the Eclipse IDE to finish the installation of the plug-in. | 834 | then restart the Eclipse IDE to finish the installation of the plug-in. |
835 | </para></listitem> | 835 | </para></listitem> |
836 | </orderedlist> | 836 | </orderedlist> |
@@ -839,7 +839,7 @@ | |||
839 | 839 | ||
840 | <section id='zip-file-method'> | 840 | <section id='zip-file-method'> |
841 | <title>Installing the Plug-in Using the Latest Source Code</title> | 841 | <title>Installing the Plug-in Using the Latest Source Code</title> |
842 | 842 | ||
843 | <para> | 843 | <para> |
844 | To install the Eclipse Yocto Plug-in from the latest source code, follow these steps: | 844 | To install the Eclipse Yocto Plug-in from the latest source code, follow these steps: |
845 | <orderedlist> | 845 | <orderedlist> |
@@ -847,9 +847,9 @@ | |||
847 | <literallayout class='monospaced'> | 847 | <literallayout class='monospaced'> |
848 | $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse | 848 | $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse |
849 | </literallayout> | 849 | </literallayout> |
850 | For this example, the repository is named | 850 | For this example, the repository is named |
851 | <filename>~/yocto-eclipse</filename>.</para></listitem> | 851 | <filename>~/yocto-eclipse</filename>.</para></listitem> |
852 | <listitem><para>Change to the directory where you set up | 852 | <listitem><para>Change to the directory where you set up |
853 | the Git repository: | 853 | the Git repository: |
854 | <literallayout class='monospaced'> | 854 | <literallayout class='monospaced'> |
855 | $ cd ~/yocto-eclipse | 855 | $ cd ~/yocto-eclipse |
@@ -864,38 +864,38 @@ | |||
864 | <literallayout class='monospaced'> | 864 | <literallayout class='monospaced'> |
865 | $ cd scripts | 865 | $ cd scripts |
866 | </literallayout></para></listitem> | 866 | </literallayout></para></listitem> |
867 | <listitem><para>Set up the local build environment by running the | 867 | <listitem><para>Set up the local build environment by running the |
868 | setup script: | 868 | setup script: |
869 | <literallayout class='monospaced'> | 869 | <literallayout class='monospaced'> |
870 | $ ./setup.sh | 870 | $ ./setup.sh |
871 | </literallayout></para></listitem> | 871 | </literallayout></para></listitem> |
872 | <listitem><para>When the script finishes execution, it prompts | 872 | <listitem><para>When the script finishes execution, it prompts |
873 | you with instructions on how to run the | 873 | you with instructions on how to run the |
874 | <filename>build.sh</filename> script, which is also in | 874 | <filename>build.sh</filename> script, which is also in |
875 | the <filename>scripts</filename> of the | 875 | the <filename>scripts</filename> of the |
876 | Git repository created earlier. | 876 | Git repository created earlier. |
877 | </para></listitem> | 877 | </para></listitem> |
878 | <listitem><para>Run the <filename>build.sh</filename> script | 878 | <listitem><para>Run the <filename>build.sh</filename> script |
879 | as directed. | 879 | as directed. |
880 | Be sure to provide the name of the Git branch along with the | 880 | Be sure to provide the name of the Git branch along with the |
881 | Yocto Project release you are using. | 881 | Yocto Project release you are using. |
882 | Here is an example that uses the <filename>&DISTRO_NAME;</filename> branches: | 882 | Here is an example that uses the <filename>&DISTRO_NAME;</filename> branches: |
883 | <literallayout class='monospaced'> | 883 | <literallayout class='monospaced'> |
884 | $ ECLIPSE_HOME=/home/scottrif/yocto-eclipse/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME; | 884 | $ ECLIPSE_HOME=/home/scottrif/yocto-eclipse/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME; |
885 | </literallayout> | 885 | </literallayout> |
886 | After running the script, the file | 886 | After running the script, the file |
887 | <filename>org.yocto.sdk-<release>-<date>-archive.zip</filename> | 887 | <filename>org.yocto.sdk-<release>-<date>-archive.zip</filename> |
888 | is in the current directory.</para></listitem> | 888 | is in the current directory.</para></listitem> |
889 | <listitem><para>If necessary, start the Eclipse IDE and be sure you are in the | 889 | <listitem><para>If necessary, start the Eclipse IDE and be sure you are in the |
890 | Workbench.</para></listitem> | 890 | Workbench.</para></listitem> |
891 | <listitem><para>Select "Install New Software" from the "Help" pull-down menu. | 891 | <listitem><para>Select "Install New Software" from the "Help" pull-down menu. |
892 | </para></listitem> | 892 | </para></listitem> |
893 | <listitem><para>Click "Add".</para></listitem> | 893 | <listitem><para>Click "Add".</para></listitem> |
894 | <listitem><para>Provide anything you want in the "Name" field.</para></listitem> | 894 | <listitem><para>Provide anything you want in the "Name" field.</para></listitem> |
895 | <listitem><para>Click "Archive" and browse to the ZIP file you built | 895 | <listitem><para>Click "Archive" and browse to the ZIP file you built |
896 | in step seven. | 896 | in step seven. |
897 | This ZIP file should not be "unzipped", and must be the | 897 | This ZIP file should not be "unzipped", and must be the |
898 | <filename>*archive.zip</filename> file created by running the | 898 | <filename>*archive.zip</filename> file created by running the |
899 | <filename>build.sh</filename> script.</para></listitem> | 899 | <filename>build.sh</filename> script.</para></listitem> |
900 | <listitem><para>Click through the "Okay" buttons.</para></listitem> | 900 | <listitem><para>Click through the "Okay" buttons.</para></listitem> |
901 | <listitem><para>Check the box next to the new entry in the installation window and complete | 901 | <listitem><para>Check the box next to the new entry in the installation window and complete |
@@ -908,16 +908,16 @@ | |||
908 | At this point you should be able to configure the Eclipse Yocto Plug-in as described in the | 908 | At this point you should be able to configure the Eclipse Yocto Plug-in as described in the |
909 | "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" | 909 | "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" |
910 | section.</para> | 910 | section.</para> |
911 | </section> | 911 | </section> |
912 | 912 | ||
913 | <section id='yocto-project-source'> | 913 | <section id='yocto-project-source'> |
914 | <title>Importing the Plug-in Project into the Eclipse Environment</title> | 914 | <title>Importing the Plug-in Project into the Eclipse Environment</title> |
915 | 915 | ||
916 | <para> | 916 | <para> |
917 | Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories | 917 | Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories |
918 | is useful when you want to try out the latest plug-in from the tip of plug-in's | 918 | is useful when you want to try out the latest plug-in from the tip of plug-in's |
919 | development tree. | 919 | development tree. |
920 | It is important to understand when you import the plug-in you are not installing | 920 | It is important to understand when you import the plug-in you are not installing |
921 | it into the Eclipse application. | 921 | it into the Eclipse application. |
922 | Rather, you are importing the project and just using it. | 922 | Rather, you are importing the project and just using it. |
923 | To import the plug-in project, follow these steps: | 923 | To import the plug-in project, follow these steps: |
@@ -926,21 +926,21 @@ | |||
926 | <literallayout class='monospaced'> | 926 | <literallayout class='monospaced'> |
927 | $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse | 927 | $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse |
928 | </literallayout> | 928 | </literallayout> |
929 | For this example, the repository is named | 929 | For this example, the repository is named |
930 | <filename>~/yocto-eclipse</filename>.</para></listitem> | 930 | <filename>~/yocto-eclipse</filename>.</para></listitem> |
931 | <listitem><para>In Eclipse, select "Import" from the "File" menu.</para></listitem> | 931 | <listitem><para>In Eclipse, select "Import" from the "File" menu.</para></listitem> |
932 | <listitem><para>Expand the "General" box and select "existing projects into workspace" | 932 | <listitem><para>Expand the "General" box and select "existing projects into workspace" |
933 | and then click "Next".</para></listitem> | 933 | and then click "Next".</para></listitem> |
934 | <listitem><para>Select the root directory and browse to | 934 | <listitem><para>Select the root directory and browse to |
935 | <filename>~/yocto-eclipse/plugins</filename>.</para></listitem> | 935 | <filename>~/yocto-eclipse/plugins</filename>.</para></listitem> |
936 | <listitem><para>Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and | 936 | <listitem><para>Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and |
937 | "org.yocto.sdk.remotetools". | 937 | "org.yocto.sdk.remotetools". |
938 | Select and import all of them.</para></listitem> | 938 | Select and import all of them.</para></listitem> |
939 | </orderedlist> | 939 | </orderedlist> |
940 | </para> | 940 | </para> |
941 | 941 | ||
942 | <para> | 942 | <para> |
943 | The left navigation pane in the Eclipse application shows the default projects. | 943 | The left navigation pane in the Eclipse application shows the default projects. |
944 | Right-click on one of these projects and run it as an Eclipse application. | 944 | Right-click on one of these projects and run it as an Eclipse application. |
945 | This brings up a second instance of Eclipse IDE that has the Yocto Plug-in. | 945 | This brings up a second instance of Eclipse IDE that has the Yocto Plug-in. |
946 | </para> | 946 | </para> |
@@ -951,17 +951,17 @@ | |||
951 | <title>Configuring the Eclipse Yocto Plug-in</title> | 951 | <title>Configuring the Eclipse Yocto Plug-in</title> |
952 | 952 | ||
953 | <para> | 953 | <para> |
954 | Configuring the Eclipse Yocto Plug-in involves setting the Cross | 954 | Configuring the Eclipse Yocto Plug-in involves setting the Cross |
955 | Compiler options and the Target options. | 955 | Compiler options and the Target options. |
956 | The configurations you choose become the default settings for all projects. | 956 | The configurations you choose become the default settings for all projects. |
957 | You do have opportunities to change them later when | 957 | You do have opportunities to change them later when |
958 | you configure the project (see the following section). | 958 | you configure the project (see the following section). |
959 | </para> | 959 | </para> |
960 | 960 | ||
961 | <para> | 961 | <para> |
962 | To start, you need to do the following from within the Eclipse IDE: | 962 | To start, you need to do the following from within the Eclipse IDE: |
963 | <itemizedlist> | 963 | <itemizedlist> |
964 | <listitem><para>Choose <filename>Windows -> Preferences</filename> to display | 964 | <listitem><para>Choose <filename>Windows -> Preferences</filename> to display |
965 | the <filename>Preferences</filename> Dialog</para></listitem> | 965 | the <filename>Preferences</filename> Dialog</para></listitem> |
966 | <listitem><para>Click <filename>Yocto Project ADT</filename></para></listitem> | 966 | <listitem><para>Click <filename>Yocto Project ADT</filename></para></listitem> |
967 | </itemizedlist> | 967 | </itemizedlist> |
@@ -976,23 +976,23 @@ | |||
976 | <itemizedlist> | 976 | <itemizedlist> |
977 | <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> | 977 | <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> |
978 | Choose between <filename>Standalone pre-built toolchain</filename> | 978 | Choose between <filename>Standalone pre-built toolchain</filename> |
979 | and <filename>Build system derived toolchain</filename> for Cross | 979 | and <filename>Build system derived toolchain</filename> for Cross |
980 | Compiler Options. | 980 | Compiler Options. |
981 | <itemizedlist> | 981 | <itemizedlist> |
982 | <listitem><para><emphasis> | 982 | <listitem><para><emphasis> |
983 | <filename>Standalone Pre-built Toolchain:</filename></emphasis> | 983 | <filename>Standalone Pre-built Toolchain:</filename></emphasis> |
984 | Select this mode when you are using a stand-alone cross-toolchain. | 984 | Select this mode when you are using a stand-alone cross-toolchain. |
985 | For example, suppose you are an application developer and do not | 985 | For example, suppose you are an application developer and do not |
986 | need to build a target image. | 986 | need to build a target image. |
987 | Instead, you just want to use an architecture-specific toolchain on an | 987 | Instead, you just want to use an architecture-specific toolchain on an |
988 | existing kernel and target root filesystem. | 988 | existing kernel and target root filesystem. |
989 | </para></listitem> | 989 | </para></listitem> |
990 | <listitem><para><emphasis> | 990 | <listitem><para><emphasis> |
991 | <filename>Build System Derived Toolchain:</filename></emphasis> | 991 | <filename>Build System Derived Toolchain:</filename></emphasis> |
992 | Select this mode if the cross-toolchain has been installed and built | 992 | Select this mode if the cross-toolchain has been installed and built |
993 | as part of the Build Directory. | 993 | as part of the Build Directory. |
994 | When you select <filename>Build system derived toolchain</filename>, | 994 | When you select <filename>Build system derived toolchain</filename>, |
995 | you are using the toolchain bundled | 995 | you are using the toolchain bundled |
996 | inside the Build Directory. | 996 | inside the Build Directory. |
997 | </para></listitem> | 997 | </para></listitem> |
998 | </itemizedlist> | 998 | </itemizedlist> |
@@ -1001,44 +1001,44 @@ | |||
1001 | If you are using a stand-alone pre-built toolchain, you should be pointing to the | 1001 | If you are using a stand-alone pre-built toolchain, you should be pointing to the |
1002 | <filename>&YOCTO_ADTPATH_DIR;</filename> directory. | 1002 | <filename>&YOCTO_ADTPATH_DIR;</filename> directory. |
1003 | This is the location for toolchains installed by the ADT Installer or by hand. | 1003 | This is the location for toolchains installed by the ADT Installer or by hand. |
1004 | Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring | 1004 | Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring |
1005 | and Running the ADT Installer Script</ulink>" and | 1005 | and Running the ADT Installer Script</ulink>" and |
1006 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" | 1006 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" |
1007 | in the Yocto Project Application Developer's Guide | 1007 | in the Yocto Project Application Developer's Guide |
1008 | describe two ways to install a stand-alone cross-toolchain in the | 1008 | describe two ways to install a stand-alone cross-toolchain in the |
1009 | <filename>/opt/poky</filename> directory. | 1009 | <filename>/opt/poky</filename> directory. |
1010 | <note>It is possible to install a stand-alone cross-toolchain in a directory | 1010 | <note>It is possible to install a stand-alone cross-toolchain in a directory |
1011 | other than <filename>/opt/poky</filename>. | 1011 | other than <filename>/opt/poky</filename>. |
1012 | However, doing so is discouraged.</note></para> | 1012 | However, doing so is discouraged.</note></para> |
1013 | <para>If you are using a system-derived toolchain, the path you provide | 1013 | <para>If you are using a system-derived toolchain, the path you provide |
1014 | for the <filename>Toolchain Root Location</filename> | 1014 | for the <filename>Toolchain Root Location</filename> |
1015 | field is the Build Directory. | 1015 | field is the Build Directory. |
1016 | See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using | 1016 | See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using |
1017 | BitBake and the Build Directory</ulink>" section in the Yocto Project Application | 1017 | BitBake and the Build Directory</ulink>" section in the Yocto Project Application |
1018 | Developer's Guide for information on how to install the toolchain into the build | 1018 | Developer's Guide for information on how to install the toolchain into the build |
1019 | directory.</para></listitem> | 1019 | directory.</para></listitem> |
1020 | <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> | 1020 | <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> |
1021 | This location is where the root filesystem for the target hardware resides. | 1021 | This location is where the root filesystem for the target hardware resides. |
1022 | If you used the ADT Installer, then the location is | 1022 | If you used the ADT Installer, then the location is |
1023 | <filename>/opt/poky/<release></filename>. | 1023 | <filename>/opt/poky/<release></filename>. |
1024 | Additionally, when you use the ADT Installer, the same location is used for | 1024 | Additionally, when you use the ADT Installer, the same location is used for |
1025 | the QEMU user-space tools and the NFS boot process.</para> | 1025 | the QEMU user-space tools and the NFS boot process.</para> |
1026 | <para>If you used either of the other two methods to install the toolchain, then the | 1026 | <para>If you used either of the other two methods to install the toolchain, then the |
1027 | location of the sysroot filesystem depends on where you separately | 1027 | location of the sysroot filesystem depends on where you separately |
1028 | extracted and intalled the filesystem.</para> | 1028 | extracted and intalled the filesystem.</para> |
1029 | <para>For information on how to install the toolchain and on how to extract | 1029 | <para>For information on how to install the toolchain and on how to extract |
1030 | and install the sysroot filesystem, see the | 1030 | and install the sysroot filesystem, see the |
1031 | "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" section. | 1031 | "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" section. |
1032 | </para></listitem> | 1032 | </para></listitem> |
1033 | <listitem><para><emphasis>Select the Target Architecture:</emphasis> | 1033 | <listitem><para><emphasis>Select the Target Architecture:</emphasis> |
1034 | The target architecture is the type of hardware you are | 1034 | The target architecture is the type of hardware you are |
1035 | going to use or emulate. | 1035 | going to use or emulate. |
1036 | Use the pull-down <filename>Target Architecture</filename> menu to make | 1036 | Use the pull-down <filename>Target Architecture</filename> menu to make |
1037 | your selection. | 1037 | your selection. |
1038 | The pull-down menu should have the supported architectures. | 1038 | The pull-down menu should have the supported architectures. |
1039 | If the architecture you need is not listed in the menu, you | 1039 | If the architecture you need is not listed in the menu, you |
1040 | will need to build the image. | 1040 | will need to build the image. |
1041 | See the "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section | 1041 | See the "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section |
1042 | of the Yocto Project Quick Start for more information.</para></listitem> | 1042 | of the Yocto Project Quick Start for more information.</para></listitem> |
1043 | </itemizedlist> | 1043 | </itemizedlist> |
1044 | </para> | 1044 | </para> |
@@ -1048,37 +1048,37 @@ directory.</para></listitem> | |||
1048 | <title>Configuring the Target Options</title> | 1048 | <title>Configuring the Target Options</title> |
1049 | 1049 | ||
1050 | <para> | 1050 | <para> |
1051 | You can choose to emulate hardware using the QEMU emulator, or you | 1051 | You can choose to emulate hardware using the QEMU emulator, or you |
1052 | can choose to run your image on actual hardware. | 1052 | can choose to run your image on actual hardware. |
1053 | <itemizedlist> | 1053 | <itemizedlist> |
1054 | <listitem><para><emphasis><filename>QEMU:</filename></emphasis> Select this option if | 1054 | <listitem><para><emphasis><filename>QEMU:</filename></emphasis> Select this option if |
1055 | you will be using the QEMU emulator. | 1055 | you will be using the QEMU emulator. |
1056 | If you are using the emulator, you also need to locate the kernel | 1056 | If you are using the emulator, you also need to locate the kernel |
1057 | and specify any custom options.</para> | 1057 | and specify any custom options.</para> |
1058 | <para>If you selected <filename>Build system derived toolchain</filename>, | 1058 | <para>If you selected <filename>Build system derived toolchain</filename>, |
1059 | the target kernel you built will be located in the | 1059 | the target kernel you built will be located in the |
1060 | Build Directory in <filename>tmp/deploy/images</filename> directory. | 1060 | Build Directory in <filename>tmp/deploy/images</filename> directory. |
1061 | If you selected <filename>Standalone pre-built toolchain</filename>, the | 1061 | If you selected <filename>Standalone pre-built toolchain</filename>, the |
1062 | pre-built image you downloaded is located | 1062 | pre-built image you downloaded is located |
1063 | in the directory you specified when you downloaded the image.</para> | 1063 | in the directory you specified when you downloaded the image.</para> |
1064 | <para>Most custom options are for advanced QEMU users to further | 1064 | <para>Most custom options are for advanced QEMU users to further |
1065 | customize their QEMU instance. | 1065 | customize their QEMU instance. |
1066 | These options are specified between paired angled brackets. | 1066 | These options are specified between paired angled brackets. |
1067 | Some options must be specified outside the brackets. | 1067 | Some options must be specified outside the brackets. |
1068 | In particular, the options <filename>serial</filename>, | 1068 | In particular, the options <filename>serial</filename>, |
1069 | <filename>nographic</filename>, and <filename>kvm</filename> must all | 1069 | <filename>nographic</filename>, and <filename>kvm</filename> must all |
1070 | be outside the brackets. | 1070 | be outside the brackets. |
1071 | Use the <filename>man qemu</filename> command to get help on all the options | 1071 | Use the <filename>man qemu</filename> command to get help on all the options |
1072 | and their use. | 1072 | and their use. |
1073 | The following is an example: | 1073 | The following is an example: |
1074 | <literallayout class='monospaced'> | 1074 | <literallayout class='monospaced'> |
1075 | serial ‘<-m 256 -full-screen>’ | 1075 | serial ‘<-m 256 -full-screen>’ |
1076 | </literallayout></para> | 1076 | </literallayout></para> |
1077 | <para> | 1077 | <para> |
1078 | Regardless of the mode, Sysroot is already defined as part of the | 1078 | Regardless of the mode, Sysroot is already defined as part of the |
1079 | Cross Compiler Options configuration in the | 1079 | Cross Compiler Options configuration in the |
1080 | <filename>Sysroot Location:</filename> field.</para></listitem> | 1080 | <filename>Sysroot Location:</filename> field.</para></listitem> |
1081 | <listitem><para><emphasis><filename>External HW:</filename></emphasis> Select this option | 1081 | <listitem><para><emphasis><filename>External HW:</filename></emphasis> Select this option |
1082 | if you will be using actual hardware.</para></listitem> | 1082 | if you will be using actual hardware.</para></listitem> |
1083 | </itemizedlist> | 1083 | </itemizedlist> |
1084 | </para> | 1084 | </para> |
@@ -1094,23 +1094,23 @@ directory.</para></listitem> | |||
1094 | <title>Creating the Project</title> | 1094 | <title>Creating the Project</title> |
1095 | 1095 | ||
1096 | <para> | 1096 | <para> |
1097 | You can create two types of projects: Autotools-based, or Makefile-based. | 1097 | You can create two types of projects: Autotools-based, or Makefile-based. |
1098 | This section describes how to create Autotools-based projects from within | 1098 | This section describes how to create Autotools-based projects from within |
1099 | the Eclipse IDE. | 1099 | the Eclipse IDE. |
1100 | For information on creating Makefile-based projects in a terminal window, see the section | 1100 | For information on creating Makefile-based projects in a terminal window, see the section |
1101 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>" | 1101 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>" |
1102 | in the Yocto Project Application Developer's Guide. | 1102 | in the Yocto Project Application Developer's Guide. |
1103 | </para> | 1103 | </para> |
1104 | 1104 | ||
1105 | <para> | 1105 | <para> |
1106 | To create a project based on a Yocto template and then display the source code, | 1106 | To create a project based on a Yocto template and then display the source code, |
1107 | follow these steps: | 1107 | follow these steps: |
1108 | <orderedlist> | 1108 | <orderedlist> |
1109 | <listitem><para>Select <filename>File -> New -> Project</filename>.</para></listitem> | 1109 | <listitem><para>Select <filename>File -> New -> Project</filename>.</para></listitem> |
1110 | <listitem><para>Double click <filename>CC++</filename>.</para></listitem> | 1110 | <listitem><para>Double click <filename>CC++</filename>.</para></listitem> |
1111 | <listitem><para>Double click <filename>C Project</filename> to create the project.</para></listitem> | 1111 | <listitem><para>Double click <filename>C Project</filename> to create the project.</para></listitem> |
1112 | <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.</para></listitem> | 1112 | <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.</para></listitem> |
1113 | <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>. | 1113 | <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>. |
1114 | This is an Autotools-based project based on a Yocto template.</para></listitem> | 1114 | This is an Autotools-based project based on a Yocto template.</para></listitem> |
1115 | <listitem><para>Put a name in the <filename>Project name:</filename> field. | 1115 | <listitem><para>Put a name in the <filename>Project name:</filename> field. |
1116 | Do not use hyphens as part of the name.</para></listitem> | 1116 | Do not use hyphens as part of the name.</para></listitem> |
@@ -1119,7 +1119,7 @@ directory.</para></listitem> | |||
1119 | <filename>Copyright notice</filename> fields.</para></listitem> | 1119 | <filename>Copyright notice</filename> fields.</para></listitem> |
1120 | <listitem><para>Be sure the <filename>License</filename> field is correct.</para></listitem> | 1120 | <listitem><para>Be sure the <filename>License</filename> field is correct.</para></listitem> |
1121 | <listitem><para>Click <filename>Finish</filename>.</para></listitem> | 1121 | <listitem><para>Click <filename>Finish</filename>.</para></listitem> |
1122 | <listitem><para>If the "open perspective" prompt appears, click "Yes" so that you | 1122 | <listitem><para>If the "open perspective" prompt appears, click "Yes" so that you |
1123 | in the C/C++ perspective.</para></listitem> | 1123 | in the C/C++ perspective.</para></listitem> |
1124 | <listitem><para>The left-hand navigation pane shows your project. | 1124 | <listitem><para>The left-hand navigation pane shows your project. |
1125 | You can display your source by double clicking the project's source file. | 1125 | You can display your source by double clicking the project's source file. |
@@ -1132,36 +1132,36 @@ directory.</para></listitem> | |||
1132 | <title>Configuring the Cross-Toolchains</title> | 1132 | <title>Configuring the Cross-Toolchains</title> |
1133 | 1133 | ||
1134 | <para> | 1134 | <para> |
1135 | The earlier section, "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring | 1135 | The earlier section, "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring |
1136 | the Eclipse Yocto Plug-in</link>", sets up the default project | 1136 | the Eclipse Yocto Plug-in</link>", sets up the default project |
1137 | configurations. | 1137 | configurations. |
1138 | You can override these settings for a given project by following these steps: | 1138 | You can override these settings for a given project by following these steps: |
1139 | <orderedlist> | 1139 | <orderedlist> |
1140 | <listitem><para>Select <filename>Project -> Change Yocto Project Settings</filename>: | 1140 | <listitem><para>Select <filename>Project -> Change Yocto Project Settings</filename>: |
1141 | This selection brings up the <filename>Yocot Project Settings</filename> Dialog | 1141 | This selection brings up the <filename>Yocot Project Settings</filename> Dialog |
1142 | and allows you to make changes specific to an individual project. | 1142 | and allows you to make changes specific to an individual project. |
1143 | </para> | 1143 | </para> |
1144 | <para>By default, the Cross Compiler Options and Target Options for a project | 1144 | <para>By default, the Cross Compiler Options and Target Options for a project |
1145 | are inherited from settings you provide using the <filename>Preferences</filename> | 1145 | are inherited from settings you provide using the <filename>Preferences</filename> |
1146 | Dialog as described earlier | 1146 | Dialog as described earlier |
1147 | in the "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse | 1147 | in the "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse |
1148 | Yocto Plug-in</link>" section. | 1148 | Yocto Plug-in</link>" section. |
1149 | The <filename>Yocto Project Settings</filename> | 1149 | The <filename>Yocto Project Settings</filename> |
1150 | Dialog allows you to override those default settings | 1150 | Dialog allows you to override those default settings |
1151 | for a given project.</para></listitem> | 1151 | for a given project.</para></listitem> |
1152 | <listitem><para>Make your configurations for the project and click "OK". | 1152 | <listitem><para>Make your configurations for the project and click "OK". |
1153 | If you are running the Juno version of Eclipse, you can skip down to the next | 1153 | If you are running the Juno version of Eclipse, you can skip down to the next |
1154 | section where you build the project. | 1154 | section where you build the project. |
1155 | If you are not working with Juno, you need to reconfigure the project as | 1155 | If you are not working with Juno, you need to reconfigure the project as |
1156 | described in the next step.</para></listitem> | 1156 | described in the next step.</para></listitem> |
1157 | <listitem><para>Select <filename>Project -> Reconfigure Project</filename>: | 1157 | <listitem><para>Select <filename>Project -> Reconfigure Project</filename>: |
1158 | This selection reconfigures the project by running | 1158 | This selection reconfigures the project by running |
1159 | <filename>autogen.sh</filename> in the workspace for your project. | 1159 | <filename>autogen.sh</filename> in the workspace for your project. |
1160 | The script also runs <filename>libtoolize</filename>, <filename>aclocal</filename>, | 1160 | The script also runs <filename>libtoolize</filename>, <filename>aclocal</filename>, |
1161 | <filename>autoconf</filename>, <filename>autoheader</filename>, | 1161 | <filename>autoconf</filename>, <filename>autoheader</filename>, |
1162 | <filename>automake --a</filename>, and | 1162 | <filename>automake --a</filename>, and |
1163 | <filename>./configure</filename>. | 1163 | <filename>./configure</filename>. |
1164 | Click on the <filename>Console</filename> tab beneath your source code to | 1164 | Click on the <filename>Console</filename> tab beneath your source code to |
1165 | see the results of reconfiguring your project.</para></listitem> | 1165 | see the results of reconfiguring your project.</para></listitem> |
1166 | </orderedlist> | 1166 | </orderedlist> |
1167 | </para> | 1167 | </para> |
@@ -1173,7 +1173,7 @@ directory.</para></listitem> | |||
1173 | <para> | 1173 | <para> |
1174 | To build the project in Juno, right click on the project in the navigator pane and select | 1174 | To build the project in Juno, right click on the project in the navigator pane and select |
1175 | <filename>Build Project</filename>. | 1175 | <filename>Build Project</filename>. |
1176 | If you are not running Juno, select <filename>Project -> Build Project</filename>. | 1176 | If you are not running Juno, select <filename>Project -> Build Project</filename>. |
1177 | The console should update and you can note the cross-compiler you are using. | 1177 | The console should update and you can note the cross-compiler you are using. |
1178 | </para> | 1178 | </para> |
1179 | </section> | 1179 | </section> |
@@ -1187,15 +1187,15 @@ directory.</para></listitem> | |||
1187 | <listitem><para>Expose the <filename>Run -> External Tools</filename> menu. | 1187 | <listitem><para>Expose the <filename>Run -> External Tools</filename> menu. |
1188 | Your image should appear as a selectable menu item. | 1188 | Your image should appear as a selectable menu item. |
1189 | </para></listitem> | 1189 | </para></listitem> |
1190 | <listitem><para>Select your image from the menu to launch the | 1190 | <listitem><para>Select your image from the menu to launch the |
1191 | emulator in a new window.</para></listitem> | 1191 | emulator in a new window.</para></listitem> |
1192 | <listitem><para>If needed, enter your host root password in the shell window at the prompt. | 1192 | <listitem><para>If needed, enter your host root password in the shell window at the prompt. |
1193 | This sets up a <filename>Tap 0</filename> connection needed for running in user-space | 1193 | This sets up a <filename>Tap 0</filename> connection needed for running in user-space |
1194 | NFS mode.</para></listitem> | 1194 | NFS mode.</para></listitem> |
1195 | <listitem><para>Wait for QEMU to launch.</para></listitem> | 1195 | <listitem><para>Wait for QEMU to launch.</para></listitem> |
1196 | <listitem><para>Once QEMU launches, you can begin operating within that | 1196 | <listitem><para>Once QEMU launches, you can begin operating within that |
1197 | environment. | 1197 | environment. |
1198 | For example, you could determine the IP Address | 1198 | For example, you could determine the IP Address |
1199 | for the user-space NFS by using the <filename>ifconfig</filename> command. | 1199 | for the user-space NFS by using the <filename>ifconfig</filename> command. |
1200 | </para></listitem> | 1200 | </para></listitem> |
1201 | </orderedlist> | 1201 | </orderedlist> |
@@ -1206,33 +1206,33 @@ directory.</para></listitem> | |||
1206 | <title>Deploying and Debugging the Application</title> | 1206 | <title>Deploying and Debugging the Application</title> |
1207 | 1207 | ||
1208 | <para> | 1208 | <para> |
1209 | Once the QEMU emulator is running the image, using the Eclipse IDE | 1209 | Once the QEMU emulator is running the image, using the Eclipse IDE |
1210 | you can deploy your application and use the emulator to perform debugging. | 1210 | you can deploy your application and use the emulator to perform debugging. |
1211 | Follow these steps to deploy the application. | 1211 | Follow these steps to deploy the application. |
1212 | <orderedlist> | 1212 | <orderedlist> |
1213 | <listitem><para>Select <filename>Run -> Debug Configurations...</filename></para></listitem> | 1213 | <listitem><para>Select <filename>Run -> Debug Configurations...</filename></para></listitem> |
1214 | <listitem><para>In the left area, expand <filename>C/C++Remote Application</filename>.</para></listitem> | 1214 | <listitem><para>In the left area, expand <filename>C/C++Remote Application</filename>.</para></listitem> |
1215 | <listitem><para>Locate your project and select it to bring up a new | 1215 | <listitem><para>Locate your project and select it to bring up a new |
1216 | tabbed view in the <filename>Debug Configurations</filename> Dialog.</para></listitem> | 1216 | tabbed view in the <filename>Debug Configurations</filename> Dialog.</para></listitem> |
1217 | <listitem><para>Enter the absolute path into which you want to deploy | 1217 | <listitem><para>Enter the absolute path into which you want to deploy |
1218 | the application. | 1218 | the application. |
1219 | Use the <filename>Remote Absolute File Path for C/C++Application:</filename> field. | 1219 | Use the <filename>Remote Absolute File Path for C/C++Application:</filename> field. |
1220 | For example, enter <filename>/usr/bin/<programname></filename>.</para></listitem> | 1220 | For example, enter <filename>/usr/bin/<programname></filename>.</para></listitem> |
1221 | <listitem><para>Click on the <filename>Debugger</filename> tab to see the cross-tool debugger | 1221 | <listitem><para>Click on the <filename>Debugger</filename> tab to see the cross-tool debugger |
1222 | you are using.</para></listitem> | 1222 | you are using.</para></listitem> |
1223 | <listitem><para>Click on the <filename>Main</filename> tab.</para></listitem> | 1223 | <listitem><para>Click on the <filename>Main</filename> tab.</para></listitem> |
1224 | <listitem><para>Create a new connection to the QEMU instance | 1224 | <listitem><para>Create a new connection to the QEMU instance |
1225 | by clicking on <filename>new</filename>.</para></listitem> | 1225 | by clicking on <filename>new</filename>.</para></listitem> |
1226 | <listitem><para>Select <filename>TCF</filename>, which means Target Communication | 1226 | <listitem><para>Select <filename>TCF</filename>, which means Target Communication |
1227 | Framework.</para></listitem> | 1227 | Framework.</para></listitem> |
1228 | <listitem><para>Click <filename>Next</filename>.</para></listitem> | 1228 | <listitem><para>Click <filename>Next</filename>.</para></listitem> |
1229 | <listitem><para>Clear out the <filename>host name</filename> field and enter the IP Address | 1229 | <listitem><para>Clear out the <filename>host name</filename> field and enter the IP Address |
1230 | determined earlier.</para></listitem> | 1230 | determined earlier.</para></listitem> |
1231 | <listitem><para>Click <filename>Finish</filename> to close the | 1231 | <listitem><para>Click <filename>Finish</filename> to close the |
1232 | <filename>New Connections</filename> Dialog.</para></listitem> | 1232 | <filename>New Connections</filename> Dialog.</para></listitem> |
1233 | <listitem><para>Use the drop-down menu now in the <filename>Connection</filename> field and pick | 1233 | <listitem><para>Use the drop-down menu now in the <filename>Connection</filename> field and pick |
1234 | the IP Address you entered.</para></listitem> | 1234 | the IP Address you entered.</para></listitem> |
1235 | <listitem><para>Click <filename>Run</filename> to bring up a login screen | 1235 | <listitem><para>Click <filename>Run</filename> to bring up a login screen |
1236 | and login.</para></listitem> | 1236 | and login.</para></listitem> |
1237 | <listitem><para>Accept the debug perspective.</para></listitem> | 1237 | <listitem><para>Accept the debug perspective.</para></listitem> |
1238 | </orderedlist> | 1238 | </orderedlist> |
@@ -1243,106 +1243,106 @@ directory.</para></listitem> | |||
1243 | <title>Running User-Space Tools</title> | 1243 | <title>Running User-Space Tools</title> |
1244 | 1244 | ||
1245 | <para> | 1245 | <para> |
1246 | As mentioned earlier in the manual, several tools exist that enhance | 1246 | As mentioned earlier in the manual, several tools exist that enhance |
1247 | your development experience. | 1247 | your development experience. |
1248 | These tools are aids in developing and debugging applications and images. | 1248 | These tools are aids in developing and debugging applications and images. |
1249 | You can run these user-space tools from within the Eclipse IDE through the | 1249 | You can run these user-space tools from within the Eclipse IDE through the |
1250 | <filename>YoctoTools</filename> menu. | 1250 | <filename>YoctoTools</filename> menu. |
1251 | </para> | 1251 | </para> |
1252 | 1252 | ||
1253 | <para> | 1253 | <para> |
1254 | Once you pick a tool, you need to configure it for the remote target. | 1254 | Once you pick a tool, you need to configure it for the remote target. |
1255 | Every tool needs to have the connection configured. | 1255 | Every tool needs to have the connection configured. |
1256 | You must select an existing TCF-based RSE connection to the remote target. | 1256 | You must select an existing TCF-based RSE connection to the remote target. |
1257 | If one does not exist, click <filename>New</filename> to create one. | 1257 | If one does not exist, click <filename>New</filename> to create one. |
1258 | </para> | 1258 | </para> |
1259 | 1259 | ||
1260 | <para> | 1260 | <para> |
1261 | Here are some specifics about the remote tools: | 1261 | Here are some specifics about the remote tools: |
1262 | <itemizedlist> | 1262 | <itemizedlist> |
1263 | <listitem><para><emphasis><filename>OProfile</filename>:</emphasis> Selecting this tool causes | 1263 | <listitem><para><emphasis><filename>OProfile</filename>:</emphasis> Selecting this tool causes |
1264 | the <filename>oprofile-server</filename> on the remote target to launch on | 1264 | the <filename>oprofile-server</filename> on the remote target to launch on |
1265 | the local host machine. | 1265 | the local host machine. |
1266 | The <filename>oprofile-viewer</filename> must be installed on the local host machine and the | 1266 | The <filename>oprofile-viewer</filename> must be installed on the local host machine and the |
1267 | <filename>oprofile-server</filename> must be installed on the remote target, | 1267 | <filename>oprofile-server</filename> must be installed on the remote target, |
1268 | respectively, in order to use. | 1268 | respectively, in order to use. |
1269 | You must compile and install the <filename>oprofile-viewer</filename> from the source code | 1269 | You must compile and install the <filename>oprofile-viewer</filename> from the source code |
1270 | on your local host machine. | 1270 | on your local host machine. |
1271 | Furthermore, in order to convert the target's sample format data into a form that the | 1271 | Furthermore, in order to convert the target's sample format data into a form that the |
1272 | host can use, you must have <filename>oprofile</filename> version 0.9.4 or | 1272 | host can use, you must have <filename>oprofile</filename> version 0.9.4 or |
1273 | greater installed on the host.</para> | 1273 | greater installed on the host.</para> |
1274 | <para>You can locate both the viewer and server from | 1274 | <para>You can locate both the viewer and server from |
1275 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>. | 1275 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>. |
1276 | <note>The <filename>oprofile-server</filename> is installed by default on | 1276 | <note>The <filename>oprofile-server</filename> is installed by default on |
1277 | the <filename>core-image-sato-sdk</filename> image.</note></para></listitem> | 1277 | the <filename>core-image-sato-sdk</filename> image.</note></para></listitem> |
1278 | <listitem><para><emphasis><filename>Lttng2.0 ust trace import</filename>:</emphasis> | 1278 | <listitem><para><emphasis><filename>Lttng2.0 ust trace import</filename>:</emphasis> |
1279 | Selecting this tool transfers the remote target's | 1279 | Selecting this tool transfers the remote target's |
1280 | <filename>Lttng</filename> tracing data back to the local host machine | 1280 | <filename>Lttng</filename> tracing data back to the local host machine |
1281 | and uses the <filename>Lttng</filename> Eclipse plug-in to graphically | 1281 | and uses the <filename>Lttng</filename> Eclipse plug-in to graphically |
1282 | display the output. | 1282 | display the output. |
1283 | For information on how to use <filename>Lttng</filename> to trace an application, | 1283 | For information on how to use <filename>Lttng</filename> to trace an application, |
1284 | see <ulink url='http://lttng.org/documentation'></ulink>. | 1284 | see <ulink url='http://lttng.org/documentation'></ulink>. |
1285 | <note>Do not use <filename>Lttng-user space (legacy)</filename> tool. | 1285 | <note>Do not use <filename>Lttng-user space (legacy)</filename> tool. |
1286 | This tool no longer has any upstream support.</note> | 1286 | This tool no longer has any upstream support.</note> |
1287 | </para> | 1287 | </para> |
1288 | <para>Before you use the <filename>Lttng2.0 ust trace import</filename> tool, | 1288 | <para>Before you use the <filename>Lttng2.0 ust trace import</filename> tool, |
1289 | you need to setup the <filename>Lttng</filename> Eclipse plug-in and create a | 1289 | you need to setup the <filename>Lttng</filename> Eclipse plug-in and create a |
1290 | <filename>Tracing</filename> project. | 1290 | <filename>Tracing</filename> project. |
1291 | Do the following: | 1291 | Do the following: |
1292 | <orderedlist> | 1292 | <orderedlist> |
1293 | <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> | 1293 | <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> |
1294 | and then select <filename>Tracing</filename>.</para></listitem> | 1294 | and then select <filename>Tracing</filename>.</para></listitem> |
1295 | <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective | 1295 | <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective |
1296 | into the <filename>Tracing</filename> perspective.</para></listitem> | 1296 | into the <filename>Tracing</filename> perspective.</para></listitem> |
1297 | <listitem><para>Create a new <filename>Tracing</filename> project by selecting | 1297 | <listitem><para>Create a new <filename>Tracing</filename> project by selecting |
1298 | <filename>File -> New -> Project</filename>.</para></listitem> | 1298 | <filename>File -> New -> Project</filename>.</para></listitem> |
1299 | <listitem><para>Choose <filename>Tracing -> Tracing Project</filename>. | 1299 | <listitem><para>Choose <filename>Tracing -> Tracing Project</filename>. |
1300 | </para></listitem> | 1300 | </para></listitem> |
1301 | <listitem><para>Generate your tracing data on the remote target. | 1301 | <listitem><para>Generate your tracing data on the remote target. |
1302 | </para></listitem> | 1302 | </para></listitem> |
1303 | <listitem><para>Click | 1303 | <listitem><para>Click |
1304 | <filename>Yocto Project Tools -> Lttng2.0 ust trace import</filename> | 1304 | <filename>Yocto Project Tools -> Lttng2.0 ust trace import</filename> |
1305 | to start the data import process.</para></listitem> | 1305 | to start the data import process.</para></listitem> |
1306 | <listitem><para>Specify your remote connection name.</para></listitem> | 1306 | <listitem><para>Specify your remote connection name.</para></listitem> |
1307 | <listitem><para>For the Ust directory path, specify the location of | 1307 | <listitem><para>For the Ust directory path, specify the location of |
1308 | your remote tracing data. | 1308 | your remote tracing data. |
1309 | Make sure the location ends with <filename>ust</filename> (e.g. | 1309 | Make sure the location ends with <filename>ust</filename> (e.g. |
1310 | <filename>/usr/mysession/ust</filename>.</para></listitem> | 1310 | <filename>/usr/mysession/ust</filename>.</para></listitem> |
1311 | <listitem><para>Click <filename>OK</filename> to complete the import process. | 1311 | <listitem><para>Click <filename>OK</filename> to complete the import process. |
1312 | The data is now in the local tracing project you created.</para></listitem> | 1312 | The data is now in the local tracing project you created.</para></listitem> |
1313 | <listitem><para>Right click on the data and then use the menu to | 1313 | <listitem><para>Right click on the data and then use the menu to |
1314 | <filename>Select Trace Type... -> Common Trace Format -> Generic CTF Trace</filename> | 1314 | <filename>Select Trace Type... -> Common Trace Format -> Generic CTF Trace</filename> |
1315 | to map the tracing type.</para></listitem> | 1315 | to map the tracing type.</para></listitem> |
1316 | <listitem><para>Right click the mouse and select <filename>Open</filename> | 1316 | <listitem><para>Right click the mouse and select <filename>Open</filename> |
1317 | to bring up the Eclipse <filename>Lttng</filename> Trace Viewer so you | 1317 | to bring up the Eclipse <filename>Lttng</filename> Trace Viewer so you |
1318 | view the tracing data.</para></listitem> | 1318 | view the tracing data.</para></listitem> |
1319 | </orderedlist></para></listitem> | 1319 | </orderedlist></para></listitem> |
1320 | <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs | 1320 | <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs |
1321 | <filename>powertop</filename> on the remote target machine and displays the results in a | 1321 | <filename>powertop</filename> on the remote target machine and displays the results in a |
1322 | new view called <filename>powertop</filename>.</para> | 1322 | new view called <filename>powertop</filename>.</para> |
1323 | <para><filename>Time to gather data(sec):</filename> is the time passed in seconds before data | 1323 | <para><filename>Time to gather data(sec):</filename> is the time passed in seconds before data |
1324 | is gathered from the remote target for analysis.</para> | 1324 | is gathered from the remote target for analysis.</para> |
1325 | <para><filename>show pids in wakeups list:</filename> corresponds to the | 1325 | <para><filename>show pids in wakeups list:</filename> corresponds to the |
1326 | <filename>-p</filename> argument | 1326 | <filename>-p</filename> argument |
1327 | passed to <filename>powertop</filename>.</para></listitem> | 1327 | passed to <filename>powertop</filename>.</para></listitem> |
1328 | <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> | 1328 | <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> |
1329 | <filename>latencytop</filename> identifies system latency, while | 1329 | <filename>latencytop</filename> identifies system latency, while |
1330 | <filename>perf</filename> monitors the system's | 1330 | <filename>perf</filename> monitors the system's |
1331 | performance counter registers. | 1331 | performance counter registers. |
1332 | Selecting either of these tools causes an RSE terminal view to appear | 1332 | Selecting either of these tools causes an RSE terminal view to appear |
1333 | from which you can run the tools. | 1333 | from which you can run the tools. |
1334 | Both tools refresh the entire screen to display results while they run.</para></listitem> | 1334 | Both tools refresh the entire screen to display results while they run.</para></listitem> |
1335 | </itemizedlist> | 1335 | </itemizedlist> |
1336 | </para> | 1336 | </para> |
1337 | </section> | 1337 | </section> |
1338 | 1338 | ||
1339 | <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'> | 1339 | <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'> |
1340 | <title>Customizing an Image Using a BitBake Commander Project and Hob</title> | 1340 | <title>Customizing an Image Using a BitBake Commander Project and Hob</title> |
1341 | 1341 | ||
1342 | <para> | 1342 | <para> |
1343 | Within Eclipse, you can create a Yocto BitBake Commander project, | 1343 | Within Eclipse, you can create a Yocto BitBake Commander project, |
1344 | edit the metadata, and then use the | 1344 | edit the metadata, and then use the |
1345 | <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build a customized | 1345 | <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build a customized |
1346 | image all within one IDE. | 1346 | image all within one IDE. |
1347 | </para> | 1347 | </para> |
1348 | 1348 | ||
@@ -1354,17 +1354,17 @@ directory.</para></listitem> | |||
1354 | <orderedlist> | 1354 | <orderedlist> |
1355 | <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> | 1355 | <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> |
1356 | and then choose <filename>Bitbake Commander</filename>.</para></listitem> | 1356 | and then choose <filename>Bitbake Commander</filename>.</para></listitem> |
1357 | <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective into the | 1357 | <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective into the |
1358 | Bitbake Commander perspective.</para></listitem> | 1358 | Bitbake Commander perspective.</para></listitem> |
1359 | <listitem><para>Select <filename>File -> New -> Project</filename> to create a new Yocto | 1359 | <listitem><para>Select <filename>File -> New -> Project</filename> to create a new Yocto |
1360 | Bitbake Commander project.</para></listitem> | 1360 | Bitbake Commander project.</para></listitem> |
1361 | <listitem><para>Choose <filename>Yocto Project Bitbake Commander -> New Yocto Project</filename> | 1361 | <listitem><para>Choose <filename>Yocto Project Bitbake Commander -> New Yocto Project</filename> |
1362 | and click <filename>Next</filename>.</para></listitem> | 1362 | and click <filename>Next</filename>.</para></listitem> |
1363 | <listitem><para>Enter the Project Name and choose the Project Location. | 1363 | <listitem><para>Enter the Project Name and choose the Project Location. |
1364 | The Yocto project's metadata files will be put under the directory | 1364 | The Yocto project's metadata files will be put under the directory |
1365 | <filename><project_location>/<project_name></filename>. | 1365 | <filename><project_location>/<project_name></filename>. |
1366 | If that directory does not exist, you need to check | 1366 | If that directory does not exist, you need to check |
1367 | the "Clone from Yocto Git Repository" box, which would execute a | 1367 | the "Clone from Yocto Git Repository" box, which would execute a |
1368 | <filename>git clone</filename> command to get the project's metadata files. | 1368 | <filename>git clone</filename> command to get the project's metadata files. |
1369 | </para></listitem> | 1369 | </para></listitem> |
1370 | <listitem><para>Select <filename>Finish</filename> to create the project.</para></listitem> | 1370 | <listitem><para>Select <filename>Finish</filename> to create the project.</para></listitem> |
@@ -1379,7 +1379,7 @@ directory.</para></listitem> | |||
1379 | After you create the Yocto Bitbake Commander project, you can modify the metadata files | 1379 | After you create the Yocto Bitbake Commander project, you can modify the metadata files |
1380 | by opening them in the project. | 1380 | by opening them in the project. |
1381 | When editing recipe files (<filename>.bb</filename> files), you can view BitBake | 1381 | When editing recipe files (<filename>.bb</filename> files), you can view BitBake |
1382 | variable values and information by hovering the mouse pointer over the variable name and | 1382 | variable values and information by hovering the mouse pointer over the variable name and |
1383 | waiting a few seconds. | 1383 | waiting a few seconds. |
1384 | </para> | 1384 | </para> |
1385 | 1385 | ||
@@ -1390,13 +1390,13 @@ directory.</para></listitem> | |||
1390 | <listitem><para>Select <filename>File -> New -> Yocto BitBake Commander -> BitBake Recipe</filename> | 1390 | <listitem><para>Select <filename>File -> New -> Yocto BitBake Commander -> BitBake Recipe</filename> |
1391 | to open a new recipe wizard.</para></listitem> | 1391 | to open a new recipe wizard.</para></listitem> |
1392 | <listitem><para>Point to your source by filling in the "SRC_URL" field. | 1392 | <listitem><para>Point to your source by filling in the "SRC_URL" field. |
1393 | For example, you can add a recipe to your | 1393 | For example, you can add a recipe to your |
1394 | <link linkend='source-directory'>Source Directory</link> | 1394 | <link linkend='source-directory'>Source Directory</link> |
1395 | by defining "SRC_URL" as follows: | 1395 | by defining "SRC_URL" as follows: |
1396 | <literallayout class='monospaced'> | 1396 | <literallayout class='monospaced'> |
1397 | ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz | 1397 | ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz |
1398 | </literallayout></para></listitem> | 1398 | </literallayout></para></listitem> |
1399 | <listitem><para>Click "Populate" to calculate the archive md5, sha256, | 1399 | <listitem><para>Click "Populate" to calculate the archive md5, sha256, |
1400 | license checksum values and to auto-generate the recipe filename.</para></listitem> | 1400 | license checksum values and to auto-generate the recipe filename.</para></listitem> |
1401 | <listitem><para>Fill in the "Description" field.</para></listitem> | 1401 | <listitem><para>Fill in the "Description" field.</para></listitem> |
1402 | <listitem><para>Be sure values for all required fields exist.</para></listitem> | 1402 | <listitem><para>Be sure values for all required fields exist.</para></listitem> |
@@ -1415,9 +1415,9 @@ directory.</para></listitem> | |||
1415 | <listitem><para>Select <filename>Project -> Launch HOB</filename>.</para></listitem> | 1415 | <listitem><para>Select <filename>Project -> Launch HOB</filename>.</para></listitem> |
1416 | <listitem><para>Enter the Build Directory where you want to put your final images.</para></listitem> | 1416 | <listitem><para>Enter the Build Directory where you want to put your final images.</para></listitem> |
1417 | <listitem><para>Click <filename>OK</filename> to launch Hob.</para></listitem> | 1417 | <listitem><para>Click <filename>OK</filename> to launch Hob.</para></listitem> |
1418 | <listitem><para>Use Hob to customize and build your own images. | 1418 | <listitem><para>Use Hob to customize and build your own images. |
1419 | For information on Hob, see the | 1419 | For information on Hob, see the |
1420 | <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob Project Page</ulink> on the | 1420 | <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob Project Page</ulink> on the |
1421 | Yocto Project website.</para></listitem> | 1421 | Yocto Project website.</para></listitem> |
1422 | </orderedlist> | 1422 | </orderedlist> |
1423 | </para> | 1423 | </para> |
@@ -1429,44 +1429,44 @@ directory.</para></listitem> | |||
1429 | <title>Workflow Using Stand-alone Cross-development Toolchains</title> | 1429 | <title>Workflow Using Stand-alone Cross-development Toolchains</title> |
1430 | 1430 | ||
1431 | <para> | 1431 | <para> |
1432 | If you want to develop an application without prior installation of the ADT, you | 1432 | If you want to develop an application without prior installation of the ADT, you |
1433 | still can employ the cross-development toolchain, the QEMU emulator, and a number of supported | 1433 | still can employ the cross-development toolchain, the QEMU emulator, and a number of supported |
1434 | target image files. | 1434 | target image files. |
1435 | You just need to follow these general steps: | 1435 | You just need to follow these general steps: |
1436 | <orderedlist> | 1436 | <orderedlist> |
1437 | <listitem><para><emphasis>Install the cross-development toolchain for your target hardware:</emphasis> | 1437 | <listitem><para><emphasis>Install the cross-development toolchain for your target hardware:</emphasis> |
1438 | For information on how to install the toolchain, see the | 1438 | For information on how to install the toolchain, see the |
1439 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" | 1439 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" |
1440 | section | 1440 | section |
1441 | in the Yocto Project Application Developer's Guide.</para></listitem> | 1441 | in the Yocto Project Application Developer's Guide.</para></listitem> |
1442 | <listitem><para><emphasis>Download the Target Image:</emphasis> The Yocto Project supports | 1442 | <listitem><para><emphasis>Download the Target Image:</emphasis> The Yocto Project supports |
1443 | several target architectures and has many pre-built kernel images and root filesystem | 1443 | several target architectures and has many pre-built kernel images and root filesystem |
1444 | images.</para> | 1444 | images.</para> |
1445 | <para>If you are going to develop your application on hardware, go to the | 1445 | <para>If you are going to develop your application on hardware, go to the |
1446 | <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> | 1446 | <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> |
1447 | download area and choose a target machine area | 1447 | download area and choose a target machine area |
1448 | from which to download the kernel image and root filesystem. | 1448 | from which to download the kernel image and root filesystem. |
1449 | This download area could have several files in it that support development using | 1449 | This download area could have several files in it that support development using |
1450 | actual hardware. | 1450 | actual hardware. |
1451 | For example, the area might contain <filename>.hddimg</filename> files that combine the | 1451 | For example, the area might contain <filename>.hddimg</filename> files that combine the |
1452 | kernel image with the filesystem, boot loaders, etc. | 1452 | kernel image with the filesystem, boot loaders, etc. |
1453 | Be sure to get the files you need for your particular development process.</para> | 1453 | Be sure to get the files you need for your particular development process.</para> |
1454 | <para>If you are going to develop your application and then run and test it using the QEMU | 1454 | <para>If you are going to develop your application and then run and test it using the QEMU |
1455 | emulator, go to the | 1455 | emulator, go to the |
1456 | <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink> | 1456 | <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink> |
1457 | download area. | 1457 | download area. |
1458 | From this area, go down into the directory for your target architecture | 1458 | From this area, go down into the directory for your target architecture |
1459 | (e.g. <filename>qemux86_64</filename> for an | 1459 | (e.g. <filename>qemux86_64</filename> for an |
1460 | <trademark class='registered'>Intel</trademark>-based 64-bit architecture). | 1460 | <trademark class='registered'>Intel</trademark>-based 64-bit architecture). |
1461 | Download kernel, root filesystem, and any other files you need for your process. | 1461 | Download kernel, root filesystem, and any other files you need for your process. |
1462 | <note>In order to use the root filesystem in QEMU, you need to extract it. | 1462 | <note>In order to use the root filesystem in QEMU, you need to extract it. |
1463 | See the | 1463 | See the |
1464 | "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>" | 1464 | "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>" |
1465 | section for information on how to extract the root filesystem.</note></para></listitem> | 1465 | section for information on how to extract the root filesystem.</note></para></listitem> |
1466 | <listitem><para><emphasis>Develop and Test your Application:</emphasis> At this point, | 1466 | <listitem><para><emphasis>Develop and Test your Application:</emphasis> At this point, |
1467 | you have the tools to develop your application. | 1467 | you have the tools to develop your application. |
1468 | If you need to separately install and use the QEMU emulator, you can go to | 1468 | If you need to separately install and use the QEMU emulator, you can go to |
1469 | <ulink url='http://www.qemu.org'>QEMU Home Page</ulink> to download and learn about the | 1469 | <ulink url='http://www.qemu.org'>QEMU Home Page</ulink> to download and learn about the |
1470 | emulator.</para></listitem> | 1470 | emulator.</para></listitem> |
1471 | </orderedlist> | 1471 | </orderedlist> |
1472 | </para> | 1472 | </para> |
@@ -1482,14 +1482,14 @@ directory.</para></listitem> | |||
1482 | to build packages. | 1482 | to build packages. |
1483 | For example, suppose you are developing a patch and you need to experiment a bit | 1483 | For example, suppose you are developing a patch and you need to experiment a bit |
1484 | to figure out your solution. | 1484 | to figure out your solution. |
1485 | After you have initially built the package, you can iteratively tweak the | 1485 | After you have initially built the package, you can iteratively tweak the |
1486 | source code, which is located in the | 1486 | source code, which is located in the |
1487 | <link linkend='build-directory'>Build Directory</link>, and then | 1487 | <link linkend='build-directory'>Build Directory</link>, and then |
1488 | you can force a re-compile and quickly test your altered code. | 1488 | you can force a re-compile and quickly test your altered code. |
1489 | Once you settle on a solution, you can then preserve your changes in the form of | 1489 | Once you settle on a solution, you can then preserve your changes in the form of |
1490 | patches. | 1490 | patches. |
1491 | You can accomplish these steps all within either a | 1491 | You can accomplish these steps all within either a |
1492 | <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or | 1492 | <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or |
1493 | <link linkend='git'>Git</link> workflow. | 1493 | <link linkend='git'>Git</link> workflow. |
1494 | </para> | 1494 | </para> |
1495 | 1495 | ||
@@ -1497,18 +1497,18 @@ directory.</para></listitem> | |||
1497 | <title>Finding the Temporary Source Code</title> | 1497 | <title>Finding the Temporary Source Code</title> |
1498 | 1498 | ||
1499 | <para> | 1499 | <para> |
1500 | During a build, the unpacked temporary source code used by recipes | 1500 | During a build, the unpacked temporary source code used by recipes |
1501 | to build packages is available in the Build Directory as | 1501 | to build packages is available in the Build Directory as |
1502 | defined by the | 1502 | defined by the |
1503 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable. | 1503 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable. |
1504 | Below is the default value for the <filename>S</filename> variable as defined in the | 1504 | Below is the default value for the <filename>S</filename> variable as defined in the |
1505 | <filename>meta/conf/bitbake.conf</filename> configuration file in the | 1505 | <filename>meta/conf/bitbake.conf</filename> configuration file in the |
1506 | <link linkend='source-directory'>Source Directory</link>: | 1506 | <link linkend='source-directory'>Source Directory</link>: |
1507 | <literallayout class='monospaced'> | 1507 | <literallayout class='monospaced'> |
1508 | S = ${WORKDIR}/${BP} | 1508 | S = ${WORKDIR}/${BP} |
1509 | </literallayout> | 1509 | </literallayout> |
1510 | You should be aware that many recipes override the <filename>S</filename> variable. | 1510 | You should be aware that many recipes override the <filename>S</filename> variable. |
1511 | For example, recipes that fetch their source from Git usually set | 1511 | For example, recipes that fetch their source from Git usually set |
1512 | <filename>S</filename> to <filename>${WORKDIR}/git</filename>. | 1512 | <filename>S</filename> to <filename>${WORKDIR}/git</filename>. |
1513 | <note> | 1513 | <note> |
1514 | The | 1514 | The |
@@ -1517,11 +1517,11 @@ directory.</para></listitem> | |||
1517 | <literallayout class='monospaced'> | 1517 | <literallayout class='monospaced'> |
1518 | BP = ${BPN}-${PV} | 1518 | BP = ${BPN}-${PV} |
1519 | </literallayout> | 1519 | </literallayout> |
1520 | </note> | 1520 | </note> |
1521 | </para> | 1521 | </para> |
1522 | 1522 | ||
1523 | <para> | 1523 | <para> |
1524 | The path to the work directory for the recipe | 1524 | The path to the work directory for the recipe |
1525 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) depends | 1525 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) depends |
1526 | on the recipe name and the architecture of the target device. | 1526 | on the recipe name and the architecture of the target device. |
1527 | For example, here is the work directory for recipes and resulting packages that are | 1527 | For example, here is the work directory for recipes and resulting packages that are |
@@ -1532,8 +1532,8 @@ directory.</para></listitem> | |||
1532 | Let's look at an example without variables. | 1532 | Let's look at an example without variables. |
1533 | Assuming a top-level <link linkend='source-directory'>Source Directory</link> | 1533 | Assuming a top-level <link linkend='source-directory'>Source Directory</link> |
1534 | named <filename>poky</filename> | 1534 | named <filename>poky</filename> |
1535 | and a default Build Directory of <filename>poky/build</filename>, | 1535 | and a default Build Directory of <filename>poky/build</filename>, |
1536 | the following is the work directory for the <filename>acl</filename> recipe that | 1536 | the following is the work directory for the <filename>acl</filename> recipe that |
1537 | creates the <filename>acl</filename> package: | 1537 | creates the <filename>acl</filename> package: |
1538 | <literallayout class='monospaced'> | 1538 | <literallayout class='monospaced'> |
1539 | ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 | 1539 | ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 |
@@ -1541,15 +1541,15 @@ directory.</para></listitem> | |||
1541 | </para> | 1541 | </para> |
1542 | 1542 | ||
1543 | <para> | 1543 | <para> |
1544 | If your resulting package is dependent on the target device, | 1544 | If your resulting package is dependent on the target device, |
1545 | the work directory varies slightly: | 1545 | the work directory varies slightly: |
1546 | <literallayout class='monospaced'> | 1546 | <literallayout class='monospaced'> |
1547 | ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} | 1547 | ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} |
1548 | </literallayout> | 1548 | </literallayout> |
1549 | Again, assuming top-level Source Directory named <filename>poky</filename> | 1549 | Again, assuming top-level Source Directory named <filename>poky</filename> |
1550 | and a default Build Directory of <filename>poky/build</filename>, the | 1550 | and a default Build Directory of <filename>poky/build</filename>, the |
1551 | following are the work and temporary source directories, respectively, | 1551 | following are the work and temporary source directories, respectively, |
1552 | for the <filename>acl</filename> package that is being | 1552 | for the <filename>acl</filename> package that is being |
1553 | built for a MIPS-based device: | 1553 | built for a MIPS-based device: |
1554 | <literallayout class='monospaced'> | 1554 | <literallayout class='monospaced'> |
1555 | ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 | 1555 | ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 |
@@ -1558,7 +1558,7 @@ directory.</para></listitem> | |||
1558 | </para> | 1558 | </para> |
1559 | 1559 | ||
1560 | <note> | 1560 | <note> |
1561 | To better understand how the OpenEmbedded build system resolves directories during the | 1561 | To better understand how the OpenEmbedded build system resolves directories during the |
1562 | build process, see the glossary entries for the | 1562 | build process, see the glossary entries for the |
1563 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>, | 1563 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>, |
1564 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>, | 1564 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>, |
@@ -1573,20 +1573,20 @@ directory.</para></listitem> | |||
1573 | </note> | 1573 | </note> |
1574 | 1574 | ||
1575 | <para> | 1575 | <para> |
1576 | Now that you know where to locate the directory that has the temporary source code, | 1576 | Now that you know where to locate the directory that has the temporary source code, |
1577 | you can use a Quilt or Git workflow to make your edits, test the changes, | 1577 | you can use a Quilt or Git workflow to make your edits, test the changes, |
1578 | and preserve the changes in the form of patches. | 1578 | and preserve the changes in the form of patches. |
1579 | </para> | 1579 | </para> |
1580 | </section> | 1580 | </section> |
1581 | 1581 | ||
1582 | <section id="using-a-quilt-workflow"> | 1582 | <section id="using-a-quilt-workflow"> |
1583 | <title>Using a Quilt Workflow</title> | 1583 | <title>Using a Quilt Workflow</title> |
1584 | 1584 | ||
1585 | <para> | 1585 | <para> |
1586 | <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> | 1586 | <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> |
1587 | is a powerful tool that allows you to capture source code changes without having | 1587 | is a powerful tool that allows you to capture source code changes without having |
1588 | a clean source tree. | 1588 | a clean source tree. |
1589 | This section outlines the typical workflow you can use to modify temporary source code, | 1589 | This section outlines the typical workflow you can use to modify temporary source code, |
1590 | test changes, and then preserve the changes in the form of a patch all using Quilt. | 1590 | test changes, and then preserve the changes in the form of a patch all using Quilt. |
1591 | </para> | 1591 | </para> |
1592 | 1592 | ||
@@ -1594,15 +1594,15 @@ directory.</para></listitem> | |||
1594 | Follow these general steps: | 1594 | Follow these general steps: |
1595 | <orderedlist> | 1595 | <orderedlist> |
1596 | <listitem><para><emphasis>Find the Source Code:</emphasis> | 1596 | <listitem><para><emphasis>Find the Source Code:</emphasis> |
1597 | The temporary source code used by the OpenEmbedded build system is kept in the | 1597 | The temporary source code used by the OpenEmbedded build system is kept in the |
1598 | Build Directory. | 1598 | Build Directory. |
1599 | See the | 1599 | See the |
1600 | "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" | 1600 | "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" |
1601 | section to learn how to locate the directory that has the temporary source code for a | 1601 | section to learn how to locate the directory that has the temporary source code for a |
1602 | particular package.</para></listitem> | 1602 | particular package.</para></listitem> |
1603 | <listitem><para><emphasis>Change Your Working Directory:</emphasis> | 1603 | <listitem><para><emphasis>Change Your Working Directory:</emphasis> |
1604 | You need to be in the directory that has the temporary source code. | 1604 | You need to be in the directory that has the temporary source code. |
1605 | That directory is defined by the | 1605 | That directory is defined by the |
1606 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> | 1606 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> |
1607 | variable.</para></listitem> | 1607 | variable.</para></listitem> |
1608 | <listitem><para><emphasis>Create a New Patch:</emphasis> | 1608 | <listitem><para><emphasis>Create a New Patch:</emphasis> |
@@ -1612,7 +1612,7 @@ directory.</para></listitem> | |||
1612 | $ quilt new my_changes.patch | 1612 | $ quilt new my_changes.patch |
1613 | </literallayout></para></listitem> | 1613 | </literallayout></para></listitem> |
1614 | <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis> | 1614 | <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis> |
1615 | After creating the patch, you need to notify Quilt about the files | 1615 | After creating the patch, you need to notify Quilt about the files |
1616 | you plan to edit. | 1616 | you plan to edit. |
1617 | You notify Quilt by adding the files to the patch you just created: | 1617 | You notify Quilt by adding the files to the patch you just created: |
1618 | <literallayout class='monospaced'> | 1618 | <literallayout class='monospaced'> |
@@ -1623,50 +1623,50 @@ directory.</para></listitem> | |||
1623 | Make your changes in the temporary source code to the files you added | 1623 | Make your changes in the temporary source code to the files you added |
1624 | to the patch.</para></listitem> | 1624 | to the patch.</para></listitem> |
1625 | <listitem><para><emphasis>Test Your Changes:</emphasis> | 1625 | <listitem><para><emphasis>Test Your Changes:</emphasis> |
1626 | Once you have modified the source code, the easiest way to test your changes | 1626 | Once you have modified the source code, the easiest way to test your changes |
1627 | is by calling the <filename>compile</filename> task as shown in the following example: | 1627 | is by calling the <filename>compile</filename> task as shown in the following example: |
1628 | <literallayout class='monospaced'> | 1628 | <literallayout class='monospaced'> |
1629 | $ bitbake -c compile -f <name_of_package> | 1629 | $ bitbake -c compile -f <name_of_package> |
1630 | </literallayout> | 1630 | </literallayout> |
1631 | The <filename>-f</filename> or <filename>--force</filename> | 1631 | The <filename>-f</filename> or <filename>--force</filename> |
1632 | option forces re-execution of the specified task. | 1632 | option forces re-execution of the specified task. |
1633 | If you find problems with your code, you can just keep editing and | 1633 | If you find problems with your code, you can just keep editing and |
1634 | re-testing iteratively until things work as expected. | 1634 | re-testing iteratively until things work as expected. |
1635 | <note>All the modifications you make to the temporary source code | 1635 | <note>All the modifications you make to the temporary source code |
1636 | disappear once you <filename>-c clean</filename> or | 1636 | disappear once you <filename>-c clean</filename> or |
1637 | <filename>-c cleanall</filename> with BitBake for the package. | 1637 | <filename>-c cleanall</filename> with BitBake for the package. |
1638 | Modifications will also disappear if you use the <filename>rm_work</filename> | 1638 | Modifications will also disappear if you use the <filename>rm_work</filename> |
1639 | feature as described in the | 1639 | feature as described in the |
1640 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | 1640 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" |
1641 | section of the Yocto Project Quick Start. | 1641 | section of the Yocto Project Quick Start. |
1642 | </note></para></listitem> | 1642 | </note></para></listitem> |
1643 | <listitem><para><emphasis>Generate the Patch:</emphasis> | 1643 | <listitem><para><emphasis>Generate the Patch:</emphasis> |
1644 | Once your changes work as expected, you need to use Quilt to generate the final patch that | 1644 | Once your changes work as expected, you need to use Quilt to generate the final patch that |
1645 | contains all your modifications. | 1645 | contains all your modifications. |
1646 | <literallayout class='monospaced'> | 1646 | <literallayout class='monospaced'> |
1647 | $ quilt refresh | 1647 | $ quilt refresh |
1648 | </literallayout> | 1648 | </literallayout> |
1649 | At this point the <filename>my_changes.patch</filename> file has all your edits made | 1649 | At this point the <filename>my_changes.patch</filename> file has all your edits made |
1650 | to the <filename>file1.c</filename>, <filename>file2.c</filename>, and | 1650 | to the <filename>file1.c</filename>, <filename>file2.c</filename>, and |
1651 | <filename>file3.c</filename> files.</para> | 1651 | <filename>file3.c</filename> files.</para> |
1652 | <para>You can find the resulting patch file in the <filename>patches/</filename> | 1652 | <para>You can find the resulting patch file in the <filename>patches/</filename> |
1653 | subdirectory of the source (<filename>S</filename>) directory.</para></listitem> | 1653 | subdirectory of the source (<filename>S</filename>) directory.</para></listitem> |
1654 | <listitem><para><emphasis>Copy the Patch File:</emphasis> | 1654 | <listitem><para><emphasis>Copy the Patch File:</emphasis> |
1655 | For simplicity, copy the patch file into a directory named <filename>files</filename>, | 1655 | For simplicity, copy the patch file into a directory named <filename>files</filename>, |
1656 | which you can create in the same directory that holds the recipe | 1656 | which you can create in the same directory that holds the recipe |
1657 | (<filename>.bb</filename>) file or the | 1657 | (<filename>.bb</filename>) file or the |
1658 | append (<filename>.bbappend</filename>) file. | 1658 | append (<filename>.bbappend</filename>) file. |
1659 | Placing the patch here guarantees that the OpenEmbedded build system will find | 1659 | Placing the patch here guarantees that the OpenEmbedded build system will find |
1660 | the patch. | 1660 | the patch. |
1661 | Next, add the patch into the | 1661 | Next, add the patch into the |
1662 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> | 1662 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> |
1663 | of the recipe. | 1663 | of the recipe. |
1664 | Here is an example: | 1664 | Here is an example: |
1665 | <literallayout class='monospaced'> | 1665 | <literallayout class='monospaced'> |
1666 | SRC_URI += "file://my_changes.patch" | 1666 | SRC_URI += "file://my_changes.patch" |
1667 | </literallayout></para></listitem> | 1667 | </literallayout></para></listitem> |
1668 | <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis> | 1668 | <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis> |
1669 | Finally, don't forget to 'bump' the | 1669 | Finally, don't forget to 'bump' the |
1670 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> | 1670 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> |
1671 | value in the recipe since the resulting packages have changed.</para></listitem> | 1671 | value in the recipe since the resulting packages have changed.</para></listitem> |
1672 | </orderedlist> | 1672 | </orderedlist> |
@@ -1675,16 +1675,16 @@ directory.</para></listitem> | |||
1675 | <section id='using-a-git-workflow'> | 1675 | <section id='using-a-git-workflow'> |
1676 | <title>Using a Git Workflow</title> | 1676 | <title>Using a Git Workflow</title> |
1677 | <para> | 1677 | <para> |
1678 | Git is an even more powerful tool that allows you to capture source code changes without having | 1678 | Git is an even more powerful tool that allows you to capture source code changes without having |
1679 | a clean source tree. | 1679 | a clean source tree. |
1680 | This section outlines the typical workflow you can use to modify temporary source code, | 1680 | This section outlines the typical workflow you can use to modify temporary source code, |
1681 | test changes, and then preserve the changes in the form of a patch all using Git. | 1681 | test changes, and then preserve the changes in the form of a patch all using Git. |
1682 | For general information on Git as it is used in the Yocto Project, see the | 1682 | For general information on Git as it is used in the Yocto Project, see the |
1683 | "<link linkend='git'>Git</link>" section. | 1683 | "<link linkend='git'>Git</link>" section. |
1684 | </para> | 1684 | </para> |
1685 | 1685 | ||
1686 | <note> | 1686 | <note> |
1687 | This workflow uses Git only for its ability to manage local changes to the source code | 1687 | This workflow uses Git only for its ability to manage local changes to the source code |
1688 | and produce patches independent of any version control system used with the Yocto Project. | 1688 | and produce patches independent of any version control system used with the Yocto Project. |
1689 | </note> | 1689 | </note> |
1690 | 1690 | ||
@@ -1692,53 +1692,53 @@ directory.</para></listitem> | |||
1692 | Follow these general steps: | 1692 | Follow these general steps: |
1693 | <orderedlist> | 1693 | <orderedlist> |
1694 | <listitem><para><emphasis>Find the Source Code:</emphasis> | 1694 | <listitem><para><emphasis>Find the Source Code:</emphasis> |
1695 | The temporary source code used by the OpenEmbedded build system is kept in the | 1695 | The temporary source code used by the OpenEmbedded build system is kept in the |
1696 | Build Directory. | 1696 | Build Directory. |
1697 | See the | 1697 | See the |
1698 | "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" | 1698 | "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" |
1699 | section to learn how to locate the directory that has the temporary source code for a | 1699 | section to learn how to locate the directory that has the temporary source code for a |
1700 | particular package.</para></listitem> | 1700 | particular package.</para></listitem> |
1701 | <listitem><para><emphasis>Change Your Working Directory:</emphasis> | 1701 | <listitem><para><emphasis>Change Your Working Directory:</emphasis> |
1702 | You need to be in the directory that has the temporary source code. | 1702 | You need to be in the directory that has the temporary source code. |
1703 | That directory is defined by the | 1703 | That directory is defined by the |
1704 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> | 1704 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> |
1705 | variable.</para></listitem> | 1705 | variable.</para></listitem> |
1706 | <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis> | 1706 | <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis> |
1707 | If the recipe you are working with does not use a Git fetcher, | 1707 | If the recipe you are working with does not use a Git fetcher, |
1708 | you need to set up a Git repository as follows: | 1708 | you need to set up a Git repository as follows: |
1709 | <literallayout class='monospaced'> | 1709 | <literallayout class='monospaced'> |
1710 | $ git init | 1710 | $ git init |
1711 | $ git add * | 1711 | $ git add * |
1712 | $ git commit -m "initial revision" | 1712 | $ git commit -m "initial revision" |
1713 | </literallayout> | 1713 | </literallayout> |
1714 | The above Git commands initialize a Git repository that is based on the | 1714 | The above Git commands initialize a Git repository that is based on the |
1715 | files in your current working directory, stage all the files, and commit | 1715 | files in your current working directory, stage all the files, and commit |
1716 | the files. | 1716 | the files. |
1717 | At this point, your Git repository is aware of all the source code files. | 1717 | At this point, your Git repository is aware of all the source code files. |
1718 | Any edits you now make to files can be committed later and will be tracked by | 1718 | Any edits you now make to files can be committed later and will be tracked by |
1719 | Git.</para></listitem> | 1719 | Git.</para></listitem> |
1720 | <listitem><para><emphasis>Edit the Files:</emphasis> | 1720 | <listitem><para><emphasis>Edit the Files:</emphasis> |
1721 | Make your changes to the temporary source code.</para></listitem> | 1721 | Make your changes to the temporary source code.</para></listitem> |
1722 | <listitem><para><emphasis>Test Your Changes:</emphasis> | 1722 | <listitem><para><emphasis>Test Your Changes:</emphasis> |
1723 | Once you have modified the source code, the easiest way to test your changes | 1723 | Once you have modified the source code, the easiest way to test your changes |
1724 | is by calling the <filename>compile</filename> task as shown in the following example: | 1724 | is by calling the <filename>compile</filename> task as shown in the following example: |
1725 | <literallayout class='monospaced'> | 1725 | <literallayout class='monospaced'> |
1726 | $ bitbake -c compile -f <name_of_package> | 1726 | $ bitbake -c compile -f <name_of_package> |
1727 | </literallayout> | 1727 | </literallayout> |
1728 | The <filename>-f</filename> or <filename>--force</filename> | 1728 | The <filename>-f</filename> or <filename>--force</filename> |
1729 | option forces re-execution of the specified task. | 1729 | option forces re-execution of the specified task. |
1730 | If you find problems with your code, you can just keep editing and | 1730 | If you find problems with your code, you can just keep editing and |
1731 | re-testing iteratively until things work as expected. | 1731 | re-testing iteratively until things work as expected. |
1732 | <note>All the modifications you make to the temporary source code | 1732 | <note>All the modifications you make to the temporary source code |
1733 | disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>, | 1733 | disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>, |
1734 | or <filename>-c cleanall</filename> with BitBake for the package. | 1734 | or <filename>-c cleanall</filename> with BitBake for the package. |
1735 | Modifications will also disappear if you use the <filename>rm_work</filename> | 1735 | Modifications will also disappear if you use the <filename>rm_work</filename> |
1736 | feature as described in the | 1736 | feature as described in the |
1737 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | 1737 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" |
1738 | section of the Yocto Project Quick Start. | 1738 | section of the Yocto Project Quick Start. |
1739 | </note></para></listitem> | 1739 | </note></para></listitem> |
1740 | <listitem><para><emphasis>See the List of Files You Changed:</emphasis> | 1740 | <listitem><para><emphasis>See the List of Files You Changed:</emphasis> |
1741 | Use the <filename>git status</filename> command to see what files you have actually edited. | 1741 | Use the <filename>git status</filename> command to see what files you have actually edited. |
1742 | The ability to have Git track the files you have changed is an advantage that this | 1742 | The ability to have Git track the files you have changed is an advantage that this |
1743 | workflow has over the Quilt workflow. | 1743 | workflow has over the Quilt workflow. |
1744 | Here is the Git command to list your changed files: | 1744 | Here is the Git command to list your changed files: |
@@ -1752,15 +1752,15 @@ directory.</para></listitem> | |||
1752 | $ git add file1.c file2.c file3.c | 1752 | $ git add file1.c file2.c file3.c |
1753 | </literallayout></para></listitem> | 1753 | </literallayout></para></listitem> |
1754 | <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis> | 1754 | <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis> |
1755 | Use the <filename>git commit</filename> command to commit the changes to the | 1755 | Use the <filename>git commit</filename> command to commit the changes to the |
1756 | local repository. | 1756 | local repository. |
1757 | Once you have committed the files, you can use the <filename>git log</filename> | 1757 | Once you have committed the files, you can use the <filename>git log</filename> |
1758 | command to see your changes: | 1758 | command to see your changes: |
1759 | <literallayout class='monospaced'> | 1759 | <literallayout class='monospaced'> |
1760 | $ git commit -m "<commit-summary-message>" | 1760 | $ git commit -m "<commit-summary-message>" |
1761 | $ git log | 1761 | $ git log |
1762 | </literallayout> | 1762 | </literallayout> |
1763 | <note>The name of the patch file created in the next step is based on your | 1763 | <note>The name of the patch file created in the next step is based on your |
1764 | <filename>commit-summary-message</filename>.</note></para></listitem> | 1764 | <filename>commit-summary-message</filename>.</note></para></listitem> |
1765 | <listitem><para><emphasis>Generate the Patch:</emphasis> | 1765 | <listitem><para><emphasis>Generate the Patch:</emphasis> |
1766 | Once the changes are committed, use the <filename>git format-patch</filename> | 1766 | Once the changes are committed, use the <filename>git format-patch</filename> |
@@ -1768,30 +1768,30 @@ directory.</para></listitem> | |||
1768 | <literallayout class='monospaced'> | 1768 | <literallayout class='monospaced'> |
1769 | $ git format-patch -1 | 1769 | $ git format-patch -1 |
1770 | </literallayout> | 1770 | </literallayout> |
1771 | Specifying "-1" causes Git to generate the | 1771 | Specifying "-1" causes Git to generate the |
1772 | patch file for the most recent commit.</para> | 1772 | patch file for the most recent commit.</para> |
1773 | <para>At this point, the patch file has all your edits made | 1773 | <para>At this point, the patch file has all your edits made |
1774 | to the <filename>file1.c</filename>, <filename>file2.c</filename>, and | 1774 | to the <filename>file1.c</filename>, <filename>file2.c</filename>, and |
1775 | <filename>file3.c</filename> files. | 1775 | <filename>file3.c</filename> files. |
1776 | You can find the resulting patch file in the current directory and it | 1776 | You can find the resulting patch file in the current directory and it |
1777 | is named according to the <filename>git commit</filename> summary line. | 1777 | is named according to the <filename>git commit</filename> summary line. |
1778 | The patch file ends with <filename>.patch</filename>.</para></listitem> | 1778 | The patch file ends with <filename>.patch</filename>.</para></listitem> |
1779 | <listitem><para><emphasis>Copy the Patch File:</emphasis> | 1779 | <listitem><para><emphasis>Copy the Patch File:</emphasis> |
1780 | For simplicity, copy the patch file into a directory named <filename>files</filename>, | 1780 | For simplicity, copy the patch file into a directory named <filename>files</filename>, |
1781 | which you can create in the same directory that holds the recipe | 1781 | which you can create in the same directory that holds the recipe |
1782 | (<filename>.bb</filename>) file or the | 1782 | (<filename>.bb</filename>) file or the |
1783 | append (<filename>.bbappend</filename>) file. | 1783 | append (<filename>.bbappend</filename>) file. |
1784 | Placing the patch here guarantees that the OpenEmbedded build system will find | 1784 | Placing the patch here guarantees that the OpenEmbedded build system will find |
1785 | the patch. | 1785 | the patch. |
1786 | Next, add the patch into the | 1786 | Next, add the patch into the |
1787 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> | 1787 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> |
1788 | of the recipe. | 1788 | of the recipe. |
1789 | Here is an example: | 1789 | Here is an example: |
1790 | <literallayout class='monospaced'> | 1790 | <literallayout class='monospaced'> |
1791 | SRC_URI += "file://0001-<commit-summary-message>.patch" | 1791 | SRC_URI += "file://0001-<commit-summary-message>.patch" |
1792 | </literallayout></para></listitem> | 1792 | </literallayout></para></listitem> |
1793 | <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis> | 1793 | <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis> |
1794 | Finally, don't forget to 'bump' the | 1794 | Finally, don't forget to 'bump' the |
1795 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> | 1795 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> |
1796 | value in the recipe since the resulting packages have changed.</para></listitem> | 1796 | value in the recipe since the resulting packages have changed.</para></listitem> |
1797 | </orderedlist> | 1797 | </orderedlist> |
@@ -1803,7 +1803,7 @@ directory.</para></listitem> | |||
1803 | <title>Image Development Using Hob</title> | 1803 | <title>Image Development Using Hob</title> |
1804 | 1804 | ||
1805 | <para> | 1805 | <para> |
1806 | The <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> is a graphical user interface for the | 1806 | The <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> is a graphical user interface for the |
1807 | OpenEmbedded build system, which is based on BitBake. | 1807 | OpenEmbedded build system, which is based on BitBake. |
1808 | You can use the Hob to build custom operating system images within the Yocto Project build environment. | 1808 | You can use the Hob to build custom operating system images within the Yocto Project build environment. |
1809 | Hob simply provides a friendly interface over the build system used during system development. | 1809 | Hob simply provides a friendly interface over the build system used during system development. |
@@ -1821,13 +1821,13 @@ directory.</para></listitem> | |||
1821 | $ source oe-init-build-env | 1821 | $ source oe-init-build-env |
1822 | $ hob | 1822 | $ hob |
1823 | </literallayout></para></listitem> | 1823 | </literallayout></para></listitem> |
1824 | <listitem><para>You can set the | 1824 | <listitem><para>You can set the |
1825 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | 1825 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> |
1826 | for which you are building the image.</para></listitem> | 1826 | for which you are building the image.</para></listitem> |
1827 | <listitem><para>You can modify various policy settings such as the package format used to build with, | 1827 | <listitem><para>You can modify various policy settings such as the package format used to build with, |
1828 | the parrallelism BitBake uses, whether or not to build an external toolchain, and which host | 1828 | the parrallelism BitBake uses, whether or not to build an external toolchain, and which host |
1829 | to build against.</para></listitem> | 1829 | to build against.</para></listitem> |
1830 | <listitem><para>You can manage | 1830 | <listitem><para>You can manage |
1831 | <link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem> | 1831 | <link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem> |
1832 | <listitem><para>You can select a base image and then add extra packages for your custom build. | 1832 | <listitem><para>You can select a base image and then add extra packages for your custom build. |
1833 | </para></listitem> | 1833 | </para></listitem> |
@@ -1840,16 +1840,16 @@ directory.</para></listitem> | |||
1840 | <title>Using a Development Shell</title> | 1840 | <title>Using a Development Shell</title> |
1841 | 1841 | ||
1842 | <para> | 1842 | <para> |
1843 | When debugging certain commands or even when just editing packages, | 1843 | When debugging certain commands or even when just editing packages, |
1844 | <filename>devshell</filename> can be a useful tool. | 1844 | <filename>devshell</filename> can be a useful tool. |
1845 | When you invoke <filename>devshell</filename>, source files are | 1845 | When you invoke <filename>devshell</filename>, source files are |
1846 | extracted into your working directory and patches are applied. | 1846 | extracted into your working directory and patches are applied. |
1847 | Then, a new terminal is opened and you are placed in the working directory. | 1847 | Then, a new terminal is opened and you are placed in the working directory. |
1848 | In the new terminal, all the OpenEmbedded build-related environment variables are | 1848 | In the new terminal, all the OpenEmbedded build-related environment variables are |
1849 | still defined so you can use commands such as <filename>configure</filename> and | 1849 | still defined so you can use commands such as <filename>configure</filename> and |
1850 | <filename>make</filename>. | 1850 | <filename>make</filename>. |
1851 | The commands execute just as if the OpenEmbedded build system were executing them. | 1851 | The commands execute just as if the OpenEmbedded build system were executing them. |
1852 | Consequently, working this way can be helpful when debugging a build or preparing | 1852 | Consequently, working this way can be helpful when debugging a build or preparing |
1853 | software to be used with the OpenEmbedded build system. | 1853 | software to be used with the OpenEmbedded build system. |
1854 | </para> | 1854 | </para> |
1855 | 1855 | ||
@@ -1862,46 +1862,46 @@ directory.</para></listitem> | |||
1862 | </para> | 1862 | </para> |
1863 | 1863 | ||
1864 | <para> | 1864 | <para> |
1865 | This command spawns a terminal with a shell prompt within the OpenEmbedded build environment. | 1865 | This command spawns a terminal with a shell prompt within the OpenEmbedded build environment. |
1866 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink> | 1866 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink> |
1867 | controls what type of shell is opened. | 1867 | controls what type of shell is opened. |
1868 | </para> | 1868 | </para> |
1869 | 1869 | ||
1870 | <para> | 1870 | <para> |
1871 | For spawned terminals, the following occurs: | 1871 | For spawned terminals, the following occurs: |
1872 | <itemizedlist> | 1872 | <itemizedlist> |
1873 | <listitem><para>The <filename>PATH</filename> variable includes the | 1873 | <listitem><para>The <filename>PATH</filename> variable includes the |
1874 | cross-toolchain.</para></listitem> | 1874 | cross-toolchain.</para></listitem> |
1875 | <listitem><para>The <filename>pkgconfig</filename> variables find the correct | 1875 | <listitem><para>The <filename>pkgconfig</filename> variables find the correct |
1876 | <filename>.pc</filename> files.</para></listitem> | 1876 | <filename>.pc</filename> files.</para></listitem> |
1877 | <listitem><para>The <filename>configure</filename> command finds the | 1877 | <listitem><para>The <filename>configure</filename> command finds the |
1878 | Yocto Project site files as well as any other necessary files.</para></listitem> | 1878 | Yocto Project site files as well as any other necessary files.</para></listitem> |
1879 | </itemizedlist> | 1879 | </itemizedlist> |
1880 | </para> | 1880 | </para> |
1881 | 1881 | ||
1882 | <para> | 1882 | <para> |
1883 | Within this environment, you can run configure or compile | 1883 | Within this environment, you can run configure or compile |
1884 | commands as if they were being run by | 1884 | commands as if they were being run by |
1885 | the OpenEmbedded build system itself. | 1885 | the OpenEmbedded build system itself. |
1886 | As noted earlier, the working directory also automatically changes to the | 1886 | As noted earlier, the working directory also automatically changes to the |
1887 | Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>). | 1887 | Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>). |
1888 | </para> | 1888 | </para> |
1889 | 1889 | ||
1890 | <para> | 1890 | <para> |
1891 | When you are finished, you just exit the shell or close the terminal window. | 1891 | When you are finished, you just exit the shell or close the terminal window. |
1892 | </para> | 1892 | </para> |
1893 | 1893 | ||
1894 | <note> | 1894 | <note> |
1895 | <para> | 1895 | <para> |
1896 | It is worth remembering that when using <filename>devshell</filename> | 1896 | It is worth remembering that when using <filename>devshell</filename> |
1897 | you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> | 1897 | you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> |
1898 | instead of just using <filename>gcc</filename>. | 1898 | instead of just using <filename>gcc</filename>. |
1899 | The same applies to other applications such as <filename>binutils</filename>, | 1899 | The same applies to other applications such as <filename>binutils</filename>, |
1900 | <filename>libtool</filename> and so forth. | 1900 | <filename>libtool</filename> and so forth. |
1901 | BitBake sets up environment variables such as <filename>CC</filename> | 1901 | BitBake sets up environment variables such as <filename>CC</filename> |
1902 | to assist applications, such as <filename>make</filename> to find the correct tools. | 1902 | to assist applications, such as <filename>make</filename> to find the correct tools. |
1903 | </para> | 1903 | </para> |
1904 | 1904 | ||
1905 | <para> | 1905 | <para> |
1906 | It is also worth noting that <filename>devshell</filename> still works over | 1906 | It is also worth noting that <filename>devshell</filename> still works over |
1907 | X11 forwarding and similar situations | 1907 | X11 forwarding and similar situations |
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index 0e1041b4b8..e09c373da2 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml | |||
@@ -8,11 +8,11 @@ | |||
8 | 8 | ||
9 | <para> | 9 | <para> |
10 | This chapter helps you understand the Yocto Project as an open source development project. | 10 | This chapter helps you understand the Yocto Project as an open source development project. |
11 | In general, working in an open source environment is very different from working in a | 11 | In general, working in an open source environment is very different from working in a |
12 | closed, proprietary environment. | 12 | closed, proprietary environment. |
13 | Additionally, the Yocto Project uses specific tools and constructs as part of its development | 13 | Additionally, the Yocto Project uses specific tools and constructs as part of its development |
14 | environment. | 14 | environment. |
15 | This chapter specifically addresses open source philosophy, licensing issues, code repositories, | 15 | This chapter specifically addresses open source philosophy, licensing issues, code repositories, |
16 | the open source distributed version control system Git, and best practices using the Yocto Project. | 16 | the open source distributed version control system Git, and best practices using the Yocto Project. |
17 | </para> | 17 | </para> |
18 | 18 | ||
@@ -20,36 +20,36 @@ | |||
20 | <title>Open Source Philosophy</title> | 20 | <title>Open Source Philosophy</title> |
21 | 21 | ||
22 | <para> | 22 | <para> |
23 | Open source philosophy is characterized by software development directed by peer production | 23 | Open source philosophy is characterized by software development directed by peer production |
24 | and collaboration through an active community of developers. | 24 | and collaboration through an active community of developers. |
25 | Contrast this to the more standard centralized development models used by commercial software | 25 | Contrast this to the more standard centralized development models used by commercial software |
26 | companies where a finite set of developers produces a product for sale using a defined set | 26 | companies where a finite set of developers produces a product for sale using a defined set |
27 | of procedures that ultimately result in an end product whose architecture and source material | 27 | of procedures that ultimately result in an end product whose architecture and source material |
28 | are closed to the public. | 28 | are closed to the public. |
29 | </para> | 29 | </para> |
30 | 30 | ||
31 | <para> | 31 | <para> |
32 | Open source projects conceptually have differing concurrent agendas, approaches, and production. | 32 | Open source projects conceptually have differing concurrent agendas, approaches, and production. |
33 | These facets of the development process can come from anyone in the public (community) that has a | 33 | These facets of the development process can come from anyone in the public (community) that has a |
34 | stake in the software project. | 34 | stake in the software project. |
35 | The open source environment contains new copyright, licensing, domain, and consumer issues | 35 | The open source environment contains new copyright, licensing, domain, and consumer issues |
36 | that differ from the more traditional development environment. | 36 | that differ from the more traditional development environment. |
37 | In an open source environment, the end product, source material, and documentation are | 37 | In an open source environment, the end product, source material, and documentation are |
38 | all available to the public at no cost. | 38 | all available to the public at no cost. |
39 | </para> | 39 | </para> |
40 | 40 | ||
41 | <para> | 41 | <para> |
42 | A benchmark example of an open source project is the Linux Kernel, which was initially conceived | 42 | A benchmark example of an open source project is the Linux Kernel, which was initially conceived |
43 | and created by Finnish computer science student Linus Torvalds in 1991. | 43 | and created by Finnish computer science student Linus Torvalds in 1991. |
44 | Conversely, a good example of a non-open source project is the | 44 | Conversely, a good example of a non-open source project is the |
45 | <trademark class='registered'>Windows</trademark> family of operating | 45 | <trademark class='registered'>Windows</trademark> family of operating |
46 | systems developed by <trademark class='registered'>Microsoft</trademark> Corporation. | 46 | systems developed by <trademark class='registered'>Microsoft</trademark> Corporation. |
47 | </para> | 47 | </para> |
48 | 48 | ||
49 | <para> | 49 | <para> |
50 | Wikipedia has a good historical description of the Open Source Philosophy | 50 | Wikipedia has a good historical description of the Open Source Philosophy |
51 | <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>. | 51 | <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>. |
52 | You can also find helpful information on how to participate in the Linux Community | 52 | You can also find helpful information on how to participate in the Linux Community |
53 | <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>. | 53 | <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>. |
54 | </para> | 54 | </para> |
55 | </section> | 55 | </section> |
@@ -58,72 +58,72 @@ | |||
58 | <title>Using the Yocto Project in a Team Environment</title> | 58 | <title>Using the Yocto Project in a Team Environment</title> |
59 | 59 | ||
60 | <para> | 60 | <para> |
61 | It might not be immediately clear how you can use the Yocto Project in a team environment, | 61 | It might not be immediately clear how you can use the Yocto Project in a team environment, |
62 | or scale it for a large team of developers. | 62 | or scale it for a large team of developers. |
63 | The specifics of any situation determine the best solution. | 63 | The specifics of any situation determine the best solution. |
64 | Granted that the Yocto Project offers immense flexibility regarding this, practices do exist | 64 | Granted that the Yocto Project offers immense flexibility regarding this, practices do exist |
65 | that experience has shown work well. | 65 | that experience has shown work well. |
66 | </para> | 66 | </para> |
67 | 67 | ||
68 | <para> | 68 | <para> |
69 | The core component of any development effort with the Yocto Project is often an | 69 | The core component of any development effort with the Yocto Project is often an |
70 | automated build and testing framework along with an image generation process. | 70 | automated build and testing framework along with an image generation process. |
71 | You can use these core components to check that the metadata can be built, | 71 | You can use these core components to check that the metadata can be built, |
72 | highlight when commits break the build, and provide up-to-date images that | 72 | highlight when commits break the build, and provide up-to-date images that |
73 | allow developers to test the end result and use it as a base platform for further | 73 | allow developers to test the end result and use it as a base platform for further |
74 | development. | 74 | development. |
75 | Experience shows that buildbot is a good fit for this role. | 75 | Experience shows that buildbot is a good fit for this role. |
76 | What works well is to configure buildbot to make two types of builds: | 76 | What works well is to configure buildbot to make two types of builds: |
77 | incremental and full (from scratch). | 77 | incremental and full (from scratch). |
78 | See "<ulink url='http://autobuilder.yoctoproject.org:8010/'>Welcome to the buildbot for the Yocto Project</ulink>" | 78 | See "<ulink url='http://autobuilder.yoctoproject.org:8010/'>Welcome to the buildbot for the Yocto Project</ulink>" |
79 | for an example implementation that uses buildbot. | 79 | for an example implementation that uses buildbot. |
80 | </para> | 80 | </para> |
81 | 81 | ||
82 | <para> | 82 | <para> |
83 | You can tie an incremental build to a commit hook that triggers the build | 83 | You can tie an incremental build to a commit hook that triggers the build |
84 | each time a commit is made to the metadata. | 84 | each time a commit is made to the metadata. |
85 | This practice results in useful acid tests that determine whether a given commit | 85 | This practice results in useful acid tests that determine whether a given commit |
86 | breaks the build in some serious way. | 86 | breaks the build in some serious way. |
87 | Associating a build to a commit can catch a lot of simple errors. | 87 | Associating a build to a commit can catch a lot of simple errors. |
88 | Furthermore, the tests are fast so developers can get quick feedback on changes. | 88 | Furthermore, the tests are fast so developers can get quick feedback on changes. |
89 | </para> | 89 | </para> |
90 | 90 | ||
91 | <para> | 91 | <para> |
92 | Full builds build and test everything from the ground up. | 92 | Full builds build and test everything from the ground up. |
93 | These types of builds usually happen at predetermined times like during the | 93 | These types of builds usually happen at predetermined times like during the |
94 | night when the machine load is low. | 94 | night when the machine load is low. |
95 | </para> | 95 | </para> |
96 | 96 | ||
97 | <para> | 97 | <para> |
98 | Most teams have many pieces of software undergoing active development at any given time. | 98 | Most teams have many pieces of software undergoing active development at any given time. |
99 | You can derive large benefits by putting these pieces under the control of a source | 99 | You can derive large benefits by putting these pieces under the control of a source |
100 | control system that is compatible (i.e. Git or Subversion (SVN)) with the OpenEmbeded | 100 | control system that is compatible (i.e. Git or Subversion (SVN)) with the OpenEmbeded |
101 | build system that the Yocto Project uses. | 101 | build system that the Yocto Project uses. |
102 | You can then set the autobuilder to pull the latest revisions of the packages | 102 | You can then set the autobuilder to pull the latest revisions of the packages |
103 | and test the latest commits by the builds. | 103 | and test the latest commits by the builds. |
104 | This practice quickly highlights issues. | 104 | This practice quickly highlights issues. |
105 | The build system easily supports testing configurations that use both a | 105 | The build system easily supports testing configurations that use both a |
106 | stable known good revision and a floating revision. | 106 | stable known good revision and a floating revision. |
107 | The build system can also take just the changes from specific source control branches. | 107 | The build system can also take just the changes from specific source control branches. |
108 | This capability allows you to track and test specific changes. | 108 | This capability allows you to track and test specific changes. |
109 | </para> | 109 | </para> |
110 | 110 | ||
111 | <para> | 111 | <para> |
112 | Perhaps the hardest part of setting this up is defining the software project or | 112 | Perhaps the hardest part of setting this up is defining the software project or |
113 | the metadata policies that surround the different source control systems. | 113 | the metadata policies that surround the different source control systems. |
114 | Of course circumstances will be different in each case. | 114 | Of course circumstances will be different in each case. |
115 | However, this situation reveals one of the Yocto Project's advantages - | 115 | However, this situation reveals one of the Yocto Project's advantages - |
116 | the system itself does not | 116 | the system itself does not |
117 | force any particular policy on users, unlike a lot of build systems. | 117 | force any particular policy on users, unlike a lot of build systems. |
118 | The system allows the best policies to be chosen for the given circumstances. | 118 | The system allows the best policies to be chosen for the given circumstances. |
119 | </para> | 119 | </para> |
120 | 120 | ||
121 | <para> | 121 | <para> |
122 | In general, best practices exist that make your work with the Yocto | 122 | In general, best practices exist that make your work with the Yocto |
123 | Project easier in a team environment. | 123 | Project easier in a team environment. |
124 | This list presents some of these practices you might consider following. | 124 | This list presents some of these practices you might consider following. |
125 | Of course, you need to understand that you do not have to follow these | 125 | Of course, you need to understand that you do not have to follow these |
126 | practices and your setup can be totally controlled and customized by | 126 | practices and your setup can be totally controlled and customized by |
127 | your team: | 127 | your team: |
128 | <itemizedlist> | 128 | <itemizedlist> |
129 | <listitem><para>Use <link linkend='git'>Git</link> | 129 | <listitem><para>Use <link linkend='git'>Git</link> |
@@ -131,9 +131,9 @@ | |||
131 | <listitem><para>Maintain your metadata in layers that make sense | 131 | <listitem><para>Maintain your metadata in layers that make sense |
132 | for your situation. | 132 | for your situation. |
133 | See the "<link linkend='understanding-and-creating-layers'>Understanding | 133 | See the "<link linkend='understanding-and-creating-layers'>Understanding |
134 | and Creating Layeres</link>" section for more information on | 134 | and Creating Layeres</link>" section for more information on |
135 | layers.</para></listitem> | 135 | layers.</para></listitem> |
136 | <listitem><para>Separate the project's metadata and code by using | 136 | <listitem><para>Separate the project's metadata and code by using |
137 | separate Git repositories. | 137 | separate Git repositories. |
138 | See the "<link linkend='yocto-project-repositories'>Yocto Project | 138 | See the "<link linkend='yocto-project-repositories'>Yocto Project |
139 | Source Repositories</link>" section for information on these | 139 | Source Repositories</link>" section for information on these |
@@ -144,10 +144,10 @@ | |||
144 | <listitem><para>Set up the directory for the shared state cache | 144 | <listitem><para>Set up the directory for the shared state cache |
145 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>) | 145 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>) |
146 | where they make sense. | 146 | where they make sense. |
147 | For example, set up the sstate cache for developers using the | 147 | For example, set up the sstate cache for developers using the |
148 | same office and share source directories on the developer's | 148 | same office and share source directories on the developer's |
149 | machines.</para></listitem> | 149 | machines.</para></listitem> |
150 | <listitem><para>Set up an autobuilder and have it populate the | 150 | <listitem><para>Set up an autobuilder and have it populate the |
151 | sstate cache and source directories.</para></listitem> | 151 | sstate cache and source directories.</para></listitem> |
152 | </itemizedlist> | 152 | </itemizedlist> |
153 | </para> | 153 | </para> |
@@ -157,37 +157,37 @@ | |||
157 | <title>Yocto Project Source Repositories</title> | 157 | <title>Yocto Project Source Repositories</title> |
158 | 158 | ||
159 | <para> | 159 | <para> |
160 | The Yocto Project team maintains complete source repositories for all Yocto Project files | 160 | The Yocto Project team maintains complete source repositories for all Yocto Project files |
161 | at <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>. | 161 | at <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>. |
162 | This web-based source code browser is organized into categories by function such as | 162 | This web-based source code browser is organized into categories by function such as |
163 | IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. | 163 | IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. |
164 | From the interface, you can click on any particular item in the "Name" column and | 164 | From the interface, you can click on any particular item in the "Name" column and |
165 | see the URL at the bottom of the page that you need to set up a Git repository for | 165 | see the URL at the bottom of the page that you need to set up a Git repository for |
166 | that particular item. | 166 | that particular item. |
167 | Having a local Git repository of the Source Directory (poky) allows you to | 167 | Having a local Git repository of the Source Directory (poky) allows you to |
168 | make changes, contribute to the history, and ultimately enhance the Yocto Project's | 168 | make changes, contribute to the history, and ultimately enhance the Yocto Project's |
169 | tools, Board Support Packages, and so forth. | 169 | tools, Board Support Packages, and so forth. |
170 | </para> | 170 | </para> |
171 | 171 | ||
172 | <para> | 172 | <para> |
173 | Conversely, if you are a developer that is not interested in contributing back to the | 173 | Conversely, if you are a developer that is not interested in contributing back to the |
174 | Yocto Project, you have the ability to simply download and extract release tarballs | 174 | Yocto Project, you have the ability to simply download and extract release tarballs |
175 | and use them within the Yocto Project environment. | 175 | and use them within the Yocto Project environment. |
176 | All that is required is a particular release of the Yocto Project and | 176 | All that is required is a particular release of the Yocto Project and |
177 | your application source code. | 177 | your application source code. |
178 | </para> | 178 | </para> |
179 | 179 | ||
180 | <para> | 180 | <para> |
181 | For any supported release of Yocto Project, you can go to the Yocto Project website’s | 181 | For any supported release of Yocto Project, you can go to the Yocto Project website’s |
182 | <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink> and get a | 182 | <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink> and get a |
183 | tarball of the release. | 183 | tarball of the release. |
184 | You can also go to this site to download any supported BSP tarballs. | 184 | You can also go to this site to download any supported BSP tarballs. |
185 | Unpacking the tarball gives you a hierarchical Source Directory that lets you develop | 185 | Unpacking the tarball gives you a hierarchical Source Directory that lets you develop |
186 | using the Yocto Project. | 186 | using the Yocto Project. |
187 | </para> | 187 | </para> |
188 | 188 | ||
189 | <para> | 189 | <para> |
190 | Once you are set up through either tarball extraction or creation of Git repositories, | 190 | Once you are set up through either tarball extraction or creation of Git repositories, |
191 | you are ready to develop. | 191 | you are ready to develop. |
192 | </para> | 192 | </para> |
193 | 193 | ||
@@ -195,18 +195,18 @@ | |||
195 | In summary, here is where you can get the project files needed for development: | 195 | In summary, here is where you can get the project files needed for development: |
196 | <itemizedlist> | 196 | <itemizedlist> |
197 | <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis> | 197 | <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis> |
198 | This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto | 198 | This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto |
199 | Metadata Layers. | 199 | Metadata Layers. |
200 | You can create local copies of Git repositories for each of these areas.</para> | 200 | You can create local copies of Git repositories for each of these areas.</para> |
201 | <para> | 201 | <para> |
202 | <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> | 202 | <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> |
203 | </para></listitem> | 203 | </para></listitem> |
204 | <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis> | 204 | <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis> |
205 | This area contains index releases such as | 205 | This area contains index releases such as |
206 | the <trademark class='trade'>Eclipse</trademark> | 206 | the <trademark class='trade'>Eclipse</trademark> |
207 | Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains, | 207 | Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains, |
208 | and all released versions of Yocto Project in the form of images or tarballs. | 208 | and all released versions of Yocto Project in the form of images or tarballs. |
209 | Downloading and extracting these files does not produce a local copy of the | 209 | Downloading and extracting these files does not produce a local copy of the |
210 | Git repository but rather a snapshot of a particular release or image.</para> | 210 | Git repository but rather a snapshot of a particular release or image.</para> |
211 | <para> | 211 | <para> |
212 | <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="4in" /> | 212 | <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="4in" /> |
@@ -214,7 +214,7 @@ | |||
214 | <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;/download'>Yocto Project Download Page</ulink></emphasis> | 214 | <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;/download'>Yocto Project Download Page</ulink></emphasis> |
215 | This page on the Yocto Project website allows you to download any Yocto Project | 215 | This page on the Yocto Project website allows you to download any Yocto Project |
216 | release or Board Support Package (BSP) in tarball form. | 216 | release or Board Support Package (BSP) in tarball form. |
217 | The tarballs are similar to those found in the | 217 | The tarballs are similar to those found in the |
218 | <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para> | 218 | <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para> |
219 | <para> | 219 | <para> |
220 | <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" /> | 220 | <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" /> |
@@ -227,17 +227,17 @@ | |||
227 | <title>Yocto Project Terms</title> | 227 | <title>Yocto Project Terms</title> |
228 | 228 | ||
229 | <para> | 229 | <para> |
230 | Following is a list of terms and definitions users new to the Yocto Project development | 230 | Following is a list of terms and definitions users new to the Yocto Project development |
231 | environment might find helpful. | 231 | environment might find helpful. |
232 | While some of these terms are universal, the list includes them just in case: | 232 | While some of these terms are universal, the list includes them just in case: |
233 | <itemizedlist> | 233 | <itemizedlist> |
234 | <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to | 234 | <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to |
235 | a recipe file. | 235 | a recipe file. |
236 | Append files are known as BitBake append files and <filename>.bbappend</filename> files. | 236 | Append files are known as BitBake append files and <filename>.bbappend</filename> files. |
237 | The OpenEmbedded build system expects every append file to have a corresponding and | 237 | The OpenEmbedded build system expects every append file to have a corresponding and |
238 | underlying recipe (<filename>.bb</filename>) file. | 238 | underlying recipe (<filename>.bb</filename>) file. |
239 | Furthermore, the append file and the underlying recipe must have the same root filename. | 239 | Furthermore, the append file and the underlying recipe must have the same root filename. |
240 | The filenames can differ only in the file type suffix used (e.g. | 240 | The filenames can differ only in the file type suffix used (e.g. |
241 | <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>). | 241 | <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>). |
242 | </para> | 242 | </para> |
243 | <para>Information in append files overrides the information in the similarly-named recipe file. | 243 | <para>Information in append files overrides the information in the similarly-named recipe file. |
@@ -245,20 +245,20 @@ | |||
245 | "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section. | 245 | "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section. |
246 | </para></listitem> | 246 | </para></listitem> |
247 | <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis> | 247 | <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis> |
248 | The task executor and scheduler used by | 248 | The task executor and scheduler used by |
249 | the OpenEmbedded build system to build images. | 249 | the OpenEmbedded build system to build images. |
250 | For more information on BitBake, see the BitBake documentation | 250 | For more information on BitBake, see the BitBake documentation |
251 | in the <filename>bitbake/doc/manual</filename> directory of the | 251 | in the <filename>bitbake/doc/manual</filename> directory of the |
252 | <link linkend='source-directory'>Source Directory</link>.</para></listitem> | 252 | <link linkend='source-directory'>Source Directory</link>.</para></listitem> |
253 | <listitem> | 253 | <listitem> |
254 | <para id='build-directory'><emphasis>Build Directory:</emphasis> | 254 | <para id='build-directory'><emphasis>Build Directory:</emphasis> |
255 | This term refers to the area used by the OpenEmbedded build system for builds. | 255 | This term refers to the area used by the OpenEmbedded build system for builds. |
256 | The area is created when you <filename>source</filename> the setup | 256 | The area is created when you <filename>source</filename> the setup |
257 | environment script that is found in the Source Directory | 257 | environment script that is found in the Source Directory |
258 | (i.e. <filename>&OE_INIT_FILE;</filename>). | 258 | (i.e. <filename>&OE_INIT_FILE;</filename>). |
259 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink> | 259 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink> |
260 | variable points to the Build Directory.</para> | 260 | variable points to the Build Directory.</para> |
261 | 261 | ||
262 | <para>You have a lot of flexibility when creating the Build Directory. | 262 | <para>You have a lot of flexibility when creating the Build Directory. |
263 | Following are some examples that show how to create the directory: | 263 | Following are some examples that show how to create the directory: |
264 | <itemizedlist> | 264 | <itemizedlist> |
@@ -268,119 +268,119 @@ | |||
268 | <literallayout class='monospaced'> | 268 | <literallayout class='monospaced'> |
269 | $ source &OE_INIT_PATH; | 269 | $ source &OE_INIT_PATH; |
270 | </literallayout></para></listitem> | 270 | </literallayout></para></listitem> |
271 | <listitem><para>Provide a directory path and specifically name the build | 271 | <listitem><para>Provide a directory path and specifically name the build |
272 | directory. | 272 | directory. |
273 | This next example creates a Build Directory named <filename>YP-&POKYVERSION;</filename> | 273 | This next example creates a Build Directory named <filename>YP-&POKYVERSION;</filename> |
274 | in your home directory within the directory <filename>mybuilds</filename>. | 274 | in your home directory within the directory <filename>mybuilds</filename>. |
275 | If <filename>mybuilds</filename> does not exist, the directory is created for you: | 275 | If <filename>mybuilds</filename> does not exist, the directory is created for you: |
276 | <literallayout class='monospaced'> | 276 | <literallayout class='monospaced'> |
277 | $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION; | 277 | $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION; |
278 | </literallayout></para></listitem> | 278 | </literallayout></para></listitem> |
279 | <listitem><para>Provide an existing directory to use as the Build Directory. | 279 | <listitem><para>Provide an existing directory to use as the Build Directory. |
280 | This example uses the existing <filename>mybuilds</filename> directory | 280 | This example uses the existing <filename>mybuilds</filename> directory |
281 | as the Build Directory. | 281 | as the Build Directory. |
282 | <literallayout class='monospaced'> | 282 | <literallayout class='monospaced'> |
283 | $ source &OE_INIT_PATH; $HOME/mybuilds/ | 283 | $ source &OE_INIT_PATH; $HOME/mybuilds/ |
284 | </literallayout></para></listitem> | 284 | </literallayout></para></listitem> |
285 | </itemizedlist> | 285 | </itemizedlist> |
286 | </para></listitem> | 286 | </para></listitem> |
287 | <listitem><para><emphasis>Build System:</emphasis> In the context of the Yocto Project | 287 | <listitem><para><emphasis>Build System:</emphasis> In the context of the Yocto Project |
288 | this term refers to the OpenEmbedded build system used by the project. | 288 | this term refers to the OpenEmbedded build system used by the project. |
289 | This build system is based on the project known as "Poky." | 289 | This build system is based on the project known as "Poky." |
290 | For some historical information about Poky, see the | 290 | For some historical information about Poky, see the |
291 | <link linkend='poky'>Poky</link> term further along in this section. | 291 | <link linkend='poky'>Poky</link> term further along in this section. |
292 | </para></listitem> | 292 | </para></listitem> |
293 | <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation | 293 | <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation |
294 | and inheritance allowing commonly used patterns to be defined once and easily used | 294 | and inheritance allowing commonly used patterns to be defined once and easily used |
295 | in multiple recipes. | 295 | in multiple recipes. |
296 | Class files end with the <filename>.bbclass</filename> filename extension. | 296 | Class files end with the <filename>.bbclass</filename> filename extension. |
297 | </para></listitem> | 297 | </para></listitem> |
298 | <listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various | 298 | <listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various |
299 | <filename>.conf</filename> files provides global definitions of variables. | 299 | <filename>.conf</filename> files provides global definitions of variables. |
300 | The <filename>conf/local.conf</filename> configuration file in the | 300 | The <filename>conf/local.conf</filename> configuration file in the |
301 | <link linkend='build-directory'>Build Directory</link> | 301 | <link linkend='build-directory'>Build Directory</link> |
302 | contains user-defined variables that affect each build. | 302 | contains user-defined variables that affect each build. |
303 | The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file | 303 | The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file |
304 | defines Yocto ‘distro’ configuration | 304 | defines Yocto ‘distro’ configuration |
305 | variables used only when building with this policy. | 305 | variables used only when building with this policy. |
306 | Machine configuration files, which | 306 | Machine configuration files, which |
307 | are located throughout the | 307 | are located throughout the |
308 | <link linkend='source-directory'>Source Directory</link>, define | 308 | <link linkend='source-directory'>Source Directory</link>, define |
309 | variables for specific hardware and are only used when building for that target | 309 | variables for specific hardware and are only used when building for that target |
310 | (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines | 310 | (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines |
311 | variables for the Texas Instruments ARM Cortex-A8 development board). | 311 | variables for the Texas Instruments ARM Cortex-A8 development board). |
312 | Configuration files end with a <filename>.conf</filename> filename extension. | 312 | Configuration files end with a <filename>.conf</filename> filename extension. |
313 | </para></listitem> | 313 | </para></listitem> |
314 | <listitem><para><emphasis>Cross-Development Toolchain:</emphasis> | 314 | <listitem><para><emphasis>Cross-Development Toolchain:</emphasis> |
315 | A collection of software development | 315 | A collection of software development |
316 | tools and utilities that allow you to develop software for targeted architectures. | 316 | tools and utilities that allow you to develop software for targeted architectures. |
317 | This toolchain contains cross-compilers, linkers, and debuggers that are specific to | 317 | This toolchain contains cross-compilers, linkers, and debuggers that are specific to |
318 | an architecture. | 318 | an architecture. |
319 | You can use the OpenEmbedded build system to build a cross-development toolchain | 319 | You can use the OpenEmbedded build system to build a cross-development toolchain |
320 | installer that when run installs the toolchain that contains the development tools you | 320 | installer that when run installs the toolchain that contains the development tools you |
321 | need to cross-compile and test your software. | 321 | need to cross-compile and test your software. |
322 | The Yocto Project ships with images that contain installers for | 322 | The Yocto Project ships with images that contain installers for |
323 | toolchains for supported architectures as well. | 323 | toolchains for supported architectures as well. |
324 | Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem> | 324 | Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem> |
325 | <listitem><para><emphasis>Image:</emphasis> An image is the result produced when | 325 | <listitem><para><emphasis>Image:</emphasis> An image is the result produced when |
326 | BitBake processes a given collection of recipes and related metadata. | 326 | BitBake processes a given collection of recipes and related metadata. |
327 | Images are the binary output that run on specific hardware or QEMU | 327 | Images are the binary output that run on specific hardware or QEMU |
328 | and for specific use cases. | 328 | and for specific use cases. |
329 | For a list of the supported image types that the Yocto Project provides, see the | 329 | For a list of the supported image types that the Yocto Project provides, see the |
330 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | 330 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" |
331 | chapter in the Yocto Project Reference Manual.</para></listitem> | 331 | chapter in the Yocto Project Reference Manual.</para></listitem> |
332 | <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core, | 332 | <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core, |
333 | a BSP, or an application stack. | 333 | a BSP, or an application stack. |
334 | For a discussion on BSP Layers, see the | 334 | For a discussion on BSP Layers, see the |
335 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" | 335 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" |
336 | section in the Yocto Project Board Support Packages (BSP) Developer's Guide.</para></listitem> | 336 | section in the Yocto Project Board Support Packages (BSP) Developer's Guide.</para></listitem> |
337 | <listitem><para id='metadata'><emphasis>Metadata:</emphasis> The files that BitBake parses when | 337 | <listitem><para id='metadata'><emphasis>Metadata:</emphasis> The files that BitBake parses when |
338 | building an image. | 338 | building an image. |
339 | Metadata includes recipes, classes, and configuration files.</para></listitem> | 339 | Metadata includes recipes, classes, and configuration files.</para></listitem> |
340 | <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of metadata originating | 340 | <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of metadata originating |
341 | with OpenEmbedded (OE) that is shared between OE and the Yocto Project. | 341 | with OpenEmbedded (OE) that is shared between OE and the Yocto Project. |
342 | This metadata is found in the <filename>meta</filename> directory of the source | 342 | This metadata is found in the <filename>meta</filename> directory of the source |
343 | directory.</para></listitem> | 343 | directory.</para></listitem> |
344 | <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project, | 344 | <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project, |
345 | this term refers to the packaged output from a baked recipe. | 345 | this term refers to the packaged output from a baked recipe. |
346 | A package is generally the compiled binaries produced from the recipe's sources. | 346 | A package is generally the compiled binaries produced from the recipe's sources. |
347 | You ‘bake’ something by running it through BitBake.</para> | 347 | You ‘bake’ something by running it through BitBake.</para> |
348 | <para>It is worth noting that the term "package" can, in general, have subtle | 348 | <para>It is worth noting that the term "package" can, in general, have subtle |
349 | meanings. For example, the packages refered to in the | 349 | meanings. For example, the packages refered to in the |
350 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are | 350 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are |
351 | compiled binaries that when installed add functionality to your Linux | 351 | compiled binaries that when installed add functionality to your Linux |
352 | distribution.</para> | 352 | distribution.</para> |
353 | <para>Another point worth noting is that historically within the Yocto Project, | 353 | <para>Another point worth noting is that historically within the Yocto Project, |
354 | recipes were referred to as packages - thus, the existence of several BitBake | 354 | recipes were referred to as packages - thus, the existence of several BitBake |
355 | variables that are seemingly mis-named, | 355 | variables that are seemingly mis-named, |
356 | (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>, | 356 | (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>, |
357 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PRINC'><filename>PRINC</filename></ulink>, | 357 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PRINC'><filename>PRINC</filename></ulink>, |
358 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and | 358 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and |
359 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>). | 359 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>). |
360 | </para></listitem> | 360 | </para></listitem> |
361 | <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things. | 361 | <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things. |
362 | In its most general sense, it is an open-source project that was initially developed | 362 | In its most general sense, it is an open-source project that was initially developed |
363 | by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded | 363 | by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded |
364 | build system becoming a build system for embedded images. | 364 | build system becoming a build system for embedded images. |
365 | After Intel Corporation aquired OpenedHand, the project poky became the basis for | 365 | After Intel Corporation aquired OpenedHand, the project poky became the basis for |
366 | the Yocto Project's build system. | 366 | the Yocto Project's build system. |
367 | Within the Yocto Project source repositories, poky exists as a separate Git repository | 367 | Within the Yocto Project source repositories, poky exists as a separate Git repository |
368 | that can be cloned to yield a local copy on the host system. | 368 | that can be cloned to yield a local copy on the host system. |
369 | Thus, "poky" can refer to the local copy of the Source Directory used to develop within | 369 | Thus, "poky" can refer to the local copy of the Source Directory used to develop within |
370 | the Yocto Project.</para></listitem> | 370 | the Yocto Project.</para></listitem> |
371 | <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages. | 371 | <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages. |
372 | A recipe describes where you get source code and which patches to apply. | 372 | A recipe describes where you get source code and which patches to apply. |
373 | Recipes describe dependencies for libraries or for other recipes, and they | 373 | Recipes describe dependencies for libraries or for other recipes, and they |
374 | also contain configuration and compilation options. | 374 | also contain configuration and compilation options. |
375 | Recipes contain the logical unit of execution, the software/images to build, and | 375 | Recipes contain the logical unit of execution, the software/images to build, and |
376 | use the <filename>.bb</filename> file extension.</para></listitem> | 376 | use the <filename>.bb</filename> file extension.</para></listitem> |
377 | <listitem> | 377 | <listitem> |
378 | <para id='source-directory'><emphasis>Source Directory:</emphasis> | 378 | <para id='source-directory'><emphasis>Source Directory:</emphasis> |
379 | This term refers to the directory structure created as a result of either downloading | 379 | This term refers to the directory structure created as a result of either downloading |
380 | and unpacking a Yocto Project release tarball or creating a local copy of | 380 | and unpacking a Yocto Project release tarball or creating a local copy of |
381 | the <filename>poky</filename> Git repository | 381 | the <filename>poky</filename> Git repository |
382 | <filename>git://git.yoctoproject.org/poky</filename>. | 382 | <filename>git://git.yoctoproject.org/poky</filename>. |
383 | Sometimes you might here the term "poky directory" used to refer to this | 383 | Sometimes you might here the term "poky directory" used to refer to this |
384 | directory structure. | 384 | directory structure. |
385 | <note> | 385 | <note> |
386 | The OpenEmbedded build system does not support file or directory names that | 386 | The OpenEmbedded build system does not support file or directory names that |
@@ -388,55 +388,55 @@ | |||
388 | Be sure that the Source Directory you use does not contain these types | 388 | Be sure that the Source Directory you use does not contain these types |
389 | of names. | 389 | of names. |
390 | </note></para> | 390 | </note></para> |
391 | <para>The Source Directory contains BitBake, Documentation, metadata and | 391 | <para>The Source Directory contains BitBake, Documentation, metadata and |
392 | other files that all support the Yocto Project. | 392 | other files that all support the Yocto Project. |
393 | Consequently, you must have the Source Directory in place on your development | 393 | Consequently, you must have the Source Directory in place on your development |
394 | system in order to do any development using the Yocto Project.</para> | 394 | system in order to do any development using the Yocto Project.</para> |
395 | 395 | ||
396 | <para>For tarball expansion, the name of the top-level directory of the Source Directory | 396 | <para>For tarball expansion, the name of the top-level directory of the Source Directory |
397 | is derived from the Yocto Project release tarball. | 397 | is derived from the Yocto Project release tarball. |
398 | For example, downloading and unpacking <filename>&YOCTO_POKY_TARBALL;</filename> | 398 | For example, downloading and unpacking <filename>&YOCTO_POKY_TARBALL;</filename> |
399 | results in a Source Directory whose top-level folder is named | 399 | results in a Source Directory whose top-level folder is named |
400 | <filename>&YOCTO_POKY;</filename>. | 400 | <filename>&YOCTO_POKY;</filename>. |
401 | If you create a local copy of the Git repository, then you can name the repository | 401 | If you create a local copy of the Git repository, then you can name the repository |
402 | anything you like. | 402 | anything you like. |
403 | Throughout much of the documentation, <filename>poky</filename> is used as the name of | 403 | Throughout much of the documentation, <filename>poky</filename> is used as the name of |
404 | the top-level folder of the local copy of the poky Git repository. | 404 | the top-level folder of the local copy of the poky Git repository. |
405 | So, for example, cloning the <filename>poky</filename> Git repository results in a | 405 | So, for example, cloning the <filename>poky</filename> Git repository results in a |
406 | local Git repository whose top-level folder is also named <filename>poky</filename>.</para> | 406 | local Git repository whose top-level folder is also named <filename>poky</filename>.</para> |
407 | 407 | ||
408 | <para>It is important to understand the differences between the Source Directory created | 408 | <para>It is important to understand the differences between the Source Directory created |
409 | by unpacking a released tarball as compared to cloning | 409 | by unpacking a released tarball as compared to cloning |
410 | <filename>git://git.yoctoproject.org/poky</filename>. | 410 | <filename>git://git.yoctoproject.org/poky</filename>. |
411 | When you unpack a tarball, you have an exact copy of the files based on the time of | 411 | When you unpack a tarball, you have an exact copy of the files based on the time of |
412 | release - a fixed release point. | 412 | release - a fixed release point. |
413 | Any changes you make to your local files in the Source Directory are on top of the release. | 413 | Any changes you make to your local files in the Source Directory are on top of the release. |
414 | On the other hand, when you clone the <filename>poky</filename> Git repository, you have an | 414 | On the other hand, when you clone the <filename>poky</filename> Git repository, you have an |
415 | active development repository. | 415 | active development repository. |
416 | In this case, any local changes you make to the Source Directory can be later applied | 416 | In this case, any local changes you make to the Source Directory can be later applied |
417 | to active development branches of the upstream <filename>poky</filename> Git | 417 | to active development branches of the upstream <filename>poky</filename> Git |
418 | repository.</para> | 418 | repository.</para> |
419 | 419 | ||
420 | <para>Finally, if you want to track a set of local changes while starting from the same point | 420 | <para>Finally, if you want to track a set of local changes while starting from the same point |
421 | as a release tarball, you can create a local Git branch that | 421 | as a release tarball, you can create a local Git branch that |
422 | reflects the exact copy of the files at the time of their release. | 422 | reflects the exact copy of the files at the time of their release. |
423 | You do this by using Git tags that are part of the repository.</para> | 423 | You do this by using Git tags that are part of the repository.</para> |
424 | 424 | ||
425 | <para>For more information on concepts around Git repositories, branches, and tags, | 425 | <para>For more information on concepts around Git repositories, branches, and tags, |
426 | see the | 426 | see the |
427 | "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" | 427 | "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" |
428 | section.</para></listitem> | 428 | section.</para></listitem> |
429 | <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes. | 429 | <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes. |
430 | You simply use Tasks to hold recipes that, when built, usually accomplish a single task. | 430 | You simply use Tasks to hold recipes that, when built, usually accomplish a single task. |
431 | For example, a task could contain the recipes for a company’s proprietary or value-add software. | 431 | For example, a task could contain the recipes for a company’s proprietary or value-add software. |
432 | Or, the task could contain the recipes that enable graphics. | 432 | Or, the task could contain the recipes that enable graphics. |
433 | A task is really just another recipe. | 433 | A task is really just another recipe. |
434 | Because task files are recipes, they end with the <filename>.bb</filename> filename | 434 | Because task files are recipes, they end with the <filename>.bb</filename> filename |
435 | extension.</para></listitem> | 435 | extension.</para></listitem> |
436 | <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories | 436 | <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories |
437 | that are not local to the development system but located in a master area that is controlled | 437 | that are not local to the development system but located in a master area that is controlled |
438 | by the maintainer of the source code. | 438 | by the maintainer of the source code. |
439 | For example, in order for a developer to work on a particular piece of code, they need to | 439 | For example, in order for a developer to work on a particular piece of code, they need to |
440 | first get a copy of it from an "upstream" source.</para></listitem> | 440 | first get a copy of it from an "upstream" source.</para></listitem> |
441 | </itemizedlist> | 441 | </itemizedlist> |
442 | </para> | 442 | </para> |
@@ -446,8 +446,8 @@ | |||
446 | <title>Licensing</title> | 446 | <title>Licensing</title> |
447 | 447 | ||
448 | <para> | 448 | <para> |
449 | Because open source projects are open to the public, they have different licensing structures in place. | 449 | Because open source projects are open to the public, they have different licensing structures in place. |
450 | License evolution for both Open Source and Free Software has an interesting history. | 450 | License evolution for both Open Source and Free Software has an interesting history. |
451 | If you are interested in this history, you can find basic information here: | 451 | If you are interested in this history, you can find basic information here: |
452 | <itemizedlist> | 452 | <itemizedlist> |
453 | <listitem><para><ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink> | 453 | <listitem><para><ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink> |
@@ -458,57 +458,57 @@ | |||
458 | </para> | 458 | </para> |
459 | 459 | ||
460 | <para> | 460 | <para> |
461 | In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology | 461 | In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology |
462 | (MIT) License. | 462 | (MIT) License. |
463 | MIT licensing permits the reuse of software within proprietary software as long as the | 463 | MIT licensing permits the reuse of software within proprietary software as long as the |
464 | license is distributed with that software. | 464 | license is distributed with that software. |
465 | MIT is also compatible with the GNU General Public License (GPL). | 465 | MIT is also compatible with the GNU General Public License (GPL). |
466 | Patches to the Yocto Project follow the upstream licensing scheme. | 466 | Patches to the Yocto Project follow the upstream licensing scheme. |
467 | You can find information on the MIT license at | 467 | You can find information on the MIT license at |
468 | <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>. | 468 | <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>. |
469 | You can find information on the GNU GPL <ulink url='http://www.opensource.org/licenses/LGPL-3.0'> | 469 | You can find information on the GNU GPL <ulink url='http://www.opensource.org/licenses/LGPL-3.0'> |
470 | here</ulink>. | 470 | here</ulink>. |
471 | </para> | 471 | </para> |
472 | 472 | ||
473 | <para> | 473 | <para> |
474 | When you build an image using the Yocto Project, the build process uses a | 474 | When you build an image using the Yocto Project, the build process uses a |
475 | known list of licenses to ensure compliance. | 475 | known list of licenses to ensure compliance. |
476 | You can find this list in the Yocto Project files directory at | 476 | You can find this list in the Yocto Project files directory at |
477 | <filename>meta/files/common-licenses</filename>. | 477 | <filename>meta/files/common-licenses</filename>. |
478 | Once the build completes, the list of all licenses found and used during that build are | 478 | Once the build completes, the list of all licenses found and used during that build are |
479 | kept in the | 479 | kept in the |
480 | <link linkend='build-directory'>Build Directory</link> at | 480 | <link linkend='build-directory'>Build Directory</link> at |
481 | <filename>tmp/deploy/images/licenses</filename>. | 481 | <filename>tmp/deploy/images/licenses</filename>. |
482 | </para> | 482 | </para> |
483 | 483 | ||
484 | <para> | 484 | <para> |
485 | If a module requires a license that is not in the base list, the build process | 485 | If a module requires a license that is not in the base list, the build process |
486 | generates a warning during the build. | 486 | generates a warning during the build. |
487 | These tools make it easier for a developer to be certain of the licenses with which | 487 | These tools make it easier for a developer to be certain of the licenses with which |
488 | their shipped products must comply. | 488 | their shipped products must comply. |
489 | However, even with these tools it is still up to the developer to resolve potential licensing issues. | 489 | However, even with these tools it is still up to the developer to resolve potential licensing issues. |
490 | </para> | 490 | </para> |
491 | 491 | ||
492 | <para> | 492 | <para> |
493 | The base list of licenses used by the build process is a combination of the Software Package | 493 | The base list of licenses used by the build process is a combination of the Software Package |
494 | Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects. | 494 | Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects. |
495 | <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of the Linux Foundation | 495 | <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of the Linux Foundation |
496 | that maintains a specification | 496 | that maintains a specification |
497 | for a standard format for communicating the components, licenses, and copyrights | 497 | for a standard format for communicating the components, licenses, and copyrights |
498 | associated with a software package. | 498 | associated with a software package. |
499 | <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source | 499 | <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source |
500 | Definition and the effort for reviewing and approving licenses that are OSD-conformant. | 500 | Definition and the effort for reviewing and approving licenses that are OSD-conformant. |
501 | </para> | 501 | </para> |
502 | 502 | ||
503 | <para> | 503 | <para> |
504 | You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses | 504 | You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses |
505 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>. | 505 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>. |
506 | This wiki page discusses the license infrastructure used by the Yocto Project. | 506 | This wiki page discusses the license infrastructure used by the Yocto Project. |
507 | </para> | 507 | </para> |
508 | 508 | ||
509 | <para> | 509 | <para> |
510 | For information that can help you to maintain compliance with various open source licensing | 510 | For information that can help you to maintain compliance with various open source licensing |
511 | during the lifecycle of a product created using the Yocto Project, see the | 511 | during the lifecycle of a product created using the Yocto Project, see the |
512 | "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>" section. | 512 | "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>" section. |
513 | </para> | 513 | </para> |
514 | </section> | 514 | </section> |
@@ -517,45 +517,45 @@ | |||
517 | <title>Git</title> | 517 | <title>Git</title> |
518 | 518 | ||
519 | <para> | 519 | <para> |
520 | The Yocto Project uses Git, which is a free, open source distributed version control system. | 520 | The Yocto Project uses Git, which is a free, open source distributed version control system. |
521 | Git supports distributed development, non-linear development, and can handle large projects. | 521 | Git supports distributed development, non-linear development, and can handle large projects. |
522 | It is best that you have some fundamental understanding of how Git tracks projects and | 522 | It is best that you have some fundamental understanding of how Git tracks projects and |
523 | how to work with Git if you are going to use Yocto Project for development. | 523 | how to work with Git if you are going to use Yocto Project for development. |
524 | This section provides a quick overview of how Git works and provides you with a summary | 524 | This section provides a quick overview of how Git works and provides you with a summary |
525 | of some essential Git commands. | 525 | of some essential Git commands. |
526 | </para> | 526 | </para> |
527 | 527 | ||
528 | <para> | 528 | <para> |
529 | For more information on Git, see | 529 | For more information on Git, see |
530 | <ulink url='http://git-scm.com/documentation'></ulink>. | 530 | <ulink url='http://git-scm.com/documentation'></ulink>. |
531 | If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>. | 531 | If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>. |
532 | </para> | 532 | </para> |
533 | 533 | ||
534 | <section id='repositories-tags-and-branches'> | 534 | <section id='repositories-tags-and-branches'> |
535 | <title>Repositories, Tags, and Branches</title> | 535 | <title>Repositories, Tags, and Branches</title> |
536 | 536 | ||
537 | <para> | 537 | <para> |
538 | As mentioned earlier in section | 538 | As mentioned earlier in section |
539 | "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>", | 539 | "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>", |
540 | the Yocto Project maintains source repositories at | 540 | the Yocto Project maintains source repositories at |
541 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. | 541 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. |
542 | If you look at this web-interface of the repositories, each item is a separate | 542 | If you look at this web-interface of the repositories, each item is a separate |
543 | Git repository. | 543 | Git repository. |
544 | </para> | 544 | </para> |
545 | 545 | ||
546 | <para> | 546 | <para> |
547 | Git repositories use branching techniques that track content change (not files) | 547 | Git repositories use branching techniques that track content change (not files) |
548 | within a project (e.g. a new feature or updated documentation). | 548 | within a project (e.g. a new feature or updated documentation). |
549 | Creating a tree-like structure based on project divergence allows for excellent historical | 549 | Creating a tree-like structure based on project divergence allows for excellent historical |
550 | information over the life of a project. | 550 | information over the life of a project. |
551 | This methodology also allows for an environment in which you can do lots of | 551 | This methodology also allows for an environment in which you can do lots of |
552 | local experimentation on a project as you develop changes or new features. | 552 | local experimentation on a project as you develop changes or new features. |
553 | </para> | 553 | </para> |
554 | 554 | ||
555 | <para> | 555 | <para> |
556 | A Git repository represents all development efforts for a given project. | 556 | A Git repository represents all development efforts for a given project. |
557 | For example, the Git repository <filename>poky</filename> contains all changes | 557 | For example, the Git repository <filename>poky</filename> contains all changes |
558 | and developments for Poky over the course of its entire life. | 558 | and developments for Poky over the course of its entire life. |
559 | That means that all changes that make up all releases are captured. | 559 | That means that all changes that make up all releases are captured. |
560 | The repository maintains a complete history of changes. | 560 | The repository maintains a complete history of changes. |
561 | </para> | 561 | </para> |
@@ -563,8 +563,8 @@ | |||
563 | <para> | 563 | <para> |
564 | You can create a local copy of any repository by "cloning" it with the Git | 564 | You can create a local copy of any repository by "cloning" it with the Git |
565 | <filename>clone</filename> command. | 565 | <filename>clone</filename> command. |
566 | When you clone a Git repository, you end up with an identical copy of the | 566 | When you clone a Git repository, you end up with an identical copy of the |
567 | repository on your development system. | 567 | repository on your development system. |
568 | Once you have a local copy of a repository, you can take steps to develop locally. | 568 | Once you have a local copy of a repository, you can take steps to develop locally. |
569 | For examples on how to clone Git repositories, see the section | 569 | For examples on how to clone Git repositories, see the section |
570 | "<link linkend='getting-setup'>Getting Set Up</link>" earlier in this manual. | 570 | "<link linkend='getting-setup'>Getting Set Up</link>" earlier in this manual. |
@@ -572,34 +572,34 @@ | |||
572 | 572 | ||
573 | <para> | 573 | <para> |
574 | It is important to understand that Git tracks content change and not files. | 574 | It is important to understand that Git tracks content change and not files. |
575 | Git uses "branches" to organize different development efforts. | 575 | Git uses "branches" to organize different development efforts. |
576 | For example, the <filename>poky</filename> repository has | 576 | For example, the <filename>poky</filename> repository has |
577 | <filename>bernard</filename>, | 577 | <filename>bernard</filename>, |
578 | <filename>edison</filename>, <filename>denzil</filename>, <filename>danny</filename> | 578 | <filename>edison</filename>, <filename>denzil</filename>, <filename>danny</filename> |
579 | and <filename>master</filename> branches among others. | 579 | and <filename>master</filename> branches among others. |
580 | You can see all the branches by going to | 580 | You can see all the branches by going to |
581 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and | 581 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and |
582 | clicking on the | 582 | clicking on the |
583 | <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename> | 583 | <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename> |
584 | link beneath the "Branch" heading. | 584 | link beneath the "Branch" heading. |
585 | </para> | 585 | </para> |
586 | 586 | ||
587 | <para> | 587 | <para> |
588 | Each of these branches represents a specific area of development. | 588 | Each of these branches represents a specific area of development. |
589 | The <filename>master</filename> branch represents the current or most recent | 589 | The <filename>master</filename> branch represents the current or most recent |
590 | development. | 590 | development. |
591 | All other branches represent off-shoots of the <filename>master</filename> | 591 | All other branches represent off-shoots of the <filename>master</filename> |
592 | branch. | 592 | branch. |
593 | </para> | 593 | </para> |
594 | 594 | ||
595 | <para> | 595 | <para> |
596 | When you create a local copy of a Git repository, the copy has the same set | 596 | When you create a local copy of a Git repository, the copy has the same set |
597 | of branches as the original. | 597 | of branches as the original. |
598 | This means you can use Git to create a local working area (also called a branch) | 598 | This means you can use Git to create a local working area (also called a branch) |
599 | that tracks a specific development branch from the source Git repository. | 599 | that tracks a specific development branch from the source Git repository. |
600 | in other words, you can define your local Git environment to work on any development | 600 | in other words, you can define your local Git environment to work on any development |
601 | branch in the repository. | 601 | branch in the repository. |
602 | To help illustrate, here is a set of commands that creates a local copy of the | 602 | To help illustrate, here is a set of commands that creates a local copy of the |
603 | <filename>poky</filename> Git repository and then creates and checks out a local | 603 | <filename>poky</filename> Git repository and then creates and checks out a local |
604 | Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development: | 604 | Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development: |
605 | <literallayout class='monospaced'> | 605 | <literallayout class='monospaced'> |
@@ -608,20 +608,20 @@ | |||
608 | $ cd poky | 608 | $ cd poky |
609 | $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; | 609 | $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; |
610 | </literallayout> | 610 | </literallayout> |
611 | In this example, the name of the top-level directory of your local Yocto Project | 611 | In this example, the name of the top-level directory of your local Yocto Project |
612 | Files Git repository is <filename>poky</filename>, | 612 | Files Git repository is <filename>poky</filename>, |
613 | and the name of the local working area (or local branch) you have created and checked | 613 | and the name of the local working area (or local branch) you have created and checked |
614 | out is <filename>&DISTRO_NAME;</filename>. | 614 | out is <filename>&DISTRO_NAME;</filename>. |
615 | The files in your repository now reflect the same files that are in the | 615 | The files in your repository now reflect the same files that are in the |
616 | <filename>&DISTRO_NAME;</filename> development branch of the Yocto Project's | 616 | <filename>&DISTRO_NAME;</filename> development branch of the Yocto Project's |
617 | <filename>poky</filename> repository. | 617 | <filename>poky</filename> repository. |
618 | It is important to understand that when you create and checkout a | 618 | It is important to understand that when you create and checkout a |
619 | local working branch based on a branch name, | 619 | local working branch based on a branch name, |
620 | your local environment matches the "tip" of that development branch | 620 | your local environment matches the "tip" of that development branch |
621 | at the time you created your local branch, which could be | 621 | at the time you created your local branch, which could be |
622 | different than the files at the time of a similarly named release. | 622 | different than the files at the time of a similarly named release. |
623 | In other words, creating and checking out a local branch based on the | 623 | In other words, creating and checking out a local branch based on the |
624 | <filename>&DISTRO_NAME;</filename> branch name is not the same as | 624 | <filename>&DISTRO_NAME;</filename> branch name is not the same as |
625 | cloning and checking out the <filename>master</filename> branch. | 625 | cloning and checking out the <filename>master</filename> branch. |
626 | Keep reading to see how you create a local snapshot of a Yocto Project Release. | 626 | Keep reading to see how you create a local snapshot of a Yocto Project Release. |
627 | </para> | 627 | </para> |
@@ -629,11 +629,11 @@ | |||
629 | <para> | 629 | <para> |
630 | Git uses "tags" to mark specific changes in a repository. | 630 | Git uses "tags" to mark specific changes in a repository. |
631 | Typically, a tag is used to mark a special point such as the final change | 631 | Typically, a tag is used to mark a special point such as the final change |
632 | before a project is released. | 632 | before a project is released. |
633 | You can see the tags used with the <filename>poky</filename> Git repository | 633 | You can see the tags used with the <filename>poky</filename> Git repository |
634 | by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and | 634 | by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and |
635 | clicking on the | 635 | clicking on the |
636 | <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename> | 636 | <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename> |
637 | link beneath the "Tag" heading. | 637 | link beneath the "Tag" heading. |
638 | </para> | 638 | </para> |
639 | 639 | ||
@@ -644,14 +644,14 @@ | |||
644 | </para> | 644 | </para> |
645 | 645 | ||
646 | <para> | 646 | <para> |
647 | When you create a local copy of the Git repository, you also have access to all the | 647 | When you create a local copy of the Git repository, you also have access to all the |
648 | tags. | 648 | tags. |
649 | Similar to branches, you can create and checkout a local working Git branch based | 649 | Similar to branches, you can create and checkout a local working Git branch based |
650 | on a tag name. | 650 | on a tag name. |
651 | When you do this, you get a snapshot of the Git repository that reflects | 651 | When you do this, you get a snapshot of the Git repository that reflects |
652 | the state of the files when the change was made associated with that tag. | 652 | the state of the files when the change was made associated with that tag. |
653 | The most common use is to checkout a working branch that matches a specific | 653 | The most common use is to checkout a working branch that matches a specific |
654 | Yocto Project release. | 654 | Yocto Project release. |
655 | Here is an example: | 655 | Here is an example: |
656 | <literallayout class='monospaced'> | 656 | <literallayout class='monospaced'> |
657 | $ cd ~ | 657 | $ cd ~ |
@@ -659,101 +659,101 @@ | |||
659 | $ cd poky | 659 | $ cd poky |
660 | $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION; | 660 | $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION; |
661 | </literallayout> | 661 | </literallayout> |
662 | In this example, the name of the top-level directory of your local Yocto Project | 662 | In this example, the name of the top-level directory of your local Yocto Project |
663 | Files Git repository is <filename>poky</filename>. | 663 | Files Git repository is <filename>poky</filename>. |
664 | And, the name of the local branch you have created and checked out is | 664 | And, the name of the local branch you have created and checked out is |
665 | <filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>. | 665 | <filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>. |
666 | The files in your repository now exactly match the Yocto Project &DISTRO; | 666 | The files in your repository now exactly match the Yocto Project &DISTRO; |
667 | Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>). | 667 | Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>). |
668 | It is important to understand that when you create and checkout a local | 668 | It is important to understand that when you create and checkout a local |
669 | working branch based on a tag, your environment matches a specific point | 669 | working branch based on a tag, your environment matches a specific point |
670 | in time and not a development branch. | 670 | in time and not a development branch. |
671 | </para> | 671 | </para> |
672 | </section> | 672 | </section> |
673 | 673 | ||
674 | <section id='basic-commands'> | 674 | <section id='basic-commands'> |
675 | <title>Basic Commands</title> | 675 | <title>Basic Commands</title> |
676 | 676 | ||
677 | <para> | 677 | <para> |
678 | Git has an extensive set of commands that lets you manage changes and perform | 678 | Git has an extensive set of commands that lets you manage changes and perform |
679 | collaboration over the life of a project. | 679 | collaboration over the life of a project. |
680 | Conveniently though, you can manage with a small set of basic operations and workflows | 680 | Conveniently though, you can manage with a small set of basic operations and workflows |
681 | once you understand the basic philosophy behind Git. | 681 | once you understand the basic philosophy behind Git. |
682 | You do not have to be an expert in Git to be functional. | 682 | You do not have to be an expert in Git to be functional. |
683 | A good place to look for instruction on a minimal set of Git commands is | 683 | A good place to look for instruction on a minimal set of Git commands is |
684 | <ulink url='http://git-scm.com/documentation'>here</ulink>. | 684 | <ulink url='http://git-scm.com/documentation'>here</ulink>. |
685 | If you need to download Git, you can do so | 685 | If you need to download Git, you can do so |
686 | <ulink url='http://git-scm.com/download'>here</ulink>. | 686 | <ulink url='http://git-scm.com/download'>here</ulink>. |
687 | </para> | 687 | </para> |
688 | 688 | ||
689 | <para> | 689 | <para> |
690 | If you don’t know much about Git, we suggest you educate | 690 | If you don’t know much about Git, we suggest you educate |
691 | yourself by visiting the links previously mentioned. | 691 | yourself by visiting the links previously mentioned. |
692 | </para> | 692 | </para> |
693 | 693 | ||
694 | <para> | 694 | <para> |
695 | The following list briefly describes some basic Git operations as a way to get started. | 695 | The following list briefly describes some basic Git operations as a way to get started. |
696 | As with any set of commands, this list (in most cases) simply shows the base command and | 696 | As with any set of commands, this list (in most cases) simply shows the base command and |
697 | omits the many arguments they support. | 697 | omits the many arguments they support. |
698 | See the Git documentation for complete descriptions and strategies on how to use these commands: | 698 | See the Git documentation for complete descriptions and strategies on how to use these commands: |
699 | <itemizedlist> | 699 | <itemizedlist> |
700 | <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository. | 700 | <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository. |
701 | You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem> | 701 | You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem> |
702 | <listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository. | 702 | <listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository. |
703 | During collaboration, this command allows you to create a local repository that is on | 703 | During collaboration, this command allows you to create a local repository that is on |
704 | equal footing with a fellow developer’s repository.</para></listitem> | 704 | equal footing with a fellow developer’s repository.</para></listitem> |
705 | <listitem><para><emphasis><filename>git add</filename>:</emphasis> Adds updated file contents | 705 | <listitem><para><emphasis><filename>git add</filename>:</emphasis> Adds updated file contents |
706 | to the index that | 706 | to the index that |
707 | Git uses to track changes. | 707 | Git uses to track changes. |
708 | You must add all files that have changed before you can commit them.</para></listitem> | 708 | You must add all files that have changed before you can commit them.</para></listitem> |
709 | <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a “commit” that documents | 709 | <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a “commit” that documents |
710 | the changes you made. | 710 | the changes you made. |
711 | Commits are used for historical purposes, for determining if a maintainer of a project | 711 | Commits are used for historical purposes, for determining if a maintainer of a project |
712 | will allow the change, and for ultimately pushing the change from your local Git repository | 712 | will allow the change, and for ultimately pushing the change from your local Git repository |
713 | into the project’s upstream (or master) repository.</para></listitem> | 713 | into the project’s upstream (or master) repository.</para></listitem> |
714 | <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that | 714 | <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that |
715 | possibly need to be added and committed.</para></listitem> | 715 | possibly need to be added and committed.</para></listitem> |
716 | <listitem><para><emphasis><filename>git checkout <branch-name></filename>:</emphasis> Changes | 716 | <listitem><para><emphasis><filename>git checkout <branch-name></filename>:</emphasis> Changes |
717 | your working branch. | 717 | your working branch. |
718 | This command is analogous to “cd”.</para></listitem> | 718 | This command is analogous to “cd”.</para></listitem> |
719 | <listitem><para><emphasis><filename>git checkout –b <working-branch></filename>:</emphasis> Creates | 719 | <listitem><para><emphasis><filename>git checkout –b <working-branch></filename>:</emphasis> Creates |
720 | a working branch on your local machine where you can isolate work. | 720 | a working branch on your local machine where you can isolate work. |
721 | It is a good idea to use local branches when adding specific features or changes. | 721 | It is a good idea to use local branches when adding specific features or changes. |
722 | This way if you don’t like what you have done you can easily get rid of the work.</para></listitem> | 722 | This way if you don’t like what you have done you can easily get rid of the work.</para></listitem> |
723 | <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports | 723 | <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports |
724 | existing local branches and | 724 | existing local branches and |
725 | tells you the branch in which you are currently working.</para></listitem> | 725 | tells you the branch in which you are currently working.</para></listitem> |
726 | <listitem><para><emphasis><filename>git branch -D <branch-name></filename>:</emphasis> | 726 | <listitem><para><emphasis><filename>git branch -D <branch-name></filename>:</emphasis> |
727 | Deletes an existing local branch. | 727 | Deletes an existing local branch. |
728 | You need to be in a local branch other than the one you are deleting | 728 | You need to be in a local branch other than the one you are deleting |
729 | in order to delete <filename><branch-name></filename>.</para></listitem> | 729 | in order to delete <filename><branch-name></filename>.</para></listitem> |
730 | <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information | 730 | <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information |
731 | from an upstream Git | 731 | from an upstream Git |
732 | repository and places it in your local Git repository. | 732 | repository and places it in your local Git repository. |
733 | You use this command to make sure you are synchronized with the repository | 733 | You use this command to make sure you are synchronized with the repository |
734 | from which you are basing changes (.e.g. the master branch).</para></listitem> | 734 | from which you are basing changes (.e.g. the master branch).</para></listitem> |
735 | <listitem><para><emphasis><filename>git push</filename>:</emphasis> Sends all your local changes you | 735 | <listitem><para><emphasis><filename>git push</filename>:</emphasis> Sends all your local changes you |
736 | have committed to an upstream Git repository (e.g. a contribution repository). | 736 | have committed to an upstream Git repository (e.g. a contribution repository). |
737 | The maintainer of the project draws from these repositories when adding your changes to the | 737 | The maintainer of the project draws from these repositories when adding your changes to the |
738 | project’s master repository.</para></listitem> | 738 | project’s master repository.</para></listitem> |
739 | <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one | 739 | <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one |
740 | local branch of your repository with another branch. | 740 | local branch of your repository with another branch. |
741 | When you create a local Git repository, the default branch is named “master”. | 741 | When you create a local Git repository, the default branch is named “master”. |
742 | A typical workflow is to create a temporary branch for isolated work, make and commit your | 742 | A typical workflow is to create a temporary branch for isolated work, make and commit your |
743 | changes, switch to your local master branch, merge the changes from the temporary branch into the | 743 | changes, switch to your local master branch, merge the changes from the temporary branch into the |
744 | local master branch, and then delete the temporary branch.</para></listitem> | 744 | local master branch, and then delete the temporary branch.</para></listitem> |
745 | <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific | 745 | <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific |
746 | commits from one branch into another branch. | 746 | commits from one branch into another branch. |
747 | There are times when you might not be able to merge all the changes in one branch with | 747 | There are times when you might not be able to merge all the changes in one branch with |
748 | another but need to pick out certain ones.</para></listitem> | 748 | another but need to pick out certain ones.</para></listitem> |
749 | <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches | 749 | <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches |
750 | and changes in your local Git repository. | 750 | and changes in your local Git repository. |
751 | This command is a good way to graphically see where things have diverged in your | 751 | This command is a good way to graphically see where things have diverged in your |
752 | local repository.</para></listitem> | 752 | local repository.</para></listitem> |
753 | <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the | 753 | <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the |
754 | repository.</para></listitem> | 754 | repository.</para></listitem> |
755 | <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences | 755 | <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences |
756 | between your local working files and the same files in the upstream Git repository that your | 756 | between your local working files and the same files in the upstream Git repository that your |
757 | branch currently tracks.</para></listitem> | 757 | branch currently tracks.</para></listitem> |
758 | </itemizedlist> | 758 | </itemizedlist> |
759 | </para> | 759 | </para> |
@@ -764,130 +764,130 @@ | |||
764 | <title>Workflows</title> | 764 | <title>Workflows</title> |
765 | 765 | ||
766 | <para> | 766 | <para> |
767 | This section provides some overview on workflows using Git. | 767 | This section provides some overview on workflows using Git. |
768 | In particular, the information covers basic practices that describe roles and actions in a | 768 | In particular, the information covers basic practices that describe roles and actions in a |
769 | collaborative development environment. | 769 | collaborative development environment. |
770 | Again, if you are familiar with this type of development environment, you might want to just | 770 | Again, if you are familiar with this type of development environment, you might want to just |
771 | skip this section. | 771 | skip this section. |
772 | </para> | 772 | </para> |
773 | 773 | ||
774 | <para> | 774 | <para> |
775 | The Yocto Project files are maintained using Git in a "master" branch whose Git history | 775 | The Yocto Project files are maintained using Git in a "master" branch whose Git history |
776 | tracks every change and whose structure provides branches for all diverging functionality. | 776 | tracks every change and whose structure provides branches for all diverging functionality. |
777 | Although there is no need to use Git, many open source projects do so. | 777 | Although there is no need to use Git, many open source projects do so. |
778 | For the Yocto Project, a key individual called the "maintainer" is responsible for the "master" | 778 | For the Yocto Project, a key individual called the "maintainer" is responsible for the "master" |
779 | branch of the Git repository. | 779 | branch of the Git repository. |
780 | The "master" branch is the “upstream” repository where the final builds of the project occur. | 780 | The "master" branch is the “upstream” repository where the final builds of the project occur. |
781 | The maintainer is responsible for allowing changes in from other developers and for | 781 | The maintainer is responsible for allowing changes in from other developers and for |
782 | organizing the underlying branch structure to reflect release strategies and so forth. | 782 | organizing the underlying branch structure to reflect release strategies and so forth. |
783 | <note>You can see who is the maintainer for Yocto Project files by examining the | 783 | <note>You can see who is the maintainer for Yocto Project files by examining the |
784 | <filename>maintainers.inc</filename> file in the Yocto Project | 784 | <filename>maintainers.inc</filename> file in the Yocto Project |
785 | <filename>meta-yocto/conf/distro/include</filename> directory.</note> | 785 | <filename>meta-yocto/conf/distro/include</filename> directory.</note> |
786 | </para> | 786 | </para> |
787 | 787 | ||
788 | <para> | 788 | <para> |
789 | The project also has contribution repositories known as “contrib” areas. | 789 | The project also has contribution repositories known as “contrib” areas. |
790 | These areas temporarily hold changes to the project that have been submitted or committed | 790 | These areas temporarily hold changes to the project that have been submitted or committed |
791 | by the Yocto Project development team and by community members that contribute to the project. | 791 | by the Yocto Project development team and by community members that contribute to the project. |
792 | The maintainer determines if the changes are qualified to be moved from the "contrib" areas | 792 | The maintainer determines if the changes are qualified to be moved from the "contrib" areas |
793 | into the "master" branch of the Git repository. | 793 | into the "master" branch of the Git repository. |
794 | </para> | 794 | </para> |
795 | 795 | ||
796 | <para> | 796 | <para> |
797 | Developers (including contributing community members) create and maintain cloned repositories | 797 | Developers (including contributing community members) create and maintain cloned repositories |
798 | of the upstream "master" branch. | 798 | of the upstream "master" branch. |
799 | These repositories are local to their development platforms and are used to develop changes. | 799 | These repositories are local to their development platforms and are used to develop changes. |
800 | When a developer is satisfied with a particular feature or change, they “push” the changes | 800 | When a developer is satisfied with a particular feature or change, they “push” the changes |
801 | to the appropriate "contrib" repository. | 801 | to the appropriate "contrib" repository. |
802 | </para> | 802 | </para> |
803 | 803 | ||
804 | <para> | 804 | <para> |
805 | Developers are responsible for keeping their local repository up-to-date with "master". | 805 | Developers are responsible for keeping their local repository up-to-date with "master". |
806 | They are also responsible for straightening out any conflicts that might arise within files | 806 | They are also responsible for straightening out any conflicts that might arise within files |
807 | that are being worked on simultaneously by more than one person. | 807 | that are being worked on simultaneously by more than one person. |
808 | All this work is done locally on the developer’s machine before anything is pushed to a | 808 | All this work is done locally on the developer’s machine before anything is pushed to a |
809 | "contrib" area and examined at the maintainer’s level. | 809 | "contrib" area and examined at the maintainer’s level. |
810 | </para> | 810 | </para> |
811 | 811 | ||
812 | <para> | 812 | <para> |
813 | A somewhat formal method exists by which developers commit changes and push them into the | 813 | A somewhat formal method exists by which developers commit changes and push them into the |
814 | "contrib" area and subsequently request that the maintainer include them into "master" | 814 | "contrib" area and subsequently request that the maintainer include them into "master" |
815 | This process is called “submitting a patch” or “submitting a change.” | 815 | This process is called “submitting a patch” or “submitting a change.” |
816 | For information on submitting patches and changes, see the | 816 | For information on submitting patches and changes, see the |
817 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section. | 817 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section. |
818 | </para> | 818 | </para> |
819 | 819 | ||
820 | <para> | 820 | <para> |
821 | To summarize the environment: we have a single point of entry for changes into the project’s | 821 | To summarize the environment: we have a single point of entry for changes into the project’s |
822 | "master" branch of the Git repository, which is controlled by the project’s maintainer. | 822 | "master" branch of the Git repository, which is controlled by the project’s maintainer. |
823 | And, we have a set of developers who independently develop, test, and submit changes | 823 | And, we have a set of developers who independently develop, test, and submit changes |
824 | to "contrib" areas for the maintainer to examine. | 824 | to "contrib" areas for the maintainer to examine. |
825 | The maintainer then chooses which changes are going to become a permanent part of the project. | 825 | The maintainer then chooses which changes are going to become a permanent part of the project. |
826 | </para> | 826 | </para> |
827 | 827 | ||
828 | <para> | 828 | <para> |
829 | <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" /> | 829 | <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" /> |
830 | </para> | 830 | </para> |
831 | 831 | ||
832 | <para> | 832 | <para> |
833 | While each development environment is unique, there are some best practices or methods | 833 | While each development environment is unique, there are some best practices or methods |
834 | that help development run smoothly. | 834 | that help development run smoothly. |
835 | The following list describes some of these practices. | 835 | The following list describes some of these practices. |
836 | For more information about Git workflows, see the workflow topics in the | 836 | For more information about Git workflows, see the workflow topics in the |
837 | <ulink url='http://book.git-scm.com'>Git Community Book</ulink>. | 837 | <ulink url='http://book.git-scm.com'>Git Community Book</ulink>. |
838 | <itemizedlist> | 838 | <itemizedlist> |
839 | <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit | 839 | <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit |
840 | small as compared to bundling many disparate changes into a single commit. | 840 | small as compared to bundling many disparate changes into a single commit. |
841 | This practice not only keeps things manageable but also allows the maintainer | 841 | This practice not only keeps things manageable but also allows the maintainer |
842 | to more easily include or refuse changes.</para> | 842 | to more easily include or refuse changes.</para> |
843 | <para>It is also good practice to leave the repository in a state that allows you to | 843 | <para>It is also good practice to leave the repository in a state that allows you to |
844 | still successfully build your project. In other words, do not commit half of a feature, | 844 | still successfully build your project. In other words, do not commit half of a feature, |
845 | then add the other half in a separate, later commit. | 845 | then add the other half in a separate, later commit. |
846 | Each commit should take you from one buildable project state to another | 846 | Each commit should take you from one buildable project state to another |
847 | buildable state.</para></listitem> | 847 | buildable state.</para></listitem> |
848 | <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and | 848 | <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and |
849 | delete local branches in your working Git repository. | 849 | delete local branches in your working Git repository. |
850 | You can name these branches anything you like. | 850 | You can name these branches anything you like. |
851 | It is helpful to give them names associated with the particular feature or change | 851 | It is helpful to give them names associated with the particular feature or change |
852 | on which you are working. | 852 | on which you are working. |
853 | Once you are done with a feature or change, simply discard the branch.</para></listitem> | 853 | Once you are done with a feature or change, simply discard the branch.</para></listitem> |
854 | <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename> | 854 | <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename> |
855 | command allows you to take the | 855 | command allows you to take the |
856 | changes from one branch and fold them into another branch. | 856 | changes from one branch and fold them into another branch. |
857 | This process is especially helpful when more than a single developer might be working | 857 | This process is especially helpful when more than a single developer might be working |
858 | on different parts of the same feature. | 858 | on different parts of the same feature. |
859 | Merging changes also automatically identifies any collisions or “conflicts” | 859 | Merging changes also automatically identifies any collisions or “conflicts” |
860 | that might happen as a result of the same lines of code being altered by two different | 860 | that might happen as a result of the same lines of code being altered by two different |
861 | developers.</para></listitem> | 861 | developers.</para></listitem> |
862 | <listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should | 862 | <listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should |
863 | use a system where branches indicate varying levels of code readiness. | 863 | use a system where branches indicate varying levels of code readiness. |
864 | For example, you can have a “work” branch to develop in, a “test” branch where the code or | 864 | For example, you can have a “work” branch to develop in, a “test” branch where the code or |
865 | change is tested, a “stage” branch where changes are ready to be committed, and so forth. | 865 | change is tested, a “stage” branch where changes are ready to be committed, and so forth. |
866 | As your project develops, you can merge code across the branches to reflect ever-increasing | 866 | As your project develops, you can merge code across the branches to reflect ever-increasing |
867 | stable states of the development.</para></listitem> | 867 | stable states of the development.</para></listitem> |
868 | <listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the | 868 | <listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the |
869 | concept of developers “pushing” local commits to a remote repository, which is | 869 | concept of developers “pushing” local commits to a remote repository, which is |
870 | usually a contribution repository. | 870 | usually a contribution repository. |
871 | This workflow is also based on developers “pulling” known states of the project down into their | 871 | This workflow is also based on developers “pulling” known states of the project down into their |
872 | local development repositories. | 872 | local development repositories. |
873 | The workflow easily allows you to pull changes submitted by other developers from the | 873 | The workflow easily allows you to pull changes submitted by other developers from the |
874 | upstream repository into your work area ensuring that you have the most recent software | 874 | upstream repository into your work area ensuring that you have the most recent software |
875 | on which to develop. | 875 | on which to develop. |
876 | The Yocto Project has two scripts named <filename>create-pull-request</filename> and | 876 | The Yocto Project has two scripts named <filename>create-pull-request</filename> and |
877 | <filename>send-pull-request</filename> that ship with the release to facilitate this | 877 | <filename>send-pull-request</filename> that ship with the release to facilitate this |
878 | workflow. | 878 | workflow. |
879 | You can find these scripts in the local Yocto Project files Git repository in | 879 | You can find these scripts in the local Yocto Project files Git repository in |
880 | the <filename>scripts</filename> directory.</para> | 880 | the <filename>scripts</filename> directory.</para> |
881 | <para>You can find more information on these scripts in the | 881 | <para>You can find more information on these scripts in the |
882 | "<link linkend='pushing-a-change-upstream'>Using | 882 | "<link linkend='pushing-a-change-upstream'>Using |
883 | Scripts to Push a Change Upstream and Request a Pull</link>" section. | 883 | Scripts to Push a Change Upstream and Request a Pull</link>" section. |
884 | </para></listitem> | 884 | </para></listitem> |
885 | <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the | 885 | <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the |
886 | maintainer through an email that you have a change (or patch) you would like considered | 886 | maintainer through an email that you have a change (or patch) you would like considered |
887 | for the "master" branch of the Git repository. | 887 | for the "master" branch of the Git repository. |
888 | To send this type of change you format the patch and then send the email using the Git commands | 888 | To send this type of change you format the patch and then send the email using the Git commands |
889 | <filename>git format-patch</filename> and <filename>git send-email</filename>. | 889 | <filename>git format-patch</filename> and <filename>git send-email</filename>. |
890 | You can find information on how to submit changes | 890 | You can find information on how to submit changes |
891 | later in this chapter.</para></listitem> | 891 | later in this chapter.</para></listitem> |
892 | </itemizedlist> | 892 | </itemizedlist> |
893 | </para> | 893 | </para> |
@@ -897,24 +897,24 @@ | |||
897 | <title>Tracking Bugs</title> | 897 | <title>Tracking Bugs</title> |
898 | 898 | ||
899 | <para> | 899 | <para> |
900 | The Yocto Project uses its own implementation of | 900 | The Yocto Project uses its own implementation of |
901 | <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs. | 901 | <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs. |
902 | Implementations of Bugzilla work well for group development because they track bugs and code | 902 | Implementations of Bugzilla work well for group development because they track bugs and code |
903 | changes, can be used to communicate changes and problems with developers, can be used to | 903 | changes, can be used to communicate changes and problems with developers, can be used to |
904 | submit and review patches, and can be used to manage quality assurance. | 904 | submit and review patches, and can be used to manage quality assurance. |
905 | The home page for the Yocto Project implementation of Bugzilla is | 905 | The home page for the Yocto Project implementation of Bugzilla is |
906 | <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>. | 906 | <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>. |
907 | </para> | 907 | </para> |
908 | 908 | ||
909 | <para> | 909 | <para> |
910 | Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself | 910 | Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself |
911 | such as when discovering an issue with some component of the build system that acts contrary | 911 | such as when discovering an issue with some component of the build system that acts contrary |
912 | to the documentation or your expectations. | 912 | to the documentation or your expectations. |
913 | Following is the general procedure for submitting a new bug using the Yocto Project | 913 | Following is the general procedure for submitting a new bug using the Yocto Project |
914 | Bugzilla. | 914 | Bugzilla. |
915 | You can find more information on defect management, bug tracking, and feature request | 915 | You can find more information on defect management, bug tracking, and feature request |
916 | processes all accomplished through the Yocto Project Bugzilla on the wiki page | 916 | processes all accomplished through the Yocto Project Bugzilla on the wiki page |
917 | <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>. | 917 | <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>. |
918 | <orderedlist> | 918 | <orderedlist> |
919 | <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit | 919 | <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit |
920 | a bug.</para></listitem> | 920 | a bug.</para></listitem> |
@@ -922,21 +922,21 @@ | |||
922 | Classification, Product, and Component for which the issue was found. | 922 | Classification, Product, and Component for which the issue was found. |
923 | Defects for Yocto Project fall into one of six classifications: Yocto Project | 923 | Defects for Yocto Project fall into one of six classifications: Yocto Project |
924 | Components, Infrastructure, Build System & Metadata, Documentation, | 924 | Components, Infrastructure, Build System & Metadata, Documentation, |
925 | QA/Testing, and Runtime. | 925 | QA/Testing, and Runtime. |
926 | Each of these Classifications break down into multiple Products and, in some | 926 | Each of these Classifications break down into multiple Products and, in some |
927 | cases, multiple Components.</para></listitem> | 927 | cases, multiple Components.</para></listitem> |
928 | <listitem><para>Use the bug form to choose the correct Hardware and Architecture | 928 | <listitem><para>Use the bug form to choose the correct Hardware and Architecture |
929 | for which the bug applies.</para></listitem> | 929 | for which the bug applies.</para></listitem> |
930 | <listitem><para>Indicate the Yocto Project version you were using when the issue | 930 | <listitem><para>Indicate the Yocto Project version you were using when the issue |
931 | occurred.</para></listitem> | 931 | occurred.</para></listitem> |
932 | <listitem><para>Be sure to indicate the Severity of the bug. | 932 | <listitem><para>Be sure to indicate the Severity of the bug. |
933 | Severity communicates how the bug impacted your work.</para></listitem> | 933 | Severity communicates how the bug impacted your work.</para></listitem> |
934 | <listitem><para>Provide a brief summary of the issue. | 934 | <listitem><para>Provide a brief summary of the issue. |
935 | Try to limit your summary to just a line or two and be sure to capture the | 935 | Try to limit your summary to just a line or two and be sure to capture the |
936 | essence of the issue.</para></listitem> | 936 | essence of the issue.</para></listitem> |
937 | <listitem><para>Provide a detailed description of the issue. | 937 | <listitem><para>Provide a detailed description of the issue. |
938 | You should provide as much detail as you can about the context, behavior, output, | 938 | You should provide as much detail as you can about the context, behavior, output, |
939 | and so forth that surround the issue. | 939 | and so forth that surround the issue. |
940 | You can even attach supporting files for output or log by using the "Add an attachment" | 940 | You can even attach supporting files for output or log by using the "Add an attachment" |
941 | button.</para></listitem> | 941 | button.</para></listitem> |
942 | <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem> | 942 | <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem> |
@@ -954,7 +954,7 @@ | |||
954 | You should send patches to the appropriate mailing list so that they | 954 | You should send patches to the appropriate mailing list so that they |
955 | can be reviewed and merged by the appropriate maintainer. | 955 | can be reviewed and merged by the appropriate maintainer. |
956 | For a list of the Yocto Project and related mailing lists, see the | 956 | For a list of the Yocto Project and related mailing lists, see the |
957 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in | 957 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in |
958 | the Yocto Project Reference Manual. | 958 | the Yocto Project Reference Manual. |
959 | </para> | 959 | </para> |
960 | 960 | ||
@@ -971,7 +971,7 @@ | |||
971 | <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem> | 971 | <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem> |
972 | <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the | 972 | <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the |
973 | <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem> | 973 | <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem> |
974 | <listitem><para>For changes to other layers hosted on | 974 | <listitem><para>For changes to other layers hosted on |
975 | <filename>yoctoproject.org</filename> (unless the | 975 | <filename>yoctoproject.org</filename> (unless the |
976 | layer's documentation specifies otherwise), tools, and Yocto Project | 976 | layer's documentation specifies otherwise), tools, and Yocto Project |
977 | documentation, use the | 977 | documentation, use the |
@@ -983,12 +983,12 @@ | |||
983 | <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or | 983 | <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or |
984 | <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink> | 984 | <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink> |
985 | mailing lists.</para></listitem> | 985 | mailing lists.</para></listitem> |
986 | </itemizedlist> | 986 | </itemizedlist> |
987 | </para> | 987 | </para> |
988 | 988 | ||
989 | <para> | 989 | <para> |
990 | When you send a patch, be sure to include a "Signed-off-by:" | 990 | When you send a patch, be sure to include a "Signed-off-by:" |
991 | line in the same style as required by the Linux kernel. | 991 | line in the same style as required by the Linux kernel. |
992 | Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 | 992 | Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 |
993 | as follows: | 993 | as follows: |
994 | <literallayout class='monospaced'> | 994 | <literallayout class='monospaced'> |
@@ -1021,8 +1021,8 @@ | |||
1021 | </para> | 1021 | </para> |
1022 | 1022 | ||
1023 | <para> | 1023 | <para> |
1024 | In a collaborative environment, it is necessary to have some sort of standard | 1024 | In a collaborative environment, it is necessary to have some sort of standard |
1025 | or method through which you submit changes. | 1025 | or method through which you submit changes. |
1026 | Otherwise, things could get quite chaotic. | 1026 | Otherwise, things could get quite chaotic. |
1027 | One general practice to follow is to make small, controlled changes. | 1027 | One general practice to follow is to make small, controlled changes. |
1028 | Keeping changes small and isolated aids review, makes merging/rebasing easier | 1028 | Keeping changes small and isolated aids review, makes merging/rebasing easier |
@@ -1035,14 +1035,14 @@ | |||
1035 | For each commit, you must provide a single-line summary of the change and you | 1035 | For each commit, you must provide a single-line summary of the change and you |
1036 | should almost always provide a more detailed description of what you did (i.e. | 1036 | should almost always provide a more detailed description of what you did (i.e. |
1037 | the body of the commit message). | 1037 | the body of the commit message). |
1038 | The only exceptions for not providing a detailed description would be if your | 1038 | The only exceptions for not providing a detailed description would be if your |
1039 | change is a simple, self-explanatory change that needs no further description | 1039 | change is a simple, self-explanatory change that needs no further description |
1040 | beyond the summary. | 1040 | beyond the summary. |
1041 | Here are the guidelines for composing a commit message: | 1041 | Here are the guidelines for composing a commit message: |
1042 | <itemizedlist> | 1042 | <itemizedlist> |
1043 | <listitem><para>Provide a single-line, short summary of the change. | 1043 | <listitem><para>Provide a single-line, short summary of the change. |
1044 | This summary is typically viewable in the "shortlist" of changes. | 1044 | This summary is typically viewable in the "shortlist" of changes. |
1045 | Thus, providing something short and descriptive that gives the reader | 1045 | Thus, providing something short and descriptive that gives the reader |
1046 | a summary of the change is useful when viewing a list of many commits. | 1046 | a summary of the change is useful when viewing a list of many commits. |
1047 | This should be prefixed by the recipe name (if changing a recipe), or | 1047 | This should be prefixed by the recipe name (if changing a recipe), or |
1048 | else the short form path to the file being changed. | 1048 | else the short form path to the file being changed. |
@@ -1052,7 +1052,7 @@ | |||
1052 | you used. It may also be helpful if you mention how you tested the change. | 1052 | you used. It may also be helpful if you mention how you tested the change. |
1053 | Provide as much detail as you can in the body of the commit message. | 1053 | Provide as much detail as you can in the body of the commit message. |
1054 | </para></listitem> | 1054 | </para></listitem> |
1055 | <listitem><para>If the change addresses a specific bug or issue that is | 1055 | <listitem><para>If the change addresses a specific bug or issue that is |
1056 | associated with a bug-tracking ID, include a reference to that ID in | 1056 | associated with a bug-tracking ID, include a reference to that ID in |
1057 | your detailed description. | 1057 | your detailed description. |
1058 | For example, the Yocto Project uses a specific convention for bug | 1058 | For example, the Yocto Project uses a specific convention for bug |
@@ -1069,15 +1069,15 @@ | |||
1069 | </para> | 1069 | </para> |
1070 | 1070 | ||
1071 | <para> | 1071 | <para> |
1072 | You can find more guidance on creating well-formed commit messages at this OpenEmbedded | 1072 | You can find more guidance on creating well-formed commit messages at this OpenEmbedded |
1073 | wiki page: | 1073 | wiki page: |
1074 | <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>. | 1074 | <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>. |
1075 | </para> | 1075 | </para> |
1076 | 1076 | ||
1077 | <para> | 1077 | <para> |
1078 | Following are general instructions for both pushing changes upstream and for submitting | 1078 | Following are general instructions for both pushing changes upstream and for submitting |
1079 | changes as patches. | 1079 | changes as patches. |
1080 | </para> | 1080 | </para> |
1081 | 1081 | ||
1082 | <section id='pushing-a-change-upstream'> | 1082 | <section id='pushing-a-change-upstream'> |
1083 | <title>Using Scripts to Push a Change Upstream and Request a Pull</title> | 1083 | <title>Using Scripts to Push a Change Upstream and Request a Pull</title> |
@@ -1089,23 +1089,23 @@ | |||
1089 | <listitem><para>Stage your changes by using the <filename>git add</filename> | 1089 | <listitem><para>Stage your changes by using the <filename>git add</filename> |
1090 | command on each file you changed.</para></listitem> | 1090 | command on each file you changed.</para></listitem> |
1091 | <listitem><para>Commit the change by using the <filename>git commit</filename> | 1091 | <listitem><para>Commit the change by using the <filename>git commit</filename> |
1092 | command and push it to the "contrib" repository. | 1092 | command and push it to the "contrib" repository. |
1093 | Be sure to provide a commit message that follows the project’s commit message standards | 1093 | Be sure to provide a commit message that follows the project’s commit message standards |
1094 | as described earlier.</para></listitem> | 1094 | as described earlier.</para></listitem> |
1095 | <listitem><para>Notify the maintainer that you have pushed a change by making a pull | 1095 | <listitem><para>Notify the maintainer that you have pushed a change by making a pull |
1096 | request. | 1096 | request. |
1097 | The Yocto Project provides two scripts that conveniently let you generate and send | 1097 | The Yocto Project provides two scripts that conveniently let you generate and send |
1098 | pull requests to the Yocto Project. | 1098 | pull requests to the Yocto Project. |
1099 | These scripts are <filename>create-pull-request</filename> and | 1099 | These scripts are <filename>create-pull-request</filename> and |
1100 | <filename>send-pull-request</filename>. | 1100 | <filename>send-pull-request</filename>. |
1101 | You can find these scripts in the <filename>scripts</filename> directory | 1101 | You can find these scripts in the <filename>scripts</filename> directory |
1102 | within the <link linkend='source-directory'>Source Directory</link>.</para> | 1102 | within the <link linkend='source-directory'>Source Directory</link>.</para> |
1103 | <para>Using these scripts correctly formats the requests without introducing any | 1103 | <para>Using these scripts correctly formats the requests without introducing any |
1104 | whitespace or HTML formatting. | 1104 | whitespace or HTML formatting. |
1105 | The maintainer that receives your patches needs to be able to save and apply them | 1105 | The maintainer that receives your patches needs to be able to save and apply them |
1106 | directly from your emails. | 1106 | directly from your emails. |
1107 | Using these scripts is the preferred method for sending patches.</para> | 1107 | Using these scripts is the preferred method for sending patches.</para> |
1108 | <para>For help on using these scripts, simply provide the | 1108 | <para>For help on using these scripts, simply provide the |
1109 | <filename>-h</filename> argument as follows: | 1109 | <filename>-h</filename> argument as follows: |
1110 | <literallayout class='monospaced'> | 1110 | <literallayout class='monospaced'> |
1111 | $ ~/poky/scripts/create-pull-request -h | 1111 | $ ~/poky/scripts/create-pull-request -h |
@@ -1114,8 +1114,8 @@ | |||
1114 | </itemizedlist> | 1114 | </itemizedlist> |
1115 | </para> | 1115 | </para> |
1116 | 1116 | ||
1117 | <para> | 1117 | <para> |
1118 | You can find general Git information on how to push a change upstream in the | 1118 | You can find general Git information on how to push a change upstream in the |
1119 | <ulink url='http://book.git-scm.com/3_distributed_workflows.html'>Git Community Book</ulink>. | 1119 | <ulink url='http://book.git-scm.com/3_distributed_workflows.html'>Git Community Book</ulink>. |
1120 | </para> | 1120 | </para> |
1121 | </section> | 1121 | </section> |
@@ -1124,7 +1124,7 @@ | |||
1124 | <title>Using Email to Submit a Patch</title> | 1124 | <title>Using Email to Submit a Patch</title> |
1125 | 1125 | ||
1126 | <para> | 1126 | <para> |
1127 | You can submit patches without using the <filename>create-pull-request</filename> and | 1127 | You can submit patches without using the <filename>create-pull-request</filename> and |
1128 | <filename>send-pull-request</filename> scripts described in the previous section. | 1128 | <filename>send-pull-request</filename> scripts described in the previous section. |
1129 | Keep in mind, the preferred method is to use the scripts, however. | 1129 | Keep in mind, the preferred method is to use the scripts, however. |
1130 | </para> | 1130 | </para> |
@@ -1132,7 +1132,7 @@ | |||
1132 | <para> | 1132 | <para> |
1133 | Depending on the components changed, you need to submit the email to a specific | 1133 | Depending on the components changed, you need to submit the email to a specific |
1134 | mailing list. | 1134 | mailing list. |
1135 | For some guidance on which mailing list to use, see the list in the | 1135 | For some guidance on which mailing list to use, see the list in the |
1136 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section | 1136 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section |
1137 | earlier in this manual. | 1137 | earlier in this manual. |
1138 | For a description of the available mailing lists, see | 1138 | For a description of the available mailing lists, see |
@@ -1140,71 +1140,71 @@ | |||
1140 | section in the Yocto Project Reference Manual. | 1140 | section in the Yocto Project Reference Manual. |
1141 | </para> | 1141 | </para> |
1142 | 1142 | ||
1143 | <para> | 1143 | <para> |
1144 | Here is the general procedure on how to submit a patch through email without using the | 1144 | Here is the general procedure on how to submit a patch through email without using the |
1145 | scripts: | 1145 | scripts: |
1146 | <itemizedlist> | 1146 | <itemizedlist> |
1147 | <listitem><para>Make your changes in your local Git repository.</para></listitem> | 1147 | <listitem><para>Make your changes in your local Git repository.</para></listitem> |
1148 | <listitem><para>Stage your changes by using the <filename>git add</filename> | 1148 | <listitem><para>Stage your changes by using the <filename>git add</filename> |
1149 | command on each file you changed.</para></listitem> | 1149 | command on each file you changed.</para></listitem> |
1150 | <listitem><para>Commit the change by using the | 1150 | <listitem><para>Commit the change by using the |
1151 | <filename>git commit --signoff</filename> command. | 1151 | <filename>git commit --signoff</filename> command. |
1152 | Using the <filename>--signoff</filename> option identifies you as the person | 1152 | Using the <filename>--signoff</filename> option identifies you as the person |
1153 | making the change and also satisfies the Developer's Certificate of | 1153 | making the change and also satisfies the Developer's Certificate of |
1154 | Origin (DCO) shown earlier.</para> | 1154 | Origin (DCO) shown earlier.</para> |
1155 | <para>When you form a commit you must follow certain standards established by the | 1155 | <para>When you form a commit you must follow certain standards established by the |
1156 | Yocto Project development team. | 1156 | Yocto Project development team. |
1157 | See the earlier section | 1157 | See the earlier section |
1158 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | 1158 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" |
1159 | for Yocto Project commit message standards.</para></listitem> | 1159 | for Yocto Project commit message standards.</para></listitem> |
1160 | <listitem><para>Format the commit into an email message. | 1160 | <listitem><para>Format the commit into an email message. |
1161 | To format commits, use the <filename>git format-patch</filename> command. | 1161 | To format commits, use the <filename>git format-patch</filename> command. |
1162 | When you provide the command, you must include a revision list or a number of patches | 1162 | When you provide the command, you must include a revision list or a number of patches |
1163 | as part of the command. | 1163 | as part of the command. |
1164 | For example, these two commands each take the most recent single commit and | 1164 | For example, these two commands each take the most recent single commit and |
1165 | format it as an email message in the current directory: | 1165 | format it as an email message in the current directory: |
1166 | <literallayout class='monospaced'> | 1166 | <literallayout class='monospaced'> |
1167 | $ git format-patch -1 | 1167 | $ git format-patch -1 |
1168 | $ git format-patch HEAD~ | 1168 | $ git format-patch HEAD~ |
1169 | </literallayout></para> | 1169 | </literallayout></para> |
1170 | <para>After the command is run, the current directory contains a | 1170 | <para>After the command is run, the current directory contains a |
1171 | numbered <filename>.patch</filename> file for the commit.</para> | 1171 | numbered <filename>.patch</filename> file for the commit.</para> |
1172 | <para>If you provide several commits as part of the command, | 1172 | <para>If you provide several commits as part of the command, |
1173 | the <filename>git format-patch</filename> command produces a numbered | 1173 | the <filename>git format-patch</filename> command produces a numbered |
1174 | series of files in the current directory – one for each commit. | 1174 | series of files in the current directory – one for each commit. |
1175 | If you have more than one patch, you should also use the | 1175 | If you have more than one patch, you should also use the |
1176 | <filename>--cover</filename> option with the command, which generates a | 1176 | <filename>--cover</filename> option with the command, which generates a |
1177 | cover letter as the first "patch" in the series. | 1177 | cover letter as the first "patch" in the series. |
1178 | You can then edit the cover letter to provide a description for | 1178 | You can then edit the cover letter to provide a description for |
1179 | the series of patches. | 1179 | the series of patches. |
1180 | For information on the <filename>git format-patch</filename> command, | 1180 | For information on the <filename>git format-patch</filename> command, |
1181 | see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the | 1181 | see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the |
1182 | <filename>man git-format-patch</filename> command.</para> | 1182 | <filename>man git-format-patch</filename> command.</para> |
1183 | <note>If you are or will be a frequent contributor to the Yocto Project | 1183 | <note>If you are or will be a frequent contributor to the Yocto Project |
1184 | or to OpenEmbedded, you might consider requesting a contrib area and the | 1184 | or to OpenEmbedded, you might consider requesting a contrib area and the |
1185 | necessary associated rights.</note></listitem> | 1185 | necessary associated rights.</note></listitem> |
1186 | <listitem><para>Import the files into your mail client by using the | 1186 | <listitem><para>Import the files into your mail client by using the |
1187 | <filename>git send-email</filename> command. | 1187 | <filename>git send-email</filename> command. |
1188 | <note>In order to use <filename>git send-email</filename>, you must have the | 1188 | <note>In order to use <filename>git send-email</filename>, you must have the |
1189 | the proper Git packages installed. | 1189 | the proper Git packages installed. |
1190 | For Ubuntu and Fedora the package is <filename>git-email</filename>.</note></para> | 1190 | For Ubuntu and Fedora the package is <filename>git-email</filename>.</note></para> |
1191 | <para>The <filename>git send-email</filename> command sends email by using a local | 1191 | <para>The <filename>git send-email</filename> command sends email by using a local |
1192 | or remote Mail Transport Agent (MTA) such as | 1192 | or remote Mail Transport Agent (MTA) such as |
1193 | <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct | 1193 | <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct |
1194 | <filename>smtp</filename> configuration in your Git <filename>config</filename> | 1194 | <filename>smtp</filename> configuration in your Git <filename>config</filename> |
1195 | file. | 1195 | file. |
1196 | If you are submitting patches through email only, it is very important | 1196 | If you are submitting patches through email only, it is very important |
1197 | that you submit them without any whitespace or HTML formatting that | 1197 | that you submit them without any whitespace or HTML formatting that |
1198 | either you or your mailer introduces. | 1198 | either you or your mailer introduces. |
1199 | The maintainer that receives your patches needs to be able to save and | 1199 | The maintainer that receives your patches needs to be able to save and |
1200 | apply them directly from your emails. | 1200 | apply them directly from your emails. |
1201 | A good way to verify that what you are sending will be applicable by the | 1201 | A good way to verify that what you are sending will be applicable by the |
1202 | maintainer is to do a dry run and send them to yourself and then | 1202 | maintainer is to do a dry run and send them to yourself and then |
1203 | save and apply them as the maintainer would.</para> | 1203 | save and apply them as the maintainer would.</para> |
1204 | <para>The <filename>git send-email</filename> command is the preferred method | 1204 | <para>The <filename>git send-email</filename> command is the preferred method |
1205 | for sending your patches since there is no risk of compromising whitespace | 1205 | for sending your patches since there is no risk of compromising whitespace |
1206 | in the body of the message, which can occur when you use your own mail client. | 1206 | in the body of the message, which can occur when you use your own mail client. |
1207 | The command also has several options that let you | 1207 | The command also has several options that let you |
1208 | specify recipients and perform further editing of the email message. | 1208 | specify recipients and perform further editing of the email message. |
1209 | For information on how to use the <filename>git send-email</filename> command, | 1209 | For information on how to use the <filename>git send-email</filename> command, |
1210 | use the <filename>man git-send-email</filename> command.</para></listitem> | 1210 | use the <filename>man git-send-email</filename> command.</para></listitem> |
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml index 11d4adca9f..299a02d581 100644 --- a/documentation/dev-manual/dev-manual-start.xml +++ b/documentation/dev-manual/dev-manual-start.xml | |||
@@ -7,14 +7,14 @@ | |||
7 | <title>Getting Started with the Yocto Project</title> | 7 | <title>Getting Started with the Yocto Project</title> |
8 | 8 | ||
9 | <para> | 9 | <para> |
10 | This chapter introduces the Yocto Project and gives you an idea of what you need to get started. | 10 | This chapter introduces the Yocto Project and gives you an idea of what you need to get started. |
11 | You can find enough information to set up your development host and build or use images for | 11 | You can find enough information to set up your development host and build or use images for |
12 | hardware supported by the Yocto Project by reading the | 12 | hardware supported by the Yocto Project by reading the |
13 | <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. | 13 | <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. |
14 | </para> | 14 | </para> |
15 | 15 | ||
16 | <para> | 16 | <para> |
17 | The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides | 17 | The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides |
18 | some higher-level concepts you might want to consider. | 18 | some higher-level concepts you might want to consider. |
19 | </para> | 19 | </para> |
20 | 20 | ||
@@ -22,24 +22,24 @@ | |||
22 | <title>Introducing the Yocto Project</title> | 22 | <title>Introducing the Yocto Project</title> |
23 | 23 | ||
24 | <para> | 24 | <para> |
25 | The Yocto Project is an open-source collaboration project focused on embedded Linux development. | 25 | The Yocto Project is an open-source collaboration project focused on embedded Linux development. |
26 | The project currently provides a build system, which is | 26 | The project currently provides a build system, which is |
27 | referred to as the OpenEmbedded build system in the Yocto Project documentation. | 27 | referred to as the OpenEmbedded build system in the Yocto Project documentation. |
28 | The Yocto Project provides various ancillary tools suitable for the embedded developer | 28 | The Yocto Project provides various ancillary tools suitable for the embedded developer |
29 | and also features the Sato reference User Interface, which is optimized for | 29 | and also features the Sato reference User Interface, which is optimized for |
30 | stylus driven, low-resolution screens. | 30 | stylus driven, low-resolution screens. |
31 | </para> | 31 | </para> |
32 | 32 | ||
33 | <para> | 33 | <para> |
34 | You can use the OpenEmbedded build system, which uses | 34 | You can use the OpenEmbedded build system, which uses |
35 | BitBake to develop complete Linux | 35 | BitBake to develop complete Linux |
36 | images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, | 36 | images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, |
37 | x86 and x86-64. | 37 | x86 and x86-64. |
38 | While the Yocto Project does not provide a strict testing framework, | 38 | While the Yocto Project does not provide a strict testing framework, |
39 | it does provide or generate for you artifacts that let you perform target-level and | 39 | it does provide or generate for you artifacts that let you perform target-level and |
40 | emulated testing and debugging. | 40 | emulated testing and debugging. |
41 | Additionally, if you are an <trademark class='trade'>Eclipse</trademark> | 41 | Additionally, if you are an <trademark class='trade'>Eclipse</trademark> |
42 | IDE user, you can install an Eclipse Yocto Plug-in to allow you to | 42 | IDE user, you can install an Eclipse Yocto Plug-in to allow you to |
43 | develop within that familiar environment. | 43 | develop within that familiar environment. |
44 | </para> | 44 | </para> |
45 | </section> | 45 | </section> |
@@ -50,59 +50,59 @@ | |||
50 | <para> | 50 | <para> |
51 | Here is what you need to get set up to use the Yocto Project: | 51 | Here is what you need to get set up to use the Yocto Project: |
52 | <itemizedlist> | 52 | <itemizedlist> |
53 | <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current | 53 | <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current |
54 | Linux-based host system. | 54 | Linux-based host system. |
55 | You will have the best results with a recent release of Fedora, | 55 | You will have the best results with a recent release of Fedora, |
56 | OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project | 56 | OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project |
57 | and officially supported. | 57 | and officially supported. |
58 | For a list of the distributions under validation and their status, see the | 58 | For a list of the distributions under validation and their status, see the |
59 | "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section | 59 | "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section |
60 | in the Yocto Project Reference Manual and the wiki page at | 60 | in the Yocto Project Reference Manual and the wiki page at |
61 | <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para> | 61 | <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para> |
62 | <para> | 62 | <para> |
63 | You should also have about 100 gigabytes of free disk space for building images. | 63 | You should also have about 100 gigabytes of free disk space for building images. |
64 | </para></listitem> | 64 | </para></listitem> |
65 | <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system | 65 | <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system |
66 | requires certain packages exist on your development system (e.g. Python 2.6 or 2.7). | 66 | requires certain packages exist on your development system (e.g. Python 2.6 or 2.7). |
67 | See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" | 67 | See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" |
68 | section in the Yocto Project Quick Start for the exact package | 68 | section in the Yocto Project Quick Start for the exact package |
69 | requirements and the installation commands to install them | 69 | requirements and the installation commands to install them |
70 | for the supported distributions.</para></listitem> | 70 | for the supported distributions.</para></listitem> |
71 | <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis> | 71 | <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis> |
72 | You need a release of the Yocto Project. | 72 | You need a release of the Yocto Project. |
73 | You set up a with local <link linkend='source-directory'>Source Directory</link> | 73 | You set up a with local <link linkend='source-directory'>Source Directory</link> |
74 | one of two ways depending on whether you | 74 | one of two ways depending on whether you |
75 | are going to contribute back into the Yocto Project or not. | 75 | are going to contribute back into the Yocto Project or not. |
76 | <note> | 76 | <note> |
77 | Regardless of the method you use, this manual refers to the resulting local | 77 | Regardless of the method you use, this manual refers to the resulting local |
78 | hierarchical set of files as the "Source Directory." | 78 | hierarchical set of files as the "Source Directory." |
79 | </note> | 79 | </note> |
80 | <itemizedlist> | 80 | <itemizedlist> |
81 | <listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute | 81 | <listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute |
82 | back into the Yocto Project, you can simply download a Yocto Project release you want | 82 | back into the Yocto Project, you can simply download a Yocto Project release you want |
83 | from the website’s <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink>. | 83 | from the website’s <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink>. |
84 | Once you have the tarball, just extract it into a directory of your choice.</para> | 84 | Once you have the tarball, just extract it into a directory of your choice.</para> |
85 | <para>For example, the following command extracts the Yocto Project &DISTRO; | 85 | <para>For example, the following command extracts the Yocto Project &DISTRO; |
86 | release tarball | 86 | release tarball |
87 | into the current working directory and sets up the local Source Directory | 87 | into the current working directory and sets up the local Source Directory |
88 | with a top-level folder named <filename>&YOCTO_POKY;</filename>: | 88 | with a top-level folder named <filename>&YOCTO_POKY;</filename>: |
89 | <literallayout class='monospaced'> | 89 | <literallayout class='monospaced'> |
90 | $ tar xfj &YOCTO_POKY_TARBALL; | 90 | $ tar xfj &YOCTO_POKY_TARBALL; |
91 | </literallayout></para> | 91 | </literallayout></para> |
92 | <para>This method does not produce a local Git repository. | 92 | <para>This method does not produce a local Git repository. |
93 | Instead, you simply end up with a snapshot of the release.</para></listitem> | 93 | Instead, you simply end up with a snapshot of the release.</para></listitem> |
94 | <listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing | 94 | <listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing |
95 | back into the Yocto Project or you simply want to keep up | 95 | back into the Yocto Project or you simply want to keep up |
96 | with the latest developments, you should use Git commands to set up a local | 96 | with the latest developments, you should use Git commands to set up a local |
97 | Git repository of the upstream <filename>poky</filename> source repository. | 97 | Git repository of the upstream <filename>poky</filename> source repository. |
98 | Doing so creates a repository with a complete history of changes and allows | 98 | Doing so creates a repository with a complete history of changes and allows |
99 | you to easily submit your changes upstream to the project. | 99 | you to easily submit your changes upstream to the project. |
100 | Because you cloned the repository, you have access to all the Yocto Project development | 100 | Because you cloned the repository, you have access to all the Yocto Project development |
101 | branches and tag names used in the upstream repository.</para> | 101 | branches and tag names used in the upstream repository.</para> |
102 | <para>The following transcript shows how to clone the <filename>poky</filename> | 102 | <para>The following transcript shows how to clone the <filename>poky</filename> |
103 | Git repository into the current working directory. | 103 | Git repository into the current working directory. |
104 | <note>You can view the Yocto Project Source Repositories at | 104 | <note>You can view the Yocto Project Source Repositories at |
105 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note> | 105 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note> |
106 | The command creates the local repository in a directory named <filename>poky</filename>. | 106 | The command creates the local repository in a directory named <filename>poky</filename>. |
107 | For information on Git used within the Yocto Project, see the | 107 | For information on Git used within the Yocto Project, see the |
108 | "<link linkend='git'>Git</link>" section. | 108 | "<link linkend='git'>Git</link>" section. |
@@ -120,27 +120,27 @@ | |||
120 | wiki page</ulink>, which describes how to create both <filename>poky</filename> | 120 | wiki page</ulink>, which describes how to create both <filename>poky</filename> |
121 | and <filename>meta-intel</filename> Git repositories.</para></listitem> | 121 | and <filename>meta-intel</filename> Git repositories.</para></listitem> |
122 | </itemizedlist></para></listitem> | 122 | </itemizedlist></para></listitem> |
123 | <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis> | 123 | <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis> |
124 | If you are going to be making modifications to a supported Yocto Project kernel, you | 124 | If you are going to be making modifications to a supported Yocto Project kernel, you |
125 | need to establish local copies of the source. | 125 | need to establish local copies of the source. |
126 | You can find Git repositories of supported Yocto Project Kernels organized under | 126 | You can find Git repositories of supported Yocto Project Kernels organized under |
127 | "Yocto Linux Kernel" in the Yocto Project Source Repositories at | 127 | "Yocto Linux Kernel" in the Yocto Project Source Repositories at |
128 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> | 128 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> |
129 | <para>This setup can involve creating a bare clone of the Yocto Project kernel and then | 129 | <para>This setup can involve creating a bare clone of the Yocto Project kernel and then |
130 | copying that cloned repository. | 130 | copying that cloned repository. |
131 | You can create the bare clone and the copy of the bare clone anywhere you like. | 131 | You can create the bare clone and the copy of the bare clone anywhere you like. |
132 | For simplicity, it is recommended that you create these structures outside of the | 132 | For simplicity, it is recommended that you create these structures outside of the |
133 | Source Directory (usually <filename>poky</filename>).</para> | 133 | Source Directory (usually <filename>poky</filename>).</para> |
134 | <para>As an example, the following transcript shows how to create the bare clone | 134 | <para>As an example, the following transcript shows how to create the bare clone |
135 | of the <filename>linux-yocto-3.4</filename> kernel and then create a copy of | 135 | of the <filename>linux-yocto-3.4</filename> kernel and then create a copy of |
136 | that clone. | 136 | that clone. |
137 | <note>When you have a local Yocto Project kernel Git repository, you can | 137 | <note>When you have a local Yocto Project kernel Git repository, you can |
138 | reference that repository rather than the upstream Git repository as | 138 | reference that repository rather than the upstream Git repository as |
139 | part of the <filename>clone</filename> command. | 139 | part of the <filename>clone</filename> command. |
140 | Doing so can speed up the process.</note></para> | 140 | Doing so can speed up the process.</note></para> |
141 | <para>In the following example, the bare clone is named | 141 | <para>In the following example, the bare clone is named |
142 | <filename>linux-yocto-3.4.git</filename>, while the | 142 | <filename>linux-yocto-3.4.git</filename>, while the |
143 | copy is named <filename>my-linux-yocto-3.4-work</filename>: | 143 | copy is named <filename>my-linux-yocto-3.4-work</filename>: |
144 | <literallayout class='monospaced'> | 144 | <literallayout class='monospaced'> |
145 | $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.4 linux-yocto-3.4.git | 145 | $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.4 linux-yocto-3.4.git |
146 | Initialized empty Git repository in /home/scottrif/linux-yocto-3.4.git/ | 146 | Initialized empty Git repository in /home/scottrif/linux-yocto-3.4.git/ |
@@ -158,20 +158,20 @@ | |||
158 | </literallayout></para></listitem> | 158 | </literallayout></para></listitem> |
159 | <listitem id='poky-extras-repo'><para><emphasis> | 159 | <listitem id='poky-extras-repo'><para><emphasis> |
160 | The <filename>poky-extras</filename> Git Repository</emphasis>: | 160 | The <filename>poky-extras</filename> Git Repository</emphasis>: |
161 | The <filename>poky-extras</filename> Git repository contains metadata needed | 161 | The <filename>poky-extras</filename> Git repository contains metadata needed |
162 | only if you are modifying and building the kernel image. | 162 | only if you are modifying and building the kernel image. |
163 | In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>) | 163 | In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>) |
164 | files that you | 164 | files that you |
165 | edit to point to your locally modified kernel source files and to build the kernel | 165 | edit to point to your locally modified kernel source files and to build the kernel |
166 | image. | 166 | image. |
167 | Pointing to these local files is much more efficient than requiring a download of the | 167 | Pointing to these local files is much more efficient than requiring a download of the |
168 | kernel's source files from upstream each time you make changes to the kernel.</para> | 168 | kernel's source files from upstream each time you make changes to the kernel.</para> |
169 | <para>You can find the <filename>poky-extras</filename> Git Repository in the | 169 | <para>You can find the <filename>poky-extras</filename> Git Repository in the |
170 | "Yocto Metadata Layers" area of the Yocto Project Source Repositories at | 170 | "Yocto Metadata Layers" area of the Yocto Project Source Repositories at |
171 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. | 171 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. |
172 | It is good practice to create this Git repository inside the Source Directory.</para> | 172 | It is good practice to create this Git repository inside the Source Directory.</para> |
173 | <para>Following is an example that creates the <filename>poky-extras</filename> Git | 173 | <para>Following is an example that creates the <filename>poky-extras</filename> Git |
174 | repository inside the Source Directory, which is named <filename>poky</filename> | 174 | repository inside the Source Directory, which is named <filename>poky</filename> |
175 | in this case: | 175 | in this case: |
176 | <literallayout class='monospaced'> | 176 | <literallayout class='monospaced'> |
177 | $ cd ~/poky | 177 | $ cd ~/poky |
@@ -183,21 +183,21 @@ | |||
183 | Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done. | 183 | Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done. |
184 | Resolving deltas: 100% (192/192), done. | 184 | Resolving deltas: 100% (192/192), done. |
185 | </literallayout></para></listitem> | 185 | </literallayout></para></listitem> |
186 | <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board | 186 | <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board |
187 | Support Packages (BSPs):</emphasis> | 187 | Support Packages (BSPs):</emphasis> |
188 | The Yocto Project provides a layer called <filename>meta-intel</filename> and | 188 | The Yocto Project provides a layer called <filename>meta-intel</filename> and |
189 | it is maintained in its own separate Git repository. | 189 | it is maintained in its own separate Git repository. |
190 | The <filename>meta-intel</filename> layer contains many supported | 190 | The <filename>meta-intel</filename> layer contains many supported |
191 | <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para> | 191 | <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para> |
192 | <para>Similar considerations exist for setting up the <filename>meta-intel</filename> | 192 | <para>Similar considerations exist for setting up the <filename>meta-intel</filename> |
193 | layer. | 193 | layer. |
194 | You can get set up for BSP development one of two ways: tarball extraction or | 194 | You can get set up for BSP development one of two ways: tarball extraction or |
195 | with a local Git repository. | 195 | with a local Git repository. |
196 | It is a good idea to use the same method that you used to set up the Source Directory. | 196 | It is a good idea to use the same method that you used to set up the Source Directory. |
197 | Regardless of the method you use, the Yocto Project uses the following BSP layer | 197 | Regardless of the method you use, the Yocto Project uses the following BSP layer |
198 | naming scheme: | 198 | naming scheme: |
199 | <literallayout class='monospaced'> | 199 | <literallayout class='monospaced'> |
200 | meta-<BSP_name> | 200 | meta-<BSP_name> |
201 | </literallayout> | 201 | </literallayout> |
202 | where <filename><BSP_name></filename> is the recognized BSP name. | 202 | where <filename><BSP_name></filename> is the recognized BSP name. |
203 | Here are some examples: | 203 | Here are some examples: |
@@ -211,22 +211,22 @@ | |||
211 | section in the Yocto Project Board Support Package (BSP) Developer's Guide for more | 211 | section in the Yocto Project Board Support Package (BSP) Developer's Guide for more |
212 | information on BSP Layers. | 212 | information on BSP Layers. |
213 | <itemizedlist> | 213 | <itemizedlist> |
214 | <listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released | 214 | <listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released |
215 | BSP tarball from the same | 215 | BSP tarball from the same |
216 | <ulink url='&YOCTO_HOME_URL;/download'>download site</ulink> used | 216 | <ulink url='&YOCTO_HOME_URL;/download'>download site</ulink> used |
217 | to get the Yocto Project release. | 217 | to get the Yocto Project release. |
218 | Once you have the tarball, just extract it into a directory of your choice. | 218 | Once you have the tarball, just extract it into a directory of your choice. |
219 | Again, this method just produces a snapshot of the BSP layer in the form | 219 | Again, this method just produces a snapshot of the BSP layer in the form |
220 | of a hierarchical directory structure.</para></listitem> | 220 | of a hierarchical directory structure.</para></listitem> |
221 | <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working | 221 | <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working |
222 | with a local Git repository for your Source Directory, you should also use this method | 222 | with a local Git repository for your Source Directory, you should also use this method |
223 | to set up the <filename>meta-intel</filename> Git repository. | 223 | to set up the <filename>meta-intel</filename> Git repository. |
224 | You can locate the <filename>meta-intel</filename> Git repository in the | 224 | You can locate the <filename>meta-intel</filename> Git repository in the |
225 | "Yocto Metadata Layers" area of the Yocto Project Source Repositories at | 225 | "Yocto Metadata Layers" area of the Yocto Project Source Repositories at |
226 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> | 226 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> |
227 | <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside | 227 | <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside |
228 | the Source Directory. | 228 | the Source Directory. |
229 | For example, the following transcript shows the steps to clone the | 229 | For example, the following transcript shows the steps to clone the |
230 | <filename>meta-intel</filename> | 230 | <filename>meta-intel</filename> |
231 | Git repository inside the local <filename>poky</filename> Git repository. | 231 | Git repository inside the local <filename>poky</filename> Git repository. |
232 | <literallayout class='monospaced'> | 232 | <literallayout class='monospaced'> |
@@ -239,15 +239,15 @@ | |||
239 | Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done. | 239 | Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done. |
240 | Resolving deltas: 100% (1689/1689), done. | 240 | Resolving deltas: 100% (1689/1689), done. |
241 | </literallayout></para> | 241 | </literallayout></para> |
242 | <para>The same | 242 | <para>The same |
243 | <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'> | 243 | <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'> |
244 | wiki page</ulink> referenced earlier covers how to | 244 | wiki page</ulink> referenced earlier covers how to |
245 | set up the <filename>meta-intel</filename> Git repository.</para></listitem> | 245 | set up the <filename>meta-intel</filename> Git repository.</para></listitem> |
246 | </itemizedlist></para></listitem> | 246 | </itemizedlist></para></listitem> |
247 | <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing | 247 | <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing |
248 | applications using the Eclipse Integrated Development Environment (IDE), | 248 | applications using the Eclipse Integrated Development Environment (IDE), |
249 | you will need this plug-in. | 249 | you will need this plug-in. |
250 | See the | 250 | See the |
251 | "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>" | 251 | "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>" |
252 | section for more information.</para></listitem> | 252 | section for more information.</para></listitem> |
253 | </itemizedlist> | 253 | </itemizedlist> |
@@ -258,8 +258,8 @@ | |||
258 | <title>Building Images</title> | 258 | <title>Building Images</title> |
259 | 259 | ||
260 | <para> | 260 | <para> |
261 | The build process creates an entire Linux distribution, including the toolchain, from source. | 261 | The build process creates an entire Linux distribution, including the toolchain, from source. |
262 | For more information on this topic, see the | 262 | For more information on this topic, see the |
263 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | 263 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" |
264 | section in the Yocto Project Quick Start. | 264 | section in the Yocto Project Quick Start. |
265 | </para> | 265 | </para> |
@@ -267,27 +267,27 @@ | |||
267 | <para> | 267 | <para> |
268 | The build process is as follows: | 268 | The build process is as follows: |
269 | <orderedlist> | 269 | <orderedlist> |
270 | <listitem><para>Make sure you have set up the Source Directory described in the | 270 | <listitem><para>Make sure you have set up the Source Directory described in the |
271 | previous section.</para></listitem> | 271 | previous section.</para></listitem> |
272 | <listitem><para>Initialize the build environment by sourcing a build environment | 272 | <listitem><para>Initialize the build environment by sourcing a build environment |
273 | script.</para></listitem> | 273 | script.</para></listitem> |
274 | <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file, | 274 | <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file, |
275 | which is found in the | 275 | which is found in the |
276 | <link linkend='build-directory'>Build Directory</link>, | 276 | <link linkend='build-directory'>Build Directory</link>, |
277 | is set up how you want it. | 277 | is set up how you want it. |
278 | This file defines many aspects of the build environment including | 278 | This file defines many aspects of the build environment including |
279 | the target machine architecture through the | 279 | the target machine architecture through the |
280 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable, | 280 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable, |
281 | the development machine's processor use through the | 281 | the development machine's processor use through the |
282 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and | 282 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and |
283 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and | 283 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and |
284 | a centralized tarball download directory through the | 284 | a centralized tarball download directory through the |
285 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem> | 285 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem> |
286 | <listitem><para>Build the image using the <filename>bitbake</filename> command. | 286 | <listitem><para>Build the image using the <filename>bitbake</filename> command. |
287 | If you want information on BitBake, see the user manual inculded in the | 287 | If you want information on BitBake, see the user manual inculded in the |
288 | <filename>bitbake/doc/manual</filename> directory of the | 288 | <filename>bitbake/doc/manual</filename> directory of the |
289 | <link linkend='source-directory'>Source Directory</link>.</para></listitem> | 289 | <link linkend='source-directory'>Source Directory</link>.</para></listitem> |
290 | <listitem><para>Run the image either on the actual hardware or using the QEMU | 290 | <listitem><para>Run the image either on the actual hardware or using the QEMU |
291 | emulator.</para></listitem> | 291 | emulator.</para></listitem> |
292 | </orderedlist> | 292 | </orderedlist> |
293 | </para> | 293 | </para> |
@@ -297,8 +297,8 @@ | |||
297 | <title>Using Pre-Built Binaries and QEMU</title> | 297 | <title>Using Pre-Built Binaries and QEMU</title> |
298 | 298 | ||
299 | <para> | 299 | <para> |
300 | Another option you have to get started is to use pre-built binaries. | 300 | Another option you have to get started is to use pre-built binaries. |
301 | The Yocto Project provides many types of binaries with each release. | 301 | The Yocto Project provides many types of binaries with each release. |
302 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | 302 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" |
303 | chapter in the Yocto Project Reference Manual | 303 | chapter in the Yocto Project Reference Manual |
304 | for descriptions of the types of binaries that ship with a Yocto Project | 304 | for descriptions of the types of binaries that ship with a Yocto Project |
@@ -306,51 +306,51 @@ | |||
306 | </para> | 306 | </para> |
307 | 307 | ||
308 | <para> | 308 | <para> |
309 | Using a pre-built binary is ideal for developing software applications to run on your | 309 | Using a pre-built binary is ideal for developing software applications to run on your |
310 | target hardware. | 310 | target hardware. |
311 | To do this, you need to be able to access the appropriate cross-toolchain tarball for | 311 | To do this, you need to be able to access the appropriate cross-toolchain tarball for |
312 | the architecture on which you are developing. | 312 | the architecture on which you are developing. |
313 | If you are using an SDK type image, the image ships with the complete toolchain native to | 313 | If you are using an SDK type image, the image ships with the complete toolchain native to |
314 | the architecture. | 314 | the architecture. |
315 | If you are not using an SDK type image, you need to separately download and | 315 | If you are not using an SDK type image, you need to separately download and |
316 | install the stand-alone Yocto Project cross-toolchain tarball. | 316 | install the stand-alone Yocto Project cross-toolchain tarball. |
317 | </para> | 317 | </para> |
318 | 318 | ||
319 | <para> | 319 | <para> |
320 | Regardless of the type of image you are using, you need to download the pre-built kernel | 320 | Regardless of the type of image you are using, you need to download the pre-built kernel |
321 | that you will boot in the QEMU emulator and then download and extract the target root | 321 | that you will boot in the QEMU emulator and then download and extract the target root |
322 | filesystem for your target machine’s architecture. | 322 | filesystem for your target machine’s architecture. |
323 | You can get architecture-specific binaries and filesystems from | 323 | You can get architecture-specific binaries and filesystems from |
324 | <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>. | 324 | <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>. |
325 | You can get installation scripts for stand-alone toolchains from | 325 | You can get installation scripts for stand-alone toolchains from |
326 | <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>. | 326 | <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>. |
327 | Once you have all your files, you set up the environment to emulate the hardware | 327 | Once you have all your files, you set up the environment to emulate the hardware |
328 | by sourcing an environment setup script. | 328 | by sourcing an environment setup script. |
329 | Finally, you start the QEMU emulator. | 329 | Finally, you start the QEMU emulator. |
330 | You can find details on all these steps in the | 330 | You can find details on all these steps in the |
331 | "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" | 331 | "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" |
332 | section of the Yocto Project Quick Start. | 332 | section of the Yocto Project Quick Start. |
333 | </para> | 333 | </para> |
334 | 334 | ||
335 | <para> | 335 | <para> |
336 | Using QEMU to emulate your hardware can result in speed issues | 336 | Using QEMU to emulate your hardware can result in speed issues |
337 | depending on the target and host architecture mix. | 337 | depending on the target and host architecture mix. |
338 | For example, using the <filename>qemux86</filename> image in the emulator | 338 | For example, using the <filename>qemux86</filename> image in the emulator |
339 | on an Intel-based 32-bit (x86) host machine is fast because the target and | 339 | on an Intel-based 32-bit (x86) host machine is fast because the target and |
340 | host architectures match. | 340 | host architectures match. |
341 | On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based | 341 | On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based |
342 | host can be slower. | 342 | host can be slower. |
343 | But, you still achieve faithful emulation of ARM-specific issues. | 343 | But, you still achieve faithful emulation of ARM-specific issues. |
344 | </para> | 344 | </para> |
345 | 345 | ||
346 | <para> | 346 | <para> |
347 | To speed things up, the QEMU images support using <filename>distcc</filename> | 347 | To speed things up, the QEMU images support using <filename>distcc</filename> |
348 | to call a cross-compiler outside the emulated system. | 348 | to call a cross-compiler outside the emulated system. |
349 | If you used <filename>runqemu</filename> to start QEMU, and the | 349 | If you used <filename>runqemu</filename> to start QEMU, and the |
350 | <filename>distccd</filename> application is present on the host system, any | 350 | <filename>distccd</filename> application is present on the host system, any |
351 | BitBake cross-compiling toolchain available from the build system is automatically | 351 | BitBake cross-compiling toolchain available from the build system is automatically |
352 | used from within QEMU simply by calling <filename>distcc</filename>. | 352 | used from within QEMU simply by calling <filename>distcc</filename>. |
353 | You can accomplish this by defining the cross-compiler variable | 353 | You can accomplish this by defining the cross-compiler variable |
354 | (e.g. <filename>export CC="distcc"</filename>). | 354 | (e.g. <filename>export CC="distcc"</filename>). |
355 | Alternatively, if you are using a suitable SDK image or the appropriate | 355 | Alternatively, if you are using a suitable SDK image or the appropriate |
356 | stand-alone toolchain is present in <filename>/opt/poky</filename>, | 356 | stand-alone toolchain is present in <filename>/opt/poky</filename>, |
@@ -358,27 +358,27 @@ | |||
358 | </para> | 358 | </para> |
359 | 359 | ||
360 | <note> | 360 | <note> |
361 | Several mechanisms exist that let you connect to the system running on the | 361 | Several mechanisms exist that let you connect to the system running on the |
362 | QEMU emulator: | 362 | QEMU emulator: |
363 | <itemizedlist> | 363 | <itemizedlist> |
364 | <listitem><para>QEMU provides a framebuffer interface that makes standard | 364 | <listitem><para>QEMU provides a framebuffer interface that makes standard |
365 | consoles available.</para></listitem> | 365 | consoles available.</para></listitem> |
366 | <listitem><para>Generally, headless embedded devices have a serial port. | 366 | <listitem><para>Generally, headless embedded devices have a serial port. |
367 | If so, you can configure the operating system of the running image | 367 | If so, you can configure the operating system of the running image |
368 | to use that port to run a console. | 368 | to use that port to run a console. |
369 | The connection uses standard IP networking.</para></listitem> | 369 | The connection uses standard IP networking.</para></listitem> |
370 | <listitem><para>SSH servers exist in some QEMU images. | 370 | <listitem><para>SSH servers exist in some QEMU images. |
371 | The <filename>core-image-sato</filename> QEMU image has a Dropbear secure | 371 | The <filename>core-image-sato</filename> QEMU image has a Dropbear secure |
372 | shell (ssh) server that runs with the root password disabled. | 372 | shell (ssh) server that runs with the root password disabled. |
373 | The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images | 373 | The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images |
374 | have OpenSSH instead of Dropbear. | 374 | have OpenSSH instead of Dropbear. |
375 | Including these SSH servers allow you to use standard <filename>ssh</filename> and | 375 | Including these SSH servers allow you to use standard <filename>ssh</filename> and |
376 | <filename>scp</filename> commands. | 376 | <filename>scp</filename> commands. |
377 | The <filename>core-image-minimal</filename> QEMU image, however, contains no ssh | 377 | The <filename>core-image-minimal</filename> QEMU image, however, contains no ssh |
378 | server.</para></listitem> | 378 | server.</para></listitem> |
379 | <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session | 379 | <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session |
380 | using a local copy of the root filesystem on the host. | 380 | using a local copy of the root filesystem on the host. |
381 | In order to make this connection, you must extract a root filesystem tarball by using the | 381 | In order to make this connection, you must extract a root filesystem tarball by using the |
382 | <filename>runqemu-extract-sdk</filename> command. | 382 | <filename>runqemu-extract-sdk</filename> command. |
383 | After running the command, you must then point the <filename>runqemu</filename> | 383 | After running the command, you must then point the <filename>runqemu</filename> |
384 | script to the extracted directory instead of a root filesystem image file.</para></listitem> | 384 | script to the extracted directory instead of a root filesystem image file.</para></listitem> |
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml index 19503a928f..5eea2e22aa 100644 --- a/documentation/dev-manual/dev-manual.xml +++ b/documentation/dev-manual/dev-manual.xml | |||
@@ -2,7 +2,7 @@ | |||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | 4 | ||
5 | <book id='dev-manual' lang='en' | 5 | <book id='dev-manual' lang='en' |
6 | xmlns:xi="http://www.w3.org/2003/XInclude" | 6 | xmlns:xi="http://www.w3.org/2003/XInclude" |
7 | xmlns="http://docbook.org/ns/docbook" | 7 | xmlns="http://docbook.org/ns/docbook" |
8 | > | 8 | > |
@@ -10,13 +10,13 @@ | |||
10 | 10 | ||
11 | <mediaobject> | 11 | <mediaobject> |
12 | <imageobject> | 12 | <imageobject> |
13 | <imagedata fileref='figures/dev-title.png' | 13 | <imagedata fileref='figures/dev-title.png' |
14 | format='SVG' | 14 | format='SVG' |
15 | align='left' scalefit='1' width='100%'/> | 15 | align='left' scalefit='1' width='100%'/> |
16 | </imageobject> | 16 | </imageobject> |
17 | </mediaobject> | 17 | </mediaobject> |
18 | 18 | ||
19 | <title></title> | 19 | <title></title> |
20 | 20 | ||
21 | <authorgroup> | 21 | <authorgroup> |
22 | <author> | 22 | <author> |
@@ -58,9 +58,9 @@ | |||
58 | 58 | ||
59 | <legalnotice> | 59 | <legalnotice> |
60 | <para> | 60 | <para> |
61 | Permission is granted to copy, distribute and/or modify this document under | 61 | Permission is granted to copy, distribute and/or modify this document under |
62 | the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/"> | 62 | the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/"> |
63 | Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by | 63 | Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by |
64 | Creative Commons. | 64 | Creative Commons. |
65 | </para> | 65 | </para> |
66 | 66 | ||
@@ -86,6 +86,6 @@ | |||
86 | <xi:include href="dev-manual-common-tasks.xml"/> | 86 | <xi:include href="dev-manual-common-tasks.xml"/> |
87 | 87 | ||
88 | </book> | 88 | </book> |
89 | <!-- | 89 | <!-- |
90 | vim: expandtab tw=80 ts=4 | 90 | vim: expandtab tw=80 ts=4 |
91 | --> | 91 | --> |