Date: Thu, 27 Mar 2014 16:50:32 +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: r44363 - in head/en_US.ISO8859-1/books/porters-handbook: pkg-files plist upgrading Message-ID: <201403271650.s2RGoWkT074743@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mat (ports committer) Date: Thu Mar 27 16:50:32 2014 New Revision: 44363 URL: http://svnweb.freebsd.org/changeset/doc/44363 Log: Update plist, pkg-files and upgrading chapters. Sponsored by: Absolight Modified: head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml Thu Mar 27 16:13:55 2014 (r44362) +++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml Thu Mar 27 16:50:32 2014 (r44363) @@ -54,25 +54,15 @@ <command>pkg install</command> you can do this via the <filename>pkg-install</filename> script. This script will automatically be added to the package, and will be run twice by - <command>pkg</command> the first time as - - <literal>${SH} pkg-install ${PKGNAME} - PRE-INSTALL</literal> and the second time as + <command>pkg</command> the first time as <literal>${SH} + pkg-install ${PKGNAME} PRE-INSTALL</literal> before the + package is installed and the second time as <literal>${SH} pkg-install ${PKGNAME} - POST-INSTALL</literal>. <literal>$2</literal> can be - tested to determine which mode the script is being run in. - The <envar>PKG_PREFIX</envar> environmental variable will be - set to the package installation directory.</para> - - <note> - <para>This script is not run automatically if you install the - port with <command>make install</command>. If you are - depending on it being run, you will have to explicitly call - it from your port's <filename>Makefile</filename>, with a - line like <literal>PKG_PREFIX=${PREFIX} ${SH} - ${PKGINSTALL} ${PKGNAME} - PRE-INSTALL</literal>.</para> - </note> + POST-INSTALL</literal> after it has been installed. + <literal>$2</literal> can be tested to determine which + mode the script is being run in. The <envar>PKG_PREFIX</envar> + environmental variable will be set to the package installation + directory.</para> </sect1> <sect1 xml:id="pkg-deinstall"> @@ -80,12 +70,16 @@ <para>This script executes when a package is removed.</para> - <para>This script will be run twice by - <command>pkg delete</command> The first time as + <para>This script will be run twice by <command>pkg + delete</command> The first time as <literal>${SH} + pkg-deinstall ${PKGNAME} DEINSTALL</literal> before the + port is de-installed and the second time as <literal>${SH} pkg-deinstall ${PKGNAME} - DEINSTALL</literal> and the second time as - <literal>${SH} pkg-deinstall - ${PKGNAME} POST-DEINSTALL</literal>.</para> + POST-DEINSTALL</literal> after the port has been de-installed. + <literal>$2</literal> can be tested to determine which + mode the script is being run in. The <envar>PKG_PREFIX</envar> + environmental variable will be set to the package installation + directory</para> </sect1> <sect1 xml:id="pkg-names"> @@ -143,12 +137,6 @@ </tbody> </tgroup> </informaltable> - - <para>Please change these variables rather than overriding - <varname>PKG_ARGS</varname>. If you change - <varname>PKG_ARGS</varname>, those files will not correctly be - installed in <filename>/var/db/pkg</filename> upon install - from a port.</para> </sect1> <sect1 xml:id="using-sub-files"> @@ -163,14 +151,15 @@ <para>The <varname>SUB_FILES</varname> variable specifies a list of files to be automatically modified. Each - <replaceable>file</replaceable> in the + <filename><replaceable>file</replaceable></filename> in the <varname>SUB_FILES</varname> list must have a corresponding - <filename>file.in</filename> present in - <varname>FILESDIR</varname>. A modified version will be created - in <varname>WRKDIR</varname>. Files defined as a value of - <varname>USE_RC_SUBR</varname> (or the deprecated - <varname>USE_RCORDER</varname>) are automatically added to the - <varname>SUB_FILES</varname>. For the files + <filename><replaceable>file</replaceable>.in</filename> present + in <varname>FILESDIR</varname>. A modified version will be + created as + <filename>${WRKDIR}/<replaceable>file</replaceable></filename>. + Files defined as a value of <varname>USE_RC_SUBR</varname> (or + the deprecated <varname>USE_RCORDER</varname>) are automatically + added to the <varname>SUB_FILES</varname>. For the files <filename>pkg-message</filename>, <filename>pkg-install</filename>, and <filename>pkg-deinstall</filename>, the corresponding Makefile @@ -186,7 +175,7 @@ <varname>LOCALBASE</varname>, <varname>DATADIR</varname>, <varname>DOCSDIR</varname>, <varname>EXAMPLESDIR</varname>, <varname>WWWDIR</varname>, and <varname>ETCDIR</varname>. Any - line beginning with <literal>@comment</literal> will be deleted + line beginning with <literal>@comment </literal> will be deleted from resulting files after a variable substitution.</para> <para>The following example will replace Modified: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Thu Mar 27 16:13:55 2014 (r44362) +++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Thu Mar 27 16:50:32 2014 (r44363) @@ -57,19 +57,22 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSI <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) -PLIST_SUB+= X11="" -.else -PLIST_SUB+= X11="@comment " -.endif</programlisting> - - <para>and in the <filename>pkg-plist</filename>:</para> + <literal>%%OPT%%</literal> for lines needed when the option is + enabled, or <literal>%%NO_OPT%%</literal> when the option is + disabled, and adding <literal>OPTIONS_SUB=yes</literal> to the + <filename>Makefile</filename>. See <xref + 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 + <filename>Makefile</filename> has:</para> + + <programlisting>OPTIONS_DEFINE= X11 +OPTIONS_SUB= yes</programlisting> + + <para>In the <filename>pkg-plist</filename> file, put + <literal>%%X11%%</literal> in front of the lines only being + installed when the option is enabled, like this :</para> <programlisting>%%X11%%bin/foo-gui</programlisting> @@ -104,6 +107,24 @@ PLIST_SUB+= X11="@comment " and <varname>PLIST_DIRSTRY</varname> must be set before <filename>TMPPLIST</filename> is written, i.e., 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 + 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 + architecture is <literal>i386</literal>:</para> + + <programlisting>.include <bsd.port.pre.mk> + +.if ${PORT_OPTIONS:MX11} && ${ARCH} == "i386" +PLIST_SUB+= X11I386="" +.else +PLIST_SUB+= X11I386="@comment " +.endif</programlisting> + </sect1> <sect1 xml:id="plist-cleaning"> @@ -112,10 +133,10 @@ PLIST_SUB+= X11="@comment " <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 + <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 directories.</para> @@ -209,6 +230,17 @@ etc/orbit.conf.sample <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> </sect1> <sect1 xml:id="plist-dynamic"> @@ -223,9 +255,10 @@ etc/orbit.conf.sample 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> + Collection by a committer (e.g., 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> <para>A <emphasis>dynamic package list</emphasis> is a package list which is generated at the time the port is compiled based @@ -249,14 +282,17 @@ etc/orbit.conf.sample <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 + <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 + <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 + can get it wrong.</para> + + <para>User configuration files should be installed as + <filename>filename.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 added as noted in the Modified: head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Thu Mar 27 16:13:55 2014 (r44362) +++ head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Thu Mar 27 16:50:32 2014 (r44363) @@ -147,7 +147,10 @@ to see what has changed, and to update the diff if something was modified in the Ports Collection since you began work on it, or if the - committer asks for something to be fixed.</para> + committer asks for something to be fixed. Also, a patch + generated with <command>svn diff</command> can be easily applied + with <command>svn patch</command> and will save some time to the + committer.</para> <screen>&prompt.user; <userinput>cd ~/my_wrkdir</userinput> <co xml:id="my-wrkdir"/> &prompt.user; <userinput>svn co https://svn0.us-west.FreeBSD.org/ports/head/dns/pdnsd</userinput>; <co xml:id="svn-FreeBSD-org"/> @@ -173,10 +176,11 @@ </calloutlist> <para>While in the working directory, make any changes that you - would usually make to the port. If you add or remove a file, - use <command>svn</command> to track these changes:</para> + would usually make to the port. If you add, move or remove a + file, use <command>svn</command> to track these changes:</para> <screen>&prompt.user; <userinput>svn add new_file</userinput> +&prompt.user; <userinput>svn move old_name new_name</userinput> &prompt.user; <userinput>svn remove deleted_file</userinput></screen> <para>Make sure that you check the port using the checklist in @@ -251,6 +255,14 @@ <para>Send your patch following the guidelines in <xref linkend="port-upgrading"/>.</para> + + <tip> + <para>You can have patch automatically generated and the PR + pre-filled with your contact information by using + the <application>Port Tools</application> <command>port + submit</command> command. See <xref + linkend="testing-porttools"/> for more details.</para> + </tip> </sect1> <sect1 xml:id="moved-and-updating-files"> @@ -273,6 +285,17 @@ instructions, please make sure to get the shell escaping right.</para> + <note> + <para>It is recommended that the AFFECTS line contains a glob + matching all the ports affected by the entry so that automated + tools can parse it as easily as possible. If an update + concerns all the existing <application>BIND 9</application> + versions the <literal>AFFECTS</literal> content should be + <literal>users of dns/bind9*</literal>, it should + <emphasis>not</emphasis> be <literal>users of BIND + 9</literal></para> + </note> + <para>The <filename>/usr/ports/MOVED</filename> file is used to list moved or removed ports. Each line in the file is made up of the name of the port, where the port was moved to, when, @@ -285,12 +308,18 @@ <para>The date should be entered in the form <literal>YYYY-MM-DD</literal>. New entries should be added to - the end of the file to keep it in chronological order.</para> + the top of the file to keep it in reverse chronological order + (the latest entries first).</para> <para>If a port was removed but has since been restored, delete the line in this file that states that it was removed.</para> + <para>If a port was renamed and then renamed back to its original + name, you should add a new one with the intermediate name to the + old name, and remove the old entry as to not create a + loop.</para> + <para>The changes can be validated with <command>Tools/scripts/MOVEDlint.awk</command>.</para> </sect1>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403271650.s2RGoWkT074743>