kumquat-buildroot/docs/manual/adding-packages-meson.txt

134 lines
5.5 KiB
Plaintext
Raw Normal View History

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
=== Infrastructure for 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. It
uses https://ninja-build.org[Ninja] as a companion tool to perform the actual
build operations.
Let's see how to write a +.mk+ file for a Meson-based package, 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 = GPL-3.0+
11: FOO_LICENSE_FILES = COPYING
12: FOO_INSTALL_STAGING = YES
13:
14: FOO_DEPENDENCIES = host-pkgconf bar
15:
16: ifeq ($(BR2_PACKAGE_BAZ),y)
17: FOO_CONF_OPTS += -Dbaz=true
18: FOO_DEPENDENCIES += baz
19: else
20: FOO_CONF_OPTS += -Dbaz=false
21: endif
22:
23: $(eval $(meson-package))
--------------------------------
The Makefile starts with the definition of the standard variables for package
declaration (lines 7 to 11).
On line line 23, we invoke the +meson-package+ macro that generates all the
Makefile rules that actually allows the package to be built.
In the example, +host-pkgconf+ and +bar+ are declared as dependencies in
+FOO_DEPENDENCIES+ at line 14 because the Meson build file of +foo+ uses
`pkg-config` to determine the compilation flags and libraries of package +bar+.
Note that it is not necessary to add +host-meson+ in the +FOO_DEPENDENCIES+
variable of a package, since this basic dependency is automatically added as
needed by the Meson package infrastructure.
If the "baz" package is selected, then support for the "baz" feature in "foo" is
activated by adding +-Dbaz=true+ to +FOO_CONF_OPTS+ at line 17, as specified in
the +meson_options.txt+ file in "foo" source tree. The "baz" package is also
added to +FOO_DEPENDENCIES+. Note that the support for +baz+ is explicitly
disabled at line 20, if the package is not selected.
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.
[[meson-package-reference]]
==== +meson-package+ reference
The main macro of the Meson package infrastructure is +meson-package+. It is
similar to the +generic-package+ macro. The ability to have target and host
packages is also available, with the +host-meson-package+ macro.
Just like the generic infrastructure, the Meson infrastructure works by defining
a number of variables before calling the +meson-package+ macro.
First, all the package metadata information variables that exist in the generic
infrastructure also exist in the Meson infrastructure: +FOO_VERSION+,
+FOO_SOURCE+, +FOO_PATCH+, +FOO_SITE+, +FOO_SUBDIR+, +FOO_DEPENDENCIES+,
+FOO_INSTALL_STAGING+, +FOO_INSTALL_TARGET+.
A few additional variables, specific to the Meson infrastructure, can also be
defined. Many of them are only useful in very specific cases, typical packages
will therefore only use a few of them.
* +FOO_SUBDIR+ may contain the name of a subdirectory inside the
package that contains the main meson.build file. This is useful,
if for example, the main meson.build file is not at the root of
the tree extracted by the tarball. If +HOST_FOO_SUBDIR+ is not
specified, it defaults to +FOO_SUBDIR+.
* +FOO_CONF_ENV+, to specify additional environment variables to pass to
+meson+ for the configuration step. By default, empty.
* +FOO_CONF_OPTS+, to specify additional options to pass to +meson+ for the
configuration step. By default, empty.
infra/pkg-meson: allow packages to pass custom compiler/linker flags Meson does not allow to pass CFLAGS/LDFLAGS/CXXFLAGS via the environment or via command-line arguments or options (instead, those flags from the environment are passed to the host compiler, which is seldom what we need). The only way to pas those flags is via the cross-compilation.conf file. Add LIBFOO_CFLAGS, LIBFOO_LDFLAGS and LIBFOO_CXXFLAGS variables to allow packages to provide their own flags, possibly overriding the generic ones entirely, as we allow for other infras. Those per-package flags will then be used to generate the per-package cross-compilation.conf. This means that the meson infra is the first and only infra for which FOO_CFLAGS, FOO_LDFLAGS, and FOO_CXXFLAGS are meaningful, while for the other infras, they are just variables private to the package itself. Instead of naming those variables after the meson infra (e.g. FOO_MESON_CFLAGS), we name them with a generic name, as maybe, just maybe, we could also change the other infras to also recognise those variables. Just like for the HOST_MESON_SED_CFLAGS etc., we need to add auxiliary variables to do convert the shell-formatted argument list into the JSON-formatted list that meson expects. We can't use a pure-make construct because the CFLAGS can contain quoting that needs to be expanded by the shell. Similarly, we need a condition on the strip'ed variable to avoid passing empty arguments. To mimic this feature for packages that are built from the SDK, we also install a templatised version of cross-compilation.conf, with three new placeholders for custom flags. If a user wants to build a package that needs custom flags, they can use that template to generate a per-package cross-compilation.conf. Signed-off-by: Peter Seiderer <ps.report@gmx.net> Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr> Cc: Adam Duskett <aduskett@gmail.com> Cc: Thomas Petazzoni <thomas.petazzoni@bootlin.com> Tested-by: Peter Seiderer <ps.report@gmx.net> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
2019-06-24 22:25:48 +02:00
* +FOO_CFLAGS+, to specify compiler arguments added to the package specific
+cross-compile.conf+ file +c_args+ property. By default, the value of
+TARGET_CFLAGS+.
* +FOO_CXXFLAGS+, to specify compiler arguments added to the package specific
+cross-compile.conf+ file +cpp_args+ property. By default, the value of
+TARGET_CXXFLAGS+.
* +FOO_LDFLAGS+, to specify compiler arguments added to the package specific
+cross-compile.conf+ file +c_link_args+ and +cpp_link_args+ properties. By
default, the value of +TARGET_LDFLAGS+.
* +FOO_MESON_EXTRA_BINARIES+, to specify a space-separated list of programs
to add to the `[binaries]` section of the meson `cross-compilation.conf`
configuration file. The format is `program-name='/path/to/program'`, with
no space around the +=+ sign, and with the path of the program between
single quotes. By default, empty. Note that Buildroot already sets the
correct values for +c+, +cpp+, +ar+, +strip+, and +pkgconfig+.
* +FOO_MESON_EXTRA_PROPERTIES+, to specify a space-separated list of
properties to add to the `[properties]` section of the meson
`cross-compilation.conf` configuration file. The format is
`property-name=<value>` with no space around the +=+ sign, and with
single quotes around string values. By default, empty. Note that
Buildroot already sets values for +needs_exe_wrapper+, +c_args+,
+c_link_args+, +cpp_args+, +cpp_link_args+, +sys_root+, and
+pkg_config_libdir+.
* +FOO_NINJA_ENV+, to specify additional environment variables to pass to
+ninja+, meson companion tool in charge of the build operations. By default,
empty.
* +FOO_NINJA_OPTS+, to specify a space-separated list of targets to build. By
default, empty, to build the default target(s).