From 9582da61de441ba2c5b347a299c6e66a04b087a7 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 29 Jan 2016 13:07:47 -0800 Subject: dev-manual: Edits to the devtool-add section. (From yocto-docs rev: f7f3cfa4a6faa556650b5ab8a04e68c585c30107) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 543 +++++++++++++------------- 1 file changed, 273 insertions(+), 270 deletions(-) (limited to 'documentation/dev-manual/dev-manual-model.xml') 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 - - - 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. - - - - 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. - -
- -
- 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-name path-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 - - -
+ + 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. + + -
- Build Your Project +
+ Use <filename>devtool add</filename> to Integrate New Code - You can use BitBake or devtool build to - build your modified project. + 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. - 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,44 +2052,29 @@ 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
-
- Adding a New Recipe to the Workspace Layer +
+ The Workspace Layer Structure - 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. - The source files the recipe uses should exist in an external - area. + 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 example creates and adds a new recipe named - jackson to the workspace layer. - 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: + The following figure shows the workspace structure: + width="6in" depth="5in" align="left" scale="70" /> @@ -2092,6 +2082,8 @@ 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. @@ -2101,13 +2093,49 @@ 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. +
+ +
+ Adding a New Recipe to the Workspace Layer + + + 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. + The source files the recipe uses should exist in an external + area. + + + + The following example creates and adds a new recipe named + 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 + + + + + If you add a recipe and the workspace layer does not exist, + 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. - -- cgit v1.2.3-54-g00ecf