summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual')
-rw-r--r--documentation/sdk-manual/appendix-customizing-standard.rst6
-rw-r--r--documentation/sdk-manual/appendix-customizing.rst187
-rw-r--r--documentation/sdk-manual/appendix-obtain.rst207
-rw-r--r--documentation/sdk-manual/extensible.rst1198
-rw-r--r--documentation/sdk-manual/figures/sdk-devtool-add-flow.pngbin181699 -> 0 bytes
-rw-r--r--documentation/sdk-manual/figures/sdk-devtool-modify-flow.pngbin171676 -> 0 bytes
-rw-r--r--documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.pngbin138917 -> 0 bytes
-rw-r--r--documentation/sdk-manual/history.rst40
-rw-r--r--documentation/sdk-manual/index.rst1
-rw-r--r--documentation/sdk-manual/intro.rst78
-rw-r--r--documentation/sdk-manual/using.rst64
-rw-r--r--documentation/sdk-manual/working-projects.rst158
12 files changed, 439 insertions, 1500 deletions
diff --git a/documentation/sdk-manual/appendix-customizing-standard.rst b/documentation/sdk-manual/appendix-customizing-standard.rst
index 90b634529e..c619c15e46 100644
--- a/documentation/sdk-manual/appendix-customizing-standard.rst
+++ b/documentation/sdk-manual/appendix-customizing-standard.rst
@@ -17,10 +17,10 @@ and
17variables control the set of packages adding to the SDK. 17variables control the set of packages adding to the SDK.
18 18
19If you want to add individual packages to the toolchain that runs on the 19If you want to add individual packages to the toolchain that runs on the
20host, simply add those packages to the ``TOOLCHAIN_HOST_TASK`` variable. 20host, simply add those packages to the :term:`TOOLCHAIN_HOST_TASK` variable.
21Similarly, if you want to add packages to the default set that is part 21Similarly, if you want to add packages to the default set that is part
22of the toolchain that runs on the target, add the packages to the 22of the toolchain that runs on the target, add the packages to the
23``TOOLCHAIN_TARGET_TASK`` variable. 23:term:`TOOLCHAIN_TARGET_TASK` variable.
24 24
25Adding API Documentation to the Standard SDK 25Adding API Documentation to the Standard SDK
26============================================ 26============================================
@@ -29,6 +29,6 @@ You can include API documentation as well as any other documentation
29provided by recipes with the standard SDK by adding "api-documentation" 29provided by recipes with the standard SDK by adding "api-documentation"
30to the 30to the
31:term:`DISTRO_FEATURES` 31:term:`DISTRO_FEATURES`
32variable: DISTRO_FEATURES_append = " api-documentation" Setting this 32variable: DISTRO_FEATURES:append = " api-documentation" Setting this
33variable as shown here causes the OpenEmbedded build system to build the 33variable as shown here causes the OpenEmbedded build system to build the
34documentation and then include it in the standard SDK. 34documentation and then include it in the standard SDK.
diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst
index 97ade0801d..61091d83ba 100644
--- a/documentation/sdk-manual/appendix-customizing.rst
+++ b/documentation/sdk-manual/appendix-customizing.rst
@@ -1,11 +1,17 @@
1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2 2
3****************************** 3***************************************************
4Customizing the Extensible SDK 4Customizing the Extensible SDK standalone installer
5****************************** 5***************************************************
6 6
7This appendix describes customizations you can apply to the extensible 7This appendix describes customizations you can apply to the extensible
8SDK. 8SDK when using in the standalone installer version.
9
10.. note::
11
12 It is also possible to use the Extensible SDK functionality directly in a
13 Yocto build, avoiding separate installer artefacts. Please refer to
14 ":ref:`sdk-manual/extensible:Installing the Extensible SDK`"
9 15
10Configuring the Extensible SDK 16Configuring the Extensible SDK
11============================== 17==============================
@@ -21,7 +27,7 @@ build system applies them against ``local.conf`` and ``auto.conf``:
21 specific to the :term:`Build Host`. 27 specific to the :term:`Build Host`.
22 28
23- Variables listed in 29- Variables listed in
24 :term:`SDK_LOCAL_CONF_BLACKLIST` 30 :term:`ESDK_LOCALCONF_REMOVE`
25 are excluded. These variables are not allowed through from the 31 are excluded. These variables are not allowed through from the
26 OpenEmbedded build system configuration into the extensible SDK 32 OpenEmbedded build system configuration into the extensible SDK
27 configuration. Typically, these variables are specific to the machine 33 configuration. Typically, these variables are specific to the machine
@@ -29,23 +35,21 @@ build system applies them against ``local.conf`` and ``auto.conf``:
29 of the extensible SDK configuration. 35 of the extensible SDK configuration.
30 36
31 For a list of the variables excluded by default, see the 37 For a list of the variables excluded by default, see the
32 :term:`SDK_LOCAL_CONF_BLACKLIST` 38 :term:`ESDK_LOCALCONF_REMOVE`
33 in the glossary of the Yocto Project Reference Manual. 39 in the glossary of the Yocto Project Reference Manual.
34 40
35- Variables listed in 41- Variables listed in
36 :term:`SDK_LOCAL_CONF_WHITELIST` 42 :term:`ESDK_LOCALCONF_ALLOW`
37 are included. Including a variable in the value of 43 are included. Including a variable in the value of
38 ``SDK_LOCAL_CONF_WHITELIST`` overrides either of the previous two 44 :term:`ESDK_LOCALCONF_ALLOW` overrides either of the previous two
39 filters. The default value is blank. 45 filters. The default value is blank.
40 46
41- Classes inherited globally with 47- Classes inherited globally with :term:`INHERIT` that are listed in
42 :term:`INHERIT` that are listed in 48 :term:`ESDK_CLASS_INHERIT_DISABLE` are disabled. Using
43 :term:`SDK_INHERIT_BLACKLIST` 49 :term:`ESDK_CLASS_INHERIT_DISABLE` to disable these classes is the typical
44 are disabled. Using ``SDK_INHERIT_BLACKLIST`` to disable these 50 method to disable classes that are problematic or unnecessary in the SDK
45 classes is the typical method to disable classes that are problematic 51 context. The default value disables the
46 or unnecessary in the SDK context. The default value blacklists the 52 :ref:`ref-classes-buildhistory` and :ref:`ref-classes-icecc` classes.
47 :ref:`buildhistory <ref-classes-buildhistory>`
48 and :ref:`icecc <ref-classes-icecc>` classes.
49 53
50Additionally, the contents of ``conf/sdk-extra.conf``, when present, are 54Additionally, the contents of ``conf/sdk-extra.conf``, when present, are
51appended to the end of ``conf/local.conf`` within the produced SDK, 55appended to the end of ``conf/local.conf`` within the produced SDK,
@@ -57,29 +61,24 @@ Adjusting the Extensible SDK to Suit Your Build Host's Setup
57============================================================ 61============================================================
58 62
59In most cases, the extensible SDK defaults should work with your :term:`Build 63In most cases, the extensible SDK defaults should work with your :term:`Build
60Host`'s setup. 64Host`'s setup. However, there are cases when you might consider making
61However, some cases exist for which you might consider making
62adjustments: 65adjustments:
63 66
64- If your SDK configuration inherits additional classes using the 67- If your SDK configuration inherits additional classes using the
65 :term:`INHERIT` variable and you 68 :term:`INHERIT` variable and you
66 do not need or want those classes enabled in the SDK, you can 69 do not need or want those classes enabled in the SDK, you can
67 blacklist them by adding them to the 70 disable them by adding them to the :term:`ESDK_CLASS_INHERIT_DISABLE`
68 :term:`SDK_INHERIT_BLACKLIST` 71 variable as described in the previous section.
69 variable as described in the fourth bullet of the previous section.
70 72
71 .. note:: 73 .. note::
72 74
73 The default value of 75 The default value of :term:`ESDK_CLASS_INHERIT_DISABLE`
74 SDK_INHERIT_BLACKLIST
75 is set using the "?=" operator. Consequently, you will need to 76 is set using the "?=" operator. Consequently, you will need to
76 either define the entire list by using the "=" operator, or you 77 either define the entire list by using the "=" operator, or you
77 will need to append a value using either "_append" or the "+=" 78 will need to append a value using either ":append" or the "+="
78 operator. You can learn more about these operators in the " 79 operator. You can learn more about these operators in the
79 Basic Syntax 80 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`"
80 " section of the BitBake User Manual. 81 section of the BitBake User Manual.
81
82 .
83 82
84- If you have classes or recipes that add additional tasks to the 83- If you have classes or recipes that add additional tasks to the
85 standard build flow (i.e. the tasks execute as the recipe builds as 84 standard build flow (i.e. the tasks execute as the recipe builds as
@@ -96,22 +95,20 @@ adjustments:
96 95
97 - Disable the tasks if they are added by a class and you do not need 96 - Disable the tasks if they are added by a class and you do not need
98 the functionality the class provides in the extensible SDK. To 97 the functionality the class provides in the extensible SDK. To
99 disable the tasks, add the class to the ``SDK_INHERIT_BLACKLIST`` 98 disable the tasks, add the class to the :term:`ESDK_CLASS_INHERIT_DISABLE`
100 variable as described in the previous section. 99 variable as described in the previous section.
101 100
102- Generally, you want to have a shared state mirror set up so users of 101- Generally, you want to have a shared state mirror set up so users of
103 the SDK can add additional items to the SDK after installation 102 the SDK can add additional items to the SDK after installation
104 without needing to build the items from source. See the "`Providing 103 without needing to build the items from source. See the
105 Additional Installable Extensible SDK 104 ":ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`"
106 Content <#sdk-providing-additional-installable-extensible-sdk-content>`__"
107 section for information. 105 section for information.
108 106
109- If you want users of the SDK to be able to easily update the SDK, you 107- If you want users of the SDK to be able to easily update the SDK, you
110 need to set the 108 need to set the
111 :term:`SDK_UPDATE_URL` 109 :term:`SDK_UPDATE_URL`
112 variable. For more information, see the "`Providing Updates to the 110 variable. For more information, see the
113 Extensible SDK After 111 ":ref:`sdk-manual/appendix-customizing:providing updates to the extensible sdk after installation`"
114 Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__"
115 section. 112 section.
116 113
117- If you have adjusted the list of files and directories that appear in 114- If you have adjusted the list of files and directories that appear in
@@ -131,41 +128,38 @@ adjustments:
131 .. note:: 128 .. note::
132 129
133 You must also reflect this change in the value used for the 130 You must also reflect this change in the value used for the
134 COREBASE_FILES 131 :term:`COREBASE_FILES` variable as previously described.
135 variable as previously described.
136 132
137Changing the Extensible SDK Installer Title 133Changing the Extensible SDK Installer Title
138=========================================== 134===========================================
139 135
140You can change the displayed title for the SDK installer by setting the 136You can change the displayed title for the SDK installer by setting the
141:term:`SDK_TITLE` variable and then 137:term:`SDK_TITLE` variable and then
142rebuilding the the SDK installer. For information on how to build an SDK 138rebuilding the SDK installer. For information on how to build an SDK
143installer, see the "`Building an SDK 139installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
144Installer <#sdk-building-an-sdk-installer>`__" section. 140section.
145 141
146By default, this title is derived from 142By default, this title is derived from
147:term:`DISTRO_NAME` when it is 143:term:`DISTRO_NAME` when it is
148set. If the ``DISTRO_NAME`` variable is not set, the title is derived 144set. If the :term:`DISTRO_NAME` variable is not set, the title is derived
149from the :term:`DISTRO` variable. 145from the :term:`DISTRO` variable.
150 146
151The 147The
152:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` 148:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
153class defines the default value of the ``SDK_TITLE`` variable as 149class defines the default value of the :term:`SDK_TITLE` variable as
154follows: 150follows::
155::
156 151
157 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" 152 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
158 153
159While several ways exist to change this variable, an efficient method is 154While there are several ways of changing this variable, an efficient method is
160to set the variable in your distribution's configuration file. Doing so 155to set the variable in your distribution's configuration file. Doing so
161creates an SDK installer title that applies across your distribution. As 156creates an SDK installer title that applies across your distribution. As
162an example, assume you have your own layer for your distribution named 157an example, assume you have your own layer for your distribution named
163"meta-mydistro" and you are using the same type of file hierarchy as 158"meta-mydistro" and you are using the same type of file hierarchy as
164does the default "poky" distribution. If so, you could update the 159does the default "poky" distribution. If so, you could update the
165``SDK_TITLE`` variable in the 160:term:`SDK_TITLE` variable in the
166``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following 161``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
167form: 162form::
168::
169 163
170 SDK_TITLE = "your_title" 164 SDK_TITLE = "your_title"
171 165
@@ -178,27 +172,24 @@ perform additional steps. These steps make it possible for anyone using
178the installed SDKs to update the installed SDKs by using the 172the installed SDKs to update the installed SDKs by using the
179``devtool sdk-update`` command: 173``devtool sdk-update`` command:
180 174
1811. Create a directory that can be shared over HTTP or HTTPS. You can do 175#. Create a directory that can be shared over HTTP or HTTPS. You can do
182 this by setting up a web server such as an `Apache HTTP 176 this by setting up a web server such as an :wikipedia:`Apache HTTP Server
183 Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or 177 <Apache_HTTP_Server>` or :wikipedia:`Nginx <Nginx>` server in the cloud
184 `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server in the cloud
185 to host the directory. This directory must contain the published SDK. 178 to host the directory. This directory must contain the published SDK.
186 179
1872. Set the 180#. Set the
188 :term:`SDK_UPDATE_URL` 181 :term:`SDK_UPDATE_URL`
189 variable to point to the corresponding HTTP or HTTPS URL. Setting 182 variable to point to the corresponding HTTP or HTTPS URL. Setting
190 this variable causes any SDK built to default to that URL and thus, 183 this variable causes any SDK built to default to that URL and thus,
191 the user does not have to pass the URL to the ``devtool sdk-update`` 184 the user does not have to pass the URL to the ``devtool sdk-update``
192 command as described in the "`Applying Updates to an Installed 185 command as described in the
193 Extensible 186 ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
194 SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__"
195 section. 187 section.
196 188
1973. Build the extensible SDK normally (i.e., use the 189#. Build the extensible SDK normally (i.e., use the
198 ``bitbake -c populate_sdk_ext`` imagename command). 190 ``bitbake -c populate_sdk_ext`` imagename command).
199 191
2004. Publish the SDK using the following command: 192#. Publish the SDK using the following command::
201 ::
202 193
203 $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory 194 $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
204 195
@@ -208,9 +199,9 @@ the installed SDKs to update the installed SDKs by using the
208 199
209Completing the above steps allows users of the existing installed SDKs 200Completing the above steps allows users of the existing installed SDKs
210to simply run ``devtool sdk-update`` to retrieve and apply the latest 201to simply run ``devtool sdk-update`` to retrieve and apply the latest
211updates. See the "`Applying Updates to an Installed Extensible 202updates. See the
212SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" section 203":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
213for further information. 204section for further information.
214 205
215Changing the Default SDK Installation Directory 206Changing the Default SDK Installation Directory
216=============================================== 207===============================================
@@ -221,26 +212,24 @@ installation directory for the SDK is based on the
221:term:`SDKEXTPATH` variables from 212:term:`SDKEXTPATH` variables from
222within the 213within the
223:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` 214:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
224class as follows: 215class as follows::
225::
226 216
227 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" 217 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
228 218
229You can 219You can
230change this default installation directory by specifically setting the 220change this default installation directory by specifically setting the
231``SDKEXTPATH`` variable. 221:term:`SDKEXTPATH` variable.
232 222
233While a number of ways exist through which you can set this variable, 223While there are several ways of setting this variable,
234the method that makes the most sense is to set the variable in your 224the method that makes the most sense is to set the variable in your
235distribution's configuration file. Doing so creates an SDK installer 225distribution's configuration file. Doing so creates an SDK installer
236default directory that applies across your distribution. As an example, 226default directory that applies across your distribution. As an example,
237assume you have your own layer for your distribution named 227assume you have your own layer for your distribution named
238"meta-mydistro" and you are using the same type of file hierarchy as 228"meta-mydistro" and you are using the same type of file hierarchy as
239does the default "poky" distribution. If so, you could update the 229does the default "poky" distribution. If so, you could update the
240``SDKEXTPATH`` variable in the 230:term:`SDKEXTPATH` variable in the
241``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following 231``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
242form: 232form::
243::
244 233
245 SDKEXTPATH = "some_path_for_your_installed_sdk" 234 SDKEXTPATH = "some_path_for_your_installed_sdk"
246 235
@@ -255,33 +244,30 @@ If you want the users of an extensible SDK you build to be able to add
255items to the SDK without requiring the users to build the items from 244items to the SDK without requiring the users to build the items from
256source, you need to do a number of things: 245source, you need to do a number of things:
257 246
2581. Ensure the additional items you want the user to be able to install 247#. Ensure the additional items you want the user to be able to install
259 are already built: 248 are already built:
260 249
261 - Build the items explicitly. You could use one or more "meta" 250 - Build the items explicitly. You could use one or more "meta"
262 recipes that depend on lists of other recipes. 251 recipes that depend on lists of other recipes.
263 252
264 - Build the "world" target and set 253 - Build the "world" target and set
265 ``EXCLUDE_FROM_WORLD_pn-``\ recipename for the recipes you do not 254 ``EXCLUDE_FROM_WORLD:pn-``\ recipename for the recipes you do not
266 want built. See the 255 want built. See the
267 :term:`EXCLUDE_FROM_WORLD` 256 :term:`EXCLUDE_FROM_WORLD`
268 variable for additional information. 257 variable for additional information.
269 258
2702. Expose the ``sstate-cache`` directory produced by the build. 259#. Expose the ``sstate-cache`` directory produced by the build.
271 Typically, you expose this directory by making it available through 260 Typically, you expose this directory by making it available through
272 an `Apache HTTP 261 an :wikipedia:`Apache HTTP Server <Apache_HTTP_Server>` or
273 Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or 262 :wikipedia:`Nginx <Nginx>` server.
274 `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server.
275 263
2763. Set the appropriate configuration so that the produced SDK knows how 264#. Set the appropriate configuration so that the produced SDK knows how
277 to find the configuration. The variable you need to set is 265 to find the configuration. The variable you need to set is
278 :term:`SSTATE_MIRRORS`: 266 :term:`SSTATE_MIRRORS`::
279 ::
280 267
281 SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH" 268 SSTATE_MIRRORS = "file://.* https://example.com/some_path/sstate-cache/PATH"
282 269
283 You can set the 270 You can set the :term:`SSTATE_MIRRORS` variable in two different places:
284 ``SSTATE_MIRRORS`` variable in two different places:
285 271
286 - If the mirror value you are setting is appropriate to be set for 272 - If the mirror value you are setting is appropriate to be set for
287 both the OpenEmbedded build system that is actually building the 273 both the OpenEmbedded build system that is actually building the
@@ -289,24 +275,21 @@ source, you need to do a number of things:
289 places or it will fail quickly on the OpenEmbedded build system 275 places or it will fail quickly on the OpenEmbedded build system
290 side, and its contents will not interfere with the build), then 276 side, and its contents will not interfere with the build), then
291 you can set the variable in your ``local.conf`` or custom distro 277 you can set the variable in your ``local.conf`` or custom distro
292 configuration file. You can then "whitelist" the variable through 278 configuration file. You can then pass the variable to the SDK by
293 to the SDK by adding the following: 279 adding the following::
294 ::
295 280
296 SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS" 281 ESDK_LOCALCONF_ALLOW = "SSTATE_MIRRORS"
297 282
298 - Alternatively, if you just want to set the ``SSTATE_MIRRORS`` 283 - Alternatively, if you just want to set the :term:`SSTATE_MIRRORS`
299 variable's value for the SDK alone, create a 284 variable's value for the SDK alone, create a ``conf/sdk-extra.conf``
300 ``conf/sdk-extra.conf`` file either in your 285 file either in your :term:`Build Directory` or within any
301 :term:`Build Directory` or within any 286 layer and put your :term:`SSTATE_MIRRORS` setting within that file.
302 layer and put your ``SSTATE_MIRRORS`` setting within that file.
303 287
304 .. note:: 288 .. note::
305 289
306 This second option is the safest option should you have any 290 This second option is the safest option should you have any
307 doubts as to which method to use when setting 291 doubts as to which method to use when setting
308 SSTATE_MIRRORS 292 :term:`SSTATE_MIRRORS`
309 .
310 293
311Minimizing the Size of the Extensible SDK Installer Download 294Minimizing the Size of the Extensible SDK Installer Download
312============================================================ 295============================================================
@@ -316,8 +299,7 @@ everything needed to reconstruct the image for which the SDK was built.
316This bundling can lead to an SDK installer file that is a Gigabyte or 299This bundling can lead to an SDK installer file that is a Gigabyte or
317more in size. If the size of this file causes a problem, you can build 300more in size. If the size of this file causes a problem, you can build
318an SDK that has just enough in it to install and provide access to the 301an SDK that has just enough in it to install and provide access to the
319``devtool command`` by setting the following in your configuration: 302``devtool command`` by setting the following in your configuration::
320::
321 303
322 SDK_EXT_TYPE = "minimal" 304 SDK_EXT_TYPE = "minimal"
323 305
@@ -339,20 +321,19 @@ information enables the ``devtool search`` command to return useful
339results. 321results.
340 322
341To facilitate this wider range of information, you would need to set the 323To facilitate this wider range of information, you would need to set the
342following: 324following::
343::
344 325
345 SDK_INCLUDE_PKGDATA = "1" 326 SDK_INCLUDE_PKGDATA = "1"
346 327
347See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information. 328See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.
348 329
349Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world" 330Setting the :term:`SDK_INCLUDE_PKGDATA` variable as shown causes the "world"
350target to be built so that information for all of the recipes included 331target to be built so that information for all of the recipes included
351within it are available. Having these recipes available increases build 332within it are available. Having these recipes available increases build
352time significantly and increases the size of the SDK installer by 30-80 333time significantly and increases the size of the SDK installer by 30-80
353Mbytes depending on how many recipes are included in your configuration. 334Mbytes depending on how many recipes are included in your configuration.
354 335
355You can use ``EXCLUDE_FROM_WORLD_pn-``\ recipename for recipes you want 336You can use ``EXCLUDE_FROM_WORLD:pn-``\ recipename for recipes you want
356to exclude. However, it is assumed that you would need to be building 337to exclude. However, it is assumed that you would need to be building
357the "world" target if you want to provide additional items to the SDK. 338the "world" target if you want to provide additional items to the SDK.
358Consequently, building for "world" should not represent undue overhead 339Consequently, building for "world" should not represent undue overhead
@@ -363,15 +344,15 @@ in most cases.
363 If you set 344 If you set
364 SDK_EXT_TYPE 345 SDK_EXT_TYPE
365 to "minimal", then providing a shared state mirror is mandatory so 346 to "minimal", then providing a shared state mirror is mandatory so
366 that items can be installed as needed. See the " 347 that items can be installed as needed. See the
367 Providing Additional Installable Extensible SDK Content 348 :ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`
368 " section for more information. 349 section for more information.
369 350
370You can explicitly control whether or not to include the toolchain when 351You can explicitly control whether or not to include the toolchain when
371you build an SDK by setting the 352you build an SDK by setting the
372:term:`SDK_INCLUDE_TOOLCHAIN` 353:term:`SDK_INCLUDE_TOOLCHAIN`
373variable to "1". In particular, it is useful to include the toolchain 354variable to "1". In particular, it is useful to include the toolchain
374when you have set ``SDK_EXT_TYPE`` to "minimal", which by default, 355when you have set :term:`SDK_EXT_TYPE` to "minimal", which by default,
375excludes the toolchain. Also, it is helpful if you are building a small 356excludes the toolchain. Also, it is helpful if you are building a small
376SDK for use with an IDE or some other tool where you do not want to take 357SDK for use with an IDE or some other tool where you do not want to take
377extra steps to install a toolchain. 358extra steps to install a toolchain.
diff --git a/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst
index f158c244ab..a42cbc31bb 100644
--- a/documentation/sdk-manual/appendix-obtain.rst
+++ b/documentation/sdk-manual/appendix-obtain.rst
@@ -4,8 +4,22 @@
4Obtaining the SDK 4Obtaining the SDK
5***************** 5*****************
6 6
7Working with the SDK components directly in a Yocto build
8=========================================================
9
10Please refer to section
11":ref:`sdk-manual/extensible:Setting up the Extensible SDK environment directly in a Yocto build`"
12
13Note that to use this feature effectively either a powerful build
14machine, or a well-functioning sstate cache infrastructure is required:
15otherwise significant time could be spent waiting for components to be built
16by BitBake from source code.
17
18Working with standalone SDK Installers
19======================================
20
7Locating Pre-Built SDK Installers 21Locating Pre-Built SDK Installers
8================================= 22---------------------------------
9 23
10You can use existing, pre-built toolchains by locating and running an 24You can use existing, pre-built toolchains by locating and running an
11SDK installer script that ships with the Yocto Project. Using this 25SDK installer script that ships with the Yocto Project. Using this
@@ -14,39 +28,31 @@ and then run the script to hand-install the toolchain.
14 28
15Follow these steps to locate and hand-install the toolchain: 29Follow these steps to locate and hand-install the toolchain:
16 30
171. *Go to the Installers Directory:* Go to 31#. *Go to the Installers Directory:* Go to
18 :yocto_dl:`/releases/yocto/yocto-&DISTRO;/toolchain/` 32 :yocto_dl:`/releases/yocto/&DISTRO_REL_LATEST_TAG;/toolchain/`
19 33
202. *Open the Folder for Your Build Host:* Open the folder that matches 34#. *Open the Folder for Your Build Host:* Open the folder that matches
21 your :term:`Build Host` (i.e. 35 your :term:`Build Host` (i.e.
22 ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines). 36 ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines).
23 37
243. *Locate and Download the SDK Installer:* You need to find and 38#. *Locate and Download the SDK Installer:* You need to find and
25 download the installer appropriate for your build host, target 39 download the installer appropriate for your build host, target
26 hardware, and image type. 40 hardware, and image type.
27 41
28 The installer files (``*.sh``) follow this naming convention: 42 The installer files (``*.sh``) follow this naming convention:
29 :: 43 ``poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh``:
30 44
31 poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh 45 - ``host_system``: string representing your development system: ``i686`` or ``x86_64``
32 46
33 Where: 47 - ``type``: string representing the image: ``sato`` or ``minimal``
34 host_system is a string representing your development system:
35 "i686" or "x86_64"
36 48
37 type is a string representing the image: 49 - ``arch``: string representing the target architecture such as ``cortexa57-qemuarm64``
38 "sato" or "minimal"
39 50
40 arch is a string representing the target architecture: 51 - ``release``: version of the Yocto Project.
41 "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2",
42 "mips64", or "ppc7400"
43
44 release is the version of Yocto Project.
45
46 NOTE:
47 The standard SDK installer does not have the "-ext" string as
48 part of the filename.
49 52
53 .. note::
54 The standard SDK installer does not have the ``-ext`` string as
55 part of the filename.
50 56
51 The toolchains provided by the Yocto 57 The toolchains provided by the Yocto
52 Project are based off of the ``core-image-sato`` and 58 Project are based off of the ``core-image-sato`` and
@@ -54,39 +60,37 @@ Follow these steps to locate and hand-install the toolchain:
54 developing against those images. 60 developing against those images.
55 61
56 For example, if your build host is a 64-bit x86 system and you need 62 For example, if your build host is a 64-bit x86 system and you need
57 an extended SDK for a 64-bit core2 target, go into the ``x86_64`` 63 an extended SDK for a 64-bit core2 QEMU target, go into the ``x86_64``
58 folder and download the following installer: 64 folder and download the following installer::
59 ::
60 65
61 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 66 poky-glibc-x86_64-core-image-sato-core2-64-qemux86-64-toolchain-&DISTRO;.sh
62 67
634. *Run the Installer:* Be sure you have execution privileges and run 68#. *Run the Installer:* Be sure you have execution privileges and run
64 the installer. Following is an example from the ``Downloads`` 69 the installer. Here is an example from the ``Downloads``
65 directory: 70 directory::
66 ::
67 71
68 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 72 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-qemux86-64-toolchain-&DISTRO;.sh
69 73
70 During execution of the script, you choose the root location for the 74 During execution of the script, you choose the root location for the
71 toolchain. See the "`Installed Standard SDK Directory 75 toolchain. See the
72 Structure <#sdk-installed-standard-sdk-directory-structure>`__" 76 ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
73 section and the "`Installed Extensible SDK Directory 77 section and the
74 Structure <#sdk-installed-extensible-sdk-directory-structure>`__" 78 ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
75 section for more information. 79 section for more information.
76 80
77Building an SDK Installer 81Building an SDK Installer
78========================= 82-------------------------
79 83
80As an alternative to locating and downloading an SDK installer, you can 84As an alternative to locating and downloading an SDK installer, you can
81build the SDK installer. Follow these steps: 85build the SDK installer. Follow these steps:
82 86
831. *Set Up the Build Environment:* Be sure you are set up to use BitBake 87#. *Set Up the Build Environment:* Be sure you are set up to use BitBake
84 in a shell. See the ":ref:`dev-manual/start:preparing the build host`" section 88 in a shell. See the ":ref:`dev-manual/start:preparing the build host`" section
85 in the Yocto Project Development Tasks Manual for information on how 89 in the Yocto Project Development Tasks Manual for information on how
86 to get a build host ready that is either a native Linux machine or a 90 to get a build host ready that is either a native Linux machine or a
87 machine that uses CROPS. 91 machine that uses CROPS.
88 92
892. *Clone the ``poky`` Repository:* You need to have a local copy of the 93#. *Clone the ``poky`` Repository:* You need to have a local copy of the
90 Yocto Project :term:`Source Directory` 94 Yocto Project :term:`Source Directory`
91 (i.e. a local 95 (i.e. a local
92 ``poky`` repository). See the ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and 96 ``poky`` repository). See the ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and
@@ -96,56 +100,52 @@ build the SDK installer. Follow these steps:
96 how to clone the ``poky`` repository and check out the appropriate 100 how to clone the ``poky`` repository and check out the appropriate
97 branch for your work. 101 branch for your work.
98 102
993. *Initialize the Build Environment:* While in the root directory of 103#. *Initialize the Build Environment:* While in the root directory of
100 the Source Directory (i.e. ``poky``), run the 104 the Source Directory (i.e. ``poky``), run the
101 :ref:`structure-core-script` environment 105 :ref:`structure-core-script` environment
102 setup script to define the OpenEmbedded build environment on your 106 setup script to define the OpenEmbedded build environment on your
103 build host. 107 build host::
104 ::
105 108
106 $ source oe-init-build-env 109 $ source oe-init-build-env
107 110
108 Among other things, the script 111 Among other things, the script creates the :term:`Build Directory`, which
109 creates the :term:`Build Directory`, 112 is ``build`` in this case and is located in the Source Directory. After
110 which is 113 the script runs, your current working directory is set to the ``build``
111 ``build`` in this case and is located in the Source Directory. After 114 directory.
112 the script runs, your current working directory is set to the 115
113 ``build`` directory. 116#. *Make Sure You Are Building an Installer for the Correct Machine:*
114 117 Check to be sure that your :term:`MACHINE` variable in the ``local.conf``
1154. *Make Sure You Are Building an Installer for the Correct Machine:* 118 file in your :term:`Build Directory` matches the architecture
116 Check to be sure that your
117 :term:`MACHINE` variable in the
118 ``local.conf`` file in your Build Directory matches the architecture
119 for which you are building. 119 for which you are building.
120 120
1215. *Make Sure Your SDK Machine is Correctly Set:* If you are building a 121#. *Make Sure Your SDK Machine is Correctly Set:* If you are building a
122 toolchain designed to run on an architecture that differs from your 122 toolchain designed to run on an architecture that differs from your
123 current development host machine (i.e. the build host), be sure that 123 current development host machine (i.e. the build host), be sure that
124 the :term:`SDKMACHINE` variable 124 the :term:`SDKMACHINE` variable in the ``local.conf`` file in your
125 in the ``local.conf`` file in your Build Directory is correctly set. 125 :term:`Build Directory` is correctly set.
126 126
127 .. note:: 127 .. note::
128 128
129 If you are building an SDK installer for the Extensible SDK, the 129 If you are building an SDK installer for the Extensible SDK, the
130 SDKMACHINE 130 :term:`SDKMACHINE` value must be set for the architecture of the
131 value must be set for the architecture of the machine you are 131 machine you are using to build the installer. If :term:`SDKMACHINE`
132 using to build the installer. If
133 SDKMACHINE
134 is not set appropriately, the build fails and provides an error 132 is not set appropriately, the build fails and provides an error
135 message similar to the following: 133 message similar to the following::
136 ::
137 134
138 The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is 135 The extensible SDK can currently only be built for the same
139 set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64). 136 architecture as the machine being built on - SDK_ARCH
140 Unable to continue. 137 is set to i686 (likely via setting SDKMACHINE) which is
138 different from the architecture of the build machine (x86_64).
139 Unable to continue.
141 140
142 141
1436. *Build the SDK Installer:* To build the SDK installer for a standard 142#. *Build the SDK Installer:* To build the SDK installer for a standard
144 SDK and populate the SDK image, use the following command form. Be 143 SDK and populate the SDK image, use the following command form. Be
145 sure to replace image with an image (e.g. "core-image-sato"): $ 144 sure to replace ``image`` with an image (e.g. "core-image-sato")::
146 bitbake image -c populate_sdk You can do the same for the extensible 145
147 SDK using this command form: 146 $ bitbake image -c populate_sdk
148 :: 147
148 You can do the same for the extensible SDK using this command form::
149 149
150 $ bitbake image -c populate_sdk_ext 150 $ bitbake image -c populate_sdk_ext
151 151
@@ -153,7 +153,7 @@ build the SDK installer. Follow these steps:
153 that matches your target root filesystem. 153 that matches your target root filesystem.
154 154
155 When the ``bitbake`` command completes, the SDK installer will be in 155 When the ``bitbake`` command completes, the SDK installer will be in
156 ``tmp/deploy/sdk`` in the Build Directory. 156 ``tmp/deploy/sdk`` in the :term:`Build Directory`.
157 157
158 .. note:: 158 .. note::
159 159
@@ -165,22 +165,21 @@ build the SDK installer. Follow these steps:
165 variable inside your ``local.conf`` file before building the 165 variable inside your ``local.conf`` file before building the
166 SDK installer. Doing so ensures that the eventual SDK 166 SDK installer. Doing so ensures that the eventual SDK
167 installation process installs the appropriate library packages 167 installation process installs the appropriate library packages
168 as part of the SDK. Following is an example using ``libc`` 168 as part of the SDK. Here is an example using ``libc``
169 static development libraries: TOOLCHAIN_TARGET_TASK_append = " 169 static development libraries: TOOLCHAIN_TARGET_TASK:append = "
170 libc-staticdev" 170 libc-staticdev"
171 171
1727. *Run the Installer:* You can now run the SDK installer from 172#. *Run the Installer:* You can now run the SDK installer from
173 ``tmp/deploy/sdk`` in the Build Directory. Following is an example: 173 ``tmp/deploy/sdk`` in the :term:`Build Directory`. Here is an example::
174 ::
175 174
176 $ cd ~/poky/build/tmp/deploy/sdk 175 $ cd poky/build/tmp/deploy/sdk
177 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 176 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
178 177
179 During execution of the script, you choose the root location for the 178 During execution of the script, you choose the root location for the
180 toolchain. See the "`Installed Standard SDK Directory 179 toolchain. See the
181 Structure <#sdk-installed-standard-sdk-directory-structure>`__" 180 ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
182 section and the "`Installed Extensible SDK Directory 181 section and the
183 Structure <#sdk-installed-extensible-sdk-directory-structure>`__" 182 ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
184 section for more information. 183 section for more information.
185 184
186Extracting the Root Filesystem 185Extracting the Root Filesystem
@@ -198,11 +197,11 @@ separately extract a root filesystem:
198 197
199Follow these steps to extract the root filesystem: 198Follow these steps to extract the root filesystem:
200 199
2011. *Locate and Download the Tarball for the Pre-Built Root Filesystem 200#. *Locate and Download the Tarball for the Pre-Built Root Filesystem
202 Image File:* You need to find and download the root filesystem image 201 Image File:* You need to find and download the root filesystem image
203 file that is appropriate for your target system. These files are kept 202 file that is appropriate for your target system. These files are kept
204 in machine-specific folders in the 203 in machine-specific folders in the
205 :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>` 204 :yocto_dl:`Index of Releases </releases/yocto/&DISTRO_REL_LATEST_TAG;/machines/>`
206 in the "machines" directory. 205 in the "machines" directory.
207 206
208 The machine-specific folders of the "machines" directory contain 207 The machine-specific folders of the "machines" directory contain
@@ -210,22 +209,14 @@ Follow these steps to extract the root filesystem:
210 also contain flattened root filesystem image files (``*.ext4``), 209 also contain flattened root filesystem image files (``*.ext4``),
211 which you can use with QEMU directly. 210 which you can use with QEMU directly.
212 211
213 The pre-built root filesystem image files follow these naming 212 The pre-built root filesystem image files follow the
214 conventions: 213 ``core-image-profile-machine.tar.bz2`` naming convention:
215 ::
216 214
217 core-image-profile-arch.tar.bz2 215 - ``profile``: filesystem image's profile, such as ``minimal``,
216 ``minimal-dev`` or ``sato``. For information on these types of image
217 profiles, see the "Images" chapter in the Yocto Project Reference Manual.
218 218
219 Where: 219 - ``machine``: same string as the name of the parent download directory.
220 profile is the filesystem image's profile:
221 lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
222 sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
223 these types of image profiles, see the "Images" chapter in
224 the Yocto Project Reference Manual.
225
226 arch is a string representing the target architecture:
227 beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
228 genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
229 220
230 The root filesystems 221 The root filesystems
231 provided by the Yocto Project are based off of the 222 provided by the Yocto Project are based off of the
@@ -233,37 +224,34 @@ Follow these steps to extract the root filesystem:
233 224
234 For example, if you plan on using a BeagleBone device as your target 225 For example, if you plan on using a BeagleBone device as your target
235 hardware and your image is a ``core-image-sato-sdk`` image, you can 226 hardware and your image is a ``core-image-sato-sdk`` image, you can
236 download the following file: 227 download the following file::
237 ::
238 228
239 core-image-sato-sdk-beaglebone-yocto.tar.bz2 229 core-image-sato-sdk-beaglebone-yocto.tar.bz2
240 230
2412. *Initialize the Cross-Development Environment:* You must ``source`` 231#. *Initialize the Cross-Development Environment:* You must ``source``
242 the cross-development environment setup script to establish necessary 232 the cross-development environment setup script to establish necessary
243 environment variables. 233 environment variables.
244 234
245 This script is located in the top-level directory in which you 235 This script is located in the top-level directory in which you
246 installed the toolchain (e.g. ``poky_sdk``). 236 installed the toolchain (e.g. ``poky_sdk``).
247 237
248 Following is an example based on the toolchain installed in the 238 Here is an example based on the toolchain installed in the
249 ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section: 239 ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section::
250 ::
251 240
252 $ source ~/poky_sdk/environment-setup-core2-64-poky-linux 241 $ source poky_sdk/environment-setup-core2-64-poky-linux
253 242
2543. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk`` 243#. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk``
255 command and provide the root filesystem image. 244 command and provide the root filesystem image.
256 245
257 Following is an example command that extracts the root filesystem 246 Here is an example command that extracts the root filesystem
258 from a previously built root filesystem image that was downloaded 247 from a previously built root filesystem image that was downloaded
259 from the :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`. 248 from the :yocto_dl:`Index of Releases </releases/yocto/&DISTRO_REL_LATEST_TAG;/machines/>`.
260 This command extracts the root filesystem into the ``core2-64-sato`` 249 This command extracts the root filesystem into the ``core2-64-sato``
261 directory: 250 directory::
262 ::
263 251
264 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato 252 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
265 253
266 You could now point to the target sysroot at ``beablebone-sato``. 254 You could now point to the target sysroot at ``beaglebone-sato``.
267 255
268Installed Standard SDK Directory Structure 256Installed Standard SDK Directory Structure
269========================================== 257==========================================
@@ -273,8 +261,7 @@ install the Standard SDK by running the ``*.sh`` SDK installation
273script: 261script:
274 262
275.. image:: figures/sdk-installed-standard-sdk-directory.png 263.. image:: figures/sdk-installed-standard-sdk-directory.png
276 :scale: 80% 264 :scale: 100%
277 :align: center
278 265
279The installed SDK consists of an environment setup script for the SDK, a 266The installed SDK consists of an environment setup script for the SDK, a
280configuration file for the target, a version file for the target, and 267configuration file for the target, a version file for the target, and
diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst
index 5962e9460a..e5e9e4a03b 100644
--- a/documentation/sdk-manual/extensible.rst
+++ b/documentation/sdk-manual/extensible.rst
@@ -15,14 +15,14 @@ hardware, and ease integration into the rest of the
15.. note:: 15.. note::
16 16
17 For a side-by-side comparison of main features supported for an 17 For a side-by-side comparison of main features supported for an
18 extensible SDK as compared to a standard SDK, see the " 18 extensible SDK as compared to a standard SDK, see the
19 Introduction 19 :ref:`sdk-manual/intro:introduction` section.
20 " section.
21 20
22In addition to the functionality available through ``devtool``, you can 21In addition to the functionality available through ``devtool``, you can
23alternatively make use of the toolchain directly, for example from 22alternatively make use of the toolchain directly, for example from
24Makefile and Autotools. See the "`Using the SDK Toolchain 23Makefile and Autotools. See the
25Directly <#sdk-working-projects>`__" chapter for more information. 24":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter
25for more information.
26 26
27Why use the Extensible SDK and What is in It? 27Why use the Extensible SDK and What is in It?
28============================================= 28=============================================
@@ -41,13 +41,53 @@ functionality.
41Installing the Extensible SDK 41Installing the Extensible SDK
42============================= 42=============================
43 43
44Two ways to install the Extensible SDK
45--------------------------------------
46
47Extensible SDK can be installed in two different ways, and both have
48their own pros and cons:
49
50#. *Setting up the Extensible SDK environment directly in a Yocto build*. This
51 avoids having to produce, test, distribute and maintain separate SDK
52 installer archives, which can get very large. There is only one environment
53 for the regular Yocto build and the SDK and less code paths where things can
54 go not according to plan. It's easier to update the SDK: it simply means
55 updating the Yocto layers with git fetch or layer management tooling. The
56 SDK extensibility is better than in the second option: just run ``bitbake``
57 again to add more things to the sysroot, or add layers if even more things
58 are required.
59
60#. *Setting up the Extensible SDK from a standalone installer*. This has the
61 benefit of having a single, self-contained archive that includes all the
62 needed binary artifacts. So nothing needs to be rebuilt, and there is no
63 need to provide a well-functioning binary artefact cache over the network
64 for developers with underpowered laptops.
65
66.. _setting_up_ext_sdk_in_build:
67
68Setting up the Extensible SDK environment directly in a Yocto build
69-------------------------------------------------------------------
70
71#. Set up all the needed layers and a Yocto :term:`Build Directory`, e.g. a regular Yocto
72 build where ``bitbake`` can be executed.
73
74#. Run::
75
76 $ bitbake meta-ide-support
77 $ bitbake -c populate_sysroot gtk+3
78 # or any other target or native item that the application developer would need
79 $ bitbake build-sysroots -c build_native_sysroot && bitbake build-sysroots -c build_target_sysroot
80
81Setting up the Extensible SDK from a standalone installer
82---------------------------------------------------------
83
44The first thing you need to do is install the SDK on your :term:`Build 84The first thing you need to do is install the SDK on your :term:`Build
45Host` by running the ``*.sh`` installation script. 85Host` by running the ``*.sh`` installation script.
46 86
47You can download a tarball installer, which includes the pre-built 87You can download a tarball installer, which includes the pre-built
48toolchain, the ``runqemu`` script, the internal build system, 88toolchain, the ``runqemu`` script, the internal build system,
49``devtool``, and support files from the appropriate 89``devtool``, and support files from the appropriate
50:yocto_dl:`toolchain </releases/yocto/yocto-&DISTRO;/toolchain/>` directory within the Index of 90:yocto_dl:`toolchain </releases/yocto/&DISTRO_REL_LATEST_TAG;/toolchain/>` directory within the Index of
51Releases. Toolchains are available for several 32-bit and 64-bit 91Releases. Toolchains are available for several 32-bit and 64-bit
52architectures with the ``x86_64`` directories, respectively. The 92architectures with the ``x86_64`` directories, respectively. The
53toolchains the Yocto Project provides are based off the 93toolchains the Yocto Project provides are based off the
@@ -58,8 +98,7 @@ The names of the tarball installer scripts are such that a string
58representing the host system appears first in the filename and then is 98representing the host system appears first in the filename and then is
59immediately followed by a string representing the target architecture. 99immediately followed by a string representing the target architecture.
60An extensible SDK has the string "-ext" as part of the name. Following 100An extensible SDK has the string "-ext" as part of the name. Following
61is the general form: 101is the general form::
62::
63 102
64 poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh 103 poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh
65 104
@@ -82,17 +121,16 @@ is the general form:
82 121
83For example, the following SDK installer is for a 64-bit 122For example, the following SDK installer is for a 64-bit
84development host system and a i586-tuned target architecture based off 123development host system and a i586-tuned target architecture based off
85the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot: 124the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot::
86::
87 125
88 poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh 126 poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh
89 127
90.. note:: 128.. note::
91 129
92 As an alternative to downloading an SDK, you can build the SDK 130 As an alternative to downloading an SDK, you can build the SDK
93 installer. For information on building the installer, see the " 131 installer. For information on building the installer, see the
94 Building an SDK Installer 132 :ref:`sdk-manual/appendix-obtain:building an sdk installer`
95 " section. 133 section.
96 134
97The SDK and toolchains are self-contained and by default are installed 135The SDK and toolchains are self-contained and by default are installed
98into the ``poky_sdk`` folder in your home directory. You can choose to 136into the ``poky_sdk`` folder in your home directory. You can choose to
@@ -104,21 +142,12 @@ must be writable for whichever users need to use the SDK.
104The following command shows how to run the installer given a toolchain 142The following command shows how to run the installer given a toolchain
105tarball for a 64-bit x86 development host system and a 64-bit x86 target 143tarball for a 64-bit x86 development host system and a 64-bit x86 target
106architecture. The example assumes the SDK installer is located in 144architecture. The example assumes the SDK installer is located in
107``~/Downloads/`` and has execution rights. 145``~/Downloads/`` and has execution rights::
108
109.. note::
110
111 If you do not have write permissions for the directory into which you
112 are installing the SDK, the installer notifies you and exits. For
113 that case, set up the proper permissions in the directory and run the
114 installer again.
115
116::
117 146
118 $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh 147 $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
119 Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5 148 Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5
120 ========================================================================== 149 ==========================================================================
121 Enter target directory for SDK (default: ~/poky_sdk): 150 Enter target directory for SDK (default: poky_sdk):
122 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y 151 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
123 Extracting SDK..............done 152 Extracting SDK..............done
124 Setting it up... 153 Setting it up...
@@ -134,11 +163,25 @@ architecture. The example assumes the SDK installer is located in
134 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. 163 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
135 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux 164 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
136 165
166.. note::
167
168 If you do not have write permissions for the directory into which you
169 are installing the SDK, the installer notifies you and exits. For
170 that case, set up the proper permissions in the directory and run the
171 installer again.
172
173.. _running_the_ext_sdk_env:
174
137Running the Extensible SDK Environment Setup Script 175Running the Extensible SDK Environment Setup Script
138=================================================== 176===================================================
139 177
140Once you have the SDK installed, you must run the SDK environment setup 178Once you have the SDK installed, you must run the SDK environment setup
141script before you can actually use the SDK. This setup script resides in 179script before you can actually use the SDK.
180
181When using an SDK directly in a Yocto build, you will find the script in
182``tmp/deploy/images/qemux86-64/`` in your :term:`Build Directory`.
183
184When using a standalone SDK installer, this setup script resides in
142the directory you chose when you installed the SDK, which is either the 185the directory you chose when you installed the SDK, which is either the
143default ``poky_sdk`` directory or the directory you chose during 186default ``poky_sdk`` directory or the directory you chose during
144installation. 187installation.
@@ -149,21 +192,25 @@ begin with the string "``environment-setup``" and include as part of
149their name the tuned target architecture. As an example, the following 192their name the tuned target architecture. As an example, the following
150commands set the working directory to where the SDK was installed and 193commands set the working directory to where the SDK was installed and
151then source the environment setup script. In this example, the setup 194then source the environment setup script. In this example, the setup
152script is for an IA-based target machine using i586 tuning: 195script is for an IA-based target machine using i586 tuning::
153::
154 196
155 $ cd /home/scottrif/poky_sdk 197 $ cd /home/scottrif/poky_sdk
156 $ source environment-setup-core2-64-poky-linux 198 $ source environment-setup-core2-64-poky-linux
157 SDK environment now set up; additionally you may now run devtool to perform development tasks. 199 SDK environment now set up; additionally you may now run devtool to perform development tasks.
158 Run devtool --help for further details. 200 Run devtool --help for further details.
159 201
160Running the setup script defines many environment variables needed in 202When using the environment script directly in a Yocto build, it can
161order to use the SDK (e.g. ``PATH``, 203be run similarly::
162:term:`CC`, 204
163:term:`LD`, and so forth). If you want to 205 $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
164see all the environment variables the script exports, examine the 206
207Running the setup script defines many environment variables needed in order to
208use the SDK (e.g. ``PATH``, :term:`CC`, :term:`LD`, and so forth). If you want
209to see all the environment variables the script exports, examine the
165installation file itself. 210installation file itself.
166 211
212.. _using_devtool:
213
167Using ``devtool`` in Your SDK Workflow 214Using ``devtool`` in Your SDK Workflow
168====================================== 215======================================
169 216
@@ -175,11 +222,8 @@ system.
175 222
176.. note:: 223.. note::
177 224
178 The use of 225 The use of ``devtool`` is not limited to the extensible SDK. You can use
179 devtool 226 ``devtool`` to help you easily develop any project whose build output must be
180 is not limited to the extensible SDK. You can use
181 devtool
182 to help you easily develop any project whose build output must be
183 part of an image built using the build system. 227 part of an image built using the build system.
184 228
185The ``devtool`` command line is organized similarly to 229The ``devtool`` command line is organized similarly to
@@ -189,21 +233,18 @@ all the commands.
189 233
190.. note:: 234.. note::
191 235
192 See the " 236 See the ":doc:`/ref-manual/devtool-reference`"
193 devtool 237 section in the Yocto Project Reference Manual.
194  Quick Reference
195 " in the Yocto Project Reference Manual for a
196 devtool
197 quick reference.
198 238
199Three ``devtool`` subcommands exist that provide entry-points into 239``devtool`` subcommands provide entry-points into development:
200development:
201 240
202- *devtool add*: Assists in adding new software to be built. 241- *devtool add*: Assists in adding new software to be built.
203 242
204- *devtool modify*: Sets up an environment to enable you to modify 243- *devtool modify*: Sets up an environment to enable you to modify
205 the source of an existing component. 244 the source of an existing component.
206 245
246- *devtool ide-sdk*: Generates a configuration for an IDE.
247
207- *devtool upgrade*: Updates an existing recipe so that you can 248- *devtool upgrade*: Updates an existing recipe so that you can
208 build it for an updated set of source files. 249 build it for an updated set of source files.
209 250
@@ -216,1014 +257,9 @@ the recipe a source tree that is under your control is used in order to
216allow you to make changes to the source as desired. By default, new 257allow you to make changes to the source as desired. By default, new
217recipes and the source go into a "workspace" directory under the SDK. 258recipes and the source go into a "workspace" directory under the SDK.
218 259
219The remainder of this section presents the ``devtool add``, 260To learn how to use ``devtool`` to add, modify, upgrade recipes and more, see
220``devtool modify``, and ``devtool upgrade`` workflows. 261the :ref:`dev-manual/devtool:Using the \`\`devtool\`\` command-line tool`
221 262section of the Yocto Project Development Tasks Manual.
222Use ``devtool add`` to Add an Application
223-----------------------------------------
224
225The ``devtool add`` command generates a new recipe based on existing
226source code. This command takes advantage of the
227:ref:`devtool-the-workspace-layer-structure`
228layer that many ``devtool`` commands use. The command is flexible enough
229to allow you to extract source code into both the workspace or a
230separate local Git repository and to use existing code that does not
231need to be extracted.
232
233Depending on your particular scenario, the arguments and options you use
234with ``devtool add`` form different combinations. The following diagram
235shows common development flows you would use with the ``devtool add``
236command:
237
238.. image:: figures/sdk-devtool-add-flow.png
239 :align: center
240
2411. *Generating the New Recipe*: The top part of the flow shows three
242 scenarios by which you could use ``devtool add`` to generate a recipe
243 based on existing source code.
244
245 In a shared development environment, it is typical for other
246 developers to be responsible for various areas of source code. As a
247 developer, you are probably interested in using that source code as
248 part of your development within the Yocto Project. All you need is
249 access to the code, a recipe, and a controlled area in which to do
250 your work.
251
252 Within the diagram, three possible scenarios feed into the
253 ``devtool add`` workflow:
254
255 - *Left*: The left scenario in the figure represents a common
256 situation where the source code does not exist locally and needs
257 to be extracted. In this situation, the source code is extracted
258 to the default workspace - you do not want the files in some
259 specific location outside of the workspace. Thus, everything you
260 need will be located in the workspace:
261 ::
262
263 $ devtool add recipe fetchuri
264
265 With this command, ``devtool`` extracts the upstream
266 source files into a local Git repository within the ``sources``
267 folder. The command then creates a recipe named recipe and a
268 corresponding append file in the workspace. If you do not provide
269 recipe, the command makes an attempt to determine the recipe name.
270
271 - *Middle*: The middle scenario in the figure also represents a
272 situation where the source code does not exist locally. In this
273 case, the code is again upstream and needs to be extracted to some
274 local area - this time outside of the default workspace.
275
276 .. note::
277
278 If required,
279 devtool
280 always creates a Git repository locally during the extraction.
281
282 Furthermore, the first positional argument srctree in this case
283 identifies where the ``devtool add`` command will locate the
284 extracted code outside of the workspace. You need to specify an
285 empty directory:
286 ::
287
288 $ devtool add recipe srctree fetchuri
289
290 In summary,
291 the source code is pulled from fetchuri and extracted into the
292 location defined by srctree as a local Git repository.
293
294 Within workspace, ``devtool`` creates a recipe named recipe along
295 with an associated append file.
296
297 - *Right*: The right scenario in the figure represents a situation
298 where the srctree has been previously prepared outside of the
299 ``devtool`` workspace.
300
301 The following command provides a new recipe name and identifies
302 the existing source tree location:
303 ::
304
305 $ devtool add recipe srctree
306
307 The command examines the source code and creates a recipe named
308 recipe for the code and places the recipe into the workspace.
309
310 Because the extracted source code already exists, ``devtool`` does
311 not try to relocate the source code into the workspace - only the
312 new recipe is placed in the workspace.
313
314 Aside from a recipe folder, the command also creates an associated
315 append folder and places an initial ``*.bbappend`` file within.
316
3172. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the
318 editor as defined by the ``$EDITOR`` environment variable and modify
319 the file:
320 ::
321
322 $ devtool edit-recipe recipe
323
324 From within the editor, you
325 can make modifications to the recipe that take affect when you build
326 it later.
327
3283. *Build the Recipe or Rebuild the Image*: The next step you take
329 depends on what you are going to do with the new code.
330
331 If you need to eventually move the build output to the target
332 hardware, use the following ``devtool`` command:
333 :;
334
335 $ devtool build recipe
336
337 On the other hand, if you want an image to contain the recipe's
338 packages from the workspace for immediate deployment onto a device
339 (e.g. for testing purposes), you can use the ``devtool build-image``
340 command:
341 ::
342
343 $ devtool build-image image
344
3454. *Deploy the Build Output*: When you use the ``devtool build`` command
346 to build out your recipe, you probably want to see if the resulting
347 build output works as expected on the target hardware.
348
349 .. note::
350
351 This step assumes you have a previously built image that is
352 already either running in QEMU or is running on actual hardware.
353 Also, it is assumed that for deployment of the image to the
354 target, SSH is installed in the image and, if the image is running
355 on real hardware, you have network access to and from your
356 development machine.
357
358 You can deploy your build output to that target hardware by using the
359 ``devtool deploy-target`` command: $ devtool deploy-target recipe
360 target The target is a live target machine running as an SSH server.
361
362 You can, of course, also deploy the image you build to actual
363 hardware by using the ``devtool build-image`` command. However,
364 ``devtool`` does not provide a specific command that allows you to
365 deploy the image to actual hardware.
366
3675. *Finish Your Work With the Recipe*: The ``devtool finish`` command
368 creates any patches corresponding to commits in the local Git
369 repository, moves the new recipe to a more permanent layer, and then
370 resets the recipe so that the recipe is built normally rather than
371 from the workspace.
372 ::
373
374 $ devtool finish recipe layer
375
376 .. note::
377
378 Any changes you want to turn into patches must be committed to the
379 Git repository in the source tree.
380
381 As mentioned, the ``devtool finish`` command moves the final recipe
382 to its permanent layer.
383
384 As a final process of the ``devtool finish`` command, the state of
385 the standard layers and the upstream source is restored so that you
386 can build the recipe from those areas rather than the workspace.
387
388 .. note::
389
390 You can use the
391 devtool reset
392 command to put things back should you decide you do not want to
393 proceed with your work. If you do use this command, realize that
394 the source tree is preserved.
395
396Use ``devtool modify`` to Modify the Source of an Existing Component
397--------------------------------------------------------------------
398
399The ``devtool modify`` command prepares the way to work on existing code
400that already has a local recipe in place that is used to build the
401software. The command is flexible enough to allow you to extract code
402from an upstream source, specify the existing recipe, and keep track of
403and gather any patch files from other developers that are associated
404with the code.
405
406Depending on your particular scenario, the arguments and options you use
407with ``devtool modify`` form different combinations. The following
408diagram shows common development flows for the ``devtool modify``
409command:
410
411.. image:: figures/sdk-devtool-modify-flow.png
412 :align: center
413
4141. *Preparing to Modify the Code*: The top part of the flow shows three
415 scenarios by which you could use ``devtool modify`` to prepare to
416 work on source files. Each scenario assumes the following:
417
418 - The recipe exists locally in a layer external to the ``devtool``
419 workspace.
420
421 - The source files exist either upstream in an un-extracted state or
422 locally in a previously extracted state.
423
424 The typical situation is where another developer has created a layer
425 for use with the Yocto Project and their recipe already resides in
426 that layer. Furthermore, their source code is readily available
427 either upstream or locally.
428
429 - *Left*: The left scenario in the figure represents a common
430 situation where the source code does not exist locally and it
431 needs to be extracted from an upstream source. In this situation,
432 the source is extracted into the default ``devtool`` workspace
433 location. The recipe, in this scenario, is in its own layer
434 outside the workspace (i.e. ``meta-``\ layername).
435
436 The following command identifies the recipe and, by default,
437 extracts the source files:
438 ::
439
440 $ devtool modify recipe
441
442 Once
443 ``devtool``\ locates the recipe, ``devtool`` uses the recipe's
444 :term:`SRC_URI` statements to
445 locate the source code and any local patch files from other
446 developers.
447
448 With this scenario, no srctree argument exists. Consequently, the
449 default behavior of the ``devtool modify`` command is to extract
450 the source files pointed to by the ``SRC_URI`` statements into a
451 local Git structure. Furthermore, the location for the extracted
452 source is the default area within the ``devtool`` workspace. The
453 result is that the command sets up both the source code and an
454 append file within the workspace while the recipe remains in its
455 original location.
456
457 Additionally, if you have any non-patch local files (i.e. files
458 referred to with ``file://`` entries in ``SRC_URI`` statement
459 excluding ``*.patch/`` or ``*.diff``), these files are copied to
460 an ``oe-local-files`` folder under the newly created source tree.
461 Copying the files here gives you a convenient area from which you
462 can modify the files. Any changes or additions you make to those
463 files are incorporated into the build the next time you build the
464 software just as are other changes you might have made to the
465 source.
466
467 - *Middle*: The middle scenario in the figure represents a situation
468 where the source code also does not exist locally. In this case,
469 the code is again upstream and needs to be extracted to some local
470 area as a Git repository. The recipe, in this scenario, is again
471 local and in its own layer outside the workspace.
472
473 The following command tells ``devtool`` the recipe with which to
474 work and, in this case, identifies a local area for the extracted
475 source files that exists outside of the default ``devtool``
476 workspace:
477 ::
478
479 $ devtool modify recipe srctree
480
481 .. note::
482
483 You cannot provide a URL for
484 srctree
485 using the
486 devtool
487 command.
488
489 As with all extractions, the command uses the recipe's ``SRC_URI``
490 statements to locate the source files and any associated patch
491 files. Non-patch files are copied to an ``oe-local-files`` folder
492 under the newly created source tree.
493
494 Once the files are located, the command by default extracts them
495 into srctree.
496
497 Within workspace, ``devtool`` creates an append file for the
498 recipe. The recipe remains in its original location but the source
499 files are extracted to the location you provide with srctree.
500
501 - *Right*: The right scenario in the figure represents a situation
502 where the source tree (srctree) already exists locally as a
503 previously extracted Git structure outside of the ``devtool``
504 workspace. In this example, the recipe also exists elsewhere
505 locally in its own layer.
506
507 The following command tells ``devtool`` the recipe with which to
508 work, uses the "-n" option to indicate source does not need to be
509 extracted, and uses srctree to point to the previously extracted
510 source files:
511 ::
512
513 $ devtool modify -n recipe srctree
514
515 If an ``oe-local-files`` subdirectory happens to exist and it
516 contains non-patch files, the files are used. However, if the
517 subdirectory does not exist and you run the ``devtool finish``
518 command, any non-patch files that might exist next to the recipe
519 are removed because it appears to ``devtool`` that you have
520 deleted those files.
521
522 Once the ``devtool modify`` command finishes, it creates only an
523 append file for the recipe in the ``devtool`` workspace. The
524 recipe and the source code remain in their original locations.
525
5262. *Edit the Source*: Once you have used the ``devtool modify`` command,
527 you are free to make changes to the source files. You can use any
528 editor you like to make and save your source code modifications.
529
5303. *Build the Recipe or Rebuild the Image*: The next step you take
531 depends on what you are going to do with the new code.
532
533 If you need to eventually move the build output to the target
534 hardware, use the following ``devtool`` command:
535 ::
536
537 $ devtool build recipe
538
539 On the other hand, if you want an image to contain the recipe's
540 packages from the workspace for immediate deployment onto a device
541 (e.g. for testing purposes), you can use the ``devtool build-image``
542 command: $ devtool build-image image
543
5444. *Deploy the Build Output*: When you use the ``devtool build`` command
545 to build out your recipe, you probably want to see if the resulting
546 build output works as expected on target hardware.
547
548 .. note::
549
550 This step assumes you have a previously built image that is
551 already either running in QEMU or running on actual hardware.
552 Also, it is assumed that for deployment of the image to the
553 target, SSH is installed in the image and if the image is running
554 on real hardware that you have network access to and from your
555 development machine.
556
557 You can deploy your build output to that target hardware by using the
558 ``devtool deploy-target`` command:
559 ::
560
561 $ devtool deploy-target recipe target
562
563 The target is a live target machine running as an SSH server.
564
565 You can, of course, use other methods to deploy the image you built
566 using the ``devtool build-image`` command to actual hardware.
567 ``devtool`` does not provide a specific command to deploy the image
568 to actual hardware.
569
5705. *Finish Your Work With the Recipe*: The ``devtool finish`` command
571 creates any patches corresponding to commits in the local Git
572 repository, updates the recipe to point to them (or creates a
573 ``.bbappend`` file to do so, depending on the specified destination
574 layer), and then resets the recipe so that the recipe is built
575 normally rather than from the workspace.
576 ::
577
578 $ devtool finish recipe layer
579
580 .. note::
581
582 Any changes you want to turn into patches must be staged and
583 committed within the local Git repository before you use the
584 devtool finish
585 command.
586
587 Because there is no need to move the recipe, ``devtool finish``
588 either updates the original recipe in the original layer or the
589 command creates a ``.bbappend`` file in a different layer as provided
590 by layer. Any work you did in the ``oe-local-files`` directory is
591 preserved in the original files next to the recipe during the
592 ``devtool finish`` command.
593
594 As a final process of the ``devtool finish`` command, the state of
595 the standard layers and the upstream source is restored so that you
596 can build the recipe from those areas rather than from the workspace.
597
598 .. note::
599
600 You can use the
601 devtool reset
602 command to put things back should you decide you do not want to
603 proceed with your work. If you do use this command, realize that
604 the source tree is preserved.
605
606Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software
607-------------------------------------------------------------------------------------------------------
608
609The ``devtool upgrade`` command upgrades an existing recipe to that of a
610more up-to-date version found upstream. Throughout the life of software,
611recipes continually undergo version upgrades by their upstream
612publishers. You can use the ``devtool upgrade`` workflow to make sure
613your recipes you are using for builds are up-to-date with their upstream
614counterparts.
615
616.. note::
617
618 Several methods exist by which you can upgrade recipes -
619 devtool upgrade
620 happens to be one. You can read about all the methods by which you
621 can upgrade recipes in the "
622 Upgrading Recipes
623 " section of the Yocto Project Development Tasks Manual.
624
625The ``devtool upgrade`` command is flexible enough to allow you to
626specify source code revision and versioning schemes, extract code into
627or out of the ``devtool``
628:ref:`devtool-the-workspace-layer-structure`,
629and work with any source file forms that the
630:ref:`fetchers <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` support.
631
632The following diagram shows the common development flow used with the
633``devtool upgrade`` command:
634
635.. image:: figures/sdk-devtool-upgrade-flow.png
636 :align: center
637
6381. *Initiate the Upgrade*: The top part of the flow shows the typical
639 scenario by which you use the ``devtool upgrade`` command. The
640 following conditions exist:
641
642 - The recipe exists in a local layer external to the ``devtool``
643 workspace.
644
645 - The source files for the new release exist in the same location
646 pointed to by :term:`SRC_URI`
647 in the recipe (e.g. a tarball with the new version number in the
648 name, or as a different revision in the upstream Git repository).
649
650 A common situation is where third-party software has undergone a
651 revision so that it has been upgraded. The recipe you have access to
652 is likely in your own layer. Thus, you need to upgrade the recipe to
653 use the newer version of the software:
654 ::
655
656 $ devtool upgrade -V version recipe
657
658 By default, the ``devtool upgrade`` command extracts source
659 code into the ``sources`` directory in the
660 :ref:`devtool-the-workspace-layer-structure`.
661 If you want the code extracted to any other location, you need to
662 provide the srctree positional argument with the command as follows:
663 $ devtool upgrade -V version recipe srctree
664
665 .. note::
666
667 In this example, the "-V" option specifies the new version. If you
668 don't use "-V", the command upgrades the recipe to the latest
669 version.
670
671 If the source files pointed to by the ``SRC_URI`` statement in the
672 recipe are in a Git repository, you must provide the "-S" option and
673 specify a revision for the software.
674
675 Once ``devtool`` locates the recipe, it uses the ``SRC_URI`` variable
676 to locate the source code and any local patch files from other
677 developers. The result is that the command sets up the source code,
678 the new version of the recipe, and an append file all within the
679 workspace.
680
681 Additionally, if you have any non-patch local files (i.e. files
682 referred to with ``file://`` entries in ``SRC_URI`` statement
683 excluding ``*.patch/`` or ``*.diff``), these files are copied to an
684 ``oe-local-files`` folder under the newly created source tree.
685 Copying the files here gives you a convenient area from which you can
686 modify the files. Any changes or additions you make to those files
687 are incorporated into the build the next time you build the software
688 just as are other changes you might have made to the source.
689
6902. *Resolve any Conflicts created by the Upgrade*: Conflicts could exist
691 due to the software being upgraded to a new version. Conflicts occur
692 if your recipe specifies some patch files in ``SRC_URI`` that
693 conflict with changes made in the new version of the software. For
694 such cases, you need to resolve the conflicts by editing the source
695 and following the normal ``git rebase`` conflict resolution process.
696
697 Before moving onto the next step, be sure to resolve any such
698 conflicts created through use of a newer or different version of the
699 software.
700
7013. *Build the Recipe or Rebuild the Image*: The next step you take
702 depends on what you are going to do with the new code.
703
704 If you need to eventually move the build output to the target
705 hardware, use the following ``devtool`` command:
706 ::
707
708 $ devtool build recipe
709
710 On the other hand, if you want an image to contain the recipe's
711 packages from the workspace for immediate deployment onto a device
712 (e.g. for testing purposes), you can use the ``devtool build-image``
713 command:
714 ::
715
716 $ devtool build-image image
717
7184. *Deploy the Build Output*: When you use the ``devtool build`` command
719 or ``bitbake`` to build your recipe, you probably want to see if the
720 resulting build output works as expected on target hardware.
721
722 .. note::
723
724 This step assumes you have a previously built image that is
725 already either running in QEMU or running on actual hardware.
726 Also, it is assumed that for deployment of the image to the
727 target, SSH is installed in the image and if the image is running
728 on real hardware that you have network access to and from your
729 development machine.
730
731 You can deploy your build output to that target hardware by using the
732 ``devtool deploy-target`` command: $ devtool deploy-target recipe
733 target The target is a live target machine running as an SSH server.
734
735 You can, of course, also deploy the image you build using the
736 ``devtool build-image`` command to actual hardware. However,
737 ``devtool`` does not provide a specific command that allows you to do
738 this.
739
7405. *Finish Your Work With the Recipe*: The ``devtool finish`` command
741 creates any patches corresponding to commits in the local Git
742 repository, moves the new recipe to a more permanent layer, and then
743 resets the recipe so that the recipe is built normally rather than
744 from the workspace.
745
746 Any work you did in the ``oe-local-files`` directory is preserved in
747 the original files next to the recipe during the ``devtool finish``
748 command.
749
750 If you specify a destination layer that is the same as the original
751 source, then the old version of the recipe and associated files are
752 removed prior to adding the new version.
753 ::
754
755 $ devtool finish recipe layer
756
757 .. note::
758
759 Any changes you want to turn into patches must be committed to the
760 Git repository in the source tree.
761
762 As a final process of the ``devtool finish`` command, the state of
763 the standard layers and the upstream source is restored so that you
764 can build the recipe from those areas rather than the workspace.
765
766 .. note::
767
768 You can use the
769 devtool reset
770 command to put things back should you decide you do not want to
771 proceed with your work. If you do use this command, realize that
772 the source tree is preserved.
773
774A Closer Look at ``devtool add``
775================================
776
777The ``devtool add`` command automatically creates a recipe based on the
778source tree you provide with the command. Currently, the command has
779support for the following:
780
781- Autotools (``autoconf`` and ``automake``)
782
783- CMake
784
785- Scons
786
787- ``qmake``
788
789- Plain ``Makefile``
790
791- Out-of-tree kernel module
792
793- Binary package (i.e. "-b" option)
794
795- Node.js module
796
797- Python modules that use ``setuptools`` or ``distutils``
798
799Apart from binary packages, the determination of how a source tree
800should be treated is automatic based on the files present within that
801source tree. For example, if a ``CMakeLists.txt`` file is found, then
802the source tree is assumed to be using CMake and is treated accordingly.
803
804.. note::
805
806 In most cases, you need to edit the automatically generated recipe in
807 order to make it build properly. Typically, you would go through
808 several edit and build cycles until the recipe successfully builds.
809 Once the recipe builds, you could use possible further iterations to
810 test the recipe on the target device.
811
812The remainder of this section covers specifics regarding how parts of
813the recipe are generated.
814
815Name and Version
816----------------
817
818If you do not specify a name and version on the command line,
819``devtool add`` uses various metadata within the source tree in an
820attempt to determine the name and version of the software being built.
821Based on what the tool determines, ``devtool`` sets the name of the
822created recipe file accordingly.
823
824If ``devtool`` cannot determine the name and version, the command prints
825an error. For such cases, you must re-run the command and provide the
826name and version, just the name, or just the version as part of the
827command line.
828
829Sometimes the name or version determined from the source tree might be
830incorrect. For such a case, you must reset the recipe:
831::
832
833 $ devtool reset -n recipename
834
835After running the ``devtool reset`` command, you need to
836run ``devtool add`` again and provide the name or the version.
837
838Dependency Detection and Mapping
839--------------------------------
840
841The ``devtool add`` command attempts to detect build-time dependencies
842and map them to other recipes in the system. During this mapping, the
843command fills in the names of those recipes as part of the
844:term:`DEPENDS` variable within the
845recipe. If a dependency cannot be mapped, ``devtool`` places a comment
846in the recipe indicating such. The inability to map a dependency can
847result from naming not being recognized or because the dependency simply
848is not available. For cases where the dependency is not available, you
849must use the ``devtool add`` command to add an additional recipe that
850satisfies the dependency. Once you add that recipe, you need to update
851the ``DEPENDS`` variable in the original recipe to include the new
852recipe.
853
854If you need to add runtime dependencies, you can do so by adding the
855following to your recipe:
856::
857
858 RDEPENDS_${PN} += "dependency1 dependency2 ..."
859
860.. note::
861
862 The
863 devtool add
864 command often cannot distinguish between mandatory and optional
865 dependencies. Consequently, some of the detected dependencies might
866 in fact be optional. When in doubt, consult the documentation or the
867 configure script for the software the recipe is building for further
868 details. In some cases, you might find you can substitute the
869 dependency with an option that disables the associated functionality
870 passed to the configure script.
871
872License Detection
873-----------------
874
875The ``devtool add`` command attempts to determine if the software you
876are adding is able to be distributed under a common, open-source
877license. If so, the command sets the
878:term:`LICENSE` value accordingly.
879You should double-check the value added by the command against the
880documentation or source files for the software you are building and, if
881necessary, update that ``LICENSE`` value.
882
883The ``devtool add`` command also sets the
884:term:`LIC_FILES_CHKSUM`
885value to point to all files that appear to be license-related. Realize
886that license statements often appear in comments at the top of source
887files or within the documentation. In such cases, the command does not
888recognize those license statements. Consequently, you might need to
889amend the ``LIC_FILES_CHKSUM`` variable to point to one or more of those
890comments if present. Setting ``LIC_FILES_CHKSUM`` is particularly
891important for third-party software. The mechanism attempts to ensure
892correct licensing should you upgrade the recipe to a newer upstream
893version in future. Any change in licensing is detected and you receive
894an error prompting you to check the license text again.
895
896If the ``devtool add`` command cannot determine licensing information,
897``devtool`` sets the ``LICENSE`` value to "CLOSED" and leaves the
898``LIC_FILES_CHKSUM`` value unset. This behavior allows you to continue
899with development even though the settings are unlikely to be correct in
900all cases. You should check the documentation or source files for the
901software you are building to determine the actual license.
902
903Adding Makefile-Only Software
904-----------------------------
905
906The use of Make by itself is very common in both proprietary and
907open-source software. Unfortunately, Makefiles are often not written
908with cross-compilation in mind. Thus, ``devtool add`` often cannot do
909very much to ensure that these Makefiles build correctly. It is very
910common, for example, to explicitly call ``gcc`` instead of using the
911:term:`CC` variable. Usually, in a
912cross-compilation environment, ``gcc`` is the compiler for the build
913host and the cross-compiler is named something similar to
914``arm-poky-linux-gnueabi-gcc`` and might require arguments (e.g. to
915point to the associated sysroot for the target machine).
916
917When writing a recipe for Makefile-only software, keep the following in
918mind:
919
920- You probably need to patch the Makefile to use variables instead of
921 hardcoding tools within the toolchain such as ``gcc`` and ``g++``.
922
923- The environment in which Make runs is set up with various standard
924 variables for compilation (e.g. ``CC``, ``CXX``, and so forth) in a
925 similar manner to the environment set up by the SDK's environment
926 setup script. One easy way to see these variables is to run the
927 ``devtool build`` command on the recipe and then look in
928 ``oe-logs/run.do_compile``. Towards the top of this file, a list of
929 environment variables exists that are being set. You can take
930 advantage of these variables within the Makefile.
931
932- If the Makefile sets a default for a variable using "=", that default
933 overrides the value set in the environment, which is usually not
934 desirable. For this case, you can either patch the Makefile so it
935 sets the default using the "?=" operator, or you can alternatively
936 force the value on the ``make`` command line. To force the value on
937 the command line, add the variable setting to
938 :term:`EXTRA_OEMAKE` or
939 :term:`PACKAGECONFIG_CONFARGS`
940 within the recipe. Here is an example using ``EXTRA_OEMAKE``:
941 ::
942
943 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
944
945 In the above example,
946 single quotes are used around the variable settings as the values are
947 likely to contain spaces because required default options are passed
948 to the compiler.
949
950- Hardcoding paths inside Makefiles is often problematic in a
951 cross-compilation environment. This is particularly true because
952 those hardcoded paths often point to locations on the build host and
953 thus will either be read-only or will introduce contamination into
954 the cross-compilation because they are specific to the build host
955 rather than the target. Patching the Makefile to use prefix variables
956 or other path variables is usually the way to handle this situation.
957
958- Sometimes a Makefile runs target-specific commands such as
959 ``ldconfig``. For such cases, you might be able to apply patches that
960 remove these commands from the Makefile.
961
962Adding Native Tools
963-------------------
964
965Often, you need to build additional tools that run on the :term:`Build
966Host` as opposed to
967the target. You should indicate this requirement by using one of the
968following methods when you run ``devtool add``:
969
970- Specify the name of the recipe such that it ends with "-native".
971 Specifying the name like this produces a recipe that only builds for
972 the build host.
973
974- Specify the "DASHDASHalso-native" option with the ``devtool add``
975 command. Specifying this option creates a recipe file that still
976 builds for the target but also creates a variant with a "-native"
977 suffix that builds for the build host.
978
979.. note::
980
981 If you need to add a tool that is shipped as part of a source tree
982 that builds code for the target, you can typically accomplish this by
983 building the native and target parts separately rather than within
984 the same compilation process. Realize though that with the
985 "DASHDASHalso-native" option, you can add the tool using just one
986 recipe file.
987
988Adding Node.js Modules
989----------------------
990
991You can use the ``devtool add`` command two different ways to add
992Node.js modules: 1) Through ``npm`` and, 2) from a repository or local
993source.
994
995Use the following form to add Node.js modules through ``npm``:
996::
997
998 $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
999
1000The name and
1001version parameters are mandatory. Lockdown and shrinkwrap files are
1002generated and pointed to by the recipe in order to freeze the version
1003that is fetched for the dependencies according to the first time. This
1004also saves checksums that are verified on future fetches. Together,
1005these behaviors ensure the reproducibility and integrity of the build.
1006
1007.. note::
1008
1009 - You must use quotes around the URL. The ``devtool add`` does not
1010 require the quotes, but the shell considers ";" as a splitter
1011 between multiple commands. Thus, without the quotes,
1012 ``devtool add`` does not receive the other parts, which results in
1013 several "command not found" errors.
1014
1015 - In order to support adding Node.js modules, a ``nodejs`` recipe
1016 must be part of your SDK.
1017
1018As mentioned earlier, you can also add Node.js modules directly from a
1019repository or local source tree. To add modules this way, use
1020``devtool add`` in the following form:
1021::
1022
1023 $ devtool add https://github.com/diversario/node-ssdp
1024
1025In this example, ``devtool``
1026fetches the specified Git repository, detects the code as Node.js code,
1027fetches dependencies using ``npm``, and sets
1028:term:`SRC_URI` accordingly.
1029
1030Working With Recipes
1031====================
1032
1033When building a recipe using the ``devtool build`` command, the typical
1034build progresses as follows:
1035
10361. Fetch the source
1037
10382. Unpack the source
1039
10403. Configure the source
1041
10424. Compile the source
1043
10445. Install the build output
1045
10466. Package the installed output
1047
1048For recipes in the workspace, fetching and unpacking is disabled as the
1049source tree has already been prepared and is persistent. Each of these
1050build steps is defined as a function (task), usually with a "do\_" prefix
1051(e.g. :ref:`ref-tasks-fetch`,
1052:ref:`ref-tasks-unpack`, and so
1053forth). These functions are typically shell scripts but can instead be
1054written in Python.
1055
1056If you look at the contents of a recipe, you will see that the recipe
1057does not include complete instructions for building the software.
1058Instead, common functionality is encapsulated in classes inherited with
1059the ``inherit`` directive. This technique leaves the recipe to describe
1060just the things that are specific to the software being built. A
1061:ref:`base <ref-classes-base>` class exists that
1062is implicitly inherited by all recipes and provides the functionality
1063that most recipes typically need.
1064
1065The remainder of this section presents information useful when working
1066with recipes.
1067
1068Finding Logs and Work Files
1069---------------------------
1070
1071After the first run of the ``devtool build`` command, recipes that were
1072previously created using the ``devtool add`` command or whose sources
1073were modified using the ``devtool modify`` command contain symbolic
1074links created within the source tree:
1075
1076- ``oe-logs``: This link points to the directory in which log files and
1077 run scripts for each build step are created.
1078
1079- ``oe-workdir``: This link points to the temporary work area for the
1080 recipe. The following locations under ``oe-workdir`` are particularly
1081 useful:
1082
1083 - ``image/``: Contains all of the files installed during the
1084 :ref:`ref-tasks-install` stage.
1085 Within a recipe, this directory is referred to by the expression
1086 ``${``\ :term:`D`\ ``}``.
1087
1088 - ``sysroot-destdir/``: Contains a subset of files installed within
1089 ``do_install`` that have been put into the shared sysroot. For
1090 more information, see the "`Sharing Files Between
1091 Recipes <#sdk-sharing-files-between-recipes>`__" section.
1092
1093 - ``packages-split/``: Contains subdirectories for each package
1094 produced by the recipe. For more information, see the
1095 "`Packaging <#sdk-packaging>`__" section.
1096
1097You can use these links to get more information on what is happening at
1098each build step.
1099
1100Setting Configure Arguments
1101---------------------------
1102
1103If the software your recipe is building uses GNU autoconf, then a fixed
1104set of arguments is passed to it to enable cross-compilation plus any
1105extras specified by
1106:term:`EXTRA_OECONF` or
1107:term:`PACKAGECONFIG_CONFARGS`
1108set within the recipe. If you wish to pass additional options, add them
1109to ``EXTRA_OECONF`` or ``PACKAGECONFIG_CONFARGS``. Other supported build
1110tools have similar variables (e.g.
1111:term:`EXTRA_OECMAKE` for
1112CMake, :term:`EXTRA_OESCONS`
1113for Scons, and so forth). If you need to pass anything on the ``make``
1114command line, you can use ``EXTRA_OEMAKE`` or the
1115:term:`PACKAGECONFIG_CONFARGS`
1116variables to do so.
1117
1118You can use the ``devtool configure-help`` command to help you set the
1119arguments listed in the previous paragraph. The command determines the
1120exact options being passed, and shows them to you along with any custom
1121arguments specified through ``EXTRA_OECONF`` or
1122``PACKAGECONFIG_CONFARGS``. If applicable, the command also shows you
1123the output of the configure script's "DASHDASHhelp" option as a
1124reference.
1125
1126Sharing Files Between Recipes
1127-----------------------------
1128
1129Recipes often need to use files provided by other recipes on the
1130:term:`Build Host`. For example,
1131an application linking to a common library needs access to the library
1132itself and its associated headers. The way this access is accomplished
1133within the extensible SDK is through the sysroot. One sysroot exists per
1134"machine" for which the SDK is being built. In practical terms, this
1135means a sysroot exists for the target machine, and a sysroot exists for
1136the build host.
1137
1138Recipes should never write files directly into the sysroot. Instead,
1139files should be installed into standard locations during the
1140:ref:`ref-tasks-install` task within
1141the ``${``\ :term:`D`\ ``}`` directory. A
1142subset of these files automatically goes into the sysroot. The reason
1143for this limitation is that almost all files that go into the sysroot
1144are cataloged in manifests in order to ensure they can be removed later
1145when a recipe is modified or removed. Thus, the sysroot is able to
1146remain free from stale files.
1147
1148Packaging
1149---------
1150
1151Packaging is not always particularly relevant within the extensible SDK.
1152However, if you examine how build output gets into the final image on
1153the target device, it is important to understand packaging because the
1154contents of the image are expressed in terms of packages and not
1155recipes.
1156
1157During the :ref:`ref-tasks-package`
1158task, files installed during the
1159:ref:`ref-tasks-install` task are
1160split into one main package, which is almost always named the same as
1161the recipe, and into several other packages. This separation exists
1162because not all of those installed files are useful in every image. For
1163example, you probably do not need any of the documentation installed in
1164a production image. Consequently, for each recipe the documentation
1165files are separated into a ``-doc`` package. Recipes that package
1166software containing optional modules or plugins might undergo additional
1167package splitting as well.
1168
1169After building a recipe, you can see where files have gone by looking in
1170the ``oe-workdir/packages-split`` directory, which contains a
1171subdirectory for each package. Apart from some advanced cases, the
1172:term:`PACKAGES` and
1173:term:`FILES` variables controls
1174splitting. The ``PACKAGES`` variable lists all of the packages to be
1175produced, while the ``FILES`` variable specifies which files to include
1176in each package by using an override to specify the package. For
1177example, ``FILES_${PN}`` specifies the files to go into the main package
1178(i.e. the main package has the same name as the recipe and
1179``${``\ :term:`PN`\ ``}`` evaluates to the
1180recipe name). The order of the ``PACKAGES`` value is significant. For
1181each installed file, the first package whose ``FILES`` value matches the
1182file is the package into which the file goes. Defaults exist for both
1183the ``PACKAGES`` and ``FILES`` variables. Consequently, you might find
1184you do not even need to set these variables in your recipe unless the
1185software the recipe is building installs files into non-standard
1186locations.
1187
1188Restoring the Target Device to its Original State
1189=================================================
1190
1191If you use the ``devtool deploy-target`` command to write a recipe's
1192build output to the target, and you are working on an existing component
1193of the system, then you might find yourself in a situation where you
1194need to restore the original files that existed prior to running the
1195``devtool deploy-target`` command. Because the ``devtool deploy-target``
1196command backs up any files it overwrites, you can use the
1197``devtool undeploy-target`` command to restore those files and remove
1198any other files the recipe deployed. Consider the following example:
1199::
1200
1201 $ devtool undeploy-target lighttpd root@192.168.7.2
1202
1203If you have deployed
1204multiple applications, you can remove them all using the "-a" option
1205thus restoring the target device to its original state:
1206::
1207
1208 $ devtool undeploy-target -a root@192.168.7.2
1209
1210Information about files deployed to
1211the target as well as any backed up files are stored on the target
1212itself. This storage, of course, requires some additional space on the
1213target machine.
1214
1215.. note::
1216
1217 The
1218 devtool deploy-target
1219 and
1220 devtool undeploy-target
1221 commands do not currently interact with any package management system
1222 on the target device (e.g. RPM or OPKG). Consequently, you should not
1223 intermingle
1224 devtool deploy-target
1225 and package manager operations on the target device. Doing so could
1226 result in a conflicting set of files.
1227 263
1228Installing Additional Items Into the Extensible SDK 264Installing Additional Items Into the Extensible SDK
1229=================================================== 265===================================================
@@ -1234,13 +270,31 @@ populated on-demand. Sometimes you must explicitly install extra items
1234into the SDK. If you need these extra items, you can first search for 270into the SDK. If you need these extra items, you can first search for
1235the items using the ``devtool search`` command. For example, suppose you 271the items using the ``devtool search`` command. For example, suppose you
1236need to link to libGL but you are not sure which recipe provides libGL. 272need to link to libGL but you are not sure which recipe provides libGL.
1237You can use the following command to find out: 273You can use the following command to find out::
1238::
1239 274
1240 $ devtool search libGL mesa 275 $ devtool search libGL mesa
276 A free implementation of the OpenGL API
277
278Once you know the recipe
279(i.e. ``mesa`` in this example), you can install it.
280
281When using the extensible SDK directly in a Yocto build
282-------------------------------------------------------
283
284In this scenario, the Yocto build tooling, e.g. ``bitbake``
285is directly accessible to build additional items, and it
286can simply be executed directly::
287
288 $ bitbake curl-native
289 # Add newly built native items to native sysroot
290 $ bitbake build-sysroots -c build_native_sysroot
291 $ bitbake mesa
292 # Add newly built target items to target sysroot
293 $ bitbake build-sysroots -c build_target_sysroot
294
295When using a standalone installer for the Extensible SDK
296--------------------------------------------------------
1241 297
1242A free implementation of the OpenGL API Once you know the recipe
1243(i.e. ``mesa`` in this example), you can install it:
1244:: 298::
1245 299
1246 $ devtool sdk-install mesa 300 $ devtool sdk-install mesa
@@ -1248,14 +302,13 @@ A free implementation of the OpenGL API Once you know the recipe
1248By default, the ``devtool sdk-install`` command assumes 302By default, the ``devtool sdk-install`` command assumes
1249the item is available in pre-built form from your SDK provider. If the 303the item is available in pre-built form from your SDK provider. If the
1250item is not available and it is acceptable to build the item from 304item is not available and it is acceptable to build the item from
1251source, you can add the "-s" option as follows: 305source, you can add the "-s" option as follows::
1252::
1253 306
1254 $ devtool sdk-install -s mesa 307 $ devtool sdk-install -s mesa
1255 308
1256It is important to remember that building the item from source 309It is important to remember that building the item from source
1257takes significantly longer than installing the pre-built artifact. Also, 310takes significantly longer than installing the pre-built artifact. Also,
1258if no recipe exists for the item you want to add to the SDK, you must 311if there is no recipe for the item you want to add to the SDK, you must
1259instead add the item using the ``devtool add`` command. 312instead add the item using the ``devtool add`` command.
1260 313
1261Applying Updates to an Installed Extensible SDK 314Applying Updates to an Installed Extensible SDK
@@ -1265,20 +318,17 @@ If you are working with an installed extensible SDK that gets
1265occasionally updated (e.g. a third-party SDK), then you will need to 318occasionally updated (e.g. a third-party SDK), then you will need to
1266manually "pull down" the updates into the installed SDK. 319manually "pull down" the updates into the installed SDK.
1267 320
1268To update your installed SDK, use ``devtool`` as follows: 321To update your installed SDK, use ``devtool`` as follows::
1269::
1270 322
1271 $ devtool sdk-update 323 $ devtool sdk-update
1272 324
1273The previous command assumes your SDK provider has set the 325The previous command assumes your SDK provider has set the default update URL
1274default update URL for you through the 326for you through the :term:`SDK_UPDATE_URL` variable as described in the
1275:term:`SDK_UPDATE_URL` 327":ref:`sdk-manual/appendix-customizing:Providing Updates to the Extensible SDK After Installation`"
1276variable as described in the "`Providing Updates to the Extensible SDK
1277After
1278Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__"
1279section. If the SDK provider has not set that default URL, you need to 328section. If the SDK provider has not set that default URL, you need to
1280specify it yourself in the command as follows: $ devtool sdk-update 329specify it yourself in the command as follows::
1281path_to_update_directory 330
331 $ devtool sdk-update path_to_update_directory
1282 332
1283.. note:: 333.. note::
1284 334
@@ -1295,15 +345,15 @@ those customers need an SDK that has custom libraries. In such a case,
1295you can produce a derivative SDK based on the currently installed SDK 345you can produce a derivative SDK based on the currently installed SDK
1296fairly easily by following these steps: 346fairly easily by following these steps:
1297 347
12981. If necessary, install an extensible SDK that you want to use as a 348#. If necessary, install an extensible SDK that you want to use as a
1299 base for your derivative SDK. 349 base for your derivative SDK.
1300 350
13012. Source the environment script for the SDK. 351#. Source the environment script for the SDK.
1302 352
13033. Add the extra libraries or other components you want by using the 353#. Add the extra libraries or other components you want by using the
1304 ``devtool add`` command. 354 ``devtool add`` command.
1305 355
13064. Run the ``devtool build-sdk`` command. 356#. Run the ``devtool build-sdk`` command.
1307 357
1308The previous steps take the recipes added to the workspace and construct 358The previous steps take the recipes added to the workspace and construct
1309a new SDK installer that contains those recipes and the resulting binary 359a new SDK installer that contains those recipes and the resulting binary
diff --git a/documentation/sdk-manual/figures/sdk-devtool-add-flow.png b/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
deleted file mode 100644
index e7d6173d2d..0000000000
--- a/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png b/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png
deleted file mode 100644
index 18ba8b7e65..0000000000
--- a/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png b/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
deleted file mode 100644
index 7d4f395e24..0000000000
--- a/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/sdk-manual/history.rst b/documentation/sdk-manual/history.rst
deleted file mode 100644
index 8c10f6d2ee..0000000000
--- a/documentation/sdk-manual/history.rst
+++ /dev/null
@@ -1,40 +0,0 @@
1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3***********************
4Manual Revision History
5***********************
6
7.. list-table::
8 :widths: 10 15 40
9 :header-rows: 1
10
11 * - Revision
12 - Date
13 - Note
14 * - 2.1
15 - April 2016
16 - The initial document released with the Yocto Project 2.1 Release
17 * - 2.2
18 - October 2016
19 - Released with the Yocto Project 2.2 Release.
20 * - 2.3
21 - May 2017
22 - Released with the Yocto Project 2.3 Release.
23 * - 2.4
24 - October 2017
25 - Released with the Yocto Project 2.4 Release.
26 * - 2.5
27 - May 2018
28 - Released with the Yocto Project 2.5 Release.
29 * - 2.6
30 - November 2018
31 - Released with the Yocto Project 2.6 Release.
32 * - 2.7
33 - May 2019
34 - Released with the Yocto Project 2.7 Release.
35 * - 3.0
36 - October 2019
37 - Released with the Yocto Project 3.0 Release.
38 * - 3.1
39 - April 2020
40 - Released with the Yocto Project 3.1 Release.
diff --git a/documentation/sdk-manual/index.rst b/documentation/sdk-manual/index.rst
index fce2b199c7..dc7186b911 100644
--- a/documentation/sdk-manual/index.rst
+++ b/documentation/sdk-manual/index.rst
@@ -17,6 +17,5 @@ Yocto Project Application Development and the Extensible Software Development Ki
17 appendix-obtain 17 appendix-obtain
18 appendix-customizing 18 appendix-customizing
19 appendix-customizing-standard 19 appendix-customizing-standard
20 history
21 20
22.. include:: /boilerplate.rst 21.. include:: /boilerplate.rst
diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
index e4b9b05ba6..fbfc8c2ac7 100644
--- a/documentation/sdk-manual/intro.rst
+++ b/documentation/sdk-manual/intro.rst
@@ -8,29 +8,20 @@ eSDK Introduction
8================= 8=================
9 9
10Welcome to the Yocto Project Application Development and the Extensible 10Welcome to the Yocto Project Application Development and the Extensible
11Software Development Kit (eSDK) manual. This manual provides information 11Software Development Kit (eSDK) manual. This manual
12that explains how to use both the Yocto Project extensible and standard 12explains how to use both the Yocto Project extensible and standard
13SDKs to develop applications and images. 13SDKs to develop applications and images.
14 14
15.. note::
16
17 Prior to the 2.0 Release of the Yocto Project, application
18 development was primarily accomplished through the use of the
19 Application Development Toolkit (ADT) and the availability of
20 stand-alone cross-development toolchains and other tools. With the
21 2.1 Release of the Yocto Project, application development has
22 transitioned to within a tool-rich extensible SDK and the more
23 traditional standard SDK.
24
25All SDKs consist of the following: 15All SDKs consist of the following:
26 16
27- *Cross-Development Toolchain*: This toolchain contains a compiler, 17- *Cross-Development Toolchain*: This toolchain contains a compiler,
28 debugger, and various miscellaneous tools. 18 debugger, and various associated tools.
29 19
30- *Libraries, Headers, and Symbols*: The libraries, headers, and 20- *Libraries, Headers, and Symbols*: The libraries, headers, and
31 symbols are specific to the image (i.e. they match the image). 21 symbols are specific to the image (i.e. they match the image
22 against which the SDK was built).
32 23
33- *Environment Setup Script*: This ``*.sh`` file, once run, sets up the 24- *Environment Setup Script*: This ``*.sh`` file, once sourced, sets up the
34 cross-development environment by defining variables and preparing for 25 cross-development environment by defining variables and preparing for
35 SDK use. 26 SDK use.
36 27
@@ -48,14 +39,14 @@ time since that path cannot be dynamically altered. This is the reason
48for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext`` 39for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext``
49archives. 40archives.
50 41
51Another feature for the SDKs is that only one set of cross-compiler 42Another feature of the SDKs is that only one set of cross-compiler
52toolchain binaries are produced for any given architecture. This feature 43toolchain binaries are produced for any given architecture. This feature
53takes advantage of the fact that the target hardware can be passed to 44takes advantage of the fact that the target hardware can be passed to
54``gcc`` as a set of compiler options. Those options are set up by the 45``gcc`` as a set of compiler options. Those options are set up by the
55environment script and contained in variables such as 46environment script and contained in variables such as
56:term:`CC` and 47:term:`CC` and
57:term:`LD`. This reduces the space needed 48:term:`LD`. This reduces the space needed
58for the tools. Understand, however, that every target still needs a 49for the tools. Understand, however, that every target still needs its own
59sysroot because those binaries are target-specific. 50sysroot because those binaries are target-specific.
60 51
61The SDK development environment consists of the following: 52The SDK development environment consists of the following:
@@ -75,7 +66,7 @@ The SDK development environment consists of the following:
75 66
76In summary, the extensible and standard SDK share many features. 67In summary, the extensible and standard SDK share many features.
77However, the extensible SDK has powerful development tools to help you 68However, the extensible SDK has powerful development tools to help you
78more quickly develop applications. Following is a table that summarizes 69more quickly develop applications. Here is a table that summarizes
79the primary differences between the standard and extensible SDK types 70the primary differences between the standard and extensible SDK types
80when considering which to build: 71when considering which to build:
81 72
@@ -118,8 +109,8 @@ The Cross-Development Toolchain
118 109
119The :term:`Cross-Development Toolchain` consists 110The :term:`Cross-Development Toolchain` consists
120of a cross-compiler, cross-linker, and cross-debugger that are used to 111of a cross-compiler, cross-linker, and cross-debugger that are used to
121develop user-space applications for targeted hardware. Additionally, for 112develop user-space applications for targeted hardware; in addition,
122an extensible SDK, the toolchain also has built-in ``devtool`` 113the extensible SDK comes with built-in ``devtool``
123functionality. This toolchain is created by running a SDK installer 114functionality. This toolchain is created by running a SDK installer
124script or through a :term:`Build Directory` that is based on 115script or through a :term:`Build Directory` that is based on
125your metadata configuration or extension for your targeted device. The 116your metadata configuration or extension for your targeted device. The
@@ -138,21 +129,19 @@ The QEMU Emulator
138----------------- 129-----------------
139 130
140The QEMU emulator allows you to simulate your hardware while running 131The QEMU emulator allows you to simulate your hardware while running
141your application or image. QEMU is not part of the SDK but is made 132your application or image. QEMU is not part of the SDK but is
142available a number of different ways: 133automatically installed and available if you have done any one of
134the following:
143 135
144- If you have cloned the ``poky`` Git repository to create a 136- cloned the ``poky`` Git repository to create a
145 :term:`Source Directory` and you have 137 :term:`Source Directory` and sourced the environment setup script.
146 sourced the environment setup script, QEMU is installed and
147 automatically available.
148 138
149- If you have downloaded a Yocto Project release and unpacked it to 139- downloaded a Yocto Project release and unpacked it to
150 create a Source Directory and you have sourced the environment setup 140 create a Source Directory and sourced the environment setup
151 script, QEMU is installed and automatically available. 141 script.
152 142
153- If you have installed the cross-toolchain tarball and you have 143- installed the cross-toolchain tarball and
154 sourced the toolchain's setup environment script, QEMU is also 144 sourced the toolchain's setup environment script.
155 installed and automatically available.
156 145
157SDK Development Model 146SDK Development Model
158===================== 147=====================
@@ -160,7 +149,7 @@ SDK Development Model
160Fundamentally, the SDK fits into the development process as follows: 149Fundamentally, the SDK fits into the development process as follows:
161 150
162.. image:: figures/sdk-environment.png 151.. image:: figures/sdk-environment.png
163 :align: center 152 :width: 100%
164 153
165The SDK is installed on any machine and can be used to develop applications, 154The SDK is installed on any machine and can be used to develop applications,
166images, and kernels. An SDK can even be used by a QA Engineer or Release 155images, and kernels. An SDK can even be used by a QA Engineer or Release
@@ -175,16 +164,16 @@ image.
175 164
176You just need to follow these general steps: 165You just need to follow these general steps:
177 166
1781. *Install the SDK for your target hardware:* For information on how to 167#. *Install the SDK for your target hardware:* For information on how to
179 install the SDK, see the "`Installing the 168 install the SDK, see the ":ref:`sdk-manual/using:installing the sdk`"
180 SDK <#sdk-installing-the-sdk>`__" section. 169 section.
181 170
1822. *Download or Build the Target Image:* The Yocto Project supports 171#. *Download or Build the Target Image:* The Yocto Project supports
183 several target architectures and has many pre-built kernel images and 172 several target architectures and has many pre-built kernel images and
184 root filesystem images. 173 root filesystem images.
185 174
186 If you are going to develop your application on hardware, go to the 175 If you are going to develop your application on hardware, go to the
187 :yocto_dl:`machines </releases/yocto/yocto-&DISTRO;/machines/>` download area and choose a 176 :yocto_dl:`machines </releases/yocto/&DISTRO_REL_LATEST_TAG;/machines/>` download area and choose a
188 target machine area from which to download the kernel image and root 177 target machine area from which to download the kernel image and root
189 filesystem. This download area could have several files in it that 178 filesystem. This download area could have several files in it that
190 support development using actual hardware. For example, the area 179 support development using actual hardware. For example, the area
@@ -194,7 +183,7 @@ You just need to follow these general steps:
194 183
195 If you are going to develop your application and then run and test it 184 If you are going to develop your application and then run and test it
196 using the QEMU emulator, go to the 185 using the QEMU emulator, go to the
197 :yocto_dl:`machines/qemu </releases/yocto/yocto-&DISTRO;/machines/qemu>` download area. From this 186 :yocto_dl:`machines/qemu </releases/yocto/&DISTRO_REL_LATEST_TAG;/machines/qemu>` download area. From this
198 area, go down into the directory for your target architecture (e.g. 187 area, go down into the directory for your target architecture (e.g.
199 ``qemux86_64`` for an Intel-based 64-bit architecture). Download the 188 ``qemux86_64`` for an Intel-based 64-bit architecture). Download the
200 kernel, root filesystem, and any other files you need for your 189 kernel, root filesystem, and any other files you need for your
@@ -202,12 +191,11 @@ You just need to follow these general steps:
202 191
203 .. note:: 192 .. note::
204 193
205 To use the root filesystem in QEMU, you need to extract it. See 194 To use the root filesystem in QEMU, you need to extract it. See the
206 the " 195 ":ref:`sdk-manual/appendix-obtain:extracting the root filesystem`"
207 Extracting the Root Filesystem 196 section for information on how to do this extraction.
208 " section for information on how to extract the root filesystem.
209 197
2103. *Develop and Test your Application:* At this point, you have the 198#. *Develop and Test your Application:* At this point, you have the
211 tools to develop your application. If you need to separately install 199 tools to develop your application. If you need to separately install
212 and use the QEMU emulator, you can go to `QEMU Home 200 and use the QEMU emulator, you can go to `QEMU Home
213 Page <https://wiki.qemu.org/Main_Page>`__ to download and learn about 201 Page <https://wiki.qemu.org/Main_Page>`__ to download and learn about
@@ -216,5 +204,5 @@ You just need to follow these general steps:
216 within the Yocto Project. 204 within the Yocto Project.
217 205
218The remainder of this manual describes how to use the extensible and 206The remainder of this manual describes how to use the extensible and
219standard SDKs. Information also exists in appendix form that describes 207standard SDKs. There is also information in appendix form describing
220how you can build, install, and modify an SDK. 208how you can build, install, and modify an SDK.
diff --git a/documentation/sdk-manual/using.rst b/documentation/sdk-manual/using.rst
index 29fb50465f..bfb306abf5 100644
--- a/documentation/sdk-manual/using.rst
+++ b/documentation/sdk-manual/using.rst
@@ -11,13 +11,13 @@ standard SDK.
11.. note:: 11.. note::
12 12
13 For a side-by-side comparison of main features supported for a 13 For a side-by-side comparison of main features supported for a
14 standard SDK as compared to an extensible SDK, see the " 14 standard SDK as compared to an extensible SDK, see the
15 Introduction 15 ":ref:`sdk-manual/intro:introduction`" section.
16 " section.
17 16
18You can use a standard SDK to work on Makefile and Autotools-based 17You can use a standard SDK to work on Makefile and Autotools-based
19projects. See the "`Using the SDK Toolchain 18projects. See the
20Directly <#sdk-working-projects>`__" chapter for more information. 19":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter
20for more information.
21 21
22Why use the Standard SDK and What is in It? 22Why use the Standard SDK and What is in It?
23=========================================== 23===========================================
@@ -31,9 +31,9 @@ the extensible SDK, which provides an internal build system and the
31The installed Standard SDK consists of several files and directories. 31The installed Standard SDK consists of several files and directories.
32Basically, it contains an SDK environment setup script, some 32Basically, it contains an SDK environment setup script, some
33configuration files, and host and target root filesystems to support 33configuration files, and host and target root filesystems to support
34usage. You can see the directory structure in the "`Installed Standard 34usage. You can see the directory structure in the
35SDK Directory 35":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
36Structure <#sdk-installed-standard-sdk-directory-structure>`__" section. 36section.
37 37
38Installing the SDK 38Installing the SDK
39================== 39==================
@@ -43,17 +43,16 @@ Host` by running the ``*.sh`` installation script.
43 43
44You can download a tarball installer, which includes the pre-built 44You can download a tarball installer, which includes the pre-built
45toolchain, the ``runqemu`` script, and support files from the 45toolchain, the ``runqemu`` script, and support files from the
46appropriate :yocto_dl:`toolchain </releases/yocto/yocto-&DISTRO;/toolchain/>` directory within 46appropriate :yocto_dl:`toolchain </releases/yocto/&DISTRO_REL_LATEST_TAG;/toolchain/>` directory within
47the Index of Releases. Toolchains are available for several 32-bit and 47the Index of Releases. Toolchains are available for several 32-bit and
4864-bit architectures with the ``x86_64`` directories, respectively. The 4864-bit architectures with the ``x86_64`` directories, respectively. The
49toolchains the Yocto Project provides are based off the 49toolchains the Yocto Project provides are based off the
50``core-image-sato`` and ``core-image-minimal`` images and contain 50``core-image-sato`` and ``core-image-minimal`` images and contain
51libraries appropriate for developing against that image. 51libraries appropriate for developing against the corresponding image.
52 52
53The names of the tarball installer scripts are such that a string 53The names of the tarball installer scripts are such that a string
54representing the host system appears first in the filename and then is 54representing the host system appears first in the filename and then is
55immediately followed by a string representing the target architecture. 55immediately followed by a string representing the target architecture::
56::
57 56
58 poky-glibc-host_system-image_type-arch-toolchain-release_version.sh 57 poky-glibc-host_system-image_type-arch-toolchain-release_version.sh
59 58
@@ -76,17 +75,16 @@ immediately followed by a string representing the target architecture.
76 75
77For example, the following SDK installer is for a 64-bit 76For example, the following SDK installer is for a 64-bit
78development host system and a i586-tuned target architecture based off 77development host system and a i586-tuned target architecture based off
79the SDK for ``core-image-sato`` and using the current DISTRO snapshot: 78the SDK for ``core-image-sato`` and using the current DISTRO snapshot::
80::
81 79
82 poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh 80 poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
83 81
84.. note:: 82.. note::
85 83
86 As an alternative to downloading an SDK, you can build the SDK 84 As an alternative to downloading an SDK, you can build the SDK
87 installer. For information on building the installer, see the " 85 installer. For information on building the installer, see the
88 Building an SDK Installer 86 ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
89 " section. 87 section.
90 88
91The SDK and toolchains are self-contained and by default are installed 89The SDK and toolchains are self-contained and by default are installed
92into the ``poky_sdk`` folder in your home directory. You can choose to 90into the ``poky_sdk`` folder in your home directory. You can choose to
@@ -98,16 +96,7 @@ must be writable for whichever users need to use the SDK.
98The following command shows how to run the installer given a toolchain 96The following command shows how to run the installer given a toolchain
99tarball for a 64-bit x86 development host system and a 64-bit x86 target 97tarball for a 64-bit x86 development host system and a 64-bit x86 target
100architecture. The example assumes the SDK installer is located in 98architecture. The example assumes the SDK installer is located in
101``~/Downloads/`` and has execution rights. 99``~/Downloads/`` and has execution rights::
102
103.. note::
104
105 If you do not have write permissions for the directory into which you
106 are installing the SDK, the installer notifies you and exits. For
107 that case, set up the proper permissions in the directory and run the
108 installer again.
109
110::
111 100
112 $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh 101 $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
113 Poky (Yocto Project Reference Distro) SDK installer version &DISTRO; 102 Poky (Yocto Project Reference Distro) SDK installer version &DISTRO;
@@ -120,9 +109,16 @@ architecture. The example assumes the SDK installer is located in
120 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. 109 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
121 $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux 110 $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
122 111
123Again, reference the "`Installed Standard SDK Directory 112.. note::
124Structure <#sdk-installed-standard-sdk-directory-structure>`__" section 113
125for more details on the resulting directory structure of the installed 114 If you do not have write permissions for the directory into which you
115 are installing the SDK, the installer notifies you and exits. For
116 that case, set up the proper permissions in the directory and run the
117 installer again.
118
119Again, reference the
120":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
121section for more details on the resulting directory structure of the installed
126SDK. 122SDK.
127 123
128Running the SDK Environment Setup Script 124Running the SDK Environment Setup Script
@@ -140,14 +136,12 @@ begin with the string "``environment-setup``" and include as part of
140their name the tuned target architecture. As an example, the following 136their name the tuned target architecture. As an example, the following
141commands set the working directory to where the SDK was installed and 137commands set the working directory to where the SDK was installed and
142then source the environment setup script. In this example, the setup 138then source the environment setup script. In this example, the setup
143script is for an IA-based target machine using i586 tuning: 139script is for an IA-based target machine using i586 tuning::
144::
145 140
146 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux 141 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
147 142
148When you run the 143When you run the
149setup script, the same environment variables are defined as are when you 144setup script, the same environment variables are defined as are when you
150run the setup script for an extensible SDK. See the "`Running the 145run the setup script for an extensible SDK. See the
151Extensible SDK Environment Setup 146":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
152Script <#sdk-running-the-extensible-sdk-environment-setup-script>`__"
153section for more information. 147section for more information.
diff --git a/documentation/sdk-manual/working-projects.rst b/documentation/sdk-manual/working-projects.rst
index bddf00a7dc..4236bcec24 100644
--- a/documentation/sdk-manual/working-projects.rst
+++ b/documentation/sdk-manual/working-projects.rst
@@ -11,14 +11,15 @@ Autotools-Based Projects
11======================== 11========================
12 12
13Once you have a suitable :ref:`sdk-manual/intro:the cross-development toolchain` 13Once you have a suitable :ref:`sdk-manual/intro:the cross-development toolchain`
14installed, it is very easy to develop a project using the `GNU 14installed, it is very easy to develop a project using the :wikipedia:`GNU
15Autotools-based <https://en.wikipedia.org/wiki/GNU_Build_System>`__ 15Autotools-based <GNU_Build_System>` workflow, which is outside of the
16workflow, which is outside of the :term:`OpenEmbedded Build System`. 16:term:`OpenEmbedded Build System`.
17 17
18The following figure presents a simple Autotools workflow. 18The following figure presents a simple Autotools workflow.
19 19
20.. image:: figures/sdk-autotools-flow.png 20.. image:: figures/sdk-autotools-flow.png
21 :align: center 21 :align: center
22 :width: 70%
22 23
23Follow these steps to create a simple Autotools-based "Hello World" 24Follow these steps to create a simple Autotools-based "Hello World"
24project: 25project:
@@ -30,10 +31,9 @@ project:
30 GNOME Developer 31 GNOME Developer
31 site. 32 site.
32 33
331. *Create a Working Directory and Populate It:* Create a clean 34#. *Create a Working Directory and Populate It:* Create a clean
34 directory for your project and then make that directory your working 35 directory for your project and then make that directory your working
35 location. 36 location::
36 ::
37 37
38 $ mkdir $HOME/helloworld 38 $ mkdir $HOME/helloworld
39 $ cd $HOME/helloworld 39 $ cd $HOME/helloworld
@@ -45,16 +45,14 @@ project:
45 respectively. 45 respectively.
46 46
47 Use the following command to create an empty README file, which is 47 Use the following command to create an empty README file, which is
48 required by GNU Coding Standards: 48 required by GNU Coding Standards::
49 ::
50 49
51 $ touch README 50 $ touch README
52 51
53 Create the remaining 52 Create the remaining
54 three files as follows: 53 three files as follows:
55 54
56 - ``hello.c``: 55 - ``hello.c``::
57 ::
58 56
59 #include <stdio.h> 57 #include <stdio.h>
60 58
@@ -63,8 +61,7 @@ project:
63 printf("Hello World!\n"); 61 printf("Hello World!\n");
64 } 62 }
65 63
66 - ``configure.ac``: 64 - ``configure.ac``::
67 ::
68 65
69 AC_INIT(hello,0.1) 66 AC_INIT(hello,0.1)
70 AM_INIT_AUTOMAKE([foreign]) 67 AM_INIT_AUTOMAKE([foreign])
@@ -72,13 +69,12 @@ project:
72 AC_CONFIG_FILES(Makefile) 69 AC_CONFIG_FILES(Makefile)
73 AC_OUTPUT 70 AC_OUTPUT
74 71
75 - ``Makefile.am``: 72 - ``Makefile.am``::
76 ::
77 73
78 bin_PROGRAMS = hello 74 bin_PROGRAMS = hello
79 hello_SOURCES = hello.c 75 hello_SOURCES = hello.c
80 76
812. *Source the Cross-Toolchain Environment Setup File:* As described 77#. *Source the Cross-Toolchain Environment Setup File:* As described
82 earlier in the manual, installing the cross-toolchain creates a 78 earlier in the manual, installing the cross-toolchain creates a
83 cross-toolchain environment setup script in the directory that the 79 cross-toolchain environment setup script in the directory that the
84 SDK was installed. Before you can use the tools to develop your 80 SDK was installed. Before you can use the tools to develop your
@@ -87,14 +83,17 @@ project:
87 which is followed by the string "poky-linux". For this example, the 83 which is followed by the string "poky-linux". For this example, the
88 command sources a script from the default SDK installation directory 84 command sources a script from the default SDK installation directory
89 that uses the 32-bit Intel x86 Architecture and the &DISTRO; Yocto 85 that uses the 32-bit Intel x86 Architecture and the &DISTRO; Yocto
90 Project release: 86 Project release::
91 ::
92 87
93 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux 88 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
94 89
953. *Create the configure Script:* Use the ``autoreconf`` command to 90 Another example is sourcing the environment setup directly in a Yocto
96 generate the ``configure`` script. 91 build::
97 :: 92
93 $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
94
95#. *Create the configure Script:* Use the ``autoreconf`` command to
96 generate the ``configure`` script::
98 97
99 $ autoreconf 98 $ autoreconf
100 99
@@ -104,20 +103,16 @@ project:
104 103
105 .. note:: 104 .. note::
106 105
107 If you get errors from 106 If you get errors from ``configure.ac``, which ``autoreconf``
108 configure.ac
109 , which
110 autoreconf
111 runs, that indicate missing files, you can use the "-i" option, 107 runs, that indicate missing files, you can use the "-i" option,
112 which ensures missing auxiliary files are copied to the build 108 which ensures missing auxiliary files are copied to the build
113 host. 109 host.
114 110
1154. *Cross-Compile the Project:* This command compiles the project using 111#. *Cross-Compile the Project:* This command compiles the project using
116 the cross-compiler. The 112 the cross-compiler. The
117 :term:`CONFIGURE_FLAGS` 113 :term:`CONFIGURE_FLAGS`
118 environment variable provides the minimal arguments for GNU 114 environment variable provides the minimal arguments for GNU
119 configure: 115 configure::
120 ::
121 116
122 $ ./configure ${CONFIGURE_FLAGS} 117 $ ./configure ${CONFIGURE_FLAGS}
123 118
@@ -130,14 +125,12 @@ project:
130 ``armv5te-poky-linux-gnueabi``. You will notice that the name of the 125 ``armv5te-poky-linux-gnueabi``. You will notice that the name of the
131 script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the 126 script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
132 following command works to update your project and rebuild it using 127 following command works to update your project and rebuild it using
133 the appropriate cross-toolchain tools: 128 the appropriate cross-toolchain tools::
134 ::
135 129
136 $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir 130 $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
137 131
1385. *Make and Install the Project:* These two commands generate and 132#. *Make and Install the Project:* These two commands generate and
139 install the project into the destination directory: 133 install the project into the destination directory::
140 ::
141 134
142 $ make 135 $ make
143 $ make install DESTDIR=./tmp 136 $ make install DESTDIR=./tmp
@@ -146,22 +139,19 @@ project:
146 139
147 To learn about environment variables established when you run the 140 To learn about environment variables established when you run the
148 cross-toolchain environment setup script and how they are used or 141 cross-toolchain environment setup script and how they are used or
149 overridden when the Makefile, see the " 142 overridden by the Makefile, see the
150 Makefile-Based Projects 143 :ref:`sdk-manual/working-projects:makefile-based projects` section.
151 " section.
152 144
153 This next command is a simple way to verify the installation of your 145 This next command is a simple way to verify the installation of your
154 project. Running the command prints the architecture on which the 146 project. Running the command prints the architecture on which the
155 binary file can run. This architecture should be the same 147 binary file can run. This architecture should be the same
156 architecture that the installed cross-toolchain supports. 148 architecture that the installed cross-toolchain supports::
157 ::
158 149
159 $ file ./tmp/usr/local/bin/hello 150 $ file ./tmp/usr/local/bin/hello
160 151
1616. *Execute Your Project:* To execute the project, you would need to run 152#. *Execute Your Project:* To execute the project, you would need to run
162 it on your target hardware. If your target hardware happens to be 153 it on your target hardware. If your target hardware happens to be
163 your build host, you could run the project as follows: 154 your build host, you could run the project as follows::
164 ::
165 155
166 $ ./tmp/usr/local/bin/hello 156 $ ./tmp/usr/local/bin/hello
167 157
@@ -181,23 +171,24 @@ variables and Makefile variables during development.
181 171
182.. image:: figures/sdk-makefile-flow.png 172.. image:: figures/sdk-makefile-flow.png
183 :align: center 173 :align: center
174 :width: 70%
184 175
185The main point of this section is to explain the following three cases 176The main point of this section is to explain the following three cases
186regarding variable behavior: 177regarding variable behavior:
187 178
188- *Case 1 - No Variables Set in the Makefile Map to Equivalent 179- *Case 1 --- No Variables Set in the Makefile Map to Equivalent
189 Environment Variables Set in the SDK Setup Script:* Because matching 180 Environment Variables Set in the SDK Setup Script:* Because matching
190 variables are not specifically set in the ``Makefile``, the variables 181 variables are not specifically set in the ``Makefile``, the variables
191 retain their values based on the environment setup script. 182 retain their values based on the environment setup script.
192 183
193- *Case 2 - Variables Are Set in the Makefile that Map to Equivalent 184- *Case 2 --- Variables Are Set in the Makefile that Map to Equivalent
194 Environment Variables from the SDK Setup Script:* Specifically 185 Environment Variables from the SDK Setup Script:* Specifically
195 setting matching variables in the ``Makefile`` during the build 186 setting matching variables in the ``Makefile`` during the build
196 results in the environment settings of the variables being 187 results in the environment settings of the variables being
197 overwritten. In this case, the variables you set in the ``Makefile`` 188 overwritten. In this case, the variables you set in the ``Makefile``
198 are used. 189 are used.
199 190
200- *Case 3 - Variables Are Set Using the Command Line that Map to 191- *Case 3 --- Variables Are Set Using the Command Line that Map to
201 Equivalent Environment Variables from the SDK Setup Script:* 192 Equivalent Environment Variables from the SDK Setup Script:*
202 Executing the ``Makefile`` from the command line results in the 193 Executing the ``Makefile`` from the command line results in the
203 environment variables being overwritten. In this case, the 194 environment variables being overwritten. In this case, the
@@ -206,10 +197,7 @@ regarding variable behavior:
206.. note:: 197.. note::
207 198
208 Regardless of how you set your variables, if you use the "-e" option 199 Regardless of how you set your variables, if you use the "-e" option
209 with 200 with ``make``, the variables from the SDK setup script take precedence::
210 make
211 , the variables from the SDK setup script take precedence:
212 ::
213 201
214 $ make -e target 202 $ make -e target
215 203
@@ -220,8 +208,7 @@ demonstrates these variable behaviors.
220In a new shell environment variables are not established for the SDK 208In a new shell environment variables are not established for the SDK
221until you run the setup script. For example, the following commands show 209until you run the setup script. For example, the following commands show
222a null value for the compiler variable (i.e. 210a null value for the compiler variable (i.e.
223:term:`CC`). 211:term:`CC`)::
224::
225 212
226 $ echo ${CC} 213 $ echo ${CC}
227 214
@@ -231,8 +218,7 @@ Running the
231SDK setup script for a 64-bit build host and an i586-tuned target 218SDK setup script for a 64-bit build host and an i586-tuned target
232architecture for a ``core-image-sato`` image using the current &DISTRO; 219architecture for a ``core-image-sato`` image using the current &DISTRO;
233Yocto Project release and then echoing that variable shows the value 220Yocto Project release and then echoing that variable shows the value
234established through the script: 221established through the script::
235::
236 222
237 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux 223 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
238 $ echo ${CC} 224 $ echo ${CC}
@@ -241,10 +227,9 @@ established through the script:
241To illustrate variable use, work through this simple "Hello World!" 227To illustrate variable use, work through this simple "Hello World!"
242example: 228example:
243 229
2441. *Create a Working Directory and Populate It:* Create a clean 230#. *Create a Working Directory and Populate It:* Create a clean
245 directory for your project and then make that directory your working 231 directory for your project and then make that directory your working
246 location. 232 location::
247 ::
248 233
249 $ mkdir $HOME/helloworld 234 $ mkdir $HOME/helloworld
250 $ cd $HOME/helloworld 235 $ cd $HOME/helloworld
@@ -257,8 +242,7 @@ example:
257 242
258 Create the three files as follows: 243 Create the three files as follows:
259 244
260 - ``main.c``: 245 - ``main.c``::
261 ::
262 246
263 #include "module.h" 247 #include "module.h"
264 void sample_func(); 248 void sample_func();
@@ -268,14 +252,12 @@ example:
268 return 0; 252 return 0;
269 } 253 }
270 254
271 - ``module.h``: 255 - ``module.h``::
272 ::
273 256
274 #include <stdio.h> 257 #include <stdio.h>
275 void sample_func(); 258 void sample_func();
276 259
277 - ``module.c``: 260 - ``module.c``::
278 ::
279 261
280 #include "module.h" 262 #include "module.h"
281 void sample_func() 263 void sample_func()
@@ -284,7 +266,7 @@ example:
284 printf("\n"); 266 printf("\n");
285 } 267 }
286 268
2872. *Source the Cross-Toolchain Environment Setup File:* As described 269#. *Source the Cross-Toolchain Environment Setup File:* As described
288 earlier in the manual, installing the cross-toolchain creates a 270 earlier in the manual, installing the cross-toolchain creates a
289 cross-toolchain environment setup script in the directory that the 271 cross-toolchain environment setup script in the directory that the
290 SDK was installed. Before you can use the tools to develop your 272 SDK was installed. Before you can use the tools to develop your
@@ -293,35 +275,37 @@ example:
293 which is followed by the string "poky-linux". For this example, the 275 which is followed by the string "poky-linux". For this example, the
294 command sources a script from the default SDK installation directory 276 command sources a script from the default SDK installation directory
295 that uses the 32-bit Intel x86 Architecture and the &DISTRO_NAME; Yocto 277 that uses the 32-bit Intel x86 Architecture and the &DISTRO_NAME; Yocto
296 Project release: 278 Project release::
297 ::
298 279
299 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux 280 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
300 281
3013. *Create the Makefile:* For this example, the Makefile contains 282 Another example is sourcing the environment setup directly in a Yocto
302 two lines that can be used to set the ``CC`` variable. One line is 283 build::
284
285 $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
286
287#. *Create the Makefile:* For this example, the Makefile contains
288 two lines that can be used to set the :term:`CC` variable. One line is
303 identical to the value that is set when you run the SDK environment 289 identical to the value that is set when you run the SDK environment
304 setup script, and the other line sets ``CC`` to "gcc", the default 290 setup script, and the other line sets :term:`CC` to "gcc", the default
305 GNU compiler on the build host: 291 GNU compiler on the build host::
306 ::
307 292
308 # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux 293 # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
309 # CC="gcc" 294 # CC="gcc"
310 all: main.o module.o 295 all: main.o module.o
311 ${CC} main.o module.o -o target_bin 296 ${CC} main.o module.o -o target_bin
312 main.o: main.c module.h 297 main.o: main.c module.h
313 ${CC} -I . -c main.c 298 ${CC} -I . -c main.c
314 module.o: module.c 299 module.o: module.c module.h
315 module.h ${CC} -I . -c module.c 300 ${CC} -I . -c module.c
316 clean: 301 clean:
317 rm -rf *.o 302 rm -rf *.o
318 rm target_bin 303 rm target_bin
319 304
3204. *Make the Project:* Use the ``make`` command to create the binary 305#. *Make the Project:* Use the ``make`` command to create the binary
321 output file. Because variables are commented out in the Makefile, the 306 output file. Because variables are commented out in the Makefile, the
322 value used for ``CC`` is the value set when the SDK environment setup 307 value used for :term:`CC` is the value set when the SDK environment setup
323 file was run: 308 file was run::
324 ::
325 309
326 $ make 310 $ make
327 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c 311 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
@@ -329,13 +313,12 @@ example:
329 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin 313 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
330 314
331 From the results of the previous command, you can see that 315 From the results of the previous command, you can see that
332 the compiler used was the compiler established through the ``CC`` 316 the compiler used was the compiler established through the :term:`CC`
333 variable defined in the setup script. 317 variable defined in the setup script.
334 318
335 You can override the ``CC`` environment variable with the same 319 You can override the :term:`CC` environment variable with the same
336 variable as set from the Makefile by uncommenting the line in the 320 variable as set from the Makefile by uncommenting the line in the
337 Makefile and running ``make`` again. 321 Makefile and running ``make`` again::
338 ::
339 322
340 $ make clean 323 $ make clean
341 rm -rf *.o 324 rm -rf *.o
@@ -356,8 +339,7 @@ example:
356 variable as part of the command line. Go into the Makefile and 339 variable as part of the command line. Go into the Makefile and
357 re-insert the comment character so that running ``make`` uses the 340 re-insert the comment character so that running ``make`` uses the
358 established SDK compiler. However, when you run ``make``, use a 341 established SDK compiler. However, when you run ``make``, use a
359 command-line argument to set ``CC`` to "gcc": 342 command-line argument to set :term:`CC` to "gcc"::
360 ::
361 343
362 $ make clean 344 $ make clean
363 rm -rf *.o 345 rm -rf *.o
@@ -381,8 +363,7 @@ example:
381 environment variable. 363 environment variable.
382 364
383 In this last case, edit Makefile again to use the "gcc" compiler but 365 In this last case, edit Makefile again to use the "gcc" compiler but
384 then use the "-e" option on the ``make`` command line: 366 then use the "-e" option on the ``make`` command line::
385 ::
386 367
387 $ make clean 368 $ make clean
388 rm -rf *.o 369 rm -rf *.o
@@ -406,9 +387,8 @@ example:
406 use the SDK environment variables regardless of the values in the 387 use the SDK environment variables regardless of the values in the
407 Makefile. 388 Makefile.
408 389
4095. *Execute Your Project:* To execute the project (i.e. ``target_bin``), 390#. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
410 use the following command: 391 use the following command::
411 ::
412 392
413 $ ./target_bin 393 $ ./target_bin
414 Hello World! 394 Hello World!