diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-appendix-customizing.rst')
-rw-r--r-- | documentation/sdk-manual/sdk-appendix-customizing.rst | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-customizing.rst b/documentation/sdk-manual/sdk-appendix-customizing.rst new file mode 100644 index 0000000000..b613a12f23 --- /dev/null +++ b/documentation/sdk-manual/sdk-appendix-customizing.rst | |||
@@ -0,0 +1,347 @@ | |||
1 | ****************************** | ||
2 | Customizing the Extensible SDK | ||
3 | ****************************** | ||
4 | |||
5 | This appendix describes customizations you can apply to the extensible | ||
6 | SDK. | ||
7 | |||
8 | Configuring the Extensible SDK | ||
9 | ============================== | ||
10 | |||
11 | The extensible SDK primarily consists of a pre-configured copy of the | ||
12 | OpenEmbedded build system from which it was produced. Thus, the SDK's | ||
13 | configuration is derived using that build system and the filters shown | ||
14 | in the following list. When these filters are present, the OpenEmbedded | ||
15 | build system applies them against ``local.conf`` and ``auto.conf``: | ||
16 | |||
17 | - Variables whose values start with "/" are excluded since the | ||
18 | assumption is that those values are paths that are likely to be | ||
19 | specific to the `build | ||
20 | host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__. | ||
21 | |||
22 | - Variables listed in | ||
23 | ```SDK_LOCAL_CONF_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST>`__ | ||
24 | are excluded. These variables are not allowed through from the | ||
25 | OpenEmbedded build system configuration into the extensible SDK | ||
26 | configuration. Typically, these variables are specific to the machine | ||
27 | on which the build system is running and could be problematic as part | ||
28 | of the extensible SDK configuration. | ||
29 | |||
30 | For a list of the variables excluded by default, see the | ||
31 | ```SDK_LOCAL_CONF_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST>`__ | ||
32 | in the glossary of the Yocto Project Reference Manual. | ||
33 | |||
34 | - Variables listed in | ||
35 | ```SDK_LOCAL_CONF_WHITELIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST>`__ | ||
36 | are included. Including a variable in the value of | ||
37 | ``SDK_LOCAL_CONF_WHITELIST`` overrides either of the previous two | ||
38 | filters. The default value is blank. | ||
39 | |||
40 | - Classes inherited globally with | ||
41 | ```INHERIT`` <&YOCTO_DOCS_REF_URL;#var-INHERIT>`__ that are listed in | ||
42 | ```SDK_INHERIT_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST>`__ | ||
43 | are disabled. Using ``SDK_INHERIT_BLACKLIST`` to disable these | ||
44 | classes is the typical method to disable classes that are problematic | ||
45 | or unnecessary in the SDK context. The default value blacklists the | ||
46 | ```buildhistory`` <&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory>`__ | ||
47 | and ```icecc`` <&YOCTO_DOCS_REF_URL;#ref-classes-icecc>`__ classes. | ||
48 | |||
49 | Additionally, the contents of ``conf/sdk-extra.conf``, when present, are | ||
50 | appended to the end of ``conf/local.conf`` within the produced SDK, | ||
51 | without any filtering. The ``sdk-extra.conf`` file is particularly | ||
52 | useful if you want to set a variable value just for the SDK and not the | ||
53 | OpenEmbedded build system used to create the SDK. | ||
54 | |||
55 | Adjusting the Extensible SDK to Suit Your Build Host's Setup | ||
56 | ============================================================ | ||
57 | |||
58 | In most cases, the extensible SDK defaults should work with your `build | ||
59 | host's <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ setup. | ||
60 | However, some cases exist for which you might consider making | ||
61 | adjustments: | ||
62 | |||
63 | - If your SDK configuration inherits additional classes using the | ||
64 | ```INHERIT`` <&YOCTO_DOCS_REF_URL;#var-INHERIT>`__ variable and you | ||
65 | do not need or want those classes enabled in the SDK, you can | ||
66 | blacklist them by adding them to the | ||
67 | ```SDK_INHERIT_BLACKLIST`` <&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST>`__ | ||
68 | variable as described in the fourth bullet of the previous section. | ||
69 | |||
70 | .. note:: | ||
71 | |||
72 | The default value of | ||
73 | SDK_INHERIT_BLACKLIST | ||
74 | is set using the "?=" operator. Consequently, you will need to | ||
75 | either define the entire list by using the "=" operator, or you | ||
76 | will need to append a value using either "_append" or the "+=" | ||
77 | operator. You can learn more about these operators in the " | ||
78 | Basic Syntax | ||
79 | " section of the BitBake User Manual. | ||
80 | |||
81 | . | ||
82 | |||
83 | - If you have classes or recipes that add additional tasks to the | ||
84 | standard build flow (i.e. the tasks execute as the recipe builds as | ||
85 | opposed to being called explicitly), then you need to do one of the | ||
86 | following: | ||
87 | |||
88 | - After ensuring the tasks are `shared | ||
89 | state <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ tasks (i.e. the | ||
90 | output of the task is saved to and can be restored from the shared | ||
91 | state cache) or ensuring the tasks are able to be produced quickly | ||
92 | from a task that is a shared state task, add the task name to the | ||
93 | value of | ||
94 | ```SDK_RECRDEP_TASKS`` <&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS>`__. | ||
95 | |||
96 | - Disable the tasks if they are added by a class and you do not need | ||
97 | the functionality the class provides in the extensible SDK. To | ||
98 | disable the tasks, add the class to the ``SDK_INHERIT_BLACKLIST`` | ||
99 | variable as described in the previous section. | ||
100 | |||
101 | - Generally, you want to have a shared state mirror set up so users of | ||
102 | the SDK can add additional items to the SDK after installation | ||
103 | without needing to build the items from source. See the "`Providing | ||
104 | Additional Installable Extensible SDK | ||
105 | Content <#sdk-providing-additional-installable-extensible-sdk-content>`__" | ||
106 | section for information. | ||
107 | |||
108 | - If you want users of the SDK to be able to easily update the SDK, you | ||
109 | need to set the | ||
110 | ```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__ | ||
111 | variable. For more information, see the "`Providing Updates to the | ||
112 | Extensible SDK After | ||
113 | Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__" | ||
114 | section. | ||
115 | |||
116 | - If you have adjusted the list of files and directories that appear in | ||
117 | ```COREBASE`` <&YOCTO_DOCS_REF_URL;#var-COREBASE>`__ (other than | ||
118 | layers that are enabled through ``bblayers.conf``), then you must | ||
119 | list these files in | ||
120 | ```COREBASE_FILES`` <&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES>`__ so | ||
121 | that the files are copied into the SDK. | ||
122 | |||
123 | - If your OpenEmbedded build system setup uses a different environment | ||
124 | setup script other than | ||
125 | ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, then you must | ||
126 | set | ||
127 | ```OE_INIT_ENV_SCRIPT`` <&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT>`__ | ||
128 | to point to the environment setup script you use. | ||
129 | |||
130 | .. note:: | ||
131 | |||
132 | You must also reflect this change in the value used for the | ||
133 | COREBASE_FILES | ||
134 | variable as previously described. | ||
135 | |||
136 | Changing the Extensible SDK Installer Title | ||
137 | =========================================== | ||
138 | |||
139 | You can change the displayed title for the SDK installer by setting the | ||
140 | ```SDK_TITLE`` <&YOCTO_DOCS_REF_URL;#var-SDK_TITLE>`__ variable and then | ||
141 | rebuilding the the SDK installer. For information on how to build an SDK | ||
142 | installer, see the "`Building an SDK | ||
143 | Installer <#sdk-building-an-sdk-installer>`__" section. | ||
144 | |||
145 | By default, this title is derived from | ||
146 | ```DISTRO_NAME`` <&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME>`__ when it is | ||
147 | set. If the ``DISTRO_NAME`` variable is not set, the title is derived | ||
148 | from the ```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__ variable. | ||
149 | |||
150 | The | ||
151 | ```populate_sdk_base`` <&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*>`__ | ||
152 | class defines the default value of the ``SDK_TITLE`` variable as | ||
153 | follows: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or | ||
154 | d.getVar('DISTRO')} SDK" | ||
155 | |||
156 | While several ways exist to change this variable, an efficient method is | ||
157 | to set the variable in your distribution's configuration file. Doing so | ||
158 | creates an SDK installer title that applies across your distribution. As | ||
159 | an example, assume you have your own layer for your distribution named | ||
160 | "meta-mydistro" and you are using the same type of file hierarchy as | ||
161 | does the default "poky" distribution. If so, you could update the | ||
162 | ``SDK_TITLE`` variable in the | ||
163 | ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following | ||
164 | form: SDK_TITLE = "your_title" | ||
165 | |||
166 | Providing Updates to the Extensible SDK After Installation | ||
167 | ========================================================== | ||
168 | |||
169 | When you make changes to your configuration or to the metadata and if | ||
170 | you want those changes to be reflected in installed SDKs, you need to | ||
171 | perform additional steps. These steps make it possible for anyone using | ||
172 | the installed SDKs to update the installed SDKs by using the | ||
173 | ``devtool sdk-update`` command: | ||
174 | |||
175 | 1. Create a directory that can be shared over HTTP or HTTPS. You can do | ||
176 | this by setting up a web server such as an `Apache HTTP | ||
177 | Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or | ||
178 | `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server in the cloud | ||
179 | to host the directory. This directory must contain the published SDK. | ||
180 | |||
181 | 2. Set the | ||
182 | ```SDK_UPDATE_URL`` <&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL>`__ | ||
183 | variable to point to the corresponding HTTP or HTTPS URL. Setting | ||
184 | this variable causes any SDK built to default to that URL and thus, | ||
185 | the user does not have to pass the URL to the ``devtool sdk-update`` | ||
186 | command as described in the "`Applying Updates to an Installed | ||
187 | Extensible | ||
188 | SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" | ||
189 | section. | ||
190 | |||
191 | 3. Build the extensible SDK normally (i.e., use the | ||
192 | ``bitbake -c populate_sdk_ext`` imagename command). | ||
193 | |||
194 | 4. Publish the SDK using the following command: $ oe-publish-sdk | ||
195 | some_path/sdk-installer.sh path_to_shared_http_directory You must | ||
196 | repeat this step each time you rebuild the SDK with changes that you | ||
197 | want to make available through the update mechanism. | ||
198 | |||
199 | Completing the above steps allows users of the existing installed SDKs | ||
200 | to simply run ``devtool sdk-update`` to retrieve and apply the latest | ||
201 | updates. See the "`Applying Updates to an Installed Extensible | ||
202 | SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" section | ||
203 | for further information. | ||
204 | |||
205 | Changing the Default SDK Installation Directory | ||
206 | =============================================== | ||
207 | |||
208 | When you build the installer for the Extensible SDK, the default | ||
209 | installation directory for the SDK is based on the | ||
210 | ```DISTRO`` <&YOCTO_DOCS_REF_URL;#var-DISTRO>`__ and | ||
211 | ```SDKEXTPATH`` <&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH>`__ variables from | ||
212 | within the | ||
213 | ```populate_sdk_base`` <&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*>`__ | ||
214 | class as follows: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" You can | ||
215 | change this default installation directory by specifically setting the | ||
216 | ``SDKEXTPATH`` variable. | ||
217 | |||
218 | While a number of ways exist through which you can set this variable, | ||
219 | the method that makes the most sense is to set the variable in your | ||
220 | distribution's configuration file. Doing so creates an SDK installer | ||
221 | default directory that applies across your distribution. As an example, | ||
222 | assume you have your own layer for your distribution named | ||
223 | "meta-mydistro" and you are using the same type of file hierarchy as | ||
224 | does the default "poky" distribution. If so, you could update the | ||
225 | ``SDKEXTPATH`` variable in the | ||
226 | ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following | ||
227 | form: SDKEXTPATH = "some_path_for_your_installed_sdk" | ||
228 | |||
229 | After building your installer, running it prompts the user for | ||
230 | acceptance of the some_path_for_your_installed_sdk directory as the | ||
231 | default location to install the Extensible SDK. | ||
232 | |||
233 | Providing Additional Installable Extensible SDK Content | ||
234 | ======================================================= | ||
235 | |||
236 | If you want the users of an extensible SDK you build to be able to add | ||
237 | items to the SDK without requiring the users to build the items from | ||
238 | source, you need to do a number of things: | ||
239 | |||
240 | 1. Ensure the additional items you want the user to be able to install | ||
241 | are already built: | ||
242 | |||
243 | - Build the items explicitly. You could use one or more "meta" | ||
244 | recipes that depend on lists of other recipes. | ||
245 | |||
246 | - Build the "world" target and set | ||
247 | ``EXCLUDE_FROM_WORLD_pn-``\ recipename for the recipes you do not | ||
248 | want built. See the | ||
249 | ```EXCLUDE_FROM_WORLD`` <&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD>`__ | ||
250 | variable for additional information. | ||
251 | |||
252 | 2. Expose the ``sstate-cache`` directory produced by the build. | ||
253 | Typically, you expose this directory by making it available through | ||
254 | an `Apache HTTP | ||
255 | Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or | ||
256 | `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server. | ||
257 | |||
258 | 3. Set the appropriate configuration so that the produced SDK knows how | ||
259 | to find the configuration. The variable you need to set is | ||
260 | ```SSTATE_MIRRORS`` <&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS>`__: | ||
261 | SSTATE_MIRRORS = "file://.\* | ||
262 | http://example.com/some_path/sstate-cache/PATH" You can set the | ||
263 | ``SSTATE_MIRRORS`` variable in two different places: | ||
264 | |||
265 | - If the mirror value you are setting is appropriate to be set for | ||
266 | both the OpenEmbedded build system that is actually building the | ||
267 | SDK and the SDK itself (i.e. the mirror is accessible in both | ||
268 | places or it will fail quickly on the OpenEmbedded build system | ||
269 | side, and its contents will not interfere with the build), then | ||
270 | you can set the variable in your ``local.conf`` or custom distro | ||
271 | configuration file. You can then "whitelist" the variable through | ||
272 | to the SDK by adding the following: SDK_LOCAL_CONF_WHITELIST = | ||
273 | "SSTATE_MIRRORS" | ||
274 | |||
275 | - Alternatively, if you just want to set the ``SSTATE_MIRRORS`` | ||
276 | variable's value for the SDK alone, create a | ||
277 | ``conf/sdk-extra.conf`` file either in your `Build | ||
278 | Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ or within any | ||
279 | layer and put your ``SSTATE_MIRRORS`` setting within that file. | ||
280 | |||
281 | .. note:: | ||
282 | |||
283 | This second option is the safest option should you have any | ||
284 | doubts as to which method to use when setting | ||
285 | SSTATE_MIRRORS | ||
286 | . | ||
287 | |||
288 | Minimizing the Size of the Extensible SDK Installer Download | ||
289 | ============================================================ | ||
290 | |||
291 | By default, the extensible SDK bundles the shared state artifacts for | ||
292 | everything needed to reconstruct the image for which the SDK was built. | ||
293 | This bundling can lead to an SDK installer file that is a Gigabyte or | ||
294 | more in size. If the size of this file causes a problem, you can build | ||
295 | an SDK that has just enough in it to install and provide access to the | ||
296 | ``devtool command`` by setting the following in your configuration: | ||
297 | SDK_EXT_TYPE = "minimal" Setting | ||
298 | ```SDK_EXT_TYPE`` <&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE>`__ to | ||
299 | "minimal" produces an SDK installer that is around 35 Mbytes in size, | ||
300 | which downloads and installs quickly. You need to realize, though, that | ||
301 | the minimal installer does not install any libraries or tools out of the | ||
302 | box. These libraries and tools must be installed either "on the fly" or | ||
303 | through actions you perform using ``devtool`` or explicitly with the | ||
304 | ``devtool sdk-install`` command. | ||
305 | |||
306 | In most cases, when building a minimal SDK you need to also enable | ||
307 | bringing in the information on a wider range of packages produced by the | ||
308 | system. Requiring this wider range of information is particularly true | ||
309 | so that ``devtool add`` is able to effectively map dependencies it | ||
310 | discovers in a source tree to the appropriate recipes. Additionally, the | ||
311 | information enables the ``devtool search`` command to return useful | ||
312 | results. | ||
313 | |||
314 | To facilitate this wider range of information, you would need to set the | ||
315 | following: SDK_INCLUDE_PKGDATA = "1" See the | ||
316 | ```SDK_INCLUDE_PKGDATA`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA>`__ | ||
317 | variable for additional information. | ||
318 | |||
319 | Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world" | ||
320 | target to be built so that information for all of the recipes included | ||
321 | within it are available. Having these recipes available increases build | ||
322 | time significantly and increases the size of the SDK installer by 30-80 | ||
323 | Mbytes depending on how many recipes are included in your configuration. | ||
324 | |||
325 | You can use ``EXCLUDE_FROM_WORLD_pn-``\ recipename for recipes you want | ||
326 | to exclude. However, it is assumed that you would need to be building | ||
327 | the "world" target if you want to provide additional items to the SDK. | ||
328 | Consequently, building for "world" should not represent undue overhead | ||
329 | in most cases. | ||
330 | |||
331 | .. note:: | ||
332 | |||
333 | If you set | ||
334 | SDK_EXT_TYPE | ||
335 | to "minimal", then providing a shared state mirror is mandatory so | ||
336 | that items can be installed as needed. See the " | ||
337 | Providing Additional Installable Extensible SDK Content | ||
338 | " section for more information. | ||
339 | |||
340 | You can explicitly control whether or not to include the toolchain when | ||
341 | you build an SDK by setting the | ||
342 | ```SDK_INCLUDE_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN>`__ | ||
343 | variable to "1". In particular, it is useful to include the toolchain | ||
344 | when you have set ``SDK_EXT_TYPE`` to "minimal", which by default, | ||
345 | excludes the toolchain. Also, it is helpful if you are building a small | ||
346 | SDK for use with an IDE or some other tool where you do not want to take | ||
347 | extra steps to install a toolchain. | ||