diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2023-02-14 19:04:37 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2023-02-24 15:43:25 +0000 |
commit | 1e14e7cc7999e924d7fb6d32844a95579534251e (patch) | |
tree | edec5e6eafa3192f812f864ce02d9b4ee2d41e81 /documentation/dev-manual | |
parent | 0fca5a5a2070d32cd70ec2efd5912e0ef37a2714 (diff) | |
download | poky-1e14e7cc7999e924d7fb6d32844a95579534251e.tar.gz |
dev-manual: new-recipe.rst: restructure examples
To make it possible to add more examples (CMake, Meson, Go, Rust...)
- Change section title names
- Adjust paragraph line length
- Have the Autotools example after the one with a custom Makefile,
corresponding to an increasing level of complexity.
- Clarify that GNU make and the Autotools are used to build
the applications, not by these applications.
(From yocto-docs rev: 6f313e673fe4d2878c8166619c27c4958af73615)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reviewed-by: Quentin Schulz <foss+yocto@0leil.net>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r-- | documentation/dev-manual/new-recipe.rst | 110 |
1 files changed, 52 insertions, 58 deletions
diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst index 4751f64b7e..143c8b9c3b 100644 --- a/documentation/dev-manual/new-recipe.rst +++ b/documentation/dev-manual/new-recipe.rst | |||
@@ -288,7 +288,7 @@ extension (e.g. ``.tar``, ``.tar.gz``, ``.tar.bz2``, ``.zip``, and so | |||
288 | forth), are automatically extracted during the | 288 | forth), are automatically extracted during the |
289 | :ref:`ref-tasks-unpack` task. For | 289 | :ref:`ref-tasks-unpack` task. For |
290 | another example that specifies these types of files, see the | 290 | another example that specifies these types of files, see the |
291 | ":ref:`dev-manual/new-recipe:autotooled package`" section. | 291 | ":ref:`dev-manual/new-recipe:building an autotooled package`" section. |
292 | 292 | ||
293 | Another way of specifying source is from an SCM. For Git repositories, | 293 | Another way of specifying source is from an SCM. For Git repositories, |
294 | you must specify :term:`SRCREV` and you should specify :term:`PV` to include | 294 | you must specify :term:`SRCREV` and you should specify :term:`PV` to include |
@@ -361,7 +361,7 @@ and searches specific directories in a certain order: | |||
361 | ``files``. The directories are assumed to be subdirectories of the | 361 | ``files``. The directories are assumed to be subdirectories of the |
362 | directory in which the recipe or append file resides. For another | 362 | directory in which the recipe or append file resides. For another |
363 | example that specifies these types of files, see the | 363 | example that specifies these types of files, see the |
364 | ":ref:`dev-manual/new-recipe:single .c file package (hello world!)`" section. | 364 | ":ref:`dev-manual/new-recipe:building a single .c file package (hello world!)`" section. |
365 | 365 | ||
366 | The previous example also specifies a patch file. Patch files are files | 366 | The previous example also specifies a patch file. Patch files are files |
367 | whose names usually end in ``.patch`` or ``.diff`` but can end with | 367 | whose names usually end in ``.patch`` or ``.diff`` but can end with |
@@ -776,7 +776,7 @@ the software being built: | |||
776 | ``PREFIX=${D}``, ``INSTALLROOT=${D}``, and so forth). | 776 | ``PREFIX=${D}``, ``INSTALLROOT=${D}``, and so forth). |
777 | 777 | ||
778 | For an example recipe using ``make install``, see the | 778 | For an example recipe using ``make install``, see the |
779 | ":ref:`dev-manual/new-recipe:makefile-based package`" section. | 779 | ":ref:`dev-manual/new-recipe:building a makefile-based package`" section. |
780 | 780 | ||
781 | - *Manual:* You need to define a :ref:`ref-tasks-install` function in your | 781 | - *Manual:* You need to define a :ref:`ref-tasks-install` function in your |
782 | recipe. The function must first use ``install -d`` to create the | 782 | recipe. The function must first use ``install -d`` to create the |
@@ -1165,28 +1165,27 @@ Examples | |||
1165 | ======== | 1165 | ======== |
1166 | 1166 | ||
1167 | To help summarize how to write a recipe, this section provides some | 1167 | To help summarize how to write a recipe, this section provides some |
1168 | examples given various scenarios: | 1168 | recipe examples given various scenarios: |
1169 | 1169 | ||
1170 | - Recipes that use local files | 1170 | - Building packages from a single local file |
1171 | 1171 | ||
1172 | - Using an Autotooled package | 1172 | - Building a Makefile-based package |
1173 | 1173 | ||
1174 | - Using a Makefile-based package | 1174 | - Building an Autotooled package |
1175 | 1175 | ||
1176 | - Splitting an application into multiple packages | 1176 | - Splitting an application into multiple packages |
1177 | 1177 | ||
1178 | - Adding binaries to an image | 1178 | - Adding binaries to an image |
1179 | 1179 | ||
1180 | Single .c File Package (Hello World!) | 1180 | Building a Single .c File Package (Hello World!) |
1181 | ------------------------------------- | 1181 | ------------------------------------------------ |
1182 | 1182 | ||
1183 | Building an application from a single file that is stored locally (e.g. | 1183 | Building an application from a single file that is stored locally (e.g. under |
1184 | under ``files``) requires a recipe that has the file listed in the | 1184 | ``files``) requires a recipe that has the file listed in the :term:`SRC_URI` |
1185 | :term:`SRC_URI` variable. Additionally, you need to manually write the | 1185 | variable. Additionally, you need to manually write the :ref:`ref-tasks-compile` |
1186 | :ref:`ref-tasks-compile` and :ref:`ref-tasks-install` tasks. The :term:`S` variable defines the | 1186 | and :ref:`ref-tasks-install` tasks. The :term:`S` variable defines the |
1187 | directory containing the source code, which is set to | 1187 | directory containing the source code, which is set to :term:`WORKDIR` in this |
1188 | :term:`WORKDIR` in this case --- the | 1188 | case --- the directory BitBake uses for the build:: |
1189 | directory BitBake uses for the build:: | ||
1190 | 1189 | ||
1191 | SUMMARY = "Simple helloworld application" | 1190 | SUMMARY = "Simple helloworld application" |
1192 | SECTION = "examples" | 1191 | SECTION = "examples" |
@@ -1206,52 +1205,22 @@ directory BitBake uses for the build:: | |||
1206 | install -m 0755 helloworld ${D}${bindir} | 1205 | install -m 0755 helloworld ${D}${bindir} |
1207 | } | 1206 | } |
1208 | 1207 | ||
1209 | By default, the ``helloworld``, ``helloworld-dbg``, and | 1208 | By default, the ``helloworld``, ``helloworld-dbg``, and ``helloworld-dev`` packages |
1210 | ``helloworld-dev`` packages are built. For information on how to | 1209 | are built. For information on how to customize the packaging process, see the |
1211 | customize the packaging process, see the | ||
1212 | ":ref:`dev-manual/new-recipe:splitting an application into multiple packages`" | 1210 | ":ref:`dev-manual/new-recipe:splitting an application into multiple packages`" |
1213 | section. | 1211 | section. |
1214 | 1212 | ||
1215 | Autotooled Package | 1213 | Building a Makefile-Based Package |
1216 | ------------------ | 1214 | --------------------------------- |
1217 | 1215 | ||
1218 | Applications that use Autotools such as ``autoconf`` and ``automake`` | 1216 | Applications built with GNU ``make`` require a recipe that has the source archive |
1219 | require a recipe that has a source archive listed in :term:`SRC_URI` and | 1217 | listed in :term:`SRC_URI`. You do not need to add a :ref:`ref-tasks-compile` |
1220 | also inherit the :ref:`ref-classes-autotools` class, | 1218 | step since by default BitBake starts the ``make`` command to compile the |
1221 | which contains the definitions of all the steps needed to build an | 1219 | application. If you need additional ``make`` options, you should store them in |
1222 | Autotool-based application. The result of the build is automatically | 1220 | the :term:`EXTRA_OEMAKE` or :term:`PACKAGECONFIG_CONFARGS` variables. BitBake |
1223 | packaged. And, if the application uses NLS for localization, packages | 1221 | passes these options into the GNU ``make`` invocation. Note that a |
1224 | with local information are generated (one package per language). | 1222 | :ref:`ref-tasks-install` task is still required. Otherwise, BitBake runs an |
1225 | Following is one example: (``hello_2.3.bb``):: | 1223 | empty :ref:`ref-tasks-install` task by default. |
1226 | |||
1227 | SUMMARY = "GNU Helloworld application" | ||
1228 | SECTION = "examples" | ||
1229 | LICENSE = "GPL-2.0-or-later" | ||
1230 | LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" | ||
1231 | |||
1232 | SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" | ||
1233 | |||
1234 | inherit autotools gettext | ||
1235 | |||
1236 | The variable :term:`LIC_FILES_CHKSUM` is used to track source license | ||
1237 | changes as described in the | ||
1238 | ":ref:`dev-manual/licenses:tracking license changes`" section in | ||
1239 | the Yocto Project Overview and Concepts Manual. You can quickly create | ||
1240 | Autotool-based recipes in a manner similar to the previous example. | ||
1241 | |||
1242 | Makefile-Based Package | ||
1243 | ---------------------- | ||
1244 | |||
1245 | Applications that use GNU ``make`` also require a recipe that has the | ||
1246 | source archive listed in :term:`SRC_URI`. You do not need to add a | ||
1247 | :ref:`ref-tasks-compile` step since by default BitBake starts the ``make`` command | ||
1248 | to compile the application. If you need additional ``make`` options, you | ||
1249 | should store them in the | ||
1250 | :term:`EXTRA_OEMAKE` or | ||
1251 | :term:`PACKAGECONFIG_CONFARGS` | ||
1252 | variables. BitBake passes these options into the GNU ``make`` | ||
1253 | invocation. Note that a :ref:`ref-tasks-install` task is still required. | ||
1254 | Otherwise, BitBake runs an empty :ref:`ref-tasks-install` task by default. | ||
1255 | 1224 | ||
1256 | Some applications might require extra parameters to be passed to the | 1225 | Some applications might require extra parameters to be passed to the |
1257 | compiler. For example, the application might need an additional header | 1226 | compiler. For example, the application might need an additional header |
@@ -1294,6 +1263,31 @@ In the following example, ``lz4`` is a makefile-based package:: | |||
1294 | 1263 | ||
1295 | BBCLASSEXTEND = "native nativesdk" | 1264 | BBCLASSEXTEND = "native nativesdk" |
1296 | 1265 | ||
1266 | Building an Autotooled Package | ||
1267 | ------------------------------ | ||
1268 | |||
1269 | Applications built with the Autotools such as ``autoconf`` and ``automake`` | ||
1270 | require a recipe that has a source archive listed in :term:`SRC_URI` and also | ||
1271 | inherit the :ref:`ref-classes-autotools` class, which contains the definitions | ||
1272 | of all the steps needed to build an Autotool-based application. The result of | ||
1273 | the build is automatically packaged. And, if the application uses NLS for | ||
1274 | localization, packages with local information are generated (one package per | ||
1275 | language). Following is one example: (``hello_2.3.bb``):: | ||
1276 | |||
1277 | SUMMARY = "GNU Helloworld application" | ||
1278 | SECTION = "examples" | ||
1279 | LICENSE = "GPL-2.0-or-later" | ||
1280 | LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" | ||
1281 | |||
1282 | SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" | ||
1283 | |||
1284 | inherit autotools gettext | ||
1285 | |||
1286 | The variable :term:`LIC_FILES_CHKSUM` is used to track source license changes | ||
1287 | as described in the ":ref:`dev-manual/licenses:tracking license changes`" | ||
1288 | section in the Yocto Project Overview and Concepts Manual. You can quickly | ||
1289 | create Autotool-based recipes in a manner similar to the previous example. | ||
1290 | |||
1297 | Splitting an Application into Multiple Packages | 1291 | Splitting an Application into Multiple Packages |
1298 | ----------------------------------------------- | 1292 | ----------------------------------------------- |
1299 | 1293 | ||