Skip site navigation (1)Skip section navigation (2)
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>&dollar;{SH} pkg-install &dollar;{PKGNAME}
-	PRE-INSTALL</literal> and the second time as
+      <command>pkg</command> the first time as <literal>&dollar;{SH}
+	pkg-install &dollar;{PKGNAME} PRE-INSTALL</literal> before the
+      package is installed and the second time as
       <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
-	POST-INSTALL</literal>.  <literal>&dollar;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=&dollar;{PREFIX} &dollar;{SH}
-	  &dollar;{PKGINSTALL} &dollar;{PKGNAME}
-	  PRE-INSTALL</literal>.</para>
-    </note>
+	POST-INSTALL</literal> after it has been installed.
+      <literal>&dollar;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>&dollar;{SH}
+	pkg-deinstall &dollar;{PKGNAME} DEINSTALL</literal> before the
+      port is de-installed and the second time as
       <literal>&dollar;{SH} pkg-deinstall &dollar;{PKGNAME}
-	DEINSTALL</literal> and the second time as
-      <literal>&dollar;{SH} pkg-deinstall
-	&dollar;{PKGNAME} POST-DEINSTALL</literal>.</para>
+	POST-DEINSTALL</literal> after the port has been de-installed.
+      <literal>&dollar;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 &lt;bsd.port.pre.mk&gt;
+
+.if ${PORT_OPTIONS:MX11} &amp;&amp; ${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>