From e1ff065baea754c3e19acf254e07930370a11ca6 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Sun, 29 Mar 2015 17:31:25 -0700 Subject: [PATCH] dev-manual: Applied review edits to the devtool section. Paul Eggleton reviewed the section. (From yocto-docs rev: 82d9750b4349b3c54f73118ec7d65f0bb96e3f7a) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 20 -- documentation/dev-manual/dev-manual-model.xml | 216 +++++++++++------- 2 files changed, 129 insertions(+), 107 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 3e48c0add5..79a3da3437 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -447,11 +447,6 @@ $HOME/poky/meta-yocto \ $HOME/poky/meta-yocto-bsp \ $HOME/poky/meta-mylayer \ - " - - BBLAYERS_NON_REMOVABLE ?= " \ - $HOME/poky/meta \ - $HOME/poky/meta-yocto \ " @@ -878,11 +873,6 @@ /usr/local/src/yocto/meta-yocto \ /usr/local/src/yocto/meta-yocto-bsp \ /usr/local/src/yocto/meta-mylayer \ - " - - BBLAYERS_NON_REMOVABLE ?= " \ - /usr/local/src/yocto/meta \ - /usr/local/src/yocto/meta-yocto \ " Adding the layer to this file enables the build system to @@ -5169,11 +5159,6 @@ $HOME/poky/meta-yocto \ $HOME/poky/meta-yocto-bsp \ $HOME/poky/meta-mylayer \ - " - - BBLAYERS_NON_REMOVABLE ?= " \ - $HOME/poky/meta \ - $HOME/poky/meta-yocto \ " @@ -10037,11 +10022,6 @@ ##OEROOT##/meta-yocto \ ##OEROOT##/meta-yocto-bsp \ ##OEROOT##/meta-mylayer \ - " - - BBLAYERS_NON_REMOVABLE ?= " \ - ##OEROOT##/meta \ - ##OEROOT##/meta-yocto \ " Creating and providing an archive of the diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index bb75926932..91b2058544 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -1669,8 +1669,8 @@ A common development workflow consists of modifying project source files that are external to the Yocto Project and then integrating - that project's build output into an image built using the Yocto - Project. + that project's build output into an image built using the + OpenEmbedded build system. Given this scenario, development engineers typically want to stick to their familiar project development tools and methods, which allows them to just focus on the project. @@ -1679,7 +1679,7 @@ Several workflows exist that allow you to develop, build, and test code that is going to be integrated into an image built using the - Yocto Project. + OpenEmbedded build system. This section describes two: devtool: @@ -1715,7 +1715,7 @@ As mentioned earlier, devtool helps you easily develop projects whose build output must be part of - an image built using the Yocto Project. + an image built using the OpenEmbedded build system. The remainder of this section presents the workflow you would use that includes devtool. @@ -1770,9 +1770,9 @@ 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 in your layer. - One obvious solution is to initially extract the code into its - own layer in preparation for modification. + access to and edit files. + One obvious solution is to initially extract the code into an + isolated area in preparation for modification. @@ -1788,7 +1788,7 @@
- Use <filename>dev-tool</filename> to Integrate Your Code with the Image + Use <filename>devtool</filename> to Integrate Your Code with the Image devtool automatically @@ -1796,15 +1796,15 @@ build system to build your code into the image. Use the following command form: - $ devtool add your-project-name path-to-source/your-project-name + $ devtool add your-project-name path-to-source Running devtool modifies the - bblayers.conf used to build the - image in the Yocto Project. + bblayers.conf that the + OpenEmbedded build system uses to build an image. For more information on the bblayers.conf, see the - "BSP Layers" - section in the Yocto Project Board Support Package (BSP) Developer's Guide. + "build/conf/bblayers.conf" + section in the Yocto Project Reference Manual. @@ -1814,7 +1814,7 @@ path-to-source/build-directory/workspace-layer - By default, the name of the workspace layer is "workplace". + By default, the name of the workspace layer is "workspace". @@ -1825,6 +1825,7 @@ section. + - Running devtool also automatically + Running devtool automatically generates your recipe: $ cat workspace/recipes/your-project-name/your-project-name.bb @@ -1898,8 +1900,10 @@ $ bitbake your-project-name - To use devtool, run the tool with the - build option: + Alternatively, you can use + devtool build, which is equivalent to + bitbake -c install. + For example: $ devtool build your-project-name @@ -1913,11 +1917,9 @@ The final step before testing is to rebuild the base image with your project changes as part of the image. Simply run BitBake again on your image. - Here is an example that assumes - MACHINE - is set to "qemux86": + Here is an example: - $ bitbake qemux86 image + $ bitbake image
@@ -1958,35 +1960,32 @@ --help option: $ devtool --help - usage: devtool [-h] [--basepath BASEPATH] [-d] [-q] - [--color {auto,always,never}] - {create-workspace,deploy-target,undeploy-target,add,modify,extract,update-recipe,status,build,reset} - ... + usage: devtool [-h] [--basepath BASEPATH] [-d] [-q] [--color COLOR] + <subcommand> ... OpenEmbedded development tool - positional arguments: - {create-workspace,deploy-target,undeploy-target,add,modify,extract,update-recipe,status,build,reset} - create-workspace Set up a workspace - deploy-target Deploy recipe output files to live target machine - undeploy-target Undeploy recipe output files in live target machine - add Add a new recipe - modify Modify the source for an existing recipe - extract Extract the source for an existing recipe - update-recipe Apply changes from external source tree to recipe - status Show status - build Build recipe - reset Remove a recipe from your workspace - optional arguments: - -h, --help show this help message and exit - --basepath BASEPATH Base directory of SDK / build directory - -d, --debug Enable debug output - -q, --quiet Print only errors - --color {auto,always,never} - Colorize output + -h, --help show this help message and exit + --basepath BASEPATH Base directory of SDK / build directory + -d, --debug Enable debug output + -q, --quiet Print only errors + --color COLOR Colorize output (where COLOR is auto, always, never) - Use devtool <command> --help to get help on a specific command + subcommands: + <subcommand> + create-workspace Set up a workspace + deploy-target Deploy recipe output files to live target machine + undeploy-target Undeploy recipe output files in live target machine + add Add a new recipe + modify Modify the source for an existing recipe + extract Extract the source for an existing recipe + update-recipe Apply changes from external source tree to recipe + status Show workspace status + build Build a recipe + reset Remove a recipe from your workspace + + Use devtool <subcommand> --help to get help on a specific command @@ -1996,7 +1995,9 @@ name and using --help: $ devtool add --help - usage: devtool add [-h] [--version VERSION] recipename srctree + usage: devtool add [-h] [--same-dir] [--version VERSION] recipename srctree + + Adds a new recipe positional arguments: recipename Name for new recipe to add @@ -2004,7 +2005,9 @@ optional arguments: -h, --help show this help message and exit + --same-dir, -s Build in same directory as source (default: False) --version VERSION, -V VERSION + Version to use within recipe (PV) (default: None) @@ -2013,7 +2016,7 @@ Adding a New Recipe to the Workspace Layer - Use the add command to add a new recipe + Use the devtool add command to add a new recipe to the workspace layer. The recipe you add should not exist - devtool creates it for you. @@ -2072,7 +2075,7 @@ Creating the Workspace Layer - Use the create-workspace command to + Use the devtool create-workspace command to create a new workspace layer in your Build Directory. When you create a new workspace layer, it is populated with the @@ -2108,19 +2111,21 @@ Modifying a Recipe - Use the modify command to configure - an external recipe in the workspace layer. + Use the devtool modify command to begin + modifying the source of an existing recipe. This command is very similar to the add command except that it does not physically create the recipe in the workspace layer because the recipe already - exists in an external layer. + exists in an another layer. - The modify command provides options - that allow you to extract the source and provide a - development branch name where you can do your work. + The devtool modify 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: @@ -2148,15 +2153,23 @@ Resetting a Recipe - Use the reset command to remove a + Use the devtool reset command to remove a recipe and its configuration (e.g. the corresponding .bbappend file) from the workspace layer. - Realize that this command deletes the recipe and and the + 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 reset command. + layer before running the devtool reset + command. + + + + If the devtool reset 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. For complete syntax, use the devtool reset --help command. @@ -2168,18 +2181,17 @@ Updating a Recipe - Use the update-recipe command to cause - devtool to update your recipe with patches - that reflect changes you make to the source files. + Use the devtool update-recipe command to + cause devtool 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 - modify + devtool modify command to extract the code and set up the workspace. - After which, you could modify, compile, and test the code - in its own layer to which it was extracted. + After which, you could modify, compile, and test the code. When you are satisfied with the results you can then - run the update-recipe to create the - patches and update the recipe in the external layer: + run the devtool update-recipe to create the + patches and update the recipe: $ devtool update-recipe recipe @@ -2194,9 +2206,12 @@ Building Your Software - Use the build command to cause the + Use the devtool build command to cause the OpenEmbedded build system to build your software based - on the recipe file: + on the recipe file. + The devtool build command is equivalent to + bitbake -c install. + Here is an example: $ devtool build recipe @@ -2204,8 +2219,8 @@ For complete syntax, use the devtool update-recipe --help command. - Building your software using build is - identical to using BitBake to build the software. + Building your software using devtool build + is identical to using BitBake to build the software. @@ -2213,17 +2228,36 @@ Deploying Your Software on the Target Machine - Use the deploy-target command to deploy - the recipe's build output to the the live target machine: + Use the devtool deploy-target command to + deploy the recipe's build output to the live target machine: $ devtool deploy-target recipe target - The target is the actual - target running on an SSH server (i.e. - user@hostname[:destdir]. - - For complete syntax, use the - devtool deploy-target --help command. + The target is the address of the + target machine, which must be running an SSH server (i.e. + user@hostname[:destdir]). + + + + This command deploys all files installed during the + do_install + task. + Furthermore, you do not need to have package management enabled + within the target machine. + If you do, the package manager is bypassed. + Notes + + The deploy-target + functionality is for development only. + 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. + @@ -2232,18 +2266,18 @@ Removing Your Software from the Target Machine - Use the undeploy-target command to remove - deployed build output from the target machine. - For undeploy-target command to work, - you must have previously used the - deploy-target + Use the devtool undeploy-target command to + remove deployed build output from the target machine. + For the devtool undeploy-target command to + work, you must have previously used the + devtool deploy-target command. $ devtool undeploy-target recipe target - The target is the actual - target running on an SSH server (i.e. - user@hostname. + 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. @@ -2257,11 +2291,19 @@ Quilt - is a powerful tool that allows you to capture source code changes without having - a clean source tree. + is a powerful tool that allows you to capture source code changes + without having a clean source tree. This section outlines the typical workflow you can use to modify source code, test changes, and then preserve the changes in the form of a patch all using Quilt. + Tip + With regard to preserving changes to source files if you + clean a recipe or have rm_work enabled, + the workflow described in the + "Using devtool in Your Workflow" + section is a safer development flow than than the flow that + uses Quilt. +