summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-appendix-customizing.xml
blob: 78ead9c02229450fafdafc12f2ae189cfe18be0a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<appendix id='sdk-appendix-customizing'>

<title>Customizing the Extensible SDK</title>

<para>
    This appendix presents customizations you can apply to the extensible SDK.
</para>

<section id='sdk-configuring-the-extensible-sdk'>
    <title>Configuring the Extensible SDK</title>

    <para>
        The extensible SDK primarily consists of a pre-configured copy of
        the OpenEmbedded build system from which it was produced.
        Thus, the SDK's configuration is derived using that build system and
        the filters shown in the following list.
        When these filters are present, the OpenEmbedded build system applies
        them against <filename>local.conf</filename> and
        <filename>auto.conf</filename>:
        <itemizedlist>
            <listitem><para>
                Variables whose values start with "/" are excluded since the
                assumption is that those values are paths that are likely to
                be specific to the
                <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
                </para></listitem>
            <listitem><para>
                Variables listed in
                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>
                are excluded.
                These variables are not allowed through from the OpenEmbedded
                build system configuration into the extensible SDK
                configuration.
                Typically, these variables are specific to the machine on
                which the build system is running and could be problematic
                as part of the extensible SDK configuration.</para>

                <para>For a list of the variables excluded by default, see the
                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>
                in the glossary of the Yocto Project Reference Manual.
                </para></listitem>
            <listitem><para>
                Variables listed in
                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>
                are included.
                Including a variable in the value of
                <filename>SDK_LOCAL_CONF_WHITELIST</filename> overrides either
                of the previous two filters.
                The default value is blank.
                </para></listitem>
            <listitem><para>
                Classes inherited globally with
                <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
                that are listed in
                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>
                are disabled.
                Using <filename>SDK_INHERIT_BLACKLIST</filename> to disable
                these classes is the typical method to disable classes that
                are problematic or unnecessary in the SDK context.
                The default value blacklists the
                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink>
                and
                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-icecc'><filename>icecc</filename></ulink>
                classes.
                </para></listitem>
        </itemizedlist>
        Additionally, the contents of <filename>conf/sdk-extra.conf</filename>,
        when present, are appended to the end of
        <filename>conf/local.conf</filename> within the produced SDK, without
        any filtering.
        The <filename>sdk-extra.conf</filename> file is particularly useful
        if you want to set a variable value just for the SDK and not the
        OpenEmbedded build system used to create the SDK.
    </para>
</section>

<section id='adjusting-the-extensible-sdk-to-suit-your-build-hosts-setup'>
    <title>Adjusting the Extensible SDK to Suit Your Build Host's Setup</title>

    <para>
        In most cases, the extensible SDK defaults should work with your
        <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host's</ulink>
        setup.
        However, some cases exist for which you might consider making
        adjustments:
        <itemizedlist>
            <listitem><para>
                If your SDK configuration inherits additional classes
                using the
                <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
                variable and you do not need or want those classes enabled in
                the SDK, you can blacklist them by adding them to the
                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>
                variable as described in the fourth bullet of the previous
                section.
                <note>
                    The default value of
                    <filename>SDK_INHERIT_BLACKLIST</filename> is set using
                    the "?=" operator.
                    Consequently, you will need to either define the entire
                    list by using the "=" operator, or you will need to append
                    a value using either "_append" or the "+=" operator.
                    You can learn more about these operators in the
                    "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
                    section of the BitBake User Manual.
                </note>.
                </para></listitem>
            <listitem><para>
                If you have classes or recipes that add additional tasks to
                the standard build flow (i.e. the tasks execute as the recipe
                builds as opposed to being called explicitly), then you need
                to do one of the following:
                <itemizedlist>
                    <listitem><para>
                        After ensuring the tasks are
                        <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
                        tasks (i.e. the output of the task is saved to and
                        can be restored from the shared state cache) or
                        ensuring the tasks are able to be produced quickly from
                        a task that is a shared state task, add the task name
                        to the value of
                        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS'><filename>SDK_RECRDEP_TASKS</filename></ulink>.
                        </para></listitem>
                    <listitem><para>
                        Disable the tasks if they are added by a class and
                        you do not need the functionality the class provides
                        in the extensible SDK.
                        To disable the tasks, add the class to the
                        <filename>SDK_INHERIT_BLACKLIST</filename> variable
                        as described in the previous section.
                        </para></listitem>
                </itemizedlist>
                </para></listitem>
            <listitem><para>
                Generally, you want to have a shared state mirror set up so
                users of the SDK can add additional items to the SDK after
                installation without needing to build the items from source.
                See the
                "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>"
                section for information.
                </para></listitem>
            <listitem><para>
                If you want users of the SDK to be able to easily update the
                SDK, you need to set the
                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
                variable.
                For more information, see the
                "<link linkend='sdk-providing-updates-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</link>"
                section.
                </para></listitem>
            <listitem><para>
                If you have adjusted the list of files and directories that
                appear in
                <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE'><filename>COREBASE</filename></ulink>
                (other than layers that are enabled through
                <filename>bblayers.conf</filename>), then you must list these
                files in
                <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES'><filename>COREBASE_FILES</filename></ulink>
                so that the files are copied into the SDK.
                </para></listitem>
            <listitem><para>
                If your OpenEmbedded build system setup uses a different
                environment setup script other than
                <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>,
                then you must set
                <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT'><filename>OE_INIT_ENV_SCRIPT</filename></ulink>
                to point to the environment setup script you use.
                <note>
                    You must also reflect this change in the value used for the
                    <filename>COREBASE_FILES</filename> variable as previously
                    described.
                </note>
                </para></listitem>
        </itemizedlist>
    </para>
</section>

<section id='sdk-changing-the-sdk-installer-title'>
    <title>Changing the Extensible SDK Installer Title</title>

    <para>
        You can change the displayed title for the SDK installer by setting
        the
        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink>
        variable and then rebuilding the the SDK installer.
        For information on how to build an SDK installer, see the
        "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
        section.
    </para>

    <para>
        By default, this title is derived from
        <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
        when it is set.
        If the <filename>DISTRO_NAME</filename> variable is not set, the title
        is derived from the
        <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
        variable.
    </para>

    <para>
        The
        <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink>
        class defines the default value of the <filename>SDK_TITLE</filename>
        variable as follows:
        <literallayout class='monospaced'>
     SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
        </literallayout>
    </para>

    <para>
        While several ways exist to change this variable, an efficient method
        is to set the variable in your distribution's configuration file.
        Doing so creates an SDK installer title that applies across your
        distribution.
        As an example, assume you have your own layer for your distribution
        named "meta-mydistro" and you are using the same type of file
        hierarchy as does the default "poky" distribution.
        If so, you could update the <filename>SDK_TITLE</filename> variable
        in the
        <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file
        using the following form:
        <literallayout class='monospaced'>
     SDK_TITLE = "<replaceable>your_title</replaceable>"
        </literallayout>
    </para>
</section>

<section id='sdk-providing-updates-to-the-extensible-sdk-after-installation'>
    <title>Providing Updates to the Extensible SDK After Installation</title>

    <para>
        When you make changes to your configuration or to the metadata and
        if you want those changes to be reflected in installed SDKs, you need
        to perform additional steps.
        These steps make it possible for anyone using the installed SDKs to
        update the installed SDKs by using the
        <filename>devtool sdk-update</filename> command:
        <orderedlist>
            <listitem><para>
                Create a directory that can be shared over HTTP or HTTPS.
                You can do this by setting up a web server such as an
                <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink>
                or
                <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink>
                server in the cloud to host the directory.
                This directory must contain the published SDK.
                </para></listitem>
            <listitem><para>
                Set the
                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
                variable to point to the corresponding HTTP or HTTPS URL.
                Setting this variable causes any SDK built to default to that
                URL and thus, the user does not have to pass the URL to the
                <filename>devtool sdk-update</filename> command as described
                in the
                "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>"
                section.
                </para></listitem>
            <listitem><para>
                Build the extensible SDK normally (i.e., use the
                <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>
                command).
                </para></listitem>
            <listitem><para>
                Publish the SDK using the following command:
                <literallayout class='monospaced'>
     $ oe-publish-sdk <replaceable>some_path</replaceable>/sdk-installer.sh <replaceable>path_to_shared_http_directory</replaceable>
                </literallayout>
                You must repeat this step each time you rebuild the SDK
                with changes that you want to make available through the
                update mechanism.
                </para></listitem>
        </orderedlist>
    </para>

    <para>
        Completing the above steps allows users of the existing installed
        SDKs to simply run <filename>devtool sdk-update</filename> to
        retrieve and apply the latest updates.
        See the
        "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>"
        section for further information.
    </para>
</section>

<section id='sdk-changing-the-default-sdk-installation-directory'>
    <title>Changing the Default SDK Installation Directory</title>

    <para>
        When you build the installer for the Extensible SDK, the default
        installation directory for the SDK is based on the
        <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
        and
        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH'><filename>SDKEXTPATH</filename></ulink>
        variables from within the
        <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink>
        class as follows:
        <literallayout class='monospaced'>
     SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
        </literallayout>
        You can change this default installation directory by specifically
        setting the <filename>SDKEXTPATH</filename> variable.
    </para>

    <para>
        While a number of ways exist through which you can set this variable,
        the method that makes the most sense is to set the variable in your
        distribution's configuration file.
        Doing so creates an SDK installer default directory that applies
        across your distribution.
        As an example, assume you have your own layer for your distribution
        named "meta-mydistro" and you are using the same type of file
        hierarchy as does the default "poky" distribution.
        If so, you could update the <filename>SDKEXTPATH</filename> variable
        in the
        <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file
        using the following form:
        <literallayout class='monospaced'>
     SDKEXTPATH = "<replaceable>some_path_for_your_installed_sdk</replaceable>"
        </literallayout>
    </para>

    <para>
        After building your installer, running it prompts the user for
        acceptance of the
        <replaceable>some_path_for_your_installed_sdk</replaceable> directory
        as the default location to install the Extensible SDK.
    </para>
</section>

<section id='sdk-providing-additional-installable-extensible-sdk-content'>
    <title>Providing Additional Installable Extensible SDK Content</title>

    <para>
        If you want the users of an extensible SDK you build to be
        able to add items to the SDK without requiring the users to build
        the items from source, you need to do a number of things:
        <itemizedlist>
            <listitem><para>
                Ensure the additional items you want the user to be able to
                install are already built:
                <itemizedlist>
                    <listitem><para>
                        Build the items explicitly.
                        You could use one or more "meta" recipes that depend
                        on lists of other recipes.
                        </para></listitem>
                    <listitem><para>
                        Build the "world" target and set
                        <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable>
                        for the recipes you do not want built.
                        See the
                        <ulink url='&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD'><filename>EXCLUDE_FROM_WORLD</filename></ulink>
                        variable for additional information.
                        </para></listitem>
                </itemizedlist>
                </para></listitem>
            <listitem><para>
                Expose the <filename>sstate-cache</filename> directory
                produced by the build.
                Typically, you expose this directory by making it available
                through an
                <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink>
                or
                <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink>
                server.
                </para></listitem>
            <listitem><para>
                Set the appropriate configuration so that the produced SDK
                knows how to find the configuration.
                The variable you need to set is
                <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>:
                <literallayout class='monospaced'>
     SSTATE_MIRRORS = "file://.*  http://<replaceable>example</replaceable>.com/<replaceable>some_path</replaceable>/sstate-cache/PATH"
                </literallayout>
                You can set the <filename>SSTATE_MIRRORS</filename> variable
                in two different places:
                <itemizedlist>
                    <listitem><para>
                        If the mirror value you are setting is appropriate to
                        be set for both the OpenEmbedded build system that is
                        actually building the SDK and the SDK itself (i.e. the
                        mirror is accessible in both places or it will fail
                        quickly on the OpenEmbedded build system side, and its
                        contents will not interfere with the build), then you
                        can set the variable in your
                        <filename>local.conf</filename> or custom distro
                        configuration file.
                        You can then "whitelist" the variable through
                        to the SDK by adding the following:
                        <literallayout class='monospaced'>
     SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
                        </literallayout>
                        </para></listitem>
                    <listitem><para>
                        Alternatively, if you just want to set the
                        <filename>SSTATE_MIRRORS</filename> variable's value
                        for the SDK alone, create a
                        <filename>conf/sdk-extra.conf</filename> file either in
                        your
                        <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
                        or within any layer and put your
                        <filename>SSTATE_MIRRORS</filename> setting within
                        that file.
                        <note>
                            This second option is the safest option should
                            you have any doubts as to which method to use when
                            setting <filename>SSTATE_MIRRORS</filename>.
                        </note>
                        </para></listitem>
                </itemizedlist>
                </para></listitem>
        </itemizedlist>
    </para>
</section>

<section id='sdk-minimizing-the-size-of-the-extensible-sdk-installer-download'>
    <title>Minimizing the Size of the Extensible SDK Installer Download</title>

    <para>
        By default, the extensible SDK bundles the shared state artifacts for
        everything needed to reconstruct the image for which the SDK was built.
        This bundling can lead to an SDK installer file that is a Gigabyte or
        more in size.
        If the size of this file causes a problem, you can build an SDK that
        has just enough in it to install and provide access to the
        <filename>devtool command</filename> by setting the following in your
        configuration:
        <literallayout class='monospaced'>
     SDK_EXT_TYPE = "minimal"
        </literallayout>
        Setting
        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>
        to "minimal" produces an SDK installer that is around 35 Mbytes in
        size, which downloads and installs quickly.
        You need to realize, though, that the minimal installer does not
        install any libraries or tools out of the box.
        These must be installed either "on the fly" or through actions you
        perform using <filename>devtool</filename> or explicitly with the
        <filename>devtool sdk-install</filename> command.
    </para>

    <para>
        In most cases, when building a minimal SDK you will need to also enable
        bringing in the information on a wider range of packages produced by
        the system.
        This is particularly true so that <filename>devtool add</filename>
        is able to effectively map dependencies it discovers in a source tree
        to the appropriate recipes.
        Also so that the <filename>devtool search</filename> command
        is able to return useful results.
    </para>

    <para>
        To facilitate this wider range of information, you would additionally
        set the following:
        <literallayout class='monospaced'>
     SDK_INCLUDE_PKGDATA = "1"
        </literallayout>
        See the
        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>
        variable for additional information.
    </para>

    <para>
        Setting the <filename>SDK_INCLUDE_PKGDATA</filename> variable as
        shown causes the "world" target to be built so that information
        for all of the recipes included within it are available.
        Having these recipes available increases build time significantly and
        increases the size of the SDK installer by 30-80 Mbytes depending on
        how many recipes are included in your configuration.
    </para>

    <para>
        You can use
        <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable>
        for recipes you want to exclude.
        However, it is assumed that you would need to be building the "world"
        target if you want to provide additional items to the SDK.
        Consequently, building for "world" should not represent undue
        overhead in most cases.
        <note>
            If you set <filename>SDK_EXT_TYPE</filename> to "minimal",
            then providing a shared state mirror is mandatory so that items
            can be installed as needed.
            See the
            "<link linkend='sdk-providing-additional-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>"
            section for more information.
        </note>
    </para>

    <para>
        You can explicitly control whether or not to include the toolchain
        when you build an SDK by setting the
        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>
        variable to "1".
        In particular, it is useful to include the toolchain when you
        have set <filename>SDK_EXT_TYPE</filename> to
        "minimal", which by default, excludes the toolchain.
        Also, it is helpful if you are building a small SDK for use with
        an IDE, such as <trademark class='trade'>Eclipse</trademark>, or some
        other tool where you do not want to take extra steps to install a
        toolchain.
    </para>
</section>
</appendix>
<!--
vim: expandtab tw=80 ts=4
-->