1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
<!-- $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>
|
