Review of porters-handbook changes
Joe Marcus Clarke
marcus at FreeBSD.org
Sun Aug 17 14:47:41 UTC 2003
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.
>
> > --- doc/en_US.ISO8859-1/books/porters-handbook/book.sgml 10 Aug 2003 20:34:31 -0000 1.319
> > +++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml 16 Aug 2003 21:24:46 -0000
>
> > @@ -3216,11 +3227,23 @@
> >
> > <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 USE_PERL5.</entry>
> ^^^^^^^^^
> Missing makevar tag.
Good catch. It's fixed in this patch.
>
> > @@ -4316,6 +4083,19 @@
> > </note>
> > </sect1>
> >
> > + <sect1 id="pkg-deinstall">
> > + <title><filename>pkg-deinstall</filename></title>
> > +
> > + <para>This script executes when a package is removed.</para>
> > +
> > + <para>
> > + Like the <filename>pkg-install</filename> script it will be run twice.
> > + 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>
>
> Perhaps a reference to pkg_delete(1) ?
Another good idea.
>
> Otherwise it looks OK to me, but I have only checked the markup, not the
> language.
Attached is a new rev with an addition suggested by Stijn Hoop.
Joe
--
Joe Marcus Clarke
FreeBSD GNOME Team :: gnome at FreeBSD.org
FreeNode / #freebsd-gnome
http://www.FreeBSD.org/gnome
-------------- 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 <command>pkg_delete</command>.
+ 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: signature.asc
Type: application/pgp-signature
Size: 187 bytes
Desc: This is a digitally signed message part
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030817/c163be10/attachment.sig>
More information about the freebsd-doc
mailing list