Date: Sun, 9 Feb 2014 04:05:25 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43850 - head/en_US.ISO8859-1/books/porters-handbook/plist Message-ID: <201402090405.s1945PhX081944@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sun Feb 9 04:05:25 2014 New Revision: 43850 URL: http://svnweb.freebsd.org/changeset/doc/43850 Log: Whitespace-only fixes, translators please ignore. 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 Sun Feb 9 03:46:05 2014 (r43849) +++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Sun Feb 9 04:05:25 2014 (r43850) @@ -5,127 +5,121 @@ $FreeBSD$ --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="plist"> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:id="plist"> + + <title>Advanced <filename>pkg-plist</filename> Practices</title> + + <sect1 xml:id="plist-sub"> + <title>Changing <filename>pkg-plist</filename> Based on Make + Variables</title> + + <para>Some ports, particularly the <literal>p5-</literal> ports, + need to change their <filename>pkg-plist</filename> depending on + what options they are configured with (or version of + <literal>perl</literal>, in the case of <literal>p5-</literal> + ports). To make this easy, any instances in the + <filename>pkg-plist</filename> of <literal>%%OSREL%%</literal>, + <literal>%%PERL_VER%%</literal>, and + <literal>%%PERL_VERSION%%</literal> will be substituted for + appropriately. The value of <literal>%%OSREL%%</literal> is the + numeric revision of the operating system (e.g., + <literal>4.9</literal>). <literal>%%PERL_VERSION%%</literal> + and <literal>%%PERL_VER%%</literal> is the full version number + of <command>perl</command> (e.g., <literal>5.8.9</literal>). + Several other <literal>%%VARS%%</literal> related to port's + documentation files are described in + <link linkend="install-documentation">the relevant + section</link>.</para> + + <para>If you need to make other substitutions, you can set the + <varname>PLIST_SUB</varname> variable with a list of + <literal>VAR=VALUE</literal> pairs and instances of + <literal>%%VAR%%</literal> will be substituted with + <replaceable>VALUE</replaceable> in the + <filename>pkg-plist</filename>.</para> + + <para>For instance, if you have a port that installs many files + in a version-specific subdirectory, you can put something + like</para> - <title>Advanced <filename>pkg-plist</filename> Practices</title> - - <sect1 xml:id="plist-sub"> - <title>Changing <filename>pkg-plist</filename> Based on Make - Variables</title> - - <para>Some ports, particularly the <literal>p5-</literal> ports, - need to change their <filename>pkg-plist</filename> depending - on what options they are configured with (or version of - <literal>perl</literal>, in the case of <literal>p5-</literal> - ports). To make this easy, any instances in the - <filename>pkg-plist</filename> of - <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, - and <literal>%%PERL_VERSION%%</literal> will be substituted - for appropriately. The value of <literal>%%OSREL%%</literal> - is the numeric revision of the operating system (e.g., - <literal>4.9</literal>). <literal>%%PERL_VERSION%%</literal> - and <literal>%%PERL_VER%%</literal> is the full version number - of <command>perl</command> (e.g., <literal>5.8.9</literal>). - Several other - <literal>%%VARS%%</literal> related - to port's documentation files are described in - <link linkend="install-documentation">the relevant - section</link>.</para> - - <para>If you need to make other substitutions, you can set the - <varname>PLIST_SUB</varname> variable with a list of - <literal>VAR=VALUE</literal> - pairs and instances of - <literal>%%VAR%%</literal> will be - substituted with <replaceable>VALUE</replaceable> in the - <filename>pkg-plist</filename>.</para> - - <para>For instance, if you have a port that installs many files - in a version-specific subdirectory, you can put something - like</para> - - <programlisting>OCTAVE_VERSION= 2.0.13 + <programlisting>OCTAVE_VERSION= 2.0.13 PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting> - <para>in the <filename>Makefile</filename> and use - <literal>%%OCTAVE_VERSION%%</literal> wherever the version - shows up in <filename>pkg-plist</filename>. That way, when - you upgrade the port, you will not have to change dozens (or - in some cases, hundreds) of lines in the - <filename>pkg-plist</filename>.</para> - - <para>If your port installs files conditionally on the options - set in the port, the usual way of handling it is prefixing the - <filename>pkg-plist</filename> lines with a - <literal>%%TAG%%</literal> and adding that - <literal>TAG</literal> to the <varname>PLIST_SUB</varname> - variable inside the <filename>Makefile</filename> with a - special value of <literal>@comment</literal>, which makes - package tools to ignore the line:</para> + <para>in the <filename>Makefile</filename> and use + <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows + up in <filename>pkg-plist</filename>. That way, when you + upgrade the port, you will not have to change dozens (or in some + cases, hundreds) of lines in the + <filename>pkg-plist</filename>.</para> + + <para>If your port installs files conditionally on the options + set in the port, the usual way of handling it is prefixing the + <filename>pkg-plist</filename> lines with a + <literal>%%TAG%%</literal> and adding that + <literal>TAG</literal> to the <varname>PLIST_SUB</varname> + variable inside the <filename>Makefile</filename> with a special + value of <literal>@comment</literal>, which makes package tools + to ignore the line:</para> - <programlisting>.if defined(WITH_X11) + <programlisting>.if defined(WITH_X11) PLIST_SUB+= X11="" .else PLIST_SUB+= X11="@comment " .endif</programlisting> - <para>and in the <filename>pkg-plist</filename>:</para> + <para>and in the <filename>pkg-plist</filename>:</para> - <programlisting>%%X11%%bin/foo-gui</programlisting> + <programlisting>%%X11%%bin/foo-gui</programlisting> - <para>This substitution - will be - done between the <buildtarget>pre-install</buildtarget> and - <buildtarget>do-install</buildtarget> targets, by reading from - <filename>PLIST</filename> and writing to - <filename>TMPPLIST</filename> (default: - <filename>WRKDIR/.PLIST.mktmp</filename>). - So if your port builds - <filename>PLIST</filename> on the fly, do - so in or before <buildtarget>pre-install</buildtarget>. Also, - if your port needs to edit the resulting file, do so in - <buildtarget>post-install</buildtarget> to a file named - <filename>TMPPLIST</filename>.</para> - - <para>Another way of modifying a port's packing list is based - on setting the variables <varname>PLIST_FILES</varname>, - <varname>PLIST_DIRS</varname>, and - <varname>PLIST_DIRSTRY</varname>. The value of each variable - is regarded as a list of pathnames to write to - <filename>TMPPLIST</filename> along with - <filename>PLIST</filename> contents. Names - listed in <varname>PLIST_FILES</varname>, - <varname>PLIST_DIRS</varname>, and - <varname>PLIST_DIRSTRY</varname> are subject to - <literal>%%VAR%%</literal> - substitution as described above. Except for that, names from - <varname>PLIST_FILES</varname> will appear in the final - packing list unchanged, while <literal>@dirrm</literal> and - <literal>@dirrmtry</literal> will - be prepended to names from <varname>PLIST_DIRS</varname> - and <varname>PLIST_DIRSTRY</varname>, respectively. To - take effect, <varname>PLIST_FILES</varname>, - <varname>PLIST_DIRS</varname>, and - <varname>PLIST_DIRSTRY</varname> must be set before - <filename>TMPPLIST</filename> is written, - i.e., in <buildtarget>pre-install</buildtarget> or - earlier.</para> - </sect1> - - <sect1 xml:id="plist-cleaning"> - <title>Empty Directories</title> - - <sect2 xml:id="plist-dir-cleaning"> - <title>Cleaning Up Empty Directories</title> - - <para>Do make your ports remove empty directories when they - are de-installed. This is usually accomplished by adding - <literal>@dirrm</literal> lines for all directories that are - specifically created by the port. You need to delete - subdirectories before you can delete parent - directories.</para> + <para>This substitution will be done between the + <buildtarget>pre-install</buildtarget> and + <buildtarget>do-install</buildtarget> targets, by reading from + <filename>PLIST</filename> and writing to + <filename>TMPPLIST</filename> (default: + <filename>WRKDIR/.PLIST.mktmp</filename>). So if your port + builds <filename>PLIST</filename> on the fly, do so in or before + <buildtarget>pre-install</buildtarget>. Also, if your port + needs to edit the resulting file, do so in + <buildtarget>post-install</buildtarget> to a file named + <filename>TMPPLIST</filename>.</para> + + <para>Another way of modifying a port's packing list is based on + setting the variables <varname>PLIST_FILES</varname>, + <varname>PLIST_DIRS</varname>, and + <varname>PLIST_DIRSTRY</varname>. The value of each variable is + regarded as a list of pathnames to write to + <filename>TMPPLIST</filename> along with + <filename>PLIST</filename> contents. Names listed in + <varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>, + and <varname>PLIST_DIRSTRY</varname> are subject to + <literal>%%VAR%%</literal> substitution as described above. + Except for that, names from <varname>PLIST_FILES</varname> will + appear in the final packing list unchanged, while + <literal>@dirrm</literal> and <literal>@dirrmtry</literal> will + be prepended to names from <varname>PLIST_DIRS</varname> and + <varname>PLIST_DIRSTRY</varname>, respectively. To take effect, + <varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>, + and <varname>PLIST_DIRSTRY</varname> must be set before + <filename>TMPPLIST</filename> is written, i.e., in + <buildtarget>pre-install</buildtarget> or earlier.</para> + </sect1> + + <sect1 xml:id="plist-cleaning"> + <title>Empty Directories</title> + + <sect2 xml:id="plist-dir-cleaning"> + <title>Cleaning Up Empty Directories</title> + + <para>Do make your ports remove empty directories when they are + de-installed. This is usually accomplished by adding + <literal>@dirrm</literal> lines for all directories that are + specifically created by the port. You need to delete + subdirectories before you can delete parent + directories.</para> - <programlisting> : + <programlisting> : lib/X11/oneko/pixmaps/cat.xpm lib/X11/oneko/sounds/cat.au : @@ -133,156 +127,151 @@ lib/X11/oneko/sounds/cat.au @dirrm lib/X11/oneko/sounds @dirrm lib/X11/oneko</programlisting> - <para>However, sometimes <literal>@dirrm</literal> will give - you errors because other ports share the same directory. - You can use <literal>@dirrmtry</literal> to remove only - empty directories without warning.</para> - - <programlisting>@dirrmtry share/doc/gimp</programlisting> - - <para>This will neither print any error messages nor cause - <command>pkg delete</command> (see &man.pkg-delete.8;) to - exit abnormally even if - <filename>${PREFIX}/share/doc/gimp</filename> is not empty - due to other ports installing some files in there.</para> - </sect2> - - <sect2 xml:id="plist-dir-empty"> - <title>Creating Empty Directories</title> - - <para>Empty directories created during port installation need - special attention. They will not get created when - installing the package, because packages only store the - files, and both <command>pkg add</command> and <command>pkg - install</command> creates directories for them as needed. - To make sure the empty directory is created when installing - the package, add this line to <filename>pkg-plist</filename> - above the corresponding <literal>@dirrm</literal> - line:</para> + <para>However, sometimes <literal>@dirrm</literal> will give + you errors because other ports share the same directory. You + can use <literal>@dirrmtry</literal> to remove only empty + directories without warning.</para> + + <programlisting>@dirrmtry share/doc/gimp</programlisting> + + <para>This will neither print any error messages nor cause + <command>pkg delete</command> (see &man.pkg-delete.8;) to + exit abnormally even if + <filename>${PREFIX}/share/doc/gimp</filename> is not empty + due to other ports installing some files in there.</para> + </sect2> + + <sect2 xml:id="plist-dir-empty"> + <title>Creating Empty Directories</title> + + <para>Empty directories created during port installation need + special attention. They will not get created when installing + the package, because packages only store the files, and both + <command>pkg add</command> and <command>pkg install</command> + creates directories for them as needed. To make sure the + empty directory is created when installing the package, add + this line to <filename>pkg-plist</filename> above the + corresponding <literal>@dirrm</literal> line:</para> <programlisting>@exec mkdir -p %D/share/foo/templates</programlisting> - </sect2> - </sect1> + </sect2> + </sect1> - <sect1 xml:id="plist-config"> - <title>Configuration Files</title> + <sect1 xml:id="plist-config"> + <title>Configuration Files</title> - <para>If your port installs configuration files to - <filename>PREFIX/etc</filename> (or - elsewhere) do <emphasis>not</emphasis> simply list them in the - <filename>pkg-plist</filename>. That will cause <command>pkg - delete</command> to remove the files carefully edited by the - user, and a re-installation will wipe them out.</para> - - <para>Instead, install sample file(s) with a - <filename>filename.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 both in the port - <filename>Makefile</filename>, and in the - <filename>pkg-plist</filename> (for installation from the - package).</para> + <para>If your port installs configuration files to + <filename>PREFIX/etc</filename> (or elsewhere) do + <emphasis>not</emphasis> simply list them in the + <filename>pkg-plist</filename>. That will cause + <command>pkg delete</command> to remove the files carefully + edited by the user, and a re-installation will wipe them + out.</para> + + <para>Instead, install sample file(s) with a + <filename>filename.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 both in the port + <filename>Makefile</filename>, and in the + <filename>pkg-plist</filename> (for installation from the + package).</para> - <para>Example of the <filename>Makefile</filename> part:</para> + <para>Example of the <filename>Makefile</filename> part:</para> - <programlisting>post-install: + <programlisting>post-install: @if [ ! -f ${PREFIX}/etc/orbit.conf ]; then \ ${CP} -p ${PREFIX}/etc/orbit.conf.sample ${STAGEDIR}${PREFIX}/etc/orbit.conf ; \ fi</programlisting> - <para>For each configuration file, create the following three - lines in <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 + <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> - - <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> - </sect1> - - <sect1 xml:id="plist-dynamic"> - <title>Dynamic Versus Static Package List</title> - - <para>A <emphasis>static package list</emphasis> is a package - list which is available in the Ports Collection either as a - <filename>pkg-plist</filename> file (with or without variable - substitution), or embedded into the - <filename>Makefile</filename> via - <varname>PLIST_FILES</varname>, - <varname>PLIST_DIRS</varname>, and - <varname>PLIST_DIRSTRY</varname>. Even if the contents are - auto-generated by a tool or a target in the Makefile - <emphasis>before</emphasis> the inclusion into the Ports - Collection by a committer, this is still considered a static - list, since it is possible to examine it without having to - download or compile the distfile.</para> - - <para>A <emphasis>dynamic package list</emphasis> is a package - list which is generated at the time the port is compiled based - upon the files and directories which are installed. It is not - possible to examine it before the source code of the ported - application is downloaded and compiled, or after running a - <literal>make clean</literal>.</para> - - <para>While the use of dynamic package lists is not forbidden, - maintainers should use static package lists wherever possible, - as it enables users to &man.grep.1; through available ports to - discover, for example, which port installs a certain file. - Dynamic lists should be primarily used for complex ports where - the package list changes drastically based upon optional - features of the port (and thus maintaining a static package - list is infeasible), or ports which change the package list - based upon the version of dependent software used (e.g., ports - which generate docs with - <application>Javadoc</application>).</para> - </sect1> - - <sect1 xml:id="plist-autoplist"> - <title>Automated Package List Creation</title> - - <para>First, make sure your port is almost complete, with only - <filename>pkg-plist</filename> missing. You may then run - <command>make makeplist</command> to - generate a <filename>pkg-plist</filename> automatically. This - file must be double checked for correctness.</para> - - <para>User configuration files should be - removed, or installed as - <filename>filename.sample</filename>. - The <filename>info/dir</filename> file should not be listed - and appropriate <filename>install-info</filename> lines should - be added as noted in the - <link linkend="makefile-info">info files</link> section. Any - libraries installed by the port should be listed as specified - in the <link linkend="porting-shlibs">shared libraries</link> - section.</para> - </sect1> - </chapter> - + <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> + + <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> + </sect1> + + <sect1 xml:id="plist-dynamic"> + <title>Dynamic Versus Static Package List</title> + + <para>A <emphasis>static package list</emphasis> is a package + list which is available in the Ports Collection either as a + <filename>pkg-plist</filename> file (with or without variable + substitution), or embedded into the + <filename>Makefile</filename> via + <varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>, + and <varname>PLIST_DIRSTRY</varname>. Even if the contents are + auto-generated by a tool or a target in the Makefile + <emphasis>before</emphasis> the inclusion into the Ports + Collection by a committer, this is still considered a static + list, since it is possible to examine it without having to + download or compile the distfile.</para> + + <para>A <emphasis>dynamic package list</emphasis> is a package + list which is generated at the time the port is compiled based + upon the files and directories which are installed. It is not + possible to examine it before the source code of the ported + application is downloaded and compiled, or after running a + <literal>make clean</literal>.</para> + + <para>While the use of dynamic package lists is not forbidden, + maintainers should use static package lists wherever possible, + as it enables users to &man.grep.1; through available ports to + discover, for example, which port installs a certain file. + Dynamic lists should be primarily used for complex ports where + the package list changes drastically based upon optional + features of the port (and thus maintaining a static package list + is infeasible), or ports which change the package list based + upon the version of dependent software used (e.g., ports which + generate docs with <application>Javadoc</application>).</para> + </sect1> + + <sect1 xml:id="plist-autoplist"> + <title>Automated Package List Creation</title> + + <para>First, make sure your port is almost complete, with only + <filename>pkg-plist</filename> missing. You may then run + <command>make makeplist</command> to generate a + <filename>pkg-plist</filename> automatically. This file must be + double checked for correctness.</para> + + <para>User configuration files should be removed, or installed as + <filename>filename.sample</filename>. The + <filename>info/dir</filename> file should not be listed and + appropriate <filename>install-info</filename> lines should be + added as noted in the + <link linkend="makefile-info">info files</link> section. Any + libraries installed by the port should be listed as specified in + the <link linkend="porting-shlibs">shared libraries</link> + section.</para> + </sect1> +</chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402090405.s1945PhX081944>