Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| 4 | |
| 5 | <appendix id='sdk-appendix-customizing'> |
| 6 | |
Brad Bishop | 37a0e4d | 2017-12-04 01:01:44 -0500 | [diff] [blame] | 7 | <title>Customizing the Extensible SDK</title> |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 8 | |
| 9 | <para> |
Brad Bishop | 1a4b7ee | 2018-12-16 17:11:34 -0800 | [diff] [blame] | 10 | This appendix describes customizations you can apply to the extensible SDK. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 11 | </para> |
| 12 | |
| 13 | <section id='sdk-configuring-the-extensible-sdk'> |
| 14 | <title>Configuring the Extensible SDK</title> |
| 15 | |
| 16 | <para> |
| 17 | The extensible SDK primarily consists of a pre-configured copy of |
| 18 | the OpenEmbedded build system from which it was produced. |
| 19 | Thus, the SDK's configuration is derived using that build system and |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 20 | the filters shown in the following list. |
| 21 | When these filters are present, the OpenEmbedded build system applies |
| 22 | them against <filename>local.conf</filename> and |
| 23 | <filename>auto.conf</filename>: |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 24 | <itemizedlist> |
| 25 | <listitem><para> |
| 26 | Variables whose values start with "/" are excluded since the |
| 27 | assumption is that those values are paths that are likely to |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 28 | be specific to the |
| 29 | <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 30 | </para></listitem> |
| 31 | <listitem><para> |
| 32 | Variables listed in |
| 33 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink> |
| 34 | are excluded. |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 35 | These variables are not allowed through from the OpenEmbedded |
| 36 | build system configuration into the extensible SDK |
| 37 | configuration. |
| 38 | Typically, these variables are specific to the machine on |
| 39 | which the build system is running and could be problematic |
| 40 | as part of the extensible SDK configuration.</para> |
| 41 | |
| 42 | <para>For a list of the variables excluded by default, see the |
| 43 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink> |
| 44 | in the glossary of the Yocto Project Reference Manual. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 45 | </para></listitem> |
| 46 | <listitem><para> |
| 47 | Variables listed in |
| 48 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink> |
| 49 | are included. |
| 50 | Including a variable in the value of |
| 51 | <filename>SDK_LOCAL_CONF_WHITELIST</filename> overrides either |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 52 | of the previous two filters. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 53 | The default value is blank. |
| 54 | </para></listitem> |
| 55 | <listitem><para> |
| 56 | Classes inherited globally with |
| 57 | <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink> |
| 58 | that are listed in |
| 59 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink> |
| 60 | are disabled. |
| 61 | Using <filename>SDK_INHERIT_BLACKLIST</filename> to disable |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 62 | these classes is the typical method to disable classes that |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 63 | are problematic or unnecessary in the SDK context. |
| 64 | The default value blacklists the |
| 65 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink> |
| 66 | and |
| 67 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-icecc'><filename>icecc</filename></ulink> |
| 68 | classes. |
| 69 | </para></listitem> |
| 70 | </itemizedlist> |
| 71 | Additionally, the contents of <filename>conf/sdk-extra.conf</filename>, |
| 72 | when present, are appended to the end of |
| 73 | <filename>conf/local.conf</filename> within the produced SDK, without |
| 74 | any filtering. |
| 75 | The <filename>sdk-extra.conf</filename> file is particularly useful |
| 76 | if you want to set a variable value just for the SDK and not the |
| 77 | OpenEmbedded build system used to create the SDK. |
| 78 | </para> |
| 79 | </section> |
| 80 | |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 81 | <section id='adjusting-the-extensible-sdk-to-suit-your-build-hosts-setup'> |
| 82 | <title>Adjusting the Extensible SDK to Suit Your Build Host's Setup</title> |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 83 | |
| 84 | <para> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 85 | In most cases, the extensible SDK defaults should work with your |
| 86 | <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host's</ulink> |
| 87 | setup. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 88 | However, some cases exist for which you might consider making |
| 89 | adjustments: |
| 90 | <itemizedlist> |
| 91 | <listitem><para> |
| 92 | If your SDK configuration inherits additional classes |
| 93 | using the |
| 94 | <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink> |
| 95 | variable and you do not need or want those classes enabled in |
| 96 | the SDK, you can blacklist them by adding them to the |
| 97 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 98 | variable as described in the fourth bullet of the previous |
| 99 | section. |
| 100 | <note> |
| 101 | The default value of |
| 102 | <filename>SDK_INHERIT_BLACKLIST</filename> is set using |
| 103 | the "?=" operator. |
| 104 | Consequently, you will need to either define the entire |
| 105 | list by using the "=" operator, or you will need to append |
| 106 | a value using either "_append" or the "+=" operator. |
| 107 | You can learn more about these operators in the |
| 108 | "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>" |
| 109 | section of the BitBake User Manual. |
| 110 | </note>. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 111 | </para></listitem> |
| 112 | <listitem><para> |
| 113 | If you have classes or recipes that add additional tasks to |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 114 | the standard build flow (i.e. the tasks execute as the recipe |
| 115 | builds as opposed to being called explicitly), then you need |
| 116 | to do one of the following: |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 117 | <itemizedlist> |
| 118 | <listitem><para> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 119 | After ensuring the tasks are |
| 120 | <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink> |
| 121 | tasks (i.e. the output of the task is saved to and |
| 122 | can be restored from the shared state cache) or |
| 123 | ensuring the tasks are able to be produced quickly from |
| 124 | a task that is a shared state task, add the task name |
| 125 | to the value of |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 126 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS'><filename>SDK_RECRDEP_TASKS</filename></ulink>. |
| 127 | </para></listitem> |
| 128 | <listitem><para> |
| 129 | Disable the tasks if they are added by a class and |
| 130 | you do not need the functionality the class provides |
| 131 | in the extensible SDK. |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 132 | To disable the tasks, add the class to the |
| 133 | <filename>SDK_INHERIT_BLACKLIST</filename> variable |
| 134 | as described in the previous section. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 135 | </para></listitem> |
| 136 | </itemizedlist> |
| 137 | </para></listitem> |
| 138 | <listitem><para> |
| 139 | Generally, you want to have a shared state mirror set up so |
| 140 | users of the SDK can add additional items to the SDK after |
| 141 | installation without needing to build the items from source. |
| 142 | See the |
| 143 | "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>" |
| 144 | section for information. |
| 145 | </para></listitem> |
| 146 | <listitem><para> |
| 147 | If you want users of the SDK to be able to easily update the |
| 148 | SDK, you need to set the |
| 149 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink> |
| 150 | variable. |
| 151 | For more information, see the |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 152 | "<link linkend='sdk-providing-updates-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</link>" |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 153 | section. |
| 154 | </para></listitem> |
| 155 | <listitem><para> |
| 156 | If you have adjusted the list of files and directories that |
| 157 | appear in |
| 158 | <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE'><filename>COREBASE</filename></ulink> |
| 159 | (other than layers that are enabled through |
| 160 | <filename>bblayers.conf</filename>), then you must list these |
| 161 | files in |
| 162 | <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES'><filename>COREBASE_FILES</filename></ulink> |
| 163 | so that the files are copied into the SDK. |
| 164 | </para></listitem> |
| 165 | <listitem><para> |
| 166 | If your OpenEmbedded build system setup uses a different |
| 167 | environment setup script other than |
Brad Bishop | d7bf8c1 | 2018-02-25 22:55:05 -0500 | [diff] [blame] | 168 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>, |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 169 | then you must set |
| 170 | <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT'><filename>OE_INIT_ENV_SCRIPT</filename></ulink> |
| 171 | to point to the environment setup script you use. |
| 172 | <note> |
| 173 | You must also reflect this change in the value used for the |
| 174 | <filename>COREBASE_FILES</filename> variable as previously |
| 175 | described. |
| 176 | </note> |
| 177 | </para></listitem> |
| 178 | </itemizedlist> |
| 179 | </para> |
| 180 | </section> |
| 181 | |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 182 | <section id='sdk-changing-the-sdk-installer-title'> |
| 183 | <title>Changing the Extensible SDK Installer Title</title> |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 184 | |
| 185 | <para> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 186 | You can change the displayed title for the SDK installer by setting |
| 187 | the |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 188 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink> |
Brad Bishop | 1a4b7ee | 2018-12-16 17:11:34 -0800 | [diff] [blame] | 189 | variable and then rebuilding the the SDK installer. |
| 190 | For information on how to build an SDK installer, see the |
| 191 | "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" |
| 192 | section. |
| 193 | </para> |
| 194 | |
| 195 | <para> |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 196 | By default, this title is derived from |
| 197 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink> |
| 198 | when it is set. |
| 199 | If the <filename>DISTRO_NAME</filename> variable is not set, the title |
| 200 | is derived from the |
| 201 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> |
| 202 | variable. |
| 203 | </para> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 204 | |
| 205 | <para> |
| 206 | The |
Brad Bishop | 1a4b7ee | 2018-12-16 17:11:34 -0800 | [diff] [blame] | 207 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 208 | class defines the default value of the <filename>SDK_TITLE</filename> |
| 209 | variable as follows: |
| 210 | <literallayout class='monospaced'> |
Brad Bishop | 1a4b7ee | 2018-12-16 17:11:34 -0800 | [diff] [blame] | 211 | SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" |
| 212 | </literallayout> |
| 213 | </para> |
| 214 | |
| 215 | <para> |
| 216 | While several ways exist to change this variable, an efficient method |
| 217 | is to set the variable in your distribution's configuration file. |
| 218 | Doing so creates an SDK installer title that applies across your |
| 219 | distribution. |
| 220 | As an example, assume you have your own layer for your distribution |
| 221 | named "meta-mydistro" and you are using the same type of file |
| 222 | hierarchy as does the default "poky" distribution. |
| 223 | If so, you could update the <filename>SDK_TITLE</filename> variable |
| 224 | in the |
| 225 | <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file |
| 226 | using the following form: |
| 227 | <literallayout class='monospaced'> |
| 228 | SDK_TITLE = "<replaceable>your_title</replaceable>" |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 229 | </literallayout> |
| 230 | </para> |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 231 | </section> |
| 232 | |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 233 | <section id='sdk-providing-updates-to-the-extensible-sdk-after-installation'> |
| 234 | <title>Providing Updates to the Extensible SDK After Installation</title> |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 235 | |
| 236 | <para> |
| 237 | When you make changes to your configuration or to the metadata and |
| 238 | if you want those changes to be reflected in installed SDKs, you need |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 239 | to perform additional steps. |
| 240 | These steps make it possible for anyone using the installed SDKs to |
| 241 | update the installed SDKs by using the |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 242 | <filename>devtool sdk-update</filename> command: |
| 243 | <orderedlist> |
| 244 | <listitem><para> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 245 | Create a directory that can be shared over HTTP or HTTPS. |
| 246 | You can do this by setting up a web server such as an |
| 247 | <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink> |
| 248 | or |
| 249 | <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink> |
| 250 | server in the cloud to host the directory. |
| 251 | This directory must contain the published SDK. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 252 | </para></listitem> |
| 253 | <listitem><para> |
| 254 | Set the |
| 255 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink> |
| 256 | variable to point to the corresponding HTTP or HTTPS URL. |
| 257 | Setting this variable causes any SDK built to default to that |
| 258 | URL and thus, the user does not have to pass the URL to the |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 259 | <filename>devtool sdk-update</filename> command as described |
| 260 | in the |
| 261 | "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>" |
| 262 | section. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 263 | </para></listitem> |
| 264 | <listitem><para> |
| 265 | Build the extensible SDK normally (i.e., use the |
| 266 | <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable> |
| 267 | command). |
| 268 | </para></listitem> |
| 269 | <listitem><para> |
| 270 | Publish the SDK using the following command: |
| 271 | <literallayout class='monospaced'> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 272 | $ oe-publish-sdk <replaceable>some_path</replaceable>/sdk-installer.sh <replaceable>path_to_shared_http_directory</replaceable> |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 273 | </literallayout> |
| 274 | You must repeat this step each time you rebuild the SDK |
| 275 | with changes that you want to make available through the |
| 276 | update mechanism. |
| 277 | </para></listitem> |
| 278 | </orderedlist> |
| 279 | </para> |
| 280 | |
| 281 | <para> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 282 | Completing the above steps allows users of the existing installed |
| 283 | SDKs to simply run <filename>devtool sdk-update</filename> to |
| 284 | retrieve and apply the latest updates. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 285 | See the |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 286 | "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>" |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 287 | section for further information. |
| 288 | </para> |
| 289 | </section> |
| 290 | |
Brad Bishop | 1a4b7ee | 2018-12-16 17:11:34 -0800 | [diff] [blame] | 291 | <section id='sdk-changing-the-default-sdk-installation-directory'> |
| 292 | <title>Changing the Default SDK Installation Directory</title> |
| 293 | |
| 294 | <para> |
| 295 | When you build the installer for the Extensible SDK, the default |
| 296 | installation directory for the SDK is based on the |
| 297 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> |
| 298 | and |
| 299 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH'><filename>SDKEXTPATH</filename></ulink> |
| 300 | variables from within the |
| 301 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink> |
| 302 | class as follows: |
| 303 | <literallayout class='monospaced'> |
| 304 | SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" |
| 305 | </literallayout> |
| 306 | You can change this default installation directory by specifically |
| 307 | setting the <filename>SDKEXTPATH</filename> variable. |
| 308 | </para> |
| 309 | |
| 310 | <para> |
| 311 | While a number of ways exist through which you can set this variable, |
| 312 | the method that makes the most sense is to set the variable in your |
| 313 | distribution's configuration file. |
| 314 | Doing so creates an SDK installer default directory that applies |
| 315 | across your distribution. |
| 316 | As an example, assume you have your own layer for your distribution |
| 317 | named "meta-mydistro" and you are using the same type of file |
| 318 | hierarchy as does the default "poky" distribution. |
| 319 | If so, you could update the <filename>SDKEXTPATH</filename> variable |
| 320 | in the |
| 321 | <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file |
| 322 | using the following form: |
| 323 | <literallayout class='monospaced'> |
| 324 | SDKEXTPATH = "<replaceable>some_path_for_your_installed_sdk</replaceable>" |
| 325 | </literallayout> |
| 326 | </para> |
| 327 | |
| 328 | <para> |
| 329 | After building your installer, running it prompts the user for |
| 330 | acceptance of the |
| 331 | <replaceable>some_path_for_your_installed_sdk</replaceable> directory |
| 332 | as the default location to install the Extensible SDK. |
| 333 | </para> |
| 334 | </section> |
| 335 | |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 336 | <section id='sdk-providing-additional-installable-extensible-sdk-content'> |
| 337 | <title>Providing Additional Installable Extensible SDK Content</title> |
| 338 | |
| 339 | <para> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 340 | If you want the users of an extensible SDK you build to be |
| 341 | able to add items to the SDK without requiring the users to build |
| 342 | the items from source, you need to do a number of things: |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 343 | <orderedlist> |
| 344 | <listitem><para> |
| 345 | Ensure the additional items you want the user to be able to |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 346 | install are already built: |
| 347 | <itemizedlist> |
| 348 | <listitem><para> |
| 349 | Build the items explicitly. |
| 350 | You could use one or more "meta" recipes that depend |
| 351 | on lists of other recipes. |
| 352 | </para></listitem> |
| 353 | <listitem><para> |
| 354 | Build the "world" target and set |
| 355 | <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable> |
| 356 | for the recipes you do not want built. |
| 357 | See the |
| 358 | <ulink url='&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD'><filename>EXCLUDE_FROM_WORLD</filename></ulink> |
| 359 | variable for additional information. |
| 360 | </para></listitem> |
| 361 | </itemizedlist> |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 362 | </para></listitem> |
| 363 | <listitem><para> |
| 364 | Expose the <filename>sstate-cache</filename> directory |
| 365 | produced by the build. |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 366 | Typically, you expose this directory by making it available |
| 367 | through an |
| 368 | <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink> |
| 369 | or |
| 370 | <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink> |
| 371 | server. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 372 | </para></listitem> |
| 373 | <listitem><para> |
| 374 | Set the appropriate configuration so that the produced SDK |
| 375 | knows how to find the configuration. |
| 376 | The variable you need to set is |
| 377 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>: |
| 378 | <literallayout class='monospaced'> |
| 379 | SSTATE_MIRRORS = "file://.* http://<replaceable>example</replaceable>.com/<replaceable>some_path</replaceable>/sstate-cache/PATH" |
| 380 | </literallayout> |
| 381 | You can set the <filename>SSTATE_MIRRORS</filename> variable |
| 382 | in two different places: |
| 383 | <itemizedlist> |
| 384 | <listitem><para> |
| 385 | If the mirror value you are setting is appropriate to |
| 386 | be set for both the OpenEmbedded build system that is |
| 387 | actually building the SDK and the SDK itself (i.e. the |
| 388 | mirror is accessible in both places or it will fail |
| 389 | quickly on the OpenEmbedded build system side, and its |
| 390 | contents will not interfere with the build), then you |
| 391 | can set the variable in your |
| 392 | <filename>local.conf</filename> or custom distro |
| 393 | configuration file. |
| 394 | You can then "whitelist" the variable through |
| 395 | to the SDK by adding the following: |
| 396 | <literallayout class='monospaced'> |
| 397 | SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS" |
| 398 | </literallayout> |
| 399 | </para></listitem> |
| 400 | <listitem><para> |
| 401 | Alternatively, if you just want to set the |
| 402 | <filename>SSTATE_MIRRORS</filename> variable's value |
| 403 | for the SDK alone, create a |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 404 | <filename>conf/sdk-extra.conf</filename> file either in |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 405 | your |
Brad Bishop | d7bf8c1 | 2018-02-25 22:55:05 -0500 | [diff] [blame] | 406 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 407 | or within any layer and put your |
| 408 | <filename>SSTATE_MIRRORS</filename> setting within |
| 409 | that file. |
| 410 | <note> |
| 411 | This second option is the safest option should |
| 412 | you have any doubts as to which method to use when |
| 413 | setting <filename>SSTATE_MIRRORS</filename>. |
| 414 | </note> |
| 415 | </para></listitem> |
| 416 | </itemizedlist> |
| 417 | </para></listitem> |
| 418 | </orderedlist> |
| 419 | </para> |
| 420 | </section> |
| 421 | |
| 422 | <section id='sdk-minimizing-the-size-of-the-extensible-sdk-installer-download'> |
| 423 | <title>Minimizing the Size of the Extensible SDK Installer Download</title> |
| 424 | |
| 425 | <para> |
| 426 | By default, the extensible SDK bundles the shared state artifacts for |
| 427 | everything needed to reconstruct the image for which the SDK was built. |
| 428 | This bundling can lead to an SDK installer file that is a Gigabyte or |
| 429 | more in size. |
| 430 | If the size of this file causes a problem, you can build an SDK that |
| 431 | has just enough in it to install and provide access to the |
| 432 | <filename>devtool command</filename> by setting the following in your |
| 433 | configuration: |
| 434 | <literallayout class='monospaced'> |
| 435 | SDK_EXT_TYPE = "minimal" |
| 436 | </literallayout> |
| 437 | Setting |
| 438 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> |
| 439 | to "minimal" produces an SDK installer that is around 35 Mbytes in |
| 440 | size, which downloads and installs quickly. |
| 441 | You need to realize, though, that the minimal installer does not |
| 442 | install any libraries or tools out of the box. |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 443 | These libraries and tools must be installed either "on the fly" or |
| 444 | through actions you perform using <filename>devtool</filename> or |
| 445 | explicitly with the <filename>devtool sdk-install</filename> command. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 446 | </para> |
| 447 | |
| 448 | <para> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 449 | In most cases, when building a minimal SDK you need to also enable |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 450 | bringing in the information on a wider range of packages produced by |
| 451 | the system. |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 452 | Requiring this wider range of information is particularly true |
| 453 | so that <filename>devtool add</filename> is able to effectively map |
| 454 | dependencies it discovers in a source tree to the appropriate recipes. |
| 455 | Additionally, the information enables the |
| 456 | <filename>devtool search</filename> command to return useful results. |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 457 | </para> |
| 458 | |
| 459 | <para> |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 460 | To facilitate this wider range of information, you would need to |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 461 | set the following: |
| 462 | <literallayout class='monospaced'> |
| 463 | SDK_INCLUDE_PKGDATA = "1" |
| 464 | </literallayout> |
| 465 | See the |
| 466 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink> |
| 467 | variable for additional information. |
| 468 | </para> |
| 469 | |
| 470 | <para> |
| 471 | Setting the <filename>SDK_INCLUDE_PKGDATA</filename> variable as |
| 472 | shown causes the "world" target to be built so that information |
| 473 | for all of the recipes included within it are available. |
| 474 | Having these recipes available increases build time significantly and |
| 475 | increases the size of the SDK installer by 30-80 Mbytes depending on |
| 476 | how many recipes are included in your configuration. |
| 477 | </para> |
| 478 | |
| 479 | <para> |
| 480 | You can use |
| 481 | <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable> |
| 482 | for recipes you want to exclude. |
| 483 | However, it is assumed that you would need to be building the "world" |
| 484 | target if you want to provide additional items to the SDK. |
| 485 | Consequently, building for "world" should not represent undue |
| 486 | overhead in most cases. |
| 487 | <note> |
| 488 | If you set <filename>SDK_EXT_TYPE</filename> to "minimal", |
| 489 | then providing a shared state mirror is mandatory so that items |
| 490 | can be installed as needed. |
| 491 | See the |
| 492 | "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>" |
| 493 | section for more information. |
| 494 | </note> |
| 495 | </para> |
Patrick Williams | c0f7c04 | 2017-02-23 20:41:17 -0600 | [diff] [blame] | 496 | |
| 497 | <para> |
| 498 | You can explicitly control whether or not to include the toolchain |
| 499 | when you build an SDK by setting the |
| 500 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> |
| 501 | variable to "1". |
| 502 | In particular, it is useful to include the toolchain when you |
Brad Bishop | d5ae7d9 | 2018-06-14 09:52:03 -0700 | [diff] [blame] | 503 | have set <filename>SDK_EXT_TYPE</filename> to "minimal", which by |
| 504 | default, excludes the toolchain. |
Patrick Williams | c0f7c04 | 2017-02-23 20:41:17 -0600 | [diff] [blame] | 505 | Also, it is helpful if you are building a small SDK for use with |
Brad Bishop | c342db3 | 2019-05-15 21:57:59 -0400 | [diff] [blame] | 506 | an IDE or some |
Brad Bishop | 316dfdd | 2018-06-25 12:45:53 -0400 | [diff] [blame] | 507 | other tool where you do not want to take extra steps to install a |
| 508 | toolchain. |
Patrick Williams | c0f7c04 | 2017-02-23 20:41:17 -0600 | [diff] [blame] | 509 | </para> |
Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 510 | </section> |
| 511 | </appendix> |
| 512 | <!-- |
| 513 | vim: expandtab tw=80 ts=4 |
| 514 | --> |