os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

1) Warn about copying pkg/DESCR from a manpage

Browse source 
2)  Include the new port in the PR, a-la current practice (the only
    submitters.sgml modification is to support this).
3)  Enlarge the list of Do's and Dont's.

Preliminary-Linuxdoc-ification-for-number-3:  Eivend
Insistence-that-number-3-not-disappear:  Eivend
Probably-implicit-offers-of-additional-help-for-number-3:  Eivend
All-the-writing:  Me.
Really-smooth-intro-written-by-Eivend-but-unfortunately-not-included-yet: Absent
This commit is contained in:
Tim Vanderhoek 1998-04-27 00:40:15 +00:00
parent 7b727ee9c7
commit 8e1ac7bc46
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=2738
2 changed files with 80 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

108
handbook/porting.sgml
View file

@ -1,4 +1,4 @@
<!-- $Id: porting.sgml,v 1.93 1998-03-15 06:03:35 hanai Exp $ -->
<!-- $Id: porting.sgml,v 1.94 1998-04-27 00:40:14 hoek Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect1><heading>Porting an existing piece of free software<label id="porting"></heading>
@ -248,9 +248,10 @@ A cat chasing a mouse all over the screen.
paragraphs concisely explaining what the port does is
sufficient. Note: This is <em>not</em> a manual nor an
in-depth description on how to use or compile the port.
In particular, <em>please do not just copy the <tt>README</tt>
file here</em>, unless, of course, it is a concise description
of the port.
<em>Please be careful if you are copying from the
<tt>README</tt> or manpage</em>; too often they are not a
concise description of the port or are in an awkward format
(e.g. manpages have justified spacing).
<p>It is recommended that you sign the name at the end of
this file, as in:
@ -313,22 +314,32 @@ lib/X11/oneko/mouse.xpm
<sect3>
<heading>Submitting the port<label id="porting:submitting"></heading>
<p>First, make sure you have read the <ref id="porting:dads"
name="Do's and Dont's"> section.
<p>Now that you are happy with your port, the only thing
remaining is to put it in the main FreeBSD ports tree and
make everybody else happy about it too. To accomplish this,
pack the necessary files (everything described in this
section -- in particular do <em>not</em> include the
original source tarball, the `<tt>work</tt>' subdirectory or
the package) into a <tt>.tar.gz</tt> file, stick it in the
directory
<tscreen><verb>
ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/
</verb></tscreen>
and send mail to us using <tt>send-pr(1)</tt> (please
classify it as category `ports' and class `change-request').
There is no need to upload the package, we will build it by
ourselves.
We will take a look, get back to you if necessary, and put
make everybody else happy about it too. We do not need
your <tt>work/</tt> directory or the <tt>pkgname.tgz</tt>
package, so delete them now. Next, simply include the
output of `<tt>shar `find port_dir`</tt>' in a
bug report and send it with the <tt>send-pr(1)</tt>
program. If the uncompressed port is larger than 20KB,
you should compress it into a tarfile and use
<tt>uuencode(1)</tt> before including it in the bug report
(uuencoded tarfiles are acceptable even if the report is
smaller than 20KB but are not preferred). Be sure to classify
the bug report as category `ports' and class `change-request'.
<p>One more time, <em>do not include the original source distfile,
the <tt>work/</tt> directory, or the package you built with
`<tt>make package</tt>'!</em>
<p>See
<ref id="contrib:general" name="Bug Reports and General Commentary">
for more information.
<p>We will look at your port, get back to you if necessary, and put
it in the tree. Your name will also appear in the list of
`Additional FreeBSD contributors' on the FreeBSD Handbook
and other files. Isn't that great?!? <tt>:)</tt>
@ -371,7 +382,7 @@ ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/
it will save the file in <tt>&dollar;{DISTDIR}</tt> for
future use and proceed.
<item>The extract target is run. It looks for your ports'
<item>The extract target is run. It looks for your port's
distribution file in <tt>&dollar;{DISTDIR}</tt> (typically
a gzip'd tarball) and unpacks it into a temporary
subdirectory specified by <tt>&dollar;{WRKDIR}</tt>
@ -589,7 +600,7 @@ foozolix-1.0.tar.gz
work/foozolix-1.0/
</verb></tscreen>
All this behavior can be overridden, of course, it simply
All this behavior can be overridden, of course; it simply
represents the most common time-saving defaults. For a port
requiring multiple distribution files, simply set
<tt>&dollar;{DISTFILES}</tt> explicitly. If only a subset
@ -1197,7 +1208,7 @@ diff -u -r1.15 PLIST
send the recursive diff (either unified or context diff is
fine, but port committers appear to prefer unified diff more)
of the new and old ports directories
to us (i.e., if your modified ports directory is called
to us (e.g., if your modified port directory is called
`<tt>superedit</tt>' and the original as in our tree is
`<tt>superedit.bak</tt>', then send us the result of `<tt>diff
-ruN superedit.bak superedit</tt>'). Please examine the output
@ -1210,10 +1221,17 @@ diff -u -r1.15 PLIST
uuencode it; otherwise, just include it in as is in the PR.
<sect2>
<heading>Do's and Dont's</heading>
<heading>Do's and Dont's
<label id="porting:dads"></heading>
<p>Here is a list of common do's and dont's that you encounter
during the porting process.
during the porting process. You should check your own port
against this list, but you can also check ports in the PR
database that others have submitted. Submit any comments on
ports you check as described in <ref id="contrib:general"
name="Bug Reports and General Commentary">. Checking ports in
the PR database will both make it faster for us to commit them,
and prove that you know what you are doing.
<sect3>
<heading>WRKDIR</heading>
@ -1227,13 +1245,11 @@ diff -u -r1.15 PLIST
copy them to the <tt>work</tt> subdirectory.
<sect3>
<heading>Package information</heading>
<heading>Portlint Clean</heading>
<p>Do include package information, i.e. <tt>COMMENT</tt>,
<tt>DESCR</tt>, and <tt>PLIST</tt>, in
<tt>pkg</tt>. Note that these files are not used only for
packaging anymore, and are <em>mandatory</em> now, even if
<tt>&dollar;{NO_PACKAGE}</tt> is set.
<p>Do use <tt>portlint</tt>! The <tt>
<htmlurl url="http://www.freebsd.org/cgi/ports.cgi?portlint"
name="portlint"></tt> program is part of the ports collection.
<sect3>
<heading>Compress manpages, strip binaries</heading>
@ -1352,7 +1368,7 @@ MAN8= baz.8
<tt>/etc/make.conf</tt>.)
<p>If you need to display a message to the installer, you may
place the message in <tt>pkg/MESSAGE</tt>. This capibility
place the message in <tt>pkg/MESSAGE</tt>. This capability
is often useful to display additional installation steps to
be taken after a pkg_add, or to display licensing information.
(note: the MESSAGE file does not need to be added to pkg/PLIST).
@ -1410,7 +1426,7 @@ MAN8= baz.8
configure, etc., are unnecessary and should be deleted.
Also, if you had to delete a file, then you can do it in the
<tt>post-extract</tt> target rather than as part of the
patch. Once you are happy with the resuling diff, please
patch. Once you are happy with the resulting diff, please
split it up into one source file per patch file.
<sect3>
@ -1533,6 +1549,36 @@ msql:*:80:249:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh
port that allocates a new UID in this range so we can keep
this list up to date.
<sect3>
<heading>Do things rationally</heading>
<p>The Makefile should do things simply and reasonably. If you
can make it a couple of lines shorter or more readable, then
do so. Examples include using a make `<tt>.if</tt>' construct
instead of a shell `<tt>if</tt>' construct, not redefining
<tt>do-extract</tt> if you can redefine <tt>&dollar;{EXTRACT*}</tt>
instead, and using <tt>&dollar;GNU_CONFIGURE</tt> instead of
`<tt>CONFIGURE_ARGS += --prefix=&dollar;{PREFIX}</tt>'.
<sect3>
<heading>Respect CFLAGS</heading>
<p>The port should respect the <tt>&dollar;{CFLAGS}</tt> variable.
If it doesn't, please add `<tt>NO_PACKAGE=ignores cflags</tt>'
to the Makefile.
<sect3>Miscellanea</heading>
<p>The files <tt>pkg/DESCR</tt>, <tt>pkg/COMMENT</tt>, and
<tt>pkg/PLIST</tt> should each be double-checked. If you are
reviewing a port and feel they can be worded better, do so.
<p>Don't copy more copies of the GNU General Public License into
our system, please.
<p>Please be careful to note any legal issues! Don't let us
illegally distribute software!
<sect3>
<heading>If you are stuck....</heading>

5
handbook/submitters.sgml
View file

@ -1,4 +1,4 @@
<!-- $Id: submitters.sgml,v 1.178 1998-04-25 16:08:58 kuriyama Exp $ -->
<!-- $Id: submitters.sgml,v 1.179 1998-04-27 00:40:15 hoek Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Contributing to FreeBSD<label id="contrib"></heading>
@ -304,7 +304,8 @@ it using the <tt>send-pr(1)</tt> program or its
<url url="http://www.freebsd.org/send-pr.html" name="WEB-based equivalent">.
Try to fill-in each field of the bug report. Unless they exceed
65KB, include any patches directly in the report. Consider compressing
them and using <tt>uuencode(1)</tt> if they exceed 20KB.
them and using <tt>uuencode(1)</tt> if they exceed 20KB. Upload very
large submissions to <url url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/">.
After filing a report, you should receive confirmation along with
a tracking number. Keep this tracking number so that you can