Document BINARY_ALIAS in the Porter's Handbook

Approved by:	mat
Differential Revision:	https://reviews.freebsd.org/D15666

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

@@ -8104,4 +8104,54 @@ bind910</screen>
 	files.</para>
     </sect2>
   </sect1>
+
+  <sect1 xml:id="binary-alias">
+    <title>Use <varname>BINARY_ALIAS</varname> to Rename Commands
+      Instead of Patching the Build</title>
+
+    <para>When <varname>BINARY_ALIAS</varname> is defined it will
+      create symlinks of the given commands in a directory which
+      will be prepended to <varname>PATH</varname>.</para>
+
+    <para>Use it to substitute hardcoded commands the build phase
+      relies on without having to patch any build files.</para>
+
+    <example xml:id="binary-alias-ex1">
+      <title>Using <varname>BINARY_ALIAS</varname> to Make
+	<command>gsed</command> Available as
+	<command>sed</command></title>
+
+      <para>Some ports expect <command>sed</command> to behave like
+	<application>GNU sed</application> and use features that
+	&man.sed.1; does not provide.
+	<application>GNU sed</application> is available from
+	<package role="port">textproc/gsed</package> on &os;.</para>
+
+      <para>Use <varname>BINARY_ALIAS</varname> to substitute
+	<command>sed</command> with <command>gsed</command>
+	for the duration of the build:</para>
+
+      <programlisting>BUILD_DEPENDS=	gsed:textproc/gsed
+...
+BINARY_ALIAS=	sed=gsed</programlisting>
+    </example>
+
+    <example xml:id="binary-alias-ex2">
+      <title>Using <varname>BINARY_ALIAS</varname> to Provide Aliases
+	for Hardcoded <command>python3</command> Commands</title>
+
+      <para>A port that has a hardcoded reference to
+	<command>python3</command> in its build scripts will need
+	to have it available in <varname>PATH</varname> at build
+	time.  Use <varname>BINARY_ALIAS</varname> to create an alias
+	that points to the right Python 3 binary:</para>
+
+      <programlisting>USES=	python:3.4+,build
+...
+BINARY_ALIAS=	python3=${PYTHON_CMD}</programlisting>
+
+      <para>See <xref linkend="using-python" /> for more information
+	about <literal>USES=python</literal>.</para>
+    </example>
+  </sect1>
 </chapter>

en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml

@@ -270,6 +270,13 @@
       generate updated patch files in the <filename>files</filename>
       directory.</para>
 
+    <tip>
+      <para>Use <varname>BINARY_ALIAS</varname> to substitute
+	hardcoded commands during the build and avoid patching
+	build files.  See <xref linkend="binary-alias" /> for
+	more information.</para>
+    </tip>
+
     <sect2 xml:id="slow-patch-rules">
       <title>General Rules for Patching</title>