blob: 09f06088d27f6081694818c37d863c9007d11185 [file] [log] [blame]
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='sdk-extensible'>
6
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007 <title>Using the Extensible SDK</title>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05008
9 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010 This chapter describes the extensible SDK and how to install it.
11 Information covers the pieces of the SDK, how to install it, and
12 presents a look at using the <filename>devtool</filename>
13 functionality.
14 The extensible SDK makes it easy to add new applications and libraries
15 to an image, modify the source for an existing component, test
16 changes on the target hardware, and ease integration into the rest of
17 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050018 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060019 <note>
20 For a side-by-side comparison of main features supported for an
21 extensible SDK as compared to a standard SDK, see the
22 "<link linkend='sdk-manual-intro'>Introduction</link>"
23 section.
24 </note>
25 </para>
26
27 <para>
28 In addition to the functionality available through
29 <filename>devtool</filename>, you can alternatively make use of the
30 toolchain directly, for example from Makefile, Autotools, and
Brad Bishop316dfdd2018-06-25 12:45:53 -040031 <trademark class='trade'>Eclipse</trademark>-based projects.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050032 See the
Patrick Williamsc0f7c042017-02-23 20:41:17 -060033 "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>"
34 chapter for more information.
35 </para>
36
37 <section id='sdk-extensible-sdk-intro'>
38 <title>Why use the Extensible SDK and What is in It?</title>
39
40 <para>
41 The extensible SDK provides a cross-development toolchain and
42 libraries tailored to the contents of a specific image.
43 You would use the Extensible SDK if you want a toolchain experience
44 supplemented with the powerful set of <filename>devtool</filename>
45 commands tailored for the Yocto Project environment.
46 </para>
47
48 <para>
49 The installed extensible SDK consists of several files and
50 directories.
51 Basically, it contains an SDK environment setup script, some
52 configuration files, an internal build system, and the
53 <filename>devtool</filename> functionality.
54 </para>
55 </section>
56
Brad Bishop316dfdd2018-06-25 12:45:53 -040057 <section id='sdk-installing-the-extensible-sdk'>
58 <title>Installing the Extensible SDK</title>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060059
60 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040061 The first thing you need to do is install the SDK on your
62 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
63 by running the <filename>*.sh</filename> installation script.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060064 </para>
65
66 <para>
67 You can download a tarball installer, which includes the
68 pre-built toolchain, the <filename>runqemu</filename>
69 script, the internal build system, <filename>devtool</filename>,
Brad Bishop316dfdd2018-06-25 12:45:53 -040070 and support files from the appropriate
71 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink>
72 directory within the Index of Releases.
73 Toolchains are available for several 32-bit and 64-bit
74 architectures with the <filename>x86_64</filename> directories,
75 respectively.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060076 The toolchains the Yocto Project provides are based off the
Brad Bishop316dfdd2018-06-25 12:45:53 -040077 <filename>core-image-sato</filename> and
78 <filename>core-image-minimal</filename> images and contain
Patrick Williamsc0f7c042017-02-23 20:41:17 -060079 libraries appropriate for developing against that image.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060080 </para>
81
82 <para>
83 The names of the tarball installer scripts are such that a
84 string representing the host system appears first in the
85 filename and then is immediately followed by a string
86 representing the target architecture.
87 An extensible SDK has the string "-ext" as part of the name.
Brad Bishop316dfdd2018-06-25 12:45:53 -040088 Following is the general form:
Patrick Williamsc0f7c042017-02-23 20:41:17 -060089 <literallayout class='monospaced'>
90 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh
91
92 Where:
93 <replaceable>host_system</replaceable> is a string representing your development system:
94
95 i686 or x86_64.
96
Brad Bishop316dfdd2018-06-25 12:45:53 -040097 <replaceable>image_type</replaceable> is the image for which the SDK was built:
98
99 core-image-sato or core-image-minimal
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600100
101 <replaceable>arch</replaceable> is a string representing the tuned target architecture:
102
Brad Bishop316dfdd2018-06-25 12:45:53 -0400103 aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600104
Brad Bishop316dfdd2018-06-25 12:45:53 -0400105 <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600106
107 &DISTRO;, &DISTRO;+snapshot
108 </literallayout>
109 For example, the following SDK installer is for a 64-bit
110 development host system and a i586-tuned target architecture
111 based off the SDK for <filename>core-image-sato</filename> and
112 using the current &DISTRO; snapshot:
113 <literallayout class='monospaced'>
114 poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh
115 </literallayout>
116 <note>
117 As an alternative to downloading an SDK, you can build the
118 SDK installer.
119 For information on building the installer, see the
120 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
121 section.
122 Another helpful resource for building an installer is the
123 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
124 wiki page.
125 This wiki page focuses on development when using the Eclipse
126 IDE.
127 </note>
128 </para>
129
130 <para>
131 The SDK and toolchains are self-contained and by default are
132 installed into the <filename>poky_sdk</filename> folder in your
133 home directory.
134 You can choose to install the extensible SDK in any location when
135 you run the installer.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400136 However, because files need to be written under that directory
137 during the normal course of operation, the location you choose
138 for installation must be writable for whichever
139 users need to use the SDK.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600140 </para>
141
142 <para>
143 The following command shows how to run the installer given a
144 toolchain tarball for a 64-bit x86 development host system and
145 a 64-bit x86 target architecture.
146 The example assumes the SDK installer is located in
Brad Bishop316dfdd2018-06-25 12:45:53 -0400147 <filename>~/Downloads/</filename> and has execution rights.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600148 <note>
149 If you do not have write permissions for the directory
150 into which you are installing the SDK, the installer
151 notifies you and exits.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400152 For that case, set up the proper permissions in the directory
153 and run the installer again.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600154 </note>
155 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400156 $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
157 Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5
158 ==========================================================================
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500159 Enter target directory for SDK (default: ~/poky_sdk):
160 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
Brad Bishop316dfdd2018-06-25 12:45:53 -0400161 Extracting SDK..............done
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500162 Setting it up...
163 Extracting buildtools...
164 Preparing build system...
Brad Bishop316dfdd2018-06-25 12:45:53 -0400165 Parsing recipes: 100% |##################################################################| Time: 0:00:52
166 Initialising tasks: 100% |###############################################################| Time: 0:00:00
167 Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00
168 Loading cache: 100% |####################################################################| Time: 0:00:00
169 Initialising tasks: 100% |###############################################################| Time: 0:00:00
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500170 done
171 SDK has been successfully set up and is ready to be used.
172 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
173 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
Brad Bishop316dfdd2018-06-25 12:45:53 -0400174
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600175 </literallayout>
176 </para>
177 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500178
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600179 <section id='sdk-running-the-extensible-sdk-environment-setup-script'>
180 <title>Running the Extensible SDK Environment Setup Script</title>
181
182 <para>
183 Once you have the SDK installed, you must run the SDK environment
Brad Bishop316dfdd2018-06-25 12:45:53 -0400184 setup script before you can actually use the SDK.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600185 This setup script resides in the directory you chose when you
186 installed the SDK, which is either the default
187 <filename>poky_sdk</filename> directory or the directory you
188 chose during installation.
189 </para>
190
191 <para>
192 Before running the script, be sure it is the one that matches the
193 architecture for which you are developing.
194 Environment setup scripts begin with the string
195 "<filename>environment-setup</filename>" and include as part of
196 their name the tuned target architecture.
197 As an example, the following commands set the working directory
198 to where the SDK was installed and then source the environment
199 setup script.
200 In this example, the setup script is for an IA-based
201 target machine using i586 tuning:
202 <literallayout class='monospaced'>
203 $ cd /home/scottrif/poky_sdk
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500204 $ source environment-setup-core2-64-poky-linux
205 SDK environment now set up; additionally you may now run devtool to perform development tasks.
206 Run devtool --help for further details.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600207 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400208 Running the setup script defines many environment variables needed
209 in order to use the SDK (e.g. <filename>PATH</filename>,
210 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>,
211 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>,
212 and so forth).
213 If you want to see all the environment variables the script
214 exports, examine the installation file itself.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600215 </para>
216 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500217
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600218 <section id='using-devtool-in-your-sdk-workflow'>
219 <title>Using <filename>devtool</filename> in Your SDK Workflow</title>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500220
221 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600222 The cornerstone of the extensible SDK is a command-line tool
223 called <filename>devtool</filename>.
224 This tool provides a number of features that help
225 you build, test and package software within the extensible SDK, and
226 optionally integrate it into an image built by the OpenEmbedded
227 build system.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500228 <note><title>Tip</title>
229 The use of <filename>devtool</filename> is not limited to
230 the extensible SDK.
231 You can use <filename>devtool</filename> to help you easily
232 develop any project whose build output must be part of an
Brad Bishop316dfdd2018-06-25 12:45:53 -0400233 image built using the build system.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500234 </note>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500235 </para>
236
237 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600238 The <filename>devtool</filename> command line is organized
239 similarly to
Brad Bishop316dfdd2018-06-25 12:45:53 -0400240 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> in that it
241 has a number of sub-commands for each function.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600242 You can run <filename>devtool --help</filename> to see all the
243 commands.
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500244 <note>
245 See the
246 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
247 in the Yocto Project Reference Manual for a
248 <filename>devtool</filename> quick reference.
249 </note>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500250 </para>
251
252 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400253 Three <filename>devtool</filename> subcommands exist that provide
254 entry-points into development:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600255 <itemizedlist>
256 <listitem><para>
257 <emphasis><filename>devtool add</filename></emphasis>:
258 Assists in adding new software to be built.
259 </para></listitem>
260 <listitem><para>
261 <emphasis><filename>devtool modify</filename></emphasis>:
262 Sets up an environment to enable you to modify the source of
263 an existing component.
264 </para></listitem>
265 <listitem><para>
266 <emphasis><filename>devtool upgrade</filename></emphasis>:
267 Updates an existing recipe so that you can build it for
268 an updated set of source files.
269 </para></listitem>
270 </itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400271 As with the build system, "recipes" represent software packages
272 within <filename>devtool</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600273 When you use <filename>devtool add</filename>, a recipe is
274 automatically created.
275 When you use <filename>devtool modify</filename>, the specified
Brad Bishop316dfdd2018-06-25 12:45:53 -0400276 existing recipe is used in order to determine where to get the
277 source code and how to patch it.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600278 In both cases, an environment is set up so that when you build the
279 recipe a source tree that is under your control is used in order to
280 allow you to make changes to the source as desired.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400281 By default, new recipes and the source go into a "workspace"
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600282 directory under the SDK.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500283 </para>
284
285 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600286 The remainder of this section presents the
287 <filename>devtool add</filename>,
288 <filename>devtool modify</filename>, and
289 <filename>devtool upgrade</filename> workflows.
290 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500291
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600292 <section id='sdk-use-devtool-to-add-an-application'>
293 <title>Use <filename>devtool add</filename> to Add an Application</title>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500294
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600295 <para>
296 The <filename>devtool add</filename> command generates
297 a new recipe based on existing source code.
298 This command takes advantage of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500299 <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600300 layer that many <filename>devtool</filename> commands
301 use.
302 The command is flexible enough to allow you to extract source
303 code into both the workspace or a separate local Git repository
304 and to use existing code that does not need to be extracted.
305 </para>
306
307 <para>
308 Depending on your particular scenario, the arguments and options
309 you use with <filename>devtool add</filename> form different
310 combinations.
311 The following diagram shows common development flows
312 you would use with the <filename>devtool add</filename>
313 command:
314 </para>
315
316 <para>
317 <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" />
318 </para>
319
320 <para>
321 <orderedlist>
322 <listitem><para><emphasis>Generating the New Recipe</emphasis>:
323 The top part of the flow shows three scenarios by which
324 you could use <filename>devtool add</filename> to
325 generate a recipe based on existing source code.</para>
326
327 <para>In a shared development environment, it is
Brad Bishop316dfdd2018-06-25 12:45:53 -0400328 typical for other developers to be responsible for
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600329 various areas of source code.
330 As a developer, you are probably interested in using
Brad Bishop316dfdd2018-06-25 12:45:53 -0400331 that source code as part of your development within
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600332 the Yocto Project.
333 All you need is access to the code, a recipe, and a
334 controlled area in which to do your work.</para>
335
336 <para>Within the diagram, three possible scenarios
337 feed into the <filename>devtool add</filename> workflow:
338 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400339 <listitem><para>
340 <emphasis>Left</emphasis>:
341 The left scenario in the figure represents a
342 common situation where the source code does not
343 exist locally and needs to be extracted.
344 In this situation, the source code is extracted
345 to the default workspace - you do not
346 want the files in some specific location
347 outside of the workspace.
348 Thus, everything you need will be located in
349 the workspace:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600350 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500351 $ devtool add <replaceable>recipe fetchuri</replaceable>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600352 </literallayout>
353 With this command, <filename>devtool</filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400354 extracts the upstream source files into a local
355 Git repository within the
356 <filename>sources</filename> folder.
357 The command then creates a recipe named
358 <replaceable>recipe</replaceable> and a
359 corresponding append file in the workspace.
360 If you do not provide
361 <replaceable>recipe</replaceable>, the command
362 makes an attempt to determine the recipe name.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600363 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400364 <listitem><para>
365 <emphasis>Middle</emphasis>:
366 The middle scenario in the figure also
367 represents a situation where the source code
368 does not exist locally.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600369 In this case, the code is again upstream
370 and needs to be extracted to some
371 local area - this time outside of the default
372 workspace.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400373 <note>
374 If required, <filename>devtool</filename>
375 always creates
376 a Git repository locally during the
377 extraction.
378 </note>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600379 Furthermore, the first positional argument
Brad Bishop316dfdd2018-06-25 12:45:53 -0400380 <replaceable>srctree</replaceable> in this
381 case identifies where the
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600382 <filename>devtool add</filename> command
383 will locate the extracted code outside of the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400384 workspace.
385 You need to specify an empty directory:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600386 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500387 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600388 </literallayout>
389 In summary, the source code is pulled from
Brad Bishop316dfdd2018-06-25 12:45:53 -0400390 <replaceable>fetchuri</replaceable> and
391 extracted into the location defined by
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600392 <replaceable>srctree</replaceable> as a local
393 Git repository.</para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500394
Brad Bishop316dfdd2018-06-25 12:45:53 -0400395 <para>Within workspace,
396 <filename>devtool</filename> creates a
397 recipe named <replaceable>recipe</replaceable>
398 along with an associated append file.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600399 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400400 <listitem><para>
401 <emphasis>Right</emphasis>:
402 The right scenario in the figure represents a
403 situation where the
404 <replaceable>srctree</replaceable> has been
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600405 previously prepared outside of the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400406 <filename>devtool</filename> workspace.</para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500407
Brad Bishop316dfdd2018-06-25 12:45:53 -0400408 <para>The following command provides a new
409 recipe name and identifies the existing source
410 tree location:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600411 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500412 $ devtool add <replaceable>recipe srctree</replaceable>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600413 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400414 The command examines the source code and
415 creates a recipe named
416 <replaceable>recipe</replaceable> for the code
417 and places the recipe into the workspace.
418 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500419
Brad Bishop316dfdd2018-06-25 12:45:53 -0400420 <para>Because the extracted source code already
421 exists, <filename>devtool</filename> does not
422 try to relocate the source code into the
423 workspace - only the new recipe is placed
424 in the workspace.</para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500425
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600426 <para>Aside from a recipe folder, the command
Brad Bishop316dfdd2018-06-25 12:45:53 -0400427 also creates an associated append folder and
428 places an initial
429 <filename>*.bbappend</filename> file within.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600430 </para></listitem>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500431 </itemizedlist>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600432 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400433 <listitem><para>
434 <emphasis>Edit the Recipe</emphasis>:
435 You can use <filename>devtool edit-recipe</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600436 to open up the editor as defined by the
437 <filename>$EDITOR</filename> environment variable
438 and modify the file:
439 <literallayout class='monospaced'>
440 $ devtool edit-recipe <replaceable>recipe</replaceable>
441 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400442 From within the editor, you can make modifications to
443 the recipe that take affect when you build it later.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600444 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400445 <listitem><para>
446 <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
447 The next step you take depends on what you are going
448 to do with the new code.</para>
449
450 <para>If you need to eventually move the build output
451 to the target hardware, use the following
452 <filename>devtool</filename> command:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600453 <literallayout class='monospaced'>
454 $ devtool build <replaceable>recipe</replaceable>
455 </literallayout></para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400456
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600457 <para>On the other hand, if you want an image to
Brad Bishop316dfdd2018-06-25 12:45:53 -0400458 contain the recipe's packages from the workspace
459 for immediate deployment onto a device (e.g. for
460 testing purposes), you can use
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600461 the <filename>devtool build-image</filename> command:
462 <literallayout class='monospaced'>
463 $ devtool build-image <replaceable>image</replaceable>
464 </literallayout>
465 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400466 <listitem><para>
467 <emphasis>Deploy the Build Output</emphasis>:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600468 When you use the <filename>devtool build</filename>
469 command to build out your recipe, you probably want to
Brad Bishop316dfdd2018-06-25 12:45:53 -0400470 see if the resulting build output works as expected
471 on the target hardware.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600472 <note>
473 This step assumes you have a previously built
474 image that is already either running in QEMU or
Brad Bishop316dfdd2018-06-25 12:45:53 -0400475 is running on actual hardware.
476 Also, it is assumed that for deployment of the
477 image to the target, SSH is installed in the image
478 and, if the image is running on real hardware,
479 you have network access to and from your
480 development machine.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600481 </note>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400482 You can deploy your build output to that target
483 hardware by using the
484 <filename>devtool deploy-target</filename> command:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600485 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500486 $ devtool deploy-target <replaceable>recipe target</replaceable>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600487 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400488 The <replaceable>target</replaceable> is a live target
489 machine running as an SSH server.</para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500490
Brad Bishop316dfdd2018-06-25 12:45:53 -0400491 <para>You can, of course, also deploy the image you
492 build to actual hardware by using the
493 <filename>devtool build-image</filename> command.
494 However, <filename>devtool</filename> does not provide
495 a specific command that allows you to deploy the
496 image to actual hardware.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600497 </para></listitem>
498 <listitem><para>
499 <emphasis>Finish Your Work With the Recipe</emphasis>:
500 The <filename>devtool finish</filename> command creates
501 any patches corresponding to commits in the local
502 Git repository, moves the new recipe to a more permanent
503 layer, and then resets the recipe so that the recipe is
504 built normally rather than from the workspace.
505 <literallayout class='monospaced'>
506 $ devtool finish <replaceable>recipe layer</replaceable>
507 </literallayout>
508 <note>
509 Any changes you want to turn into patches must be
510 committed to the Git repository in the source tree.
511 </note></para>
512
Brad Bishop316dfdd2018-06-25 12:45:53 -0400513 <para>As mentioned, the
514 <filename>devtool finish</filename> command moves the
515 final recipe to its permanent layer.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600516 </para>
517
518 <para>As a final process of the
519 <filename>devtool finish</filename> command, the state
520 of the standard layers and the upstream source is
521 restored so that you can build the recipe from those
522 areas rather than the workspace.
523 <note>
524 You can use the <filename>devtool reset</filename>
525 command to put things back should you decide you
526 do not want to proceed with your work.
527 If you do use this command, realize that the source
528 tree is preserved.
529 </note>
530 </para></listitem>
531 </orderedlist>
532 </para>
533 </section>
534
535 <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
536 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
537
538 <para>
539 The <filename>devtool modify</filename> command prepares the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400540 way to work on existing code that already has a local recipe in
541 place that is used to build the software.
542 The command is flexible enough to allow you to extract code
543 from an upstream source, specify the existing recipe, and
544 keep track of and gather any patch files from other developers
545 that are associated with the code.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600546 </para>
547
548 <para>
549 Depending on your particular scenario, the arguments and options
550 you use with <filename>devtool modify</filename> form different
551 combinations.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400552 The following diagram shows common development flows for the
553 <filename>devtool modify</filename> command:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600554 </para>
555
556 <para>
557 <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" />
558 </para>
559
560 <para>
561 <orderedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400562 <listitem><para>
563 <emphasis>Preparing to Modify the Code</emphasis>:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600564 The top part of the flow shows three scenarios by which
565 you could use <filename>devtool modify</filename> to
566 prepare to work on source files.
567 Each scenario assumes the following:
568 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400569 <listitem><para>
570 The recipe exists locally in a layer external
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600571 to the <filename>devtool</filename> workspace.
572 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400573 <listitem><para>
574 The source files exist either upstream in an
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600575 un-extracted state or locally in a previously
576 extracted state.
577 </para></listitem>
578 </itemizedlist>
579 The typical situation is where another developer has
Brad Bishop316dfdd2018-06-25 12:45:53 -0400580 created a layer for use with the Yocto Project and
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600581 their recipe already resides in that layer.
582 Furthermore, their source code is readily available
583 either upstream or locally.
584 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400585 <listitem><para>
586 <emphasis>Left</emphasis>:
587 The left scenario in the figure represents a
588 common situation where the source code does
589 not exist locally and it needs to be extracted
590 from an upstream source.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600591 In this situation, the source is extracted
Brad Bishop316dfdd2018-06-25 12:45:53 -0400592 into the default <filename>devtool</filename>
593 workspace location.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600594 The recipe, in this scenario, is in its own
595 layer outside the workspace
596 (i.e.
597 <filename>meta-</filename><replaceable>layername</replaceable>).
598 </para>
599
Brad Bishop316dfdd2018-06-25 12:45:53 -0400600 <para>The following command identifies the
601 recipe and, by default, extracts the source
602 files:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600603 <literallayout class='monospaced'>
604 $ devtool modify <replaceable>recipe</replaceable>
605 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400606 Once <filename>devtool</filename>locates the
607 recipe, <filename>devtool</filename> uses the
608 recipe's
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600609 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400610 statements to locate the source code and any
611 local patch files from other developers.</para>
612
613 <para>With this scenario, no
614 <replaceable>srctree</replaceable> argument
615 exists.
616 Consequently, the default behavior of the
617 <filename>devtool modify</filename> command is
618 to extract the source files pointed to by the
619 <filename>SRC_URI</filename> statements into a
620 local Git structure.
621 Furthermore, the location for the extracted
622 source is the default area within the
623 <filename>devtool</filename> workspace.
624 The result is that the command sets up both
625 the source code and an append file within the
626 workspace while the recipe remains in its
627 original location.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600628 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400629 <listitem><para>
630 <emphasis>Middle</emphasis>:
631 The middle scenario in the figure represents a
632 situation where the source code also does not
633 exist locally.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600634 In this case, the code is again upstream
635 and needs to be extracted to some
636 local area as a Git repository.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400637 The recipe, in this scenario, is again local
638 and in its own layer outside the workspace.
639 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600640
641 <para>The following command tells
642 <filename>devtool</filename> what recipe with
Brad Bishop316dfdd2018-06-25 12:45:53 -0400643 which to work and, in this case, identifies a
644 local area for the extracted source files that
645 is outside of the default
646 <filename>devtool</filename> workspace:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600647 <literallayout class='monospaced'>
648 $ devtool modify <replaceable>recipe srctree</replaceable>
649 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400650 <note>
651 You cannot provide a URL for
652 <replaceable>srctree</replaceable> using
653 the <filename>devtool</filename> command.
654 </note>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600655 As with all extractions, the command uses
Brad Bishop316dfdd2018-06-25 12:45:53 -0400656 the recipe's <filename>SRC_URI</filename>
657 statements to locate the source files and any
658 associated patch files.
659 Once the files are located, the command by
660 default extracts them into
661 <replaceable>srctree</replaceable>.</para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600662
Brad Bishop316dfdd2018-06-25 12:45:53 -0400663 <para>Within workspace,
664 <filename>devtool</filename> creates an append
665 file for the recipe.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600666 The recipe remains in its original location but
Brad Bishop316dfdd2018-06-25 12:45:53 -0400667 the source files are extracted to the location
668 you provide with
669 <replaceable>srctree</replaceable>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600670 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400671 <listitem><para>
672 <emphasis>Right</emphasis>:
673 The right scenario in the figure represents a
674 situation where the source tree
675 (<replaceable>srctree</replaceable>) already
676 exists locally as a previously extracted Git
677 structure outside of the
678 <filename>devtool</filename> workspace.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600679 In this example, the recipe also exists
Brad Bishop316dfdd2018-06-25 12:45:53 -0400680 elsewhere locally in its own layer.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600681 </para>
682
683 <para>The following command tells
684 <filename>devtool</filename> the recipe
Brad Bishop316dfdd2018-06-25 12:45:53 -0400685 with which to work, uses the "-n" option to
686 indicate source does not need to be extracted,
687 and uses <replaceable>srctree</replaceable> to
688 point to the previously extracted source files:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600689 <literallayout class='monospaced'>
690 $ devtool modify -n <replaceable>recipe srctree</replaceable>
691 </literallayout>
692 </para>
693
694 <para>Once the command finishes, it creates only
Brad Bishop316dfdd2018-06-25 12:45:53 -0400695 an append file for the recipe in the
696 <filename>devtool</filename> workspace.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600697 The recipe and the source code remain in their
698 original locations.
699 </para></listitem>
700 </itemizedlist>
701 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400702 <listitem><para>
703 <emphasis>Edit the Source</emphasis>:
704 Once you have used the
705 <filename>devtool modify</filename> command, you are
706 free to make changes to the source files.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600707 You can use any editor you like to make and save
708 your source code modifications.
709 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400710 <listitem><para>
711 <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
712 The next step you take depends on what you are going
713 to do with the new code.</para>
714
715 <para>If you need to eventually move the build output
716 to the target hardware, use the following
717 <filename>devtool</filename> command:
718 <literallayout class='monospaced'>
719 $ devtool build <replaceable>recipe</replaceable>
720 </literallayout></para>
721
722 <para>On the other hand, if you want an image to
723 contain the recipe's packages from the workspace
724 for immediate deployment onto a device (e.g. for
725 testing purposes), you can use
726 the <filename>devtool build-image</filename> command:
727 <literallayout class='monospaced'>
728 $ devtool build-image <replaceable>image</replaceable>
729 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600730 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400731 <listitem><para>
732 <emphasis>Deploy the Build Output</emphasis>:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600733 When you use the <filename>devtool build</filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400734 command to build out your recipe, you probably want to
735 see if the resulting build output works as expected
736 on target hardware.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600737 <note>
738 This step assumes you have a previously built
739 image that is already either running in QEMU or
740 running on actual hardware.
741 Also, it is assumed that for deployment of the image
742 to the target, SSH is installed in the image and if
743 the image is running on real hardware that you have
744 network access to and from your development machine.
745 </note>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400746 You can deploy your build output to that target
747 hardware by using the
748 <filename>devtool deploy-target</filename> command:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600749 <literallayout class='monospaced'>
750 $ devtool deploy-target <replaceable>recipe target</replaceable>
751 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400752 The <replaceable>target</replaceable> is a live target
753 machine running as an SSH server.</para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600754
Brad Bishop316dfdd2018-06-25 12:45:53 -0400755 <para>You can, of course, use other methods to deploy
756 the image you built using the
757 <filename>devtool build-image</filename> command to
758 actual hardware.
759 <filename>devtool</filename> does not provide
760 a specific command to deploy the image to actual
761 hardware.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600762 </para></listitem>
763 <listitem><para>
764 <emphasis>Finish Your Work With the Recipe</emphasis>:
765 The <filename>devtool finish</filename> command creates
766 any patches corresponding to commits in the local
767 Git repository, updates the recipe to point to them
768 (or creates a <filename>.bbappend</filename> file to do
769 so, depending on the specified destination layer), and
Brad Bishop316dfdd2018-06-25 12:45:53 -0400770 then resets the recipe so that the recipe is built
771 normally rather than from the workspace.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600772 <literallayout class='monospaced'>
773 $ devtool finish <replaceable>recipe layer</replaceable>
774 </literallayout>
775 <note>
776 Any changes you want to turn into patches must be
Brad Bishop316dfdd2018-06-25 12:45:53 -0400777 staged and committed within the local Git
778 repository before you use the
779 <filename>devtool finish</filename> command.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600780 </note></para>
781
782 <para>Because there is no need to move the recipe,
783 <filename>devtool finish</filename> either updates the
784 original recipe in the original layer or the command
Brad Bishop316dfdd2018-06-25 12:45:53 -0400785 creates a <filename>.bbappend</filename> file in a
786 different layer as provided by
787 <replaceable>layer</replaceable>.</para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600788
789 <para>As a final process of the
790 <filename>devtool finish</filename> command, the state
791 of the standard layers and the upstream source is
792 restored so that you can build the recipe from those
Brad Bishop316dfdd2018-06-25 12:45:53 -0400793 areas rather than from the workspace.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600794 <note>
795 You can use the <filename>devtool reset</filename>
796 command to put things back should you decide you
797 do not want to proceed with your work.
798 If you do use this command, realize that the source
799 tree is preserved.
800 </note>
801 </para></listitem>
802 </orderedlist>
803 </para>
804 </section>
805
806 <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
807 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
808
809 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400810 The <filename>devtool upgrade</filename> command upgrades
811 an existing recipe to that of a more up-to-date version
812 found upstream.
813 Throughout the life of software, recipes continually undergo
814 version upgrades by their upstream publishers.
815 You can use the <filename>devtool upgrade</filename>
816 workflow to make sure your recipes you are using for builds
817 are up-to-date with their upstream counterparts.
818 <note>
819 Several methods exist by which you can upgrade recipes -
820 <filename>devtool upgrade</filename> happens to be one.
821 You can read about all the methods by which you can
822 upgrade recipes in the
823 "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>"
824 section of the Yocto Project Development Tasks Manual.
825 </note>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600826 </para>
827
828 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400829 The <filename>devtool upgrade</filename> command is flexible
830 enough to allow you to specify source code revision and
831 versioning schemes, extract code into or out of the
832 <filename>devtool</filename>
833 <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>,
834 and work with any source file forms that the fetchers support.
835 </para>
836
837 <para>
838 The following diagram shows the common development flow
839 used with the <filename>devtool upgrade</filename> command:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600840 </para>
841
842 <para>
843 <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" />
844 </para>
845
846 <para>
847 <orderedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400848 <listitem><para>
849 <emphasis>Initiate the Upgrade</emphasis>:
850 The top part of the flow shows the typical scenario by
851 which you use the <filename>devtool upgrade</filename>
852 command.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600853 The following conditions exist:
854 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400855 <listitem><para>
856 The recipe exists in a local layer external
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600857 to the <filename>devtool</filename> workspace.
858 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400859 <listitem><para>
860 The source files for the new release
861 exist in the same location pointed to by
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600862 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400863 in the recipe (e.g. a tarball with the new
864 version number in the name, or as a different
865 revision in the upstream Git repository).
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600866 </para></listitem>
867 </itemizedlist>
868 A common situation is where third-party software has
869 undergone a revision so that it has been upgraded.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400870 The recipe you have access to is likely in your own
871 layer.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600872 Thus, you need to upgrade the recipe to use the
873 newer version of the software:
874 <literallayout class='monospaced'>
875 $ devtool upgrade -V <replaceable>version recipe</replaceable>
876 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400877 By default, the <filename>devtool upgrade</filename>
878 command extracts source code into the
879 <filename>sources</filename> directory in the
880 <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>.
881 If you want the code extracted to any other location,
882 you need to provide the
883 <replaceable>srctree</replaceable> positional argument
884 with the command as follows:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600885 <literallayout class='monospaced'>
886 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
887 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400888 <note>
889 In this example, the "-V" option specifies the new
890 version.
891 If you don't use "-V", the command upgrades the
892 recipe to the latest version.
893 </note>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600894 If the source files pointed to by the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400895 <filename>SRC_URI</filename> statement in the recipe
896 are in a Git repository, you must provide the "-S"
897 option and specify a revision for the software.</para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600898
Brad Bishop316dfdd2018-06-25 12:45:53 -0400899 <para>Once <filename>devtool</filename> locates the
900 recipe, it uses the <filename>SRC_URI</filename>
901 variable to locate the source code and any local patch
902 files from other developers.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600903 The result is that the command sets up the source
904 code, the new version of the recipe, and an append file
905 all within the workspace.
906 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400907 <listitem><para>
908 <emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
909 Conflicts could exist due to the software being
910 upgraded to a new version.
911 Conflicts occur if your recipe specifies some patch
912 files in <filename>SRC_URI</filename> that conflict
913 with changes made in the new version of the software.
914 For such cases, you need to resolve the conflicts
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600915 by editing the source and following the normal
916 <filename>git rebase</filename> conflict resolution
917 process.</para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400918
919 <para>Before moving onto the next step, be sure to
920 resolve any such conflicts created through use of a
921 newer or different version of the software.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600922 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400923 <listitem><para>
924 <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
925 The next step you take depends on what you are going
926 to do with the new code.</para>
927
928 <para>If you need to eventually move the build output
929 to the target hardware, use the following
930 <filename>devtool</filename> command:
931 <literallayout class='monospaced'>
932 $ devtool build <replaceable>recipe</replaceable>
933 </literallayout></para>
934
935 <para>On the other hand, if you want an image to
936 contain the recipe's packages from the workspace
937 for immediate deployment onto a device (e.g. for
938 testing purposes), you can use
939 the <filename>devtool build-image</filename> command:
940 <literallayout class='monospaced'>
941 $ devtool build-image <replaceable>image</replaceable>
942 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600943 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400944 <listitem><para>
945 <emphasis>Deploy the Build Output</emphasis>:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600946 When you use the <filename>devtool build</filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400947 command or <filename>bitbake</filename> to build
948 your recipe, you probably want to see if the resulting
949 build output works as expected on target hardware.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600950 <note>
951 This step assumes you have a previously built
952 image that is already either running in QEMU or
953 running on actual hardware.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400954 Also, it is assumed that for deployment of the
955 image to the target, SSH is installed in the image
956 and if the image is running on real hardware that
957 you have network access to and from your
958 development machine.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600959 </note>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400960 You can deploy your build output to that target
961 hardware by using the
962 <filename>devtool deploy-target</filename> command:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600963 <literallayout class='monospaced'>
964 $ devtool deploy-target <replaceable>recipe target</replaceable>
965 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400966 The <replaceable>target</replaceable> is a live target
967 machine running as an SSH server.</para>
968
969 <para>You can, of course, also deploy the image you
970 build using the
971 <filename>devtool build-image</filename> command
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600972 to actual hardware.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400973 However, <filename>devtool</filename> does not provide
974 a specific command that allows you to do this.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600975 </para></listitem>
976 <listitem><para>
977 <emphasis>Finish Your Work With the Recipe</emphasis>:
978 The <filename>devtool finish</filename> command creates
979 any patches corresponding to commits in the local
Brad Bishop316dfdd2018-06-25 12:45:53 -0400980 Git repository, moves the new recipe to a more
981 permanent layer, and then resets the recipe so that
982 the recipe is built normally rather than from the
983 workspace.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600984 If you specify a destination layer that is the same as
985 the original source, then the old version of the
986 recipe and associated files will be removed prior to
987 adding the new version.
988 <literallayout class='monospaced'>
989 $ devtool finish <replaceable>recipe layer</replaceable>
990 </literallayout>
991 <note>
992 Any changes you want to turn into patches must be
993 committed to the Git repository in the source tree.
994 </note></para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400995
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600996 <para>As a final process of the
997 <filename>devtool finish</filename> command, the state
998 of the standard layers and the upstream source is
999 restored so that you can build the recipe from those
1000 areas rather than the workspace.
1001 <note>
1002 You can use the <filename>devtool reset</filename>
1003 command to put things back should you decide you
1004 do not want to proceed with your work.
1005 If you do use this command, realize that the source
1006 tree is preserved.
1007 </note>
1008 </para></listitem>
1009 </orderedlist>
1010 </para>
1011 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001012 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001013
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001014 <section id='sdk-a-closer-look-at-devtool-add'>
1015 <title>A Closer Look at <filename>devtool add</filename></title>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001016
1017 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001018 The <filename>devtool add</filename> command automatically creates
1019 a recipe based on the source tree you provide with the command.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001020 Currently, the command has support for the following:
1021 <itemizedlist>
1022 <listitem><para>
1023 Autotools (<filename>autoconf</filename> and
1024 <filename>automake</filename>)
1025 </para></listitem>
1026 <listitem><para>
1027 CMake
1028 </para></listitem>
1029 <listitem><para>
1030 Scons
1031 </para></listitem>
1032 <listitem><para>
1033 <filename>qmake</filename>
1034 </para></listitem>
1035 <listitem><para>
1036 Plain <filename>Makefile</filename>
1037 </para></listitem>
1038 <listitem><para>
1039 Out-of-tree kernel module
1040 </para></listitem>
1041 <listitem><para>
1042 Binary package (i.e. "-b" option)
1043 </para></listitem>
1044 <listitem><para>
1045 Node.js module
1046 </para></listitem>
1047 <listitem><para>
1048 Python modules that use <filename>setuptools</filename>
1049 or <filename>distutils</filename>
1050 </para></listitem>
1051 </itemizedlist>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001052 </para>
1053
1054 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001055 Apart from binary packages, the determination of how a source tree
1056 should be treated is automatic based on the files present within
1057 that source tree.
1058 For example, if a <filename>CMakeLists.txt</filename> file is found,
1059 then the source tree is assumed to be using
1060 CMake and is treated accordingly.
1061 <note>
1062 In most cases, you need to edit the automatically generated
1063 recipe in order to make it build properly.
1064 Typically, you would go through several edit and build cycles
Brad Bishop316dfdd2018-06-25 12:45:53 -04001065 until the recipe successfully builds.
1066 Once the recipe builds, you could use possible further
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001067 iterations to test the recipe on the target device.
1068 </note>
1069 </para>
1070
1071 <para>
1072 The remainder of this section covers specifics regarding how parts
1073 of the recipe are generated.
1074 </para>
1075
1076 <section id='sdk-name-and-version'>
1077 <title>Name and Version</title>
1078
1079 <para>
1080 If you do not specify a name and version on the command
Brad Bishop316dfdd2018-06-25 12:45:53 -04001081 line, <filename>devtool add</filename> uses various metadata
1082 within the source tree in an attempt to determine
1083 the name and version of the software being built.
1084 Based on what the tool determines, <filename>devtool</filename>
1085 sets the name of the created recipe file accordingly.
1086 </para>
1087
1088 <para>
1089 If <filename>devtool</filename> cannot determine the name and
1090 version, the command prints an error.
1091 For such cases, you must re-run the command and provide
1092 the name and version, just the name, or just the version as
1093 part of the command line.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001094 </para>
1095
1096 <para>
1097 Sometimes the name or version determined from the source tree
1098 might be incorrect.
1099 For such a case, you must reset the recipe:
1100 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001101 $ devtool reset -n <replaceable>recipename</replaceable>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001102 </literallayout>
1103 After running the <filename>devtool reset</filename> command,
1104 you need to run <filename>devtool add</filename> again and
1105 provide the name or the version.
1106 </para>
1107 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001108
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001109 <section id='sdk-dependency-detection-and-mapping'>
1110 <title>Dependency Detection and Mapping</title>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001111
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001112 <para>
1113 The <filename>devtool add</filename> command attempts to
1114 detect build-time dependencies and map them to other recipes
1115 in the system.
1116 During this mapping, the command fills in the names of those
Brad Bishop316dfdd2018-06-25 12:45:53 -04001117 recipes as part of the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001118 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001119 variable within the recipe.
1120 If a dependency cannot be mapped, <filename>devtool</filename>
1121 places a comment in the recipe indicating such.
1122 The inability to map a dependency can result from naming not
1123 being recognized or because the dependency simply is not
1124 available.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001125 For cases where the dependency is not available, you must use
1126 the <filename>devtool add</filename> command to add an
Brad Bishop316dfdd2018-06-25 12:45:53 -04001127 additional recipe that satisfies the dependency.
1128 Once you add that recipe, you need to update the
1129 <filename>DEPENDS</filename> variable in the original recipe
1130 to include the new recipe.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001131 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001132
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001133 <para>
1134 If you need to add runtime dependencies, you can do so by
1135 adding the following to your recipe:
1136 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001137 RDEPENDS_${PN} += "<replaceable>dependency1 dependency2 ...</replaceable>"
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001138 </literallayout>
1139 <note>
1140 The <filename>devtool add</filename> command often cannot
1141 distinguish between mandatory and optional dependencies.
1142 Consequently, some of the detected dependencies might
1143 in fact be optional.
1144 When in doubt, consult the documentation or the configure
1145 script for the software the recipe is building for further
1146 details.
1147 In some cases, you might find you can substitute the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001148 dependency with an option that disables the associated
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001149 functionality passed to the configure script.
1150 </note>
1151 </para>
1152 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001153
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001154 <section id='sdk-license-detection'>
1155 <title>License Detection</title>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001156
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001157 <para>
1158 The <filename>devtool add</filename> command attempts to
1159 determine if the software you are adding is able to be
Brad Bishop316dfdd2018-06-25 12:45:53 -04001160 distributed under a common, open-source license.
1161 If so, the command sets the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001162 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1163 value accordingly.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001164 You should double-check the value added by the command against
1165 the documentation or source files for the software you are
1166 building and, if necessary, update that
1167 <filename>LICENSE</filename> value.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001168 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001169
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001170 <para>
1171 The <filename>devtool add</filename> command also sets the
1172 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1173 value to point to all files that appear to be license-related.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001174 Realize that license statements often appear in comments at
1175 the top of source files or within the documentation.
1176 In such cases, the command does not recognize those license
1177 statements.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001178 Consequently, you might need to amend the
1179 <filename>LIC_FILES_CHKSUM</filename> variable to point to one
1180 or more of those comments if present.
1181 Setting <filename>LIC_FILES_CHKSUM</filename> is particularly
1182 important for third-party software.
1183 The mechanism attempts to ensure correct licensing should you
1184 upgrade the recipe to a newer upstream version in future.
1185 Any change in licensing is detected and you receive an error
1186 prompting you to check the license text again.
1187 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001188
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001189 <para>
1190 If the <filename>devtool add</filename> command cannot
Brad Bishop316dfdd2018-06-25 12:45:53 -04001191 determine licensing information, <filename>devtool</filename>
1192 sets the <filename>LICENSE</filename> value to "CLOSED" and
1193 leaves the <filename>LIC_FILES_CHKSUM</filename> value unset.
1194 This behavior allows you to continue with development even
1195 though the settings are unlikely to be correct in all cases.
1196 You should check the documentation or source files for the
1197 software you are building to determine the actual license.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001198 </para>
1199 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001200
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001201 <section id='sdk-adding-makefile-only-software'>
1202 <title>Adding Makefile-Only Software</title>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001203
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001204 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001205 The use of Make by itself is very common in both proprietary
1206 and open-source software.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001207 Unfortunately, Makefiles are often not written with
1208 cross-compilation in mind.
1209 Thus, <filename>devtool add</filename> often cannot do very
1210 much to ensure that these Makefiles build correctly.
1211 It is very common, for example, to explicitly call
1212 <filename>gcc</filename> instead of using the
1213 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
1214 variable.
1215 Usually, in a cross-compilation environment,
1216 <filename>gcc</filename> is the compiler for the build host
1217 and the cross-compiler is named something similar to
1218 <filename>arm-poky-linux-gnueabi-gcc</filename> and might
Brad Bishop316dfdd2018-06-25 12:45:53 -04001219 require arguments (e.g. to point to the associated sysroot
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001220 for the target machine).
1221 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001222
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001223 <para>
1224 When writing a recipe for Makefile-only software, keep the
1225 following in mind:
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001226 <itemizedlist>
1227 <listitem><para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001228 You probably need to patch the Makefile to use
1229 variables instead of hardcoding tools within the
1230 toolchain such as <filename>gcc</filename> and
1231 <filename>g++</filename>.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001232 </para></listitem>
1233 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001234 The environment in which Make runs is set up with
1235 various standard variables for compilation (e.g.
1236 <filename>CC</filename>, <filename>CXX</filename>, and
1237 so forth) in a similar manner to the environment set
1238 up by the SDK's environment setup script.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001239 One easy way to see these variables is to run the
1240 <filename>devtool build</filename> command on the
1241 recipe and then look in
1242 <filename>oe-logs/run.do_compile</filename>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001243 Towards the top of this file, a list of environment
1244 variables exists that are being set.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001245 You can take advantage of these variables within the
1246 Makefile.
1247 </para></listitem>
1248 <listitem><para>
1249 If the Makefile sets a default for a variable using "=",
1250 that default overrides the value set in the environment,
1251 which is usually not desirable.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001252 For this case, you can either patch the Makefile
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001253 so it sets the default using the "?=" operator, or
1254 you can alternatively force the value on the
1255 <filename>make</filename> command line.
1256 To force the value on the command line, add the
1257 variable setting to
1258 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink>
1259 or
1260 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1261 within the recipe.
1262 Here is an example using <filename>EXTRA_OEMAKE</filename>:
1263 <literallayout class='monospaced'>
1264 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
1265 </literallayout>
1266 In the above example, single quotes are used around the
1267 variable settings as the values are likely to contain
1268 spaces because required default options are passed to
1269 the compiler.
1270 </para></listitem>
1271 <listitem><para>
1272 Hardcoding paths inside Makefiles is often problematic
1273 in a cross-compilation environment.
1274 This is particularly true because those hardcoded paths
1275 often point to locations on the build host and thus
1276 will either be read-only or will introduce
Brad Bishop316dfdd2018-06-25 12:45:53 -04001277 contamination into the cross-compilation because they
1278 are specific to the build host rather than the target.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001279 Patching the Makefile to use prefix variables or other
Brad Bishop316dfdd2018-06-25 12:45:53 -04001280 path variables is usually the way to handle this
1281 situation.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001282 </para></listitem>
1283 <listitem><para>
1284 Sometimes a Makefile runs target-specific commands such
1285 as <filename>ldconfig</filename>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001286 For such cases, you might be able to apply patches that
1287 remove these commands from the Makefile.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001288 </para></listitem>
1289 </itemizedlist>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001290 </para>
1291 </section>
1292
1293 <section id='sdk-adding-native-tools'>
1294 <title>Adding Native Tools</title>
1295
1296 <para>
1297 Often, you need to build additional tools that run on the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001298 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
1299 as opposed to the target.
1300 You should indicate this requirement by using one of the
1301 following methods when you run
1302 <filename>devtool add</filename>:
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001303 <itemizedlist>
1304 <listitem><para>
1305 Specify the name of the recipe such that it ends
1306 with "-native".
1307 Specifying the name like this produces a recipe that
1308 only builds for the build host.
1309 </para></listitem>
1310 <listitem><para>
1311 Specify the "&dash;&dash;also-native" option with the
1312 <filename>devtool add</filename> command.
1313 Specifying this option creates a recipe file that still
1314 builds for the target but also creates a variant with
1315 a "-native" suffix that builds for the build host.
1316 </para></listitem>
1317 </itemizedlist>
1318 <note>
1319 If you need to add a tool that is shipped as part of a
1320 source tree that builds code for the target, you can
1321 typically accomplish this by building the native and target
1322 parts separately rather than within the same compilation
1323 process.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001324 Realize though that with the "&dash;&dash;also-native"
1325 option, you can add the tool using just one recipe file.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001326 </note>
1327 </para>
1328 </section>
1329
1330 <section id='sdk-adding-node-js-modules'>
1331 <title>Adding Node.js Modules</title>
1332
1333 <para>
1334 You can use the <filename>devtool add</filename> command two
1335 different ways to add Node.js modules: 1) Through
1336 <filename>npm</filename> and, 2) from a repository or local
1337 source.
1338 </para>
1339
1340 <para>
1341 Use the following form to add Node.js modules through
1342 <filename>npm</filename>:
1343 <literallayout class='monospaced'>
1344 $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
1345 </literallayout>
1346 The name and version parameters are mandatory.
1347 Lockdown and shrinkwrap files are generated and pointed to by
1348 the recipe in order to freeze the version that is fetched for
1349 the dependencies according to the first time.
1350 This also saves checksums that are verified on future fetches.
1351 Together, these behaviors ensure the reproducibility and
1352 integrity of the build.
1353 <note><title>Notes</title>
1354 <itemizedlist>
1355 <listitem><para>
1356 You must use quotes around the URL.
1357 The <filename>devtool add</filename> does not require
1358 the quotes, but the shell considers ";" as a splitter
1359 between multiple commands.
1360 Thus, without the quotes,
1361 <filename>devtool add</filename> does not receive the
1362 other parts, which results in several "command not
1363 found" errors.
1364 </para></listitem>
1365 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001366 In order to support adding Node.js modules, a
1367 <filename>nodejs</filename> recipe must be part
1368 of your SDK.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001369 </para></listitem>
1370 </itemizedlist>
1371 </note>
1372 </para>
1373
1374 <para>
1375 As mentioned earlier, you can also add Node.js modules
1376 directly from a repository or local source tree.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001377 To add modules this way, use <filename>devtool add</filename>
1378 in the following form:
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001379 <literallayout class='monospaced'>
1380 $ devtool add https://github.com/diversario/node-ssdp
1381 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001382 In this example, <filename>devtool</filename> fetches the
1383 specified Git repository, detects the code as Node.js
1384 code, fetches dependencies using <filename>npm</filename>, and
1385 sets
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001386 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1387 accordingly.
1388 </para>
1389 </section>
1390 </section>
1391
1392 <section id='sdk-working-with-recipes'>
1393 <title>Working With Recipes</title>
1394
1395 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001396 When building a recipe using the
1397 <filename>devtool build</filename> command, the typical build
1398 progresses as follows:
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001399 <orderedlist>
1400 <listitem><para>
1401 Fetch the source
1402 </para></listitem>
1403 <listitem><para>
1404 Unpack the source
1405 </para></listitem>
1406 <listitem><para>
1407 Configure the source
1408 </para></listitem>
1409 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001410 Compile the source
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001411 </para></listitem>
1412 <listitem><para>
1413 Install the build output
1414 </para></listitem>
1415 <listitem><para>
1416 Package the installed output
1417 </para></listitem>
1418 </orderedlist>
1419 For recipes in the workspace, fetching and unpacking is disabled
1420 as the source tree has already been prepared and is persistent.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001421 Each of these build steps is defined as a function (task), usually
1422 with a "do_" prefix (e.g.
1423 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>,
1424 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>,
1425 and so forth).
1426 These functions are typically shell scripts but can instead be
1427 written in Python.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001428 </para>
1429
1430 <para>
1431 If you look at the contents of a recipe, you will see that the
1432 recipe does not include complete instructions for building the
1433 software.
1434 Instead, common functionality is encapsulated in classes inherited
Brad Bishop316dfdd2018-06-25 12:45:53 -04001435 with the <filename>inherit</filename> directive.
1436 This technique leaves the recipe to describe just the things that
1437 are specific to the software being built.
1438 A
1439 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
1440 class exists that is implicitly inherited by all recipes and
1441 provides the functionality that most recipes typically need.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001442 </para>
1443
1444 <para>
1445 The remainder of this section presents information useful when
1446 working with recipes.
1447 </para>
1448
1449 <section id='sdk-finding-logs-and-work-files'>
1450 <title>Finding Logs and Work Files</title>
1451
1452 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001453 After the first run of the <filename>devtool build</filename>
1454 command, recipes that were previously created using the
1455 <filename>devtool add</filename> command or whose sources were
1456 modified using the <filename>devtool modify</filename>
1457 command contain symbolic links created within the source tree:
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001458 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001459 <listitem><para>
1460 <filename>oe-logs</filename>:
1461 This link points to the directory in which log files
1462 and run scripts for each build step are created.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001463 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001464 <listitem><para>
1465 <filename>oe-workdir</filename>:
1466 This link points to the temporary work area for the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001467 recipe.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001468 The following locations under
1469 <filename>oe-workdir</filename> are particularly
1470 useful:
1471 <itemizedlist>
1472 <listitem><para>
1473 <filename>image/</filename>:
1474 Contains all of the files installed during
1475 the
1476 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1477 stage.
1478 Within a recipe, this directory is referred
1479 to by the expression
1480 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
1481 </para></listitem>
1482 <listitem><para>
1483 <filename>sysroot-destdir/</filename>:
1484 Contains a subset of files installed within
1485 <filename>do_install</filename> that have
1486 been put into the shared sysroot.
1487 For more information, see the
1488 "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
1489 section.
1490 </para></listitem>
1491 <listitem><para>
1492 <filename>packages-split/</filename>:
1493 Contains subdirectories for each package
1494 produced by the recipe.
1495 For more information, see the
1496 "<link linkend='sdk-packaging'>Packaging</link>"
1497 section.
1498 </para></listitem>
1499 </itemizedlist>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001500 </para></listitem>
1501 </itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001502 You can use these links to get more information on what is
1503 happening at each build step.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001504 </para>
1505 </section>
1506
1507 <section id='sdk-setting-configure-arguments'>
1508 <title>Setting Configure Arguments</title>
1509
1510 <para>
1511 If the software your recipe is building uses GNU autoconf,
1512 then a fixed set of arguments is passed to it to enable
1513 cross-compilation plus any extras specified by
1514 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1515 or
1516 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1517 set within the recipe.
1518 If you wish to pass additional options, add them to
1519 <filename>EXTRA_OECONF</filename> or
1520 <filename>PACKAGECONFIG_CONFARGS</filename>.
1521 Other supported build tools have similar variables
1522 (e.g.
1523 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
1524 for CMake,
1525 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink>
1526 for Scons, and so forth).
1527 If you need to pass anything on the <filename>make</filename>
1528 command line, you can use <filename>EXTRA_OEMAKE</filename> or the
1529 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1530 variables to do so.
1531 </para>
1532
1533 <para>
1534 You can use the <filename>devtool configure-help</filename> command
1535 to help you set the arguments listed in the previous paragraph.
1536 The command determines the exact options being passed, and shows
1537 them to you along with any custom arguments specified through
1538 <filename>EXTRA_OECONF</filename> or
1539 <filename>PACKAGECONFIG_CONFARGS</filename>.
1540 If applicable, the command also shows you the output of the
1541 configure script's "&dash;&dash;help" option as a reference.
1542 </para>
1543 </section>
1544
1545 <section id='sdk-sharing-files-between-recipes'>
1546 <title>Sharing Files Between Recipes</title>
1547
1548 <para>
1549 Recipes often need to use files provided by other recipes on
Brad Bishop316dfdd2018-06-25 12:45:53 -04001550 the
1551 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001552 For example, an application linking to a common library needs
1553 access to the library itself and its associated headers.
1554 The way this access is accomplished within the extensible SDK is
1555 through the sysroot.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001556 One sysroot exists per "machine" for which the SDK is being
1557 built.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001558 In practical terms, this means a sysroot exists for the target
1559 machine, and a sysroot exists for the build host.
1560 </para>
1561
1562 <para>
1563 Recipes should never write files directly into the sysroot.
1564 Instead, files should be installed into standard locations
1565 during the
1566 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1567 task within the
1568 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
1569 directory.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001570 A subset of these files automatically goes into the sysroot.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001571 The reason for this limitation is that almost all files that go
1572 into the sysroot are cataloged in manifests in order to ensure
1573 they can be removed later when a recipe is modified or removed.
1574 Thus, the sysroot is able to remain free from stale files.
1575 </para>
1576 </section>
1577
1578 <section id='sdk-packaging'>
1579 <title>Packaging</title>
1580
1581 <para>
1582 Packaging is not always particularly relevant within the
1583 extensible SDK.
1584 However, if you examine how build output gets into the final image
1585 on the target device, it is important to understand packaging
1586 because the contents of the image are expressed in terms of
1587 packages and not recipes.
1588 </para>
1589
1590 <para>
1591 During the
1592 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
1593 task, files installed during the
1594 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001595 task are split into one main package, which is almost always
1596 named the same as the recipe, and into several other packages.
1597 This separation exists because not all of those installed files
1598 are useful in every image.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001599 For example, you probably do not need any of the documentation
1600 installed in a production image.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001601 Consequently, for each recipe the documentation files are
1602 separated into a <filename>-doc</filename> package.
1603 Recipes that package software containing optional modules or
1604 plugins might undergo additional package splitting as well.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001605 </para>
1606
1607 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001608 After building a recipe, you can see where files have gone by
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001609 looking in the <filename>oe-workdir/packages-split</filename>
1610 directory, which contains a subdirectory for each package.
1611 Apart from some advanced cases, the
1612 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
1613 and
1614 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1615 variables controls splitting.
1616 The <filename>PACKAGES</filename> variable lists all of the
1617 packages to be produced, while the <filename>FILES</filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001618 variable specifies which files to include in each package by
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001619 using an override to specify the package.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001620 For example, <filename>FILES_${PN}</filename> specifies the
1621 files to go into the main package (i.e. the main package has
1622 the same name as the recipe and
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001623 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
1624 evaluates to the recipe name).
Brad Bishop316dfdd2018-06-25 12:45:53 -04001625 The order of the <filename>PACKAGES</filename> value is
1626 significant.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001627 For each installed file, the first package whose
Brad Bishop316dfdd2018-06-25 12:45:53 -04001628 <filename>FILES</filename> value matches the file is the
1629 package into which the file goes.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001630 Defaults exist for both the <filename>PACKAGES</filename> and
1631 <filename>FILES</filename> variables.
1632 Consequently, you might find you do not even need to set these
1633 variables in your recipe unless the software the recipe is
1634 building installs files into non-standard locations.
1635 </para>
1636 </section>
1637 </section>
1638
1639 <section id='sdk-restoring-the-target-device-to-its-original-state'>
1640 <title>Restoring the Target Device to its Original State</title>
1641
1642 <para>
1643 If you use the <filename>devtool deploy-target</filename>
1644 command to write a recipe's build output to the target, and
1645 you are working on an existing component of the system, then you
1646 might find yourself in a situation where you need to restore the
1647 original files that existed prior to running the
1648 <filename>devtool deploy-target</filename> command.
1649 Because the <filename>devtool deploy-target</filename> command
1650 backs up any files it overwrites, you can use the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001651 <filename>devtool undeploy-target</filename> command to restore
1652 those files and remove any other files the recipe deployed.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001653 Consider the following example:
1654 <literallayout class='monospaced'>
1655 $ devtool undeploy-target lighttpd root@192.168.7.2
1656 </literallayout>
1657 If you have deployed multiple applications, you can remove them
Brad Bishop316dfdd2018-06-25 12:45:53 -04001658 all using the "-a" option thus restoring the target device to its
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001659 original state:
1660 <literallayout class='monospaced'>
1661 $ devtool undeploy-target -a root@192.168.7.2
1662 </literallayout>
1663 Information about files deployed to the target as well as any
1664 backed up files are stored on the target itself.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001665 This storage, of course, requires some additional space
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001666 on the target machine.
1667 <note>
1668 The <filename>devtool deploy-target</filename> and
Brad Bishop316dfdd2018-06-25 12:45:53 -04001669 <filename>devtool undeploy-target</filename> commands do not
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001670 currently interact with any package management system on the
1671 target device (e.g. RPM or OPKG).
Brad Bishop316dfdd2018-06-25 12:45:53 -04001672 Consequently, you should not intermingle
1673 <filename>devtool deploy-target</filename> and package
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001674 manager operations on the target device.
1675 Doing so could result in a conflicting set of files.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001676 </note>
1677 </para>
1678 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001679
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001680 <section id='sdk-installing-additional-items-into-the-extensible-sdk'>
1681 <title>Installing Additional Items Into the Extensible SDK</title>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001682
1683 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001684 Out of the box the extensible SDK typically only comes with a small
1685 number of tools and libraries.
1686 A minimal SDK starts mostly empty and is populated on-demand.
1687 Sometimes you must explicitly install extra items into the SDK.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001688 If you need these extra items, you can first search for the items
1689 using the <filename>devtool search</filename> command.
1690 For example, suppose you need to link to libGL but you are not sure
Brad Bishop316dfdd2018-06-25 12:45:53 -04001691 which recipe provides libGL.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001692 You can use the following command to find out:
1693 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001694 $ devtool search libGL
1695 mesa A free implementation of the OpenGL API
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001696 </literallayout>
1697 Once you know the recipe (i.e. <filename>mesa</filename> in this
1698 example), you can install it:
1699 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001700 $ devtool sdk-install mesa
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001701 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001702 By default, the <filename>devtool sdk-install</filename> command
1703 assumes the item is available in pre-built form from your SDK
1704 provider.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001705 If the item is not available and it is acceptable to build the item
1706 from source, you can add the "-s" option as follows:
1707 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001708 $ devtool sdk-install -s mesa
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001709 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001710 It is important to remember that building the item from source
1711 takes significantly longer than installing the pre-built artifact.
1712 Also, if no recipe exists for the item you want to add to the SDK,
1713 you must instead add the item using the
1714 <filename>devtool add</filename> command.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001715 </para>
1716 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001717
Brad Bishopd5ae7d92018-06-14 09:52:03 -07001718 <section id='sdk-applying-updates-to-an-installed-extensible-sdk'>
1719 <title>Applying Updates to an Installed Extensible SDK</title>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001720
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001721 <para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -07001722 If you are working with an installed extensible SDK that gets
1723 occasionally updated (e.g. a third-party SDK), then you will need
1724 to manually "pull down" the updates into the installed SDK.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001725 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001726
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001727 <para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -07001728 To update your installed SDK, use <filename>devtool</filename> as
1729 follows:
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001730 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001731 $ devtool sdk-update
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001732 </literallayout>
1733 The previous command assumes your SDK provider has set the default
Brad Bishopd5ae7d92018-06-14 09:52:03 -07001734 update URL for you through the
1735 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
1736 variable as described in the
1737 "<link linkend='sdk-providing-updates-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</link>"
1738 section.
1739 If the SDK provider has not set that default URL, you need to
1740 specify it yourself in the command as follows:
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001741 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001742 $ devtool sdk-update <replaceable>path_to_update_directory</replaceable>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001743 </literallayout>
1744 <note>
Brad Bishopd5ae7d92018-06-14 09:52:03 -07001745 The URL needs to point specifically to a published SDK and
1746 not to an SDK installer that you would download and install.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001747 </note>
1748 </para>
1749 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001750
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001751 <section id='sdk-creating-a-derivative-sdk-with-additional-components'>
1752 <title>Creating a Derivative SDK With Additional Components</title>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001753
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001754 <para>
1755 You might need to produce an SDK that contains your own custom
Brad Bishop316dfdd2018-06-25 12:45:53 -04001756 libraries.
1757 A good example would be if you were a vendor with customers that
1758 use your SDK to build their own platform-specific software and
1759 those customers need an SDK that has custom libraries.
1760 In such a case, you can produce a derivative SDK based on the
1761 currently installed SDK fairly easily by following these steps:
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001762 <orderedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001763 <listitem><para>
1764 If necessary, install an extensible SDK that
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001765 you want to use as a base for your derivative SDK.
1766 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001767 <listitem><para>
1768 Source the environment script for the SDK.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001769 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001770 <listitem><para>
1771 Add the extra libraries or other components you want by
1772 using the <filename>devtool add</filename> command.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001773 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001774 <listitem><para>
1775 Run the <filename>devtool build-sdk</filename> command.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001776 </para></listitem>
1777 </orderedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001778 The previous steps take the recipes added to the workspace and
1779 construct a new SDK installer that contains those recipes and the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001780 resulting binary artifacts.
1781 The recipes go into their own separate layer in the constructed
Brad Bishop316dfdd2018-06-25 12:45:53 -04001782 derivative SDK, which leaves the workspace clean and ready for
1783 users to add their own recipes.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001784 </para>
1785 </section>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001786</chapter>
1787<!--
1788vim: expandtab tw=80 ts=4
1789-->