From 5bd96726f37f56d66f82538a7cd470a920bfba18 Mon Sep 17 00:00:00 2001 From: Bjørn Forsman Date: Wed, 26 Jan 2011 22:18:44 +0100 Subject: doc: add CMAKETARGETS documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Bjørn Forsman Acked-by: Thomas Petazzoni Signed-off-by: Peter Korsgaard --- docs/buildroot.html | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 147 insertions(+), 4 deletions(-) (limited to 'docs/buildroot.html') diff --git a/docs/buildroot.html b/docs/buildroot.html index 9d6e835f6..a5444cc42 100644 --- a/docs/buildroot.html +++ b/docs/buildroot.html @@ -756,6 +756,8 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
  • Makefile for generic packages : reference
  • Makefile for autotools-based packages : tutorial
  • Makefile for autotools-based packages : reference
    • +
  • Makefile for CMake-based packages : tutorial
    • +
  • Makefile for CMake-based packages : reference
  • Manual Makefile : tutorial
    • @@ -1331,13 +1333,154 @@ LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP general case. +

    Makefile for CMake-based packages : 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: LIBFOO_VERSION = 1.0
+07: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
+08: LIBFOO_SITE = http://www.foosoftware.org/download
+09: LIBFOO_INSTALL_STAGING = YES
+10: LIBFOO_INSTALL_TARGET = YES
+11: LIBFOO_CONF_OPT = -DBUILD_DEMOS=ON
+12: LIBFOO_DEPENDENCIES = libglib2 host-pkg-config
+13:
+14: $(eval $(call CMAKETARGETS,package,libfoo))
+
    + +

    On line 6, we declare the version of the package.

    + +

    On line 7 and 8, we declare the name of the tarball and the location + of the tarball on the Web. Buildroot will automatically download the + tarball from this location.

    + +

    On line 9, 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 10, we tell Buildroot to also install the package to the + target directory. This directory contains what will become the root + filesystem running on the target. Usually, we try not to install header + files and to install stripped versions of the binary. By default, target + installation is enabled, so in fact, this line is not strictly + necessary. Also by default, packages are installed in this location + using the make install command.

    + +

    On line 11, we tell Buildroot to pass custom options to CMake when it is + configuring the package.

    + +

    On line 12, we declare our dependencies, so that they are built + before the build process of our package starts.

    + +

    Finally, on line line 14, we invoke the CMAKETARGETS + macro that generates all the Makefile rules that actually allows the + package to be built.

    + +

    Makefile for CMake packages : reference

    + +

    The main macro of the CMake package infrastructure is + CMAKETARGETS. It has the same number of arguments and the + same semantic as the GENTARGETS macro, which is the main + macro of the generic package infrastructure. For CMake packages, the + ability to have target and host packages is also available.

    + +

    Just like the generic infrastructure, the CMake infrastructure + works by defining a number of variables before calling the + CMAKETARGETS 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_OPT, to specify additional configure + options to pass to CMake. By default, empty.
      • + +
    • 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_OPT, 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_OPT 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_OPT 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.
      • + +
    • LIBFOO_CLEAN_OPT contains the make options used to + clean the package. By default, the value is clean.
      • +
    + +

    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 the reference documentation of the generic + infrastructure 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.
      • +
    +

    Manual Makefile : tutorial

    NOTE: new manual makefiles should not be created, and existing - manual makefiles should be converted either to the generic - infrastructure or the autotools infrastructure. This section is only - kept to document the existing manual makefiles and to help understand - how they work.

    + manual makefiles should be converted either to the generic, autotools + or cmake infrastructure. This section is only kept to document the existing + manual makefiles and to help understand how they work.

     01: #############################################################
-- 
cgit v1.2.3