diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 1582 |
1 files changed, 791 insertions, 791 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 | --> |