From owner-freebsd-doc@FreeBSD.ORG Tue Jun 17 14:00:31 2003 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 27F7B37B401 for ; Tue, 17 Jun 2003 14:00:31 -0700 (PDT) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id C48E743F85 for ; Tue, 17 Jun 2003 14:00:29 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.12.9/8.12.9) with ESMTP id h5HL0TUp004157 for ; Tue, 17 Jun 2003 14:00:29 -0700 (PDT) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.9/8.12.9/Submit) id h5HL0TtD004156; Tue, 17 Jun 2003 14:00:29 -0700 (PDT) Resent-Date: Tue, 17 Jun 2003 14:00:29 -0700 (PDT) Resent-Message-Id: <200306172100.h5HL0TtD004156@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Mark Linimon Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id C78F637B401 for ; Tue, 17 Jun 2003 13:53:03 -0700 (PDT) Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66]) by mx1.FreeBSD.org (Postfix) with ESMTP id DB82043F75 for ; Tue, 17 Jun 2003 13:53:02 -0700 (PDT) (envelope-from linimon@lonesome.com) Received: from lonesome.lonesome.com (cs242746-11.austin.rr.com [24.27.46.11]) (using TLSv1 with cipher EDH-RSA-DES-CBC3-SHA (168/168 bits)) (No client certificate requested) by mail.soaustin.net (Postfix) with ESMTP id 0248D140D7 for ; Tue, 17 Jun 2003 15:53:02 -0500 (CDT) Received: from lonesome.lonesome.com (localhost.lonesome.com [127.0.0.1]) by lonesome.lonesome.com (8.12.9/8.12.3) with ESMTP id h5HKvENa027647 for ; Tue, 17 Jun 2003 15:57:14 -0500 (CDT) (envelope-from linimon@lonesome.lonesome.com) Received: (from linimon@localhost) by lonesome.lonesome.com (8.12.9/8.12.6/Submit) id h5HKvEnO027646; Tue, 17 Jun 2003 15:57:14 -0500 (CDT) (envelope-from linimon) Message-Id: <200306172057.h5HKvEnO027646@lonesome.lonesome.com> Date: Tue, 17 Jun 2003 15:57:14 -0500 (CDT) From: Mark Linimon To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113.1 Subject: docs/53425: [patch] rework of parts of Porter's Handbook part 5 of 5: based on feedback X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 17 Jun 2003 21:00:31 -0000 >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 @@ 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. - - 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. + do not need any special commit privileges to do so. @@ -86,7 +72,7 @@ (This is the file that actually controls the actual port build process, so if this document says one thing and bsd.port.mk says another, - bsd.port.mk is correct.) + it's a bug in this document; please submit a PR.) Even if you do not hack Makefiles daily, it is well commented, and you will still gain much knowledge from it. Additionally, you may send specific questions @@ -168,12 +154,7 @@ pkg-descr and pkg-plist. Their pkg- prefix distinguishes them from - other files. (Note: the former - pkg-comment files have now been folded - into the Makefiles themselves as the - one-line COMMENT variable and are - thus deprecated. Please make sure your port does not - include them.) + other files. <filename>pkg-descr</filename> @@ -574,7 +555,7 @@ distfile we can house it ourselves on ftp.FreeBSD.org; however, this is the - least-preferred solution, as files housed there tend to get stale. + least-preferred solution. The distfile must be placed into ~/public_distfiles/ of someone's freefall account. @@ -587,10 +568,10 @@ 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 MASTER_SITES. (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 MASTER_SITES. (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 checksum mismatch 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. - - There are a large number of port Makefiles - in the ports collection that get the ordering of these variables - wrong. Please do not blindly copy other Makefiles - 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 canonical order of the - variables ought to be, try to follow the order in - bsd.port.mk. (In fact blindly copying - other Makefiles may encourage even worse - brokenness that just the ordering of the variables!) - - Now, consider the following problems in sequence as you design your new Makefile: @@ -912,7 +880,7 @@ suffix ,0 on the earlier package. Dropping or resetting PORTEPOCH - 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. @@ -1001,10 +969,6 @@ 3 is still numerically less than 10. This is the whole point of PORTEPOCH in the first place. - - Yes, this is subtle, but again, do not fiddle with - the setting of PORTEPOCH until you - understand this! @@ -2749,8 +2713,7 @@ This is a one-line description of the port. Please 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: COMMENT= A cat chasing a mouse all over the screen @@ -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: cd /usr/ports; make index. 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 bsd.port.mk already provides a - shorthand solution. There is almost nothing in - bsd.port.mk which was included by - accident and is not continually being worked on. + shorthand solution. >Release-Note: >Audit-Trail: >Unformatted: