[PATCH] dev-manual: new-recipe.rst: restructure examples

[PATCH] dev-manual: new-recipe.rst: restructure examples

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

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.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/new-recipe.rst | 110 +++++++++++-------------
 1 file 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
 forth), are automatically extracted during the
 :ref:`ref-tasks-unpack` task. For
 another example that specifies these types of files, see the
-":ref:`dev-manual/new-recipe:autotooled package`" section.
+":ref:`dev-manual/new-recipe:building an autotooled package`" section.
 
 Another way of specifying source is from an SCM. For Git repositories,
 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:
 ``files``. The directories are assumed to be subdirectories of the
 directory in which the recipe or append file resides. For another
 example that specifies these types of files, see the
-":ref:`dev-manual/new-recipe:single .c file package (hello world!)`" section.
+":ref:`dev-manual/new-recipe:building a single .c file package (hello world!)`" section.
 
 The previous example also specifies a patch file. Patch files are files
 whose names usually end in ``.patch`` or ``.diff`` but can end with
@@ -776,7 +776,7 @@ the software being built:
    ``PREFIX=${D}``, ``INSTALLROOT=${D}``, and so forth).
 
    For an example recipe using ``make install``, see the
-   ":ref:`dev-manual/new-recipe:makefile-based package`" section.
+   ":ref:`dev-manual/new-recipe:building a makefile-based package`" section.
 
 -  *Manual:* You need to define a :ref:`ref-tasks-install` function in your
    recipe. The function must first use ``install -d`` to create the
@@ -1165,28 +1165,27 @@ Examples
 ========
 
 To help summarize how to write a recipe, this section provides some
-examples given various scenarios:
+recipe examples given various scenarios:
 
--  Recipes that use local files
+-  Building packages from a single local file
 
--  Using an Autotooled package
+-  Building a Makefile-based package
 
--  Using a Makefile-based package
+-  Building an Autotooled package
 
 -  Splitting an application into multiple packages
 
 -  Adding binaries to an image
 
-Single .c File Package (Hello World!)
--------------------------------------
+Building a Single .c File Package (Hello World!)
+------------------------------------------------
 
-Building an application from a single file that is stored locally (e.g.
-under ``files``) requires a recipe that has the file listed in the
-:term:`SRC_URI` variable. Additionally, you need to manually write the
-:ref:`ref-tasks-compile` and :ref:`ref-tasks-install` tasks. The :term:`S` variable defines the
-directory containing the source code, which is set to
-:term:`WORKDIR` in this case --- the
-directory BitBake uses for the build::
+Building an application from a single file that is stored locally (e.g. under
+``files``) requires a recipe that has the file listed in the :term:`SRC_URI`
+variable. Additionally, you need to manually write the :ref:`ref-tasks-compile`
+and :ref:`ref-tasks-install` tasks. The :term:`S` variable defines the
+directory containing the source code, which is set to :term:`WORKDIR` in this
+case --- the directory BitBake uses for the build::
 
    SUMMARY = "Simple helloworld application"
    SECTION = "examples"
@@ -1206,52 +1205,22 @@ directory BitBake uses for the build::
        install -m 0755 helloworld ${D}${bindir}
    }
 
-By default, the ``helloworld``, ``helloworld-dbg``, and
-``helloworld-dev`` packages are built. For information on how to
-customize the packaging process, see the
+By default, the ``helloworld``, ``helloworld-dbg``, and ``helloworld-dev`` packages
+are built. For information on how to customize the packaging process, see the
 ":ref:`dev-manual/new-recipe:splitting an application into multiple packages`"
 section.
 
-Autotooled Package
-------------------
+Building a Makefile-Based Package
+---------------------------------
 
-Applications that use Autotools such as ``autoconf`` and ``automake``
-require a recipe that has a source archive listed in :term:`SRC_URI` and
-also inherit the :ref:`ref-classes-autotools` class,
-which contains the definitions of all the steps needed to build an
-Autotool-based application. The result of the build is automatically
-packaged. And, if the application uses NLS for localization, packages
-with local information are generated (one package per language).
-Following is one example: (``hello_2.3.bb``)::
-
-   SUMMARY = "GNU Helloworld application"
-   SECTION = "examples"
-   LICENSE = "GPL-2.0-or-later"
-   LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
-
-   SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
-
-   inherit autotools gettext
-
-The variable :term:`LIC_FILES_CHKSUM` is used to track source license
-changes as described in the
-":ref:`dev-manual/licenses:tracking license changes`" section in
-the Yocto Project Overview and Concepts Manual. You can quickly create
-Autotool-based recipes in a manner similar to the previous example.
-
-Makefile-Based Package
-----------------------
-
-Applications that use GNU ``make`` also require a recipe that has the
-source archive listed in :term:`SRC_URI`. You do not need to add a
-:ref:`ref-tasks-compile` step since by default BitBake starts the ``make`` command
-to compile the application. If you need additional ``make`` options, you
-should store them in the
-:term:`EXTRA_OEMAKE` or
-:term:`PACKAGECONFIG_CONFARGS`
-variables. BitBake passes these options into the GNU ``make``
-invocation. Note that a :ref:`ref-tasks-install` task is still required.
-Otherwise, BitBake runs an empty :ref:`ref-tasks-install` task by default.
+Applications built with GNU ``make`` require a recipe that has the source archive
+listed in :term:`SRC_URI`. You do not need to add a :ref:`ref-tasks-compile`
+step since by default BitBake starts the ``make`` command to compile the
+application. If you need additional ``make`` options, you should store them in
+the :term:`EXTRA_OEMAKE` or :term:`PACKAGECONFIG_CONFARGS` variables. BitBake
+passes these options into the GNU ``make`` invocation. Note that a
+:ref:`ref-tasks-install` task is still required. Otherwise, BitBake runs an
+empty :ref:`ref-tasks-install` task by default.
 
 Some applications might require extra parameters to be passed to the
 compiler. For example, the application might need an additional header
@@ -1294,6 +1263,31 @@ In the following example, ``lz4`` is a makefile-based package::
 
    BBCLASSEXTEND = "native nativesdk"
 
+Building an Autotooled Package
+------------------------------
+
+Applications built with the Autotools such as ``autoconf`` and ``automake``
+require a recipe that has a source archive listed in :term:`SRC_URI` and also
+inherit the :ref:`ref-classes-autotools` class, which contains the definitions
+of all the steps needed to build an Autotool-based application. The result of
+the build is automatically packaged. And, if the application uses NLS for
+localization, packages with local information are generated (one package per
+language). Following is one example: (``hello_2.3.bb``)::
+
+   SUMMARY = "GNU Helloworld application"
+   SECTION = "examples"
+   LICENSE = "GPL-2.0-or-later"
+   LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
+
+   SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
+
+   inherit autotools gettext
+
+The variable :term:`LIC_FILES_CHKSUM` is used to track source license changes
+as described in the ":ref:`dev-manual/licenses:tracking license changes`"
+section in the Yocto Project Overview and Concepts Manual. You can quickly
+create Autotool-based recipes in a manner similar to the previous example.
+
 Splitting an Application into Multiple Packages
 -----------------------------------------------
 
-- 
2.37.2

Re: [docs] [PATCH] dev-manual: new-recipe.rst: restructure examples

[Quentin Schulz]

Hi Michael,

On 2/15/23 10:58, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> 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.
> 

Reviewed-by: Quentin Schulz <foss+yocto@0leil.net>

Thanks,
Quentin