From nobody@FreeBSD.org  Wed Mar 20 15:56:25 2013
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115])
	by hub.freebsd.org (Postfix) with ESMTP id 84CDEC78
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 20 Mar 2013 15:56:25 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id 65DD5C4
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 20 Mar 2013 15:56:25 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.5/8.14.5) with ESMTP id r2KFuPXW056455
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 20 Mar 2013 15:56:25 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.5/8.14.5/Submit) id r2KFuPMO056454;
	Wed, 20 Mar 2013 15:56:25 GMT
	(envelope-from nobody)
Message-Id: <201303201556.r2KFuPMO056454@red.freebsd.org>
Date: Wed, 20 Mar 2013 15:56:25 GMT
From: Max Brazhnikov <makc@FreeBSD.org>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [porters-handbook]: document CMake usage
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         177141
>Category:       docs
>Synopsis:       [porters-handbook]: document CMake usage
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    wblock
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Wed Mar 20 16:00:02 UTC 2013
>Closed-Date:    Sun Mar 24 20:47:45 UTC 2013
>Last-Modified:  Sun Mar 24 23:20:00 UTC 2013
>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>&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 "-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>&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 +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> &mdash; configuration
-	    tool widely spread among KDE 4 projects.
+	    <literal>USES= cmake:outsource</literal> instructs the port
+	    to utilize <application>CMake</application> &mdash; 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:
Responsible-Changed-From-To: freebsd-doc->wblock 
Responsible-Changed-By: wblock 
Responsible-Changed-When: Sat Mar 23 22:04:39 UTC 2013 
Responsible-Changed-Why:  
Take. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=177141 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/177141: commit references a PR
Date: Sun, 24 Mar 2013 18:16:25 +0000 (UTC)

 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>&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>
 
 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>
 _______________________________________________
 svn-doc-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-doc-all
 To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->closed 
State-Changed-By: wblock 
State-Changed-When: Sun Mar 24 20:47:20 UTC 2013 
State-Changed-Why:  
Modified version of patch committed, thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=177141 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/177141: commit references a PR
Date: Sun, 24 Mar 2013 23:17:37 +0000 (UTC)

 Author: wblock
 Date: Sun Mar 24 23:17:28 2013
 New Revision: 41309
 URL: http://svnweb.freebsd.org/changeset/doc/41309
 
 Log:
   Add a missing space after a tag.
   
   PR:		docs/177141
   Submitted by:	Max Brazhnikov <makc@freebsd.org>
 
 Modified:
   head/en_US.ISO8859-1/books/porters-handbook/book.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 19:20:52 2013	(r41308)
 +++ head/en_US.ISO8859-1/books/porters-handbook/book.xml	Sun Mar 24 23:17:28 2013	(r41309)
 @@ -5464,7 +5464,7 @@ IGNORE=	may not be redistributed because
  		<entry>Type of build (<application>CMake</application>
  		  predefined build profiles).  Default is
  		  <literal>Release</literal>, or
 -		  <literal>Debug</literal>if
 +		  <literal>Debug</literal> if
  		  <makevar>WITH_DEBUG</makevar> is set.</entry>
  	      </row>
  
 _______________________________________________
 svn-doc-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-doc-all
 To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"
 
>Unformatted:
