From flz@xbsd.org  Wed Jan 26 00:13:56 2005
Return-Path: <flz@xbsd.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 88C1F16A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 26 Jan 2005 00:13:56 +0000 (GMT)
Received: from gate.xbsd.org (xbsd.org [82.233.2.192])
	by mx1.FreeBSD.org (Postfix) with ESMTP id D248F43D1F
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 26 Jan 2005 00:13:55 +0000 (GMT)
	(envelope-from flz@xbsd.org)
Received: from localhost (localhost.xbsd.org [127.0.0.1])
	by gate.xbsd.org (Postfix) with ESMTP id 3D8EE119C7
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 26 Jan 2005 01:14:32 +0100 (CET)
Received: from gate.xbsd.org ([127.0.0.1])
 by localhost (gate.xbsd.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP
 id 84516-01 for <FreeBSD-gnats-submit@freebsd.org>;
 Wed, 26 Jan 2005 01:14:26 +0100 (CET)
Received: by gate.xbsd.org (Postfix, from userid 2001)
	id D3C0B116DC; Wed, 26 Jan 2005 01:14:25 +0100 (CET)
Message-Id: <20050126001425.D3C0B116DC@gate.xbsd.org>
Date: Wed, 26 Jan 2005 01:14:25 +0100 (CET)
From: Florent Thoumie <flz@xbsd.org>
Reply-To: Florent Thoumie <flz@xbsd.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Update doc: books/porters-handbook - tell about SUB_{FILES,LIST}
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         76688
>Category:       docs
>Synopsis:       Update doc: books/porters-handbook - tell about SUB_{FILES,LIST}
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jan 26 00:20:24 GMT 2005
>Closed-Date:    Thu Feb 24 03:32:45 GMT 2005
>Last-Modified:  Thu Feb 24 03:32:45 GMT 2005
>Originator:     Florent Thoumie
>Release:        FreeBSD 5.3-RELEASE i386
>Organization:
Xbsd.org
>Environment:
System: FreeBSD gate.xbsd.org 5.3-RELEASE FreeBSD 5.3-RELEASE #2: Wed Nov 24 16:35:34 CET 2004 root@gate.xbsd.org:/usr/src/sys/i386/compile/GATE i386

>Description:

Add some piece of information about SUB_FILES and SUB_LIST variables.

>How-To-Repeat:

N/A

>Fix:

--- subfiles.diff begins here ---
--- book.sgml.orig	Wed Jan 26 00:15:04 2005
+++ book.sgml	Wed Jan 26 01:07:06 2005
@@ -5377,6 +5377,56 @@
 	  installed in <filename>/var/db/pkg</filename> upon install from a
 	  port.</para>
       </sect1>
+
+      <sect1 id="using-sub-files">
+	<title>Making use of <makevar>SUB_FILES</makevar> and
+	  <makevar>SUB_LIST</makevar></title>
+
+	<para>If your port wants to modify some of your files (that means not
+	  included in the original distribution) according to some values, you
+	  can use <makevar>SUB_FILES</makevar> and <makevar>SUB_LIST</makevar>
+	  variables.</para>
+
+	<para><makevar>SUB_FILES</makevar> specifies a list of files to be
+	  automatically modified.  Each <replaceable>file</replaceable> in
+	  <makevar>SUB_FILES</makevar> must have a corresponding
+	  <filename><replaceable>file</replaceable>.in</filename> in
+	  <makevar>FILESDIR</makevar>.  If you add some special files
+	  (<filename>pkg-message</filename>, <filename>pkg-install</filename>,
+	  <filename>pkg-deinstall</filename> or <filename>pkg-reg</filename>),
+	  <makevar>PKG-<replaceable>FILE</replaceable></makevar> associated
+	  variables will be set to
+	  <filename><makevar>WRKDIR</makevar>/pkg-<replaceable>file</replaceable></filename>.</para>
+
+	<para><makevar>SUB_LIST</makevar> is a list of <literal>VAR=VALUE</literal>
+	  pairs.  The modified version of each file will be created in
+	  <makevar>WRKDIR</makevar>.  For each <literal>VAR=VALUE</literal> in
+	  <makevar>SUB_LIST</makevar>, <literal>%%VAR%%</literal> gets replaced
+	  by <literal>VALUE</literal> in each file in <makevar>SUB_FILES</makevar>.
+	  Some usual pairs are automatically added to <makevar>SUB_LIST</makevar>,
+	  so you don't have to worry about them : <literal>PREFIX=&dollar;{PREFIX}
+	  DOCSDIR=&dollar;{DOCSDIR}</literal>, etc. (see
+	  <filename>bsd.port.mk</filename> for the entire list).</para>
+	  
+	<para> The substition process is almost the same as with
+	  <makevar>PLIST_SUB</makevar>.  Note that any line beginning with
+	  <literal>@comment</literal> after variables substitution are deleted from
+	  resulting files.</para>
+	  
+	<para>The following example can be enough for a port wanting to display a
+	  custom <filename>pkg-message</filename> (using <literal>%%PREFIX%%</literal>)
+	  and to install a rcNG startup script (using
+	  <literal>%%RC_SUBR%%</literal>).</para>
+	  
+	<programlisting>SUB_FILES= pkg-message myport.sh
+SUB_LIST= RC_SUBR=${RC_SUBR}
+
+USE_RC_SUBR=  yes</programlisting>
+
+	<para>Note that you must have (in this case) at least
+	  <filename>pkg-message.in</filename> and <filename>myport.sh.in</filename>
+	  in <makevar>FILESDIR</makevar>.</para>
+      </sect1>
     </chapter>
 
   <chapter id="testing">
--- subfiles.diff ends here ---
>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->closed 
State-Changed-By: trhodes 
State-Changed-When: Thu Feb 24 03:31:47 GMT 2005 
State-Changed-Why:  
Patch committed with some minor changes.  Thanks for the submission! 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Thu Feb 24 03:31:47 GMT 2005 
Responsible-Changed-Why:  
Over to me. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=76688 
>Unformatted:
