aboutsummaryrefslogtreecommitdiffstats
path: root/meta/recipes-devtools/postinst-intercept
AgeCommit message (Expand)Author
2014-11-20postinst-intercept: rename recipe for nativesdk onlyHongxu Jia
2014-02-02postinst-intercept: New recipe to include postinstall intercepts in nativesdkDavid Nyström
generated by cgit 1.2.3-korg (git 2.39.0) at 2024-05-06 21:34:32 +0000
36' href='#n36'>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 
<!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 SDK</title>

<para>
    This appendix presents customizations you can apply to both the standard
    and extensible SDK.
    Each subsection identifies the type of SDK to which the section applies.
</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 following filters, which the OpenEmbedded build system applies
        against <filename>local.conf</filename> and
        <filename>auto.conf</filename> if they are present:
        <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 build host.
                </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.
                The default value blacklists
                <ulink url='&YOCTO_DOCS_REF_URL;#var-CONF_VERSION'><filename>CONF_VERSION</filename></ulink>,
                <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>,
                <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>,
                <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>,
                and
                <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>.
                </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 above two conditions.
                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 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-system-setup'>
    <title>Adjusting the Extensible SDK to Suit Your Build System Setup</title>

    <para>
        In most cases, the extensible SDK defaults should work.
        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.
                The default value of <filename>SDK_INHERIT_BLACKLIST</filename>
                is set using the "?=" operator.
                Consequently, you will need to either set the complete value
                using "=" or append the value using "_append".
                </para></listitem>
            <listitem><para>
                If you have classes or recipes that add additional tasks to
                the standard build flow (i.e. that execute as part of building
                the recipe as opposed to needing to be called explicitly), then
                you need to do one of the following:
                <itemizedlist>
                    <listitem><para>
                        Ensure the tasks are shared state tasks (i.e. their
                        output is saved to and can be restored from the shared
                        state cache), or that the tasks are able to be
                        produced quickly from a task that is a shared state
                        task and 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
                        <filename>SDK_INHERIT_BLACKLIST</filename> as previously
                        described.
                        </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-after-installing-the-extensible-sdk'>Providing Updates After Installing the Extensible SDK</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>
                or
                <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</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-appearance-of-the-extensible-sdk'>
    <title>Changing the Appearance of the Extensible SDK</title>

    <para>
        You can change the title shown by the SDK installer by setting the
        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink>
        variable.
        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>
</section>

<section id='sdk-providing-updates-after-installing-the-extensible-sdk'>
    <title>Providing Updates After Installing the Extensible SDK</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 to make it possible for those that use
        the SDK to update their installations with the
        <filename>devtool sdk-update</filename> command:
        <orderedlist>
            <listitem><para>
                Arrange to be created a directory that can be shared over
                HTTP or HTTPS.
                </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.
                </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 SDKs to
        simply run <filename>devtool sdk-update</filename> to retrieve the
        latest updates.
        See the
        "<link linkend='sdk-updating-the-extensible-sdk'>Updating the Extensible SDK</link>"
        section for further information.
    </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 the extensible SDK you are building to be
        able to add items to the SDK without needing to build the
        items from source, you need to do a number of things:
        <orderedlist>
            <listitem><para>
                Ensure the additional items you want the user to be able to
                install are actually built.
                You can ensure these items are built a number of different
                ways: 1) Build them explicitly, perhaps using one or more
                "meta" recipes that depend on lists of other recipes to keep
                things tidy, or 2) 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>
            <listitem><para>
                Expose the <filename>sstate-cache</filename> directory
                produced by the build.
                Typically, you expose this directory over HTTP or HTTPS.
                </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> either in
                        your
                        <ulink url='&YOCTO_DOCS_DEV_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>
        </orderedlist>
    </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-installable-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 Eclipse, 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
-->
generated by cgit 1.2.3-korg (git 2.39.0) at 2024-05-06 21:34:32 +0000