NetCube-Systems-Austria/kumquat-buildroot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: add CMAKETARGETS documentation

Browse Source 
Signed-off-by: Bjørn Forsman <bjorn.forsman@gmail.com>
Acked-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Signed-off-by: Peter Korsgaard <jacmet@sunsite.dk>
This commit is contained in:
Bjørn Forsman 2011-01-26 22:18:44 +01:00 committed by Peter Korsgaard
parent bc1acec143
commit 5bd96726f3
1 changed files with 147 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
docs/buildroot.html
View File

@ -756,6 +756,8 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
<li><a href="#generic-reference">Makefile for generic packages : reference</a></li>
<li><a href="#autotools-tutorial">Makefile for autotools-based packages : tutorial</a></li>
<li><a href="#autotools-reference">Makefile for autotools-based packages : reference</a></li>
<li><a href="#cmake-tutorial">Makefile for CMake-based packages : tutorial</a></li>
<li><a href="#cmake-reference">Makefile for CMake-based packages : reference</a></li>
<li><a href="#manual-tutorial">Manual Makefile : tutorial</a></li>
</ul>
</li>
@ -1331,13 +1333,154 @@ LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
general case.</li>
</ul>
<h4 id="cmake-tutorial">Makefile for CMake-based packages : tutorial</h4>
<p>First, let's see how to write a <code>.mk</code> file for a CMake-based
package, with an example :</p>
<pre>
<span style="color: #000000">01:</span><span style="font-style: italic; color: #9A1900"> #############################################################</span>
<span style="color: #000000">02:</span><span style="font-style: italic; color: #9A1900"> #</span>
<span style="color: #000000">03:</span><span style="font-style: italic; color: #9A1900"> # libfoo</span>
<span style="color: #000000">04:</span><span style="font-style: italic; color: #9A1900"> #</span>
<span style="color: #000000">05:</span><span style="font-style: italic; color: #9A1900"> #############################################################</span>
<span style="color: #000000">06:</span><span style="color: #009900"> LIBFOO_VERSION</span> = 1.0
<span style="color: #000000">07:</span><span style="color: #009900"> LIBFOO_SOURCE</span> = libfoo-<span style="color: #009900">$(LIBFOO_VERSION)</span>.tar.gz
<span style="color: #000000">08:</span><span style="color: #009900"> LIBFOO_SITE</span> = http://www.foosoftware.org/download
<span style="color: #000000">09:</span><span style="color: #009900"> LIBFOO_INSTALL_STAGING</span> = YES
<span style="color: #000000">10:</span><span style="color: #009900"> LIBFOO_INSTALL_TARGET</span> = YES
<span style="color: #000000">11:</span><span style="color: #009900"> LIBFOO_CONF_OPT</span> = -DBUILD_DEMOS=ON
<span style="color: #000000">12:</span><span style="color: #009900"> LIBFOO_DEPENDENCIES</span> = libglib2 host-pkg-config
<span style="color: #000000">13:</span>
<span style="color: #000000">14:</span><span style="color: #009900"> $(eval $(call CMAKETARGETS,package,libfoo))</span>
</pre>
<p>On line 6, we declare the version of the package.</p>
<p>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.</p>
<p>On line 9, we tell Buildroot to install the package to the staging
directory. The staging directory, located in <code>output/staging/</code>
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 <code>make install</code> command.</p>
<p>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 <code>make install</code> command.</p>
<p>On line 11, we tell Buildroot to pass custom options to CMake when it is
configuring the package.</p>
<p>On line 12, we declare our dependencies, so that they are built
before the build process of our package starts.</p>
<p>Finally, on line line 14, we invoke the <code>CMAKETARGETS</code>
macro that generates all the Makefile rules that actually allows the
package to be built.</p>
<h4 id="cmake-reference">Makefile for CMake packages : reference</h4>
<p>The main macro of the CMake package infrastructure is
<code>CMAKETARGETS</code>. It has the same number of arguments and the
same semantic as the <code>GENTARGETS</code> 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.</p>
<p>Just like the generic infrastructure, the CMake infrastructure
works by defining a number of variables before calling the
<code>CMAKETARGETS</code> macro.</p>
<p>First, all the package metadata information variables that exist in the
generic infrastructure also exist in the CMake infrastructure:
<code>LIBFOO_VERSION</code>, <code>LIBFOO_SOURCE</code>,
<code>LIBFOO_PATCH</code>, <code>LIBFOO_SITE</code>,
<code>LIBFOO_SUBDIR</code>, <code>LIBFOO_DEPENDENCIES</code>,
<code>LIBFOO_INSTALL_STAGING</code>, <code>LIBFOO_INSTALL_TARGET</code>.</p>
<p>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.</p>
<ul>
<li><code>LIBFOO_SUBDIR</code> 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 <code>HOST_LIBFOO_SUBDIR</code>
is not specified, it defaults to <code>LIBFOO_SUBDIR</code>.</li>
<li><code>LIBFOO_CONF_ENV</code>, to specify additional environment
variables to pass to CMake. By default, empty.</li>
<li><code>LIBFOO_CONF_OPT</code>, to specify additional configure
options to pass to CMake. By default, empty.</li>
<li><code>LIBFOO_MAKE</code>, to specify an alternate <code>make</code>
command. This is typically useful when parallel make is enabled in
the configuration (using <code>BR2_JLEVEL</code>) but that this
feature should be disabled for the given package, for one reason or
another. By default, set to <code>$(MAKE)</code>. If parallel building
is not supported by the package, then it should be set to
<code>LIBFOO_MAKE=$(MAKE1)</code>.</li>
<li><code>LIBFOO_MAKE_ENV</code>, to specify additional environment
variables to pass to make in the build step. These are passed before
the <code>make</code> command. By default, empty.</li>
<li><code>LIBFOO_MAKE_OPT</code>, to specify additional variables to
pass to make in the build step. These are passed after the
<code>make</code> command. By default, empty.</li>
<li><code>LIBFOO_INSTALL_STAGING_OPT</code> contains the make options
used to install the package to the staging directory. By default, the
value is <code>DESTDIR=$$(STAGING_DIR) install</code>, which is
correct for most CMake packages. It is still possible to override
it.</li>
<li><code>LIBFOO_INSTALL_TARGET_OPT</code> contains the make options
used to install the package to the target directory. By default, the
value is <code>DESTDIR=$$(TARGET_DIR) install</code>. The default
value is correct for most CMake packages, but it is still possible
to override it if needed.</li>
<li><code>LIBFOO_CLEAN_OPT</code> contains the make options used to
clean the package. By default, the value is <code>clean</code>.</li>
</ul>
<p>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:</p>
<ul>
<li>By adding a post-operation hook (after extract, patch, configure,
build or install). See the reference documentation of the generic
infrastructure for details.</li>
<li>By overriding one of the steps. For example, even if the CMake
infrastructure is used, if the package <code>.mk</code> file defines its
own <code>LIBFOO_CONFIGURE_CMDS</code> 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.</li>
</ul>
<h4 id ="manual-tutorial">Manual Makefile : tutorial</h4>
<p><b>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.</b></p>
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.</b></p>
<pre>
01: #############################################################