docs/manual/adding-packages-cmake.txt

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