Date: Mon, 18 Aug 2003 14:53:44 +0200 From: "Simon L. Nielsen" <simon@FreeBSD.org> To: Joe Marcus Clarke <marcus@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: Review of porters-handbook changes Message-ID: <20030818125337.GB407@FreeBSD.org> In-Reply-To: <1061131638.43833.2.camel@shumai.marcuscom.com> References: <1061069299.54862.34.camel@shumai.marcuscom.com> <20030817110722.GA391@FreeBSD.org> <1061131638.43833.2.camel@shumai.marcuscom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--VrqPEDrXMn8OVzN4
Content-Type: multipart/mixed; boundary="AqsLC8rIMeq19msA"
Content-Disposition: inline
--AqsLC8rIMeq19msA
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
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@ciam.ru> for some of the recent
> > > ports infrastructure changes. It is technically accurate, and I fixe=
d 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!
> >=20
> > 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.
>=20
> 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:1=
2:05 -0000 1.320
> +++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml 17 Aug 2003 14:4=
6:25 -0000
> @@ -4316,6 +4086,19 @@
> </note>
> </sect1>
> =20
> + <sect1 id=3D"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.
--=20
Simon L. Nielsen
FreeBSD Documentation Team
--AqsLC8rIMeq19msA
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="book.sgml-sln.diff"
Content-Transfer-Encoding: quoted-printable
--- 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>
=20
+ <sect1 id=3D"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=3D"makefile-build">
<title>Building mechanisms</title>
=20
@@ -3216,11 +3229,24 @@
=20
<entry>Says that the port uses Perl 5 to build and run.</entry>
</row>
- =20
+
<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>
- =20
+ </tbody>
+ </tgroup>
+
+ <tgroup cols=3D"2">
+ <thead>
+ <row>
+ <entry>Read only variables</entry>
+ </row>
+ </thead>
+
+ <tbody>
<row>
<entry><makevar>PERL_VERSION</makevar></entry>
=20
@@ -4003,267 +4029,11 @@
<chapter id=3D"porting-info">
<title>Info files</title>
=20
- <para>The new version of texinfo (included in 2.2.2-RELEASE and onwa=
rd)
- contains a utility called <command>install-info</command> to add a=
nd
- delete entries to the <filename>dir</filename> file. If your port
- installs any info documents, please follow these instructions so y=
our
- port/package will correctly update the user's
- <filename><makevar>PREFIX</makevar>/info/dir</filename> file. (So=
rry
- 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=3DTEXT Insert TEXT as an Info directory entry.
- :
---section=3DSEC Put this file's entries in section SEC of the director=
y. :</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=3D"package">editors/emacs</filename> will be used a=
s an
- example.</para>
-
- <procedure>
- <step>
- <para>Look at the texinfo sources and make a patch to insert
- <literal>@dircategory</literal> and <literal>@direntry</litera=
l>
- 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
-+@dircategory The Emacs editor and associated tools
-+@direntry
-+* VIP: (vip). A VI-emulation for Emacs.
-+@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 y=
our
- 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 becau=
se
- 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>) inst=
ead
- of patching the texinfo sources. This probably is not a good
- idea for ports because you need to duplicate the same informat=
ion
- 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 h=
ave
- Japanese (or other multi-byte encoding) info files, you will h=
ave
- 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=3D"package">j=
apanese/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 pa=
tch 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 =3D lib-src src
-+SUBDIR =3D lib-src src man
-
- # The makefiles of the directories in $SUBDIR.
- SUBDIR_MAKEFILES =3D 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> t=
hat
- is installing the <filename>dir</filename> file, delete it. Y=
our
- 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)` !=3D `(cd ${infodir} && /bi=
n/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 exist=
ing
- port.) Take a look at <filename>pkg-plist</filename> and delete
- anything that is trying to patch up <filename>info/dir</filena=
me>.
- They may be in <filename>pkg-install</filename> or some other
- file, so search extensively.</para>
-
- <programlisting>Index: pkg-plist
-=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
-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
--@unexec cp %D/info/dir %D/info/dir.bak
--info/dir
--@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
-=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
-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
-=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
-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
-+@unexec install-info --delete %D/info/emacs %D/info/dir
- :
-+@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
-+@exec install-info %D/info/emacs %D/info/dir
- :
-+@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=3D"porting-testing">Test</link> and admire y=
our
- work. <!-- smiley --><emphasis>:-)</emphasis>. Check the
- <filename>dir</filename> file before and after each step.</par=
a>
- </step>
- </procedure>
+ <para>If your package needs to install GNU info files, they should be
+ listed in the <makevar>INFO</makevar> variable (without the traili=
ng
+ <literal>.info</literal>), and appropriate installation/deinstalla=
tion
+ code will be automaticaly added to the temporary
+ <filename>pkg-plist</filename> before package registration.</para>
</chapter>
=20
<chapter id=3D"pkg-files">
@@ -4316,6 +4086,19 @@
</note>
</sect1>
=20
+ <sect1 id=3D"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 ${PKG=
NAME}
+ DEINSTALL</literal> and the second time as
+ <literal>${SH} pkg-install ${PKGNAME} POST-DEINSTA=
LL</literal>.
+ </para>
+ </sect1>
+
<sect1 id=3D"pkg-req">
<title><filename>pkg-req</filename></title>
=20
@@ -4372,13 +4155,13 @@
=20
<para>This substitution (as well as addition of any <link
linkend=3D"porting-manpages">manual pages</link>) will be done b=
etween
- 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</makev=
ar>
(default:
<filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). S=
o 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>
=20
<row>
--AqsLC8rIMeq19msA--
--VrqPEDrXMn8OVzN4
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (FreeBSD)
iD8DBQE/QMxRh9pcDSc1mlERAuj3AJ43euf3bjLYZWDPEPMTWEcK52pLrwCgkGIb
WEJJny31nT/rPDDpDLFt6+M=
=lzkE
-----END PGP SIGNATURE-----
--VrqPEDrXMn8OVzN4--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030818125337.GB407>