From 293b53674c1c97a29a8beaffc82130e90c0d3c2b Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 3 Jul 2017 15:27:58 -0700 Subject: documentation: Moved devtool workflow to sdk manual Fixes [YOCTO #11630] The section on the devtool workflow in the dev-manual was 99% identical to what was in the sdk-manual. I have moved the workflow procedure from the old "Model" chapter of the dev-manual to be merged with what was in the sdk-manual. In truth, the only things added were a note about devtool not being exclusive to SDK development. The result of moving (deleting) this section was that the "model" chapter of the dev-manual went away. The devtool stuff, Quilt, devshell, and python shell are all out now and there is no chapter left. So, mega-manual had to be adjusted to not pull that chapter in when building the dev-manual. I had to delete three figures that were used in the flow. The figures were already replicated in the sdk-manual. The figures were deleted from the figures folder of both the dev-manual and the mega-manual. I had to make sure all references to the old devtool stuf in the YP doc set were adjusted. (From yocto-docs rev: 5dbd643d31ab502df53a22229e457a03da7772b7) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 721 -------------------------- 1 file changed, 721 deletions(-) delete mode 100644 documentation/dev-manual/dev-manual-model.xml (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 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. - - - - -
-
-
- - -- cgit v1.2.3-54-g00ecf