diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index d2ab2d7f41..d3fadbd1f7 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -6,6 +6,10 @@
Common Development Models
+
+ Test paragraph.
+
+
Many development models exist for which you can use the Yocto Project.
This chapter overviews simple methods that use tools provided by the
@@ -1743,212 +1747,211 @@
As mentioned earlier, devtool helps
you easily develop projects whose build output must be part of
an image built using the OpenEmbedded build system.
- The remainder of this section presents the workflow you would
- use that includes devtool.
-
-
- Kudos and thanks to
- Trevor Woerner
- whose
- "Yocto Project Developer Workflow Tutorial"
- paper contributed nicely towards the development of this
- section.
-
-
- The steps in this section assume you have a previously built
- image that is already either running in QEMU or running on actual
- hardware.
- Also, it is assumed that for deployment of the image to the
- target, SSH is installed in the image and if the image is running
- on real hardware that you have network access to and from your
- development machine.
+ Three entry points exist that allow you develop using
+ devtool:
+
+ devtool add
+
+ devtool modify
+
+ devtool upgrade
+
+
-
- Update Your External Source
+
+ The remainder of this section presents these workflows.
+
+ The steps in this section assume you have a previously built
+ image that is already either running in QEMU or running on actual
+ hardware.
+ Also, it is assumed that for deployment of the image to the
+ target, SSH is installed in the image and if the image is running
+ on real hardware that you have network access to and from your
+ development machine.
+
+
+
+
+ Use <filename>devtool add</filename> to Integrate New Code
- Part of the development flow using
- devtool of course involves updating
- your source files.
- Several opportunities exist in the workflow to extract and
- work on the files.
- For now, just realize that you need to be able to have
- access to and edit files.
- One obvious solution is to initially extract the code into an
- isolated area in preparation for modification.
+ This section describes the devtool
+ workflow to integrate new code.
+ With this workflow, you can either build and deploy
+ your code or rebuild an image that contains your code.
- Another option is to use the
- devtool modify command.
- This command makes use of a "workspace" layer where much of
- the transitional work occurs, which is needed for setting up
- Metadata used by the OpenEmbedded build system that lets you
- build your software.
- Options (i.e. "-x") exist using devtool
- that enable you to use the tool to extract source code.
+
+
+
+
+
+ Add a New Recipe:
+ The devtool add command automatically
+ generates the needed Metadata that allows the OpenEmbedded
+ build system to build your code.
+ Following are some forms you can use to enter the command:
+
+ $ devtool add [recipe_name] source_path
+ $ devtool add [recipe_name] source_path remote_URL
+ $ devtool add [recipe_name] remote_URL
+
+ The devtool command automatically detects the
+ recipe_name and, in many cases, the
+ version if you do not supply a name or version with the command.
+ Running devtool for the first time
+ creates a workspace layer, which by default is named
+ "workspace", and adds it to your
+ conf/bblayers.conf file:
+
+ source_path/build_directory/workspace_layer
+
+ For details on the workspace layer created in the
+ build-directory,
+ see the
+ "The Workspace Layer Structure"
+ section.
+ You can also specify a remote_URL
+ from which to download source instead of (or in addition
+ to) specifying a source_path.
+ If you specify a URL but not a source_path,
+ devtool uses a subdirectory called "sources"
+ within workspace to house the source files.
+ Here is an example command that provides the
+ remote_URL only:
+
+ $ devtool add ftp://ftp.bitwizard.nl/mtr/mtr-0.86.tar.gz
+ NOTE: Creating workspace layer in /home/scottrif/poky/build/workspace
+ NOTE: Enabling workspace layer in bblayers.conf
+ NOTE: Using default source tree path /home/scottrif/poky/build/workspace/sources/mtr
+ NOTE: Recipe /home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb
+ has been automatically created; further editing may be required to
+ make it fully functional
+ $
+
+ In this example, devtool detected both
+ a recipe name and version from the software for use when
+ creating the mtr_0.86.bb recipe file.
+ Because no source_path was provided, the
+ tool also created the default directory
+ sources/mtr/ in the created
+ workspace directory.
+ If you are using devtool add
+ to fetch source from a remote URL, the command turns
+ the source directory into a Git repository if one does
+ not already exist.
+ You can disable this behavior by using the "--no-git"
+ option.
+ The devtool add command does this in
+ order to support using
+ devtool update-recipe, shown as step
+ 5 in the flow diagram, to later create patches.
+
+ In case you ever need to locate the directory in which
+ devtool creates the recipe or, you
+ need to locate the source, you can use devtool
+ to check status:
+
+ $ devtool status
+ mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
+ $
+
+ Continuing with the example, the tool returns the location
+ for the source followed by the location and name of the
+ recipe.
+
+
+ Edit the Recipe:
+ At this point, you can use devtool edit-recipe
+ to open up the editor as defined by the
+ $EDITOR environment variable
+ and modify the file:
+
+ $ devtool edit-recipe recipe
+
+ From within the editor, you can make modifications to the
+ recipe that take affect when you build it later.
+
+ Build the Recipe or Rebuild the Image:
+ At this point in the flow, the next step you
+ take depends on what you are going to do with
+ the new code.
+ If you need to take the build output and eventually
+ move it to the target hardware, you would use
+ devtool build:
+
+ $ devtool build recipe
+
+ On the other hand, if you want an image to
+ contain the recipe's packages for immediate deployment
+ onto a device (e.g. for testing purposes), you can use
+ the devtool build-image command:
+
+ $ devtool build-image image
+
+
+ Deploy the Build Output:
+ When you use the devtool build
+ command to build out your recipe, you probably want to
+ see if the resulting build output works as expected on target
+ hardware.
+ You can deploy your build output to that target hardware by
+ using the devtool deploy-target command:
+
+ $ devtool deploy-target recipe target
+
+ The target is a live target machine
+ running as an SSH server.
+
+ You can, of course, also deploy the image you build
+ using the devtool build-image command
+ to actual hardware.
+ However, devtool does not provide a
+ specific command that allows you to do this.
+
+ Optionally Update the Recipe With Patch Files:
+ Once you are satisfied with the recipe you probably want
+ to generate patch files that go with the recipe.
+ You do this before moving the recipe
+ to its final layer and cleaning up the workspace area
+ devtool uses.
+ This optional step is especially relevant if you are
+ using or adding third-party software.
+ To convert commits created using Git to patch files,
+ use the devtool update-recipe command.
+
+ Any patches added, removed, or otherwise must be
+ previously committed to the upstream Git repository.
+
+
+ $ devtool update-recipe recipe_name
+
+
+ Move the Recipe to its Permanent Layer:
+ Before cleaning up the workspace, you need to move the
+ final recipe to its permanent layer.
+ You must do this before using the
+ devtool reset command if you want to
+ retain the recipe.
+
+ Reset the Recipe:
+ As a final step, you can restore the state such that
+ standard layers and the upstream source is used to build
+ the recipe rather than data in the workspace.
+ To reset the recipe, use the devtool reset
+ command:
+
+ $ devtool reset recipe
+
+
+
-
-
- Use <filename>devtool add</filename> to Integrate Your Code with the Image
-
-
- The devtool add command automatically
- generates the needed Metadata that allows the OpenEmbedded
- build system to build your code into the image.
-
- If a package or packages produced by the recipe on which
- you are working are not already in
- IMAGE_INSTALL
- for the image, you must add them.
- The devtool add command does not
- add them for you.
-
- Use the following command form:
-
- $ devtool add your-project-namepath-to-source
-
-
-
-
- Running devtool for the first time
- creates a workspace layer through the
- bblayers.conf file that
- is based on your project's location:
-
- path-to-source/build-directory/workspace-layer
-
- By default, the name of the workspace layer is "workspace".
-
-
-
- For details on the workspace layer created in the
- build-directory,
- see the
- "Adding a New Recipe to the Workspace Layer"
- section.
-
-
-
-
-
- Running devtool add automatically
- generates your recipe:
-
- $ cat workspace/recipes/your-project-name/your-project-name.bb
- # Recipe created by recipetool
- # This is the basis of a recipe and may need further editing in order to be fully functional.
- # (Feel free to remove these comments when editing.)
- #
- # Unable to find any files that looked like license statements. Check the accompanying
- # documentation and source headers and set LICENSE and LIC_FILES_CHKSUM accordingly.
- LICENSE = "CLOSED"
- LIC_FILES_CHKSUM = ""
-
- # No information for SRC_URI yet (only an external source tree was
- # specified)
- SRC_URI = ""
-
- DEPENDS = "libx11"
- # NOTE: if this software is not capable of being built in a separate build directory
- # from the source, you should replace autotools with autotools-brokensep in the
- # inherit line
- inherit autotools
-
- # Specify any options you want to pass to the configure script using EXTRA_OECONF:
- EXTRA_OECONF = ""
-
-
-
-
- Lastly, the devtool add command creates the
- .bbappend file:
-
- $ cat workspace/appends/your-project-name.bbappend
- inherit externalsrc
- EXTERNALSRC = "/path-to-source/your-project-name"
-
- # initial_rev: commit-ID
-
-
-
-
-
- Build Your Project
-
-
- You can use BitBake or devtool build to
- build your modified project.
-
-
-
- To use BitBake, use the following:
-
- $ bitbake your-project-name
-
- Alternatively, you can use
- devtool build, which is equivalent to
- bitbake -c populate_sysroot.
- For example:
-
- $ devtool build your-project-name
-
-
-
-
-
@@ -1959,7 +1962,7 @@
adding a new recipe and the supporting Metadata to a temporary
workspace layer.
This section provides a short reference on
- devtool for most of the commands.
+ devtool and its commands.
@@ -1993,6 +1996,8 @@
undeploy-target Undeploy recipe output files in live target machine
search Search available recipes
build Build a recipe
+ edit-recipe Edit a recipe file in your workspace
+ configure-help Get help on configure script options
add Add a new recipe
modify Modify the source for an existing recipe
extract Extract the source for an existing recipe
@@ -2000,7 +2005,6 @@
update-recipe Apply changes from external source tree to recipe
status Show workspace status
reset Remove a recipe from your workspace
- edit-recipe Edit a recipe file in your workspace
build-image Build image including workspace recipe packages
Use devtool <subcommand> --help to get help on a specific command
@@ -2015,6 +2019,7 @@
$ devtool add --help
usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
[--version VERSION] [--no-git] [--binary] [--also-native]
+ [--src-subdir SUBDIR]
[recipename] [srctree] [fetchuri]
Adds a new recipe to the workspace to build a specified source tree. Can
@@ -2026,7 +2031,7 @@
auto-detect it.
srctree Path to external source tree. If not specified, a
subdirectory of
- /home/user/poky/build/workspace/sources will be
+ /home/scottrif/poky/build/workspace/sources will be
used.
fetchuri Fetch the specified URI and extract it to create the
source tree
@@ -2047,6 +2052,52 @@
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
+
+
+
+
+
+ The Workspace Layer Structure
+
+
+ devtool uses a "Workspace" layer
+ in which to accomplish builds.
+ This layer is not specific to any single
+ devtool command but is rather a common
+ working area used across the tool.
+
+
+
+ The following figure shows the workspace structure:
+
+
+
+
+
+
+
+
+ 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 recipe.bb file
+ within that sub-directory.
+
+ sources - A directory containing a working copy of the source files used
+ when building the recipe. This directory contains a
+ folder for each set of source files matched to a corresponding
+ recipe.
@@ -2065,49 +2116,26 @@
The following example creates and adds a new recipe named
- jackson to the workspace layer.
+ jackson to a workspace layer the tool creates.
The source code built by the recipes resides in
/home/scottrif/sources/jackson:
$ devtool add jackson /home/scottrif/sources/jackson
-
- For complete syntax, use the
- devtool add --help command.
-
If you add a recipe and the workspace layer does not exist,
- the command creates the layer and populates it as follows:
-
-
-
-
-
-
-
-
- README - Provides information on what is in workspace layer and how to
- manage it.
-
- 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 recipe.bb file
- within that sub-directory.
-
+ the command creates the layer and populates it as
+ described in
+ "The Workspace Layer Structure"
+ section.
Running devtool add when the
- workspace layer exists causes the tool to add the recipe
- and append files into the existing workspace layer.
+ workspace layer exists causes the tool to add the recipe,
+ append files, and source files into the existing workspace layer.
The .bbappend file is created to point
to the external source tree.
@@ -2130,10 +2158,6 @@
development branch into which you can checkout the source
and whether or not to keep a temporary directory, which is
useful for debugging.
-
- For complete syntax, use the
- devtool extract --help command.
-
@@ -2155,10 +2179,6 @@
development branch into which you can checkout the source
and whether or not to keep a temporary directory, which is
useful for debugging.
-
- For complete syntax, use the
- devtool sync --help command.
-
@@ -2188,10 +2208,6 @@
Using the above command form, the default development branch
would be "devtool".
-
- For complete syntax, use the
- devtool modify --help command.
-
@@ -2215,10 +2231,6 @@
"-a" or "--any-recipe" option.
Using either of these options allows you to edit any recipe
regardless of its location.
-
- For complete syntax, use the
- devtool edit-recipe --help command.
-
@@ -2268,10 +2280,6 @@
file.
If an append file already exists, the command updates it
appropriately.
-
- For complete syntax, use the
- devtool update-recipe --help command.
-
@@ -2298,10 +2306,6 @@
the source revision to which you want to upgrade (i.e. the
SRCREV,
whether or not to apply patches, and so forth.
-
- For complete syntax, use the
- devtool upgrade --help command.
-
@@ -2326,10 +2330,18 @@
the recipe or the append files have been modified, the
command preserves the modified files in a separate "attic"
subdirectory under the workspace layer.
-
- For complete syntax, use the
- devtool reset --help command.
-
+
+
+
+ Here is an example that resets the workspace directory that
+ contains the mtr recipe:
+
+ $ 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
+ $
+
@@ -2353,10 +2365,6 @@
$ devtool build recipe
-
- For complete syntax, use the
- devtool build --help command.
-
@@ -2367,6 +2375,10 @@
Use the devtool build-image 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.
@@ -2407,12 +2419,6 @@
You should never use it to update an image that will be
used in production.
-
-
- For complete syntax, use the
- devtool deploy-target --help
- command.
-
@@ -2433,10 +2439,6 @@
The target is the address of the
target machine, which must be running an SSH server (i.e.
user@hostname).
-
- For complete syntax, use the
- devtool undeploy-target --help command.
-
@@ -2459,10 +2461,6 @@
$ devtool create-workspace
-
- For complete syntax, use the
- devtool create-workspace --help command.
-
@@ -2492,6 +2490,15 @@
devtool status
+ Following is sample output after using
+ devtool add
+ to create and add the mtr_0.86.bb recipe
+ to the workspace directory:
+
+ $ devtool status
+ mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
+ $
+
@@ -2512,10 +2519,6 @@
you must supply a keyword.
The command uses the keyword when
searching for a match.
-
- For complete syntax, use the
- devtool search --help command.
-