1 files changed, 149 insertions, 38 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index b8669f8daa..8706bd6888 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1213,40 +1213,154 @@
            </para>
        </section>
-        <section id='new-recipe-locate-a-base-recipe'>
+        <section id='new-recipe-locate-or-automatically-create-a-base-recipe'>
-            <title>Locate a Base Recipe</title>
+            <title>Locate or Automatically Create a Base Recipe</title>
            <para>
-                Before writing a recipe from scratch, it is often useful to
+                You can always write a recipe from scratch.
-                discover whether someone else has already written one that
+                However, two choices exist that can help you quickly get a
-                meets (or comes close to meeting) your needs.
+                start on a new recipe:
-                The Yocto Project and OpenEmbedded communities maintain many
+                <itemizedlist>
-                recipes that might be candidates for what you are doing.
+                    <listitem><para><emphasis><filename>recipetool</filename>:</emphasis>
-                You can find a good central index of these recipes in the
+                        A tool provided by the Yocto Project that automates
-                <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
+                        creation of a base recipe based on the source
+                        files.
+                        </para></listitem>
+                    <listitem><para><emphasis>Existing Recipes:</emphasis>
+                        Location and modification of an existing recipe that is
+                        similar in function to the recipe you need.
+                        </para></listitem>
+                </itemizedlist>
            </para>
-            <para>
+            <section id='new-recipe-creating-the-base-recipe-using-recipetool'>
-                Working from an existing recipe or a skeleton recipe is the
+                <title>Creating the Base Recipe Using <filename>recipetool</filename></title>
-                best way to get started.
-                Here are some points on both methods:
+                <para>
-                <itemizedlist>
+                    <filename>recipetool</filename> automates creation of
-                    <listitem><para><emphasis>Locate and modify a recipe that
+                    a base recipe given a set of source code files.
-                        is close to what you want to do:</emphasis>
+                    As long as you can extract or point to the source files,
-                        This method works when you are familiar with the
+                    the tool will construct a recipe and automatically
-                        current recipe space.
+                    configure all pre-build information into the recipe.
-                        The method does not work so well for those new to
+                    For example, suppose you have an application that builds
-                        the Yocto Project or writing recipes.</para>
+                    using Autotools.
-                        <para>Some risks associated with this method are
+                    Creating the base recipe using
-                        using a recipe that has areas totally unrelated to
+                    <filename>recipetool</filename> results in a recipe
-                        what you are trying to accomplish with your recipe,
+                    that has the pre-build dependencies, license requirements,
-                        not recognizing areas of the recipe that you might
+                    and checksums configured.
-                        have to add from scratch, and so forth.
+                </para>
-                        All these risks stem from unfamiliarity with the
-                        existing recipe space.</para></listitem>
+                <para>
-                    <listitem><para><emphasis>Use and modify the following
+                    To run the tool, you just need to be in your
-                        skeleton recipe:</emphasis>
+                    <link linkend='build-directory'>Build Directory</link>
-                        <literallayout class='monospaced'>
+                    and have sourced the build environment setup script
+                    (i.e.
+                    <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>
+                    or
+                    <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
+                    Here is the basic <filename>recipetool</filename> syntax:
+                    <literallayout class='monospaced'>
+     recipetool -h
+     recipetool create [-h]
+     recipetool [-d] [-q] [--color auto | always | never ] create [-o <replaceable>OUTFILE</replaceable>] [-m] [-x <replaceable>EXTERNALSRC</replaceable>] <replaceable>source</replaceable>
+          -d       Enables debug output.
+          -q       Outputs only errors (quiet mode).
+          --color  Colorizes the output automatically, always, or never.
+          -h       Displays Python generated syntax for recipetool.
+          create   Causes recipetool to create a base recipe.  The create
+                   command is further defined with these options:
+                   -o <replaceable>OUTFILE</replaceable>      Specifies the full path and filename for the generated
+                                   recipe.
+                   -m              Causes the recipe to be machine-specific rather than
+                                   architecture-specific (default).
+                   -x <replaceable>EXTERNALSRC</replaceable>  Fetches and extracts source files from <replaceable>source</replaceable>
+                                   and places them in <replaceable>EXTERNALSRC</replaceable>.
+                                   <replaceable>source</replaceable> must be a URL.
+                   -h              Displays Python-generated syntax for create.
+                   <replaceable>source</replaceable>          Specifies the source code on which to base the
+                                   recipe.
+                    </literallayout>
+                </para>
+                <para>
+                    Running <filename>recipetool</filename> creates the base
+                    recipe and locates it properly in the layer that contains
+                    your source files.
+                    Following are some syntax examples:
+                </para>
+                <para>
+                    Use this syntax to generate a recipe based on <replaceable>source</replaceable>.
+                    Once generated, the recipe resides in the existing source
+                    code layer:
+                    <literallayout class='monospaced'>
+     recipetool create <replaceable>source</replaceable>
+                    </literallayout>
+                    Use this syntax to generate a recipe using code that you
+                    extract from <replaceable>source</replaceable>.
+                    The extracted code is placed in its own layer defined
+                    by <replaceable>EXTERNALSRC</replaceable>.
+                    <literallayout class='monospaced'>
+     recipetool create -x <replaceable>EXTERNALSRC</replaceable> <replaceable>source</replaceable>
+                    </literallayout>
+                    Use this syntax to generate a recipe and override the
+                    tool's default placement of the recipe by specifying both
+                    its location and name using <replaceable>OUTFILE</replaceable>.
+                    <literallayout class='monospaced'>
+     recipetool create -o <replaceable>OUTFILE</replaceable> <replaceable>source</replaceable>
+                    </literallayout>
+                    Use this syntax to generate a recipe based on <replaceable>source</replaceable>.
+                    The options direct <filename>recipetool</filename> to
+                    run in "quiet mode" and to generate debugging information.
+                    Once generated, the recipe resides in the existing source
+                    code layer:
+                    <literallayout class='monospaced'>
+     recipetool create -o <replaceable>OUTFILE</replaceable> <replaceable>source</replaceable>
+                    </literallayout>
+                </para>
+            </section>
+            <section id='new-recipe-locating-and-using-a-similar-recipe'>
+                <title>Locating and Using a Similar Recipe</title>
+                <para>
+                    Before writing a recipe from scratch, it is often useful to
+                    discover whether someone else has already written one that
+                    meets (or comes close to meeting) your needs.
+                    The Yocto Project and OpenEmbedded communities maintain many
+                    recipes that might be candidates for what you are doing.
+                    You can find a good central index of these recipes in the
+                    <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
+                </para>
+                <para>
+                    Working from an existing recipe or a skeleton recipe is the
+                    best way to get started.
+                    Here are some points on both methods:
+                    <itemizedlist>
+                        <listitem><para><emphasis>Locate and modify a recipe that
+                            is close to what you want to do:</emphasis>
+                            This method works when you are familiar with the
+                            current recipe space.
+                            The method does not work so well for those new to
+                            the Yocto Project or writing recipes.</para>
+                            <para>Some risks associated with this method are
+                            using a recipe that has areas totally unrelated to
+                            what you are trying to accomplish with your recipe,
+                            not recognizing areas of the recipe that you might
+                            have to add from scratch, and so forth.
+                            All these risks stem from unfamiliarity with the
+                            existing recipe space.</para></listitem>
+                        <listitem><para><emphasis>Use and modify the following
+                            skeleton recipe:</emphasis>
+                            If for some reason you do not want to use
+                            <filename>recipetool</filename> and you cannot
+                            find an existing recipe that is close to meeting
+                            your needs, you can use the following structure to
+                            provide the fundamental areas of a new recipe.
+                            <literallayout class='monospaced'>
     DESCRIPTION = ""
     HOMEPAGE = ""
     LICENSE = ""
@@ -1255,14 +1369,11 @@
     LIC_FILES_CHKSUM = ""
     SRC_URI = ""
-                        </literallayout>
+                            </literallayout>
-                        Modifying this recipe is the recommended method for
+                            </para></listitem>
-                        creating a new recipe.
+                    </itemizedlist>
-                        The recipe provides the fundamental areas that you need
+                </para>
-                        to include, exclude, or alter to fit your needs.
+            </section>
-                        </para></listitem>
-                </itemizedlist>
-            </para>
        </section>
        <section id='new-recipe-storing-and-naming-the-recipe'>

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index b8669f8daa..8706bd6888 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1213,40 +1213,154 @@
1213	</para>	1213	</para>
1214	</section>	1214	</section>
1215		1215
1216	<section id='new-recipe-locate-a-base-recipe'>	1216	<section id='new-recipe-locate-or-automatically-create-a-base-recipe'>
1217	<title>Locate a Base Recipe</title>	1217	<title>Locate or Automatically Create a Base Recipe</title>
1218		1218
1219	<para>	1219	<para>
1220	Before writing a recipe from scratch, it is often useful to	1220	You can always write a recipe from scratch.
1221	discover whether someone else has already written one that	1221	However, two choices exist that can help you quickly get a
1222	meets (or comes close to meeting) your needs.	1222	start on a new recipe:
1223	The Yocto Project and OpenEmbedded communities maintain many	1223	<itemizedlist>
1224	recipes that might be candidates for what you are doing.	1224	<listitem><para><emphasis><filename>recipetool</filename>:</emphasis>
1225	You can find a good central index of these recipes in the	1225	A tool provided by the Yocto Project that automates
1226	<ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.	1226	creation of a base recipe based on the source
		1227	files.
		1228	</para></listitem>
		1229	<listitem><para><emphasis>Existing Recipes:</emphasis>
		1230	Location and modification of an existing recipe that is
		1231	similar in function to the recipe you need.
		1232	</para></listitem>
		1233	</itemizedlist>
1227	</para>	1234	</para>
1228		1235
1229	<para>	1236	<section id='new-recipe-creating-the-base-recipe-using-recipetool'>
1230	Working from an existing recipe or a skeleton recipe is the	1237	<title>Creating the Base Recipe Using <filename>recipetool</filename></title>
1231	best way to get started.	1238
1232	Here are some points on both methods:	1239	<para>
1233	<itemizedlist>	1240	<filename>recipetool</filename> automates creation of
1234	<listitem><para><emphasis>Locate and modify a recipe that	1241	a base recipe given a set of source code files.
1235	is close to what you want to do:</emphasis>	1242	As long as you can extract or point to the source files,
1236	This method works when you are familiar with the	1243	the tool will construct a recipe and automatically
1237	current recipe space.	1244	configure all pre-build information into the recipe.
1238	The method does not work so well for those new to	1245	For example, suppose you have an application that builds
1239	the Yocto Project or writing recipes.</para>	1246	using Autotools.
1240	<para>Some risks associated with this method are	1247	Creating the base recipe using
1241	using a recipe that has areas totally unrelated to	1248	<filename>recipetool</filename> results in a recipe
1242	what you are trying to accomplish with your recipe,	1249	that has the pre-build dependencies, license requirements,
1243	not recognizing areas of the recipe that you might	1250	and checksums configured.
1244	have to add from scratch, and so forth.	1251	</para>
1245	All these risks stem from unfamiliarity with the	1252
1246	existing recipe space.</para></listitem>	1253	<para>
1247	<listitem><para><emphasis>Use and modify the following	1254	To run the tool, you just need to be in your
1248	skeleton recipe:</emphasis>	1255	<link linkend='build-directory'>Build Directory</link>
1249	<literallayout class='monospaced'>	1256	and have sourced the build environment setup script
		1257	(i.e.
		1258	<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>
		1259	or
		1260	<ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
		1261	Here is the basic <filename>recipetool</filename> syntax:
		1262	<literallayout class='monospaced'>
		1263	recipetool -h
		1264	recipetool create [-h]
		1265	recipetool [-d] [-q] [--color auto \| always \| never ] create [-o <replaceable>OUTFILE</replaceable>] [-m] [-x <replaceable>EXTERNALSRC</replaceable>] <replaceable>source</replaceable>
		1266
		1267	-d Enables debug output.
		1268	-q Outputs only errors (quiet mode).
		1269	--color Colorizes the output automatically, always, or never.
		1270	-h Displays Python generated syntax for recipetool.
		1271	create Causes recipetool to create a base recipe. The create
		1272	command is further defined with these options:
		1273
		1274	-o <replaceable>OUTFILE</replaceable> Specifies the full path and filename for the generated
		1275	recipe.
		1276	-m Causes the recipe to be machine-specific rather than
		1277	architecture-specific (default).
		1278	-x <replaceable>EXTERNALSRC</replaceable> Fetches and extracts source files from <replaceable>source</replaceable>
		1279	and places them in <replaceable>EXTERNALSRC</replaceable>.
		1280	<replaceable>source</replaceable> must be a URL.
		1281	-h Displays Python-generated syntax for create.
		1282	<replaceable>source</replaceable> Specifies the source code on which to base the
		1283	recipe.
		1284	</literallayout>
		1285	</para>
		1286
		1287	<para>
		1288	Running <filename>recipetool</filename> creates the base
		1289	recipe and locates it properly in the layer that contains
		1290	your source files.
		1291	Following are some syntax examples:
		1292	</para>
		1293
		1294	<para>
		1295	Use this syntax to generate a recipe based on <replaceable>source</replaceable>.
		1296	Once generated, the recipe resides in the existing source
		1297	code layer:
		1298	<literallayout class='monospaced'>
		1299	recipetool create <replaceable>source</replaceable>
		1300	</literallayout>
		1301	Use this syntax to generate a recipe using code that you
		1302	extract from <replaceable>source</replaceable>.
		1303	The extracted code is placed in its own layer defined
		1304	by <replaceable>EXTERNALSRC</replaceable>.
		1305	<literallayout class='monospaced'>
		1306	recipetool create -x <replaceable>EXTERNALSRC</replaceable> <replaceable>source</replaceable>
		1307	</literallayout>
		1308	Use this syntax to generate a recipe and override the
		1309	tool's default placement of the recipe by specifying both
		1310	its location and name using <replaceable>OUTFILE</replaceable>.
		1311	<literallayout class='monospaced'>
		1312	recipetool create -o <replaceable>OUTFILE</replaceable> <replaceable>source</replaceable>
		1313	</literallayout>
		1314	Use this syntax to generate a recipe based on <replaceable>source</replaceable>.
		1315	The options direct <filename>recipetool</filename> to
		1316	run in "quiet mode" and to generate debugging information.
		1317	Once generated, the recipe resides in the existing source
		1318	code layer:
		1319	<literallayout class='monospaced'>
		1320	recipetool create -o <replaceable>OUTFILE</replaceable> <replaceable>source</replaceable>
		1321	</literallayout>
		1322	</para>
		1323	</section>
		1324
		1325	<section id='new-recipe-locating-and-using-a-similar-recipe'>
		1326	<title>Locating and Using a Similar Recipe</title>
		1327
		1328	<para>
		1329	Before writing a recipe from scratch, it is often useful to
		1330	discover whether someone else has already written one that
		1331	meets (or comes close to meeting) your needs.
		1332	The Yocto Project and OpenEmbedded communities maintain many
		1333	recipes that might be candidates for what you are doing.
		1334	You can find a good central index of these recipes in the
		1335	<ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
		1336	</para>
		1337
		1338	<para>
		1339	Working from an existing recipe or a skeleton recipe is the
		1340	best way to get started.
		1341	Here are some points on both methods:
		1342	<itemizedlist>
		1343	<listitem><para><emphasis>Locate and modify a recipe that
		1344	is close to what you want to do:</emphasis>
		1345	This method works when you are familiar with the
		1346	current recipe space.
		1347	The method does not work so well for those new to
		1348	the Yocto Project or writing recipes.</para>
		1349	<para>Some risks associated with this method are
		1350	using a recipe that has areas totally unrelated to
		1351	what you are trying to accomplish with your recipe,
		1352	not recognizing areas of the recipe that you might
		1353	have to add from scratch, and so forth.
		1354	All these risks stem from unfamiliarity with the
		1355	existing recipe space.</para></listitem>
		1356	<listitem><para><emphasis>Use and modify the following
		1357	skeleton recipe:</emphasis>
		1358	If for some reason you do not want to use
		1359	<filename>recipetool</filename> and you cannot
		1360	find an existing recipe that is close to meeting
		1361	your needs, you can use the following structure to
		1362	provide the fundamental areas of a new recipe.
		1363	<literallayout class='monospaced'>
1250	DESCRIPTION = ""	1364	DESCRIPTION = ""
1251	HOMEPAGE = ""	1365	HOMEPAGE = ""
1252	LICENSE = ""	1366	LICENSE = ""
@@ -1255,14 +1369,11 @@
1255	LIC_FILES_CHKSUM = ""	1369	LIC_FILES_CHKSUM = ""
1256		1370
1257	SRC_URI = ""	1371	SRC_URI = ""
1258	</literallayout>	1372	</literallayout>
1259	Modifying this recipe is the recommended method for	1373	</para></listitem>
1260	creating a new recipe.	1374	</itemizedlist>
1261	The recipe provides the fundamental areas that you need	1375	</para>
1262	to include, exclude, or alter to fit your needs.	1376	</section>
1263	</para></listitem>
1264	</itemizedlist>
1265	</para>
1266	</section>	1377	</section>
1267		1378
1268	<section id='new-recipe-storing-and-naming-the-recipe'>	1379	<section id='new-recipe-storing-and-naming-the-recipe'>