summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml187
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 @@
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'>