diff options
Diffstat (limited to 'documentation/ref-manual/ref-devtool-reference.rst')
-rw-r--r-- | documentation/ref-manual/ref-devtool-reference.rst | 533 |
1 files changed, 533 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-devtool-reference.rst b/documentation/ref-manual/ref-devtool-reference.rst new file mode 100644 index 0000000000..c91ba5bdfa --- /dev/null +++ b/documentation/ref-manual/ref-devtool-reference.rst | |||
@@ -0,0 +1,533 @@ | |||
1 | *************************** | ||
2 | ``devtool`` Quick Reference | ||
3 | *************************** | ||
4 | |||
5 | The ``devtool`` command-line tool provides a number of features that | ||
6 | help you build, test, and package software. This command is available | ||
7 | alongside the ``bitbake`` command. Additionally, the ``devtool`` command | ||
8 | is a key part of the extensible SDK. | ||
9 | |||
10 | This chapter provides a Quick Reference for the ``devtool`` command. For | ||
11 | more information on how to apply the command when using the extensible | ||
12 | SDK, see the "`Using the Extensible | ||
13 | SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" chapter in the Yocto | ||
14 | Project Application Development and the Extensible Software Development | ||
15 | Kit (eSDK) manual. | ||
16 | |||
17 | .. _devtool-getting-help: | ||
18 | |||
19 | Getting Help | ||
20 | ============ | ||
21 | |||
22 | The ``devtool`` command line is organized similarly to Git in that it | ||
23 | has a number of sub-commands for each function. You can run | ||
24 | ``devtool --help`` to see all the commands: $ devtool -h NOTE: Starting | ||
25 | bitbake server... usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] | ||
26 | [-d] [-q] [--color COLOR] [-h] <subcommand> ... OpenEmbedded development | ||
27 | tool options: --basepath BASEPATH Base directory of SDK / build | ||
28 | directory --bbpath BBPATH Explicitly specify the BBPATH, rather than | ||
29 | getting it from the metadata -d, --debug Enable debug output -q, --quiet | ||
30 | Print only errors --color COLOR Colorize output (where COLOR is auto, | ||
31 | always, never) -h, --help show this help message and exit subcommands: | ||
32 | Beginning work on a recipe: add Add a new recipe modify Modify the | ||
33 | source for an existing recipe upgrade Upgrade an existing recipe Getting | ||
34 | information: status Show workspace status search Search available | ||
35 | recipes latest-version Report the latest version of an existing recipe | ||
36 | check-upgrade-status Report upgradability for multiple (or all) recipes | ||
37 | Working on a recipe in the workspace: build Build a recipe rename Rename | ||
38 | a recipe file in the workspace edit-recipe Edit a recipe file | ||
39 | find-recipe Find a recipe file configure-help Get help on configure | ||
40 | script options update-recipe Apply changes from external source tree to | ||
41 | recipe reset Remove a recipe from your workspace finish Finish working | ||
42 | on a recipe in your workspace Testing changes on target: deploy-target | ||
43 | Deploy recipe output files to live target machine undeploy-target | ||
44 | Undeploy recipe output files in live target machine build-image Build | ||
45 | image including workspace recipe packages Advanced: create-workspace Set | ||
46 | up workspace in an alternative location export Export workspace into a | ||
47 | tar archive import Import exported tar archive into workspace extract | ||
48 | Extract the source for an existing recipe sync Synchronize the source | ||
49 | tree for an existing recipe Use devtool <subcommand> --help to get help | ||
50 | on a specific command As directed in the general help output, you can | ||
51 | get more syntax on a specific command by providing the command name and | ||
52 | using "--help": $ devtool add --help NOTE: Starting bitbake server... | ||
53 | usage: devtool add [-h] [--same-dir \| --no-same-dir] [--fetch URI] | ||
54 | [--fetch-dev] [--version VERSION] [--no-git] [--srcrev SRCREV \| | ||
55 | --autorev] [--srcbranch SRCBRANCH] [--binary] [--also-native] | ||
56 | [--src-subdir SUBDIR] [--mirrors] [--provides PROVIDES] [recipename] | ||
57 | [srctree] [fetchuri] Adds a new recipe to the workspace to build a | ||
58 | specified source tree. Can optionally fetch a remote URI and unpack it | ||
59 | to create the source tree. arguments: recipename Name for new recipe to | ||
60 | add (just name - no version, path or extension). If not specified, will | ||
61 | attempt to auto-detect it. srctree Path to external source tree. If not | ||
62 | specified, a subdirectory of /home/scottrif/poky/build/workspace/sources | ||
63 | will be used. fetchuri Fetch the specified URI and extract it to create | ||
64 | the source tree options: -h, --help show this help message and exit | ||
65 | --same-dir, -s Build in same directory as source --no-same-dir Force | ||
66 | build in a separate build directory --fetch URI, -f URI Fetch the | ||
67 | specified URI and extract it to create the source tree (deprecated - | ||
68 | pass as positional argument instead) --fetch-dev For npm, also fetch | ||
69 | devDependencies --version VERSION, -V VERSION Version to use within | ||
70 | recipe (PV) --no-git, -g If fetching source, do not set up source tree | ||
71 | as a git repository --srcrev SRCREV, -S SRCREV Source revision to fetch | ||
72 | if fetching from an SCM such as git (default latest) --autorev, -a When | ||
73 | fetching from a git repository, set SRCREV in the recipe to a floating | ||
74 | revision instead of fixed --srcbranch SRCBRANCH, -B SRCBRANCH Branch in | ||
75 | source repository if fetching from an SCM such as git (default master) | ||
76 | --binary, -b Treat the source tree as something that should be installed | ||
77 | verbatim (no compilation, same directory structure). Useful with binary | ||
78 | packages e.g. RPMs. --also-native Also add native variant (i.e. support | ||
79 | building recipe for the build host as well as the target machine) | ||
80 | --src-subdir SUBDIR Specify subdirectory within source tree to use | ||
81 | --mirrors Enable PREMIRRORS and MIRRORS for source tree fetching | ||
82 | (disable by default). --provides PROVIDES, -p PROVIDES Specify an alias | ||
83 | for the item provided by the recipe. E.g. virtual/libgl | ||
84 | |||
85 | .. _devtool-the-workspace-layer-structure: | ||
86 | |||
87 | The Workspace Layer Structure | ||
88 | ============================= | ||
89 | |||
90 | ``devtool`` uses a "Workspace" layer in which to accomplish builds. This | ||
91 | layer is not specific to any single ``devtool`` command but is rather a | ||
92 | common working area used across the tool. | ||
93 | |||
94 | The following figure shows the workspace structure: | ||
95 | |||
96 | attic - A directory created if devtool believes it must preserve | ||
97 | anything when you run "devtool reset". For example, if you run "devtool | ||
98 | add", make changes to the recipe, and then run "devtool reset", devtool | ||
99 | takes notice that the file has been changed and moves it into the attic | ||
100 | should you still want the recipe. README - Provides information on what | ||
101 | is in workspace layer and how to manage it. .devtool_md5 - A checksum | ||
102 | file used by devtool. appends - A directory that contains \*.bbappend | ||
103 | files, which point to external source. conf - A configuration directory | ||
104 | that contains the layer.conf file. recipes - A directory containing | ||
105 | recipes. This directory contains a folder for each directory added whose | ||
106 | name matches that of the added recipe. devtool places the recipe.bb file | ||
107 | within that sub-directory. sources - A directory containing a working | ||
108 | copy of the source files used when building the recipe. This is the | ||
109 | default directory used as the location of the source tree when you do | ||
110 | not provide a source tree path. This directory contains a folder for | ||
111 | each set of source files matched to a corresponding recipe. | ||
112 | |||
113 | .. _devtool-adding-a-new-recipe-to-the-workspace: | ||
114 | |||
115 | Adding a New Recipe to the Workspace Layer | ||
116 | ========================================== | ||
117 | |||
118 | Use the ``devtool add`` command to add a new recipe to the workspace | ||
119 | layer. The recipe you add should not exist - ``devtool`` creates it for | ||
120 | you. The source files the recipe uses should exist in an external area. | ||
121 | |||
122 | The following example creates and adds a new recipe named ``jackson`` to | ||
123 | a workspace layer the tool creates. The source code built by the recipes | ||
124 | resides in ``/home/user/sources/jackson``: $ devtool add jackson | ||
125 | /home/user/sources/jackson | ||
126 | |||
127 | If you add a recipe and the workspace layer does not exist, the command | ||
128 | creates the layer and populates it as described in "`The Workspace Layer | ||
129 | Structure <#devtool-the-workspace-layer-structure>`__" section. | ||
130 | |||
131 | Running ``devtool add`` when the workspace layer exists causes the tool | ||
132 | to add the recipe, append files, and source files into the existing | ||
133 | workspace layer. The ``.bbappend`` file is created to point to the | ||
134 | external source tree. | ||
135 | |||
136 | .. note:: | ||
137 | |||
138 | If your recipe has runtime dependencies defined, you must be sure | ||
139 | that these packages exist on the target hardware before attempting to | ||
140 | run your application. If dependent packages (e.g. libraries) do not | ||
141 | exist on the target, your application, when run, will fail to find | ||
142 | those functions. For more information, see the " | ||
143 | Deploying Your Software on the Target Machine | ||
144 | " section. | ||
145 | |||
146 | By default, ``devtool add`` uses the latest revision (i.e. master) when | ||
147 | unpacking files from a remote URI. In some cases, you might want to | ||
148 | specify a source revision by branch, tag, or commit hash. You can | ||
149 | specify these options when using the ``devtool add`` command: | ||
150 | |||
151 | - To specify a source branch, use the ``--srcbranch`` option: $ devtool | ||
152 | add --srcbranch DISTRO_NAME_NO_CAP jackson /home/user/sources/jackson | ||
153 | In the previous example, you are checking out the DISTRO_NAME_NO_CAP | ||
154 | branch. | ||
155 | |||
156 | - To specify a specific tag or commit hash, use the ``--srcrev`` | ||
157 | option: $ devtool add --srcrev DISTRO_REL_TAG jackson | ||
158 | /home/user/sources/jackson $ devtool add --srcrev some_commit_hash | ||
159 | /home/user/sources/jackson The previous examples check out the | ||
160 | DISTRO_REL_TAG tag and the commit associated with the | ||
161 | some_commit_hash hash. | ||
162 | |||
163 | .. note:: | ||
164 | |||
165 | If you prefer to use the latest revision every time the recipe is | ||
166 | built, use the options | ||
167 | --autorev | ||
168 | or | ||
169 | -a | ||
170 | . | ||
171 | |||
172 | .. _devtool-extracting-the-source-for-an-existing-recipe: | ||
173 | |||
174 | Extracting the Source for an Existing Recipe | ||
175 | ============================================ | ||
176 | |||
177 | Use the ``devtool extract`` command to extract the source for an | ||
178 | existing recipe. When you use this command, you must supply the root | ||
179 | name of the recipe (i.e. no version, paths, or extensions), and you must | ||
180 | supply the directory to which you want the source extracted. | ||
181 | |||
182 | Additional command options let you control the name of a development | ||
183 | branch into which you can checkout the source and whether or not to keep | ||
184 | a temporary directory, which is useful for debugging. | ||
185 | |||
186 | .. _devtool-synchronizing-a-recipes-extracted-source-tree: | ||
187 | |||
188 | Synchronizing a Recipe's Extracted Source Tree | ||
189 | ============================================== | ||
190 | |||
191 | Use the ``devtool sync`` command to synchronize a previously extracted | ||
192 | source tree for an existing recipe. When you use this command, you must | ||
193 | supply the root name of the recipe (i.e. no version, paths, or | ||
194 | extensions), and you must supply the directory to which you want the | ||
195 | source extracted. | ||
196 | |||
197 | Additional command options let you control the name of a development | ||
198 | branch into which you can checkout the source and whether or not to keep | ||
199 | a temporary directory, which is useful for debugging. | ||
200 | |||
201 | .. _devtool-modifying-a-recipe: | ||
202 | |||
203 | Modifying an Existing Recipe | ||
204 | ============================ | ||
205 | |||
206 | Use the ``devtool modify`` command to begin modifying the source of an | ||
207 | existing recipe. This command is very similar to the | ||
208 | ```add`` <#devtool-adding-a-new-recipe-to-the-workspace>`__ command | ||
209 | except that it does not physically create the recipe in the workspace | ||
210 | layer because the recipe already exists in an another layer. | ||
211 | |||
212 | The ``devtool modify`` command extracts the source for a recipe, sets it | ||
213 | up as a Git repository if the source had not already been fetched from | ||
214 | Git, checks out a branch for development, and applies any patches from | ||
215 | the recipe as commits on top. You can use the following command to | ||
216 | checkout the source files: $ devtool modify recipe Using the above | ||
217 | command form, ``devtool`` uses the existing recipe's | ||
218 | ```SRC_URI`` <#var-SRC_URI>`__ statement to locate the upstream source, | ||
219 | extracts the source into the default sources location in the workspace. | ||
220 | The default development branch used is "devtool". | ||
221 | |||
222 | .. _devtool-edit-an-existing-recipe: | ||
223 | |||
224 | Edit an Existing Recipe | ||
225 | ======================= | ||
226 | |||
227 | Use the ``devtool edit-recipe`` command to run the default editor, which | ||
228 | is identified using the ``EDITOR`` variable, on the specified recipe. | ||
229 | |||
230 | When you use the ``devtool edit-recipe`` command, you must supply the | ||
231 | root name of the recipe (i.e. no version, paths, or extensions). Also, | ||
232 | the recipe file itself must reside in the workspace as a result of the | ||
233 | ``devtool add`` or ``devtool upgrade`` commands. However, you can | ||
234 | override that requirement by using the "-a" or "--any-recipe" option. | ||
235 | Using either of these options allows you to edit any recipe regardless | ||
236 | of its location. | ||
237 | |||
238 | .. _devtool-updating-a-recipe: | ||
239 | |||
240 | Updating a Recipe | ||
241 | ================= | ||
242 | |||
243 | Use the ``devtool update-recipe`` command to update your recipe with | ||
244 | patches that reflect changes you make to the source files. For example, | ||
245 | if you know you are going to work on some code, you could first use the | ||
246 | ```devtool modify`` <#devtool-modifying-a-recipe>`__ command to extract | ||
247 | the code and set up the workspace. After which, you could modify, | ||
248 | compile, and test the code. | ||
249 | |||
250 | When you are satisfied with the results and you have committed your | ||
251 | changes to the Git repository, you can then run the | ||
252 | ``devtool update-recipe`` to create the patches and update the recipe: $ | ||
253 | devtool update-recipe recipe If you run the ``devtool update-recipe`` | ||
254 | without committing your changes, the command ignores the changes. | ||
255 | |||
256 | Often, you might want to apply customizations made to your software in | ||
257 | your own layer rather than apply them to the original recipe. If so, you | ||
258 | can use the ``-a`` or ``--append`` option with the | ||
259 | ``devtool update-recipe`` command. These options allow you to specify | ||
260 | the layer into which to write an append file: $ devtool update-recipe | ||
261 | recipe -a base-layer-directory The ``*.bbappend`` file is created at the | ||
262 | appropriate path within the specified layer directory, which may or may | ||
263 | not be in your ``bblayers.conf`` file. If an append file already exists, | ||
264 | the command updates it appropriately. | ||
265 | |||
266 | .. _devtool-checking-on-the-upgrade-status-of-a-recipe: | ||
267 | |||
268 | Checking on the Upgrade Status of a Recipe | ||
269 | ========================================== | ||
270 | |||
271 | Upstream recipes change over time. Consequently, you might find that you | ||
272 | need to determine if you can upgrade a recipe to a newer version. | ||
273 | |||
274 | To check on the upgrade status of a recipe, use the | ||
275 | ``devtool check-upgrade-status`` command. The command displays a table | ||
276 | of your current recipe versions, the latest upstream versions, the email | ||
277 | address of the recipe's maintainer, and any additional information such | ||
278 | as commit hash strings and reasons you might not be able to upgrade a | ||
279 | particular recipe. | ||
280 | |||
281 | .. note:: | ||
282 | |||
283 | - For the ``oe-core`` layer, recipe maintainers come from the | ||
284 | ```maintainers.inc`` <http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc>`__ | ||
285 | file. | ||
286 | |||
287 | - If the recipe is using the `Git | ||
288 | fetcher <&YOCTO_DOCS_BB_URL;#git-fetcher>`__ rather than a | ||
289 | tarball, the commit hash points to the commit that matches the | ||
290 | recipe's latest version tag. | ||
291 | |||
292 | As with all ``devtool`` commands, you can get help on the individual | ||
293 | command: $ devtool check-upgrade-status -h NOTE: Starting bitbake | ||
294 | server... usage: devtool check-upgrade-status [-h] [--all] [recipe | ||
295 | [recipe ...]] Prints a table of recipes together with versions currently | ||
296 | provided by recipes, and latest upstream versions, when there is a later | ||
297 | version available arguments: recipe Name of the recipe to report (omit | ||
298 | to report upgrade info for all recipes) options: -h, --help show this | ||
299 | help message and exit --all, -a Show all recipes, not just recipes | ||
300 | needing upgrade | ||
301 | |||
302 | Unless you provide a specific recipe name on the command line, the | ||
303 | command checks all recipes in all configured layers. | ||
304 | |||
305 | Following is a partial example table that reports on all the recipes. | ||
306 | Notice the reported reason for not upgrading the ``base-passwd`` recipe. | ||
307 | In this example, while a new version is available upstream, you do not | ||
308 | want to use it because the dependency on ``cdebconf`` is not easily | ||
309 | satisfied. | ||
310 | |||
311 | .. note:: | ||
312 | |||
313 | When a reason for not upgrading displays, the reason is usually | ||
314 | written into the recipe using the | ||
315 | RECIPE_NO_UPDATE_REASON | ||
316 | variable. See the | ||
317 | base-passwd.bb | ||
318 | recipe for an example. | ||
319 | |||
320 | $ devtool check-upgrade-status ... NOTE: acpid 2.0.30 2.0.31 Ross Burton | ||
321 | <ross.burton@intel.com> NOTE: u-boot-fw-utils 2018.11 2019.01 Marek | ||
322 | Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff | ||
323 | NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> | ||
324 | d3689267f92c5956e09cc7d1baa4700141662bff . . . NOTE: base-passwd 3.5.29 | ||
325 | 3.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: | ||
326 | Version 3.5.38 requires cdebconf for update-passwd utility NOTE: busybox | ||
327 | 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com> NOTE: dbus-test | ||
328 | 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com> | ||
329 | |||
330 | .. _devtool-upgrading-a-recipe: | ||
331 | |||
332 | Upgrading a Recipe | ||
333 | ================== | ||
334 | |||
335 | As software matures, upstream recipes are upgraded to newer versions. As | ||
336 | a developer, you need to keep your local recipes up-to-date with the | ||
337 | upstream version releases. Several methods exist by which you can | ||
338 | upgrade recipes. You can read about them in the "`Upgrading | ||
339 | Recipes <&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes>`__" section of the | ||
340 | Yocto Project Development Tasks Manual. This section overviews the | ||
341 | ``devtool upgrade`` command. | ||
342 | |||
343 | .. note:: | ||
344 | |||
345 | Before you upgrade a recipe, you can check on its upgrade status. See | ||
346 | the " | ||
347 | Checking on the Upgrade Status of a Recipe | ||
348 | " for more information. | ||
349 | |||
350 | The ``devtool upgrade`` command upgrades an existing recipe to a more | ||
351 | recent version of the recipe upstream. The command puts the upgraded | ||
352 | recipe file along with any associated files into a "workspace" and, if | ||
353 | necessary, extracts the source tree to a specified location. During the | ||
354 | upgrade, patches associated with the recipe are rebased or added as | ||
355 | needed. | ||
356 | |||
357 | When you use the ``devtool upgrade`` command, you must supply the root | ||
358 | name of the recipe (i.e. no version, paths, or extensions), and you must | ||
359 | supply the directory to which you want the source extracted. Additional | ||
360 | command options let you control things such as the version number to | ||
361 | which you want to upgrade (i.e. the ```PV`` <#var-PV>`__), the source | ||
362 | revision to which you want to upgrade (i.e. the | ||
363 | ```SRCREV`` <#var-SRCREV>`__), whether or not to apply patches, and so | ||
364 | forth. | ||
365 | |||
366 | You can read more on the ``devtool upgrade`` workflow in the "`Use | ||
367 | ``devtool upgrade`` to Create a Version of the Recipe that Supports a | ||
368 | Newer Version of the | ||
369 | Software <&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software>`__" | ||
370 | section in the Yocto Project Application Development and the Extensible | ||
371 | Software Development Kit (eSDK) manual. You can also see an example of | ||
372 | how to use ``devtool upgrade`` in the "`Using | ||
373 | ``devtool upgrade`` <&YOCTO_DOCS_DEV_URL;#gs-using-devtool-upgrade>`__" | ||
374 | section in the Yocto Project Development Tasks Manual. | ||
375 | |||
376 | .. _devtool-resetting-a-recipe: | ||
377 | |||
378 | Resetting a Recipe | ||
379 | ================== | ||
380 | |||
381 | Use the ``devtool reset`` command to remove a recipe and its | ||
382 | configuration (e.g. the corresponding ``.bbappend`` file) from the | ||
383 | workspace layer. Realize that this command deletes the recipe and the | ||
384 | append file. The command does not physically move them for you. | ||
385 | Consequently, you must be sure to physically relocate your updated | ||
386 | recipe and the append file outside of the workspace layer before running | ||
387 | the ``devtool reset`` command. | ||
388 | |||
389 | If the ``devtool reset`` command detects that the recipe or the append | ||
390 | files have been modified, the command preserves the modified files in a | ||
391 | separate "attic" subdirectory under the workspace layer. | ||
392 | |||
393 | Here is an example that resets the workspace directory that contains the | ||
394 | ``mtr`` recipe: $ devtool reset mtr NOTE: Cleaning sysroot for recipe | ||
395 | mtr... NOTE: Leaving source tree | ||
396 | /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer | ||
397 | need it then please delete it manually $ | ||
398 | |||
399 | .. _devtool-building-your-recipe: | ||
400 | |||
401 | Building Your Recipe | ||
402 | ==================== | ||
403 | |||
404 | Use the ``devtool build`` command to build your recipe. The | ||
405 | ``devtool build`` command is equivalent to the | ||
406 | ``bitbake -c populate_sysroot`` command. | ||
407 | |||
408 | When you use the ``devtool build`` command, you must supply the root | ||
409 | name of the recipe (i.e. do not provide versions, paths, or extensions). | ||
410 | You can use either the "-s" or the "--disable-parallel-make" options to | ||
411 | disable parallel makes during the build. Here is an example: $ devtool | ||
412 | build recipe | ||
413 | |||
414 | .. _devtool-building-your-image: | ||
415 | |||
416 | Building Your Image | ||
417 | =================== | ||
418 | |||
419 | Use the ``devtool build-image`` command to build an image, extending it | ||
420 | to include packages from recipes in the workspace. Using this command is | ||
421 | useful when you want an image that ready for immediate deployment onto a | ||
422 | device for testing. For proper integration into a final image, you need | ||
423 | to edit your custom image recipe appropriately. | ||
424 | |||
425 | When you use the ``devtool build-image`` command, you must supply the | ||
426 | name of the image. This command has no command line options: $ devtool | ||
427 | build-image image | ||
428 | |||
429 | .. _devtool-deploying-your-software-on-the-target-machine: | ||
430 | |||
431 | Deploying Your Software on the Target Machine | ||
432 | ============================================= | ||
433 | |||
434 | Use the ``devtool deploy-target`` command to deploy the recipe's build | ||
435 | output to the live target machine: $ devtool deploy-target recipe target | ||
436 | The target is the address of the target machine, which must be running | ||
437 | an SSH server (i.e. ``user@hostname[:destdir]``). | ||
438 | |||
439 | This command deploys all files installed during the | ||
440 | ```do_install`` <#ref-tasks-install>`__ task. Furthermore, you do not | ||
441 | need to have package management enabled within the target machine. If | ||
442 | you do, the package manager is bypassed. | ||
443 | |||
444 | .. note:: | ||
445 | |||
446 | The ``deploy-target`` functionality is for development only. You | ||
447 | should never use it to update an image that will be used in | ||
448 | production. | ||
449 | |||
450 | Some conditions exist that could prevent a deployed application from | ||
451 | behaving as expected. When both of the following conditions exist, your | ||
452 | application has the potential to not behave correctly when run on the | ||
453 | target: | ||
454 | |||
455 | - You are deploying a new application to the target and the recipe you | ||
456 | used to build the application had correctly defined runtime | ||
457 | dependencies. | ||
458 | |||
459 | - The target does not physically have the packages on which the | ||
460 | application depends installed. | ||
461 | |||
462 | If both of these conditions exist, your application will not behave as | ||
463 | expected. The reason for this misbehavior is because the | ||
464 | ``devtool deploy-target`` command does not deploy the packages (e.g. | ||
465 | libraries) on which your new application depends. The assumption is that | ||
466 | the packages are already on the target. Consequently, when a runtime | ||
467 | call is made in the application for a dependent function (e.g. a library | ||
468 | call), the function cannot be found. | ||
469 | |||
470 | To be sure you have all the dependencies local to the target, you need | ||
471 | to be sure that the packages are pre-deployed (installed) on the target | ||
472 | before attempting to run your application. | ||
473 | |||
474 | .. _devtool-removing-your-software-from-the-target-machine: | ||
475 | |||
476 | Removing Your Software from the Target Machine | ||
477 | ============================================== | ||
478 | |||
479 | Use the ``devtool undeploy-target`` command to remove deployed build | ||
480 | output from the target machine. For the ``devtool undeploy-target`` | ||
481 | command to work, you must have previously used the | ||
482 | ```devtool deploy-target`` <#devtool-deploying-your-software-on-the-target-machine>`__ | ||
483 | command. $ devtool undeploy-target recipe target The target is the | ||
484 | address of the target machine, which must be running an SSH server (i.e. | ||
485 | ``user@hostname``). | ||
486 | |||
487 | .. _devtool-creating-the-workspace: | ||
488 | |||
489 | Creating the Workspace Layer in an Alternative Location | ||
490 | ======================================================= | ||
491 | |||
492 | Use the ``devtool create-workspace`` command to create a new workspace | ||
493 | layer in your `Build Directory <#build-directory>`__. When you create a | ||
494 | new workspace layer, it is populated with the ``README`` file and the | ||
495 | ``conf`` directory only. | ||
496 | |||
497 | The following example creates a new workspace layer in your current | ||
498 | working and by default names the workspace layer "workspace": $ devtool | ||
499 | create-workspace | ||
500 | |||
501 | You can create a workspace layer anywhere by supplying a pathname with | ||
502 | the command. The following command creates a new workspace layer named | ||
503 | "new-workspace": $ devtool create-workspace /home/scottrif/new-workspace | ||
504 | |||
505 | .. _devtool-get-the-status-of-the-recipes-in-your-workspace: | ||
506 | |||
507 | Get the Status of the Recipes in Your Workspace | ||
508 | =============================================== | ||
509 | |||
510 | Use the ``devtool status`` command to list the recipes currently in your | ||
511 | workspace. Information includes the paths to their respective external | ||
512 | source trees. | ||
513 | |||
514 | The ``devtool status`` command has no command-line options: $ devtool | ||
515 | status Following is sample output after using | ||
516 | ```devtool add`` <#devtool-adding-a-new-recipe-to-the-workspace>`__ to | ||
517 | create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` | ||
518 | directory: $ devtool status mtr: | ||
519 | /home/scottrif/poky/build/workspace/sources/mtr | ||
520 | (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) $ | ||
521 | |||
522 | .. _devtool-search-for-available-target-recipes: | ||
523 | |||
524 | Search for Available Target Recipes | ||
525 | =================================== | ||
526 | |||
527 | Use the ``devtool search`` command to search for available target | ||
528 | recipes. The command matches the recipe name, package name, description, | ||
529 | and installed files. The command displays the recipe name as a result of | ||
530 | a match. | ||
531 | |||
532 | When you use the ``devtool search`` command, you must supply a keyword. | ||
533 | The command uses the keyword when searching for a match. | ||