summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-devtool-reference.xml
blob: 90330f1a35b5a3b438eb18b7d073556305a082e6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<chapter id='ref-devtool-reference'>
    <title><filename>devtool</filename> Quick Reference</title>

    <para>
        The <filename>devtool</filename> command-line tool provides a number
        of features that help you build, test, and package software.
        This command is available alongside the <filename>bitbake</filename>
        command.
        Additionally, the <filename>devtool</filename> command is a key
        part of the extensible SDK.
    </para>

    <para>
        This chapter provides a Quick Reference for the
        <filename>devtool</filename> command.
        For more information on how to apply the command when using the
        extensible SDK, see the
        "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
        section in the Yocto Project Software Development Kit (SDK) Developer's
        Guide.
    </para>

    <section id='devtool-getting-help'>
        <title>Getting Help</title>

        <para>
            The <filename>devtool</filename> command line is organized
            similarly to Git in that it has a number of sub-commands for
            each function.
            You can run <filename>devtool --help</filename> to see all
            the commands:
            <literallayout class='monospaced'>
     $ devtool --help
     usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
                    [--color COLOR] [-h]
                    &lt;subcommand&gt; ...

     OpenEmbedded development tool

     options:
       --basepath BASEPATH  Base directory of SDK / build directory
       --bbpath BBPATH      Explicitly specify the BBPATH, rather than getting it
                            from the metadata
       -d, --debug          Enable debug output
       -q, --quiet          Print only errors
       --color COLOR        Colorize output (where COLOR is auto, always, never)
       -h, --help           show this help message and exit

     subcommands:
       Beginning work on a recipe:
         add                  Add a new recipe
         modify               Modify the source for an existing recipe
         upgrade              Upgrade an existing recipe
       Getting information:
         status               Show workspace status
         search               Search available recipes
       Working on a recipe in the workspace:
         edit-recipe          Edit a recipe file in your workspace
         configure-help       Get help on configure script options
         build                Build a recipe
         update-recipe        Apply changes from external source tree to recipe
         reset                Remove a recipe from your workspace
         finish               Finish working on a recipe in your workspace
       Testing changes on target:
         deploy-target        Deploy recipe output files to live target machine
         undeploy-target      Undeploy recipe output files in live target machine
         build-image          Build image including workspace recipe packages
       Advanced:
         create-workspace     Set up workspace in an alternative location
         extract              Extract the source for an existing recipe
         sync                 Synchronize the source tree for an existing recipe
     Use devtool &lt;subcommand&gt; --help to get help on a specific command
            </literallayout>
        </para>

        <para>
                As directed in the general help output, you can get more
                syntax on a specific command by providing the command
                name and using <filename>--help</filename>:
            <literallayout class='monospaced'>
     $ devtool add --help
     usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
                        [--version VERSION] [--no-git] [--autorev] [--binary]
                        [--also-native] [--src-subdir SUBDIR]
                        [recipename] [srctree] [fetchuri]

     Adds a new recipe to the workspace to build a specified source tree. Can
     optionally fetch a remote URI and unpack it to create the source tree.

     arguments:
       recipename            Name for new recipe to add (just name - no version,
                             path or extension). If not specified, will attempt to
                             auto-detect it.
       srctree               Path to external source tree. If not specified, a
                             subdirectory of
                             /home/scottrif/poky/build/workspace/sources will be
                             used.
       fetchuri              Fetch the specified URI and extract it to create the
                             source tree

     options:
       -h, --help            show this help message and exit
       --same-dir, -s        Build in same directory as source
       --no-same-dir         Force build in a separate build directory
       --fetch URI, -f URI   Fetch the specified URI and extract it to create the
                             source tree (deprecated - pass as positional argument
                             instead)
       --version VERSION, -V VERSION
                             Version to use within recipe (PV)
       --no-git, -g          If fetching source, do not set up source tree as a git
                             repository
       --autorev, -a         When fetching from a git repository, set SRCREV in the
                             recipe to a floating revision instead of fixed
       --binary, -b          Treat the source tree as something that should be
                             installed verbatim (no compilation, same directory
                             structure). Useful with binary packages e.g. RPMs.
       --also-native         Also add native variant (i.e. support building recipe
                             for the build host as well as the target machine)
       --src-subdir SUBDIR   Specify subdirectory within source tree to use
            </literallayout>
        </para>
    </section>

    <section id='devtool-the-workspace-layer-structure'>
        <title>The Workspace Layer Structure</title>

        <para>
            <filename>devtool</filename> uses a "Workspace" layer
            in which to accomplish builds.
            This layer is not specific to any single
            <filename>devtool</filename> command but is rather a common
            working area used across the tool.
        </para>

        <para>
            The following figure shows the workspace structure:
        </para>

        <para>
            <imagedata fileref="figures/build-workspace-directory.png"
                width="6in" depth="5in" align="left" scale="70" />
        </para>

        <para>
            <literallayout class='monospaced'>
     attic - A directory created if devtool believes it preserve
             anything when you run "devtool reset".  For example, if you
             run "devtool add", make changes to the recipe, and then
             run "devtool reset", devtool takes notice that the file has
             been changed and moves it into the attic should you still
             want the recipe.

     README - Provides information on what is in workspace layer and how to
              manage it.

     .devtool_md5 - A checksum file used by devtool.

     appends - A directory that contains *.bbappend files, which point to
               external source.

     conf - A configuration directory that contains the layer.conf file.

     recipes - A directory containing recipes.  This directory contains a
               folder for each directory added whose name matches that of the
               added recipe.  devtool places the <replaceable>recipe</replaceable>.bb file
               within that sub-directory.

     sources - A directory containing a working copy of the source files used
               when building the recipe.  This is the default directory used
               as the location of the source tree when you do not provide a
               source tree path.  This directory contains a folder for each
               set of source files matched to a corresponding recipe.
            </literallayout>
        </para>
    </section>

    <section id='devtool-adding-a-new-recipe-to-the-workspace'>
        <title>Adding a New Recipe to the Workspace Layer</title>

        <para>
            Use the <filename>devtool add</filename> command to add a new recipe
            to the workspace layer.
            The recipe you add should not exist -
            <filename>devtool</filename> creates it for you.
            The source files the recipe uses should exist in an external
            area.
        </para>

        <para>
            The following example creates and adds a new recipe named
            <filename>jackson</filename> to a workspace layer the tool creates.
            The source code built by the recipes resides in
            <filename>/home/scottrif/sources/jackson</filename>:
            <literallayout class='monospaced'>
     $ devtool add jackson /home/scottrif/sources/jackson
            </literallayout>
        </para>

        <para>
            If you add a recipe and the workspace layer does not exist,
            the command creates the layer and populates it as
            described in
            "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>"
            section.
        </para>

        <para>
            Running <filename>devtool add</filename> when the
            workspace layer exists causes the tool to add the recipe,
            append files, and source files into the existing workspace layer.
            The <filename>.bbappend</filename> file is created to point
            to the external source tree.
        </para>

        <note>
            If your recipe has runtime dependencies defined, you must be sure
            that these packages exist on the target hardware before attempting
            to run your application.
            If dependent packages (e.g. libraries) do not exist on the target,
            your application, when run, will fail to find those functions.
            For more information, see the
            "<link linkend='devtool-deploying-your-software-on-the-target-machine'>Deploying Your Software on the Target Machine</link>"
            section.
        </note>
    </section>

    <section id='devtool-extracting-the-source-for-an-existing-recipe'>
        <title>Extracting the Source for an Existing Recipe</title>

        <para>
            Use the <filename>devtool extract</filename> command to
            extract the source for an existing recipe.
            When you use this command, you must supply the root name
            of the recipe (i.e. no version, paths, or extensions), and
            you must supply the directory to which you want the source
            extracted.
        </para>

        <para>
            Additional command options let you control the name of a
            development branch into which you can checkout the source
            and whether or not to keep a temporary directory, which is
            useful for debugging.
        </para>
    </section>

    <section id='devtool-synchronizing-a-recipes-extracted-source-tree'>
        <title>Synchronizing a Recipe's Extracted Source Tree</title>

        <para>
            Use the <filename>devtool sync</filename> command to
            synchronize a previously extracted source tree for an
            existing recipe.
            When you use this command, you must supply the root name
            of the recipe (i.e. no version, paths, or extensions), and
            you must supply the directory to which you want the source
            extracted.
        </para>

        <para>
            Additional command options let you control the name of a
            development branch into which you can checkout the source
            and whether or not to keep a temporary directory, which is
            useful for debugging.
        </para>
    </section>

    <section id='devtool-modifying-a-recipe'>
        <title>Modifying an Existing Recipe</title>

        <para>
            Use the <filename>devtool modify</filename> command to begin
            modifying the source of an existing recipe.
            This command is very similar to the
            <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></ulink>
            command except that it does not physically create the
            recipe in the workspace layer because the recipe already
            exists in an another layer.
        </para>

        <para>
            The <filename>devtool modify</filename> command extracts the
            source for a recipe, sets it up as a Git repository if the
            source had not already been fetched from Git, checks out a
            branch for development, and applies any patches from the recipe
            as commits on top.
            You can use the following command to checkout the source
            files:
            <literallayout class='monospaced'>
     $ devtool modify <replaceable>recipe</replaceable>
            </literallayout>
            Using the above command form, <filename>devtool</filename> uses
            the existing recipe's
            <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
            statement to locate the upstream source, extracts the source
            into the default sources location in the workspace.
            The default development branch used is "devtool".
        </para>
    </section>

    <section id='devtool-edit-an-existing-recipe'>
        <title>Edit an Existing Recipe</title>

        <para>
            Use the <filename>devtool edit-recipe</filename> command
            to run the default editor, which is identified using the
            <filename>EDITOR</filename> variable, on the specified recipe.
        </para>

        <para>
            When you use the <filename>devtool edit-recipe</filename>
            command, you must supply the root name of the recipe
            (i.e. no version, paths, or extensions).
            Also, the recipe file itself must reside in the workspace
            as a result of the <filename>devtool add</filename> or
            <filename>devtool upgrade</filename> commands.
            However, you can override that requirement by using the
            "-a" or "--any-recipe" option.
            Using either of these options allows you to edit any recipe
            regardless of its location.
        </para>
    </section>

    <section id='devtool-updating-a-recipe'>
        <title>Updating a Recipe</title>

        <para>
            Use the <filename>devtool update-recipe</filename> command to
            update your recipe with patches that reflect changes you make
            to the source files.
            For example, if you know you are going to work on some
            code, you could first use the
            <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-modifying-a-recipe'><filename>devtool modify</filename></ulink>
            command to extract the code and set up the workspace.
            After which, you could modify, compile, and test the code.
        </para>

        <para>
            When you are satisfied with the results and you have committed
            your changes to the Git repository, you can then
            run the <filename>devtool update-recipe</filename> to create the
            patches and update the recipe:
            <literallayout class='monospaced'>
     $ devtool update-recipe <replaceable>recipe</replaceable>
            </literallayout>
            If you run the <filename>devtool update-recipe</filename>
            without committing your changes, the command ignores the
            changes.
        </para>

        <para>
            Often, you might want to apply customizations made to your
            software in your own layer rather than apply them to the
            original recipe.
            If so, you can use the
            <filename>-a</filename> or <filename>--append</filename>
            option with the <filename>devtool update-recipe</filename>
            command.
            These options allow you to specify the layer into which to
            write an append file:
            <literallayout class='monospaced'>
     $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable>
            </literallayout>
            The <filename>*.bbappend</filename> file is created at the
            appropriate path within the specified layer directory, which
            may or may not be in your <filename>bblayers.conf</filename>
            file.
            If an append file already exists, the command updates it
            appropriately.
        </para>
    </section>

    <section id='devtool-upgrading-a-recipe'>
        <title>Upgrading a Recipe</title>

        <para>
            Use the <filename>devtool upgrade</filename> command
            to upgrade an existing recipe to a new upstream version.
            The command puts the upgraded recipe file into the
            workspace along with any associated files, and extracts
            the source tree to a specified location should patches
            need rebased or added to as a result of the upgrade.
        </para>

        <para>
            When you use the <filename>devtool upgrade</filename> command,
            you must supply the root name of the recipe (i.e. no version,
            paths, or extensions), and you must supply the directory
            to which you want the source extracted.
            Additional command options let you control things such as
            the version number to which you want to upgrade (i.e. the
            <link linkend='var-PV'><filename>PV</filename></link>),
            the source revision to which you want to upgrade (i.e. the
            <link linkend='var-SRCREV'><filename>SRCREV</filename></link>,
            whether or not to apply patches, and so forth.
        </para>
    </section>

    <section id='devtool-resetting-a-recipe'>
        <title>Resetting a Recipe</title>

        <para>
            Use the <filename>devtool reset</filename> command to remove a
            recipe and its configuration (e.g. the corresponding
            <filename>.bbappend</filename> file) from the workspace layer.
            Realize that this command deletes the recipe and the
            append file.
            The command does not physically move them for you.
            Consequently, you must be sure to physically relocate your
            updated recipe and the append file outside of the workspace
            layer before running the <filename>devtool reset</filename>
            command.
        </para>

        <para>
            If the <filename>devtool reset</filename> command detects that
            the recipe or the append files have been modified, the
            command preserves the modified files in a separate "attic"
            subdirectory under the workspace layer.
        </para>

        <para>
            Here is an example that resets the workspace directory that
            contains the <filename>mtr</filename> recipe:
            <literallayout class='monospaced'>
     $ devtool reset mtr
     NOTE: Cleaning sysroot for recipe mtr...
     NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no
        longer need it then please delete it manually
     $
            </literallayout>
        </para>
    </section>

    <section id='devtool-building-your-recipe'>
        <title>Building Your Recipe</title>

        <para>
            Use the <filename>devtool build</filename> command to cause the
            OpenEmbedded build system to build your recipe.
            The <filename>devtool build</filename> command is equivalent to
            <filename>bitbake -c populate_sysroot</filename>.
        </para>

        <para>
            When you use the <filename>devtool build</filename> command,
            you must supply the root name of the recipe (i.e. no version,
            paths, or extensions).
            You can use either the "-s" or the "--disable-parallel-make"
            option to disable parallel makes during the build.
            Here is an example:
            <literallayout class='monospaced'>
     $ devtool build <replaceable>recipe</replaceable>
            </literallayout>
        </para>
    </section>

    <section id='devtool-building-your-image'>
        <title>Building Your Image</title>

        <para>
            Use the <filename>devtool build-image</filename> command
            to build an image, extending it to include packages from
            recipes in the workspace.
            Using this command is useful when you want an image that
            ready for immediate deployment onto a device for testing.
            For proper integration into a final image, you need to
            edit your custom image recipe appropriately.
        </para>

        <para>
            When you use the <filename>devtool build-image</filename>
            command, you must supply the name of the image.
            This command has no command line options:
            <literallayout class='monospaced'>
     $ devtool build-image <replaceable>image</replaceable>
            </literallayout>
        </para>
    </section>

    <section id='devtool-deploying-your-software-on-the-target-machine'>
        <title>Deploying Your Software on the Target Machine</title>

        <para>
            Use the <filename>devtool deploy-target</filename> command to
            deploy the recipe's build output to the live target machine:
            <literallayout class='monospaced'>
     $ devtool deploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
            </literallayout>
            The <replaceable>target</replaceable> is the address of the
            target machine, which must be running an SSH server (i.e.
            <filename>user@hostname[:destdir]</filename>).
        </para>

        <para>
            This command deploys all files installed during the
            <link linkend='ref-tasks-install'><filename>do_install</filename></link>
            task.
            Furthermore, you do not need to have package management enabled
            within the target machine.
            If you do, the package manager is bypassed.
            <note><title>Notes</title>
                <para>
                    The <filename>deploy-target</filename>
                    functionality is for development only.
                    You should never use it to update an image that will be
                    used in production.
                </para>
            </note>
        </para>

        <para>
            Some conditions exist that could prevent a deployed application
            from behaving as expected.
            When both of the following conditions exist, your application has
            the potential to not behave correctly when run on the target:
            <itemizedlist>
                <listitem><para>
                    You are deploying a new application to the target that
                    has correctly defined runtime dependencies defined in
                    recipe you used to build the application.
                    </para></listitem>
                <listitem><para>
                    The target does not physically have the packages on which
                    the application depends installed.
                    </para></listitem>
            </itemizedlist>
            If both of these conditions exist, your application will not
            behave as expected.
            The reason for this misbehavior is because the
            <filename>devtool deploy-target</filename> command does not deploy
            the packages (e.g. libraries) on which your new application
            depends.
            The assumption is that the packages are already on the target.
            Consequently, when a runtime call is made in the application
            for a dependent function (e.g. a library call), the function
            cannot be found.
        </para>

        <para>
            To be sure you have all the dependencies local to the target, you
            need to be sure that the packages are pre-deployed (installed)
            on the target before attempting to run your application.
        </para>
    </section>

    <section id='devtool-removing-your-software-from-the-target-machine'>
        <title>Removing Your Software from the Target Machine</title>

        <para>
            Use the <filename>devtool undeploy-target</filename> command to
            remove deployed build output from the target machine.
            For the <filename>devtool undeploy-target</filename> command to
            work, you must have previously used the
            <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></ulink>
            command.
            <literallayout class='monospaced'>
     $ devtool undeploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
            </literallayout>
            The <replaceable>target</replaceable> is the address of the
            target machine, which must be running an SSH server (i.e.
            <filename>user@hostname</filename>).
        </para>
    </section>

    <section id='devtool-creating-the-workspace'>
        <title>Creating the Workspace Layer in an Alternative Location</title>

        <para>
            Use the <filename>devtool create-workspace</filename> command to
            create a new workspace layer in your
            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
            When you create a new workspace layer, it is populated with the
            <filename>README</filename> file and the
            <filename>conf</filename> directory only.
        </para>

        <para>
            The following example creates a new workspace layer in your
            current working and by default names the workspace layer
            "workspace":
            <literallayout class='monospaced'>
     $ devtool create-workspace
            </literallayout>
        </para>

        <para>
            You can create a workspace layer anywhere by supplying
            a pathname with the command.
            The following command creates a new workspace layer named
            "new-workspace":
            <literallayout class='monospaced'>
     $ devtool create-workspace /home/scottrif/new-workspace
            </literallayout>
        </para>
    </section>

    <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'>
        <title>Get the Status of the Recipes in Your Workspace</title>

        <para>
            Use the <filename>devtool status</filename> command to
            list the recipes currently in your workspace.
            Information includes the paths to their respective
            external source trees.
        </para>

        <para>
            The <filename>devtool status</filename> command has no
            command-line options:
            <literallayout class='monospaced'>
     $ devtool status
            </literallayout>
            Following is sample output after using
            <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></ulink>
            to create and add the <filename>mtr_0.86.bb</filename> recipe
            to the <filename>workspace</filename> directory:
            <literallayout class='monospaced'>
     $ devtool status
     mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
     $
            </literallayout>
        </para>
    </section>

    <section id='devtool-search-for-available-target-recipes'>
        <title>Search for Available Target Recipes</title>

        <para>
            Use the <filename>devtool search</filename> command to
            search for available target recipes.
            The command matches the recipe name, package name,
            description, and installed files.
            The command displays the recipe name as a result of a
            match.
        </para>

        <para>
            When you use the <filename>devtool search</filename> command,
            you must supply a <replaceable>keyword</replaceable>.
            The command uses the <replaceable>keyword</replaceable> when
            searching for a match.
        </para>
    </section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->