NetCube-Systems-Austria/kumquat-buildroot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs/manual: document pkg-meson infra

Browse Source 
Update documentation about adding meson-based packages with instructions for
using pkg-meson infrastructure.

Signed-off-by: Eric Le Bihan <eric.le.bihan.dev@free.fr>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
This commit is contained in:
Eric Le Bihan 2018-05-15 21:51:53 +02:00 committed by Thomas Petazzoni
parent 91f7f38106
commit 12e56136e2
1 changed files with 56 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
docs/manual/adding-packages-meson.txt
View File

@ -1,18 +1,18 @@
// -*- mode:doc; -*- // -*- mode:doc; -*-
// vim: set syntax=asciidoc: // vim: set syntax=asciidoc:
=== Integration of Meson-based packages === Infrastructure for Meson-based packages
[[meson-package-tutorial]] [[meson-package-tutorial]]
==== +meson-package+ tutorial ==== +meson-package+ tutorial
http://mesonbuild.com[Meson] is an open source build system meant to be both 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. 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.
Buildroot does not (yet) provide a dedicated package infrastructure for Let's see how to write a +.mk+ file for a Meson-based package, with an example:
meson-based packages. So, we will explain how to write a +.mk+ file for such a
package. Let's start with an example:
------------------------------ ------------------------------
01: ################################################################################ 01: ################################################################################
@ -28,74 +28,69 @@ package. Let's start with an example:
11: FOO_LICENSE_FILES = COPYING 11: FOO_LICENSE_FILES = COPYING
12: FOO_INSTALL_STAGING = YES 12: FOO_INSTALL_STAGING = YES
13: 13:
14: FOO_DEPENDENCIES = host-meson host-pkgconf bar 14: FOO_DEPENDENCIES = host-pkgconf bar
15: 15:
16: FOO_CONF_OPTS += \ 16: ifeq ($(BR2_PACKAGE_BAZ),y)
17: --prefix=/usr \ 17: FOO_CONF_OPTS += -Dbaz=true
18: --buildtype $(if $(BR2_ENABLE_DEBUG),debug,release) \ 18: FOO_DEPENDENCIES += baz
19: --cross-file $(HOST_DIR)/etc/meson/cross-compilation.conf 19: else
20: 20: FOO_CONF_OPTS += -Dbaz=false
21: FOO_NINJA_OPTS = $(if $(VERBOSE),-v) -j$(PARALLEL_JOBS) 21: endif
22: 22:
23: ifeq ($(BR2_PACKAGE_BAZ),y) 23: $(eval $(meson-package))
24: FOO_CONF_OPTS += -Dbaz
25: endif
26:
27: define FOO_CONFIGURE_CMDS
28: rm -rf $(@D)/build
29: mkdir -p $(@D)/build
30: $(TARGET_MAKE_ENV) meson $(FOO_CONF_OPTS) $(@D) $(@D)/build
31: endef
32:
33: define FOO_BUILD_CMDS
34: $(TARGET_MAKE_ENV) ninja $(FOO_NINJA_OPTS) -C $(@D)/build
35: endef
36:
37: define FOO_INSTALL_TARGET_CMDS
38: $(TARGET_MAKE_ENV) DESTDIR=$(TARGET_DIR) ninja $(FOO_NINJA_OPTS) \
39: -C $(@D)/build install
40: endef
41:
42: define FOO_INSTALL_STAGING_CMDS
43: $(TARGET_MAKE_ENV) DESTDIR=$(STAGING_DIR) ninja $(FOO_NINJA_OPTS) \
44: -C $(@D)/build install
45: endef
46:
47: $(eval $(generic-package))
-------------------------------- --------------------------------
The Makefile starts with the definition of the standard variables for package The Makefile starts with the definition of the standard variables for package
declaration (lines 7 to 11). declaration (lines 7 to 11).
As seen in line 47, it is based on the On line line 23, we invoke the +meson-package+ macro that generates all the
xref:generic-package-tutorial[+generic-package+ infrastructure]. So, it defines Makefile rules that actually allows the package to be built.
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 In the example, +host-pkgconf+ and +bar+ are declared as dependencies in
Meson is invoked to generate the Ninja build file. The options required to +FOO_DEPENDENCIES+ at line 14 because the Meson build file of +foo+ uses
configure the cross-compilation of the package are passed via `pkg-config` to determine the compilation flags and libraries of package +bar+.
+FOO_CONF_OPTS+.
* +FOO_BUILD_CMDS+: Ninja is invoked to perform the build. 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.
* +FOO_INSTALL_TARGET_CMDS+: Ninja is invoked to install the files generated If the "baz" package is selected, then support for the "baz" feature in "foo" is
during the build step in the target directory. 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
* +FOO_INSTALL_STAGING_CMDS+: Ninja is invoked to install the files generated added to +FOO_DEPENDENCIES+. Note that the support for +baz+ is explicitly
during the build step in the staging directory, as +FOO_INSTALL_STAGING+ is disabled at line 20, if the package is not selected.
set to "YES".
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+.
If the "baz" package is selected, then support for the "baz" feature in "foo"
is activated by adding +-Dbaz+ to +FOO_CONF_OPTS+, as specified in the
+meson_options.txt+ file in "foo" source tree.
To sum it up, to add a new meson-based package, the Makefile example can be 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 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 uppercase name of the new package and update the values of the standard
variables. 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_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.
* +FOO_NINJA_ENV+, to specify additional environment variables to pass to
+ninja+, meson companion tool in charge of the build operations. By default,
empty.