Date: Fri, 18 Apr 2014 12:06:38 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44602 - head/en_US.ISO8859-1/books/porters-handbook/plist Message-ID: <201404181206.s3IC6cQh026706@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mat (ports committer) Date: Fri Apr 18 12:06:38 2014 New Revision: 44602 URL: http://svnweb.freebsd.org/changeset/doc/44602 Log: Document the new @sample keyword, and move the old way in a note below. Sponsored by: Absolight 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 Thu Apr 17 20:33:55 2014 (r44601) +++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Fri Apr 18 12:06:38 2014 (r44602) @@ -189,46 +189,19 @@ 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>@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 -@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, - the sample file is compared to the actual configuration file. - If these files are identical, no changes have been made by the - user and the actual file can be safely deleted. Because the - sample file must still exist for the comparison, the - <literal>@unexec</literal> line comes before the sample - configuration file name. On installation, if an actual - configuration file is not already present, the sample file is - copied to the actual file. The sample file must be present - before it can be copied, so the <literal>@exec</literal> line - comes after the sample configuration file name.</para> - - <para>To debug any issues, temporarily remove the - <literal>-s</literal> flag to &man.cmp.1; for more - output.</para> - - <para>See &man.pkg-create.8; for more information on - <literal>%D</literal> and related substitution markers.</para> + <programlisting>@sample etc/orbit.conf.sample</programlisting> <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 + 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> @@ -241,6 +214,36 @@ etc/orbit.conf.sample <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, + the sample file is compared to the actual configuration file. + If these files are identical, no changes have been made by the + user and the actual file can be safely deleted. Because the + sample file must still exist for the comparison, the + <literal>@unexec</literal> line comes before the sample + configuration file name. On installation, if an actual + configuration file is not already present, the sample file is + copied to the actual file. The sample file must be present + before it can be copied, so the <literal>@exec</literal> line + comes after the sample configuration file name.</para> + + <para>To debug any issues, temporarily remove the + <literal>-s</literal> flag to &man.cmp.1; for more + output.</para> + + <para>See &man.pkg-create.8; for more information on + <literal>%D</literal> and related substitution markers.</para> + </note> </sect1> <sect1 xml:id="plist-dynamic">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404181206.s3IC6cQh026706>