Review of porters-handbook changes

Simon L. Nielsen simon at FreeBSD.org
Mon Aug 18 13:50:30 UTC 2003


On 2003.08.17 10:47:18 -0400, Joe Marcus Clarke wrote:
> On Sun, 2003-08-17 at 07:07, Simon L. Nielsen wrote:
> > On 2003.08.16 17:28:19 -0400, Joe Marcus Clarke wrote:
> > > Can someone review the attached diff to the porter's handbook?  It was
> > > submitted by Sergey Matveychuk <sem at ciam.ru> for some of the recent
> > > ports infrastructure changes.  It is technically accurate, and I fixed a
> > > few grammar and spelling nits, but I would like a doc committers take on
> > > it before committing.  Also, if one of you would rather commit, that's
> > > fine.  Thanks!
> > 
> > There are some places where 8 spaces have been used instead of a tab
> > (can be fixed by marking the regions and using 'meta-x tabify' in
> > emacs').  There are also some end of line white-spaces which should be
> > removed.
> 
> I tried to preserve the style of adjacent blocks.  To that end, some use
> spaces, so I opted for spaces to keep things lined up.

OK, I didn't check the rest for the file for style, and the tab/space
thing is not that important then.

But the end of line whitespace still doesn't need to be there :).  It's
not crucial to remove it, but there is no reason to have it there.

Sorry for being so pedantic about this...

I have attached a patch where I have removed the end of line whitespace,
and changed the pkg_deinstall reference (see below).

> --- doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	17 Aug 2003 09:12:05 -0000	1.320
> +++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	17 Aug 2003 14:46:25 -0000
> @@ -4316,6 +4086,19 @@
>          </note>
>        </sect1>
>  
> +      <sect1 id="pkg-deinstall">
> +        <title><filename>pkg-deinstall</filename></title>
> +
> +        <para>This script executes when a package is removed.</para>
> +
> +        <para>
> +          This script will be run twice by <command>pkg_delete</command>.

It's better to use "&man.pkg.delete.1;" instead of the command tag since
it will create a link to the manual page.

-- 
Simon L. Nielsen
FreeBSD Documentation Team
-------------- next part --------------
--- doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	17 Aug 2003 09:12:05 -0000	1.320
+++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	17 Aug 2003 14:46:25 -0000
@@ -3019,6 +3019,19 @@
       </sect2>
     </sect1>
 
+    <sect1 id="conflicts">
+      <title><makevar>CONFLICTS</makevar></title>
+
+        <para>If your package cannot coexist with other packages
+          (because of file conflicts, runtime incompatibility, etc.),
+          list the other package names in the <makevar>CONFLICTS</makevar>
+          variable. You can use shell globs like <literal>*</literal> and
+          <literal>?</literal> here.  Packages names should be
+          enumerated the same way they appear in
+          <filename>/var/db/pkg</filename>.
+       </para>
+    </sect1>
+
       <sect1 id="makefile-build">
         <title>Building mechanisms</title>
 
@@ -3216,11 +3229,24 @@
 
 	      <entry>Says that the port uses Perl 5 to build and run.</entry>
 	    </row>
-	    
+
 	    <row>
-	      <entry><makevar>PERL</makevar></entry>
+	      <entry><makevar>PERL_CONFIGURE</makevar></entry>
+
+	      <entry>Configure using Perl's MakeMaker.  It implies
+	        <makevar>USE_PERL5</makevar>.</entry>
 	    </row>
-	    
+	  </tbody>
+	</tgroup>
+
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Read only variables</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
 	    <row>
 	      <entry><makevar>PERL_VERSION</makevar></entry>
 	      
@@ -4003,267 +4029,11 @@
     <chapter id="porting-info">
       <title>Info files</title>
 
-      <para>The new version of texinfo (included in 2.2.2-RELEASE and onward)
-        contains a utility called <command>install-info</command> to add and
-        delete entries to the <filename>dir</filename> file.  If your port
-        installs any info documents, please follow these instructions so your
-        port/package will correctly update the user's
-        <filename><makevar>PREFIX</makevar>/info/dir</filename> file.  (Sorry
-        for the length of this section, but is it imperative to weave all the
-        info files together.  If done correctly, it will produce a
-        <emphasis>beautiful</emphasis> listing, so please bear with me!)</para>
-
-      <para>First, this is what you (as a porter) need to know:</para>
-
-      <screen>&prompt.user; <userinput>install-info --help</userinput>
-install-info [OPTION]... [INFO-FILE [DIR-FILE]]
-  Install INFO-FILE in the Info directory file DIR-FILE.
-
-Options:
---delete          Delete existing entries in INFO-FILE;
-                    don't insert any new entries.
- :
---entry=TEXT      Insert TEXT as an Info directory entry.
- :
---section=SEC     Put this file's entries in section SEC of the directory. :</screen>
-
-      <note>
-        <para>This program will not actually <emphasis>install</emphasis> info
-          files; it merely inserts or deletes entries in the
-          <filename>dir</filename> file.</para>
-      </note>
-
-      <para>Here's a seven-step procedure to convert ports to use
-        <command>install-info</command>.
-        <filename role="package">editors/emacs</filename> will be used as an
-        example.</para>
-
-      <procedure>
-        <step>
-          <para>Look at the texinfo sources and make a patch to insert
-            <literal>@dircategory</literal> and <literal>@direntry</literal>
-            statements to files that do not have them.  This is part of my
-            patch:</para>
-
-          <programlisting>--- ./man/vip.texi.org  Fri Jun 16 15:31:11 1995
-+++ ./man/vip.texi      Tue May 20 01:28:33 1997
-@@ -2,6 +2,10 @@
-
- @setfilename ../info/vip
- @settitle VIP
-+ at dircategory The Emacs editor and associated tools
-+ at direntry
-+* VIP: (vip).          A VI-emulation for Emacs.
-+ at end direntry
-
- @iftex
- @finalout
- :</programlisting>
-
-          <para>The format should be self-explanatory.  Many authors leave a
-            <filename>dir</filename> file in the source tree that contains all
-            the entries you need, so look around before you try to write your
-            own.  Also, make sure you look into related ports and make the
-            section names and entry indentations consistent (we recommend that
-            all entry text start at the 4th tab stop).</para>
-
-          <note>
-            <para>Note that you can put only one info entry per file because
-              of a bug in <command>install-info --delete</command> that
-              deletes only the first entry if you specify multiple entries in
-              the <email>@direntry</email> section.</para>
-          </note>
-
-          <para>You can give the <literal>dir</literal> entries to
-            <command>install-info</command> as arguments
-            (<option>--section</option> and <option>--entry</option>) instead
-            of patching the texinfo sources.  This probably is not a good
-            idea for ports because you need to duplicate the same information
-            in <emphasis>three</emphasis> places
-            (<filename>Makefile</filename> and
-            <literal>@exec</literal>/<literal>@unexec</literal> of
-            <filename>pkg-plist</filename>; see below).  However, if you have
-            Japanese (or other multi-byte encoding) info files, you will have
-            to use the extra arguments to <command>install-info</command>
-            because <command>makeinfo</command> cannot handle those texinfo
-            sources.  (See <filename>Makefile</filename> and
-            <filename>pkg-plist</filename> of <filename role="package">japanese/skk</filename>
-            for examples on how to do this).</para>
-        </step>
-
-        <step>
-          <para>Go back to the port directory and do a <command>make clean;
-              make</command> and verify that the info files are regenerated
-            from the texinfo sources. Since the texinfo sources are newer than
-            the info files, they should be rebuilt when you type
-            <command>make</command>; but many <filename>Makefile</filename>s
-            do not include correct dependencies for info files.  In
-            <application>Emacs</application>' case, it was necessary to patch the main
-            <filename>Makefile.in</filename> so it would descend into the
-            <filename>man</filename> subdirectory to rebuild the info
-            pages.</para>
-
-          <programlisting>--- ./Makefile.in.org   Mon Aug 19 21:12:19 1996
-+++ ./Makefile.in       Tue Apr 15 00:15:28 1997
-@@ -184,7 +184,7 @@
- # Subdirectories to make recursively.  `lisp' is not included
- # because the compiled lisp files are part of the distribution
- # and you cannot remake them without installing Emacs first.
--SUBDIR = lib-src src
-+SUBDIR = lib-src src man
-
- # The makefiles of the directories in $SUBDIR.
- SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile
- lwlib/Makefile
---- ./man/Makefile.in.org       Thu Jun 27 15:27:19 1996
-+++ ./man/Makefile.in   Tue Apr 15 00:29:52 1997
-@@ -66,6 +66,7 @@
- ${srcdir}/gnu1.texi \
- ${srcdir}/glossary.texi
-
-+all: info
- info: $(INFO_TARGETS)
-
- dvi: $(DVI_TARGETS)</programlisting>
-
-          <para>The second hunk was necessary because the default target in
-            the <filename>man</filename> subdir is called
-            <maketarget>info</maketarget>, while the main
-            <filename>Makefile</filename> wants to call
-            <maketarget>all</maketarget>.  The installation of the
-            <filename>info</filename> info file was also removed because we
-            already have one with the same name in
-            <filename>/usr/share/info</filename> (that patch is not shown
-            here).</para>
-        </step>
-
-        <step>
-          <para>If there is a place in the <filename>Makefile</filename> that
-            is installing the <filename>dir</filename> file, delete it.  Your
-            port may not be doing it.  Also, remove any commands that are
-            otherwise mucking around with the <filename>dir</filename>
-            file.</para>
-
-          <programlisting>--- ./Makefile.in.org   Mon Aug 19 21:12:19 1996
-+++ ./Makefile.in       Mon Apr 14 23:38:07 1997
-@@ -368,14 +368,8 @@
-        if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
-        then \
-          (cd ${infodir};  \
--          if [ -f dir ]; then \
--            if [ ! -f dir.old ]; then mv -f dir dir.old; \
--            else mv -f dir dir.bak; fi; \
--          fi; \
-           cd ${srcdir}/info ; \
--          (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir);
-\
--          (cd $${thisdir}; chmod a+r ${infodir}/dir); \
-           for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
-             (cd $${thisdir}; \
-              ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
-              chmod a+r ${infodir}/$$f); \</programlisting>
-        </step>
-
-        <step>
-          <para>(This step is only necessary if you are modifying an existing
-            port.) Take a look at <filename>pkg-plist</filename> and delete
-            anything that is trying to patch up <filename>info/dir</filename>.
-            They may be in <filename>pkg-install</filename> or some other
-            file, so search extensively.</para>
-
-          <programlisting>Index: pkg-plist
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v
-retrieving revision 1.15
-diff -u -r1.15 pkg-plist
---- pkg-plist       1997/03/04 08:04:00     1.15
-+++ pkg-plist       1997/04/15 06:32:12
-@@ -15,9 +15,6 @@
- man/man1/emacs.1.gz
- man/man1/etags.1.gz
- man/man1/ctags.1.gz
-- at unexec cp %D/info/dir %D/info/dir.bak
--info/dir
-- at unexec cp %D/info/dir.bak %D/info/dir
- info/cl
- info/cl-1
- info/cl-2</programlisting>
-        </step>
-
-        <step>
-          <para>Add a <maketarget>post-install</maketarget> target to the
-            <filename>Makefile</filename> to call
-            <maketarget>install-info</maketarget> with the installed
-            info files.  (It is no longer necessary to create the
-            <filename>dir</filename> file yourself;
-            <command>install-info</command> automatically creates this
-            file if it does not exist.)</para>
-
-          <programlisting>Index: Makefile
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
-retrieving revision 1.26
-diff -u -r1.26 Makefile
---- Makefile    1996/11/19 13:14:40     1.26
-+++ Makefile    1997/05/20 10:25:09     1.28
-@@ -20,5 +20,8 @@
- post-install:
- .for file in emacs-19.34 emacsclient etags ctags b2m
-        strip ${PREFIX}/bin/${file}
- .endfor
-+.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
-+       install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
-+.endfor
-
- .include <bsd.port.mk></programlisting>
-        </step>
-
-        <step>
-          <para>Edit <filename>pkg-plist</filename> and add equivalent
-            <literal>@exec</literal> statements and also
-            <literal>@unexec</literal> for
-            <command>pkg_delete</command>.</para>
-
-          <programlisting>Index: pkg-plist
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v
-retrieving revision 1.15
-diff -u -r1.15 pkg-plist
---- pkg-plist       1997/03/04 08:04:00     1.15
-+++ pkg-plist       1997/05/20 10:25:12     1.17
-@@ -16,7 +14,14 @@
- man/man1/etags.1.gz
- man/man1/ctags.1.gz
-+ at unexec install-info --delete %D/info/emacs %D/info/dir
- :
-+ at unexec install-info --delete %D/info/ccmode %D/info/dir
- info/cl
- info/cl-1
-@@ -87,6 +94,18 @@
- info/viper-3
- info/viper-4
-+ at exec install-info %D/info/emacs %D/info/dir
- :
-+ at exec install-info %D/info/ccmode %D/info/dir
- libexec/emacs/19.34/i386--freebsd/cvtmail
- libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
-
-          <note>
-            <para>The <literal>@unexec install-info --delete</literal>
-              commands have to be listed before the info files themselves so
-              they can read the files. Also, the <literal>@exec
-                install-info</literal> commands have to be after the info
-              files and the <literal>@exec</literal> command that creates the
-              the <filename>dir</filename> file.</para>
-          </note>
-        </step>
-
-        <step>
-          <para><link linkend="porting-testing">Test</link> and admire your
-            work.  <!-- smiley --><emphasis>:-)</emphasis>.  Check the
-            <filename>dir</filename> file before and after each step.</para>
-        </step>
-      </procedure>
+      <para>If your package needs to install GNU info files, they should be
+        listed in the <makevar>INFO</makevar> variable (without the trailing
+        <literal>.info</literal>), and appropriate installation/deinstallation
+        code will be automaticaly added to the temporary
+        <filename>pkg-plist</filename> before package registration.</para>
     </chapter>
 
     <chapter id="pkg-files">
@@ -4316,6 +4086,19 @@
         </note>
       </sect1>
 
+      <sect1 id="pkg-deinstall">
+        <title><filename>pkg-deinstall</filename></title>
+
+        <para>This script executes when a package is removed.</para>
+
+        <para>
+          This script will be run twice by &man.pkg.delete.1;.
+          The first time as <literal>${SH} pkg-install ${PKGNAME}
+          DEINSTALL</literal> and the second time as
+          <literal>${SH} pkg-install ${PKGNAME} POST-DEINSTALL</literal>.
+        </para>
+      </sect1>
+
       <sect1 id="pkg-req">
         <title><filename>pkg-req</filename></title>
 
@@ -4372,13 +4155,13 @@
 
         <para>This substitution (as well as addition of any <link
           linkend="porting-manpages">manual pages</link>) will be done between
-          the <maketarget>do-install</maketarget> and
-          <maketarget>post-install</maketarget> targets, by reading from
+          the <maketarget>pre-install</maketarget> and
+          <maketarget>do-install</maketarget> targets, by reading from
           <makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar>
           (default:
           <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>).  So if
           your port builds <makevar>PLIST</makevar> on the fly, do so in or
-          before <maketarget>do-install</maketarget>.  Also, if your port
+          before <maketarget>pre-install</maketarget>.  Also, if your port
           needs to edit the resulting file, do so in
           <maketarget>post-install</maketarget> to a file named
           <makevar>TMPPLIST</makevar>.</para>
@@ -4424,6 +4207,11 @@
               <row>
                 <entry><makevar>PKGINSTALL</makevar></entry>
                 <entry><literal>${PKGDIR}/pkg-install</literal></entry>
+              </row>
+
+              <row>
+                <entry><makevar>PKGDEINSTALL</makevar></entry>
+                <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry>
               </row>
 
               <row>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030818/39c5bd72/attachment.sig>


More information about the freebsd-doc mailing list