Date: Sun, 24 Mar 2013 18:16:17 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r41304 - head/en_US.ISO8859-1/books/porters-handbook Message-ID: <201303241816.r2OIGHtX072558@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201303241816.r2OIGHtX072558>