Date: Wed, 26 Jan 2005 01:14:25 +0100 (CET)
From: Florent Thoumie <flz@xbsd.org>
To: FreeBSD-gnats-submit@FreeBSD.org
Subject: docs/76688: Update doc: books/porters-handbook - tell about SUB_{FILES,LIST}
Message-ID: <20050126001425.D3C0B116DC@gate.xbsd.org>
Resent-Message-ID: <200501260020.j0Q0KPwK035374@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 76688
>Category: docs
>Synopsis: Update doc: books/porters-handbook - tell about SUB_{FILES,LIST}
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Wed Jan 26 00:20:24 GMT 2005
>Closed-Date:
>Last-Modified:
>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=${PREFIX}
+ DOCSDIR=${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:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20050126001425.D3C0B116DC>