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