Document CMake usage. Slightly modified version of patch submitted with

PR.

PR:		docs/177141
Submitted by:	Max Brazhnikov <makc@FreeBSD.org>
This commit is contained in:
Warren Block 2013-03-24 18:16:16 +00:00
parent 1c082439fd
commit e44ea6eb08
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=41304
2 changed files with 120 additions and 6 deletions
en_US.ISO8859-1/books/porters-handbook

View file

@ -5422,6 +5422,110 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep
</table>
</sect2>
<sect2 id="using-cmake">
<title>Using <command>cmake</command></title>
<para>For ports that use <application>CMake</application>,
define <literal>USES= cmake</literal>, or
<literal>USES= cmake:outsource</literal> to build in a
separate directory (see below).</para>
<table frame="none">
<title>Variables for Ports That Use
<command>cmake</command></title>
<tgroup cols="2">
<thead>
<row>
<entry>Variable</entry>
<entry>Means</entry>
</row>
</thead>
<tbody>
<row>
<entry><makevar>CMAKE_ARGS</makevar></entry>
<entry>Port specific <application>CMake</application>
flags to be passed to the <command>cmake</command>
binary.</entry>
</row>
<row>
<entry><makevar>CMAKE_BUILD_TYPE</makevar></entry>
<entry>Type of build (<application>CMake</application>
predefined build profiles). Default is
<literal>Release</literal>, or
<literal>Debug</literal>if
<makevar>WITH_DEBUG</makevar> is set.</entry>
</row>
<row>
<entry><makevar>CMAKE_ENV</makevar></entry>
<entry>Environment variables to be set for
<command>cmake</command> binary. Default is
<literal>&dollar;{CONFIGURE_ENV}</literal>.</entry>
</row>
<row>
<entry><makevar>CMAKE_SOURCE_PATH</makevar></entry>
<entry>Path to the source directory. Default is
<literal>&dollar;{WRKSRC}</literal>.</entry>
</row>
</tbody>
</tgroup>
</table>
<para><application>CMake</application> supports the following
build profiles: <literal>Debug</literal>,
<literal>Release</literal>,
<literal>RelWithDebInfo</literal> and
<literal>MinSizeRel</literal>. <literal>Debug</literal> and
<literal>Release</literal> profiles respect system
<literal>*FLAGS</literal>, <literal>RelWithDebInfo</literal>
and <literal>MinSizeRel</literal> will set
<makevar>CFLAGS</makevar> to <literal>-O2 -g</literal> and
<literal>-Os -DNDEBUG</literal> correspondingly. The
lower-cased value of <makevar>CMAKE_BUILD_TYPE</makevar> is
exported to the <makevar>PLIST_SUB</makevar> and should be
used if port installs <literal>*.cmake</literal> files
depending on the build type (see <filename
role="package">deskutils/strigi</filename> for an
example). Please note that some projects may define their
own build profiles and/or force particular build type by
setting <literal>CMAKE_BUILD_TYPE</literal> in
<filename>CMakeLists.txt </filename> files. In order to
make a port for such a project respect
<makevar>CFLAGS</makevar> and <makevar>WITH_DEBUG</makevar>,
the <literal>CMAKE_BUILD_TYPE</literal> definitions must be
removed from those files.</para>
<para>Most <application>CMake</application>-based projects
support an out-of-source method of building. The
out-of-source build for a port can be requested by using
<literal>:outsource</literal> suffix. When enabled,
<makevar>CONFIGURE_WRKSRC</makevar>,
<makevar>BUILD_WRKSRC</makevar> and
<makevar>INSTALL_WRKSRC</makevar> will be set to
<literal>&dollar;{WRKDIR}/.build</literal> and this
directory will be used to keep all files generated during
configuration and build stages, leaving the source directory
intact.</para>
<example id="using-cmake-example">
<title><literal>USES= cmake</literal> Example</title>
<para>The following snippet demonstrates the use of
<application>CMake</application> for a port.
<makevar>CMAKE_SOURCE_PATH</makevar> is not usually
required, but can be set when the sources are not located
in the top directory, or if only a subset of the project
is intended to be built by the port.</para>
<programlisting>USES= cmake:outsource
CMAKE_SOURCE_PATH= &dollar;{WRKSRC}/subproject</programlisting>
</example>
</sect2>
<sect2 id="using-scons">
<title>Using <command>scons</command></title>
@ -6902,9 +7006,10 @@ do-configure:
<title><makevar>USE_KDE4</makevar> Example</title>
<para>This is a simple example for a KDE 4 port.
<makevar>USE_CMAKE</makevar> instructs the port to utilize
<application>CMake</application> &mdash; configuration
tool widely spread among KDE 4 projects.
<literal>USES= cmake:outsource</literal> instructs the
port to utilize <application>CMake</application>, a
configuration tool widely used by KDE 4 projects (see
<xref linkend="using-cmake"/> for detailed usage).
<makevar>USE_KDE4</makevar> brings dependency on KDE
libraries and makes port using
<command>automoc4</command> at build stage.
@ -6915,7 +7020,7 @@ do-configure:
Qt 4 components, they should be specified in
<makevar>USE_QT4</makevar>.</para>
<programlisting>USE_CMAKE= yes
<programlisting>USES= cmake:outsource
USE_KDE4= kdelibs kdeprefix automoc4
USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting>
</example>

View file

@ -29,11 +29,20 @@
dependencies.</entry>
</row>
<row>
<entry><literal>cmake</literal></entry>
<entry>none, <literal>outsource</literal></entry>
<entry>The port will use <application>CMake</application> for configuring
and building. With the <literal>outsource</literal> argument, an
out-of-source build will be performed. For more information see
<xref linkend="using-cmake"/>.
</entry>
</row>
<row>
<entry><literal>fuse</literal></entry>
<entry>none</entry>
<entry>Implies the port will depend on the FUSE library and handle the
the dependency on the kernel module depending on the version of
<entry>Implies the port will depend on the FUSE library and handle the the dependency on the kernel module depending on the version of
&os;.
</entry>
</row>