From owner-freebsd-doc@FreeBSD.ORG Sat May 22 11:57:34 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 4375316A4CE; Sat, 22 May 2004 11:57:34 -0700 (PDT) Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0916F43D1D; Sat, 22 May 2004 11:57:34 -0700 (PDT) (envelope-from linimon@lonesome.com) Received: by mail.soaustin.net (Postfix, from userid 502) id 80134148B2; Sat, 22 May 2004 13:57:13 -0500 (CDT) Date: Sat, 22 May 2004 13:57:13 -0500 (CDT) 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: RFC: minor change to Porter's Handbook 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: Sat, 22 May 2004 18:57:34 -0000 I'd like to expand on the Testing Your Port section by expanding the section on portlint(1) and adding a section on 'make describe'. Would anyone have any objections to the following: Index: book.sgml =================================================================== RCS file: /home/FreeBSD/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v retrieving revision 1.404 diff -u -r1.404 book.sgml --- book.sgml 19 May 2004 18:01:05 -0000 1.404 +++ book.sgml 22 May 2004 18:33:47 -0000 @@ -4891,14 +4891,71 @@ Testing your port + + Running <command>make describe</command> + + Several of the &os; port maintainence tools, such as + &man.portupgrade.1;, rely on a database called + INDEX which keeps track of such items + as port dependencies. INDEX is created + by the top-level ports/Makefile via + make index, which descends into each + port subdirectory and executes make describe + there. Thus, if make describe fails in any + port, no one can generate INDEX, and many + people will quickly become unhappy. + + + It is important to be able to generate this file no + matter what options are present in make.conf, + so please avoid doing things such as using .error + statements when (for instance) a dependency is not satisfied. + + + + Assume that someone has the line + USE_POINTYHAT=yes + in make.conf. The first of + the next two Makefile snippets will + cause make index to fail, while the + second one will not: + +.if USE_POINTYHAT +.error "POINTYHAT is not supported" +.endif + + +.if USE_POINTYHAT +IGNORE=POINTYHAT is not supported +.endif + + + + + If make describe produces a string, + rather than an error message, you are probably safe. See + bsd.port.mk for the meaning of this + string. + + Portlint Do check your work with portlint - before you submit or commit it. - + before you submit or commit it. portlint + warns you about many common errors, both functional and + stylistic. For a new (or repocopied) port, + portlint -A is the most thorough; for an + existing port, portlint -C is sufficient. + Since portlint uses heuristics to + try to figure out errors, it can produce false positive + warnings. In addition, occasionally something that is + flagged as a problem really cannot be done in any other + way due to limitations in the ports framework. When in + doubt, the best thing to do is ask on &a.ports;. + <makevar>PREFIX</makevar>