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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
WHAT IS IT?
-----------------------------
Namcap is a tool for pacman checking binary packages and source PKGBUILDs for
common packaging errors.
HOW CAN I HELP?
-----------------------------
There are several ways that you can contribute and help namcap's development.
You can contribute with code, patches, tests, bugs and feature requests.
To report a bug or a feature request for namcap, file a bug in the
Packages:Extra section of the Arch Linux bugtracker and the set the importance
accordingly. If you're reporting a bug, please give concrete examples of
packages where the problem occurs.
Minimal examples (very simple packages forged to exhibit unexpected
behaviour from namcap) are also welcome to extend namcap's test suite.
If you've a patch (fixing a bug or a new namcap module), then you can send it
to the arch-projects mailing list. Namcap development is managed with git, so
git-formatted patches are preferred.
Namcap's source is available on:
http://projects.archlinux.org/?p=namcap.git;a=summary
HOW TO USE
-----------------------------
To run namcap on a PKGBUILD or a binary pkg.tar.xz:
$ namcap FILENAME
If you want to see extra informational messages, then invoke namcap with
the -i flag:
$ namcap -i FILENAME
You can also see the namcap(1) manual by typing man namcap at the command line
or see the usage help:
$ namcap -h
UNDERSTANDING THE OUTPUT
-----------------------------
Namcap uses a system of tags to classify the output. Currently, tags are of
three types, errors (denoted by E), warnings (denoted by W) and informational
(denoted by I).
An error is important and should be fixed immediately; mostly they relate to
insufficient security, missing licenses or permission problems.
Normally namcap prints a human-readable explanation (sometimes with suggestions
on how to fix the problem). If you want output which can be easily parsed by a
program, then pass the -m (machine-readable) flag to namcap.
HOW IT WORKS
-----------------------------
Namcap takes the package name (or a PKGBUILD) as an argument that runs through
all the rules defined in Namcap.rules submodules and tests them against the argument
looking for flaws.
HOW TO CREATE A MODULE
-----------------------------
This section documents the innards of namcap and specifies how to create a new
namcap rule.
The main namcap program namcap.py takes as parameters the filename of a package
or a PKGBUILD and makes a pkginfo object, which it passes to a list of rules
defined in Namcap.rules.all_rules :
* a rule is a subclass of AbstractRule (defined in Namcap.ruleclass)
* PkgInfoRule classes process any pkginfo object
* PkgbuildRule classes process only PKGBUILDs
* TarballRule classes process binary packages
Put the new rule in a module and make sure it is imported in
Namcap/rules/__init__.py
A very simple rule is the "url" rule (Namcap/rules/pkginfo.py):
from Namcap.ruleclass import PkgInfoRule
class UrlRule(PkgInfoRule):
name = "url"
description = "Verifies the package comes with an URL"
def analyze(self, pkginfo, tar):
if 'url' not in pkginfo:
self.errors.append(("missing-url", ()))
Mostly, the code is self-explanatory. The following are the list of
attributes that each namcap rule must have:
* base class
Either PkgInfoRull, PkgbuildRule, TarballRule.
* name
Contains a string containing a short name of the module. Usually, this
is the same as the basename of the module file.
* description
A string containing a concise description of the module. This
description is used when listing all the rules using namcap -r list.
* analyze(self, pkginfo, tar)
Should fill three lists self.errors, self.warnings and self.infos
with error tags, warning tags and information tags respectively.
Each member of these tag lists should be a tuple consisting of two
components: the short, hyphenated form of the tag with the appropriate
format specifiers (%s, etc.) The first word of this string must be the tag
name. The human readable form of the tag should be put in the namcap-tags
file. The format of the tags file is described below; and the parameters
which should replace the format specifier tokens in the final output.
The namcap-tags file consists of lines specifying the human readable form of
the hyphenated tags used in the namcap code. A line beginning with a '#' is
treated as a comment. Otherwise the format of the file is:
machine-parseable-tag %s :: This is machine parseable tag %s
Note that a double colon (::) is used to separate the hyphenated tag from the
human readable description.
HOW TO TEST A RULE
-----------------------------
Namcap comes with a test suite covering the classical mistakes or
warnings we are expecting from the rules. The test suite
is in Namcap/tests. The makepkg and pkgbuild_test submodules
provide easy generic methods to test a rule.
Here is an example testing the rule "pkgnameindesc"
from Namcap.tests.pkgbuild_test import PkgbuildTest
import Namcap.rules.pkgnameindesc
class NamcapPkgnameInDescTest(PkgbuildTest):
pkgbuild1 = "...some bogus pkgbuild..."
def preSetUp(self):
self.rule = Namcap.rules.pkgnameindesc.package
def test_example1(self):
r = self.run_on_pkg(self.pkgbuild1)
self.assertEqual(r.errors, [])
self.assertEqual(set(r.warnings), set(
[("pkgname-in-description", ())] ))
self.assertEqual(r.infos, [])
* the preSetUp() method sets the rule to be used in the test
* the test_example1() method runs the rule on the given PKGBUILD and
tests whether the results are as expected
* the PkgbuildTest also automatically tests the rule against a set
of known valid PKGBUILDs.
MORE INFORMATION
-----------------------------
You can find more information about namcap on namcap's wiki page:
http://wiki.archlinux.org/index.php/Namcap
|
