Commit 5bd96726 authored by Bjørn Forsman's avatar Bjørn Forsman Committed by Peter Korsgaard
Browse files

doc: add CMAKETARGETS documentation 



Signed-off-by: default avatarBjørn Forsman <bjorn.forsman@gmail.com>
Acked-by: default avatarThomas Petazzoni <thomas.petazzoni@free-electrons.com>
Signed-off-by: default avatarPeter Korsgaard <jacmet@sunsite.dk>
parent bc1acec1

docs/buildroot.html

+147 −4
Original line number Diff line number Diff line
@@ -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: #############################################################