adding-packages-cmake.txt 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. === Infrastructure for CMake-based packages
  4. [[cmake-package-tutorial]]
  5. ==== +cmake-package+ tutorial
  6. First, let's see how to write a +.mk+ file for a CMake-based package,
  7. with an example :
  8. ------------------------
  9. 01: ################################################################################
  10. 02: #
  11. 03: # libfoo
  12. 04: #
  13. 05: ################################################################################
  14. 06:
  15. 07: LIBFOO_VERSION = 1.0
  16. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  17. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  18. 10: LIBFOO_INSTALL_STAGING = YES
  19. 11: LIBFOO_INSTALL_TARGET = NO
  20. 12: LIBFOO_CONF_OPTS = -DBUILD_DEMOS=ON
  21. 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
  22. 14:
  23. 15: $(eval $(cmake-package))
  24. ------------------------
  25. On line 7, we declare the version of the package.
  26. On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended)
  27. and the location of the tarball on the Web. Buildroot will automatically
  28. download the tarball from this location.
  29. On line 10, we tell Buildroot to install the package to the staging
  30. directory. The staging directory, located in +output/staging/+
  31. is the directory where all the packages are installed, including their
  32. development files, etc. By default, packages are not installed to the
  33. staging directory, since usually, only libraries need to be installed in
  34. the staging directory: their development files are needed to compile
  35. other libraries or applications depending on them. Also by default, when
  36. staging installation is enabled, packages are installed in this location
  37. using the +make install+ command.
  38. On line 11, we tell Buildroot to not install the package to the
  39. target directory. This directory contains what will become the root
  40. filesystem running on the target. For purely static libraries, it is
  41. not necessary to install them in the target directory because they will
  42. not be used at runtime. By default, target installation is enabled; setting
  43. this variable to NO is almost never needed. Also by default, packages are
  44. installed in this location using the +make install+ command.
  45. On line 12, we tell Buildroot to pass custom options to CMake when it is
  46. configuring the package.
  47. On line 13, we declare our dependencies, so that they are built
  48. before the build process of our package starts.
  49. Finally, on line line 15, we invoke the +cmake-package+
  50. macro that generates all the Makefile rules that actually allows the
  51. package to be built.
  52. [[cmake-package-reference]]
  53. ==== +cmake-package+ reference
  54. The main macro of the CMake package infrastructure is
  55. +cmake-package+. It is similar to the +generic-package+ macro. The ability to
  56. have target and host packages is also available, with the
  57. +host-cmake-package+ macro.
  58. Just like the generic infrastructure, the CMake infrastructure works
  59. by defining a number of variables before calling the +cmake-package+
  60. macro.
  61. First, all the package metadata information variables that exist in
  62. the generic infrastructure also exist in the CMake infrastructure:
  63. +LIBFOO_VERSION+, +LIBFOO_SOURCE+, +LIBFOO_PATCH+, +LIBFOO_SITE+,
  64. +LIBFOO_SUBDIR+, +LIBFOO_DEPENDENCIES+, +LIBFOO_INSTALL_STAGING+,
  65. +LIBFOO_INSTALL_TARGET+.
  66. A few additional variables, specific to the CMake infrastructure, can
  67. also be defined. Many of them are only useful in very specific cases,
  68. typical packages will therefore only use a few of them.
  69. * +LIBFOO_SUBDIR+ may contain the name of a subdirectory inside the
  70. package that contains the main CMakeLists.txt file. This is useful,
  71. if for example, the main CMakeLists.txt file is not at the root of
  72. the tree extracted by the tarball. If +HOST_LIBFOO_SUBDIR+ is not
  73. specified, it defaults to +LIBFOO_SUBDIR+.
  74. * +LIBFOO_CONF_ENV+, to specify additional environment variables to
  75. pass to CMake. By default, empty.
  76. * +LIBFOO_CONF_OPTS+, to specify additional configure options to pass
  77. to CMake. By default, empty. A number of common CMake options are
  78. set by the +cmake-package+ infrastructure; so it is normally not
  79. necessary to set them in the package's +*.mk+ file unless you want
  80. to override them:
  81. ** +CMAKE_BUILD_TYPE+ is driven by +BR2_ENABLE_DEBUG+;
  82. ** +CMAKE_INSTALL_PREFIX+;
  83. ** +BUILD_SHARED_LIBS+ is driven by +BR2_STATIC_LIBS+;
  84. ** +BUILD_DOC+, +BUILD_DOCS+ are disabled;
  85. ** +BUILD_EXAMPLE+, +BUILD_EXAMPLES+ are disabled;
  86. ** +BUILD_TEST+, +BUILD_TESTS+, +BUILD_TESTING+ are disabled.
  87. * +LIBFOO_SUPPORTS_IN_SOURCE_BUILD = NO+ should be set when the package
  88. cannot be built inside the source tree but needs a separate build
  89. directory.
  90. * +LIBFOO_MAKE+, to specify an alternate +make+ command. This is
  91. typically useful when parallel make is enabled in the configuration
  92. (using +BR2_JLEVEL+) but that this feature should be disabled for
  93. the given package, for one reason or another. By default, set to
  94. +$(MAKE)+. If parallel building is not supported by the package,
  95. then it should be set to +LIBFOO_MAKE=$(MAKE1)+.
  96. * +LIBFOO_MAKE_ENV+, to specify additional environment variables to
  97. pass to make in the build step. These are passed before the +make+
  98. command. By default, empty.
  99. * +LIBFOO_MAKE_OPTS+, to specify additional variables to pass to make
  100. in the build step. These are passed after the +make+ command. By
  101. default, empty.
  102. * +LIBFOO_INSTALL_STAGING_OPTS+ contains the make options used to
  103. install the package to the staging directory. By default, the value
  104. is +DESTDIR=$(STAGING_DIR) install+, which is correct for most
  105. CMake packages. It is still possible to override it.
  106. * +LIBFOO_INSTALL_TARGET_OPTS+ contains the make options used to
  107. install the package to the target directory. By default, the value
  108. is +DESTDIR=$(TARGET_DIR) install+. The default value is correct
  109. for most CMake packages, but it is still possible to override it if
  110. needed.
  111. With the CMake infrastructure, all the steps required to build and
  112. install the packages are already defined, and they generally work well
  113. for most CMake-based packages. However, when required, it is still
  114. possible to customize what is done in any particular step:
  115. * By adding a post-operation hook (after extract, patch, configure,
  116. build or install). See xref:hooks[] for details.
  117. * By overriding one of the steps. For example, even if the CMake
  118. infrastructure is used, if the package +.mk+ file defines its own
  119. +LIBFOO_CONFIGURE_CMDS+ variable, it will be used instead of the
  120. default CMake one. However, using this method should be restricted
  121. to very specific cases. Do not use it in the general case.