Date: Sat, 22 May 2004 13:57:13 -0500 (CDT) From: Mark Linimon <linimon@lonesome.com> To: freebsd-doc@FreeBSD.org, <freebsd-ports@FreeBSD.org> Subject: RFC: minor change to Porter's Handbook Message-ID: <Pine.LNX.4.44.0405221355320.15322-100000@pancho>
next in thread | raw e-mail | index | archive | help
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 @@
<chapter id="testing">
<title>Testing your port</title>
+ <sect1 id="make-describe">
+ <title>Running <command>make describe</command></title>
+
+ <para>Several of the &os; port maintainence tools, such as
+ &man.portupgrade.1;, rely on a database called
+ <filename>INDEX</filename> which keeps track of such items
+ as port dependencies. <filename>INDEX</filename> is created
+ by the top-level <filename>ports/Makefile</filename> via
+ <command>make index</command>, which descends into each
+ port subdirectory and executes <command>make describe</command>
+ there. Thus, if <command>make describe</command> fails in any
+ port, no one can generate <filename>INDEX</filename>, and many
+ people will quickly become unhappy.</para>
+
+ <note>
+ <para>It is important to be able to generate this file no
+ matter what options are present in <filename>make.conf</filename>,
+ so please avoid doing things such as using <literal>.error</literal>
+ statements when (for instance) a dependency is not satisfied.</para>
+ </note>
+
+ <example id="dot-error-breaks-index"><title></title>
+ <para>Assume that someone has the line
+ <programlisting>USE_POINTYHAT=yes</programlisting>
+ in <filename>make.conf</filename>. The first of
+ the next two <filename>Makefile</filename> snippets will
+ cause <command>make index</command> to fail, while the
+ second one will not:
+ <programlisting>
+.if USE_POINTYHAT
+.error "POINTYHAT is not supported"
+.endif
+ </programlisting>
+ <programlisting>
+.if USE_POINTYHAT
+IGNORE=POINTYHAT is not supported
+.endif
+ </programlisting>
+ </para>
+ </example>
+
+ <para>If <command>make describe</command> produces a string,
+ rather than an error message, you are probably safe. See
+ <filename>bsd.port.mk</filename> for the meaning of this
+ string.</para>
+ </sect1>
+
<sect1 id="testing-portlint">
<title>Portlint</title>
<para>Do check your work with <link
linkend="porting-portlint"><command>portlint</command></link>
- before you submit or commit it.</para>
- </sect1>
+ before you submit or commit it. <command>portlint</command>
+ warns you about many common errors, both functional and
+ stylistic. For a new (or repocopied) port,
+ <command>portlint -A</command> is the most thorough; for an
+ existing port, <command>portlint -C</command> is sufficient.</para>
+ <para>Since <command>portlint</command> 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;.</para>
+ </sect1>
<sect1 id="porting-prefix">
<title><makevar>PREFIX</makevar></title>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.LNX.4.44.0405221355320.15322-100000>