From owner-freebsd-doc@FreeBSD.ORG Sun Dec 12 22:49:07 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id B2DCF16A4CE for ; Sun, 12 Dec 2004 22:49:07 +0000 (GMT) Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66]) by mx1.FreeBSD.org (Postfix) with ESMTP id 3E7B343D48 for ; Sun, 12 Dec 2004 22:49:07 +0000 (GMT) (envelope-from linimon@lonesome.com) Received: by mail.soaustin.net (Postfix, from userid 502) id ABF36148D9; Sun, 12 Dec 2004 16:49:06 -0600 (CST) Date: Sun, 12 Dec 2004 16:49:06 -0600 (CST) From: Mark Linimon X-X-Sender: linimon@pancho To: freebsd-doc@FreeBSD.org Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Subject: CFD: update to Porter's Handbook to document build Makevars 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: Sun, 12 Dec 2004 22:49:07 -0000 pav just committed some things to disambiguate the meaning of BROKEN and IGNORE but there's still more to do. In fact, several other things are completely missing, like NOT_FOR_ARCHS and DEPRECATED. The following patch attempts to fix all that up. The HTML for the one page is on http://www.lonesome.com/FreeBSD_doc/dads-noinstall.html. I plan to commit it unless someone points out any markup bugs. mcl Index: book.sgml =================================================================== RCS file: /home/FreeBSD/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v retrieving revision 1.500 diff -u -r1.500 book.sgml --- book.sgml 12 Dec 2004 14:15:09 -0000 1.500 +++ book.sgml 12 Dec 2004 21:26:58 -0000 @@ -3484,6 +3484,12 @@ package itself, or else forcing its installation with FORCE_PKG_REGISTER will no longer work. + + + CONFLICTS automatically sets + IGNORE, which is more fully documented + here. + @@ -5359,8 +5365,8 @@ However, sometimes people forget to put the name of the port into the Synopsis field in an unambiguous fashion. In that case, - you can try the - FreeBSD Ports Monitoring System (also known as + you can try the + FreeBSD Ports Monitoring System (also known as portsmon). This system attempts to classify port PRs by portname. To search for PRs about a particular port, use the @@ -5498,7 +5504,7 @@ patch or a new version instantly, and you will only need to update the port promptly with respect to the author's fix. If the fix is delayed for some reason, - you should either mark the port as + you should either mark the port as FORBIDDEN or introduce a patch file of your own to the port. In the case of a vulnerable port, just fix the port as soon as @@ -7984,38 +7990,36 @@ - - Marking a port <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or otherwise + + Marking a port <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or otherwise not installable - Invariably there will come a time when a particular port + In certain cases users should be prevented from installing + a port. For instance, there may come a time when a particular port will contain a security vulnerability, will be radically broken and needs many hours of tender loving care, or is generally obsoleted, but for one reason or another should - remain in the tree (and get fixed, right?). To designate a - port as broken, there are three make + remain in the tree (and get fixed, right?). To tell a user that + a port should not be installed, there are several make variables that can be used in a port's Makefile. The value of the following make variables will be the reason that is - given back to users for why the port was marked as broken. + given back to users for why the port refuses to install itself. Please use the correct make variable as each make variable conveys radically different meanings to - both users, and to automated systems that parse - Makefiles. + both users, and to automated systems that depend on the + Makefiles, such as + the ports build cluster, + FreshPorts, and + portsmon. BROKEN is reserved for ports that do not compile or install. This will prevent users - from wasting their time trying to install the port. - - - - TRYBROKEN is used for ports - if you want to attempt a build of a - BROKEN port. Ports marked as - TRYBROKEN will be also built by - the Pointyhat - cluster. + from wasting their time trying to install the port. + The build cluster will still attempt to try to build + them to see if the underlying problem has been + resolved. @@ -8040,23 +8044,80 @@ IGNORE is reserved for ports that - should not be built for one reason or another. Users - and the Pointyhat - cluster will not, under any + should not be built for some other reason. The build + cluster will not, under any circumstances, build ports marked as - IGNORE. The IGNORE - variable should also be used for ports that compile but do - not run properly. If in doubt, do use - IGNORE to prevent a port from being - built. + IGNORE. For instance, use + IGNORE when a port: + + + + compiles but does not run properly + + + + does not work on the installed version of &os; + + + + requires &os; kernel sources to build, but the + user does not have them installed + + + + has a distfile which may not be automatically + fetched due to licensing restrictions + + + + does not work with a currently installed port + + + + + If a port would conflict with a currently installed + port, use + CONFLICTS instead. + CONFLICTS will set + IGNORE by itself. + + + If a port sould be marked IGNORE + only on certain architectures, there are two other + convenience variables that will automatically set + IGNORE for you: + ONLY_FOR_ARCHS and + NOT_FOR_ARCHS. Examples: + + ONLY_FOR_ARCHS = i386 amd64 + + NOT_FOR_ARCHS = alpha ia64 sparc64 - Do remember that these variables are to be used as a + Do remember that BROKEN and + FORBIDDEN are to be used as a last resort if a port is not upgradeable. Permanently broken ports should be removed from the tree entirely. + + When it makes sense to do so, users can be warned about + a pending port removal with DEPRECATED + and EXPIRATION_DATE. The former is + simply a string stating why the port is scheduled for removal; + the latter is a string in ISO 8601 format (YYYY-MM-DD). Both + will be shown to the user. + + It is possible to set DEPRECATED + without an EXPIRATION_DATE (for + instance, recommending a newer version of the port), but + the converse does not make any sense. + + There is no policy on how long to give users notice. + Current practice seems to be one month for security-related + issues and two months for build issues. This also gives any + interested committers a little time to fix the problems. @@ -8285,7 +8346,7 @@ The &os; Ports Collection is constantly changing. Here is some information on how to keep up. - + FreshPorts One of the easiest ways to learn about updates that have @@ -8345,8 +8406,8 @@ - - The &os; Port Building Cluster + + The &os; Port Building Cluster on pointyhat One of the least-publicized strengths of &os; is that an entire cluster of machines is dedicated to continually @@ -8356,6 +8417,13 @@ package building logs and errors. + Individual ports are built unless they are specifically + marked with IGNORE. Ports that are + marked with BROKEN will still be attempted, + to see if the underlying problem has been resolved. (This + is done by passing TRYBROKEN to the + port's Makefile.) + @@ -8376,7 +8444,7 @@ - + The &os; Ports Monitoring System @@ -8396,6 +8464,14 @@ Overview of One Port. + As of this writing, this is the only resource available + that maps GNATS PR entries to portnames. (PR submitters + do not always include the portname in their Synopsis, although + we would prefer that they did.) So, portsmon) + is a good place to start if you want to find out whether an + existing port has any PRs filed against it and/or any build + errors; or, to find out if a new port that you may be thinking + about creating has already been submitted.