svn commit: r49328 - head/en_US.ISO8859-1/books/porters-handbook/plist

[Mathieu Arnold]

Author: mat
Date: Wed Aug 24 09:14:07 2016
New Revision: 49328
URL: https://svnweb.freebsd.org/changeset/doc/49328

Log:
  Document the PLIST_SUB regex new feature.
  
  Reviewed by:	wblock
  Sponsored by:	Absolight
  Differential Revision:	https://reviews.freebsd.org/D7545

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

Modified: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml	Wed Aug 24 04:41:50 2016	(r49327)
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml	Wed Aug 24 09:14:07 2016	(r49328)
@@ -288,6 +288,82 @@ PLIST_SUB+=	X11I386="@comment "
       must be listed as specified in the <link
 	linkend="porting-shlibs">shared libraries</link>
       section.</para>
+
+    <sect2 xml:id="plist-autoplist-regex">
+      <title>Expanding <varname>PLIST_SUB</varname> With Regular
+	Expressions</title>
+
+      <para>Strings to be replaced sometimes need to be very specific
+	to avoid undesired replacements.  This is a common problem
+	with shorter values.</para>
+
+      <para>To address this problem, for each
+	<literal><replaceable>PLACEHOLDER</replaceable>=<replaceable>value</replaceable></literal>,
+	a
+	<literal><replaceable>PLACEHOLDER</replaceable>_regex=<replaceable>regex</replaceable></literal>
+	can be set, with the
+	<literal><replaceable>regex</replaceable></literal> part
+	matching <replaceable>value</replaceable> more
+	precisely.</para>
+
+      <example xml:id="plist-autoplist-regex-ex1">
+	<title>Using PLIST_SUB With Regular Expressions</title>
+
+	<para><application>Perl</application> ports can install
+	  architecture dependant files in a specific tree.  On &os; to
+	  ease porting, this tree is called <literal>mach</literal>.
+	  For example, a port that installs a file whose path contains
+	  <literal>mach</literal> could have that part of the path
+	  string replaced with the wrong values.  Consider this
+	  <filename>Makefile</filename>:</para>
+
+	<programlisting>PORTNAME=	Machine-Build
+PORTVERSION=	1
+CATEGORIES=	devel perl5
+MASTER_SITES=	CPAN
+PKGNAMEPREFIX=	p5-
+
+MAINTAINER=	perl at FreeBSD.org
+COMMENT=	Building machine
+
+USES=		perl5
+USE_PERL5=	configure
+
+PLIST_SUB=	PERL_ARCH=mach</programlisting>
+
+	<para>The files installed by the port are:</para>
+
+	<programlisting>/usr/local/bin/machine-build
+/usr/local/lib/perl5/site_perl/man/man1/machine-build.1.gz
+/usr/local/lib/perl5/site_perl/man/man3/Machine::Build.3.gz
+/usr/local/lib/perl5/site_perl/Machine/Build.pm
+/usr/local/lib/perl5/site_perl/mach/5.20/Machine/Build/Build.so</programlisting>
+
+	<para>Runnig <command>make makeplist</command> wrongly
+	  generates:</para>
+
+	<programlisting>bin/<emphasis>%%PERL_ARCH%%</emphasis>ine-build
+%%PERL5_MAN1%%/<emphasis>%%PERL_ARCH%%</emphasis>ine-build.1.gz
+%%PERL5_MAN3%%/Machine::Build.3.gz
+%%SITE_PERL%%/Machine/Build.pm
+%%SITE_PERL%%/%%PERL_ARCH%%/%%PERL_VER%%/Machine/Build/Build.so</programlisting>
+
+	<para>Change the <varname>PLIST_SUB</varname> line from the
+	  <filename>Makefile</filename> to:</para>
+
+	<programlisting>PLIST_SUB=	PERL_ARCH=mach \
+		PERL_ARCH_regex=\bmach\b</programlisting>
+
+	<para>Now <command>make makeplist</command> correctly
+	  generates:</para>
+
+	<programlisting>bin/machine-build
+%%PERL5_MAN1%%/machine-build.1.gz
+%%PERL5_MAN3%%/Machine::Build.3.gz
+%%SITE_PERL%%/Machine/Build.pm
+%%SITE_PERL%%/%%PERL_ARCH%%/%%PERL_VER%%/Machine/Build/Build.so</programlisting>
+      </example>
+    </sect2>
   </sect1>
 
   <sect1 xml:id="plist-keywords">