svn commit: r53991 - head/en_US.ISO8859-1/books/porters-handbook/special

[Tobias Kortkamp]

Author: tobik (ports committer)
Date: Wed Mar 18 12:29:36 2020
New Revision: 53991
URL: https://svnweb.freebsd.org/changeset/doc/53991

Log:
  Porter's Handbook: Document CARGO_FEATURES==--no-default-features
  
  Approved by:	bcr
  Differential Revision:	https://reviews.freebsd.org/D23999

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/special/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	Wed Mar 18 08:48:01 2020	(r53990)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Wed Mar 18 12:29:36 2020	(r53991)
@@ -857,7 +857,14 @@ CMAKE_OFF=	VAR3</programlisting>
 	      <entry><varname>CARGO_FEATURES</varname></entry>
 	      <entry></entry>
 	      <entry>List of application features to build (space
-		separated list).</entry>
+		separated list).  To deactivate all default
+		features add the special token
+		<literal>--no-default-features</literal>
+		to <varname>CARGO_FEATURES</varname>.  Manually
+		passing it to <varname>CARGO_BUILD_ARGS</varname>,
+		<varname>CARGO_INSTALL_ARGS</varname>, and
+		<varname>CARGO_TEST_ARGS</varname> is not
+		needed.</entry>
 	    </row>
 
 	    <row>
@@ -1127,6 +1134,35 @@ rust/crates/atty-0.2.9.tar.gz                 100% of 
 	  <literal>yaml</literal> features:</para>
 
 	<programlisting>CARGO_FEATURES=	json yaml</programlisting>
+      </example>
+
+      <example xml:id="cargo-ex4">
+	<title>Encoding Application Features As Port Options</title>
+
+	<para>An example <literal>[features]</literal> section
+	  in <filename>Cargo.toml</filename> could look like
+	  this:</para>
+
+	<programlisting>[features]
+pulseaudio_backend = ["librespot-playback/pulseaudio-backend"]
+portaudio_backend = ["librespot-playback/portaudio-backend"]
+default = ["pulseaudio_backend"]</programlisting>
+
+	<para><literal>pulseaudio_backend</literal> is a default
+	  feature.  It is always enabled unless we explicitly turn
+	  off default features by adding
+	  <literal>--no-default-features</literal> to
+	  <varname>CARGO_FEATURES</varname>.  Here we turn the
+	  <literal>portaudio_backend</literal>
+	  and <literal>pulseaudio_backend</literal> features into
+	  port options:</para>
+
+	<programlisting>CARGO_FEATURES=	--no-default-features
+
+OPTIONS_DEFINE=	PORTAUDIO PULSEAUDIO
+
+PORTAUDIO_VARS=		CARGO_FEATURES+=portaudio_backend
+PULSEAUDIO_VARS=	CARGO_FEATURES+=pulseaudio_backend</programlisting>
       </example>
 
       <example xml:id="cargo-ex3">