dev-manual: Added section for devtool modify flow

New figure and some writer notes for now (From yocto-docs rev: 0a627626f5f353e514b0225b468b0bd0fa3ceef3) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
author: Scott Rifenbark <srifenbark@gmail.com> 2016-02-11 17:14:32 -0800
committer: Richard Purdie <richard.purdie@linuxfoundation.org> 2016-03-03 17:40:12 +0000
commit: 7699f0ab60b000c38233ba99245df1ff76c44217 (patch)
tree: ec68e6cd9d2232509c8f6fa5af8e7d216a101d03
parent: 1eecaea70d0c801d08cea17e57c8693f8058cdce (diff)
download: poky-7699f0ab60b000c38233ba99245df1ff76c44217.tar.gz
1 files changed, 275 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index d3fadbd1f7..b07b6c96c9 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1952,6 +1952,281 @@
                </orderedlist>
            </para>
        </section>
+        <section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'>
+            <title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe</title>
+            <para>
+                The <filename>devtool modify</filename> 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.
+            </para>
+            <para>
+                Depending on your particular scenario, the arguments and options
+                you use with <filename>devtool modify</filename> form different
+                combinations.
+                The following diagram shows common development flows
+                you would use with the <filename>devtool modify</filename>
+                command:
+            </para>
+            <para>
+                <imagedata fileref="figures/devtool-modify-flow.png" align="center" />
+            </para>
+            <para>
+                <orderedlist>
+                    <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
+                        The top part of the flow shows three scenarios by which
+                        you could use <filename>devtool modify</filename> to
+                        prepare to work on source files.
+                        Each scenario assumes the following:
+                        <itemizedlist>
+                            <listitem><para>The recipe exists in some layer external
+                                to the <filename>devtool</filename> workspace.
+                                </para></listitem>
+                            <listitem><para>The source files exist in a Git
+                                structure either upstream in an un-extracted
+                                state or locally in a previously extracted
+                                state.
+                                </para></listitem>
+                        </itemizedlist>
+                        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.
+                        <itemizedlist>
+                            <listitem><para><emphasis>Left</emphasis>:
+                                The left scenario represents a situation
+                                where the source tree (srctree) exists as a
+                                previously extracted Git structure outside of
+                                the <filename>devtool</filename> workspace.
+                                In this example, the recipe also exists
+                                elsewhere in its own layer
+                                (i.e. <filename>meta-</filename><replaceable>layername</replaceable>).
+                                </para>
+                                <para>The following command tells
+                                <filename>devtool</filename> the recipe
+                                with which to work and uses
+                                <replaceable>srctree</replaceable> to point to the
+                                previously extracted source files:
+                                <literallayout class='monospaced'>
+     $ devtool modify <replaceable>recipe srctree</replaceable>
+                                </literallayout>
+                                Because <filename>devtool</filename> uses the
+                                <filename>conf/bblayers.conf</filename> to
+                                identify layers in which to look for recipes,
+                                you do not have to provide anything beyond a
+                                recipe's name with the command.
+                                In other words, you do not have to provide a
+                                full recipe pathname or provide any file naming
+                                extensions for <replaceable>recipe</replaceable>.
+                                </para>
+                                <para>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.
+                                </para></listitem>
+                            <listitem><para><emphasis>Middle</emphasis>:
+                                The middle scenario represents a situation where
+                                the source code does not exist locally.
+                                In this case, the code is in an upstream Git
+                                repository and needs to be extracted to some
+                                local area.
+                                The recipe, in this scenario, is again in its own
+                                layer outside the workspace.</para>
+                                <para>The following command tells
+                                <filename>devtool</filename> what recipe with
+                                which to work and also uses the "-x" option to
+                                instruct <filename>devtool</filename> to locate and
+                                extract the source code:
+                                <literallayout class='monospaced'>
+     $ devtool modify -x <replaceable>recipe srctree</replaceable>
+                                </literallayout>
+                                With the help of the
+                                <filename>conf/bblayers.conf</filename> file,
+                                <filename>devtool</filename>locates the recipe.
+                                Inside the recipe, the
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                                variable points to where the source code and
+                                any local patch files from other developers are
+                                located.
+                                <note>
+                                    You cannot provide an URL for
+                                    <replaceable>srctree</replaceable> when using the
+                                    <filename>devtool modify</filename> command.
+                                </note>
+                                Once the files are located, the command extracts
+                                them to the location specified by
+                                <replaceable>srctree</replaceable>.</para>
+                                <para>Within workspace, <filename>devtool</filename>
+                                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 <replaceable>srctree</replaceable>.
+                                </para></listitem>
+                            <listitem><para><emphasis>Right</emphasis>:
+                                The right scenario represents another situation
+                                where the source code does not exist locally
+                                and again needs to be extracted.
+                                However, in this situation, you want to extract the
+                                source into the workspace.
+                                The recipe, in this scenario, is again in its own
+                                layer outside the workspace.</para>
+                                <para>The following command identifies the recipe
+                                and instructs <filename>devtool</filename> to
+                                extract the source files using the "-x" option:
+                                <literallayout class='monospaced'>
+     $ devtool modify -x <replaceable>recipe</replaceable>
+                                </literallayout>
+                                As with the previous example, the
+                                <filename>conf/bblayers.conf</filename> file
+                                helps locate the recipe.
+                                And, as with all extractions, the command uses
+                                the recipe's <filename>SRC_URI</filename> to locate the
+                                source files.
+                                With this scenario, however, since no
+                                <replaceable>srctree</replaceable> argument exists, the
+                                <filename>devtool modify</filename> command extracts the
+                                source files to a Git structure using the default
+                                location within the workspace.
+                                The result is that the command set up both the source
+                                code and an append file within the workspace with the
+                                recipe remaining in its original location.
+                                </para></listitem>
+                            </itemizedlist>
+                        </para></listitem>
+                    <listitem><para><emphasis>Edit the Source</emphasis>:
+                        Once you have used the <filename>devtool modify</filename>
+                        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.
+                        </para></listitem>
+                    <listitem><para><emphasis>Build the Recipe</emphasis>:
+                        Once you have updated the source files, you can build
+                        the recipe.
+                        You can either use <filename>devtool build</filename> or
+                        <filename>bitbake</filename>.
+                        Either method produces build output that is stored
+                        in
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
+                        </para></listitem>
+                    <listitem><para><emphasis>Test Your Changes</emphasis>:
+                        Once your code is built, you can test it for
+                        correct operation.
+                        If you have actual hardware, you can use the
+                        <filename>devtool deploy-target</filename> command
+                        to put the build output on the target.
+                        If you do not have target hardware, you can deploy
+                        the output to QEMU where it can emulate the hardware:
+                        <literallayout class='monospaced'>
+     $ devtool deploy-target <replaceable>recipe target</replaceable>
+                        </literallayout>
+                        Regardless of where you are deploying the build
+                        output, the <replaceable>target</replaceable> must
+                        be running an SSH server.
+                        For example, to run the <filename>dropbear</filename>
+                        SSH server in an image you are going to be running on
+                        QEMU, be sure this statement is in your
+                        <filename>conf/local.conf</filename> file:
+                        <literallayout class='monospaced'>
+     EXTRA_IMAGE_FEATURES += "ssh-server-dropbear"
+                        </literallayout>
+                        Here is a <filename>devtool deploy-target</filename>
+                        command example that uses the
+                        <filename>busybox</filename> recipe and QEMU as
+                        the target:
+                        <literallayout class='monospaced'>
+     $ devtool deploy-target busybox root@192.168.7.2
+                        </literallayout>
+                        <note>
+                            It is worth mentioning that you can load an image
+                            onto your <replaceable>target</replaceable> and
+                            while it is running, deploy your package build
+                            output to the target as the image is running.
+                            You can also rebuild your image using
+                            <filename>bitbake</filename> and it will pick up
+                            your new package output.
+                            From there, you could re-run the image on QEMU
+                            to see the effects of your
+                            <filename>devtool build</filename> output.
+                        </note>
+                        You can continue to change, build, and test your
+                        changes until you are satisfied with the code's
+                        behavior.
+                        </para></listitem>
+                    <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
+                        After you have debugged your changes, you can
+                        use <filename>devtool update-recipe</filename> to
+                        generate patch files for all the commits you have
+                        made.
+                        <note>
+                            Patch files are generated only for changes
+                            you have committed.
+                        </note>
+                        <literallayout class='monospaced'>
+     $ devtool update-recipe <replaceable>recipe</replaceable>
+                        </literallayout>
+                        By default, <filename>devtool</filename> updates
+                        the recipe's <filename>SRC_URI</filename> statement
+                        to include the location for the patch files it
+                        generates.
+                        <note>
+                            You can use the
+                            "--append <replaceable>LAYERDIR</replaceable>
+                            option to cause the command to create append files
+                            in a specific layer rather than the default
+                            recipe layer.
+                        </note>
+                        The command also creates a <replaceable>recipe</replaceable>
+                        folder beneath the folder in which the recipe resides
+                        that contains the actual <filename>*.patch</filename>
+                        files.
+                        </para></listitem>
+                    <listitem><para><emphasis>Make Sure the Recipe is in the Final Layer</emphasis>:
+                        Strictly speaking, this step is not necessary if
+                        you begin this workflow with the recipe in its own
+                        proper layer outside of the <filename>devtool</filename>
+                        workspace.
+                        However, it is included here so that when you do the
+                        final step following this you do not lose the recipe
+                        should it be in the workspace, which is possible
+                        (e.g. starting with <filename>devtool add</filename> to
+                        create a recipe in the workspace).</para>
+                        <para>You should be sure that the recipe is located
+                        outside of the workspace before using the
+                        <filename>devtool reset</filename> command described in
+                        the next step.
+                        </para></listitem>
+                    <listitem><para><emphasis>Restore the Workspace</emphasis>:
+                        The <filename>devtool reset</filename> restores the
+                        state so that standard layers and upstream sources are
+                        used to build the recipe rather than what is in the
+                        workspace.
+                        Restoring the workspace removes all traces of the
+                        <replaceable>recipe</replaceable>.
+                        <literallayout class='monospaced'>
+     $ devtool reset <replaceable>recipe</replaceable>
+                        </literallayout>
+                        Once the workspace is restored, you can use it again for
+                        working on different code.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
    </section>
    <section id='devtool-quick-reference'>
author	Scott Rifenbark <srifenbark@gmail.com>	2016-02-11 17:14:32 -0800
committer	Richard Purdie <richard.purdie@linuxfoundation.org>	2016-03-03 17:40:12 +0000
commit	7699f0ab60b000c38233ba99245df1ff76c44217 (patch)
tree	ec68e6cd9d2232509c8f6fa5af8e7d216a101d03
parent	1eecaea70d0c801d08cea17e57c8693f8058cdce (diff)
download	poky-7699f0ab60b000c38233ba99245df1ff76c44217.tar.gz

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index d3fadbd1f7..b07b6c96c9 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1952,6 +1952,281 @@
1952	</orderedlist>	1952	</orderedlist>
1953	</para>	1953	</para>
1954	</section>	1954	</section>
		1955
		1956	<section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'>
		1957	<title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe</title>
		1958
		1959	<para>
		1960	The <filename>devtool modify</filename> command prepares the
		1961	way to work on existing code that already has a recipe in
		1962	place.
		1963	The command is flexible enough to allow you to extract code,
		1964	specify the existing recipe, and keep track of and gather any
		1965	patch files from other developers that are
		1966	associated with the code.
		1967	</para>
		1968
		1969	<para>
		1970	Depending on your particular scenario, the arguments and options
		1971	you use with <filename>devtool modify</filename> form different
		1972	combinations.
		1973	The following diagram shows common development flows
		1974	you would use with the <filename>devtool modify</filename>
		1975	command:
		1976	</para>
		1977
		1978	<para>
		1979	<imagedata fileref="figures/devtool-modify-flow.png" align="center" />
		1980	</para>
		1981
		1982	<para>
		1983	<orderedlist>
		1984	<listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
		1985	The top part of the flow shows three scenarios by which
		1986	you could use <filename>devtool modify</filename> to
		1987	prepare to work on source files.
		1988	Each scenario assumes the following:
		1989	<itemizedlist>
		1990	<listitem><para>The recipe exists in some layer external
		1991	to the <filename>devtool</filename> workspace.
		1992	</para></listitem>
		1993	<listitem><para>The source files exist in a Git
		1994	structure either upstream in an un-extracted
		1995	state or locally in a previously extracted
		1996	state.
		1997	</para></listitem>
		1998	</itemizedlist>
		1999	The typical situation is where another developer has
		2000	created some layer for use with the Yocto Project and
		2001	their recipe already resides in that layer.
		2002	Furthermore, their source code is readily available
		2003	either upstream or locally.
		2004	<itemizedlist>
		2005	<listitem><para><emphasis>Left</emphasis>:
		2006	The left scenario represents a situation
		2007	where the source tree (srctree) exists as a
		2008	previously extracted Git structure outside of
		2009	the <filename>devtool</filename> workspace.
		2010	In this example, the recipe also exists
		2011	elsewhere in its own layer
		2012	(i.e. <filename>meta-</filename><replaceable>layername</replaceable>).
		2013	</para>
		2014
		2015	<para>The following command tells
		2016	<filename>devtool</filename> the recipe
		2017	with which to work and uses
		2018	<replaceable>srctree</replaceable> to point to the
		2019	previously extracted source files:
		2020	<literallayout class='monospaced'>
		2021	$ devtool modify <replaceable>recipe srctree</replaceable>
		2022	</literallayout>
		2023	Because <filename>devtool</filename> uses the
		2024	<filename>conf/bblayers.conf</filename> to
		2025	identify layers in which to look for recipes,
		2026	you do not have to provide anything beyond a
		2027	recipe's name with the command.
		2028	In other words, you do not have to provide a
		2029	full recipe pathname or provide any file naming
		2030	extensions for <replaceable>recipe</replaceable>.
		2031	</para>
		2032
		2033	<para>Once the command finishes, it creates only
		2034	an append file for the recipe in the workspace.
		2035	The recipe and the source code remain in their
		2036	original locations.
		2037	</para></listitem>
		2038	<listitem><para><emphasis>Middle</emphasis>:
		2039	The middle scenario represents a situation where
		2040	the source code does not exist locally.
		2041	In this case, the code is in an upstream Git
		2042	repository and needs to be extracted to some
		2043	local area.
		2044	The recipe, in this scenario, is again in its own
		2045	layer outside the workspace.</para>
		2046
		2047	<para>The following command tells
		2048	<filename>devtool</filename> what recipe with
		2049	which to work and also uses the "-x" option to
		2050	instruct <filename>devtool</filename> to locate and
		2051	extract the source code:
		2052	<literallayout class='monospaced'>
		2053	$ devtool modify -x <replaceable>recipe srctree</replaceable>
		2054	</literallayout>
		2055	With the help of the
		2056	<filename>conf/bblayers.conf</filename> file,
		2057	<filename>devtool</filename>locates the recipe.
		2058	Inside the recipe, the
		2059	<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
		2060	variable points to where the source code and
		2061	any local patch files from other developers are
		2062	located.
		2063	<note>
		2064	You cannot provide an URL for
		2065	<replaceable>srctree</replaceable> when using the
		2066	<filename>devtool modify</filename> command.
		2067	</note>
		2068	Once the files are located, the command extracts
		2069	them to the location specified by
		2070	<replaceable>srctree</replaceable>.</para>
		2071
		2072	<para>Within workspace, <filename>devtool</filename>
		2073	creates an append file for the recipe.
		2074	The recipe remains in its original location but
		2075	the source files are extracted to the location you
		2076	provided with <replaceable>srctree</replaceable>.
		2077	</para></listitem>
		2078	<listitem><para><emphasis>Right</emphasis>:
		2079	The right scenario represents another situation
		2080	where the source code does not exist locally
		2081	and again needs to be extracted.
		2082	However, in this situation, you want to extract the
		2083	source into the workspace.
		2084	The recipe, in this scenario, is again in its own
		2085	layer outside the workspace.</para>
		2086
		2087	<para>The following command identifies the recipe
		2088	and instructs <filename>devtool</filename> to
		2089	extract the source files using the "-x" option:
		2090	<literallayout class='monospaced'>
		2091	$ devtool modify -x <replaceable>recipe</replaceable>
		2092	</literallayout>
		2093	As with the previous example, the
		2094	<filename>conf/bblayers.conf</filename> file
		2095	helps locate the recipe.
		2096	And, as with all extractions, the command uses
		2097	the recipe's <filename>SRC_URI</filename> to locate the
		2098	source files.
		2099	With this scenario, however, since no
		2100	<replaceable>srctree</replaceable> argument exists, the
		2101	<filename>devtool modify</filename> command extracts the
		2102	source files to a Git structure using the default
		2103	location within the workspace.
		2104	The result is that the command set up both the source
		2105	code and an append file within the workspace with the
		2106	recipe remaining in its original location.
		2107	</para></listitem>
		2108	</itemizedlist>
		2109	</para></listitem>
		2110	<listitem><para><emphasis>Edit the Source</emphasis>:
		2111	Once you have used the <filename>devtool modify</filename>
		2112	command, you are free to make changes to the source
		2113	files.
		2114	You can use any editor you like to make and save
		2115	your source code modifications.
		2116	</para></listitem>
		2117	<listitem><para><emphasis>Build the Recipe</emphasis>:
		2118	Once you have updated the source files, you can build
		2119	the recipe.
		2120	You can either use <filename>devtool build</filename> or
		2121	<filename>bitbake</filename>.
		2122	Either method produces build output that is stored
		2123	in
		2124	<ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
		2125	</para></listitem>
		2126	<listitem><para><emphasis>Test Your Changes</emphasis>:
		2127	Once your code is built, you can test it for
		2128	correct operation.
		2129	If you have actual hardware, you can use the
		2130	<filename>devtool deploy-target</filename> command
		2131	to put the build output on the target.
		2132	If you do not have target hardware, you can deploy
		2133	the output to QEMU where it can emulate the hardware:
		2134	<literallayout class='monospaced'>
		2135	$ devtool deploy-target <replaceable>recipe target</replaceable>
		2136	</literallayout>
		2137	Regardless of where you are deploying the build
		2138	output, the <replaceable>target</replaceable> must
		2139	be running an SSH server.
		2140	For example, to run the <filename>dropbear</filename>
		2141	SSH server in an image you are going to be running on
		2142	QEMU, be sure this statement is in your
		2143	<filename>conf/local.conf</filename> file:
		2144	<literallayout class='monospaced'>
		2145	EXTRA_IMAGE_FEATURES += "ssh-server-dropbear"
		2146	</literallayout>
		2147	Here is a <filename>devtool deploy-target</filename>
		2148	command example that uses the
		2149	<filename>busybox</filename> recipe and QEMU as
		2150	the target:
		2151	<literallayout class='monospaced'>
		2152	$ devtool deploy-target busybox root@192.168.7.2
		2153	</literallayout>
		2154	<note>
		2155	It is worth mentioning that you can load an image
		2156	onto your <replaceable>target</replaceable> and
		2157	while it is running, deploy your package build
		2158	output to the target as the image is running.
		2159	You can also rebuild your image using
		2160	<filename>bitbake</filename> and it will pick up
		2161	your new package output.
		2162	From there, you could re-run the image on QEMU
		2163	to see the effects of your
		2164	<filename>devtool build</filename> output.
		2165	</note>
		2166	You can continue to change, build, and test your
		2167	changes until you are satisfied with the code's
		2168	behavior.
		2169	</para></listitem>
		2170	<listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
		2171	After you have debugged your changes, you can
		2172	use <filename>devtool update-recipe</filename> to
		2173	generate patch files for all the commits you have
		2174	made.
		2175	<note>
		2176	Patch files are generated only for changes
		2177	you have committed.
		2178	</note>
		2179	<literallayout class='monospaced'>
		2180	$ devtool update-recipe <replaceable>recipe</replaceable>
		2181	</literallayout>
		2182	By default, <filename>devtool</filename> updates
		2183	the recipe's <filename>SRC_URI</filename> statement
		2184	to include the location for the patch files it
		2185	generates.
		2186	<note>
		2187	You can use the
		2188	"--append <replaceable>LAYERDIR</replaceable>
		2189	option to cause the command to create append files
		2190	in a specific layer rather than the default
		2191	recipe layer.
		2192	</note>
		2193	The command also creates a <replaceable>recipe</replaceable>
		2194	folder beneath the folder in which the recipe resides
		2195	that contains the actual <filename>*.patch</filename>
		2196	files.
		2197	</para></listitem>
		2198	<listitem><para><emphasis>Make Sure the Recipe is in the Final Layer</emphasis>:
		2199	Strictly speaking, this step is not necessary if
		2200	you begin this workflow with the recipe in its own
		2201	proper layer outside of the <filename>devtool</filename>
		2202	workspace.
		2203	However, it is included here so that when you do the
		2204	final step following this you do not lose the recipe
		2205	should it be in the workspace, which is possible
		2206	(e.g. starting with <filename>devtool add</filename> to
		2207	create a recipe in the workspace).</para>
		2208
		2209	<para>You should be sure that the recipe is located
		2210	outside of the workspace before using the
		2211	<filename>devtool reset</filename> command described in
		2212	the next step.
		2213	</para></listitem>
		2214	<listitem><para><emphasis>Restore the Workspace</emphasis>:
		2215	The <filename>devtool reset</filename> restores the
		2216	state so that standard layers and upstream sources are
		2217	used to build the recipe rather than what is in the
		2218	workspace.
		2219	Restoring the workspace removes all traces of the
		2220	<replaceable>recipe</replaceable>.
		2221	<literallayout class='monospaced'>
		2222	$ devtool reset <replaceable>recipe</replaceable>
		2223	</literallayout>
		2224	Once the workspace is restored, you can use it again for
		2225	working on different code.
		2226	</para></listitem>
		2227	</orderedlist>
		2228	</para>
		2229	</section>
1955	</section>	2230	</section>
1956		2231
1957	<section id='devtool-quick-reference'>	2232	<section id='devtool-quick-reference'>