summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-12-20 09:41:32 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-02 13:16:12 +0000
commit9f51f11ca6599ca820c2c01c8b07a8ee73975318 (patch)
treec6a44a13bd114d8e59a3b3bdcdf99ec697cc622c /documentation
parentfac99a49df61504ddc5d887892d72a0004473987 (diff)
downloadpoky-9f51f11ca6599ca820c2c01c8b07a8ee73975318.tar.gz
dev-manual: Completed the "Fetching" and "Configuration" sections.
This involved a first draft and implementation of Paul's review comments. Also worked on the "Configuration" section. (From yocto-docs rev: 0e168dbaf5f4949c4c5f79fe7da406ca91390e22) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml380
1 files changed, 280 insertions, 100 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index f6184cec32..6d1d08365b 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1183,8 +1183,6 @@
1183 <listitem><para><emphasis>Use and modify the following 1183 <listitem><para><emphasis>Use and modify the following
1184 skeleton recipe:</emphasis> 1184 skeleton recipe:</emphasis>
1185 <literallayout class='monospaced'> 1185 <literallayout class='monospaced'>
1186 inherit &lt;stuff&gt;
1187
1188 SUMMARY = "" 1186 SUMMARY = ""
1189 HOMEPAGE = "" 1187 HOMEPAGE = ""
1190 LICENSE = "" 1188 LICENSE = ""
@@ -1195,7 +1193,9 @@
1195 SRC_URI[md5sum] = "" 1193 SRC_URI[md5sum] = ""
1196 SRC_URI[sha256sum] = "" 1194 SRC_URI[sha256sum] = ""
1197 1195
1198 S = ${WORKDIR}/${PN}-${PV} 1196 S = "${WORKDIR}/${PN}-${PV}"
1197
1198 inherit &lt;stuff&gt;
1199 </literallayout> 1199 </literallayout>
1200 Modifying this recipe is the recommended method for 1200 Modifying this recipe is the recommended method for
1201 creating a new recipe. 1201 creating a new recipe.
@@ -1206,6 +1206,135 @@
1206 </para> 1206 </para>
1207 </section> 1207 </section>
1208 1208
1209 <section id='new-recipe-naming-the-recipe'>
1210 <title>Naming the Recipe</title>
1211
1212 <para>
1213 Once you have your base recipe, you need to name it and be
1214 sure that it resides where the OpenEmbedded build system
1215 can find it.
1216 </para>
1217
1218 <para>
1219 When you name your recipe, you need to follow this naming
1220 convention:
1221 <literallayout class='monospaced'>
1222 &lt;basename&gt;_&lt;version&gt;.bb
1223 </literallayout>
1224 Use lower-cased characters and do not include the reserved
1225 suffixes <filename>-native</filename>,
1226 <filename>-cross</filename>, <filename>-initial</filename>,
1227 or <filename>-dev</filename>.
1228 Here are some examples:
1229 <literallayout class='monospaced'>
1230 cups_1.7.0.bb
1231 gawk_4.0.2.bb
1232 xdg-utils_1.1.0-rc1.bb
1233 </literallayout>
1234 </para>
1235
1236 <para>
1237 The OpenEmbedded build system locates your recipe through
1238 the <filename>layer.conf</filename> file and the
1239 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>
1240 variable.
1241 This variable sets up a path from which the build system can
1242 locate recipes.
1243 Here is the typical use:
1244 <literallayout class='monospaced'>
1245 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1246 ${LAYERDIR}/recipes-*/*/*.bbappend"
1247 </literallayout>
1248 Consequently, you need to be sure you locate your new recipe
1249 inside your layer such that it can be found.
1250 </para>
1251
1252 <para>
1253 You can find more information on how layers are structured
1254 in the
1255 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
1256 section.
1257 </para>
1258 </section>
1259
1260 <section id='new-recipe-running-a-build-on-the-recipe'>
1261 <title>Running a Build on the Recipe</title>
1262
1263 <para>
1264 Creating a new recipe is an iterative process that requires
1265 using BitBake to process the recipe multiple times in order to
1266 progressively discover and add information to the recipe.
1267 </para>
1268
1269 <para>
1270 To process the recipe, use the following BitBake command form
1271 from within the
1272 <link linkend='build-directory'>Build Directory</link>:
1273 <literallayout class='monospaced'>
1274 $ bitbake &lt;base-recipe-name&gt;
1275 </literallayout>
1276 Before you run BitBake, be sure that you source a build
1277 environment setup script (i.e.
1278 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1279 or
1280 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>.
1281 </para>
1282
1283 <para>
1284 The OpenEmbedded build system creates a temporary work
1285 directory
1286 (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>)
1287 where it keeps extracted source files, log files, images, and
1288 so forth.
1289 </para>
1290
1291 <para>
1292 This temporary work directory is constructed depending on
1293 several factors.
1294 For packages that are not dependent on a particular machine,
1295 <filename>WORKDIR</filename> is defined as follows:
1296 <literallayout class='monospaced'>
1297 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
1298 </literallayout>
1299 As an example, assume a Source Directory top-level folder name
1300 <filename>poky</filename>, a default Build Directory at
1301 <filename>poky/build</filename>, a <filename>qemux86</filename>
1302 package architecture, and a <filename>linux</filename> target
1303 operating system.
1304 Furthermore, suppose your recipe is named
1305 <filename>foo_1.3.0-r0.bb</filename>.
1306 In this case, the work directory the build system uses to
1307 build the package would be as follows:
1308 <literallayout class='monospaced'>
1309 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1310 </literallayout>
1311 Inside this directory you can find sub-directories such as
1312 <filename>image</filename>, <filename>package-split</filename>,
1313 and <filename>temp</filename>.
1314 After the build, you can examine these to determine how well
1315 the build went.
1316 </para>
1317
1318 <para>
1319 You can find more information about the build process in the
1320 "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>"
1321 chapter of the Yocto Project Reference Manual.
1322 </para>
1323
1324 <para>
1325 You can also reference the following variables in the
1326 Yocto Project Reference Manual's glossary for more information:
1327 <itemizedlist>
1328 <listitem>The temporary directory - <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink></listitem>
1329 <listitem>The package architecture - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink></listitem>
1330 <listitem>The target operating system - <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink></listitem>
1331 <listitem>The recipe name - <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink></listitem>
1332 <listitem>The recipe version - <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink></listitem>
1333 <listitem>The recipe revision - <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink></listitem>
1334 </itemizedlist>
1335 </para>
1336 </section>
1337
1209 <section id='new-recipe-fetching-code'> 1338 <section id='new-recipe-fetching-code'>
1210 <title>Fetching Code</title> 1339 <title>Fetching Code</title>
1211 1340
@@ -1268,7 +1397,7 @@
1268 you provide the <filename>SRC_URI</filename> variable in your 1397 you provide the <filename>SRC_URI</filename> variable in your
1269 recipe: 1398 recipe:
1270 <itemizedlist> 1399 <itemizedlist>
1271 <listitem><para> 1400 <listitem><para><emphasis>Avoid hard-coding URLs:</emphasis>
1272 Rather than hard-coding the version in an URL, it is 1401 Rather than hard-coding the version in an URL, it is
1273 good practice to use 1402 good practice to use
1274 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>, 1403 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
@@ -1279,7 +1408,7 @@
1279 as renaming the recipe to match the new version. 1408 as renaming the recipe to match the new version.
1280 Notice that the two examples in the previous paragraph 1409 Notice that the two examples in the previous paragraph
1281 both use <filename>${PV}</filename>.</para></listitem> 1410 both use <filename>${PV}</filename>.</para></listitem>
1282 <listitem><para> 1411 <listitem><para><emphasis>Using the <filename>file://</filename> URI protocol:</emphasis>
1283 When you specify local files using the 1412 When you specify local files using the
1284 <filename>file://</filename> URI protocol, the build 1413 <filename>file://</filename> URI protocol, the build
1285 system fetches files from the local machine. 1414 system fetches files from the local machine.
@@ -1297,26 +1426,15 @@
1297 For more information, see the 1426 For more information, see the
1298 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 1427 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1299 variable.</para></listitem> 1428 variable.</para></listitem>
1300 <listitem><para> 1429 <listitem><para><emphasis>Specifying patch files:</emphasis>
1301 Files mentioned in <filename>SRC_URI</filename> whose
1302 names end in a typical archive extension
1303 (e.g. <filename>.tar</filename>,
1304 <filename>.tar.gz</filename>,
1305 <filename>.tar.bz2</filename>,
1306 <filename>.zip</filename>, and so forth),
1307 are automatically extracted during
1308 the <filename>do_unpack</filename> task.
1309 </para></listitem>
1310 <listitem><para>
1311 Files mentioned in <filename>SRC_URI</filename> whose 1430 Files mentioned in <filename>SRC_URI</filename> whose
1312 names end in <filename>.patch</filename> or 1431 names end in <filename>.patch</filename> or
1313 <filename>.diff</filename> are treated as patches and 1432 <filename>.diff</filename> are treated as patches and
1314 are automatically applied during the 1433 are automatically applied during the
1315 <filename>do_patch</filename> task.</para></listitem> 1434 <filename>do_patch</filename> task.</para>
1316 <listitem><para> 1435 <para>The build system should be able to apply patches
1317 Patches should be applicable with the "-p1" option to 1436 with the "-p1" option (i.e. one directory level in the
1318 patch (i.e. one directory level in the path will be 1437 path will be stripped off).
1319 stripped off.)
1320 If your patch needs to have more directory levels 1438 If your patch needs to have more directory levels
1321 stripped off, specify the number of levels using the 1439 stripped off, specify the number of levels using the
1322 "striplevel" option in the <filename>SRC_URI</filename> 1440 "striplevel" option in the <filename>SRC_URI</filename>
@@ -1325,7 +1443,17 @@
1325 specific subdirectory that is not specified in the patch 1443 specific subdirectory that is not specified in the patch
1326 file, use the "patchdir" option in the entry. 1444 file, use the "patchdir" option in the entry.
1327 </para></listitem> 1445 </para></listitem>
1328 <listitem><para> 1446 <listitem><para><emphasis>Extracting archived source files:</emphasis>
1447 Files mentioned in <filename>SRC_URI</filename> whose
1448 names end in a typical archive extension
1449 (e.g. <filename>.tar</filename>,
1450 <filename>.tar.gz</filename>,
1451 <filename>.tar.bz2</filename>,
1452 <filename>.zip</filename>, and so forth),
1453 are automatically extracted during
1454 the <filename>do_unpack</filename> task.
1455 </para></listitem>
1456 <listitem><para><emphasis>Specifying source from an SCM:</emphasis>
1329 For Git repositories, you must specify 1457 For Git repositories, you must specify
1330 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> 1458 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1331 and you should specify 1459 and you should specify
@@ -1347,14 +1475,36 @@
1347 </para> 1475 </para>
1348 1476
1349 <para> 1477 <para>
1350 Also part of the <filename>SRC_URI</filename> variable are the 1478 If your <filename>SRC_URI</filename> statement includes
1479 URLs pointing to individual files fetched from a remote server
1480 other than a version control system, BitBake attempts to
1481 verify the files against checksums defined in your recipe to
1482 ensure they have not been tampered with or otherwise modified
1483 since the recipe was written.
1484 Two checksums are used:
1351 <filename>SRC_URI[md5sum] = ""</filename> and 1485 <filename>SRC_URI[md5sum] = ""</filename> and
1352 <filename>SRC_URI[sha256sum] = ""</filename> statements. 1486 <filename>SRC_URI[sha256sum] = ""</filename>.
1353 These two checksums ensure that the remote file (and hence 1487 </para>
1354 the source code you are building) has not changed since the 1488
1355 recipe was written. 1489 <para>
1356 You must provide these two checksums whenever you fetch 1490 If your <filename>SRC_URI</filename> variable points to
1357 source from anywhere other than an SCM or a local file. 1491 more than a single URL (excluding SCM URLs), you need to
1492 provide the <filename>md5</filename> and
1493 <filename>sha256</filename> checksums for each URL.
1494 For these cases, you provide a name for each URL as part of
1495 the <filename>SRC_URI</filename> and then reference that name
1496 in the subsequent checksum statements.
1497 Here is an example:
1498 <literallayout class='monospaced'>
1499 SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \
1500 ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch
1501
1502 SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8"
1503 SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d"
1504
1505 SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92"
1506 SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430"
1507 </literallayout>
1358 </para> 1508 </para>
1359 1509
1360 <para> 1510 <para>
@@ -1371,13 +1521,14 @@
1371 <section id='new-recipe-unpacking-code'> 1521 <section id='new-recipe-unpacking-code'>
1372 <title>Unpacking Code</title> 1522 <title>Unpacking Code</title>
1373 1523
1524do_unpack unpacks the source, and S must be set
1525> to point to where it will be unpacked
1526
1374 <para> 1527 <para>
1375 During the build, source code that is fetched needs to be 1528 During the build, the <filename>do_unpack</filename> task
1376 unpacked. 1529 unpacks the source and
1377 The OpenEmbedded build system uses the 1530 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>
1378 <filename>do_unpack</filename> task to organize the source 1531 points to where it will be unpacked.
1379 files into the temporary work directory pointed to by
1380 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>.
1381 </para> 1532 </para>
1382 1533
1383 <para> 1534 <para>
@@ -1388,6 +1539,13 @@
1388 source from an SCM like Git or Subversion, your recipe needs 1539 source from an SCM like Git or Subversion, your recipe needs
1389 to define <filename>S</filename>. 1540 to define <filename>S</filename>.
1390 </para> 1541 </para>
1542
1543 <para>
1544 If processing your recipe using BitBake successfully unpacks
1545 the source files, you need to be sure that the structure
1546 created in <filename>${S}</filename> matches the structure
1547 from the source.
1548 </para>
1391 </section> 1549 </section>
1392 1550
1393 <section id='new-recipe-licensing'> 1551 <section id='new-recipe-licensing'>
@@ -1401,10 +1559,11 @@
1401 variables: 1559 variables:
1402 <itemizedlist> 1560 <itemizedlist>
1403 <listitem><para><emphasis><filename>LICENSE</filename>:</emphasis> 1561 <listitem><para><emphasis><filename>LICENSE</filename>:</emphasis>
1562 This variable specifies the license for the software.
1404 If you do not know the license under which the software 1563 If you do not know the license under which the software
1405 you are building is distributed, you can go to the 1564 you are building is distributed, you can go to the
1406 source code and look for that information. 1565 source code and look for that information.
1407 Places that hold this information are the 1566 Typical files containing this information include
1408 <filename>COPYING</filename>, 1567 <filename>COPYING</filename>,
1409 <filename>LICENSE</filename>, and 1568 <filename>LICENSE</filename>, and
1410 <filename>README</filename> files. 1569 <filename>README</filename> files.
@@ -1412,17 +1571,20 @@
1412 a source file. 1571 a source file.
1413 The key is to find something that states the public 1572 The key is to find something that states the public
1414 license needed for the software. 1573 license needed for the software.
1415 For example, the 1574 For example, given a piece of software licensed under
1416 <ulink url='http://sourceforge.net/p/htop/code/HEAD/tree/trunk/COPYING'><filename>COPYING</filename></ulink> 1575 the GNU General Public License version 2, you would
1417 file for the <filename>htop</filename> software states 1576 set <filename>LICENSE</filename> as follows:
1418 clearly that the software is licensed under the
1419 "GNU GENERAL PUBLIC LICENSE Version 2, June 1991".
1420 Consequently, if you were writing a recipe to build
1421 <filename>htop</filename>, you would include the
1422 following:
1423 <literallayout class='monospaced'> 1577 <literallayout class='monospaced'>
1424 LICENSE = "GPLv2" 1578 LICENSE = "GPLv2"
1425 </literallayout></para></listitem> 1579 </literallayout></para>
1580 <para>The licenses you specify with
1581 <filename>LICENSE</filename> be any name as long as
1582 you do not use spaces.
1583 For standard licenses, use the names of the files in
1584 <filename>meta/files/common-licenses/</filename>
1585 or the <filename>SPDXLICENSEMAP</filename> flag names
1586 defined in <filename>meta/conf/licenses.conf</filename>.
1587 </para></listitem>
1426 <listitem><para><emphasis><filename>LIC_FILES_CHKSUM</filename>:</emphasis> 1588 <listitem><para><emphasis><filename>LIC_FILES_CHKSUM</filename>:</emphasis>
1427 The OpenEmbedded build system uses this variable to 1589 The OpenEmbedded build system uses this variable to
1428 make sure the license text has not changed. 1590 make sure the license text has not changed.
@@ -1435,7 +1597,7 @@
1435 will compare the checksums of the files to be sure 1597 will compare the checksums of the files to be sure
1436 the text has not changed. 1598 the text has not changed.
1437 Any differences result in an error with the message 1599 Any differences result in an error with the message
1438 containing the proper checksum. 1600 containing the current checksum.
1439 For more explanation and examples of how to set the 1601 For more explanation and examples of how to set the
1440 <filename>LIC_FILES_CHKSUM</filename> variable, see the 1602 <filename>LIC_FILES_CHKSUM</filename> variable, see the
1441 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" 1603 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
@@ -1511,76 +1673,94 @@
1511 <title>Configuring the Recipe</title> 1673 <title>Configuring the Recipe</title>
1512 1674
1513 <para> 1675 <para>
1514 Configurations for your recipe might include passing in 1676 Most software provides some means of setting build-time
1515 configuration options in the case of an Autotools or CMake 1677 configuration options before compilation.
1516 enabled software or tweaking with the 1678 Typically, setting these options is accomplished by running a
1517 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> 1679 configure script with some options, or by modifying a build
1518 situation. 1680 configuration file.
1519 Regardless, you need to consider this part of the recipe.
1520 </para> 1681 </para>
1521 1682
1522 <para> 1683 <para>
1523 If the software you are building uses Autotools or CMake to 1684 When considering configuration, you should realize that
1524 get built, you do not have to create a 1685 required build-time or runtime dependencies might or might not
1525 <filename>do_configure</filename> task in your recipe. 1686 be noted in the software's documentation.
1526 You might still want to make some adjustments however.
1527 For example, you can set
1528 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1529 to pass any needed configure options that are specific to the
1530 recipe.
1531 </para> 1687 </para>
1532 1688
1533 <para> 1689 <para>
1534 If the source files have a <filename>configure.ac</filename> 1690 The following list provides configuration items of note based
1535 or <filename>CMakeLists.txt</filename> file, then your software 1691 on how your software is built:
1536 is built using Autotools or CMake, respectively. 1692 <itemizedlist>
1537 For either of these cases, you just need to worry about 1693 <listitem><para><emphasis>Autotools:</emphasis>
1538 tweaking the configuration. 1694 If your source files have a
1539 However, if you don't have these files then your software is 1695 <filename>configure.ac</filename> file, then your
1540 being built by some other system and you need to provide a 1696 software is built using Autotools.
1541 <filename>do_configure</filename> task in your recipe. 1697 If this is the case, you just need to worry about
1698 tweaking the configuration.</para>
1699 <para>When using Autotools, your recipe needs to inherit
1700 the
1701 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
1702 class and your recipe does not have to contain a
1703 <filename>do_configure</filename> task.
1704 However, you might still want to make some adjustments.
1705 For example, you can set
1706 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1707 to pass any needed configure options that are specific
1708 to the recipe.</para></listitem>
1709 <listitem><para><emphasis>CMake:</emphasis>
1710 If your source files have a
1711 <filename>CMakeLists.txt</filename> file, then your
1712 software is built using CMake.
1713 If this is the case, you just need to worry about
1714 tweaking the configuration.</para>
1715 <para>When you use CMake, your recipe needs to inherit
1716 the
1717 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
1718 class and your recipe does not have to contain a
1719 <filename>do_configure</filename> task.
1720 You can make some adjustments by setting
1721 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
1722 to pass any needed configure options that are specific
1723 to the recipe.</para></listitem>
1724 <listitem><para><emphasis>Other:</emphasis>
1725 If your source files do not have a
1726 <filename>configure.ac</filename> or
1727 <filename>CMakeLists.txt</filename> file, then your
1728 software is built using some method other than Autotools
1729 or CMake.
1730 If this is the case, you need to provide a
1731 <filename>do_configure</filename> task in your recipe.
1732 </para>
1733 <para>Even if your software is not being built by
1734 Autotools or CMake, you still might not need to deal
1735 with any configuration issues.
1736 You need to determine if configuration is even a required step.
1737 You might need to modify a Makefile or some configuration file
1738 used for the build to specify necessary build options.
1739 Or, perhaps you might need to run a hand-written configuration
1740 script as opposed to something that
1741 <filename>autoconf</filename> would run.</para>
1742 <para>For the case involving a hand-written
1743 configuration script, you would run
1744 <filename>./configure --help</filename> and look for
1745 the options you need to set.</para></listitem>
1746 </itemizedlist>
1542 </para> 1747 </para>
1543 1748
1544 <para> 1749 <para>
1545 Even if you are using Autotools or CMake and configuration 1750 Once configuration succeeds, it is always good practice to
1546 succeeds during the build, it is always good practice to look 1751 look at the <filename>log.do_configure</filename> file to
1547 at the <filename>log.do_configure</filename> file to ensure 1752 ensure that nothing needs to be added to
1548 that nothing needs to be added to
1549 <filename>DEPENDS</filename>. 1753 <filename>DEPENDS</filename>.
1550 For example, if the configure script reports that it found 1754 For example, if the configure script reports that it found
1551 something not mentioned in <filename>DEPENDS</filename>, or that 1755 something not mentioned in <filename>DEPENDS</filename>, or
1552 it did not find something that it needed for some desired 1756 that it did not find something that it needed for some
1553 optional functionality, then you would need to add 1757 desired optional functionality, then you would need to add
1554 those to <filename>DEPENDS</filename>. 1758 those to <filename>DEPENDS</filename>.
1555 Looking at the log might also reveal items being checked for 1759 Looking at the log might also reveal items being checked for
1556 and/or enabled that you do not want, or items not being found 1760 and/or enabled that you do not want, or items not being found
1557 that are in <filename>DEPENDS</filename>, in which case 1761 that are in <filename>DEPENDS</filename>, in which case
1558 you would need to look at passing extra options to the 1762 you would need to look at passing extra options to the
1559 configure script as needed using 1763 configure script as needed.
1560 <filename>EXTRA_OECONF</filename>.
1561 </para>
1562
1563 <para>
1564 You should also realize that required build-time or runtime
1565 dependencies might or might not be noted in the software's
1566 documentation.
1567 </para>
1568
1569 <para>
1570 Even if your software is not being built by Autotools or CMake,
1571 you still might not need to deal with any configuration issues.
1572 You to determine if configuration is even a required step.
1573 You might need to modify a Makefile or some configuration file
1574 used for the build to specify necessary build options.
1575 Or, perhaps you might need to run a hand-written configuration
1576 script as opposed to something that
1577 <filename>autoconf</filename> would run.
1578 </para>
1579
1580 <para>
1581 For the case involving a hand-written configuration script, you
1582 would run <filename>./configure --help</filename> and look for
1583 the options you need to set.
1584 </para> 1764 </para>
1585 </section> 1765 </section>
1586 1766