diff options
Diffstat (limited to 'documentation/sdk-manual')
-rw-r--r-- | documentation/sdk-manual/appendix-customizing-standard.rst | 6 | ||||
-rw-r--r-- | documentation/sdk-manual/appendix-customizing.rst | 187 | ||||
-rw-r--r-- | documentation/sdk-manual/appendix-obtain.rst | 207 | ||||
-rw-r--r-- | documentation/sdk-manual/extensible.rst | 1198 | ||||
-rw-r--r-- | documentation/sdk-manual/figures/sdk-devtool-add-flow.png | bin | 181699 -> 0 bytes | |||
-rw-r--r-- | documentation/sdk-manual/figures/sdk-devtool-modify-flow.png | bin | 171676 -> 0 bytes | |||
-rw-r--r-- | documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png | bin | 138917 -> 0 bytes | |||
-rw-r--r-- | documentation/sdk-manual/history.rst | 40 | ||||
-rw-r--r-- | documentation/sdk-manual/index.rst | 1 | ||||
-rw-r--r-- | documentation/sdk-manual/intro.rst | 78 | ||||
-rw-r--r-- | documentation/sdk-manual/using.rst | 64 | ||||
-rw-r--r-- | documentation/sdk-manual/working-projects.rst | 158 |
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 | |||
17 | variables control the set of packages adding to the SDK. | 17 | variables control the set of packages adding to the SDK. |
18 | 18 | ||
19 | If you want to add individual packages to the toolchain that runs on the | 19 | If you want to add individual packages to the toolchain that runs on the |
20 | host, simply add those packages to the ``TOOLCHAIN_HOST_TASK`` variable. | 20 | host, simply add those packages to the :term:`TOOLCHAIN_HOST_TASK` variable. |
21 | Similarly, if you want to add packages to the default set that is part | 21 | Similarly, if you want to add packages to the default set that is part |
22 | of the toolchain that runs on the target, add the packages to the | 22 | of 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 | ||
25 | Adding API Documentation to the Standard SDK | 25 | Adding API Documentation to the Standard SDK |
26 | ============================================ | 26 | ============================================ |
@@ -29,6 +29,6 @@ You can include API documentation as well as any other documentation | |||
29 | provided by recipes with the standard SDK by adding "api-documentation" | 29 | provided by recipes with the standard SDK by adding "api-documentation" |
30 | to the | 30 | to the |
31 | :term:`DISTRO_FEATURES` | 31 | :term:`DISTRO_FEATURES` |
32 | variable: DISTRO_FEATURES_append = " api-documentation" Setting this | 32 | variable: DISTRO_FEATURES:append = " api-documentation" Setting this |
33 | variable as shown here causes the OpenEmbedded build system to build the | 33 | variable as shown here causes the OpenEmbedded build system to build the |
34 | documentation and then include it in the standard SDK. | 34 | documentation 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 | *************************************************** |
4 | Customizing the Extensible SDK | 4 | Customizing the Extensible SDK standalone installer |
5 | ****************************** | 5 | *************************************************** |
6 | 6 | ||
7 | This appendix describes customizations you can apply to the extensible | 7 | This appendix describes customizations you can apply to the extensible |
8 | SDK. | 8 | SDK 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 | ||
10 | Configuring the Extensible SDK | 16 | Configuring 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 | ||
50 | Additionally, the contents of ``conf/sdk-extra.conf``, when present, are | 54 | Additionally, the contents of ``conf/sdk-extra.conf``, when present, are |
51 | appended to the end of ``conf/local.conf`` within the produced SDK, | 55 | appended 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 | ||
59 | In most cases, the extensible SDK defaults should work with your :term:`Build | 63 | In most cases, the extensible SDK defaults should work with your :term:`Build |
60 | Host`'s setup. | 64 | Host`'s setup. However, there are cases when you might consider making |
61 | However, some cases exist for which you might consider making | ||
62 | adjustments: | 65 | adjustments: |
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 | ||
137 | Changing the Extensible SDK Installer Title | 133 | Changing the Extensible SDK Installer Title |
138 | =========================================== | 134 | =========================================== |
139 | 135 | ||
140 | You can change the displayed title for the SDK installer by setting the | 136 | You 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 |
142 | rebuilding the the SDK installer. For information on how to build an SDK | 138 | rebuilding the SDK installer. For information on how to build an SDK |
143 | installer, see the "`Building an SDK | 139 | installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" |
144 | Installer <#sdk-building-an-sdk-installer>`__" section. | 140 | section. |
145 | 141 | ||
146 | By default, this title is derived from | 142 | By default, this title is derived from |
147 | :term:`DISTRO_NAME` when it is | 143 | :term:`DISTRO_NAME` when it is |
148 | set. If the ``DISTRO_NAME`` variable is not set, the title is derived | 144 | set. If the :term:`DISTRO_NAME` variable is not set, the title is derived |
149 | from the :term:`DISTRO` variable. | 145 | from the :term:`DISTRO` variable. |
150 | 146 | ||
151 | The | 147 | The |
152 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` | 148 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` |
153 | class defines the default value of the ``SDK_TITLE`` variable as | 149 | class defines the default value of the :term:`SDK_TITLE` variable as |
154 | follows: | 150 | follows:: |
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 | ||
159 | While several ways exist to change this variable, an efficient method is | 154 | While there are several ways of changing this variable, an efficient method is |
160 | to set the variable in your distribution's configuration file. Doing so | 155 | to set the variable in your distribution's configuration file. Doing so |
161 | creates an SDK installer title that applies across your distribution. As | 156 | creates an SDK installer title that applies across your distribution. As |
162 | an example, assume you have your own layer for your distribution named | 157 | an 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 |
164 | does the default "poky" distribution. If so, you could update the | 159 | does 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 |
167 | form: | 162 | form:: |
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 | |||
178 | the installed SDKs to update the installed SDKs by using the | 172 | the installed SDKs to update the installed SDKs by using the |
179 | ``devtool sdk-update`` command: | 173 | ``devtool sdk-update`` command: |
180 | 174 | ||
181 | 1. 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 | ||
187 | 2. 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 | ||
197 | 3. 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 | ||
200 | 4. 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 | ||
209 | Completing the above steps allows users of the existing installed SDKs | 200 | Completing the above steps allows users of the existing installed SDKs |
210 | to simply run ``devtool sdk-update`` to retrieve and apply the latest | 201 | to simply run ``devtool sdk-update`` to retrieve and apply the latest |
211 | updates. See the "`Applying Updates to an Installed Extensible | 202 | updates. See the |
212 | SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" section | 203 | ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`" |
213 | for further information. | 204 | section for further information. |
214 | 205 | ||
215 | Changing the Default SDK Installation Directory | 206 | Changing 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 |
222 | within the | 213 | within the |
223 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` | 214 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` |
224 | class as follows: | 215 | class as follows:: |
225 | :: | ||
226 | 216 | ||
227 | SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" | 217 | SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" |
228 | 218 | ||
229 | You can | 219 | You can |
230 | change this default installation directory by specifically setting the | 220 | change this default installation directory by specifically setting the |
231 | ``SDKEXTPATH`` variable. | 221 | :term:`SDKEXTPATH` variable. |
232 | 222 | ||
233 | While a number of ways exist through which you can set this variable, | 223 | While there are several ways of setting this variable, |
234 | the method that makes the most sense is to set the variable in your | 224 | the method that makes the most sense is to set the variable in your |
235 | distribution's configuration file. Doing so creates an SDK installer | 225 | distribution's configuration file. Doing so creates an SDK installer |
236 | default directory that applies across your distribution. As an example, | 226 | default directory that applies across your distribution. As an example, |
237 | assume you have your own layer for your distribution named | 227 | assume 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 |
239 | does the default "poky" distribution. If so, you could update the | 229 | does 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 |
242 | form: | 232 | form:: |
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 | |||
255 | items to the SDK without requiring the users to build the items from | 244 | items to the SDK without requiring the users to build the items from |
256 | source, you need to do a number of things: | 245 | source, you need to do a number of things: |
257 | 246 | ||
258 | 1. 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 | ||
270 | 2. 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 | ||
276 | 3. 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 | ||
311 | Minimizing the Size of the Extensible SDK Installer Download | 294 | Minimizing 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. | |||
316 | This bundling can lead to an SDK installer file that is a Gigabyte or | 299 | This bundling can lead to an SDK installer file that is a Gigabyte or |
317 | more in size. If the size of this file causes a problem, you can build | 300 | more in size. If the size of this file causes a problem, you can build |
318 | an SDK that has just enough in it to install and provide access to the | 301 | an 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 | |||
339 | results. | 321 | results. |
340 | 322 | ||
341 | To facilitate this wider range of information, you would need to set the | 323 | To facilitate this wider range of information, you would need to set the |
342 | following: | 324 | following:: |
343 | :: | ||
344 | 325 | ||
345 | SDK_INCLUDE_PKGDATA = "1" | 326 | SDK_INCLUDE_PKGDATA = "1" |
346 | 327 | ||
347 | See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information. | 328 | See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information. |
348 | 329 | ||
349 | Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world" | 330 | Setting the :term:`SDK_INCLUDE_PKGDATA` variable as shown causes the "world" |
350 | target to be built so that information for all of the recipes included | 331 | target to be built so that information for all of the recipes included |
351 | within it are available. Having these recipes available increases build | 332 | within it are available. Having these recipes available increases build |
352 | time significantly and increases the size of the SDK installer by 30-80 | 333 | time significantly and increases the size of the SDK installer by 30-80 |
353 | Mbytes depending on how many recipes are included in your configuration. | 334 | Mbytes depending on how many recipes are included in your configuration. |
354 | 335 | ||
355 | You can use ``EXCLUDE_FROM_WORLD_pn-``\ recipename for recipes you want | 336 | You can use ``EXCLUDE_FROM_WORLD:pn-``\ recipename for recipes you want |
356 | to exclude. However, it is assumed that you would need to be building | 337 | to exclude. However, it is assumed that you would need to be building |
357 | the "world" target if you want to provide additional items to the SDK. | 338 | the "world" target if you want to provide additional items to the SDK. |
358 | Consequently, building for "world" should not represent undue overhead | 339 | Consequently, 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 | ||
370 | You can explicitly control whether or not to include the toolchain when | 351 | You can explicitly control whether or not to include the toolchain when |
371 | you build an SDK by setting the | 352 | you build an SDK by setting the |
372 | :term:`SDK_INCLUDE_TOOLCHAIN` | 353 | :term:`SDK_INCLUDE_TOOLCHAIN` |
373 | variable to "1". In particular, it is useful to include the toolchain | 354 | variable to "1". In particular, it is useful to include the toolchain |
374 | when you have set ``SDK_EXT_TYPE`` to "minimal", which by default, | 355 | when you have set :term:`SDK_EXT_TYPE` to "minimal", which by default, |
375 | excludes the toolchain. Also, it is helpful if you are building a small | 356 | excludes the toolchain. Also, it is helpful if you are building a small |
376 | SDK for use with an IDE or some other tool where you do not want to take | 357 | SDK for use with an IDE or some other tool where you do not want to take |
377 | extra steps to install a toolchain. | 358 | extra 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 @@ | |||
4 | Obtaining the SDK | 4 | Obtaining the SDK |
5 | ***************** | 5 | ***************** |
6 | 6 | ||
7 | Working with the SDK components directly in a Yocto build | ||
8 | ========================================================= | ||
9 | |||
10 | Please refer to section | ||
11 | ":ref:`sdk-manual/extensible:Setting up the Extensible SDK environment directly in a Yocto build`" | ||
12 | |||
13 | Note that to use this feature effectively either a powerful build | ||
14 | machine, or a well-functioning sstate cache infrastructure is required: | ||
15 | otherwise significant time could be spent waiting for components to be built | ||
16 | by BitBake from source code. | ||
17 | |||
18 | Working with standalone SDK Installers | ||
19 | ====================================== | ||
20 | |||
7 | Locating Pre-Built SDK Installers | 21 | Locating Pre-Built SDK Installers |
8 | ================================= | 22 | --------------------------------- |
9 | 23 | ||
10 | You can use existing, pre-built toolchains by locating and running an | 24 | You can use existing, pre-built toolchains by locating and running an |
11 | SDK installer script that ships with the Yocto Project. Using this | 25 | SDK 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 | ||
15 | Follow these steps to locate and hand-install the toolchain: | 29 | Follow these steps to locate and hand-install the toolchain: |
16 | 30 | ||
17 | 1. *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 | ||
20 | 2. *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 | ||
24 | 3. *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 | ||
63 | 4. *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 | ||
77 | Building an SDK Installer | 81 | Building an SDK Installer |
78 | ========================= | 82 | ------------------------- |
79 | 83 | ||
80 | As an alternative to locating and downloading an SDK installer, you can | 84 | As an alternative to locating and downloading an SDK installer, you can |
81 | build the SDK installer. Follow these steps: | 85 | build the SDK installer. Follow these steps: |
82 | 86 | ||
83 | 1. *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 | ||
89 | 2. *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 | ||
99 | 3. *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`` | |
115 | 4. *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 | ||
121 | 5. *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 | ||
143 | 6. *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 | ||
172 | 7. *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 | ||
186 | Extracting the Root Filesystem | 185 | Extracting the Root Filesystem |
@@ -198,11 +197,11 @@ separately extract a root filesystem: | |||
198 | 197 | ||
199 | Follow these steps to extract the root filesystem: | 198 | Follow these steps to extract the root filesystem: |
200 | 199 | ||
201 | 1. *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 | ||
241 | 2. *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 | ||
254 | 3. *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 | ||
268 | Installed Standard SDK Directory Structure | 256 | Installed Standard SDK Directory Structure |
269 | ========================================== | 257 | ========================================== |
@@ -273,8 +261,7 @@ install the Standard SDK by running the ``*.sh`` SDK installation | |||
273 | script: | 261 | script: |
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 | ||
279 | The installed SDK consists of an environment setup script for the SDK, a | 266 | The installed SDK consists of an environment setup script for the SDK, a |
280 | configuration file for the target, a version file for the target, and | 267 | configuration 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 | ||
22 | In addition to the functionality available through ``devtool``, you can | 21 | In addition to the functionality available through ``devtool``, you can |
23 | alternatively make use of the toolchain directly, for example from | 22 | alternatively make use of the toolchain directly, for example from |
24 | Makefile and Autotools. See the "`Using the SDK Toolchain | 23 | Makefile and Autotools. See the |
25 | Directly <#sdk-working-projects>`__" chapter for more information. | 24 | ":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter |
25 | for more information. | ||
26 | 26 | ||
27 | Why use the Extensible SDK and What is in It? | 27 | Why use the Extensible SDK and What is in It? |
28 | ============================================= | 28 | ============================================= |
@@ -41,13 +41,53 @@ functionality. | |||
41 | Installing the Extensible SDK | 41 | Installing the Extensible SDK |
42 | ============================= | 42 | ============================= |
43 | 43 | ||
44 | Two ways to install the Extensible SDK | ||
45 | -------------------------------------- | ||
46 | |||
47 | Extensible SDK can be installed in two different ways, and both have | ||
48 | their 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 | |||
68 | Setting 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 | |||
81 | Setting up the Extensible SDK from a standalone installer | ||
82 | --------------------------------------------------------- | ||
83 | |||
44 | The first thing you need to do is install the SDK on your :term:`Build | 84 | The first thing you need to do is install the SDK on your :term:`Build |
45 | Host` by running the ``*.sh`` installation script. | 85 | Host` by running the ``*.sh`` installation script. |
46 | 86 | ||
47 | You can download a tarball installer, which includes the pre-built | 87 | You can download a tarball installer, which includes the pre-built |
48 | toolchain, the ``runqemu`` script, the internal build system, | 88 | toolchain, 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 |
51 | Releases. Toolchains are available for several 32-bit and 64-bit | 91 | Releases. Toolchains are available for several 32-bit and 64-bit |
52 | architectures with the ``x86_64`` directories, respectively. The | 92 | architectures with the ``x86_64`` directories, respectively. The |
53 | toolchains the Yocto Project provides are based off the | 93 | toolchains the Yocto Project provides are based off the |
@@ -58,8 +98,7 @@ The names of the tarball installer scripts are such that a string | |||
58 | representing the host system appears first in the filename and then is | 98 | representing the host system appears first in the filename and then is |
59 | immediately followed by a string representing the target architecture. | 99 | immediately followed by a string representing the target architecture. |
60 | An extensible SDK has the string "-ext" as part of the name. Following | 100 | An extensible SDK has the string "-ext" as part of the name. Following |
61 | is the general form: | 101 | is 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 | ||
83 | For example, the following SDK installer is for a 64-bit | 122 | For example, the following SDK installer is for a 64-bit |
84 | development host system and a i586-tuned target architecture based off | 123 | development host system and a i586-tuned target architecture based off |
85 | the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot: | 124 | the 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 | ||
97 | The SDK and toolchains are self-contained and by default are installed | 135 | The SDK and toolchains are self-contained and by default are installed |
98 | into the ``poky_sdk`` folder in your home directory. You can choose to | 136 | into 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. | |||
104 | The following command shows how to run the installer given a toolchain | 142 | The following command shows how to run the installer given a toolchain |
105 | tarball for a 64-bit x86 development host system and a 64-bit x86 target | 143 | tarball for a 64-bit x86 development host system and a 64-bit x86 target |
106 | architecture. The example assumes the SDK installer is located in | 144 | architecture. 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 | |||
137 | Running the Extensible SDK Environment Setup Script | 175 | Running the Extensible SDK Environment Setup Script |
138 | =================================================== | 176 | =================================================== |
139 | 177 | ||
140 | Once you have the SDK installed, you must run the SDK environment setup | 178 | Once you have the SDK installed, you must run the SDK environment setup |
141 | script before you can actually use the SDK. This setup script resides in | 179 | script before you can actually use the SDK. |
180 | |||
181 | When 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 | |||
184 | When using a standalone SDK installer, this setup script resides in | ||
142 | the directory you chose when you installed the SDK, which is either the | 185 | the directory you chose when you installed the SDK, which is either the |
143 | default ``poky_sdk`` directory or the directory you chose during | 186 | default ``poky_sdk`` directory or the directory you chose during |
144 | installation. | 187 | installation. |
@@ -149,21 +192,25 @@ begin with the string "``environment-setup``" and include as part of | |||
149 | their name the tuned target architecture. As an example, the following | 192 | their name the tuned target architecture. As an example, the following |
150 | commands set the working directory to where the SDK was installed and | 193 | commands set the working directory to where the SDK was installed and |
151 | then source the environment setup script. In this example, the setup | 194 | then source the environment setup script. In this example, the setup |
152 | script is for an IA-based target machine using i586 tuning: | 195 | script 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 | ||
160 | Running the setup script defines many environment variables needed in | 202 | When using the environment script directly in a Yocto build, it can |
161 | order to use the SDK (e.g. ``PATH``, | 203 | be 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 |
164 | see all the environment variables the script exports, examine the | 206 | |
207 | Running the setup script defines many environment variables needed in order to | ||
208 | use the SDK (e.g. ``PATH``, :term:`CC`, :term:`LD`, and so forth). If you want | ||
209 | to see all the environment variables the script exports, examine the | ||
165 | installation file itself. | 210 | installation file itself. |
166 | 211 | ||
212 | .. _using_devtool: | ||
213 | |||
167 | Using ``devtool`` in Your SDK Workflow | 214 | Using ``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 | ||
185 | The ``devtool`` command line is organized similarly to | 229 | The ``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 | ||
199 | Three ``devtool`` subcommands exist that provide entry-points into | 239 | ``devtool`` subcommands provide entry-points into development: |
200 | development: | ||
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 | |||
216 | allow you to make changes to the source as desired. By default, new | 257 | allow you to make changes to the source as desired. By default, new |
217 | recipes and the source go into a "workspace" directory under the SDK. | 258 | recipes and the source go into a "workspace" directory under the SDK. |
218 | 259 | ||
219 | The remainder of this section presents the ``devtool add``, | 260 | To learn how to use ``devtool`` to add, modify, upgrade recipes and more, see |
220 | ``devtool modify``, and ``devtool upgrade`` workflows. | 261 | the :ref:`dev-manual/devtool:Using the \`\`devtool\`\` command-line tool` |
221 | 262 | section of the Yocto Project Development Tasks Manual. | |
222 | Use ``devtool add`` to Add an Application | ||
223 | ----------------------------------------- | ||
224 | |||
225 | The ``devtool add`` command generates a new recipe based on existing | ||
226 | source code. This command takes advantage of the | ||
227 | :ref:`devtool-the-workspace-layer-structure` | ||
228 | layer that many ``devtool`` commands use. The command is flexible enough | ||
229 | to allow you to extract source code into both the workspace or a | ||
230 | separate local Git repository and to use existing code that does not | ||
231 | need to be extracted. | ||
232 | |||
233 | Depending on your particular scenario, the arguments and options you use | ||
234 | with ``devtool add`` form different combinations. The following diagram | ||
235 | shows common development flows you would use with the ``devtool add`` | ||
236 | command: | ||
237 | |||
238 | .. image:: figures/sdk-devtool-add-flow.png | ||
239 | :align: center | ||
240 | |||
241 | 1. *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 | |||
317 | 2. *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 | |||
328 | 3. *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 | |||
345 | 4. *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 | |||
367 | 5. *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 | |||
396 | Use ``devtool modify`` to Modify the Source of an Existing Component | ||
397 | -------------------------------------------------------------------- | ||
398 | |||
399 | The ``devtool modify`` command prepares the way to work on existing code | ||
400 | that already has a local recipe in place that is used to build the | ||
401 | software. The command is flexible enough to allow you to extract code | ||
402 | from an upstream source, specify the existing recipe, and keep track of | ||
403 | and gather any patch files from other developers that are associated | ||
404 | with the code. | ||
405 | |||
406 | Depending on your particular scenario, the arguments and options you use | ||
407 | with ``devtool modify`` form different combinations. The following | ||
408 | diagram shows common development flows for the ``devtool modify`` | ||
409 | command: | ||
410 | |||
411 | .. image:: figures/sdk-devtool-modify-flow.png | ||
412 | :align: center | ||
413 | |||
414 | 1. *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 | |||
526 | 2. *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 | |||
530 | 3. *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 | |||
544 | 4. *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 | |||
570 | 5. *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 | |||
606 | Use ``devtool upgrade`` to Create a Version of the Recipe that Supports a Newer Version of the Software | ||
607 | ------------------------------------------------------------------------------------------------------- | ||
608 | |||
609 | The ``devtool upgrade`` command upgrades an existing recipe to that of a | ||
610 | more up-to-date version found upstream. Throughout the life of software, | ||
611 | recipes continually undergo version upgrades by their upstream | ||
612 | publishers. You can use the ``devtool upgrade`` workflow to make sure | ||
613 | your recipes you are using for builds are up-to-date with their upstream | ||
614 | counterparts. | ||
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 | |||
625 | The ``devtool upgrade`` command is flexible enough to allow you to | ||
626 | specify source code revision and versioning schemes, extract code into | ||
627 | or out of the ``devtool`` | ||
628 | :ref:`devtool-the-workspace-layer-structure`, | ||
629 | and work with any source file forms that the | ||
630 | :ref:`fetchers <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` support. | ||
631 | |||
632 | The 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 | |||
638 | 1. *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 | |||
690 | 2. *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 | |||
701 | 3. *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 | |||
718 | 4. *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 | |||
740 | 5. *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 | |||
774 | A Closer Look at ``devtool add`` | ||
775 | ================================ | ||
776 | |||
777 | The ``devtool add`` command automatically creates a recipe based on the | ||
778 | source tree you provide with the command. Currently, the command has | ||
779 | support 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 | |||
799 | Apart from binary packages, the determination of how a source tree | ||
800 | should be treated is automatic based on the files present within that | ||
801 | source tree. For example, if a ``CMakeLists.txt`` file is found, then | ||
802 | the 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 | |||
812 | The remainder of this section covers specifics regarding how parts of | ||
813 | the recipe are generated. | ||
814 | |||
815 | Name and Version | ||
816 | ---------------- | ||
817 | |||
818 | If you do not specify a name and version on the command line, | ||
819 | ``devtool add`` uses various metadata within the source tree in an | ||
820 | attempt to determine the name and version of the software being built. | ||
821 | Based on what the tool determines, ``devtool`` sets the name of the | ||
822 | created recipe file accordingly. | ||
823 | |||
824 | If ``devtool`` cannot determine the name and version, the command prints | ||
825 | an error. For such cases, you must re-run the command and provide the | ||
826 | name and version, just the name, or just the version as part of the | ||
827 | command line. | ||
828 | |||
829 | Sometimes the name or version determined from the source tree might be | ||
830 | incorrect. For such a case, you must reset the recipe: | ||
831 | :: | ||
832 | |||
833 | $ devtool reset -n recipename | ||
834 | |||
835 | After running the ``devtool reset`` command, you need to | ||
836 | run ``devtool add`` again and provide the name or the version. | ||
837 | |||
838 | Dependency Detection and Mapping | ||
839 | -------------------------------- | ||
840 | |||
841 | The ``devtool add`` command attempts to detect build-time dependencies | ||
842 | and map them to other recipes in the system. During this mapping, the | ||
843 | command fills in the names of those recipes as part of the | ||
844 | :term:`DEPENDS` variable within the | ||
845 | recipe. If a dependency cannot be mapped, ``devtool`` places a comment | ||
846 | in the recipe indicating such. The inability to map a dependency can | ||
847 | result from naming not being recognized or because the dependency simply | ||
848 | is not available. For cases where the dependency is not available, you | ||
849 | must use the ``devtool add`` command to add an additional recipe that | ||
850 | satisfies the dependency. Once you add that recipe, you need to update | ||
851 | the ``DEPENDS`` variable in the original recipe to include the new | ||
852 | recipe. | ||
853 | |||
854 | If you need to add runtime dependencies, you can do so by adding the | ||
855 | following 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 | |||
872 | License Detection | ||
873 | ----------------- | ||
874 | |||
875 | The ``devtool add`` command attempts to determine if the software you | ||
876 | are adding is able to be distributed under a common, open-source | ||
877 | license. If so, the command sets the | ||
878 | :term:`LICENSE` value accordingly. | ||
879 | You should double-check the value added by the command against the | ||
880 | documentation or source files for the software you are building and, if | ||
881 | necessary, update that ``LICENSE`` value. | ||
882 | |||
883 | The ``devtool add`` command also sets the | ||
884 | :term:`LIC_FILES_CHKSUM` | ||
885 | value to point to all files that appear to be license-related. Realize | ||
886 | that license statements often appear in comments at the top of source | ||
887 | files or within the documentation. In such cases, the command does not | ||
888 | recognize those license statements. Consequently, you might need to | ||
889 | amend the ``LIC_FILES_CHKSUM`` variable to point to one or more of those | ||
890 | comments if present. Setting ``LIC_FILES_CHKSUM`` is particularly | ||
891 | important for third-party software. The mechanism attempts to ensure | ||
892 | correct licensing should you upgrade the recipe to a newer upstream | ||
893 | version in future. Any change in licensing is detected and you receive | ||
894 | an error prompting you to check the license text again. | ||
895 | |||
896 | If 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 | ||
899 | with development even though the settings are unlikely to be correct in | ||
900 | all cases. You should check the documentation or source files for the | ||
901 | software you are building to determine the actual license. | ||
902 | |||
903 | Adding Makefile-Only Software | ||
904 | ----------------------------- | ||
905 | |||
906 | The use of Make by itself is very common in both proprietary and | ||
907 | open-source software. Unfortunately, Makefiles are often not written | ||
908 | with cross-compilation in mind. Thus, ``devtool add`` often cannot do | ||
909 | very much to ensure that these Makefiles build correctly. It is very | ||
910 | common, for example, to explicitly call ``gcc`` instead of using the | ||
911 | :term:`CC` variable. Usually, in a | ||
912 | cross-compilation environment, ``gcc`` is the compiler for the build | ||
913 | host and the cross-compiler is named something similar to | ||
914 | ``arm-poky-linux-gnueabi-gcc`` and might require arguments (e.g. to | ||
915 | point to the associated sysroot for the target machine). | ||
916 | |||
917 | When writing a recipe for Makefile-only software, keep the following in | ||
918 | mind: | ||
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 | |||
962 | Adding Native Tools | ||
963 | ------------------- | ||
964 | |||
965 | Often, you need to build additional tools that run on the :term:`Build | ||
966 | Host` as opposed to | ||
967 | the target. You should indicate this requirement by using one of the | ||
968 | following 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 | |||
988 | Adding Node.js Modules | ||
989 | ---------------------- | ||
990 | |||
991 | You can use the ``devtool add`` command two different ways to add | ||
992 | Node.js modules: 1) Through ``npm`` and, 2) from a repository or local | ||
993 | source. | ||
994 | |||
995 | Use 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 | |||
1000 | The name and | ||
1001 | version parameters are mandatory. Lockdown and shrinkwrap files are | ||
1002 | generated and pointed to by the recipe in order to freeze the version | ||
1003 | that is fetched for the dependencies according to the first time. This | ||
1004 | also saves checksums that are verified on future fetches. Together, | ||
1005 | these 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 | |||
1018 | As mentioned earlier, you can also add Node.js modules directly from a | ||
1019 | repository 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 | |||
1025 | In this example, ``devtool`` | ||
1026 | fetches the specified Git repository, detects the code as Node.js code, | ||
1027 | fetches dependencies using ``npm``, and sets | ||
1028 | :term:`SRC_URI` accordingly. | ||
1029 | |||
1030 | Working With Recipes | ||
1031 | ==================== | ||
1032 | |||
1033 | When building a recipe using the ``devtool build`` command, the typical | ||
1034 | build progresses as follows: | ||
1035 | |||
1036 | 1. Fetch the source | ||
1037 | |||
1038 | 2. Unpack the source | ||
1039 | |||
1040 | 3. Configure the source | ||
1041 | |||
1042 | 4. Compile the source | ||
1043 | |||
1044 | 5. Install the build output | ||
1045 | |||
1046 | 6. Package the installed output | ||
1047 | |||
1048 | For recipes in the workspace, fetching and unpacking is disabled as the | ||
1049 | source tree has already been prepared and is persistent. Each of these | ||
1050 | build 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 | ||
1053 | forth). These functions are typically shell scripts but can instead be | ||
1054 | written in Python. | ||
1055 | |||
1056 | If you look at the contents of a recipe, you will see that the recipe | ||
1057 | does not include complete instructions for building the software. | ||
1058 | Instead, common functionality is encapsulated in classes inherited with | ||
1059 | the ``inherit`` directive. This technique leaves the recipe to describe | ||
1060 | just the things that are specific to the software being built. A | ||
1061 | :ref:`base <ref-classes-base>` class exists that | ||
1062 | is implicitly inherited by all recipes and provides the functionality | ||
1063 | that most recipes typically need. | ||
1064 | |||
1065 | The remainder of this section presents information useful when working | ||
1066 | with recipes. | ||
1067 | |||
1068 | Finding Logs and Work Files | ||
1069 | --------------------------- | ||
1070 | |||
1071 | After the first run of the ``devtool build`` command, recipes that were | ||
1072 | previously created using the ``devtool add`` command or whose sources | ||
1073 | were modified using the ``devtool modify`` command contain symbolic | ||
1074 | links 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 | |||
1097 | You can use these links to get more information on what is happening at | ||
1098 | each build step. | ||
1099 | |||
1100 | Setting Configure Arguments | ||
1101 | --------------------------- | ||
1102 | |||
1103 | If the software your recipe is building uses GNU autoconf, then a fixed | ||
1104 | set of arguments is passed to it to enable cross-compilation plus any | ||
1105 | extras specified by | ||
1106 | :term:`EXTRA_OECONF` or | ||
1107 | :term:`PACKAGECONFIG_CONFARGS` | ||
1108 | set within the recipe. If you wish to pass additional options, add them | ||
1109 | to ``EXTRA_OECONF`` or ``PACKAGECONFIG_CONFARGS``. Other supported build | ||
1110 | tools have similar variables (e.g. | ||
1111 | :term:`EXTRA_OECMAKE` for | ||
1112 | CMake, :term:`EXTRA_OESCONS` | ||
1113 | for Scons, and so forth). If you need to pass anything on the ``make`` | ||
1114 | command line, you can use ``EXTRA_OEMAKE`` or the | ||
1115 | :term:`PACKAGECONFIG_CONFARGS` | ||
1116 | variables to do so. | ||
1117 | |||
1118 | You can use the ``devtool configure-help`` command to help you set the | ||
1119 | arguments listed in the previous paragraph. The command determines the | ||
1120 | exact options being passed, and shows them to you along with any custom | ||
1121 | arguments specified through ``EXTRA_OECONF`` or | ||
1122 | ``PACKAGECONFIG_CONFARGS``. If applicable, the command also shows you | ||
1123 | the output of the configure script's "DASHDASHhelp" option as a | ||
1124 | reference. | ||
1125 | |||
1126 | Sharing Files Between Recipes | ||
1127 | ----------------------------- | ||
1128 | |||
1129 | Recipes often need to use files provided by other recipes on the | ||
1130 | :term:`Build Host`. For example, | ||
1131 | an application linking to a common library needs access to the library | ||
1132 | itself and its associated headers. The way this access is accomplished | ||
1133 | within the extensible SDK is through the sysroot. One sysroot exists per | ||
1134 | "machine" for which the SDK is being built. In practical terms, this | ||
1135 | means a sysroot exists for the target machine, and a sysroot exists for | ||
1136 | the build host. | ||
1137 | |||
1138 | Recipes should never write files directly into the sysroot. Instead, | ||
1139 | files should be installed into standard locations during the | ||
1140 | :ref:`ref-tasks-install` task within | ||
1141 | the ``${``\ :term:`D`\ ``}`` directory. A | ||
1142 | subset of these files automatically goes into the sysroot. The reason | ||
1143 | for this limitation is that almost all files that go into the sysroot | ||
1144 | are cataloged in manifests in order to ensure they can be removed later | ||
1145 | when a recipe is modified or removed. Thus, the sysroot is able to | ||
1146 | remain free from stale files. | ||
1147 | |||
1148 | Packaging | ||
1149 | --------- | ||
1150 | |||
1151 | Packaging is not always particularly relevant within the extensible SDK. | ||
1152 | However, if you examine how build output gets into the final image on | ||
1153 | the target device, it is important to understand packaging because the | ||
1154 | contents of the image are expressed in terms of packages and not | ||
1155 | recipes. | ||
1156 | |||
1157 | During the :ref:`ref-tasks-package` | ||
1158 | task, files installed during the | ||
1159 | :ref:`ref-tasks-install` task are | ||
1160 | split into one main package, which is almost always named the same as | ||
1161 | the recipe, and into several other packages. This separation exists | ||
1162 | because not all of those installed files are useful in every image. For | ||
1163 | example, you probably do not need any of the documentation installed in | ||
1164 | a production image. Consequently, for each recipe the documentation | ||
1165 | files are separated into a ``-doc`` package. Recipes that package | ||
1166 | software containing optional modules or plugins might undergo additional | ||
1167 | package splitting as well. | ||
1168 | |||
1169 | After building a recipe, you can see where files have gone by looking in | ||
1170 | the ``oe-workdir/packages-split`` directory, which contains a | ||
1171 | subdirectory for each package. Apart from some advanced cases, the | ||
1172 | :term:`PACKAGES` and | ||
1173 | :term:`FILES` variables controls | ||
1174 | splitting. The ``PACKAGES`` variable lists all of the packages to be | ||
1175 | produced, while the ``FILES`` variable specifies which files to include | ||
1176 | in each package by using an override to specify the package. For | ||
1177 | example, ``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 | ||
1180 | recipe name). The order of the ``PACKAGES`` value is significant. For | ||
1181 | each installed file, the first package whose ``FILES`` value matches the | ||
1182 | file is the package into which the file goes. Defaults exist for both | ||
1183 | the ``PACKAGES`` and ``FILES`` variables. Consequently, you might find | ||
1184 | you do not even need to set these variables in your recipe unless the | ||
1185 | software the recipe is building installs files into non-standard | ||
1186 | locations. | ||
1187 | |||
1188 | Restoring the Target Device to its Original State | ||
1189 | ================================================= | ||
1190 | |||
1191 | If you use the ``devtool deploy-target`` command to write a recipe's | ||
1192 | build output to the target, and you are working on an existing component | ||
1193 | of the system, then you might find yourself in a situation where you | ||
1194 | need to restore the original files that existed prior to running the | ||
1195 | ``devtool deploy-target`` command. Because the ``devtool deploy-target`` | ||
1196 | command backs up any files it overwrites, you can use the | ||
1197 | ``devtool undeploy-target`` command to restore those files and remove | ||
1198 | any other files the recipe deployed. Consider the following example: | ||
1199 | :: | ||
1200 | |||
1201 | $ devtool undeploy-target lighttpd root@192.168.7.2 | ||
1202 | |||
1203 | If you have deployed | ||
1204 | multiple applications, you can remove them all using the "-a" option | ||
1205 | thus restoring the target device to its original state: | ||
1206 | :: | ||
1207 | |||
1208 | $ devtool undeploy-target -a root@192.168.7.2 | ||
1209 | |||
1210 | Information about files deployed to | ||
1211 | the target as well as any backed up files are stored on the target | ||
1212 | itself. This storage, of course, requires some additional space on the | ||
1213 | target 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 | ||
1228 | Installing Additional Items Into the Extensible SDK | 264 | Installing Additional Items Into the Extensible SDK |
1229 | =================================================== | 265 | =================================================== |
@@ -1234,13 +270,31 @@ populated on-demand. Sometimes you must explicitly install extra items | |||
1234 | into the SDK. If you need these extra items, you can first search for | 270 | into the SDK. If you need these extra items, you can first search for |
1235 | the items using the ``devtool search`` command. For example, suppose you | 271 | the items using the ``devtool search`` command. For example, suppose you |
1236 | need to link to libGL but you are not sure which recipe provides libGL. | 272 | need to link to libGL but you are not sure which recipe provides libGL. |
1237 | You can use the following command to find out: | 273 | You 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 | |||
278 | Once you know the recipe | ||
279 | (i.e. ``mesa`` in this example), you can install it. | ||
280 | |||
281 | When using the extensible SDK directly in a Yocto build | ||
282 | ------------------------------------------------------- | ||
283 | |||
284 | In this scenario, the Yocto build tooling, e.g. ``bitbake`` | ||
285 | is directly accessible to build additional items, and it | ||
286 | can 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 | |||
295 | When using a standalone installer for the Extensible SDK | ||
296 | -------------------------------------------------------- | ||
1241 | 297 | ||
1242 | A 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 | |||
1248 | By default, the ``devtool sdk-install`` command assumes | 302 | By default, the ``devtool sdk-install`` command assumes |
1249 | the item is available in pre-built form from your SDK provider. If the | 303 | the item is available in pre-built form from your SDK provider. If the |
1250 | item is not available and it is acceptable to build the item from | 304 | item is not available and it is acceptable to build the item from |
1251 | source, you can add the "-s" option as follows: | 305 | source, 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 | ||
1256 | It is important to remember that building the item from source | 309 | It is important to remember that building the item from source |
1257 | takes significantly longer than installing the pre-built artifact. Also, | 310 | takes significantly longer than installing the pre-built artifact. Also, |
1258 | if no recipe exists for the item you want to add to the SDK, you must | 311 | if there is no recipe for the item you want to add to the SDK, you must |
1259 | instead add the item using the ``devtool add`` command. | 312 | instead add the item using the ``devtool add`` command. |
1260 | 313 | ||
1261 | Applying Updates to an Installed Extensible SDK | 314 | Applying Updates to an Installed Extensible SDK |
@@ -1265,20 +318,17 @@ If you are working with an installed extensible SDK that gets | |||
1265 | occasionally updated (e.g. a third-party SDK), then you will need to | 318 | occasionally updated (e.g. a third-party SDK), then you will need to |
1266 | manually "pull down" the updates into the installed SDK. | 319 | manually "pull down" the updates into the installed SDK. |
1267 | 320 | ||
1268 | To update your installed SDK, use ``devtool`` as follows: | 321 | To update your installed SDK, use ``devtool`` as follows:: |
1269 | :: | ||
1270 | 322 | ||
1271 | $ devtool sdk-update | 323 | $ devtool sdk-update |
1272 | 324 | ||
1273 | The previous command assumes your SDK provider has set the | 325 | The previous command assumes your SDK provider has set the default update URL |
1274 | default update URL for you through the | 326 | for 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`" |
1276 | variable as described in the "`Providing Updates to the Extensible SDK | ||
1277 | After | ||
1278 | Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__" | ||
1279 | section. If the SDK provider has not set that default URL, you need to | 328 | section. If the SDK provider has not set that default URL, you need to |
1280 | specify it yourself in the command as follows: $ devtool sdk-update | 329 | specify it yourself in the command as follows:: |
1281 | path_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, | |||
1295 | you can produce a derivative SDK based on the currently installed SDK | 345 | you can produce a derivative SDK based on the currently installed SDK |
1296 | fairly easily by following these steps: | 346 | fairly easily by following these steps: |
1297 | 347 | ||
1298 | 1. 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 | ||
1301 | 2. Source the environment script for the SDK. | 351 | #. Source the environment script for the SDK. |
1302 | 352 | ||
1303 | 3. 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 | ||
1306 | 4. Run the ``devtool build-sdk`` command. | 356 | #. Run the ``devtool build-sdk`` command. |
1307 | 357 | ||
1308 | The previous steps take the recipes added to the workspace and construct | 358 | The previous steps take the recipes added to the workspace and construct |
1309 | a new SDK installer that contains those recipes and the resulting binary | 359 | a 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 | *********************** | ||
4 | Manual 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 | ||
10 | Welcome to the Yocto Project Application Development and the Extensible | 10 | Welcome to the Yocto Project Application Development and the Extensible |
11 | Software Development Kit (eSDK) manual. This manual provides information | 11 | Software Development Kit (eSDK) manual. This manual |
12 | that explains how to use both the Yocto Project extensible and standard | 12 | explains how to use both the Yocto Project extensible and standard |
13 | SDKs to develop applications and images. | 13 | SDKs 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 | |||
25 | All SDKs consist of the following: | 15 | All 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 | |||
48 | for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext`` | 39 | for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext`` |
49 | archives. | 40 | archives. |
50 | 41 | ||
51 | Another feature for the SDKs is that only one set of cross-compiler | 42 | Another feature of the SDKs is that only one set of cross-compiler |
52 | toolchain binaries are produced for any given architecture. This feature | 43 | toolchain binaries are produced for any given architecture. This feature |
53 | takes advantage of the fact that the target hardware can be passed to | 44 | takes 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 |
55 | environment script and contained in variables such as | 46 | environment 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 |
58 | for the tools. Understand, however, that every target still needs a | 49 | for the tools. Understand, however, that every target still needs its own |
59 | sysroot because those binaries are target-specific. | 50 | sysroot because those binaries are target-specific. |
60 | 51 | ||
61 | The SDK development environment consists of the following: | 52 | The SDK development environment consists of the following: |
@@ -75,7 +66,7 @@ The SDK development environment consists of the following: | |||
75 | 66 | ||
76 | In summary, the extensible and standard SDK share many features. | 67 | In summary, the extensible and standard SDK share many features. |
77 | However, the extensible SDK has powerful development tools to help you | 68 | However, the extensible SDK has powerful development tools to help you |
78 | more quickly develop applications. Following is a table that summarizes | 69 | more quickly develop applications. Here is a table that summarizes |
79 | the primary differences between the standard and extensible SDK types | 70 | the primary differences between the standard and extensible SDK types |
80 | when considering which to build: | 71 | when considering which to build: |
81 | 72 | ||
@@ -118,8 +109,8 @@ The Cross-Development Toolchain | |||
118 | 109 | ||
119 | The :term:`Cross-Development Toolchain` consists | 110 | The :term:`Cross-Development Toolchain` consists |
120 | of a cross-compiler, cross-linker, and cross-debugger that are used to | 111 | of a cross-compiler, cross-linker, and cross-debugger that are used to |
121 | develop user-space applications for targeted hardware. Additionally, for | 112 | develop user-space applications for targeted hardware; in addition, |
122 | an extensible SDK, the toolchain also has built-in ``devtool`` | 113 | the extensible SDK comes with built-in ``devtool`` |
123 | functionality. This toolchain is created by running a SDK installer | 114 | functionality. This toolchain is created by running a SDK installer |
124 | script or through a :term:`Build Directory` that is based on | 115 | script or through a :term:`Build Directory` that is based on |
125 | your metadata configuration or extension for your targeted device. The | 116 | your metadata configuration or extension for your targeted device. The |
@@ -138,21 +129,19 @@ The QEMU Emulator | |||
138 | ----------------- | 129 | ----------------- |
139 | 130 | ||
140 | The QEMU emulator allows you to simulate your hardware while running | 131 | The QEMU emulator allows you to simulate your hardware while running |
141 | your application or image. QEMU is not part of the SDK but is made | 132 | your application or image. QEMU is not part of the SDK but is |
142 | available a number of different ways: | 133 | automatically installed and available if you have done any one of |
134 | the 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 | ||
157 | SDK Development Model | 146 | SDK Development Model |
158 | ===================== | 147 | ===================== |
@@ -160,7 +149,7 @@ SDK Development Model | |||
160 | Fundamentally, the SDK fits into the development process as follows: | 149 | Fundamentally, 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 | ||
165 | The SDK is installed on any machine and can be used to develop applications, | 154 | The SDK is installed on any machine and can be used to develop applications, |
166 | images, and kernels. An SDK can even be used by a QA Engineer or Release | 155 | images, and kernels. An SDK can even be used by a QA Engineer or Release |
@@ -175,16 +164,16 @@ image. | |||
175 | 164 | ||
176 | You just need to follow these general steps: | 165 | You just need to follow these general steps: |
177 | 166 | ||
178 | 1. *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 | ||
182 | 2. *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 | ||
210 | 3. *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 | ||
218 | The remainder of this manual describes how to use the extensible and | 206 | The remainder of this manual describes how to use the extensible and |
219 | standard SDKs. Information also exists in appendix form that describes | 207 | standard SDKs. There is also information in appendix form describing |
220 | how you can build, install, and modify an SDK. | 208 | how 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 | ||
18 | You can use a standard SDK to work on Makefile and Autotools-based | 17 | You can use a standard SDK to work on Makefile and Autotools-based |
19 | projects. See the "`Using the SDK Toolchain | 18 | projects. See the |
20 | Directly <#sdk-working-projects>`__" chapter for more information. | 19 | ":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter |
20 | for more information. | ||
21 | 21 | ||
22 | Why use the Standard SDK and What is in It? | 22 | Why 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 | |||
31 | The installed Standard SDK consists of several files and directories. | 31 | The installed Standard SDK consists of several files and directories. |
32 | Basically, it contains an SDK environment setup script, some | 32 | Basically, it contains an SDK environment setup script, some |
33 | configuration files, and host and target root filesystems to support | 33 | configuration files, and host and target root filesystems to support |
34 | usage. You can see the directory structure in the "`Installed Standard | 34 | usage. You can see the directory structure in the |
35 | SDK Directory | 35 | ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`" |
36 | Structure <#sdk-installed-standard-sdk-directory-structure>`__" section. | 36 | section. |
37 | 37 | ||
38 | Installing the SDK | 38 | Installing the SDK |
39 | ================== | 39 | ================== |
@@ -43,17 +43,16 @@ Host` by running the ``*.sh`` installation script. | |||
43 | 43 | ||
44 | You can download a tarball installer, which includes the pre-built | 44 | You can download a tarball installer, which includes the pre-built |
45 | toolchain, the ``runqemu`` script, and support files from the | 45 | toolchain, the ``runqemu`` script, and support files from the |
46 | appropriate :yocto_dl:`toolchain </releases/yocto/yocto-&DISTRO;/toolchain/>` directory within | 46 | appropriate :yocto_dl:`toolchain </releases/yocto/&DISTRO_REL_LATEST_TAG;/toolchain/>` directory within |
47 | the Index of Releases. Toolchains are available for several 32-bit and | 47 | the Index of Releases. Toolchains are available for several 32-bit and |
48 | 64-bit architectures with the ``x86_64`` directories, respectively. The | 48 | 64-bit architectures with the ``x86_64`` directories, respectively. The |
49 | toolchains the Yocto Project provides are based off the | 49 | toolchains 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 |
51 | libraries appropriate for developing against that image. | 51 | libraries appropriate for developing against the corresponding image. |
52 | 52 | ||
53 | The names of the tarball installer scripts are such that a string | 53 | The names of the tarball installer scripts are such that a string |
54 | representing the host system appears first in the filename and then is | 54 | representing the host system appears first in the filename and then is |
55 | immediately followed by a string representing the target architecture. | 55 | immediately 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 | ||
77 | For example, the following SDK installer is for a 64-bit | 76 | For example, the following SDK installer is for a 64-bit |
78 | development host system and a i586-tuned target architecture based off | 77 | development host system and a i586-tuned target architecture based off |
79 | the SDK for ``core-image-sato`` and using the current DISTRO snapshot: | 78 | the 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 | ||
91 | The SDK and toolchains are self-contained and by default are installed | 89 | The SDK and toolchains are self-contained and by default are installed |
92 | into the ``poky_sdk`` folder in your home directory. You can choose to | 90 | into 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. | |||
98 | The following command shows how to run the installer given a toolchain | 96 | The following command shows how to run the installer given a toolchain |
99 | tarball for a 64-bit x86 development host system and a 64-bit x86 target | 97 | tarball for a 64-bit x86 development host system and a 64-bit x86 target |
100 | architecture. The example assumes the SDK installer is located in | 98 | architecture. 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 | ||
123 | Again, reference the "`Installed Standard SDK Directory | 112 | .. note:: |
124 | Structure <#sdk-installed-standard-sdk-directory-structure>`__" section | 113 | |
125 | for 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 | |||
119 | Again, reference the | ||
120 | ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`" | ||
121 | section for more details on the resulting directory structure of the installed | ||
126 | SDK. | 122 | SDK. |
127 | 123 | ||
128 | Running the SDK Environment Setup Script | 124 | Running the SDK Environment Setup Script |
@@ -140,14 +136,12 @@ begin with the string "``environment-setup``" and include as part of | |||
140 | their name the tuned target architecture. As an example, the following | 136 | their name the tuned target architecture. As an example, the following |
141 | commands set the working directory to where the SDK was installed and | 137 | commands set the working directory to where the SDK was installed and |
142 | then source the environment setup script. In this example, the setup | 138 | then source the environment setup script. In this example, the setup |
143 | script is for an IA-based target machine using i586 tuning: | 139 | script 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 | ||
148 | When you run the | 143 | When you run the |
149 | setup script, the same environment variables are defined as are when you | 144 | setup script, the same environment variables are defined as are when you |
150 | run the setup script for an extensible SDK. See the "`Running the | 145 | run the setup script for an extensible SDK. See the |
151 | Extensible SDK Environment Setup | 146 | ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`" |
152 | Script <#sdk-running-the-extensible-sdk-environment-setup-script>`__" | ||
153 | section for more information. | 147 | section 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 | ||
13 | Once you have a suitable :ref:`sdk-manual/intro:the cross-development toolchain` | 13 | Once you have a suitable :ref:`sdk-manual/intro:the cross-development toolchain` |
14 | installed, it is very easy to develop a project using the `GNU | 14 | installed, it is very easy to develop a project using the :wikipedia:`GNU |
15 | Autotools-based <https://en.wikipedia.org/wiki/GNU_Build_System>`__ | 15 | Autotools-based <GNU_Build_System>` workflow, which is outside of the |
16 | workflow, which is outside of the :term:`OpenEmbedded Build System`. | 16 | :term:`OpenEmbedded Build System`. |
17 | 17 | ||
18 | The following figure presents a simple Autotools workflow. | 18 | The 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 | ||
23 | Follow these steps to create a simple Autotools-based "Hello World" | 24 | Follow these steps to create a simple Autotools-based "Hello World" |
24 | project: | 25 | project: |
@@ -30,10 +31,9 @@ project: | |||
30 | GNOME Developer | 31 | GNOME Developer |
31 | site. | 32 | site. |
32 | 33 | ||
33 | 1. *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 | ||
81 | 2. *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 | ||
95 | 3. *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 | ||
115 | 4. *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 | ||
138 | 5. *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 | ||
161 | 6. *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 | ||
185 | The main point of this section is to explain the following three cases | 176 | The main point of this section is to explain the following three cases |
186 | regarding variable behavior: | 177 | regarding 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. | |||
220 | In a new shell environment variables are not established for the SDK | 208 | In a new shell environment variables are not established for the SDK |
221 | until you run the setup script. For example, the following commands show | 209 | until you run the setup script. For example, the following commands show |
222 | a null value for the compiler variable (i.e. | 210 | a 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 | |||
231 | SDK setup script for a 64-bit build host and an i586-tuned target | 218 | SDK setup script for a 64-bit build host and an i586-tuned target |
232 | architecture for a ``core-image-sato`` image using the current &DISTRO; | 219 | architecture for a ``core-image-sato`` image using the current &DISTRO; |
233 | Yocto Project release and then echoing that variable shows the value | 220 | Yocto Project release and then echoing that variable shows the value |
234 | established through the script: | 221 | established 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: | |||
241 | To illustrate variable use, work through this simple "Hello World!" | 227 | To illustrate variable use, work through this simple "Hello World!" |
242 | example: | 228 | example: |
243 | 229 | ||
244 | 1. *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 | ||
287 | 2. *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 | ||
301 | 3. *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 | ||
320 | 4. *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 | ||
409 | 5. *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! |