svn commit: r41304 - head/en_US.ISO8859-1/books/porters-handbook
Warren Block
wblock at FreeBSD.org
Sun Mar 24 18:16:17 UTC 2013
Author: wblock
Date: Sun Mar 24 18:16:16 2013
New Revision: 41304
URL: http://svnweb.freebsd.org/changeset/doc/41304
Log:
Document CMake usage. Slightly modified version of patch submitted with
PR.
PR: docs/177141
Submitted by: Max Brazhnikov <makc at FreeBSD.org>
Modified:
head/en_US.ISO8859-1/books/porters-handbook/book.xml
head/en_US.ISO8859-1/books/porters-handbook/uses.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/book.xml Sun Mar 24 13:35:32 2013 (r41303)
+++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Sun Mar 24 18:16:16 2013 (r41304)
@@ -5422,6 +5422,110 @@ IGNORE= may not be redistributed because
</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>${CONFIGURE_ENV}</literal>.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>CMAKE_SOURCE_PATH</makevar></entry>
+ <entry>Path to the source directory. Default is
+ <literal>${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>${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= ${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> — 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>
Modified: head/en_US.ISO8859-1/books/porters-handbook/uses.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/uses.xml Sun Mar 24 13:35:32 2013 (r41303)
+++ head/en_US.ISO8859-1/books/porters-handbook/uses.xml Sun Mar 24 18:16:16 2013 (r41304)
@@ -30,10 +30,19 @@
</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>
More information about the svn-doc-head
mailing list