svn commit: r52862 - in head/en_US.ISO8859-1/books/porters-handbook: special uses

[Tobias Kortkamp]

Author: tobik (ports committer)
Date: Wed Mar 13 07:51:40 2019
New Revision: 52862
URL: https://svnweb.freebsd.org/changeset/doc/52862

Log:
  Porter's Handbook: Update USES=cmake description
  
  - outsource is no longer a valid argument
  - Document noninja, insource
  
  Approved by:	mat, tcberner
  Differential Revision:	https://reviews.freebsd.org/D19567

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
  head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Tue Mar 12 17:42:24 2019	(r52861)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Wed Mar 13 07:51:40 2019	(r52862)
@@ -635,9 +635,7 @@ IGNORE=	may not be redistributed because of licensing 
       <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>
+	define <literal>USES= cmake</literal>.</para>
 
       <table frame="none" xml:id="using-cmake-variables">
 	<title>Variables for Ports That Use
@@ -756,9 +754,10 @@ IGNORE=	may not be redistributed because of licensing 
 
       <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 the
-	<literal>:outsource</literal> suffix.  When enabled,
-	<varname>CONFIGURE_WRKSRC</varname>,
+	out-of-source build for a port is the default setting.
+	An in-source build can be requested by using the
+	<literal>:insource</literal> suffix.  With out-of-source
+	builds, <varname>CONFIGURE_WRKSRC</varname>,
 	<varname>BUILD_WRKSRC</varname> and
 	<varname>INSTALL_WRKSRC</varname> will be set to
 	<literal>${WRKDIR}/.build</literal> and this
@@ -776,7 +775,7 @@ IGNORE=	may not be redistributed because of licensing 
 	  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
+	<programlisting>USES=			cmake
 CMAKE_SOURCE_PATH=	${WRKSRC}/subproject</programlisting>
       </example>
 
@@ -3214,7 +3213,7 @@ USE_QT=	buildtools_build</programlisting>
 	<title><varname>USE_KDE</varname> Example</title>
 
 	<para>This is a simple example for a KDE 4 port.
-	  <literal>USES= cmake:outsource</literal> instructs the
+	  <literal>USES= cmake</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).
@@ -3228,7 +3227,7 @@ USE_QT=	buildtools_build</programlisting>
 	  Qt 4 components, specify them in
 	  <varname>USE_QT</varname>.</para>
 
-	<programlisting>USES=		cmake:outsource kde:4 qt:4
+	<programlisting>USES=		cmake kde:4 qt:4
 USE_KDE=	kdelibs kdeprefix automoc4
 USE_QT=		moc_build qmake_build rcc_build uic_build</programlisting>
       </example>
@@ -3287,7 +3286,7 @@ USE_QT=		moc_build qmake_build rcc_build uic_build</pr
 	LXQt libraries.  Required LXQt components and
 	other dependencies can be determined from the
 	configure log.</para>
-      <programlisting>USES=	cmake:outsource lxqt qt:5 tar:xz
+      <programlisting>USES=	cmake lxqt qt:5 tar:xz
 USE_QT=		core dbus widgets buildtools_build qmake_build
 USE_LXQT=	buildtools libfmqt</programlisting>
     </example>

Modified: head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml	Tue Mar 12 17:42:24 2019	(r52861)
+++ head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml	Wed Mar 13 07:51:40 2019	(r52862)
@@ -263,15 +263,31 @@
   <sect1 xml:id="uses-cmake">
     <title><literal>cmake</literal></title>
 
-    <para>Possible arguments: (none), <literal>outsource</literal>,
-      <literal>run</literal></para>
+    <para>Possible arguments: (none), <literal>insource</literal>,
+      <literal>noninja</literal>, <literal>run</literal></para>
 
     <para>Uses <application>CMake</application> for configuring and
-      building.  With the <literal>outsource</literal> argument, an
-      out-of-source build will be performed.  With the
-      <literal>run</literal> argument, a run-time dependency is
-      registered.  For more information see <xref
-	linkend="using-cmake"/>.</para>
+      building.</para>
+
+    <para>By default an out-of-source build is performed, leaving the
+      sources in <varname>WRKSRC</varname> free from build artifacts.
+      With the <literal>insource</literal> argument, an in-source
+      build will be performed instead.  Setting it should be the
+      exception when a regular out-of-source build does not
+      work.</para>
+
+    <para>By default <application>Ninja</application> is used for
+      the build.  In some cases this does not work correctly.  With
+      the <literal>noninja</literal> argument, the build will
+      fallback to using regular <command>make</command> for builds.
+      It should only be used if a
+      <application>Ninja</application>-based build does not
+      work.</para>
+
+    <para>With the <literal>run</literal> argument, a run dependency
+      is registered in addition to a build dependency.</para>
+
+    <para>For more information see <xref linkend="using-cmake"/>.</para>
   </sect1>
 
   <sect1 xml:id="uses-compiler">