Date: Tue, 17 Jun 2003 15:57:14 -0500 (CDT) From: Mark Linimon <linimon@lonesome.com> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/53425: [patch] rework of parts of Porter's Handbook part 5 of 5: based on feedback Message-ID: <200306172057.h5HKvEnO027646@lonesome.lonesome.com> Resent-Message-ID: <200306172100.h5HL0TtD004156@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 53425
>Category: docs
>Synopsis: [patch] rework of parts of Porter's Handbook part 5 of 5: based on feedback
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Tue Jun 17 14:00:29 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator: Mark Linimon
>Release: FreeBSD-4.7
>Organization:
FreeBSD
>Environment:
System: FreeBSD lonesome.lonesome.com 4.7-STABLE FreeBSD 4.7-STABLE #0: Fri Nov 8 23:46:29 CST 2002 root@lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA i386
>Description:
The Porter's Handbook is insufficiently clear in some places, and
needs expanding in others. As requested I have tried to break
out the rework that I did into several pieces. This last piece
builds on parts 1-4 by incorporating feedback from various
invdividuals, notably Tilman Linneweh but also including
Giorgios Keramida and others. In several cases these patches
simply result in some of the content additions in patch #3
being dropped as being too controversial. I apologize for
the extra work that this adds for the translators, but keeping
these patches both separate and also up-to-date while changes
continue to be made to the underlying Handbook is becoming
very difficult.
>How-To-Repeat:
n/a
>Fix:
--- book.sgml.mcl.newest Sat May 24 14:00:49 2003
+++ book.sgml Sat May 24 14:19:10 2003
@@ -53,21 +53,7 @@
<para>In FreeBSD, anyone may submit a new port, or volunteer
to maintain an existing port if it is unmaintained—you
- do not need any special commit privileges to do so.
- Over time, if you gain experience and respect within the
- developer community, you may eventually gain a ports
- "commit bit" and thus become a ports "committer"
- —someone who has the right to commit to the FreeBSD
- ports CVS tree.</para>
-
- <para>A typical problem, however, is that there are many
- more people who want to add new ports than to maintain
- existing ports, and many more people who want to maintain
- existing ports than who want to serve as ports committers.
- Please keep this in mind when deciding whether to port
- something in the first place—it does not make the project
- overall look good to have ports in the tree that do not
- work because they are no longer maintained.</para>
+ do not need any special commit privileges to do so.</para>
</chapter>
<chapter id="own-port">
@@ -86,7 +72,7 @@
(This is the file that actually
controls the actual port build process, so if this document says
one thing and <filename>bsd.port.mk</filename> says another,
- <filename>bsd.port.mk</filename> is correct.)
+ it's a bug in this document; please submit a PR.)
Even if you do not hack <filename>Makefiles</filename>
daily, it is well commented, and you will still gain much
knowledge from it. Additionally, you may send specific questions
@@ -168,12 +154,7 @@
<filename>pkg-descr</filename> and
<filename>pkg-plist</filename>. Their
<filename>pkg-</filename> prefix distinguishes them from
- other files. (Note: the former
- <filename>pkg-comment</filename> files have now been folded
- into the <filename>Makefile</filename>s themselves as the
- one-line <literal>COMMENT</literal> variable and are
- thus deprecated. Please make sure your port does not
- include them.)</para>
+ other files.</para>
<sect2>
<title><filename>pkg-descr</filename></title>
@@ -574,7 +555,7 @@
distfile
we can <quote>house</quote> it ourselves
on <hostid>ftp.FreeBSD.org</hostid>; however, this is the
- least-preferred solution, as files housed there tend to get stale.
+ least-preferred solution.
The distfile must be placed into
<filename>~/public_distfiles/</filename> of someone's
<hostid>freefall</hostid> account.
@@ -587,10 +568,10 @@
<para>If your port's distfile changes all the time without any
kind of version update by the author,
consider putting the distfile in your home page and listing it as
- the first <makevar>MASTER_SITES</makevar>. (It is too bad we
- cannot always talk port authors out of doing this, because it
- really helps to establish some kind of source code control, but
- alas this is not always easy). Hosting your own version will
+ the first <makevar>MASTER_SITES</makevar>. (If you can, try to
+ talk the author out of doing this, because it really helps to
+ establish some kind of source code control for projects like ours).
+ Hosting your own version will
prevent users
from getting <errorname>checksum mismatch</errorname> errors, and
also reduce the workload of maintainers of our FTP site. Also, if
@@ -725,19 +706,6 @@
and sections in that template to make your port easier for others to
read.</para>
- <important>
- <para>There are a large number of port <literal>Makefile</literal>s
- in the ports collection that get the ordering of these variables
- wrong. Please do not blindly copy other <literal>Makefile</literal>s
- from other ports without checking the order of these variables;
- this just encourages wider propogation of bad usage in the source
- base. If in doubt of what the <quote>canonical order</quote> of the
- variables ought to be, try to follow the order in
- <filename>bsd.port.mk</filename>. (In fact blindly copying
- other <literal>Makefile</literal>s may encourage even worse
- brokenness that just the ordering of the variables!)</para>
- </important>
-
<para>Now, consider the following problems in sequence as you design
your new <filename>Makefile</filename>:</para>
@@ -912,7 +880,7 @@
suffix <literal>,0</literal> on the earlier package.</para>
<para>Dropping or resetting <makevar>PORTEPOCH</makevar>
- incorrectly is a common error in the ports collection and leads
+ incorrectly leads
to no end of grief; if you do not understand the above discussion,
please keep after it until you do, or ask questions on
the mailing lists.</para>
@@ -1001,10 +969,6 @@
<literal>3</literal> is still numerically less than
<literal>10</literal>. This is the whole point of
<makevar>PORTEPOCH</makevar> in the first place.</para>
-
- <para>Yes, this is subtle, but again, do not fiddle with
- the setting of <makevar>PORTEPOCH</makevar> until you
- understand this!</para>
</note>
</sect3>
</sect2>
@@ -2749,8 +2713,7 @@
<para>This is a one-line description of the port.
<emphasis>Please</emphasis> do not include the package name (or
version number of the software) in the comment. The comment
- should begin with a capital, end without a period, and
- should not be surrounded by quotes. Here
+ should begin with a capital, and end without a period. Here
is an example:</para>
<programlisting>COMMENT= A cat chasing a mouse all over the screen</programlisting>
@@ -3114,8 +3077,7 @@
circular dependencies. If you introduce one, you will have
someone, somewhere in the world, whose FreeBSD installation will
break almost immediately, with many others quickly to follow.
- These can really be hard to detect, especially with,
- for instance, the GNOME libraries. If in doubt, before
+ These can really be hard to detect; if in doubt, before
you make that change, make sure you have done the following:
<command>cd /usr/ports; make index</command>. That process
can be quite slow on older machines, but you may be able to
@@ -6202,9 +6164,7 @@
existing implementation of what you are trying to do. While
hard to read, there are a great many seemingly-hard problems for
which <filename>bsd.port.mk</filename> already provides a
- shorthand solution. There is almost nothing in
- <filename>bsd.port.mk</filename> which was included by
- accident and is not continually being worked on.</para>
+ shorthand solution.</para>
</sect1>
<sect1 id="dads-cc">
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200306172057.h5HKvEnO027646>