Date: Tue, 16 Sep 2014 12:44:46 +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: r45619 - head/en_US.ISO8859-1/books/porters-handbook/plist Message-ID: <201409161244.s8GCikLh048114@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mat (ports committer) Date: Tue Sep 16 12:44:45 2014 New Revision: 45619 URL: http://svnweb.freebsd.org/changeset/doc/45619 Log: igor -Ry and some other rewording and fixes. Differential Revision: https://reviews.freebsd.org/D646 Reviewed by: wblock 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 Tue Sep 16 12:41:02 2014 (r45618) +++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Tue Sep 16 12:44:45 2014 (r45619) @@ -19,45 +19,47 @@ 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 + ports). To make this easy, any instances in <filename>pkg-plist</filename> of <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and - <literal>%%PERL_VERSION%%</literal> will be substituted for + <literal>%%PERL_VERSION%%</literal> will be substituted appropriately. The value of <literal>%%OSREL%%</literal> is the - numeric revision of the operating system (e.g., + numeric revision of the operating system (for example, <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>). + of <command>perl</command> (for example, <literal>5.8.9</literal>). Several other <literal>%%<replaceable>VARS</replaceable>%%</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 + <para>To make other substitutions, set + <varname>PLIST_SUB</varname> with a list of <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal> pairs and instances of <literal>%%<replaceable>VAR</replaceable>%%</literal> will be - substituted with <replaceable>VALUE</replaceable> in the + substituted with <replaceable>VALUE</replaceable> in <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> + <para>For instance, if a port installs many files + in a version-specific subdirectory, use a placeholder for the + version so that <filename>pkg-plist</filename> does not have to + be regenerated every time the port is updated. For + example:</para> - <programlisting>OCTAVE_VERSION= 2.0.13 + <programlisting>OCTAVE_VERSION= ${PORTREVISION} 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 + up in <filename>pkg-plist</filename>. When + the port is upgraded, it will not be necessary to edit dozens (or in some + cases, hundreds) of lines in <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 + <para>If files are installed conditionally on the options + set in the port, the usual way of handling it is prefixing <filename>pkg-plist</filename> lines with a <literal>%%OPT%%</literal> for lines needed when the option is enabled, or <literal>%%NO_OPT%%</literal> when the option is @@ -66,13 +68,13 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSI linkend="options_sub"/> for more information.</para> <para>For instance, if there are files that are only installed - when the <literal>X11</literal> option is enabled, and the + when the <literal>X11</literal> option is enabled, and <filename>Makefile</filename> has:</para> <programlisting>OPTIONS_DEFINE= X11 OPTIONS_SUB= yes</programlisting> - <para>In the <filename>pkg-plist</filename> file, put + <para>In <filename>pkg-plist</filename>, put <literal>%%X11%%</literal> in front of the lines only being installed when the option is enabled, like this :</para> @@ -83,9 +85,9 @@ OPTIONS_SUB= yes</programlisting> <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 + <filename>WRKDIR/.PLIST.mktmp</filename>). So if the port builds <filename>PLIST</filename> on the fly, do so in or before - <buildtarget>pre-install</buildtarget>. Also, if your port + <buildtarget>pre-install</buildtarget>. Also, if the port needs to edit the resulting file, do so in <buildtarget>post-install</buildtarget> to a file named <filename>TMPPLIST</filename>.</para> @@ -108,13 +110,13 @@ OPTIONS_SUB= yes</programlisting> <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 + <filename>TMPPLIST</filename> is written, that is, in <buildtarget>pre-install</buildtarget> or earlier.</para> - <para>From time to time, the <varname>OPTIONS_SUB</varname> - construct is not enough, in those cases, adding a specific - <literal>TAG</literal> to the <varname>PLIST_SUB</varname> - variable inside the <filename>Makefile</filename> with a special + <para>From time to time, using <varname>OPTIONS_SUB</varname> + is not enough. In those cases, adding a specific + <literal><replaceable>TAG</replaceable></literal> to <varname>PLIST_SUB</varname> + inside the <filename>Makefile</filename> with a special value of <literal>@comment</literal>, makes package tools to ignore the line. For instance, if some files are only installed when the <literal>X11</literal> option is on and the @@ -139,8 +141,8 @@ PLIST_SUB+= X11I386="@comment " <para>When being de-installed, A port has to remove empty directories it created. 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 + that are specifically created by the port. Subdirectories + must be deleted before deleting parent directories.</para> <programlisting> : @@ -152,8 +154,8 @@ lib/X11/oneko/sounds/cat.au @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 + errors because other ports share the same directory. + Use <literal>@dirrmtry</literal> to remove only empty directories without warning.</para> <programlisting>@dirrmtry share/doc/gimp</programlisting> @@ -169,33 +171,38 @@ lib/X11/oneko/sounds/cat.au <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> + special attention. They must be present when the package + is created. If they are not created by the port code, create + them in the <filename>Makefile</filename>:</para> + + <programlisting>post-stage: + @${MKDIR} ${STAGEDIR}${PREFIX}/some/directory</programlisting> + + <para>Add the directory to <filename>pkg-plist</filename> + like any other. For example, if the directory has files + created when the port is used:</para> - <programlisting>@exec mkdir -p %D/share/foo/templates</programlisting> + <programlisting>@dirrmtry some/directory</programlisting> </sect2> </sect1> <sect1 xml:id="plist-config"> <title>Configuration Files</title> - <para>If your port installs configuration files to + <para>If the port installs configuration files to <filename>PREFIX/etc</filename> (or elsewhere) do - <emphasis>not</emphasis> simply list them in the + <emphasis>not</emphasis> list them in <filename>pkg-plist</filename>. That will cause - <command>pkg delete</command> to remove the files carefully + <command>pkg delete</command> to remove files that have been carefully edited by the user, and a re-installation will wipe them out.</para> - <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>Instead, install sample files with a + <filename><replaceable>filename</replaceable>.sample</filename> + extension. The <literal>@sample</literal> macro automates this, + see <xref linkend="plist-keywords-sample"/> for what it does + exactly. For each sample file, add a line to + <filename>pkg-plist</filename>:</para> <programlisting>@sample etc/orbit.conf.sample</programlisting> @@ -209,19 +216,19 @@ lib/X11/oneko/sounds/cat.au <tip> <para>When a port installs its configuration in a subdirectory - of <filename>${PREFIX}/etc</filename>, it should be in + of <filename>${PREFIX}/etc</filename>, use <varname>ETCDIR</varname>, which defaults to <literal>${PREFIX}/etc/${PORTNAME}</literal>, it can be overridden 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> + <literal>%%ETCDIR%%</literal> macro will be used in its + stead in <filename>pkg-plist</filename>.</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 + reason using the standard suffix is not possible, 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 @@ -253,15 +260,15 @@ etc/orbit.conf-dist <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 + list which is available in the Ports Collection either as + <filename>pkg-plist</filename> (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 (e.g., using <command>make + Collection by a committer (for example, using <command>make makeplist></command>), this is still considered a static list, since it is possible to examine it without having to download or compile the distfile.</para> @@ -281,8 +288,8 @@ etc/orbit.conf-dist 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> + upon the version of dependent software used. For example, ports which + generate docs with <application>Javadoc</application>.</para> </sect1> <sect1 xml:id="plist-autoplist"> @@ -290,7 +297,7 @@ etc/orbit.conf-dist <para>First, make sure the port is almost complete, with only <filename>pkg-plist</filename> missing. Running <command>make - makeplist</command> will show what should be put in + makeplist</command> will show an example for <filename>pkg-plist</filename>. The output of <buildtarget>makeplist</buildtarget> must be double checked for correctness as it tries to automatically guess a few things, and @@ -298,12 +305,12 @@ etc/orbit.conf-dist <para>User configuration files should be installed as <filename><replaceable>filename</replaceable>.sample</filename>, - as it is described in <xref linkend="plist-config"/>. The - <filename>info/dir</filename> file should not be listed and - appropriate <filename>install-info</filename> lines should be + as it is described in <xref linkend="plist-config"/>. + <filename>info/dir</filename> must not be listed and + appropriate <filename>install-info</filename> lines must 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 + must be listed as specified in the <link linkend="porting-shlibs">shared libraries</link> section.</para> </sect1> @@ -412,9 +419,9 @@ etc/orbit.conf-dist <replaceable>command</replaceable></title> <para>Execute <replaceable>command</replaceable> as part of - the unpacking process. If command contains any of the - following sequences somewhere in it, they are expanded - inline. For the following examples, assume that + the unpacking process. If command contains any of these + sequences somewhere in it, they are expanded + inline. For these examples, assume that <literal>@cwd</literal> is set to <filename class="directory">/usr/local</filename> and the last extracted file was <filename>bin/emacs</filename>.</para> @@ -527,7 +534,7 @@ etc/orbit.conf-dist By default, directories created by a package installation are not deleted when the package is deinstalled. This provides an explicit directory cleanup method. These - directives should appear at the end of the package list. If + directives must appear at the end of the package list. If the directory is not empty a warning is printed, and the directory is not removed.</para> </sect3> @@ -542,8 +549,8 @@ etc/orbit.conf-dist </sect3> </sect2> - <sect2 xml:id="plist-keywords-your-own"> - <title>Creating Your Own Keyword</title> + <sect2 xml:id="plist-keywords-creating-new"> + <title>Creating New Keywords</title> <para>Package list files can be extended by keywords that are defined in the <filename @@ -551,7 +558,7 @@ etc/orbit.conf-dist The settings for each keyword lives in a <acronym>YAML</acronym> file named <filename><replaceable>keyword</replaceable>.yaml</filename>. - The file must contain at least one of the following + The file must contain at least one of the next sections:</para> <variablelist> @@ -713,13 +720,19 @@ post-deinstall: | <programlisting>actions: [file] post-install: | - sample_file="%D/%@" + case "%@" in + /*) sample_file="%@" ;; + *) sample_file="%D/%@" ;; + esac target_file="${sample_file%.sample}" if ! [ -f "${target_file}" ]; then /bin/cp -p "${sample_file}" "${target_file}" fi pre-deinstall: | - sample_file="%D/%@" + case "%@" in + /*) sample_file="%@" ;; + *) sample_file="%D/%@" ;; + esac target_file="${sample_file%.sample}" if cmp -s "${target_file}" "${sample_file}"; then rm -f "${target_file}"
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409161244.s8GCikLh048114>