docs/177141: [porters-handbook]: document CMake usage
Max Brazhnikov
makc at FreeBSD.org
Wed Mar 20 16:00:03 UTC 2013
>Number: 177141
>Category: docs
>Synopsis: [porters-handbook]: document CMake usage
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: update
>Submitter-Id: current-users
>Arrival-Date: Wed Mar 20 16:00:02 UTC 2013
>Closed-Date:
>Last-Modified:
>Originator: Max Brazhnikov
>Release:
>Organization:
>Environment:
>Description:
Add documentation for cmake usage in ports.
http://people.freebsd.org/~makc/patches/ph-cmake.diff
>How-To-Repeat:
>Fix:
Patch attached with submission follows:
Index: book.xml
===================================================================
--- book.xml (revision 41270)
+++ book.xml (working copy)
@@ -5422,6 +5422,106 @@
</table>
</sect2>
+ <sect2 id="using-cmake">
+ <title>Using <command>cmake</command></title>
+
+ <para>If your port uses <application>CMake</application>,
+ define <literal>USES= cmake[:outsource]</literal>.</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> if <makevar>WITH_DEBUG</makevar>
+ is not set, otherwise <literal>Debug</literal>.
+ </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 "-O2 -g" and "-Os -DNDEBUG"
+ 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 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 port for such 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
+ out-of-source way of buildling. The ouf-of-source build for a port
+ can be requested by using <literal>:outsource</literal> suffix. In
+ this case <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 +7002,10 @@
<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> — configuration
+ tool widely spread among 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 +7016,7 @@
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>
Index: uses.xml
===================================================================
--- uses.xml (revision 41270)
+++ uses.xml (working copy)
@@ -30,6 +30,16 @@
</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 <literal>outsource</literal> argument the
+ 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
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list