From 6898a9706eddc15480c890d7029008146931a821 Mon Sep 17 00:00:00 2001 From: Mark Linimon Date: Fri, 22 Jul 2005 04:54:42 +0000 Subject: [PATCH] Try to clear up the ongoing confusion between the usage of the BROKEN and IGNORE Makevars. Include example reasons to use BROKEN and example usages of both BROKEN and IGNORE. Remove text made redundant by this. Finally, to try to make the added text more readable, add some sections to try to break up the flow. I would accept the argument that these sections (now 17.18 and 17.19) now have a sufficient amount of text that they should be moved up one level to become the new section 17. Requested by: many --- .../books/porters-handbook/book.sgml | 93 ++++++++++++++++--- 1 file changed, 80 insertions(+), 13 deletions(-) diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml index f1d5e58c83..663b098d67 100644 --- a/en_US.ISO8859-1/books/porters-handbook/book.sgml +++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml @@ -9081,14 +9081,11 @@ bacula:*:910: - Marking a port <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or otherwise not installable + Marking a port not installable with <makevar>BROKEN</makevar>, + <makevar>FORBIDDEN</makevar>, or <makevar>IGNORE</makevar> 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 tell a user that + a port. 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 @@ -9102,14 +9099,42 @@ bacula:*:910: FreshPorts, and portsmon. + + Variables + BROKEN is reserved for ports that - do not compile or install. This will prevent users - from wasting their time trying to install the port. + currently do not compile, install, or deinstall correctly. + It should be used for ports where the the problem is + believed to be temporary. The build cluster will still attempt to try to build them to see if the underlying problem has been - resolved. + resolved. For instance, use + BROKEN when a port: + + + + does not compile + + + + fails its configuration or installation process + + + + installs files outside of + ${LOCALBASE} and + ${X11BASE} + + + + does not remove all its files cleanly upon + deinstall (however, it may be acceptable, and desirable, + for the port to leave user-modified files behind) + + + @@ -9134,7 +9159,10 @@ bacula:*:910: IGNORE is reserved for ports that - should not be built for some other reason. The build + should not be built for some other reason. + It should be used for ports where the the problem is + believed to be structural. + The build cluster will not, under any circumstances, build ports marked as IGNORE. For instance, use @@ -9160,18 +9188,26 @@ bacula:*:910: - does not work with a currently installed port + does not work with some other currently installed + port (for instance, the port depends on + www/apache21 but + www/apache13 + is installed) If a port would conflict with a currently installed - port, use + port (for example, if they install a file in the same + place that perfoms a different function), + 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 @@ -9186,9 +9222,40 @@ bacula:*:910: + + + Implementation Notes + + Due to vagaries in the usage of IGNORECMD + in bsd.port.mk among other places, + the value of BROKEN should be enclosed + in quotes, and the value of IGNORE should + not be enclosed in quotes. + + Also, the wording of the string should be somewhat + different due to the way the information is shown to the + user. Examples: + + BROKEN= "this port is unsupported on FreeBSD 5.x" + + IGNORE= is unsupported on FreeBSD 5.x + + resulting in the following output from + make describe: + + ===> foobar-0.1 is marked as broken: this port is unsupported on FreeBSD 5.x. + + ===> foobar-0.1 is unsupported on FreeBSD 5.x. + + + + + Marking a port for removal with <makevar>DEPRECATED</makevar> + or <makevar>EXPIRATION_DATE</makevar> + Do remember that BROKEN and FORBIDDEN are to be used as a - last resort if a port is not upgradeable. Permanently + temporary resort if a port is not working. Permanently broken ports should be removed from the tree entirely.