From a537dd69f90f860e69924ebdb59cf5e27f892356 Mon Sep 17 00:00:00 2001
From: Mathieu Arnold <mat@FreeBSD.org>
Date: Fri, 24 Jul 2015 12:43:05 +0000
Subject: [PATCH] Document the target helpers introduced in rP391051.

Reviewed by:	wblock
Sponsored by:	Absolight
Differential Revision:	https://reviews.freebsd.org/D2957
---
 .../porters-handbook/makefiles/chapter.xml    | 135 ++++++++++++++++++
 1 file changed, 135 insertions(+)

diff --git a/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
index 2589515ad7..81b2a01392 100644
--- a/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
@@ -4425,6 +4425,8 @@ QMAKE_ARGS+=	-DTEST:BOOL=false
 	  </listitem>
 	</itemizedlist>
 
+	<para>The following variables can be used.</para>
+
 	<sect4>
 	  <title><varname><replaceable>OPT</replaceable>_<replaceable>ABOVEVARIABLE</replaceable></varname></title>
 
@@ -4574,6 +4576,8 @@ LIB_DEPENDS+=	liba.so:${PORTSDIR}/devel/a
 	  </listitem>
 	</itemizedlist>
 
+	<para>The following variables can be used.</para>
+
 	<note>
 	  <para>Some variables are not in this list, in particular
 	    <varname>PKGNAMEPREFIX</varname> and
@@ -4662,6 +4666,137 @@ USES+=	gmake
 
 	</sect4>
       </sect3>
+
+      <sect3 xml:id="options-targets">
+	<title>Additional Build Targets</title>
+
+	<para>These <filename>Makefile</filename> targets can accept
+	  optional extra build targets:</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para><buildtarget>pre-fetch</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>post-fetch</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>pre-extract</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>post-extract</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>pre-patch</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>post-patch</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>pre-configure</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>post-configure</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>pre-build</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>post-build</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>pre-install</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>post-install</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>pre-package</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>post-package</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>pre-stage</buildtarget></para>
+	  </listitem>
+
+	  <listitem>
+	    <para><buildtarget>post-stage</buildtarget></para>
+	  </listitem>
+	</itemizedlist>
+
+	<para>The additional build targets are listed below.</para>
+
+	<sect4 xml:id="options-targets-on">
+	  <!-- XXX: Should be <buildtarget> and not <literal> -->
+	  <title><buildtarget><replaceable>ABOVETARGET</replaceable>-<replaceable>OPT</replaceable>-on</buildtarget></title>
+
+	  <para>When option <replaceable>OPT</replaceable> is
+	    selected, the target
+	    <buildtarget><replaceable>ABOVETARGET</replaceable>-<replaceable>OPT</replaceable>-on</buildtarget>,
+	    if defined, is executed after
+	    <buildtarget><replaceable>ABOVETARGET</replaceable></buildtarget>.
+	    For example:</para>
+
+	  <programlisting>OPTIONS_DEFINE=	OPT1
+
+post-patch-OPT1-on:
+	@${REINPLACE_CMD} -e '/opt1/d' ${WRKSRC}/Makefile</programlisting>
+
+	<para>is equivalent to:</para>
+
+	<programlisting>OPTIONS_DEFINE=	OPT1
+
+.include &lt;bsd.port.options.mk&gt;
+
+post-patch:
+.if ${PORT_OPTIONS:MOPT1}
+	@${REINPLACE_CMD} -e '/opt1/d' ${WRKSRC}/Makefile
+.endif</programlisting>
+	</sect4>
+
+	<sect4 xml:id="options-targets-off">
+	  <!-- XXX: Should be <buildtarget> and not <literal> -->
+	  <title><buildtarget><replaceable>ABOVETARGET</replaceable>-<replaceable>OPT</replaceable>-off</buildtarget></title>
+
+	  <para>When option <replaceable>OPT</replaceable> is
+	    not selected, the target
+	    <buildtarget><replaceable>ABOVETARGET</replaceable>-<replaceable>OPT</replaceable>-off</buildtarget>,
+	    if defined, is executed after
+	    <buildtarget><replaceable>ABOVETARGET</replaceable></buildtarget>.
+	    For example:</para>
+
+	  <programlisting>OPTIONS_DEFINE=	OPT1
+
+post-patch-OPT1-off:
+	@${REINPLACE_CMD} -e '/opt1/d' ${WRKSRC}/Makefile</programlisting>
+
+	<para>is equivalent to:</para>
+
+	<programlisting>OPTIONS_DEFINE=	OPT1
+
+.include &lt;bsd.port.options.mk&gt;
+
+post-patch:
+.if !${PORT_OPTIONS:MOPT1}
+	@${REINPLACE_CMD} -e '/opt1/d' ${WRKSRC}/Makefile
+.endif</programlisting>
+	</sect4>
+      </sect3>
     </sect2>
   </sect1>