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 10First, let's see how to write a +.mk+ file for a CMake-based package, 11with an example : 12 13------------------------ 1401: ################################################################################ 1502: # 1603: # libfoo 1704: # 1805: ################################################################################ 1906: 2007: LIBFOO_VERSION = 1.0 2108: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz 2209: LIBFOO_SITE = http://www.foosoftware.org/download 2310: LIBFOO_INSTALL_STAGING = YES 2411: LIBFOO_INSTALL_TARGET = NO 2512: LIBFOO_CONF_OPTS = -DBUILD_DEMOS=ON 2613: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf 2714: 2815: $(eval $(cmake-package)) 29------------------------ 30 31On line 7, we declare the version of the package. 32 33On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended) 34and the location of the tarball on the Web. Buildroot will automatically 35download the tarball from this location. 36 37On line 10, we tell Buildroot to install the package to the staging 38directory. The staging directory, located in +output/staging/+ 39is the directory where all the packages are installed, including their 40development files, etc. By default, packages are not installed to the 41staging directory, since usually, only libraries need to be installed in 42the staging directory: their development files are needed to compile 43other libraries or applications depending on them. Also by default, when 44staging installation is enabled, packages are installed in this location 45using the +make install+ command. 46 47On line 11, we tell Buildroot to not install the package to the 48target directory. This directory contains what will become the root 49filesystem running on the target. For purely static libraries, it is 50not necessary to install them in the target directory because they will 51not be used at runtime. By default, target installation is enabled; setting 52this variable to NO is almost never needed. Also by default, packages are 53installed in this location using the +make install+ command. 54 55On line 12, we tell Buildroot to pass custom options to CMake when it is 56configuring the package. 57 58On line 13, we declare our dependencies, so that they are built 59before the build process of our package starts. 60 61Finally, on line line 15, we invoke the +cmake-package+ 62macro that generates all the Makefile rules that actually allows the 63package to be built. 64 65[[cmake-package-reference]] 66 67==== +cmake-package+ reference 68 69The main macro of the CMake package infrastructure is 70+cmake-package+. It is similar to the +generic-package+ macro. The ability to 71have target and host packages is also available, with the 72+host-cmake-package+ macro. 73 74Just like the generic infrastructure, the CMake infrastructure works 75by defining a number of variables before calling the +cmake-package+ 76macro. 77 78First, all the package metadata information variables that exist in 79the 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 84A few additional variables, specific to the CMake infrastructure, can 85also be defined. Many of them are only useful in very specific cases, 86typical 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_CMAKE_BACKEND+ specifies the cmake backend to use, one of 95 `make` (to use the GNU Makefiles generator, the default) or `ninja` 96 (to use the Ninja generator). 97 98* +LIBFOO_CONF_ENV+, to specify additional environment variables to 99 pass to CMake. By default, empty. 100 101* +LIBFOO_CONF_OPTS+, to specify additional configure options to pass 102 to CMake. By default, empty. A number of common CMake options are 103 set by the +cmake-package+ infrastructure; so it is normally not 104 necessary to set them in the package's +*.mk+ file unless you want 105 to override them: 106 107** +CMAKE_BUILD_TYPE+ is driven by +BR2_ENABLE_RUNTIME_DEBUG+; 108** +CMAKE_INSTALL_PREFIX+; 109** +BUILD_SHARED_LIBS+ is driven by +BR2_STATIC_LIBS+; 110** +BUILD_DOC+, +BUILD_DOCS+ are disabled; 111** +BUILD_EXAMPLE+, +BUILD_EXAMPLES+ are disabled; 112** +BUILD_TEST+, +BUILD_TESTS+, +BUILD_TESTING+ are disabled. 113 114* +LIBFOO_BUILD_ENV+ and +LIBFOO_BUILD_OPTS+ to specify additional 115 environment variables, or command line options, to pass to the backend 116 at build time. 117 118* +LIBFOO_SUPPORTS_IN_SOURCE_BUILD = NO+ should be set when the package 119 cannot be built inside the source tree but needs a separate build 120 directory. 121 122* +LIBFOO_MAKE+, to specify an alternate +make+ command. This is 123 typically useful when parallel make is enabled in the configuration 124 (using +BR2_JLEVEL+) but that this feature should be disabled for 125 the given package, for one reason or another. By default, set to 126 +$(MAKE)+. If parallel building is not supported by the package, 127 then it should be set to +LIBFOO_MAKE=$(MAKE1)+. 128 129* +LIBFOO_MAKE_ENV+, to specify additional environment variables to 130 pass to make in the build step. These are passed before the +make+ 131 command. By default, empty. 132 133* +LIBFOO_MAKE_OPTS+, to specify additional variables to pass to make 134 in the build step. These are passed after the +make+ command. By 135 default, empty. 136 137* +LIBFOO_INSTALL_OPTS+ contains the make options used to 138 install the package to the host directory. By default, the value 139 is +install+, which is correct for most CMake packages. It is still 140 possible to override it. 141 142* +LIBFOO_INSTALL_STAGING_OPTS+ contains the make options used to 143 install the package to the staging directory. By default, the value 144 is +DESTDIR=$(STAGING_DIR) install/fast+, which is correct for most 145 CMake packages. It is still possible to override it. 146 147* +LIBFOO_INSTALL_TARGET_OPTS+ contains the make options used to 148 install the package to the target directory. By default, the value 149 is +DESTDIR=$(TARGET_DIR) install/fast+. The default value is correct 150 for most CMake packages, but it is still possible to override it if 151 needed. 152 153With the CMake infrastructure, all the steps required to build and 154install the packages are already defined, and they generally work well 155for most CMake-based packages. However, when required, it is still 156possible to customize what is done in any particular step: 157 158* By adding a post-operation hook (after extract, patch, configure, 159 build or install). See xref:hooks[] for details. 160 161* By overriding one of the steps. For example, even if the CMake 162 infrastructure is used, if the package +.mk+ file defines its own 163 +LIBFOO_CONFIGURE_CMDS+ variable, it will be used instead of the 164 default CMake one. However, using this method should be restricted 165 to very specific cases. Do not use it in the general case. 166