1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4=== Infrastructure for Meson-based packages 5 6[[meson-package-tutorial]] 7 8==== +meson-package+ tutorial 9 10http://mesonbuild.com[Meson] is an open source build system meant to be both 11extremely fast, and, even more importantly, as user friendly as possible. It 12uses https://ninja-build.org[Ninja] as a companion tool to perform the actual 13build operations. 14 15Let's see how to write a +.mk+ file for a Meson-based package, with an example: 16 17------------------------------ 1801: ################################################################################ 1902: # 2003: # foo 2104: # 2205: ################################################################################ 2306: 2407: FOO_VERSION = 1.0 2508: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz 2609: FOO_SITE = http://www.foosoftware.org/download 2710: FOO_LICENSE = GPL-3.0+ 2811: FOO_LICENSE_FILES = COPYING 2912: FOO_INSTALL_STAGING = YES 3013: 3114: FOO_DEPENDENCIES = host-pkgconf bar 3215: 3316: ifeq ($(BR2_PACKAGE_BAZ),y) 3417: FOO_CONF_OPTS += -Dbaz=true 3518: FOO_DEPENDENCIES += baz 3619: else 3720: FOO_CONF_OPTS += -Dbaz=false 3821: endif 3922: 4023: $(eval $(meson-package)) 41-------------------------------- 42 43The Makefile starts with the definition of the standard variables for package 44declaration (lines 7 to 11). 45 46On line line 23, we invoke the +meson-package+ macro that generates all the 47Makefile rules that actually allows the package to be built. 48 49In the example, +host-pkgconf+ and +bar+ are declared as dependencies in 50+FOO_DEPENDENCIES+ at line 14 because the Meson build file of +foo+ uses 51`pkg-config` to determine the compilation flags and libraries of package +bar+. 52 53Note that it is not necessary to add +host-meson+ in the +FOO_DEPENDENCIES+ 54variable of a package, since this basic dependency is automatically added as 55needed by the Meson package infrastructure. 56 57If the "baz" package is selected, then support for the "baz" feature in "foo" is 58activated by adding +-Dbaz=true+ to +FOO_CONF_OPTS+ at line 17, as specified in 59the +meson_options.txt+ file in "foo" source tree. The "baz" package is also 60added to +FOO_DEPENDENCIES+. Note that the support for +baz+ is explicitly 61disabled at line 20, if the package is not selected. 62 63To sum it up, to add a new meson-based package, the Makefile example can be 64copied verbatim then edited to replace all occurences of +FOO+ with the 65uppercase name of the new package and update the values of the standard 66variables. 67 68[[meson-package-reference]] 69 70==== +meson-package+ reference 71 72The main macro of the Meson package infrastructure is +meson-package+. It is 73similar to the +generic-package+ macro. The ability to have target and host 74packages is also available, with the +host-meson-package+ macro. 75 76Just like the generic infrastructure, the Meson infrastructure works by defining 77a number of variables before calling the +meson-package+ macro. 78 79First, all the package metadata information variables that exist in the generic 80infrastructure also exist in the Meson infrastructure: +FOO_VERSION+, 81+FOO_SOURCE+, +FOO_PATCH+, +FOO_SITE+, +FOO_SUBDIR+, +FOO_DEPENDENCIES+, 82+FOO_INSTALL_STAGING+, +FOO_INSTALL_TARGET+. 83 84A few additional variables, specific to the Meson infrastructure, can also be 85defined. Many of them are only useful in very specific cases, typical packages 86will therefore only use a few of them. 87 88* +FOO_SUBDIR+ may contain the name of a subdirectory inside the 89 package that contains the main meson.build file. This is useful, 90 if for example, the main meson.build file is not at the root of 91 the tree extracted by the tarball. If +HOST_FOO_SUBDIR+ is not 92 specified, it defaults to +FOO_SUBDIR+. 93 94* +FOO_CONF_ENV+, to specify additional environment variables to pass to 95 +meson+ for the configuration step. By default, empty. 96 97* +FOO_CONF_OPTS+, to specify additional options to pass to +meson+ for the 98 configuration step. By default, empty. 99 100* +FOO_CFLAGS+, to specify compiler arguments added to the package specific 101 +cross-compile.conf+ file +c_args+ property. By default, the value of 102 +TARGET_CFLAGS+. 103 104* +FOO_CXXFLAGS+, to specify compiler arguments added to the package specific 105 +cross-compile.conf+ file +cpp_args+ property. By default, the value of 106 +TARGET_CXXFLAGS+. 107 108* +FOO_LDFLAGS+, to specify compiler arguments added to the package specific 109 +cross-compile.conf+ file +c_link_args+ and +cpp_link_args+ properties. By 110 default, the value of +TARGET_LDFLAGS+. 111 112* +FOO_MESON_EXTRA_BINARIES+, to specify a space-separated list of programs 113 to add to the `[binaries]` section of the meson `cross-compilation.conf` 114 configuration file. The format is `program-name='/path/to/program'`, with 115 no space around the +=+ sign, and with the path of the program between 116 single quotes. By default, empty. Note that Buildroot already sets the 117 correct values for +c+, +cpp+, +ar+, +strip+, and +pkgconfig+. 118 119* +FOO_MESON_EXTRA_PROPERTIES+, to specify a space-separated list of 120 properties to add to the `[properties]` section of the meson 121 `cross-compilation.conf` configuration file. The format is 122 `property-name=<value>` with no space around the +=+ sign, and with 123 single quotes around string values. By default, empty. Note that 124 Buildroot already sets values for +needs_exe_wrapper+, +c_args+, 125 +c_link_args+, +cpp_args+, +cpp_link_args+, +sys_root+, and 126 +pkg_config_libdir+. 127 128* +FOO_NINJA_ENV+, to specify additional environment variables to pass to 129 +ninja+, meson companion tool in charge of the build operations. By default, 130 empty. 131 132* +FOO_NINJA_OPTS+, to specify a space-separated list of targets to build. By 133 default, empty, to build the default target(s). 134