[v3,2/3] docs/manual: document meson-based packages

Message ID 20170727095527.14324-3-joerg.krause@embedded.rocks
State New
Headers show

Commit Message

Jörg Krause July 27, 2017, 9:55 a.m.
From: Eric Le Bihan <eric.le.bihan.dev@free.fr>

Add instructions for adding a package which uses the Meson build system.

Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr>
[Jörg Krause:
 * use one-liner for buildtype]
Signed-off-by: Jörg Krause <joerg.krause@embedded.rocks>
---
v3:
 * none
---
 docs/manual/adding-packages-meson.txt | 80 +++++++++++++++++++++++++++++++++++
 docs/manual/adding-packages.txt       |  2 +
 2 files changed, 82 insertions(+)
 create mode 100644 docs/manual/adding-packages-meson.txt

Comments

Yann E. MORIN Oct. 8, 2017, 10:03 a.m. | #1
Jörg, Éric, All,

On 2017-07-27 11:55 +0200, Jörg Krause spake thusly:
> From: Eric Le Bihan <eric.le.bihan.dev@free.fr>
> 
> Add instructions for adding a package which uses the Meson build system.
> 
> Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr>
> [Jörg Krause:
>  * use one-liner for buildtype]
> Signed-off-by: Jörg Krause <joerg.krause@embedded.rocks>
> ---
> v3:
>  * none
> ---
>  docs/manual/adding-packages-meson.txt | 80 +++++++++++++++++++++++++++++++++++
>  docs/manual/adding-packages.txt       |  2 +
>  2 files changed, 82 insertions(+)
>  create mode 100644 docs/manual/adding-packages-meson.txt
> 
> diff --git a/docs/manual/adding-packages-meson.txt b/docs/manual/adding-packages-meson.txt
> new file mode 100644
> index 0000000000..697f2520c7
> --- /dev/null
> +++ b/docs/manual/adding-packages-meson.txt
> @@ -0,0 +1,80 @@
> +// -*- mode:doc; -*-
> +// vim: set syntax=asciidoc:
> +
> +=== Integration of Meson-based packages
> +
> +[[meson-package-tutorial]]
> +
> +==== +meson-package+ tutorial
> +
> +http://mesonbuild.com[Meson] is an open source build system meant to be both
> +extremely fast, and, even more importantly, as user friendly as possible.
> +
> +Buildroot does not (yet) provide a dedicated package infrastructure for
> +meson-based packages. So, we will explain how to write a +.mk+ file for such a
> +package. Let's start with an example:
> +
> +------------------------------
> +01: ################################################################################
> +02: #
> +03: # foo

We're not very consistent with the meta-name of the tutorial package.
Some infras use libfoo, others use foo, while there is also foobar.
Sigh...

foo is nice for me, but I'd settle for anything as long as it is
consistent.

> +04: #
> +05: ################################################################################
> +06:
> +07: FOO_VERSION = 1.0
> +08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
> +09: FOO_SITE = http://www.foosoftware.org/download
> +10: FOO_LICENSE = GPLv3+
> +11: FOO_LICENSE_FILES = COPYING
> +12:
> +13: FOO_DEPENDENCIES = host-meson host-pkgconf bar
> +14:
> +15: FOO_MESON_OPTS += \
> +16: 	--prefix=/usr \
> +17: 	--buildtype $(if $(BR2_ENABLE_DEBUG),debug,release) \
> +18: 	--cross-file $(HOST_DIR)/etc/meson/cross-compilation.conf

Whether we one day add a meson-package infra or not, I think this
variable should be documented as FOO_CONF_OPTS for symetry with the
other package infras.

> +20: define FOO_CONFIGURE_CMDS
> +21: 	rm -rf $(@D)/build

We don't usually remove stuff created in a previous run, unless it
breaks the build.

> +22: 	mkdir -p $(@D)/build
> +23: 	$(TARGET_MAKE_ENV) meson.py $(FOO_MESON_OPTS) $(@D) $(@D)/build
> +24: endef
> +25:
> +26: define FOO_BUILD_CMDS
> +27: 	$(TARGET_MAKE_ENV) ninja -C $(@D)/build

Would the build accept additional options? I mean, do we need to prepare
to pass extra parameteres, like FOO_MAKE_OPTS does for autotools?

> +28: endef
> +29:
> +30: define FOO_INSTALL_TARGET_CMDS
> +31: 	$(TARGET_MAKE_ENV) DESTDIR=$(TARGET_DIR) ninja -C $(@D)/build install

Ditto FOO_INSTALL_TARGET_OPTS and FOO_INSTALL_STAGING_OPTS?

> +32: endef

If all the meson-based packages are just those three commands (configure,
build and install) and never deviates by more than the _OPTS stuff, then
I believe we should add the meson-package infra right away. And it
should be reasonably easy.

Regards,
Yann E. MORIN.

> +34: $(eval $(generic-package))
> +--------------------------------
> +
> +The Makefile starts with the definition of the standard variables for package
> +declaration (lines 7 to 11).
> +
> +As seen in line 34, it is based on the
> +xref:generic-package-tutorial[+generic-package+ infrastructure]. So, it defines
> +the variables required by this particular infrastructure, where Meson and its
> +companion tool, Ninja, are invoked:
> +
> +* +FOO_CONFIGURE_CMDS+: the build directory required by Meson is created, and
> +  Meson is invoked to generate the Ninja build file. The options required to
> +  configure the cross-compilation of the package are passed via
> +  +FOO_MESON_OPTS+.
> +
> +* +FOO_BUILD_CMDS+: Ninja is invoked to perform the build.
> +
> +* +FOO_INSTALL_TARGET_CMDS+: Ninja is invoked to install the files generated
> +  during the build step.
> +
> +In order to have Meson available for the build, +FOO_DEPENDENCIES+ needs to
> +contain +host-meson+. In the example, +host-pkgconf+ and +bar+ are also
> +declared as dependencies because the Meson build file of +foo+ uses `pkg-config`
> +to determine the compilation flags and libraries of package +bar+.
> +
> +To sum it up, to add a new meson-based package, the Makefile example can be
> +copied verbatim then edited to replace all occurences of +FOO+ with the
> +uppercase name of the new package and update the values of the standard
> +variables.
> diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
> index d577ff030e..e542124cf9 100644
> --- a/docs/manual/adding-packages.txt
> +++ b/docs/manual/adding-packages.txt
> @@ -34,6 +34,8 @@ include::adding-packages-rebar.txt[]
>  
>  include::adding-packages-waf.txt[]
>  
> +include::adding-packages-meson.txt[]
> +
>  include::adding-packages-kernel-module.txt[]
>  
>  include::adding-packages-asciidoc.txt[]
> -- 
> 2.13.3
>
Eric Le Bihan Oct. 8, 2017, 2:48 p.m. | #2
On 17-10-08 12:03:41, Yann E. MORIN wrote:
> Jörg, Éric, All,
>
> On 2017-07-27 11:55 +0200, Jörg Krause spake thusly:
> > From: Eric Le Bihan <eric.le.bihan.dev@free.fr>
> >
> > Add instructions for adding a package which uses the Meson build system.
> >
> > Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr>
> > [Jörg Krause:
> >  * use one-liner for buildtype]
> > Signed-off-by: Jörg Krause <joerg.krause@embedded.rocks>
> > ---
> > v3:
> >  * none
> > ---
> >  docs/manual/adding-packages-meson.txt | 80 +++++++++++++++++++++++++++++++++++
> >  docs/manual/adding-packages.txt       |  2 +
> >  2 files changed, 82 insertions(+)
> >  create mode 100644 docs/manual/adding-packages-meson.txt
> >
> > diff --git a/docs/manual/adding-packages-meson.txt b/docs/manual/adding-packages-meson.txt
> > new file mode 100644
> > index 0000000000..697f2520c7
> > --- /dev/null
> > +++ b/docs/manual/adding-packages-meson.txt
> > @@ -0,0 +1,80 @@
> > +// -*- mode:doc; -*-
> > +// vim: set syntax=asciidoc:
> > +
> > +=== Integration of Meson-based packages
> > +
> > +[[meson-package-tutorial]]
> > +
> > +==== +meson-package+ tutorial
> > +
> > +http://mesonbuild.com[Meson] is an open source build system meant to be both
> > +extremely fast, and, even more importantly, as user friendly as possible.
> > +
> > +Buildroot does not (yet) provide a dedicated package infrastructure for
> > +meson-based packages. So, we will explain how to write a +.mk+ file for such a
> > +package. Let's start with an example:
> > +
> > +------------------------------
> > +01: ################################################################################
> > +02: #
> > +03: # foo
>
> We're not very consistent with the meta-name of the tutorial package.
> Some infras use libfoo, others use foo, while there is also foobar.
> Sigh...
>
> foo is nice for me, but I'd settle for anything as long as it is
> consistent.
>
> > +04: #
> > +05: ################################################################################
> > +06:
> > +07: FOO_VERSION = 1.0
> > +08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
> > +09: FOO_SITE = http://www.foosoftware.org/download
> > +10: FOO_LICENSE = GPLv3+
> > +11: FOO_LICENSE_FILES = COPYING
> > +12:
> > +13: FOO_DEPENDENCIES = host-meson host-pkgconf bar
> > +14:
> > +15: FOO_MESON_OPTS += \
> > +16: 	--prefix=/usr \
> > +17: 	--buildtype $(if $(BR2_ENABLE_DEBUG),debug,release) \
> > +18: 	--cross-file $(HOST_DIR)/etc/meson/cross-compilation.conf
>
> Whether we one day add a meson-package infra or not, I think this
> variable should be documented as FOO_CONF_OPTS for symetry with the
> other package infras.

OK.

> > +20: define FOO_CONFIGURE_CMDS
> > +21: 	rm -rf $(@D)/build
>
> We don't usually remove stuff created in a previous run, unless it
> breaks the build.

OK.

> > +22: 	mkdir -p $(@D)/build
> > +23: 	$(TARGET_MAKE_ENV) meson.py $(FOO_MESON_OPTS) $(@D) $(@D)/build
> > +24: endef
> > +25:
> > +26: define FOO_BUILD_CMDS
> > +27: 	$(TARGET_MAKE_ENV) ninja -C $(@D)/build
>
> Would the build accept additional options? I mean, do we need to prepare
> to pass extra parameteres, like FOO_MAKE_OPTS does for autotools?

I'll check this.

> > +28: endef
> > +29:
> > +30: define FOO_INSTALL_TARGET_CMDS
> > +31: 	$(TARGET_MAKE_ENV) DESTDIR=$(TARGET_DIR) ninja -C $(@D)/build install
>
> Ditto FOO_INSTALL_TARGET_OPTS and FOO_INSTALL_STAGING_OPTS?

I did not know about these two (I should have read the other pkg-*.mk
more carefully). I'll check this.

> > +32: endef
>
> If all the meson-based packages are just those three commands (configure,
> build and install) and never deviates by more than the _OPTS stuff, then
> I believe we should add the meson-package infra right away. And it
> should be reasonably easy.
>
> Regards,
> Yann E. MORIN.
>
> > +34: $(eval $(generic-package))
> > +--------------------------------
> > +
> > +The Makefile starts with the definition of the standard variables for package
> > +declaration (lines 7 to 11).
> > +
> > +As seen in line 34, it is based on the
> > +xref:generic-package-tutorial[+generic-package+ infrastructure]. So, it defines
> > +the variables required by this particular infrastructure, where Meson and its
> > +companion tool, Ninja, are invoked:
> > +
> > +* +FOO_CONFIGURE_CMDS+: the build directory required by Meson is created, and
> > +  Meson is invoked to generate the Ninja build file. The options required to
> > +  configure the cross-compilation of the package are passed via
> > +  +FOO_MESON_OPTS+.
> > +
> > +* +FOO_BUILD_CMDS+: Ninja is invoked to perform the build.
> > +
> > +* +FOO_INSTALL_TARGET_CMDS+: Ninja is invoked to install the files generated
> > +  during the build step.
> > +
> > +In order to have Meson available for the build, +FOO_DEPENDENCIES+ needs to
> > +contain +host-meson+. In the example, +host-pkgconf+ and +bar+ are also
> > +declared as dependencies because the Meson build file of +foo+ uses `pkg-config`
> > +to determine the compilation flags and libraries of package +bar+.
> > +
> > +To sum it up, to add a new meson-based package, the Makefile example can be
> > +copied verbatim then edited to replace all occurences of +FOO+ with the
> > +uppercase name of the new package and update the values of the standard
> > +variables.
> > diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
> > index d577ff030e..e542124cf9 100644
> > --- a/docs/manual/adding-packages.txt
> > +++ b/docs/manual/adding-packages.txt
> > @@ -34,6 +34,8 @@ include::adding-packages-rebar.txt[]
> >
> >  include::adding-packages-waf.txt[]
> >
> > +include::adding-packages-meson.txt[]
> > +
> >  include::adding-packages-kernel-module.txt[]
> >
> >  include::adding-packages-asciidoc.txt[]
> > --
> > 2.13.3
> >

Regards,

--
ELB
Adrian Perez de Castro Oct. 8, 2017, 4:48 p.m. | #3
Hello everybody,

On Sun, 8 Oct 2017 16:48:17 +0200, Eric Le Bihan <eric.le.bihan.dev@free.fr> wrote:
> On 17-10-08 12:03:41, Yann E. MORIN wrote:
> > Jörg, Éric, All,
> >
> > On 2017-07-27 11:55 +0200, Jörg Krause spake thusly:
> > > From: Eric Le Bihan <eric.le.bihan.dev@free.fr>
> > >
> > > Add instructions for adding a package which uses the Meson build system.
> > >
> > > Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr>
> > > [Jörg Krause:
> > >  * use one-liner for buildtype]
> > > Signed-off-by: Jörg Krause <joerg.krause@embedded.rocks>
> > > ---
> > > v3:
> > >  * none
> > > ---
> > >  docs/manual/adding-packages-meson.txt | 80 +++++++++++++++++++++++++++++++++++
> > >  docs/manual/adding-packages.txt       |  2 +
> > >  2 files changed, 82 insertions(+)
> > >  create mode 100644 docs/manual/adding-packages-meson.txt
> > >
> > > diff --git a/docs/manual/adding-packages-meson.txt b/docs/manual/adding-packages-meson.txt
> > > new file mode 100644
> > > index 0000000000..697f2520c7
> > > --- /dev/null
> > > +++ b/docs/manual/adding-packages-meson.txt
> > > @@ -0,0 +1,80 @@
> > > +// -*- mode:doc; -*-
> > > +// vim: set syntax=asciidoc:
> > > +
> > > +=== Integration of Meson-based packages
> > > +
> > > +[[meson-package-tutorial]]
> > > +
> > > +==== +meson-package+ tutorial
> > > +
> > > +http://mesonbuild.com[Meson] is an open source build system meant to be both
> > > +extremely fast, and, even more importantly, as user friendly as possible.
> > > +
> > > +Buildroot does not (yet) provide a dedicated package infrastructure for
> > > +meson-based packages. So, we will explain how to write a +.mk+ file for such a
> > > +package. Let's start with an example:
> > > +
> > > +------------------------------
> > > +01: ################################################################################
> > > +02: #
> > > +03: # foo
> >
> > We're not very consistent with the meta-name of the tutorial package.
> > Some infras use libfoo, others use foo, while there is also foobar.
> > Sigh...
> >
> > foo is nice for me, but I'd settle for anything as long as it is
> > consistent.
> >
> > > +04: #
> > > +05: ################################################################################
> > > +06:
> > > +07: FOO_VERSION = 1.0
> > > +08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
> > > +09: FOO_SITE = http://www.foosoftware.org/download
> > > +10: FOO_LICENSE = GPLv3+
> > > +11: FOO_LICENSE_FILES = COPYING
> > > +12:
> > > +13: FOO_DEPENDENCIES = host-meson host-pkgconf bar
> > > +14:
> > > +15: FOO_MESON_OPTS += \
> > > +16: 	--prefix=/usr \
> > > +17: 	--buildtype $(if $(BR2_ENABLE_DEBUG),debug,release) \
> > > +18: 	--cross-file $(HOST_DIR)/etc/meson/cross-compilation.conf
> >
> > Whether we one day add a meson-package infra or not, I think this
> > variable should be documented as FOO_CONF_OPTS for symetry with the
> > other package infras.
> 
> OK.
> 
> > > +20: define FOO_CONFIGURE_CMDS
> > > +21: 	rm -rf $(@D)/build
> >
> > We don't usually remove stuff created in a previous run, unless it
> > breaks the build.
> 
> OK.

Though you may want/need to remove the build directory at least for the
“<pkg>-reconfigure” target because Meson will refuse to use an
already-configured build directory:

  % mkdir build
  % meson . build/
  ...
  % meson . build/
  Trying to run Meson on a build directory that has already been configured.
  If you want to build it, just run your build command (e.g. ninja) inside the
  build directory. Meson will autodetect any changes in your setup and regenerate
  itself as required. Though it shouldn't be necessary, running ninja reconfigure
  will force Meson to regenerate the build files.
 
  If you want to change option values, use meson configure instead.
  %

> > > +22: 	mkdir -p $(@D)/build
> > > +23: 	$(TARGET_MAKE_ENV) meson.py $(FOO_MESON_OPTS) $(@D) $(@D)/build
> > > +24: endef
> > > +25:
> > > +26: define FOO_BUILD_CMDS
> > > +27: 	$(TARGET_MAKE_ENV) ninja -C $(@D)/build
> >
> > Would the build accept additional options? I mean, do we need to prepare
> > to pass extra parameteres, like FOO_MAKE_OPTS does for autotools?
> 
> I'll check this.
> 
> > > +28: endef
> > > +29:
> > > +30: define FOO_INSTALL_TARGET_CMDS
> > > +31: 	$(TARGET_MAKE_ENV) DESTDIR=$(TARGET_DIR) ninja -C $(@D)/build install
> >
> > Ditto FOO_INSTALL_TARGET_OPTS and FOO_INSTALL_STAGING_OPTS?
> 
> I did not know about these two (I should have read the other pkg-*.mk
> more carefully). I'll check this.
> 
> > > +32: endef
> >
> > If all the meson-based packages are just those three commands (configure,
> > build and install) and never deviates by more than the _OPTS stuff, then
> > I believe we should add the meson-package infra right away. And it
> > should be reasonably easy.
> >
> > Regards,
> > Yann E. MORIN.
> >
> > > +34: $(eval $(generic-package))
> > > +--------------------------------
> > > +
> > > +The Makefile starts with the definition of the standard variables for package
> > > +declaration (lines 7 to 11).
> > > +
> > > +As seen in line 34, it is based on the
> > > +xref:generic-package-tutorial[+generic-package+ infrastructure]. So, it defines
> > > +the variables required by this particular infrastructure, where Meson and its
> > > +companion tool, Ninja, are invoked:
> > > +
> > > +* +FOO_CONFIGURE_CMDS+: the build directory required by Meson is created, and
> > > +  Meson is invoked to generate the Ninja build file. The options required to
> > > +  configure the cross-compilation of the package are passed via
> > > +  +FOO_MESON_OPTS+.
> > > +
> > > +* +FOO_BUILD_CMDS+: Ninja is invoked to perform the build.
> > > +
> > > +* +FOO_INSTALL_TARGET_CMDS+: Ninja is invoked to install the files generated
> > > +  during the build step.
> > > +
> > > +In order to have Meson available for the build, +FOO_DEPENDENCIES+ needs to
> > > +contain +host-meson+. In the example, +host-pkgconf+ and +bar+ are also
> > > +declared as dependencies because the Meson build file of +foo+ uses `pkg-config`
> > > +to determine the compilation flags and libraries of package +bar+.
> > > +
> > > +To sum it up, to add a new meson-based package, the Makefile example can be
> > > +copied verbatim then edited to replace all occurences of +FOO+ with the
> > > +uppercase name of the new package and update the values of the standard
> > > +variables.
> > > diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
> > > index d577ff030e..e542124cf9 100644
> > > --- a/docs/manual/adding-packages.txt
> > > +++ b/docs/manual/adding-packages.txt
> > > @@ -34,6 +34,8 @@ include::adding-packages-rebar.txt[]
> > >
> > >  include::adding-packages-waf.txt[]
> > >
> > > +include::adding-packages-meson.txt[]
> > > +
> > >  include::adding-packages-kernel-module.txt[]
> > >
> > >  include::adding-packages-asciidoc.txt[]
> > > --
> > > 2.13.3
> > >
> 
> Regards,
> 
> --
> ELB
> _______________________________________________
> buildroot mailing list
> buildroot@busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
>
Yann E. MORIN Oct. 8, 2017, 6:05 p.m. | #4
Adrian, All,

On 2017-10-08 18:48 +0200, Adrian Perez de Castro spake thusly:
> On Sun, 8 Oct 2017 16:48:17 +0200, Eric Le Bihan <eric.le.bihan.dev@free.fr> wrote:
> > On 17-10-08 12:03:41, Yann E. MORIN wrote:
> > > On 2017-07-27 11:55 +0200, Jörg Krause spake thusly:
> > > > From: Eric Le Bihan <eric.le.bihan.dev@free.fr>
[--SNIP--]
> > > > +20: define FOO_CONFIGURE_CMDS
> > > > +21: 	rm -rf $(@D)/build
> > > We don't usually remove stuff created in a previous run, unless it
> > > breaks the build.
> > OK.
> Though you may want/need to remove the build directory at least for the
> “<pkg>-reconfigure” target because Meson will refuse to use an
> already-configured build directory:
[--SNIP--]

This is a good reason to forcibly remove it, indeed.

Regards,
Yann E. MORIN.

Patch

diff --git a/docs/manual/adding-packages-meson.txt b/docs/manual/adding-packages-meson.txt
new file mode 100644
index 0000000000..697f2520c7
--- /dev/null
+++ b/docs/manual/adding-packages-meson.txt
@@ -0,0 +1,80 @@ 
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+=== Integration of Meson-based packages
+
+[[meson-package-tutorial]]
+
+==== +meson-package+ tutorial
+
+http://mesonbuild.com[Meson] is an open source build system meant to be both
+extremely fast, and, even more importantly, as user friendly as possible.
+
+Buildroot does not (yet) provide a dedicated package infrastructure for
+meson-based packages. So, we will explain how to write a +.mk+ file for such a
+package. Let's start with an example:
+
+------------------------------
+01: ################################################################################
+02: #
+03: # foo
+04: #
+05: ################################################################################
+06:
+07: FOO_VERSION = 1.0
+08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
+09: FOO_SITE = http://www.foosoftware.org/download
+10: FOO_LICENSE = GPLv3+
+11: FOO_LICENSE_FILES = COPYING
+12:
+13: FOO_DEPENDENCIES = host-meson host-pkgconf bar
+14:
+15: FOO_MESON_OPTS += \
+16: 	--prefix=/usr \
+17: 	--buildtype $(if $(BR2_ENABLE_DEBUG),debug,release) \
+18: 	--cross-file $(HOST_DIR)/etc/meson/cross-compilation.conf
+19:
+20: define FOO_CONFIGURE_CMDS
+21: 	rm -rf $(@D)/build
+22: 	mkdir -p $(@D)/build
+23: 	$(TARGET_MAKE_ENV) meson.py $(FOO_MESON_OPTS) $(@D) $(@D)/build
+24: endef
+25:
+26: define FOO_BUILD_CMDS
+27: 	$(TARGET_MAKE_ENV) ninja -C $(@D)/build
+28: endef
+29:
+30: define FOO_INSTALL_TARGET_CMDS
+31: 	$(TARGET_MAKE_ENV) DESTDIR=$(TARGET_DIR) ninja -C $(@D)/build install
+32: endef
+33:
+34: $(eval $(generic-package))
+--------------------------------
+
+The Makefile starts with the definition of the standard variables for package
+declaration (lines 7 to 11).
+
+As seen in line 34, it is based on the
+xref:generic-package-tutorial[+generic-package+ infrastructure]. So, it defines
+the variables required by this particular infrastructure, where Meson and its
+companion tool, Ninja, are invoked:
+
+* +FOO_CONFIGURE_CMDS+: the build directory required by Meson is created, and
+  Meson is invoked to generate the Ninja build file. The options required to
+  configure the cross-compilation of the package are passed via
+  +FOO_MESON_OPTS+.
+
+* +FOO_BUILD_CMDS+: Ninja is invoked to perform the build.
+
+* +FOO_INSTALL_TARGET_CMDS+: Ninja is invoked to install the files generated
+  during the build step.
+
+In order to have Meson available for the build, +FOO_DEPENDENCIES+ needs to
+contain +host-meson+. In the example, +host-pkgconf+ and +bar+ are also
+declared as dependencies because the Meson build file of +foo+ uses `pkg-config`
+to determine the compilation flags and libraries of package +bar+.
+
+To sum it up, to add a new meson-based package, the Makefile example can be
+copied verbatim then edited to replace all occurences of +FOO+ with the
+uppercase name of the new package and update the values of the standard
+variables.
diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
index d577ff030e..e542124cf9 100644
--- a/docs/manual/adding-packages.txt
+++ b/docs/manual/adding-packages.txt
@@ -34,6 +34,8 @@  include::adding-packages-rebar.txt[]
 
 include::adding-packages-waf.txt[]
 
+include::adding-packages-meson.txt[]
+
 include::adding-packages-kernel-module.txt[]
 
 include::adding-packages-asciidoc.txt[]