os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Document the new @sample keyword, and move the old way in a note below.

Browse source 
Sponsored by:	Absolight
This commit is contained in:
Mathieu Arnold 2014-04-18 12:06:38 +00:00
parent 9f6c3b13b1
commit e5711c282b
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44602
1 changed files with 39 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

61
en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
View file

@ -189,19 +189,40 @@ lib/X11/oneko/sounds/cat.au
edited by the user, and a re-installation will wipe them
out.</para>
<para>Instead, install sample file(s) with a
<filename><replaceable>filename</replaceable>.sample</filename> suffix. Then copy the
sample file to the real configuration file name, if it does not
already exist. On deinstall delete the configuration file, but
only if it is identical to the <filename>.sample</filename>
file. You need to handle this in the
<para>Instead, install sample file(s) as
<filename><replaceable>filename</replaceable>.sample</filename>,
and for each sample file, add this line to your
<filename>pkg-plist</filename>.</para>
<para>For each configuration file, create the following three
lines in <filename>pkg-plist</filename>:</para>
<programlisting>@sample etc/orbit.conf.sample</programlisting>
<programlisting>@unexec if cmp -s %D/etc/orbit.conf.sample %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
etc/orbit.conf.sample
<para>If there is a very good reason not to install a working
configuration file by default, only list the sample filename in
<filename>pkg-plist</filename>, without the <literal>@sample
</literal> part, and add a <link
linkend="porting-message">message</link> pointing out that the
user must copy and edit the file before the software will
work.</para>
<tip>
<para>When a port installs its configuration in a subdirectory
of <filename>${PREFIX}/etc</filename>, it should be in
<varname>ETCDIR</varname>, which defaults to
<literal>${PREFIX}/etc/${PORTNAME}</literal>, it can be
overrided in the ports <filename>Makefile</filename> if there
is a convention for the port to use some other directory. The
<literal>%%ETCDIR%%</literal> macro should be used in its
stead in the <filename>pkg-plist</filename> file.</para>
</tip>
<note>
<para>The sample configuration files should always have the
<filename>.sample</filename> suffix. If for some historical
reason you cannot use the standard suffix, you can still use
this construct:</para>
<programlisting>@unexec if cmp -s %D/etc/orbit.conf-dist %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
etc/orbit.conf-dist
@exec if [ ! -f %D/etc/orbit.conf ] ; then cp -p %D/%F %B/orbit.conf; fi</programlisting>
<para>The order of these lines is important. On deinstallation,
@ -222,25 +243,7 @@ etc/orbit.conf.sample
<para>See &man.pkg-create.8; for more information on
<literal>%D</literal> and related substitution markers.</para>
<para>If there is a very good reason not to install a working
configuration file by default, leave the
<literal>@exec</literal> line out of
<filename>pkg-plist</filename> and add a
<link linkend="porting-message">message</link> pointing out that
the user must copy and edit the file before the software will
work.</para>
<tip>
<para>When a port installs its configuration in a subdirectory
of <filename>${PREFIX}/etc</filename>, it should be in
<varname>ETCDIR</varname>, which defaults to
<literal>${PREFIX}/etc/${PORTNAME}</literal>, it can be
overrided in the ports <filename>Makefile</filename> if there
is a convention for the port to use some other directory. The
<literal>%%ETCDIR%%</literal> macro should be used in its
stead in the <filename>pkg-plist</filename> file.</para>
</tip>
</note>
</sect1>
<sect1 xml:id="plist-dynamic">