adding-packages-meson.txt 5.5 KB

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