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