diff --git a/documentation/Makefile b/documentation/Makefile index 770ef93f37..167b73e2cd 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -131,8 +131,6 @@ TARFILES = dev-style.css dev-manual.html \ TARFILES = dev-style.css dev-manual.html \ figures/dev-title.png \ figures/recipe-workflow.png \ - figures/devtool-add-flow.png figures/devtool-modify-flow.png \ - figures/devtool-upgrade-flow.png \ eclipse endif @@ -241,8 +239,7 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \ figures/sdk-generation.png figures/recipe-workflow.png \ figures/build-workspace-directory.png figures/mega-title.png \ figures/toaster-title.png figures/hosted-service.png \ - figures/simple-configuration.png figures/devtool-add-flow.png \ - figures/devtool-modify-flow.png figures/devtool-upgrade-flow.png \ + figures/simple-configuration.png \ figures/compatible-layers.png figures/import-layer.png figures/new-project.png \ figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \ figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \ diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index c6efcf6699..f040c402c4 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1516,8 +1516,9 @@ You can find a complete description of the devtool add command in the - "Use devtool add to Add an Application" - section. + "A Closer Look at devtool add" + section in the Yocto Project Software Development Kit + (SDK) Developer's Guide. @@ -4081,10 +4082,11 @@ 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 the flow that - uses Quilt. + the + devtool workflow + as described in the Yocto Project Software Development Kit + (SDK) Developer's Guide is a safer development flow than the + flow that uses Quilt. @@ -6966,7 +6968,8 @@ Two methods exist by which you can create the patch: - devtool and + devtool + and Quilt. For kernel patches, the Git workflow is more appropriate. This section assumes the Git workflow and shows the steps specific to diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml deleted file mode 100644 index aeaa3fd9d3..0000000000 --- a/documentation/dev-manual/dev-manual-model.xml +++ /dev/null @@ -1,721 +0,0 @@ - %poky; ] > - - - -Common Development Models - - - Many development models exist for which you can use the Yocto Project. - This chapter overviews simple methods that use tools provided by the - Yocto Project: - - System Development: - System Development covers Board Support Package (BSP) development - and kernel modification or configuration. - For an example on how to create a BSP, see the - "Creating a New BSP Layer Using the yocto-bsp Script" - section in the Yocto Project Board Support Package (BSP) - Developer's Guide. - For more complete information on how to work with the kernel, - see the - Yocto Project Linux Kernel Development Manual. - - Temporary Source Code Modification: - Direct modification of temporary source code is a convenient - development model to quickly iterate and develop towards a - solution. - Once you implement the solution, you should of course take - steps to get the changes upstream and applied in the affected - recipes. - - Using a Development Shell: - You can use a - devshell - to efficiently debug - commands or simply edit packages. - Working inside a development shell is a quick way to set up the - OpenEmbedded build environment to work on parts of a project. - - - - -
- Modifying Source Code - - - 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 - 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. - - - - Several workflows exist that allow you to develop, build, and test - code that is going to be integrated into an image built using the - OpenEmbedded build system. - This section describes two: - - devtool: - A set of tools to aid in working on the source code built by - the OpenEmbedded build system. - Section - "Using devtool in Your Workflow" - describes this workflow. - If you want more information that showcases the workflow, click - here - for a presentation by Trevor Woerner that, while somewhat dated, - provides detailed background information and a complete - working tutorial. - - Quilt: - A powerful tool that allows you to capture source - code changes without having a clean source tree. - While Quilt is not the preferred workflow of the two, this - section includes it for users that are committed to using - the tool. - See the - "Using Quilt in Your Workflow" - section for more information. - - - - -
- Using <filename>devtool</filename> in Your Workflow - - - As mentioned earlier, devtool helps - you easily develop projects whose build output must be part of - an image built using the OpenEmbedded build system. - - - - Three entry points exist that allow you to develop using - devtool: - - devtool add - - devtool modify - - devtool upgrade - - - - - - The remainder of this section presents these workflows. - See the - "devtool Quick Reference" - in the Yocto Project Reference Manual for a - devtool quick reference. - - -
- Use <filename>devtool add</filename> to Add an Application - - - The devtool add command generates - a new recipe based on existing source code. - This command takes advantage of the - workspace - layer that many devtool commands - use. - The command is flexible enough to allow you to extract source - code into both the workspace or a separate local Git repository - and to use existing code that does not need to be extracted. - - - - Depending on your particular scenario, the arguments and options - you use with devtool add form different - combinations. - The following diagram shows common development flows - you would use with the devtool add - command: - - - - - - - - - Generating the New Recipe: - The top part of the flow shows three scenarios by which - you could use devtool add to - generate a recipe based on existing source code. - - In a shared development environment, it is - typical where other developers are responsible for - various areas of source code. - As a developer, you are probably interested in using - that source code as part of your development using - the Yocto Project. - All you need is access to the code, a recipe, and a - controlled area in which to do your work. - - Within the diagram, three possible scenarios - feed into the devtool add workflow: - - Left: - The left scenario represents a common situation - where the source code does not exist locally - and needs to be extracted. - In this situation, you just let it get - extracted to the default workspace - you do not - want it in some specific location outside of the - workspace. - Thus, everything you need will be located in the - workspace: - - $ devtool add recipe fetchuri - - With this command, devtool - creates a recipe and an append file in the - workspace as well as extracts the upstream - source files into a local Git repository also - within the sources folder. - - Middle: - The middle scenario also represents a situation where - the source code does not exist locally. - In this case, the code is again upstream - and needs to be extracted to some - local area - this time outside of the default - workspace. - If required, devtool - always creates - a Git repository locally during the extraction. - Furthermore, the first positional argument - srctree in this case - identifies where the - devtool add command - will locate the extracted code outside of the - workspace: - - $ devtool add recipe srctree fetchuri - - In summary, the source code is pulled from - fetchuri and extracted - into the location defined by - srctree as a local - Git repository. - - Within workspace, devtool - creates both the recipe and an append file - for the recipe. - - Right: - The right scenario represents a situation - where the source tree (srctree) has been - previously prepared outside of the - devtool workspace. - - - The following command names the recipe - and identifies where the existing source tree - is located: - - $ devtool add recipe srctree - - The command examines the source code and creates - a recipe for it placing the recipe into the - workspace. - - Because the extracted source code already exists, - devtool does not try to - relocate it into the workspace - just the new - the recipe is placed in the workspace. - - Aside from a recipe folder, the command - also creates an append folder and places an initial - *.bbappend within. - - - - 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. - - This step assumes 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. - - 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. - - - Finish Your Work With the Recipe: - The devtool finish command creates - any patches corresponding to commits in the local - Git repository, moves the new recipe to a more permanent - layer, and then resets the recipe so that the recipe is - built normally rather than from the workspace. - - $ devtool finish recipe layer - - - Any changes you want to turn into patches must be - committed to the Git repository in the source tree. - - - As mentioned, the devtool finish - command moves the final recipe to its permanent layer. - - - As a final process of the - devtool finish command, the state - of the standard layers and the upstream source is - restored so that you can build the recipe from those - areas rather than the workspace. - - You can use the devtool reset - command to put things back should you decide you - do not want to proceed with your work. - If you do use this command, realize that the source - tree is preserved. - - - - -
- -
- Use <filename>devtool modify</filename> to Modify the Source of an Existing Component - - - The devtool modify command prepares the - way to work on existing code that already has a recipe in - place. - The command is flexible enough to allow you to extract code, - specify the existing recipe, and keep track of and gather any - patch files from other developers that are - associated with the code. - - - - Depending on your particular scenario, the arguments and options - you use with devtool modify form different - combinations. - The following diagram shows common development flows - you would use with the devtool modify - command: - - - - - - - - - Preparing to Modify the Code: - The top part of the flow shows three scenarios by which - you could use devtool modify to - prepare to work on source files. - Each scenario assumes the following: - - The recipe exists in some layer external - to the devtool workspace. - - The source files exist upstream in an - un-extracted state or locally in a previously - extracted state. - - - The typical situation is where another developer has - created some layer for use with the Yocto Project and - their recipe already resides in that layer. - Furthermore, their source code is readily available - either upstream or locally. - - Left: - The left scenario represents a common situation - where the source code does not exist locally - and needs to be extracted. - In this situation, the source is extracted - into the default workspace location. - The recipe, in this scenario, is in its own - layer outside the workspace - (i.e. - meta-layername). - - - The following command identifies the recipe - and by default extracts the source files: - - $ devtool modify recipe - - Once devtoollocates the recipe, - it uses the - SRC_URI - variable to locate the source code and - any local patch files from other developers are - located. - - You cannot provide an URL for - srctree when using the - devtool modify command. - - With this scenario, however, since no - srctree argument exists, the - devtool modify command by default - extracts the source files to a Git structure. - Furthermore, the location for the extracted source is the - default area within the workspace. - The result is that the command sets up both the source - code and an append file within the workspace with the - recipe remaining in its original location. - - Middle: - The middle scenario represents a situation where - the source code also does not exist locally. - In this case, the code is again upstream - and needs to be extracted to some - local area as a Git repository. - The recipe, in this scenario, is again in its own - layer outside the workspace. - - The following command tells - devtool what recipe with - which to work and, in this case, identifies a local - area for the extracted source files that is outside - of the default workspace: - - $ devtool modify recipe srctree - - As with all extractions, the command uses - the recipe's SRC_URI to locate the - source files. - Once the files are located, the command by default - extracts them. - Providing the srctree - argument instructs devtool where - to place the extracted source. - - Within workspace, devtool - creates an append file for the recipe. - The recipe remains in its original location but - the source files are extracted to the location you - provided with srctree. - - Right: - The right scenario represents a situation - where the source tree - (srctree) exists as a - previously extracted Git structure outside of - the devtool workspace. - In this example, the recipe also exists - elsewhere in its own layer. - - - The following command tells - devtool the recipe - with which to work, uses the "-n" option to indicate - source does not need to be extracted, and uses - srctree to point to the - previously extracted source files: - - $ devtool modify -n recipe srctree - - - - Once the command finishes, it creates only - an append file for the recipe in the workspace. - The recipe and the source code remain in their - original locations. - - - - Edit the Source: - Once you have used the devtool modify - command, you are free to make changes to the source - files. - You can use any editor you like to make and save - your source code modifications. - - Build the Recipe: - Once you have updated the source files, you can build - the recipe. - - 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. - - This step assumes 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. - - 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. - - - Finish Your Work With the Recipe: - The devtool finish command creates - any patches corresponding to commits in the local - Git repository, updates the recipe to point to them - (or creates a .bbappend file to do - so, depending on the specified destination layer), and - then resets the recipe so that the recipe is built normally - rather than from the workspace. - - $ devtool finish recipe layer - - - Any changes you want to turn into patches must be - committed to the Git repository in the source tree. - - - Because there is no need to move the recipe, - devtool finish either updates the - original recipe in the original layer or the command - creates a .bbappend in a different - layer as provided by layer. - - - As a final process of the - devtool finish command, the state - of the standard layers and the upstream source is - restored so that you can build the recipe from those - areas rather than the workspace. - - You can use the devtool reset - command to put things back should you decide you - do not want to proceed with your work. - If you do use this command, realize that the source - tree is preserved. - - - - -
- -
- Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software - - - The devtool upgrade command updates - an existing recipe so that you can build it for an updated - set of source files. - The command is flexible enough to allow you to specify - source code revision and versioning schemes, extract code into - or out of the devtool workspace, and - work with any source file forms that the fetchers support. - - - - The following diagram shows the common development flow - you would use with the devtool upgrade - command: - - - - - - - - - Initiate the Upgrade: - The top part of the flow shows a typical scenario by which - you could use devtool upgrade. - The following conditions exist: - - The recipe exists in some layer external - to the devtool workspace. - - The source files for the new release - exist adjacent to the same location pointed to by - SRC_URI - in the recipe (e.g. a tarball with the new version - number in the name, or as a different revision in - the upstream Git repository). - - - A common situation is where third-party software has - undergone a revision so that it has been upgraded. - The recipe you have access to is likely in your own layer. - Thus, you need to upgrade the recipe to use the - newer version of the software: - - $ devtool upgrade -V version recipe - - By default, the devtool upgrade command - extracts source code into the sources - directory in the workspace. - If you want the code extracted to any other location, you - need to provide the srctree - positional argument with the command as follows: - - $ devtool upgrade -V version recipe srctree - - Also, in this example, the "-V" option is used to specify - the new version. - If the source files pointed to by the - SRC_URI statement in the recipe are - in a Git repository, you must provide the "-S" option and - specify a revision for the software. - - Once devtool locates the recipe, - it uses the SRC_URI variable to locate - the source code and any local patch files from other - developers are located. - The result is that the command sets up the source - code, the new version of the recipe, and an append file - all within the workspace. - - Resolve any Conflicts created by the Upgrade: - At this point, there could be some conflicts due to the - software being upgraded to a new version. - This would occur if your recipe specifies some patch files in - SRC_URI that conflict with changes - made in the new version of the software. - If this is the case, you need to resolve the conflicts - by editing the source and following the normal - git rebase conflict resolution - process. - - Before moving onto the next step, be sure to resolve any - such conflicts created through use of a newer or different - version of the software. - - Build the Recipe: - Once you have your recipe in order, you can build it. - You can either use devtool build or - bitbake. - Either method produces build output that is stored - in - TMPDIR. - - Deploy the Build Output: - When you use the devtool build - command or bitbake to build out your - recipe, you probably want to see if the resulting build - output works as expected on target hardware. - - This step assumes 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. - - 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. - - - Finish Your Work With the Recipe: - The devtool finish command creates - any patches corresponding to commits in the local - Git repository, moves the new recipe to a more permanent - layer, and then resets the recipe so that the recipe is - built normally rather than from the workspace. - If you specify a destination layer that is the same as - the original source, then the old version of the - recipe and associated files will be removed prior to - adding the new version. - - $ devtool finish recipe layer - - - Any changes you want to turn into patches must be - committed to the Git repository in the source tree. - - As a final process of the - devtool finish command, the state - of the standard layers and the upstream source is - restored so that you can build the recipe from those - areas rather than the workspace. - - You can use the devtool reset - command to put things back should you decide you - do not want to proceed with your work. - If you do use this command, realize that the source - tree is preserved. - - - - -
-
-
- - diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml index 37576537b4..09b13c7783 100644 --- a/documentation/dev-manual/dev-manual-start.xml +++ b/documentation/dev-manual/dev-manual-start.xml @@ -199,10 +199,10 @@ Setting Up to Work on a Kernel - Kernel development is best accomplished using the - devtool tool and not through traditional - kernel workflow methods. - This section provides procedures for both. + Kernel development is best accomplished using + devtool + and not through traditional kernel workflow methods. + This section provides procedures to set up for both.
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml index 55cacb7941..e7eb70d91b 100644 --- a/documentation/dev-manual/dev-manual.xml +++ b/documentation/dev-manual/dev-manual.xml @@ -152,8 +152,6 @@ - - diff --git a/documentation/dev-manual/figures/devtool-add-flow.png b/documentation/dev-manual/figures/devtool-add-flow.png deleted file mode 100644 index 985ac331f1..0000000000 Binary files a/documentation/dev-manual/figures/devtool-add-flow.png and /dev/null differ diff --git a/documentation/dev-manual/figures/devtool-modify-flow.png b/documentation/dev-manual/figures/devtool-modify-flow.png deleted file mode 100644 index fd684ffbe9..0000000000 Binary files a/documentation/dev-manual/figures/devtool-modify-flow.png and /dev/null differ diff --git a/documentation/dev-manual/figures/devtool-upgrade-flow.png b/documentation/dev-manual/figures/devtool-upgrade-flow.png deleted file mode 100644 index 65474dad02..0000000000 Binary files a/documentation/dev-manual/figures/devtool-upgrade-flow.png and /dev/null differ diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml index e62fb67ed1..bb03c60a2c 100644 --- a/documentation/kernel-dev/kernel-dev-intro.xml +++ b/documentation/kernel-dev/kernel-dev-intro.xml @@ -237,7 +237,7 @@ Other Resources - The sections that follow provide instructions for completing + The remainder of this manual provides instructions for completing specific Linux kernel development tasks. These instructions assume you are comfortable working with BitBake @@ -251,9 +251,9 @@ Yocto Project Quick Start - The - "Modifying Source Code" - section in the Yocto Project Development Manual + devtool workflow + as described in the Yocto Project Software Development Kit + (SDK) Developer's Guide. The diff --git a/documentation/mega-manual/figures/devtool-add-flow.png b/documentation/mega-manual/figures/devtool-add-flow.png deleted file mode 100644 index c09e60e355..0000000000 Binary files a/documentation/mega-manual/figures/devtool-add-flow.png and /dev/null differ diff --git a/documentation/mega-manual/figures/devtool-modify-flow.png b/documentation/mega-manual/figures/devtool-modify-flow.png deleted file mode 100644 index cd7f4d05b1..0000000000 Binary files a/documentation/mega-manual/figures/devtool-modify-flow.png and /dev/null differ diff --git a/documentation/mega-manual/figures/devtool-upgrade-flow.png b/documentation/mega-manual/figures/devtool-upgrade-flow.png deleted file mode 100644 index d25168c840..0000000000 Binary files a/documentation/mega-manual/figures/devtool-upgrade-flow.png and /dev/null differ diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml index a6fdce5e6c..d7d66143a7 100644 --- a/documentation/mega-manual/mega-manual.xml +++ b/documentation/mega-manual/mega-manual.xml @@ -130,8 +130,6 @@ xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-start.xml"/> - Tip + The use of devtool is not limited to + the extensible SDK. + You can use devtool to help you easily + develop any project whose build output must be part of an + image built using the OpenEmbedded build system. + @@ -244,6 +251,12 @@ number of sub-commands for each function. You can run devtool --help to see all the commands. + + See the + "devtool Quick Reference" + in the Yocto Project Reference Manual for a + devtool quick reference. + @@ -1262,7 +1275,7 @@ Working With Recipes - When building a recipe with devtool build the + When building a recipe with devtool build, the typical build progression is as follows: diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml index 78881d4185..409d537645 100644 --- a/documentation/yocto-project-qs/yocto-project-qs.xml +++ b/documentation/yocto-project-qs/yocto-project-qs.xml @@ -945,9 +945,7 @@ is a great place to get a feel for how to use the Yocto Project. The manual contains conceptual and procedural information - that covers - common development models - and introduces + that introduces the Yocto Project open source development environment. The manual also contains several targeted sections that cover specific