blob: 9319addc3c611ee183ad069bf7e41d14811b33ce [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3***************************
4``devtool`` Quick Reference
5***************************
6
7The ``devtool`` command-line tool provides a number of features that
8help you build, test, and package software. This command is available
9alongside the ``bitbake`` command. Additionally, the ``devtool`` command
10is a key part of the extensible SDK.
11
12This chapter provides a Quick Reference for the ``devtool`` command. For
13more information on how to apply the command when using the extensible
Andrew Geissler09209ee2020-12-13 08:44:15 -060014SDK, see the ":doc:`/sdk-manual/extensible`" chapter in the Yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -050015Project Application Development and the Extensible Software Development
16Kit (eSDK) manual.
17
18.. _devtool-getting-help:
19
20Getting Help
21============
22
23The ``devtool`` command line is organized similarly to Git in that it
24has a number of sub-commands for each function. You can run
Andrew Geisslerc926e172021-05-07 16:11:35 -050025``devtool --help`` to see all the commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050026
27 $ devtool -h
28 NOTE: Starting bitbake server...
29 usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] [--color COLOR] [-h] <subcommand> ...
30
31 OpenEmbedded development tool
32
33 options:
34 --basepath BASEPATH Base directory of SDK / build directory
35 --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it from the metadata
36 -d, --debug Enable debug output
37 -q, --quiet Print only errors
38 --color COLOR Colorize output (where COLOR is auto, always, never)
39 -h, --help show this help message and exit
40
41 subcommands:
42 Beginning work on a recipe:
43 add Add a new recipe
44 modify Modify the source for an existing recipe
45 upgrade Upgrade an existing recipe
46 Getting information:
47 status Show workspace status
48 latest-version Report the latest version of an existing recipe
49 check-upgrade-status Report upgradability for multiple (or all) recipes
50 search Search available recipes
51 Working on a recipe in the workspace:
52 build Build a recipe
53 rename Rename a recipe file in the workspace
54 edit-recipe Edit a recipe file
55 find-recipe Find a recipe file
56 configure-help Get help on configure script options
57 update-recipe Apply changes from external source tree to recipe
58 reset Remove a recipe from your workspace
59 finish Finish working on a recipe in your workspace
60 Testing changes on target:
61 deploy-target Deploy recipe output files to live target machine
62 undeploy-target Undeploy recipe output files in live target machine
63 build-image Build image including workspace recipe packages
64 Advanced:
65 create-workspace Set up workspace in an alternative location
66 extract Extract the source for an existing recipe
67 sync Synchronize the source tree for an existing recipe
68 menuconfig Alter build-time configuration for a recipe
69 import Import exported tar archive into workspace
70 export Export workspace into a tar archive
71 other:
72 selftest-reverse Reverse value (for selftest)
73 pluginfile Print the filename of this plugin
74 bbdir Print the BBPATH directory of this plugin
75 count How many times have this plugin been registered.
76 multiloaded How many times have this plugin been initialized
77 Use devtool <subcommand> --help to get help on a specific command
78
79As directed in the general help output, you can
80get more syntax on a specific command by providing the command name and
Andrew Geissler5199d832021-09-24 16:47:35 -050081using ``--help``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050082
83 $ devtool add --help
84 NOTE: Starting bitbake server...
85 usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] [--npm-dev] [--version VERSION] [--no-git] [--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH] [--binary] [--also-native] [--src-subdir SUBDIR] [--mirrors]
86 [--provides PROVIDES]
87 [recipename] [srctree] [fetchuri]
88
89 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.
90
91 arguments:
92 recipename Name for new recipe to add (just name - no version, path or extension). If not specified, will attempt to auto-detect it.
93 srctree Path to external source tree. If not specified, a subdirectory of /media/build1/poky/build/workspace/sources will be used.
94 fetchuri Fetch the specified URI and extract it to create the source tree
95
96 options:
97 -h, --help show this help message and exit
98 --same-dir, -s Build in same directory as source
99 --no-same-dir Force build in a separate build directory
100 --fetch URI, -f URI Fetch the specified URI and extract it to create the source tree (deprecated - pass as positional argument instead)
101 --npm-dev For npm, also fetch devDependencies
102 --version VERSION, -V VERSION
103 Version to use within recipe (PV)
104 --no-git, -g If fetching source, do not set up source tree as a git repository
105 --srcrev SRCREV, -S SRCREV
106 Source revision to fetch if fetching from an SCM such as git (default latest)
107 --autorev, -a When fetching from a git repository, set SRCREV in the recipe to a floating revision instead of fixed
108 --srcbranch SRCBRANCH, -B SRCBRANCH
109 Branch in source repository if fetching from an SCM such as git (default master)
110 --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.
111 --also-native Also add native variant (i.e. support building recipe for the build host as well as the target machine)
112 --src-subdir SUBDIR Specify subdirectory within source tree to use
113 --mirrors Enable PREMIRRORS and MIRRORS for source tree fetching (disable by default).
114 --provides PROVIDES, -p PROVIDES
115 Specify an alias for the item provided by the recipe. E.g. virtual/libgl
116
117.. _devtool-the-workspace-layer-structure:
118
119The Workspace Layer Structure
120=============================
121
122``devtool`` uses a "Workspace" layer in which to accomplish builds. This
123layer is not specific to any single ``devtool`` command but is rather a
124common working area used across the tool.
125
126The following figure shows the workspace structure:
127
128.. image:: figures/build-workspace-directory.png
Andrew Geisslerd5838332022-05-27 11:33:10 -0500129 :scale: 100%
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500130
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500131.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500132
133 attic - A directory created if devtool believes it must preserve
134 anything when you run "devtool reset". For example, if you
135 run "devtool add", make changes to the recipe, and then
136 run "devtool reset", devtool takes notice that the file has
137 been changed and moves it into the attic should you still
138 want the recipe.
139
140 README - Provides information on what is in workspace layer and how to
141 manage it.
142
143 .devtool_md5 - A checksum file used by devtool.
144
145 appends - A directory that contains *.bbappend files, which point to
146 external source.
147
148 conf - A configuration directory that contains the layer.conf file.
149
150 recipes - A directory containing recipes. This directory contains a
151 folder for each directory added whose name matches that of the
152 added recipe. devtool places the recipe.bb file
153 within that sub-directory.
154
155 sources - A directory containing a working copy of the source files used
156 when building the recipe. This is the default directory used
157 as the location of the source tree when you do not provide a
158 source tree path. This directory contains a folder for each
159 set of source files matched to a corresponding recipe.
160
161.. _devtool-adding-a-new-recipe-to-the-workspace:
162
163Adding a New Recipe to the Workspace Layer
164==========================================
165
166Use the ``devtool add`` command to add a new recipe to the workspace
Andrew Geissler615f2f12022-07-15 14:00:58 -0500167layer. The recipe you add should not exist --- ``devtool`` creates it for
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500168you. The source files the recipe uses should exist in an external area.
169
170The following example creates and adds a new recipe named ``jackson`` to
171a workspace layer the tool creates. The source code built by the recipes
Andrew Geisslerc926e172021-05-07 16:11:35 -0500172resides in ``/home/user/sources/jackson``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173
174 $ devtool add jackson /home/user/sources/jackson
175
176If you add a recipe and the workspace layer does not exist, the command
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500177creates the layer and populates it as described in
178":ref:`devtool-the-workspace-layer-structure`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500179
180Running ``devtool add`` when the workspace layer exists causes the tool
181to add the recipe, append files, and source files into the existing
182workspace layer. The ``.bbappend`` file is created to point to the
183external source tree.
184
185.. note::
186
187 If your recipe has runtime dependencies defined, you must be sure
188 that these packages exist on the target hardware before attempting to
189 run your application. If dependent packages (e.g. libraries) do not
190 exist on the target, your application, when run, will fail to find
191 those functions. For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600192 ":ref:`ref-manual/devtool-reference:deploying your software on the target machine`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500193 section.
194
195By default, ``devtool add`` uses the latest revision (i.e. master) when
196unpacking files from a remote URI. In some cases, you might want to
197specify a source revision by branch, tag, or commit hash. You can
198specify these options when using the ``devtool add`` command:
199
Andrew Geisslerc926e172021-05-07 16:11:35 -0500200- To specify a source branch, use the ``--srcbranch`` option::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500201
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600202 $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/user/sources/jackson
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500203
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600204 In the previous example, you are checking out the &DISTRO_NAME_NO_CAP;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500205 branch.
206
207- To specify a specific tag or commit hash, use the ``--srcrev``
Andrew Geisslerc926e172021-05-07 16:11:35 -0500208 option::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500209
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600210 $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/user/sources/jackson
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500211 $ devtool add --srcrev some_commit_hash /home/user/sources/jackson
212
213 The previous examples check out the
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600214 &DISTRO_REL_TAG; tag and the commit associated with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500215 some_commit_hash hash.
216
217.. note::
218
219 If you prefer to use the latest revision every time the recipe is
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500220 built, use the options ``--autorev`` or ``-a``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221
222.. _devtool-extracting-the-source-for-an-existing-recipe:
223
224Extracting the Source for an Existing Recipe
225============================================
226
227Use the ``devtool extract`` command to extract the source for an
228existing recipe. When you use this command, you must supply the root
229name of the recipe (i.e. no version, paths, or extensions), and you must
230supply the directory to which you want the source extracted.
231
232Additional command options let you control the name of a development
233branch into which you can checkout the source and whether or not to keep
234a temporary directory, which is useful for debugging.
235
236.. _devtool-synchronizing-a-recipes-extracted-source-tree:
237
238Synchronizing a Recipe's Extracted Source Tree
239==============================================
240
241Use the ``devtool sync`` command to synchronize a previously extracted
242source tree for an existing recipe. When you use this command, you must
243supply the root name of the recipe (i.e. no version, paths, or
244extensions), and you must supply the directory to which you want the
245source extracted.
246
247Additional command options let you control the name of a development
248branch into which you can checkout the source and whether or not to keep
249a temporary directory, which is useful for debugging.
250
251.. _devtool-modifying-a-recipe:
252
253Modifying an Existing Recipe
254============================
255
256Use the ``devtool modify`` command to begin modifying the source of an
257existing recipe. This command is very similar to the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500258:ref:`add <devtool-adding-a-new-recipe-to-the-workspace>` command
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500259except that it does not physically create the recipe in the workspace
260layer because the recipe already exists in an another layer.
261
262The ``devtool modify`` command extracts the source for a recipe, sets it
263up as a Git repository if the source had not already been fetched from
264Git, checks out a branch for development, and applies any patches from
265the recipe as commits on top. You can use the following command to
Andrew Geisslerc926e172021-05-07 16:11:35 -0500266checkout the source files::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500267
268 $ devtool modify recipe
269
270Using the above command form, ``devtool`` uses the existing recipe's
271:term:`SRC_URI` statement to locate the upstream source,
272extracts the source into the default sources location in the workspace.
273The default development branch used is "devtool".
274
275.. _devtool-edit-an-existing-recipe:
276
277Edit an Existing Recipe
278=======================
279
280Use the ``devtool edit-recipe`` command to run the default editor, which
281is identified using the ``EDITOR`` variable, on the specified recipe.
282
283When you use the ``devtool edit-recipe`` command, you must supply the
284root name of the recipe (i.e. no version, paths, or extensions). Also,
285the recipe file itself must reside in the workspace as a result of the
Andrew Geissler5199d832021-09-24 16:47:35 -0500286``devtool add`` or ``devtool upgrade`` commands.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500287
288.. _devtool-updating-a-recipe:
289
290Updating a Recipe
291=================
292
293Use the ``devtool update-recipe`` command to update your recipe with
294patches that reflect changes you make to the source files. For example,
295if you know you are going to work on some code, you could first use the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500296:ref:`devtool modify <devtool-modifying-a-recipe>` command to extract
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500297the code and set up the workspace. After which, you could modify,
298compile, and test the code.
299
300When you are satisfied with the results and you have committed your
301changes to the Git repository, you can then run the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500302``devtool update-recipe`` to create the patches and update the recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500303
304 $ devtool update-recipe recipe
305
306If you run the ``devtool update-recipe``
307without committing your changes, the command ignores the changes.
308
309Often, you might want to apply customizations made to your software in
310your own layer rather than apply them to the original recipe. If so, you
311can use the ``-a`` or ``--append`` option with the
312``devtool update-recipe`` command. These options allow you to specify
Andrew Geisslerc926e172021-05-07 16:11:35 -0500313the layer into which to write an append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500314
315 $ devtool update-recipe recipe -a base-layer-directory
316
317The ``*.bbappend`` file is created at the
318appropriate path within the specified layer directory, which may or may
319not be in your ``bblayers.conf`` file. If an append file already exists,
320the command updates it appropriately.
321
322.. _devtool-checking-on-the-upgrade-status-of-a-recipe:
323
324Checking on the Upgrade Status of a Recipe
325==========================================
326
327Upstream recipes change over time. Consequently, you might find that you
328need to determine if you can upgrade a recipe to a newer version.
329
Andrew Geissler5199d832021-09-24 16:47:35 -0500330To check on the upgrade status of a recipe, you can use the
331``devtool latest-version recipe`` command, which quickly shows the current
332version and the latest version available upstream. To get a more global
333picture, use the ``devtool check-upgrade-status`` command, which takes a
334list of recipes as input, or no arguments, in which case it checks all
335available recipes. This command will only print the recipes for which
336a new upstream version is available. Each such recipe will have its current
337version and latest upstream version, as well as the email of the maintainer
338and any additional information such as the commit hash or reason for not
339being able to upgrade it, displayed in a table.
340
341This upgrade checking mechanism relies on the optional :term:`UPSTREAM_CHECK_URI`,
342:term:`UPSTREAM_CHECK_REGEX`, :term:`UPSTREAM_CHECK_GITTAGREGEX`,
343:term:`UPSTREAM_CHECK_COMMITS` and :term:`UPSTREAM_VERSION_UNKNOWN`
344variables in package recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500345
346.. note::
347
Andrew Geissler5199d832021-09-24 16:47:35 -0500348 - Most of the time, the above variables are unnecessary. They are only
349 required when upstream does something unusual, and default
350 mechanisms cannot find the new upstream versions.
351
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500352 - For the ``oe-core`` layer, recipe maintainers come from the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600353 :yocto_git:`maintainers.inc </poky/tree/meta/conf/distro/include/maintainers.inc>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500354 file.
355
Andrew Geisslerfc113ea2023-03-31 09:59:46 -0500356 - If the recipe is using the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)`
Andrew Geissler5199d832021-09-24 16:47:35 -0500357 rather than a tarball, the commit hash points to the commit that matches
358 the recipe's latest version tag, or in the absence of suitable tags,
359 to the latest commit (when :term:`UPSTREAM_CHECK_COMMITS` set to ``1``
360 in the recipe).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500361
362As with all ``devtool`` commands, you can get help on the individual
Andrew Geisslerc926e172021-05-07 16:11:35 -0500363command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500364
365 $ devtool check-upgrade-status -h
366 NOTE: Starting bitbake server...
367 usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]]
368
369 Prints a table of recipes together with versions currently provided by recipes, and latest upstream versions, when there is a later version available
370
371 arguments:
372 recipe Name of the recipe to report (omit to report upgrade info for all recipes)
373
374 options:
375 -h, --help show this help message and exit
376 --all, -a Show all recipes, not just recipes needing upgrade
377
378Unless you provide a specific recipe name on the command line, the
379command checks all recipes in all configured layers.
380
Patrick Williams39653562024-03-01 08:54:02 -0600381Here is a partial example table that reports on all the recipes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500382
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500383 $ devtool check-upgrade-status
384 ...
Andrew Geissler5199d832021-09-24 16:47:35 -0500385 INFO: bind 9.16.20 9.16.21 Armin Kuster <akuster808@gmail.com>
386 INFO: inetutils 2.1 2.2 Tom Rini <trini@konsulko.com>
387 INFO: iproute2 5.13.0 5.14.0 Changhyeok Bae <changhyeok.bae@gmail.com>
388 INFO: openssl 1.1.1l 3.0.0 Alexander Kanavin <alex.kanavin@gmail.com>
389 INFO: base-passwd 3.5.29 3.5.51 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility
390 ...
391
Andrew Geissler6aa7eec2023-03-03 12:41:14 -0600392Notice the reported reason for not upgrading the ``base-passwd`` recipe.
393In this example, while a new version is available upstream, you do not
394want to use it because the dependency on ``cdebconf`` is not easily
395satisfied. Maintainers can explicit the reason that is shown by adding
396the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe.
397See :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb?h=kirkstone>`
398for an example::
399
400 RECIPE_NO_UPDATE_REASON = "Version 3.5.38 requires cdebconf for update-passwd utility"
401
Andrew Geissler5199d832021-09-24 16:47:35 -0500402Last but not least, you may set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1``
403in a recipe when there's currently no way to determine its latest upstream
404version.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500405
406.. _devtool-upgrading-a-recipe:
407
408Upgrading a Recipe
409==================
410
411As software matures, upstream recipes are upgraded to newer versions. As
412a developer, you need to keep your local recipes up-to-date with the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700413upstream version releases. There are several ways of upgrading recipes.
Andrew Geissler517393d2023-01-13 08:55:19 -0600414You can read about them in the ":ref:`dev-manual/upgrading-recipes:upgrading recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500415section of the Yocto Project Development Tasks Manual. This section
416overviews the ``devtool upgrade`` command.
417
418Before you upgrade a recipe, you can check on its upgrade status. See
419the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" section
420for more information.
421
422The ``devtool upgrade`` command upgrades an existing recipe to a more
423recent version of the recipe upstream. The command puts the upgraded
424recipe file along with any associated files into a "workspace" and, if
425necessary, extracts the source tree to a specified location. During the
426upgrade, patches associated with the recipe are rebased or added as
427needed.
428
429When you use the ``devtool upgrade`` command, you must supply the root
430name of the recipe (i.e. no version, paths, or extensions), and you must
431supply the directory to which you want the source extracted. Additional
432command options let you control things such as the version number to
433which you want to upgrade (i.e. the :term:`PV`), the source
434revision to which you want to upgrade (i.e. the
435:term:`SRCREV`), whether or not to apply patches, and so
436forth.
437
438You can read more on the ``devtool upgrade`` workflow in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600439":ref:`sdk-manual/extensible:use \`\`devtool upgrade\`\` to create a version of the recipe that supports a newer version of the software`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500440section in the Yocto Project Application Development and the Extensible
441Software Development Kit (eSDK) manual. You can also see an example of
Andrew Geissler517393d2023-01-13 08:55:19 -0600442how to use ``devtool upgrade`` in the ":ref:`dev-manual/upgrading-recipes:using \`\`devtool upgrade\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500443section in the Yocto Project Development Tasks Manual.
444
445.. _devtool-resetting-a-recipe:
446
447Resetting a Recipe
448==================
449
450Use the ``devtool reset`` command to remove a recipe and its
451configuration (e.g. the corresponding ``.bbappend`` file) from the
452workspace layer. Realize that this command deletes the recipe and the
453append file. The command does not physically move them for you.
454Consequently, you must be sure to physically relocate your updated
455recipe and the append file outside of the workspace layer before running
456the ``devtool reset`` command.
457
458If the ``devtool reset`` command detects that the recipe or the append
459files have been modified, the command preserves the modified files in a
460separate "attic" subdirectory under the workspace layer.
461
462Here is an example that resets the workspace directory that contains the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500463``mtr`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500464
465 $ devtool reset mtr
466 NOTE: Cleaning sysroot for recipe mtr...
467 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
468 $
469
470.. _devtool-building-your-recipe:
471
472Building Your Recipe
473====================
474
475Use the ``devtool build`` command to build your recipe. The
476``devtool build`` command is equivalent to the
477``bitbake -c populate_sysroot`` command.
478
479When you use the ``devtool build`` command, you must supply the root
480name of the recipe (i.e. do not provide versions, paths, or extensions).
Andrew Geissler5199d832021-09-24 16:47:35 -0500481You can use either the ``-s`` or the ``--disable-parallel-make`` options to
Andrew Geisslerc926e172021-05-07 16:11:35 -0500482disable parallel makes during the build. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500483
484 $ devtool build recipe
485
486.. _devtool-building-your-image:
487
488Building Your Image
489===================
490
491Use the ``devtool build-image`` command to build an image, extending it
492to include packages from recipes in the workspace. Using this command is
493useful when you want an image that ready for immediate deployment onto a
494device for testing. For proper integration into a final image, you need
495to edit your custom image recipe appropriately.
496
497When you use the ``devtool build-image`` command, you must supply the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500498name of the image. This command has no command line options::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500499
500 $ devtool build-image image
501
502.. _devtool-deploying-your-software-on-the-target-machine:
503
504Deploying Your Software on the Target Machine
505=============================================
506
507Use the ``devtool deploy-target`` command to deploy the recipe's build
Andrew Geisslerc926e172021-05-07 16:11:35 -0500508output to the live target machine::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500509
510 $ devtool deploy-target recipe target
511
512The target is the address of the target machine, which must be running
513an SSH server (i.e. ``user@hostname[:destdir]``).
514
515This command deploys all files installed during the
516:ref:`ref-tasks-install` task. Furthermore, you do not
517need to have package management enabled within the target machine. If
518you do, the package manager is bypassed.
519
520.. note::
521
522 The ``deploy-target`` functionality is for development only. You
523 should never use it to update an image that will be used in
524 production.
525
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700526Some conditions could prevent a deployed application from
527behaving as expected. When both of the following conditions are met, your
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500528application has the potential to not behave correctly when run on the
529target:
530
531- You are deploying a new application to the target and the recipe you
532 used to build the application had correctly defined runtime
533 dependencies.
534
535- The target does not physically have the packages on which the
536 application depends installed.
537
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700538If both of these conditions are met, your application will not behave as
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500539expected. The reason for this misbehavior is because the
540``devtool deploy-target`` command does not deploy the packages (e.g.
541libraries) on which your new application depends. The assumption is that
542the packages are already on the target. Consequently, when a runtime
543call is made in the application for a dependent function (e.g. a library
544call), the function cannot be found.
545
546To be sure you have all the dependencies local to the target, you need
547to be sure that the packages are pre-deployed (installed) on the target
548before attempting to run your application.
549
550.. _devtool-removing-your-software-from-the-target-machine:
551
552Removing Your Software from the Target Machine
553==============================================
554
555Use the ``devtool undeploy-target`` command to remove deployed build
556output from the target machine. For the ``devtool undeploy-target``
557command to work, you must have previously used the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600558":ref:`devtool deploy-target <ref-manual/devtool-reference:deploying your software on the target machine>`"
Andrew Geissler517393d2023-01-13 08:55:19 -0600559command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500560
561 $ devtool undeploy-target recipe target
562
563The target is the
564address of the target machine, which must be running an SSH server (i.e.
565``user@hostname``).
566
567.. _devtool-creating-the-workspace:
568
569Creating the Workspace Layer in an Alternative Location
570=======================================================
571
572Use the ``devtool create-workspace`` command to create a new workspace
573layer in your :term:`Build Directory`. When you create a
574new workspace layer, it is populated with the ``README`` file and the
575``conf`` directory only.
576
577The following example creates a new workspace layer in your current
Andrew Geisslerc926e172021-05-07 16:11:35 -0500578working and by default names the workspace layer "workspace"::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500579
580 $ devtool create-workspace
581
582You can create a workspace layer anywhere by supplying a pathname with
583the command. The following command creates a new workspace layer named
Andrew Geisslerc926e172021-05-07 16:11:35 -0500584"new-workspace"::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500585
586 $ devtool create-workspace /home/scottrif/new-workspace
587
588.. _devtool-get-the-status-of-the-recipes-in-your-workspace:
589
590Get the Status of the Recipes in Your Workspace
591===============================================
592
593Use the ``devtool status`` command to list the recipes currently in your
594workspace. Information includes the paths to their respective external
595source trees.
596
Andrew Geisslerc926e172021-05-07 16:11:35 -0500597The ``devtool status`` command has no command-line options::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500598
599 $ devtool status
600
Patrick Williams39653562024-03-01 08:54:02 -0600601Here is sample output after using
Andrew Geissler09209ee2020-12-13 08:44:15 -0600602:ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500603to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500604
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500605 $ devtool status
606 mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500607 $
608
609.. _devtool-search-for-available-target-recipes:
610
611Search for Available Target Recipes
612===================================
613
614Use the ``devtool search`` command to search for available target
615recipes. The command matches the recipe name, package name, description,
616and installed files. The command displays the recipe name as a result of
617a match.
618
619When you use the ``devtool search`` command, you must supply a keyword.
620The command uses the keyword when searching for a match.