From mboxrd@z Thu Jan 1 00:00:00 1970 From: =?UTF-8?q?Bj=C3=B8rn=20Forsman?= Date: Sat, 15 Jan 2011 21:53:27 +0100 Subject: [Buildroot] [PATCH v2 3/4] doc: add CMAKETARGETS documentation In-Reply-To: <1295124808-5649-1-git-send-email-bjorn.forsman@gmail.com> References: <1295124808-5649-1-git-send-email-bjorn.forsman@gmail.com> Message-ID: <1295124808-5649-4-git-send-email-bjorn.forsman@gmail.com> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: buildroot@busybox.net Signed-off-by: Bj?rn Forsman --- docs/buildroot.html | 151 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 files changed, 147 insertions(+), 4 deletions(-) diff --git a/docs/buildroot.html b/docs/buildroot.html index 9d6e835..a5444cc 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: #############################################################
-- 
1.7.1