buildroot

// -*- 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+.