From ee0ba4e85b08c9edefc05dfed596ff479348ca5e Mon Sep 17 00:00:00 2001
From: Mathieu Arnold <mat@FreeBSD.org>
Date: Tue, 2 May 2017 17:05:20 +0000
Subject: [PATCH] Keep up-to-date with changes in existing USES.

Sponsored by:	Absolight
---
 .../books/porters-handbook/uses/chapter.xml   | 121 +++++++++++-------
 1 file changed, 72 insertions(+), 49 deletions(-)

diff --git a/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
index c05be47a82..b4903277c0 100644
--- a/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
@@ -8,19 +8,19 @@
 
 <!--
 
-  Document up-to date with r416240 revision of the ports tree.
+  Document up-to date with r439950 revision of the ports tree.
 
   This file documents the values of the USES make variable.  The
   format is easy to grasp from the already-added entries below (or use
   this scheme below as a skeleton):
 
-<sect1 xml:id="uses-FEATURE">
-  <title><literal>FEATURE</literal></title>
+  <sect1 xml:id="uses-FEATURE">
+    <title><literal>FEATURE</literal></title>
 
-  <para>Possible arguments: ARGUMENTS</para>
+    <para>Possible arguments: ARGUMENTS</para>
 
-  <para>DESCRIPTION</para>
-</sect1>
+    <para>DESCRIPTION</para>
+  </sect1>
 
 -->
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink=
@@ -407,11 +407,14 @@
     <title><literal>cran</literal></title>
 
     <para>Possible arguments: (none),
-      <literal>auto-plist</literal></para>
+      <literal>auto-plist</literal>,
+      <literal>compiles</literal></para>
 
     <para>Uses the Comprehensive R Archive Network.  Specify
       <varname>auto-plist</varname> to automatically generate
-      <filename>pkg-plist</filename>.</para>
+      <filename>pkg-plist</filename>.  Specify
+      <literal>compiles</literal> if the port has code that need to be
+      compiled.</para>
   </sect1>
 
   <sect1 xml:id="uses-desktop-file-utils">
@@ -496,14 +499,14 @@
   <sect1 xml:id="uses-drupal">
     <title><literal>drupal</literal></title>
 
-    <para>Possible arguments: <literal>6</literal>,
+    <para>Possible arguments:
       <literal>7</literal>, <literal>module</literal>,
       <literal>theme</literal></para>
 
     <para>Automate installation of a port that is a
       <application>Drupal</application> theme or module.  Use with the
       version of Drupal that the port is expecting.  For example,
-      <literal>USES=drupal:6,module</literal> says that this port
+      <literal>USES=drupal:7,module</literal> says that this port
       creates a Drupal 6 module.  A Drupal 7 theme can be specified
       with <literal>USES=drupal:7,theme</literal>.</para>
   </sect1>
@@ -711,6 +714,11 @@
       should be listed in <varname>USE_GNOME</varname>.  The available
       components are:</para>
 
+    <!--
+      From any port with USES=gnome, run:
+      $ make -V '${_USE_GNOME_ALL:O:u:C,.*,<listitem> <para><literal>&</literal></para> </listitem> ,}'
+      replace all spaces with new lines and reindent.
+      -->
     <itemizedlist>
       <listitem>
 	<para><literal>atk</literal></para>
@@ -720,10 +728,6 @@
 	<para><literal>atkmm</literal></para>
       </listitem>
 
-      <listitem>
-	<para><literal>atspi</literal></para>
-      </listitem>
-
       <listitem>
 	<para><literal>cairo</literal></para>
       </listitem>
@@ -744,10 +748,6 @@
 	<para><literal>evolutiondataserver3</literal></para>
       </listitem>
 
-      <listitem>
-	<para><literal>gal2</literal></para>
-      </listitem>
-
       <listitem>
 	<para><literal>gconf2</literal></para>
       </listitem>
@@ -804,10 +804,6 @@
 	<para><literal>gnomesharp20</literal></para>
       </listitem>
 
-      <listitem>
-	<para><literal>gnomespeech</literal></para>
-      </listitem>
-
       <listitem>
 	<para><literal>gnomevfs2</literal></para>
       </listitem>
@@ -852,10 +848,6 @@
 	<para><literal>gtkmm30</literal></para>
       </listitem>
 
-      <listitem>
-	<para><literal>gtksharp10</literal></para>
-      </listitem>
-
       <listitem>
 	<para><literal>gtksharp20</literal></para>
       </listitem>
@@ -904,10 +896,6 @@
 	<para><literal>libbonoboui</literal></para>
       </listitem>
 
-      <listitem>
-	<para><literal>libgda4</literal></para>
-      </listitem>
-
       <listitem>
 	<para><literal>libgda5</literal></para>
       </listitem>
@@ -916,10 +904,6 @@
 	<para><literal>libgda5-ui</literal></para>
       </listitem>
 
-      <listitem>
-	<para><literal>libgdamm</literal></para>
-      </listitem>
-
       <listitem>
 	<para><literal>libgdamm5</literal></para>
       </listitem>
@@ -1715,11 +1699,14 @@ GSSAPI_NONE_CONFIGURE_ON=	--without-gssapi</programlisting>
   <sect1 xml:id="uses-localbase">
     <title><literal>localbase</literal></title>
 
-    <para>Possible arguments: (none)</para>
+    <para>Possible arguments: (none), <literal>ldflags</literal></para>
 
     <para>Ensures that libraries from dependencies in
       <varname>LOCALBASE</varname> are used instead of the ones from
-      the base system.  Ports that depend on libraries that are also
+      the base system.  Specify <literal>ldflags</literal> to add
+      <literal>-L${LOCALBASE}/lib</literal> to
+      <varname>LDFLAGS</varname> instead of <varname>LIBS</varname>.
+      Ports that depend on libraries that are also
       present in the base system should use this.  It is also used
       internally by a few other <varname>USES</varname>.</para>
   </sect1>
@@ -1853,6 +1840,10 @@ GSSAPI_NONE_CONFIGURE_ON=	--without-gssapi</programlisting>
 	<para><literal>polkit</literal></para>
       </listitem>
 
+      <listitem>
+	<para><literal>session</literal></para>
+      </listitem>
+
       <listitem>
 	<para><literal>settingsdaemon</literal></para>
       </listitem>
@@ -1899,7 +1890,9 @@ USE_MATE=	menus:build intlhack</programlisting>
       Fall back to the default version, MySQL-5.6.  The possible
       versions are <literal>55</literal>, <literal>55m</literal>,
       <literal>55p</literal>, <literal>56</literal>,
-      <literal>56p</literal>, <literal>57</literal>,
+      <literal>56p</literal>, <literal>56w</literal>,
+      <literal>57</literal>, <literal>57p</literal>,
+      <literal>80</literal>,
       <literal>100m</literal>, and <literal>101m</literal>.  The
       <literal>m</literal> and <literal>p</literal> suffixes are for
       the <application>MariaDB</application> and
@@ -1920,11 +1913,23 @@ USE_MATE=	menus:build intlhack</programlisting>
   <sect1 xml:id="uses-mono">
     <title><literal>mono</literal></title>
 
-    <para>Possible arguments: (none)</para>
+    <para>Possible arguments: (none), <literal>nuget</literal></para>
 
     <para>Adds a dependency on the <application>Mono</application>
       (currently only C#) framework by setting the appropriate
       dependencies.</para>
+
+    <para>Specify <literal>nuget</literal> when the port uses nuget
+      packages.  <varname>NUGET_DEPENDS</varname> needs to be set with
+      the names and versions of the nuget packages in the format
+      <literal><replaceable>name</replaceable>=<replaceable>version</replaceable></literal>.
+      An optional package origin can be added using
+      <literal><replaceable>name</replaceable>=<replaceable>version</replaceable>:<replaceable>origin</replaceable></literal>.</para>
+
+    <para>The helper target, <buildtarget>buildnuget</buildtarget>,
+      will output the content of the <varname>NUGET_DEPENDS</varname>
+      based on the provided
+      <filename>packages.config</filename>.</para>
   </sect1>
 
   <sect1 xml:id="uses-motif">
@@ -1954,9 +1959,8 @@ USE_MATE=	menus:build intlhack</programlisting>
 
     <para>Possible arguments: (none)</para>
 
-    <para>Uses <application>ninja</application> to build the port.
-      End users can set <varname>NINJA_VERBOSE</varname> for verbose
-      output.</para>
+    <para>Uses <application>ninja</application> to build the
+      port.</para>
   </sect1>
 
   <sect1 xml:id="uses-objc">
@@ -1996,9 +2000,9 @@ USE_MATE=	menus:build intlhack</programlisting>
       hierarchy.  For example, it fixes the installation directory
       of <command>pkgconfig</command>'s <filename>.pc</filename> files
       to <filename>${PREFIX}/libdata/pkgconfig</filename>.  If
-      the port uses <command>automake</command>, set
-      <varname>PATHFIX_MAKEFILEIN</varname> to
-      <filename>Makefile.am</filename> if needed.</para>
+      the port uses <literal>USES=autoreconf</literal>,
+      <filename>Makefile.am</filename> will be added to
+      <varname>PATHFIX_MAKEFILEIN</varname> automatically.</para>
 
     <para>If the port <link
 	linkend="uses-cmake"><literal>USES=cmake</literal></link> it
@@ -2095,7 +2099,8 @@ USE_MATE=	menus:build intlhack</programlisting>
       <literal>ext</literal>, <literal>zend</literal>,
       <literal>build</literal>, <literal>cli</literal>,
       <literal>cgi</literal>, <literal>mod</literal>,
-      <literal>web</literal>, <literal>embed</literal></para>
+      <literal>web</literal>, <literal>embed</literal>,
+      <literal>pecl</literal></para>
 
     <para>Provide support for <application>PHP</application>.  Add a
       runtime dependency on the default PHP version, <package
@@ -2174,6 +2179,15 @@ USE_MATE=	menus:build intlhack</programlisting>
 	    <application>PHP</application>.</para>
 	</listitem>
       </varlistentry>
+
+      <varlistentry>
+	<term><literal>pecl</literal></term>
+	<listitem>
+	  <para>Provide defaults for fetching
+	    <application>PHP</application> extensions from the PECL
+	    repository.</para>
+	</listitem>
+      </varlistentry>
     </variablelist>
 
     <para>Variables are used to specify which
@@ -2583,12 +2597,20 @@ USE_PYQT=	core doc_build designer_run</programlisting>
       interpreters, most notably <filename>/usr/bin/perl</filename>
       and <filename>/bin/bash</filename>.  The shebagngfix macro fixes
       shebang lines in scripts listed in
-      <varname>SHEBANG_FILES</varname>.  The shebangfix macro is run
-      from <literal>${WRKSRC}</literal>, so it can contain paths that
+      <varname>SHEBANG_REGEX</varname>,
+      <varname>SHEBANG_GLOB</varname>, or
+      <varname>SHEBANG_FILES</varname>.
+      <varname>SHEBANG_REGEX</varname> contains an extended regular
+      expressions, and is used with the <literal>-iregex</literal>
+      argument of &man.find.1;.  <varname>SHEBANG_GLOB</varname>
+      contains a pattern used with the <literal>-name</literal>
+      argument of &man.find.1;.  The shebangfix macro is run
+      from <literal>${WRKSRC}</literal>, so
+      <varname>SHEBANG_FILES</varname> can contain paths that
       are relative to <literal>${WRKSRC}</literal>.  It can also deal
       with absolute paths if files outside of
       <literal>${WRKSRC}</literal> require patching.  For
-      example:</para>
+      example when using <varname>SHEBANG_FILES</varname>:</para>
 
     <programlisting>USES=	shebangfix
 SHEBANG_FILES=	scripts/foobar.pl scripts/*.sh</programlisting>
@@ -2636,7 +2658,8 @@ SHEBANG_FILES=	scripts/foobar.pl scripts/*.sh</programlisting>
 	    <varname><replaceable>interp</replaceable>_OLD_CMD</varname>:
 	    <literal>"/usr/bin/env <replaceable>interp</replaceable>"
 	      /bin/<replaceable>interp</replaceable>
-	      /usr/bin/<replaceable>interp</replaceable></literal>.</para>
+	      /usr/bin/<replaceable>interp</replaceable>
+	      /usr/local/bin/<replaceable>interp</replaceable></literal>.</para>
 	</listitem>
       </varlistentry>
     </variablelist>