118 lines
5.1 KiB
XML
118 lines
5.1 KiB
XML
<!-- $NetBSD: chap.design.xml,v 1.2 2006/02/28 23:25:23 rillig Exp $ -->
|
|
|
|
<chapter id="design">
|
|
<title>Design goals</title>
|
|
|
|
<para>&pkglint; should be simple to use. It should be consistent
|
|
and predictable in what it does. The diagnostics should be
|
|
understandable. The number of false positive and false negative
|
|
diagnostics should be minimal.</para>
|
|
|
|
<sect1 id="design.simple-to-use">
|
|
<title>Simple to use</title>
|
|
|
|
<para><emphasis>Requirement:</emphasis> Using &pkglint; should
|
|
not require any knowledge about obscure command line options or
|
|
hidden features.</para>
|
|
|
|
<para>Calling &pkglint; without options gives a useful amount of
|
|
warnings. No further knowledge is needed. Users that are
|
|
accustomed to GNU software will quickly find the
|
|
<literal>--help</literal> command line option, which gives a
|
|
quite verbose description of the available options. Users that
|
|
know the GNU compilers will easily remember the
|
|
<literal>-W</literal> class of options, especially
|
|
<literal>-Wall</literal>. Other than with the GNU compilers, the
|
|
latter option enables really <emphasis>all</emphasis> warnings
|
|
that are intended to be user-visible.</para>
|
|
|
|
<para>The command line options come in two flavors: short and
|
|
long options. The long options are meant to be used when
|
|
explaining them to others, while the short options are meant to
|
|
be used when invoking &pkglint; in an interactive shell.</para>
|
|
|
|
</sect1>
|
|
<sect1 id="design.consistent-and-predictable">
|
|
<title>Consistent and predictable</title>
|
|
|
|
<para><emphasis>Requirement:</emphasis> &pkglint; should behave
|
|
such that the user quickly gets an impression about what
|
|
&pkglint; does. This impression should be persistent, that is,
|
|
the output format for diagnostics should be stable over time,
|
|
and diagnostic messages should not be changed without
|
|
reason.</para>
|
|
|
|
<para>There are only two cases of what the output of
|
|
&pkglint; is. One is a single line containing the text
|
|
<quote>looks fine.</quote>, the other is a list of diagnostics,
|
|
followed by a summary on the number of diagnostics.</para>
|
|
|
|
<para>If no warnings are printed, the single line <quote>looks
|
|
fine.</quote> gives a little motivation to the user. This
|
|
message is one of the few things that have been kept in
|
|
&pkglint; since it has been adopted from FreeBSD. It just makes
|
|
pkglint a more friendly tool. :)</para>
|
|
|
|
<para>All error and warning messages are formatted by a single
|
|
procedure, <function>PkgLint::Logging::log_message</function>. This
|
|
way, all messages are formatted the same way, which allows easy
|
|
recognition by human users as well as other tools. There are two
|
|
different formats available, the traditional one and the gcc-like
|
|
one. In both formats, each diagnostic occupies exactly one line. Up
|
|
to the year 2005, some of the longer messages used to take more than
|
|
one line, but this behavior has been removed.</para>
|
|
|
|
<para>The default format is the traditional one. It consists of the
|
|
severity, in upper-case letters, followed by the filename, the line
|
|
number and finally the message text. It allows easy recognition of
|
|
the severity of the messages. Even if errors and warnings are
|
|
intermixed in the output, the filenames start almost in the same
|
|
column.</para>
|
|
|
|
<para>The gcc-like output format consists of the filename, the line
|
|
numbers, the severity and finally the message text. It has been
|
|
added to make it easier to integrate the &pkglint; diagnostics into
|
|
various text editors, for example Emacs. Since in this format the
|
|
filename is the first word, it can be easily seen which warning
|
|
originates in which file.</para>
|
|
|
|
<para>There are some other procedures that affect the output, but
|
|
they have to be enabled explicitly.</para>
|
|
|
|
</sect1>
|
|
<sect1 id="design.understandable">
|
|
<title>Understandable diagnostics</title>
|
|
|
|
<para><emphasis>Requirement:</emphasis> The diagnostics are
|
|
intended to help the user in writing better package definitions.
|
|
They should use an unambiguous, clear language and point
|
|
directly to the problem. If possible, they should include a hint
|
|
on how the problem can be fixed properly.</para>
|
|
|
|
</sect1>
|
|
<sect1 id="design.false-diagnostics">
|
|
<title>Few false diagnostics</title>
|
|
|
|
<para><emphasis>Requirement:</emphasis> The number of
|
|
<firstterm>false positives</firstterm>, that is diagnostics
|
|
where no problem actually exists, should be minimal. On the
|
|
other hand, &pkglint; should detect as many problems as
|
|
possible. If it fails to detect a problem, this is called a
|
|
<firstterm>false negative</firstterm>.</para>
|
|
|
|
<para>Currently, there are very few false positives. The way
|
|
&pkglint; parses the files is already close to the way
|
|
<command>make</command> and <command>sh</command> parse them, so
|
|
the structure of the files is modelled quite well.</para>
|
|
|
|
<para>Since &pkglint; is also very strict in what it accepts,
|
|
many problems can already be detected. But since the pkgsrc
|
|
developers are quite creative when it comes to solving problems,
|
|
&pkglint; cannot detect everything. After all, the language used
|
|
to define packages is turing-complete, so it cannot be decided
|
|
in every case whether a package is valid or not. Luckily, most
|
|
packages are quite simple.</para>
|
|
|
|
</sect1>
|
|
</chapter>
|