From: Eric Le Bihan Date: Tue, 15 May 2018 19:51:53 +0000 (+0200) Subject: docs/manual: document pkg-meson infra X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=12e56136e24b76d153950afe27e13bbf5f11eebc;p=buildroot.git docs/manual: document pkg-meson infra Update documentation about adding meson-based packages with instructions for using pkg-meson infrastructure. Signed-off-by: Eric Le Bihan Signed-off-by: Thomas Petazzoni --- diff --git a/docs/manual/adding-packages-meson.txt b/docs/manual/adding-packages-meson.txt index f8aa08fa91..c52fe10506 100644 --- a/docs/manual/adding-packages-meson.txt +++ b/docs/manual/adding-packages-meson.txt @@ -1,18 +1,18 @@ // -*- mode:doc; -*- // vim: set syntax=asciidoc: -=== Integration of Meson-based packages +=== 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. +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 -meson-based packages. So, we will explain how to write a +.mk+ file for such a -package. Let's start with an example: +Let's see how to write a +.mk+ file for a Meson-based package, with an example: ------------------------------ 01: ################################################################################ @@ -28,74 +28,69 @@ package. Let's start with an example: 11: FOO_LICENSE_FILES = COPYING 12: FOO_INSTALL_STAGING = YES 13: -14: FOO_DEPENDENCIES = host-meson host-pkgconf bar +14: FOO_DEPENDENCIES = host-pkgconf bar 15: -16: FOO_CONF_OPTS += \ -17: --prefix=/usr \ -18: --buildtype $(if $(BR2_ENABLE_DEBUG),debug,release) \ -19: --cross-file $(HOST_DIR)/etc/meson/cross-compilation.conf -20: -21: FOO_NINJA_OPTS = $(if $(VERBOSE),-v) -j$(PARALLEL_JOBS) +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: ifeq ($(BR2_PACKAGE_BAZ),y) -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)) +23: $(eval $(meson-package)) -------------------------------- The Makefile starts with the definition of the standard variables for package declaration (lines 7 to 11). -As seen in line 47, 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: +On line line 23, we invoke the +meson-package+ macro that generates all the +Makefile rules that actually allows the package to be built. -* +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_CONF_OPTS+. +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+. -* +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 - during the build step in the target directory. - -* +FOO_INSTALL_STAGING_CMDS+: Ninja is invoked to install the files generated - during the build step in the staging directory, as +FOO_INSTALL_STAGING+ is - 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. +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_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.