diff options
| -rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 455 |
1 files changed, 168 insertions, 287 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 843b1b788d..cef668408a 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml | |||
| @@ -1764,15 +1764,6 @@ | |||
| 1764 | 1764 | ||
| 1765 | <para> | 1765 | <para> |
| 1766 | The remainder of this section presents these workflows. | 1766 | The remainder of this section presents these workflows. |
| 1767 | <note> | ||
| 1768 | The steps in this section assume you have a previously built | ||
| 1769 | image that is already either running in QEMU or running on actual | ||
| 1770 | hardware. | ||
| 1771 | Also, it is assumed that for deployment of the image to the | ||
| 1772 | target, SSH is installed in the image and if the image is running | ||
| 1773 | on real hardware that you have network access to and from your | ||
| 1774 | development machine. | ||
| 1775 | </note> | ||
| 1776 | </para> | 1767 | </para> |
| 1777 | 1768 | ||
| 1778 | <section id='use-devtool-to-integrate-new-code'> | 1769 | <section id='use-devtool-to-integrate-new-code'> |
| @@ -1823,49 +1814,33 @@ | |||
| 1823 | feed into the <filename>devtool add</filename> workflow: | 1814 | feed into the <filename>devtool add</filename> workflow: |
| 1824 | <itemizedlist> | 1815 | <itemizedlist> |
| 1825 | <listitem><para><emphasis>Left</emphasis>: | 1816 | <listitem><para><emphasis>Left</emphasis>: |
| 1826 | The left scenario represents a situation | 1817 | The left scenario represents a common situation |
| 1827 | where the source tree (srctree) exists as a | 1818 | where the source code does not exist locally |
| 1828 | previously extracted Git structure outside of | 1819 | and needs to be extracted. |
| 1829 | the <filename>devtool</filename> workspace. | 1820 | In this situation, you just let it get |
| 1830 | </para> | 1821 | extracted to the default workspace - you do not |
| 1831 | 1822 | want it in some specific location outside of the | |
| 1832 | <para>The following command names the recipe | 1823 | workspace. |
| 1833 | and identifies where the existing source tree | 1824 | Thus, everything you need will be located in the |
| 1834 | is located: | 1825 | workspace: |
| 1835 | <literallayout class='monospaced'> | 1826 | <literallayout class='monospaced'> |
| 1836 | $ devtool add <replaceable>recipe srctree</replaceable> | 1827 | $ devtool add <replaceable>recipe fetchuri</replaceable> |
| 1837 | </literallayout> | 1828 | </literallayout> |
| 1838 | <note> | 1829 | With this command, <filename>devtool</filename> |
| 1839 | If a recipe exists that is associated with | 1830 | creates a recipe and an append file in the |
| 1840 | source code, <filename>devtool</filename> | 1831 | workspace as well as extracts the upstream |
| 1841 | can leverage off that if it knows about the | 1832 | source files into a local Git repository also |
| 1842 | layer in which the recipe resides. | 1833 | within the <filename>sources</filename> folder. |
| 1843 | Be sure to update your | ||
| 1844 | <filename>conf/bblayers.conf</filename> file | ||
| 1845 | to include the layers you want | ||
| 1846 | <filename>devtool</filename> to know about | ||
| 1847 | when looking for an existing recipe. | ||
| 1848 | </note> | ||
| 1849 | The command examines the source code and creates | ||
| 1850 | a recipe for it placing the recipe into the | ||
| 1851 | workspace.</para> | ||
| 1852 | |||
| 1853 | <para>Because the extracted source code already exists, | ||
| 1854 | <filename>devtool</filename> does not try to | ||
| 1855 | relocate it into the workspace - just the new | ||
| 1856 | (or a modified copy of) the recipe is placed in | ||
| 1857 | the workspace.</para> | ||
| 1858 | |||
| 1859 | <para>Aside from a recipe folder, the command | ||
| 1860 | also creates an append folder and places an initial | ||
| 1861 | <filename>*.bbappend</filename> within. | ||
| 1862 | </para></listitem> | 1834 | </para></listitem> |
| 1863 | <listitem><para><emphasis>Middle</emphasis>: | 1835 | <listitem><para><emphasis>Middle</emphasis>: |
| 1864 | The middle scenario represents a situation where | 1836 | The middle scenario also represents a situation where |
| 1865 | the source code does not exist locally. | 1837 | the source code does not exist locally. |
| 1866 | In this case, the code is in an upstream Git | 1838 | In this case, the code is again upstream |
| 1867 | repository and needs to be extracted to some | 1839 | and needs to be extracted to some |
| 1868 | local area. | 1840 | local area - this time outside of the default |
| 1841 | workspace. | ||
| 1842 | As always, if required <filename>devtool</filename> creates | ||
| 1843 | a Git repository locally during the extraction. | ||
| 1869 | Furthermore, the first positional argument | 1844 | Furthermore, the first positional argument |
| 1870 | <replaceable>srctree</replaceable> in this case | 1845 | <replaceable>srctree</replaceable> in this case |
| 1871 | identifies where the | 1846 | identifies where the |
| @@ -1886,101 +1861,33 @@ | |||
| 1886 | for the recipe. | 1861 | for the recipe. |
| 1887 | </para></listitem> | 1862 | </para></listitem> |
| 1888 | <listitem><para><emphasis>Right</emphasis>: | 1863 | <listitem><para><emphasis>Right</emphasis>: |
| 1889 | The right scenario represents another situation | 1864 | The right scenario represents a situation |
| 1890 | where the source code does not exist locally | 1865 | where the source tree (srctree) has been |
| 1891 | and again needs to be extracted. | 1866 | previously prepared outside of the |
| 1892 | However, in this situation, you want to extract the | 1867 | <filename>devtool</filename> workspace. |
| 1893 | source into the workspace. | 1868 | </para> |
| 1894 | Thus, everything you need will be located in the | 1869 | |
| 1895 | workspace: | 1870 | <para>The following command names the recipe |
| 1871 | and identifies where the existing source tree | ||
| 1872 | is located: | ||
| 1896 | <literallayout class='monospaced'> | 1873 | <literallayout class='monospaced'> |
| 1897 | $ devtool add <replaceable>recipe fetchuri</replaceable> | 1874 | $ devtool add <replaceable>recipe srctree</replaceable> |
| 1898 | </literallayout> | 1875 | </literallayout> |
| 1899 | With this command, <filename>devtool</filename> | 1876 | The command examines the source code and creates |
| 1900 | creates a recipe and an append file in the | 1877 | a recipe for it placing the recipe into the |
| 1901 | workspace as well as extracts the upstream | 1878 | workspace.</para> |
| 1902 | source files into a local Git repository also | 1879 | |
| 1903 | within the <filename>sources</filename> folder. | 1880 | <para>Because the extracted source code already exists, |
| 1881 | <filename>devtool</filename> does not try to | ||
| 1882 | relocate it into the workspace - just the new | ||
| 1883 | the recipe is placed in the workspace.</para> | ||
| 1884 | |||
| 1885 | <para>Aside from a recipe folder, the command | ||
| 1886 | also creates an append folder and places an initial | ||
| 1887 | <filename>*.bbappend</filename> within. | ||
| 1904 | </para></listitem> | 1888 | </para></listitem> |
| 1905 | </itemizedlist> | 1889 | </itemizedlist> |
| 1906 | </para></listitem> | 1890 | </para></listitem> |
| 1907 | <!-- | ||
| 1908 | <listitem><para><emphasis>Add a New Recipe</emphasis>: | ||
| 1909 | The <filename>devtool add</filename> command automatically | ||
| 1910 | generates the needed Metadata that allows the OpenEmbedded | ||
| 1911 | build system to build your code. | ||
| 1912 | Following are some forms you can use to enter the command: | ||
| 1913 | <literallayout class='monospaced'> | ||
| 1914 | $ devtool add [<replaceable>recipe_name</replaceable>] <replaceable>source_path</replaceable> | ||
| 1915 | $ devtool add [<replaceable>recipe_name</replaceable>] <replaceable>source_path remote_URL</replaceable> | ||
| 1916 | $ devtool add [<replaceable>recipe_name</replaceable>] <replaceable>remote_URL</replaceable> | ||
| 1917 | </literallayout> | ||
| 1918 | The <filename>devtool</filename> command automatically detects the | ||
| 1919 | <replaceable>recipe_name</replaceable> and, in many cases, the | ||
| 1920 | version if you do not supply a name or version with the command.</para> | ||
| 1921 | <para>Running <filename>devtool</filename> for the first time | ||
| 1922 | creates a workspace layer, which by default is named | ||
| 1923 | "workspace", and adds it to your | ||
| 1924 | <filename>conf/bblayers.conf</filename> file: | ||
| 1925 | <literallayout class='monospaced'> | ||
| 1926 | <replaceable>source_path</replaceable>/<replaceable>build_directory</replaceable>/<replaceable>workspace_layer</replaceable> | ||
| 1927 | </literallayout> | ||
| 1928 | For details on the workspace layer created in the | ||
| 1929 | <replaceable>build-directory</replaceable>, | ||
| 1930 | see the | ||
| 1931 | "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>" | ||
| 1932 | section.</para> | ||
| 1933 | <para>You can also specify a <replaceable>remote_URL</replaceable> | ||
| 1934 | from which to download source instead of (or in addition | ||
| 1935 | to) specifying a <replaceable>source_path</replaceable>. | ||
| 1936 | If you specify a URL but not a <replaceable>source_path</replaceable>, | ||
| 1937 | <filename>devtool</filename> uses a subdirectory called "sources" | ||
| 1938 | within <filename>workspace</filename> to house the source files.</para> | ||
| 1939 | <para>Here is an example command that provides the | ||
| 1940 | <replaceable>remote_URL</replaceable> only: | ||
| 1941 | <literallayout class='monospaced'> | ||
| 1942 | $ devtool add ftp://ftp.bitwizard.nl/mtr/mtr-0.86.tar.gz | ||
| 1943 | NOTE: Creating workspace layer in /home/scottrif/poky/build/workspace | ||
| 1944 | NOTE: Enabling workspace layer in bblayers.conf | ||
| 1945 | NOTE: Using default source tree path /home/scottrif/poky/build/workspace/sources/mtr | ||
| 1946 | NOTE: Recipe /home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb | ||
| 1947 | has been automatically created; further editing may be required to | ||
| 1948 | make it fully functional | ||
| 1949 | $ | ||
| 1950 | </literallayout> | ||
| 1951 | In this example, <filename>devtool</filename> detected both | ||
| 1952 | a recipe name and version from the software for use when | ||
| 1953 | creating the <filename>mtr_0.86.bb</filename> recipe file. | ||
| 1954 | Because no <filename>source_path</filename> was provided, the | ||
| 1955 | tool also created the default directory | ||
| 1956 | <filename>sources/mtr/</filename> in the created | ||
| 1957 | <filename>workspace</filename> directory.</para> | ||
| 1958 | <para>If you are using <filename>devtool add</filename> | ||
| 1959 | to fetch source from a remote URL, the command turns | ||
| 1960 | the source directory into a Git repository if one does | ||
| 1961 | not already exist. | ||
| 1962 | You can disable this behavior by using the "‐‐no-git" | ||
| 1963 | option. | ||
| 1964 | The <filename>devtool add</filename> command does this in | ||
| 1965 | order to support using | ||
| 1966 | <filename>devtool update-recipe</filename>, shown as step | ||
| 1967 | 5 in the flow diagram, to later create patches. | ||
| 1968 | <tip> | ||
| 1969 | In case you ever need to locate the directory in which | ||
| 1970 | <filename>devtool</filename> creates the recipe or, you | ||
| 1971 | need to locate the source, you can use <filename>devtool</filename> | ||
| 1972 | to check status: | ||
| 1973 | <literallayout class='monospaced'> | ||
| 1974 | $ devtool status | ||
| 1975 | mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) | ||
| 1976 | $ | ||
| 1977 | </literallayout> | ||
| 1978 | Continuing with the example, the tool returns the location | ||
| 1979 | for the source followed by the location and name of the | ||
| 1980 | recipe. | ||
| 1981 | </tip> | ||
| 1982 | </para></listitem> | ||
| 1983 | --> | ||
| 1984 | <listitem><para><emphasis>Edit the Recipe</emphasis>: | 1891 | <listitem><para><emphasis>Edit the Recipe</emphasis>: |
| 1985 | At this point, you can use <filename>devtool edit-recipe</filename> | 1892 | At this point, you can use <filename>devtool edit-recipe</filename> |
| 1986 | to open up the editor as defined by the | 1893 | to open up the editor as defined by the |
| @@ -1999,6 +1906,10 @@ | |||
| 1999 | <para>If you need to take the build output and eventually | 1906 | <para>If you need to take the build output and eventually |
| 2000 | move it to the target hardware, you would use | 1907 | move it to the target hardware, you would use |
| 2001 | <filename>devtool build</filename>: | 1908 | <filename>devtool build</filename>: |
| 1909 | <note> | ||
| 1910 | You could use <filename>bitbake</filename> to build | ||
| 1911 | the recipe as well. | ||
| 1912 | </note> | ||
| 2002 | <literallayout class='monospaced'> | 1913 | <literallayout class='monospaced'> |
| 2003 | $ devtool build <replaceable>recipe</replaceable> | 1914 | $ devtool build <replaceable>recipe</replaceable> |
| 2004 | </literallayout></para> | 1915 | </literallayout></para> |
| @@ -2015,6 +1926,15 @@ | |||
| 2015 | command to build out your recipe, you probably want to | 1926 | command to build out your recipe, you probably want to |
| 2016 | see if the resulting build output works as expected on target | 1927 | see if the resulting build output works as expected on target |
| 2017 | hardware. | 1928 | hardware. |
| 1929 | <note> | ||
| 1930 | This step assumes you have a previously built | ||
| 1931 | image that is already either running in QEMU or | ||
| 1932 | running on actual hardware. | ||
| 1933 | Also, it is assumed that for deployment of the image | ||
| 1934 | to the target, SSH is installed in the image and if | ||
| 1935 | the image is running on real hardware that you have | ||
| 1936 | network access to and from your development machine. | ||
| 1937 | </note> | ||
| 2018 | You can deploy your build output to that target hardware by | 1938 | You can deploy your build output to that target hardware by |
| 2019 | using the <filename>devtool deploy-target</filename> command: | 1939 | using the <filename>devtool deploy-target</filename> command: |
| 2020 | <literallayout class='monospaced'> | 1940 | <literallayout class='monospaced'> |
| @@ -2030,8 +1950,10 @@ | |||
| 2030 | specific command that allows you to do this. | 1950 | specific command that allows you to do this. |
| 2031 | </para></listitem> | 1951 | </para></listitem> |
| 2032 | <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>: | 1952 | <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>: |
| 2033 | Once you are satisfied with the recipe you probably want | 1953 | Once you are satisfied with the recipe, if you have made |
| 2034 | to generate patch files that go with the recipe. | 1954 | any changes to the source tree that you want to have |
| 1955 | applied by the recipe, you need to generate patches | ||
| 1956 | from those changes. | ||
| 2035 | You do this before moving the recipe | 1957 | You do this before moving the recipe |
| 2036 | to its final layer and cleaning up the workspace area | 1958 | to its final layer and cleaning up the workspace area |
| 2037 | <filename>devtool</filename> uses. | 1959 | <filename>devtool</filename> uses. |
| @@ -2040,11 +1962,11 @@ | |||
| 2040 | <para>To convert commits created using Git to patch files, | 1962 | <para>To convert commits created using Git to patch files, |
| 2041 | use the <filename>devtool update-recipe</filename> command. | 1963 | use the <filename>devtool update-recipe</filename> command. |
| 2042 | <note> | 1964 | <note> |
| 2043 | Any patches added, removed, or otherwise must be | 1965 | Any changes you want to turn into patches must be |
| 2044 | previously committed to the upstream Git repository. | 1966 | committed to the Git repository in the source tree. |
| 2045 | </note> | 1967 | </note> |
| 2046 | <literallayout class='monospaced'> | 1968 | <literallayout class='monospaced'> |
| 2047 | $ devtool update-recipe <replaceable>recipe_name</replaceable> | 1969 | $ devtool update-recipe <replaceable>recipe</replaceable> |
| 2048 | </literallayout> | 1970 | </literallayout> |
| 2049 | </para></listitem> | 1971 | </para></listitem> |
| 2050 | <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: | 1972 | <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: |
| @@ -2105,10 +2027,9 @@ | |||
| 2105 | <listitem><para>The recipe exists in some layer external | 2027 | <listitem><para>The recipe exists in some layer external |
| 2106 | to the <filename>devtool</filename> workspace. | 2028 | to the <filename>devtool</filename> workspace. |
| 2107 | </para></listitem> | 2029 | </para></listitem> |
| 2108 | <listitem><para>The source files exist in a Git | 2030 | <listitem><para>The source files exist upstream in an |
| 2109 | structure either upstream in an un-extracted | 2031 | un-extracted state or locally in a previously |
| 2110 | state or locally in a previously extracted | 2032 | extracted state. |
| 2111 | state. | ||
| 2112 | </para></listitem> | 2033 | </para></listitem> |
| 2113 | </itemizedlist> | 2034 | </itemizedlist> |
| 2114 | The typical situation is where another developer has | 2035 | The typical situation is where another developer has |
| @@ -2118,44 +2039,49 @@ | |||
| 2118 | either upstream or locally. | 2039 | either upstream or locally. |
| 2119 | <itemizedlist> | 2040 | <itemizedlist> |
| 2120 | <listitem><para><emphasis>Left</emphasis>: | 2041 | <listitem><para><emphasis>Left</emphasis>: |
| 2121 | The left scenario represents a situation | 2042 | The left scenario represents a common situation |
| 2122 | where the source tree (srctree) exists as a | 2043 | where the source code does not exist locally |
| 2123 | previously extracted Git structure outside of | 2044 | and needs to be extracted. |
| 2124 | the <filename>devtool</filename> workspace. | 2045 | In this situation, the source is extracted |
| 2125 | In this example, the recipe also exists | 2046 | into the default workspace location. |
| 2126 | elsewhere in its own layer | 2047 | The recipe, in this scenario, is in its own |
| 2127 | (i.e. <filename>meta-</filename><replaceable>layername</replaceable>). | 2048 | layer outside the workspace |
| 2049 | (i.e. | ||
| 2050 | <filename>meta-</filename><replaceable>layername</replaceable>). | ||
| 2128 | </para> | 2051 | </para> |
| 2129 | 2052 | ||
| 2130 | <para>The following command tells | 2053 | <para>The following command identifies the recipe |
| 2131 | <filename>devtool</filename> the recipe | 2054 | and instructs <filename>devtool</filename> to |
| 2132 | with which to work and uses | 2055 | extract the source files using the "-x" option: |
| 2133 | <replaceable>srctree</replaceable> to point to the | ||
| 2134 | previously extracted source files: | ||
| 2135 | <literallayout class='monospaced'> | 2056 | <literallayout class='monospaced'> |
| 2136 | $ devtool modify <replaceable>recipe srctree</replaceable> | 2057 | $ devtool modify -x <replaceable>recipe</replaceable> |
| 2137 | </literallayout> | 2058 | </literallayout> |
| 2138 | Because <filename>devtool</filename> uses the | 2059 | Once <filename>devtool</filename>locates the recipe, |
| 2139 | <filename>conf/bblayers.conf</filename> to | 2060 | it uses the |
| 2140 | identify layers in which to look for recipes, | 2061 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| 2141 | you do not have to provide anything beyond a | 2062 | variable to locate the source code and |
| 2142 | recipe's name with the command. | 2063 | any local patch files from other developers are |
| 2143 | In other words, you do not have to provide a | 2064 | located. |
| 2144 | full recipe pathname or provide any file naming | 2065 | <note> |
| 2145 | extensions for <replaceable>recipe</replaceable>. | 2066 | You cannot provide an URL for |
| 2146 | </para> | 2067 | <replaceable>srctree</replaceable> when using the |
| 2147 | 2068 | <filename>devtool modify</filename> command. | |
| 2148 | <para>Once the command finishes, it creates only | 2069 | </note> |
| 2149 | an append file for the recipe in the workspace. | 2070 | With this scenario, however, since no |
| 2150 | The recipe and the source code remain in their | 2071 | <replaceable>srctree</replaceable> argument exists, the |
| 2151 | original locations. | 2072 | <filename>devtool modify</filename> command extracts the |
| 2073 | source files to a Git structure using the default | ||
| 2074 | location within the workspace. | ||
| 2075 | The result is that the command set up both the source | ||
| 2076 | code and an append file within the workspace with the | ||
| 2077 | recipe remaining in its original location. | ||
| 2152 | </para></listitem> | 2078 | </para></listitem> |
| 2153 | <listitem><para><emphasis>Middle</emphasis>: | 2079 | <listitem><para><emphasis>Middle</emphasis>: |
| 2154 | The middle scenario represents a situation where | 2080 | The middle scenario represents a situation where |
| 2155 | the source code does not exist locally. | 2081 | the source code also does not exist locally. |
| 2156 | In this case, the code is in an upstream Git | 2082 | In this case, the code is again upstream |
| 2157 | repository and needs to be extracted to some | 2083 | and needs to be extracted to some |
| 2158 | local area. | 2084 | local area as a Git repository. |
| 2159 | The recipe, in this scenario, is again in its own | 2085 | The recipe, in this scenario, is again in its own |
| 2160 | layer outside the workspace.</para> | 2086 | layer outside the workspace.</para> |
| 2161 | 2087 | ||
| @@ -2167,19 +2093,9 @@ | |||
| 2167 | <literallayout class='monospaced'> | 2093 | <literallayout class='monospaced'> |
| 2168 | $ devtool modify -x <replaceable>recipe srctree</replaceable> | 2094 | $ devtool modify -x <replaceable>recipe srctree</replaceable> |
| 2169 | </literallayout> | 2095 | </literallayout> |
| 2170 | With the help of the | 2096 | As with all extractions, the command uses |
| 2171 | <filename>conf/bblayers.conf</filename> file, | 2097 | the recipe's <filename>SRC_URI</filename> to locate the |
| 2172 | <filename>devtool</filename>locates the recipe. | 2098 | source files. |
| 2173 | Inside the recipe, the | ||
| 2174 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
| 2175 | variable points to where the source code and | ||
| 2176 | any local patch files from other developers are | ||
| 2177 | located. | ||
| 2178 | <note> | ||
| 2179 | You cannot provide an URL for | ||
| 2180 | <replaceable>srctree</replaceable> when using the | ||
| 2181 | <filename>devtool modify</filename> command. | ||
| 2182 | </note> | ||
| 2183 | Once the files are located, the command extracts | 2099 | Once the files are located, the command extracts |
| 2184 | them to the location specified by | 2100 | them to the location specified by |
| 2185 | <replaceable>srctree</replaceable>.</para> | 2101 | <replaceable>srctree</replaceable>.</para> |
| @@ -2191,34 +2107,28 @@ | |||
| 2191 | provided with <replaceable>srctree</replaceable>. | 2107 | provided with <replaceable>srctree</replaceable>. |
| 2192 | </para></listitem> | 2108 | </para></listitem> |
| 2193 | <listitem><para><emphasis>Right</emphasis>: | 2109 | <listitem><para><emphasis>Right</emphasis>: |
| 2194 | The right scenario represents another situation | 2110 | The right scenario represents a situation |
| 2195 | where the source code does not exist locally | 2111 | where the source tree (srctree) exists as a |
| 2196 | and again needs to be extracted. | 2112 | previously extracted Git structure outside of |
| 2197 | However, in this situation, you want to extract the | 2113 | the <filename>devtool</filename> workspace. |
| 2198 | source into the workspace. | 2114 | In this example, the recipe also exists |
| 2199 | The recipe, in this scenario, is again in its own | 2115 | elsewhere in its own layer. |
| 2200 | layer outside the workspace.</para> | 2116 | </para> |
| 2201 | 2117 | ||
| 2202 | <para>The following command identifies the recipe | 2118 | <para>The following command tells |
| 2203 | and instructs <filename>devtool</filename> to | 2119 | <filename>devtool</filename> the recipe |
| 2204 | extract the source files using the "-x" option: | 2120 | with which to work and uses |
| 2121 | <replaceable>srctree</replaceable> to point to the | ||
| 2122 | previously extracted source files: | ||
| 2205 | <literallayout class='monospaced'> | 2123 | <literallayout class='monospaced'> |
| 2206 | $ devtool modify -x <replaceable>recipe</replaceable> | 2124 | $ devtool modify <replaceable>recipe srctree</replaceable> |
| 2207 | </literallayout> | 2125 | </literallayout> |
| 2208 | As with the previous example, the | 2126 | </para> |
| 2209 | <filename>conf/bblayers.conf</filename> file | 2127 | |
| 2210 | helps locate the recipe. | 2128 | <para>Once the command finishes, it creates only |
| 2211 | And, as with all extractions, the command uses | 2129 | an append file for the recipe in the workspace. |
| 2212 | the recipe's <filename>SRC_URI</filename> to locate the | 2130 | The recipe and the source code remain in their |
| 2213 | source files. | 2131 | original locations. |
| 2214 | With this scenario, however, since no | ||
| 2215 | <replaceable>srctree</replaceable> argument exists, the | ||
| 2216 | <filename>devtool modify</filename> command extracts the | ||
| 2217 | source files to a Git structure using the default | ||
| 2218 | location within the workspace. | ||
| 2219 | The result is that the command set up both the source | ||
| 2220 | code and an append file within the workspace with the | ||
| 2221 | recipe remaining in its original location. | ||
| 2222 | </para></listitem> | 2132 | </para></listitem> |
| 2223 | </itemizedlist> | 2133 | </itemizedlist> |
| 2224 | </para></listitem> | 2134 | </para></listitem> |
| @@ -2238,49 +2148,33 @@ | |||
| 2238 | in | 2148 | in |
| 2239 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. | 2149 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. |
| 2240 | </para></listitem> | 2150 | </para></listitem> |
| 2241 | <listitem><para><emphasis>Test Your Changes</emphasis>: | 2151 | <listitem><para><emphasis>Deploy the Build Output</emphasis>: |
| 2242 | Once your code is built, you can test it for | 2152 | When you use the <filename>devtool build</filename> |
| 2243 | correct operation. | 2153 | command or <filename>bitbake</filename> to build out your |
| 2244 | If you have actual hardware, you can use the | 2154 | recipe, you probably want to see if the resulting build |
| 2245 | <filename>devtool deploy-target</filename> command | 2155 | output works as expected on target hardware. |
| 2246 | to put the build output on the target. | 2156 | <note> |
| 2247 | If you do not have target hardware, you can deploy | 2157 | This step assumes you have a previously built |
| 2248 | the output to QEMU where it can emulate the hardware: | 2158 | image that is already either running in QEMU or |
| 2159 | running on actual hardware. | ||
| 2160 | Also, it is assumed that for deployment of the image | ||
| 2161 | to the target, SSH is installed in the image and if | ||
| 2162 | the image is running on real hardware that you have | ||
| 2163 | network access to and from your development machine. | ||
| 2164 | </note> | ||
| 2165 | You can deploy your build output to that target hardware by | ||
| 2166 | using the <filename>devtool deploy-target</filename> command: | ||
| 2249 | <literallayout class='monospaced'> | 2167 | <literallayout class='monospaced'> |
| 2250 | $ devtool deploy-target <replaceable>recipe target</replaceable> | 2168 | $ devtool deploy-target <replaceable>recipe target</replaceable> |
| 2251 | </literallayout> | 2169 | </literallayout> |
| 2252 | Regardless of where you are deploying the build | 2170 | The <replaceable>target</replaceable> is a live target machine |
| 2253 | output, the <replaceable>target</replaceable> must | 2171 | running as an SSH server.</para> |
| 2254 | be running an SSH server. | 2172 | |
| 2255 | For example, to run the <filename>dropbear</filename> | 2173 | <para>You can, of course, also deploy the image you build |
| 2256 | SSH server in an image you are going to be running on | 2174 | using the <filename>devtool build-image</filename> command |
| 2257 | QEMU, be sure this statement is in your | 2175 | to actual hardware. |
| 2258 | <filename>conf/local.conf</filename> file: | 2176 | However, <filename>devtool</filename> does not provide a |
| 2259 | <literallayout class='monospaced'> | 2177 | specific command that allows you to do this. |
| 2260 | EXTRA_IMAGE_FEATURES += "ssh-server-dropbear" | ||
| 2261 | </literallayout> | ||
| 2262 | Here is a <filename>devtool deploy-target</filename> | ||
| 2263 | command example that uses the | ||
| 2264 | <filename>busybox</filename> recipe and QEMU as | ||
| 2265 | the target: | ||
| 2266 | <literallayout class='monospaced'> | ||
| 2267 | $ devtool deploy-target busybox root@192.168.7.2 | ||
| 2268 | </literallayout> | ||
| 2269 | <note> | ||
| 2270 | It is worth mentioning that you can load an image | ||
| 2271 | onto your <replaceable>target</replaceable> and | ||
| 2272 | while it is running, deploy your package build | ||
| 2273 | output to the target as the image is running. | ||
| 2274 | You can also rebuild your image using | ||
| 2275 | <filename>bitbake</filename> and it will pick up | ||
| 2276 | your new package output. | ||
| 2277 | From there, you could re-run the image on QEMU | ||
| 2278 | to see the effects of your | ||
| 2279 | <filename>devtool build</filename> output. | ||
| 2280 | </note> | ||
| 2281 | You can continue to change, build, and test your | ||
| 2282 | changes until you are satisfied with the code's | ||
| 2283 | behavior. | ||
| 2284 | </para></listitem> | 2178 | </para></listitem> |
| 2285 | <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: | 2179 | <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: |
| 2286 | After you have debugged your changes, you can | 2180 | After you have debugged your changes, you can |
| @@ -2294,50 +2188,29 @@ | |||
| 2294 | <literallayout class='monospaced'> | 2188 | <literallayout class='monospaced'> |
| 2295 | $ devtool update-recipe <replaceable>recipe</replaceable> | 2189 | $ devtool update-recipe <replaceable>recipe</replaceable> |
| 2296 | </literallayout> | 2190 | </literallayout> |
| 2297 | By default, <filename>devtool</filename> updates | 2191 | By default, the |
| 2298 | the recipe's <filename>SRC_URI</filename> statement | 2192 | <filename>devtool update-recipe</filename> command |
| 2299 | to include the location for the patch files it | 2193 | creates the patch files in a folder named the same |
| 2300 | generates. | 2194 | as the recipe beneath the folder in which the recipe |
| 2195 | resides, and updates the recipe's | ||
| 2196 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
| 2197 | statement to point to the generated patch files. | ||
| 2301 | <note> | 2198 | <note> |
| 2302 | You can use the | 2199 | You can use the |
| 2303 | "--append <replaceable>LAYERDIR</replaceable> | 2200 | "--append <replaceable>LAYERDIR</replaceable>" |
| 2304 | option to cause the command to create append files | 2201 | option to cause the command to create append files |
| 2305 | in a specific layer rather than the default | 2202 | in a specific layer rather than the default |
| 2306 | recipe layer. | 2203 | recipe layer. |
| 2307 | </note> | 2204 | </note> |
| 2308 | The command also creates a <replaceable>recipe</replaceable> | ||
| 2309 | folder beneath the folder in which the recipe resides | ||
| 2310 | that contains the actual <filename>*.patch</filename> | ||
| 2311 | files. | ||
| 2312 | </para></listitem> | ||
| 2313 | <listitem><para><emphasis>Make Sure the Recipe is in the Final Layer</emphasis>: | ||
| 2314 | Strictly speaking, this step is not necessary if | ||
| 2315 | you begin this workflow with the recipe in its own | ||
| 2316 | proper layer outside of the <filename>devtool</filename> | ||
| 2317 | workspace. | ||
| 2318 | However, it is included here so that when you do the | ||
| 2319 | final step following this you do not lose the recipe | ||
| 2320 | should it be in the workspace, which is possible | ||
| 2321 | (e.g. starting with <filename>devtool add</filename> to | ||
| 2322 | create a recipe in the workspace).</para> | ||
| 2323 | |||
| 2324 | <para>You should be sure that the recipe is located | ||
| 2325 | outside of the workspace before using the | ||
| 2326 | <filename>devtool reset</filename> command described in | ||
| 2327 | the next step. | ||
| 2328 | </para></listitem> | 2205 | </para></listitem> |
| 2329 | <listitem><para><emphasis>Restore the Workspace</emphasis>: | 2206 | <listitem><para><emphasis>Restore the Workspace</emphasis>: |
| 2330 | The <filename>devtool reset</filename> restores the | 2207 | The <filename>devtool reset</filename> restores the |
| 2331 | state so that standard layers and upstream sources are | 2208 | state so that standard layers and upstream sources are |
| 2332 | used to build the recipe rather than what is in the | 2209 | used to build the recipe rather than what is in the |
| 2333 | workspace. | 2210 | workspace. |
| 2334 | Restoring the workspace removes all traces of the | ||
| 2335 | <replaceable>recipe</replaceable>. | ||
| 2336 | <literallayout class='monospaced'> | 2211 | <literallayout class='monospaced'> |
| 2337 | $ devtool reset <replaceable>recipe</replaceable> | 2212 | $ devtool reset <replaceable>recipe</replaceable> |
| 2338 | </literallayout> | 2213 | </literallayout> |
| 2339 | Once the workspace is restored, you can use it again for | ||
| 2340 | working on different code. | ||
| 2341 | </para></listitem> | 2214 | </para></listitem> |
| 2342 | </orderedlist> | 2215 | </orderedlist> |
| 2343 | </para> | 2216 | </para> |
| @@ -2469,6 +2342,13 @@ | |||
| 2469 | 2342 | ||
| 2470 | <para> | 2343 | <para> |
| 2471 | <literallayout class='monospaced'> | 2344 | <literallayout class='monospaced'> |
| 2345 | attic - A directory created if devtool believes it preserve | ||
| 2346 | anything when you run "devtool reset". For example, if you | ||
| 2347 | run "devtool add", make changes to the recipe, and then | ||
| 2348 | run "devtool reset", devtool takes notice that the file has | ||
| 2349 | been changed and moves it into the attic should you still | ||
| 2350 | want the recipe. | ||
| 2351 | |||
| 2472 | README - Provides information on what is in workspace layer and how to | 2352 | README - Provides information on what is in workspace layer and how to |
| 2473 | manage it. | 2353 | manage it. |
| 2474 | 2354 | ||
| @@ -2485,9 +2365,10 @@ | |||
| 2485 | within that sub-directory. | 2365 | within that sub-directory. |
| 2486 | 2366 | ||
| 2487 | sources - A directory containing a working copy of the source files used | 2367 | sources - A directory containing a working copy of the source files used |
| 2488 | when building the recipe. This directory contains a | 2368 | when building the recipe. This is the default directory used |
| 2489 | folder for each set of source files matched to a corresponding | 2369 | as the location of the source tree when you do not provide a |
| 2490 | recipe. | 2370 | source tree path. This directory contains a folder for each |
| 2371 | set of source files matched to a corresponding recipe. | ||
| 2491 | </literallayout> | 2372 | </literallayout> |
| 2492 | </para> | 2373 | </para> |
| 2493 | </section> | 2374 | </section> |