123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152 |
- // -*- mode:doc; -*-
- // vim: set syntax=asciidoc:
- === Infrastructure for CMake-based packages
- [[cmake-package-tutorial]]
- ==== +cmake-package+ tutorial
- First, let's see how to write a +.mk+ file for a CMake-based package,
- with an example :
- ------------------------
- 01: ################################################################################
- 02: #
- 03: # libfoo
- 04: #
- 05: ################################################################################
- 06:
- 07: LIBFOO_VERSION = 1.0
- 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
- 09: LIBFOO_SITE = http://www.foosoftware.org/download
- 10: LIBFOO_INSTALL_STAGING = YES
- 11: LIBFOO_INSTALL_TARGET = NO
- 12: LIBFOO_CONF_OPTS = -DBUILD_DEMOS=ON
- 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
- 14:
- 15: $(eval $(cmake-package))
- ------------------------
- On line 7, we declare the version of the package.
- On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended)
- and the location of the tarball on the Web. Buildroot will automatically
- download the tarball from this location.
- On line 10, we tell Buildroot to install the package to the staging
- directory. The staging directory, located in +output/staging/+
- is the directory where all the packages are installed, including their
- development files, etc. By default, packages are not installed to the
- staging directory, since usually, only libraries need to be installed in
- the staging directory: their development files are needed to compile
- other libraries or applications depending on them. Also by default, when
- staging installation is enabled, packages are installed in this location
- using the +make install+ command.
- On line 11, we tell Buildroot to not install the package to the
- target directory. This directory contains what will become the root
- filesystem running on the target. For purely static libraries, it is
- not necessary to install them in the target directory because they will
- not be used at runtime. By default, target installation is enabled; setting
- this variable to NO is almost never needed. Also by default, packages are
- installed in this location using the +make install+ command.
- On line 12, we tell Buildroot to pass custom options to CMake when it is
- configuring the package.
- On line 13, we declare our dependencies, so that they are built
- before the build process of our package starts.
- Finally, on line line 15, we invoke the +cmake-package+
- macro that generates all the Makefile rules that actually allows the
- package to be built.
- [[cmake-package-reference]]
- ==== +cmake-package+ reference
- The main macro of the CMake package infrastructure is
- +cmake-package+. It is similar to the +generic-package+ macro. The ability to
- have target and host packages is also available, with the
- +host-cmake-package+ macro.
- Just like the generic infrastructure, the CMake infrastructure works
- by defining a number of variables before calling the +cmake-package+
- macro.
- First, all the package metadata information variables that exist in
- the generic infrastructure also exist in the CMake infrastructure:
- +LIBFOO_VERSION+, +LIBFOO_SOURCE+, +LIBFOO_PATCH+, +LIBFOO_SITE+,
- +LIBFOO_SUBDIR+, +LIBFOO_DEPENDENCIES+, +LIBFOO_INSTALL_STAGING+,
- +LIBFOO_INSTALL_TARGET+.
- A few additional variables, specific to the CMake infrastructure, can
- also be defined. Many of them are only useful in very specific cases,
- typical packages will therefore only use a few of them.
- * +LIBFOO_SUBDIR+ may contain the name of a subdirectory inside the
- package that contains the main CMakeLists.txt file. This is useful,
- if for example, the main CMakeLists.txt file is not at the root of
- the tree extracted by the tarball. If +HOST_LIBFOO_SUBDIR+ is not
- specified, it defaults to +LIBFOO_SUBDIR+.
- * +LIBFOO_CONF_ENV+, to specify additional environment variables to
- pass to CMake. By default, empty.
- * +LIBFOO_CONF_OPTS+, to specify additional configure options to pass
- to CMake. By default, empty. A number of common CMake options are
- set by the +cmake-package+ infrastructure; so it is normally not
- necessary to set them in the package's +*.mk+ file unless you want
- to override them:
- ** +CMAKE_BUILD_TYPE+ is driven by +BR2_ENABLE_DEBUG+;
- ** +CMAKE_INSTALL_PREFIX+;
- ** +BUILD_SHARED_LIBS+ is driven by +BR2_STATIC_LIBS+;
- ** +BUILD_DOC+, +BUILD_DOCS+ are disabled;
- ** +BUILD_EXAMPLE+, +BUILD_EXAMPLES+ are disabled;
- ** +BUILD_TEST+, +BUILD_TESTS+, +BUILD_TESTING+ are disabled.
- * +LIBFOO_SUPPORTS_IN_SOURCE_BUILD = NO+ should be set when the package
- cannot be built inside the source tree but needs a separate build
- directory.
- * +LIBFOO_MAKE+, to specify an alternate +make+ command. This is
- typically useful when parallel make is enabled in the configuration
- (using +BR2_JLEVEL+) but that this feature should be disabled for
- the given package, for one reason or another. By default, set to
- +$(MAKE)+. If parallel building is not supported by the package,
- then it should be set to +LIBFOO_MAKE=$(MAKE1)+.
- * +LIBFOO_MAKE_ENV+, to specify additional environment variables to
- pass to make in the build step. These are passed before the +make+
- command. By default, empty.
- * +LIBFOO_MAKE_OPTS+, to specify additional variables to pass to make
- in the build step. These are passed after the +make+ command. By
- default, empty.
- * +LIBFOO_INSTALL_STAGING_OPTS+ contains the make options used to
- install the package to the staging directory. By default, the value
- is +DESTDIR=$(STAGING_DIR) install+, which is correct for most
- CMake packages. It is still possible to override it.
- * +LIBFOO_INSTALL_TARGET_OPTS+ contains the make options used to
- install the package to the target directory. By default, the value
- is +DESTDIR=$(TARGET_DIR) install+. The default value is correct
- for most CMake packages, but it is still possible to override it if
- needed.
- With the CMake infrastructure, all the steps required to build and
- install the packages are already defined, and they generally work well
- for most CMake-based packages. However, when required, it is still
- possible to customize what is done in any particular step:
- * By adding a post-operation hook (after extract, patch, configure,
- build or install). See xref:hooks[] for details.
- * By overriding one of the steps. For example, even if the CMake
- infrastructure is used, if the package +.mk+ file defines its own
- +LIBFOO_CONFIGURE_CMDS+ variable, it will be used instead of the
- default CMake one. However, using this method should be restricted
- to very specific cases. Do not use it in the general case.
|