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