Date: Wed, 20 Mar 2013 15:56:25 GMT From: Max Brazhnikov <makc@FreeBSD.org> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/177141: [porters-handbook]: document CMake usage Message-ID: <201303201556.r2KFuPMO056454@red.freebsd.org> Resent-Message-ID: <201303201600.r2KG02kw029719@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201303201556.r2KFuPMO056454>