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
|
<!-- $NetBSD: chap.design.xml,v 1.1 2006/02/28 11:40:15 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>
</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>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>
|
