1.\" Copyright (c) 1997 by Jun-ichiro Hagino <itojun@itojun.org>.
2.\" All Rights Reserved.  Absolutely no warranty.
3.\"
4.Dd April 1, 2010
5.Dt PORTLINT 1
6.Os
7.Sh NAME
8.Nm portlint
9.Nd a verifier for port directories
10.Sh SYNOPSIS
11.Nm portlint
12.Op Fl abcghvtACNV
13.Op Fl M Ar ENV
14.Op Fl B Ar n
15.Op Ar dir
16.Sh DESCRIPTION
17.Nm
18tries to verify the content of a port directory.
19The purpose of
20.Nm
21can be separated into two parts:
22.Pq 1
23to let the submitters easily polish their own port directory, and
24.Pq 2
25to decrease the labor of the committers.
26.Pp
27.Nm
28uses very simple regular-expression matching for verifying
29files that make up a port directory.
30Note that it does NOT implement a complete parser for those files.
31Because of this the user may see some extra warnings,
32especially when checking complex
33.Pa Makefile Ns No s .
34.Pp
35.Sy Options
36.Bl -tag -width Fl
37.It Fl a
38Perform additional checks for extra files, such as
39.Pa scripts/*
40and
41.Pa pkg-* .
42.It Fl b
43Warn the use of
44.Pa $(VARIABLE) .
45Some of the committers prefer
46.Pa ${VARIABLE}
47instead of
48.Pa $(VARIABLE) ,
49even though they are semantically the same.
50.It Fl c
51Committer flag.
52It will add several checks useful only for committers.
53If you are a committer and performing check just before committing a port,
54use this option.
55.It Fl g
56Group and consolidate errors so that redundant error messages are rolled
57up into one line with a list of all affected line numbers (where
58appropriate).  This option is disabled if
59.Fl v
60is specified.
61.It Fl h
62Show the summary of command line options, then exit.
63.It Fl m
64Adds checks for $PORTSDIR/MOVED, $PORTSDIR/UIDs, and $PORTSDIR/GIDs.
65.It Fl v
66Be verbose.
67Show the progress report for items that are being checked.
68.It Fl t
69Nit pick about use of spaces.
70.It Fl A
71Turn on all additional checks.  This is equivalent to
72.Fl abcmNt .
73.It Fl C
74Pedantic committer flag.  This is equivalent to
75.Fl abcmt .
76.It Fl N
77New port flag.
78Adds several checks specific to newly submitted port.
79If you are willing to submit the directory to be checked as a new port,
80use this option.
81.It Fl V
82Print the portlint version and exit.
83.It Fl M Ar ENV
84Set make variables to
85.Pa ENV
86(ex. PORTSDIR=/usr/ports.work).
87.It Fl B Ar n
88Set the number of contiguous blank lines allowed in
89.Pa Makefile
90to
91.Ar n .
92(by default,
93.Ar n
94is 1)
95.It dir
96The port directory to be checked.
97If omitted, check will be performed over the current directory.
98.El
99.Sh ENVIRONMENT
100The following environment variables affect the execution of
101.Nm :
102.Bl -tag -width ".Ev PL_GIT_IGNORE"
103.It Ev PL_GIT_IGNORE
104Set to a Perl-compatible regular expression, of patterns
105to ignore when checking to see if files are in the git
106repository.  For example,
107.Li '^\ed+$|^pr-patch$' .
108.It Ev PORTSDIR
109The fully-qualified path to the ports tree.
110For example,
111.Dq Li /usr/ports .
112.El
113.Sh FILES
114.Bl -tag -width bsd.port.mkxx -compact
115.It Pa bsd.port.mk
116master Makefile for ports
117.Po
118.Pa bsd.pkg.mk
119on
120.Nx
121/
122.Ox
123.Pc
124.It Pa /usr/ports/*
125ports collection
126.Po
127.Pa /usr/pkgsrc/*
128on
129.Nx
130/
131.Ox
132.Pc ;
133can be overriden by setting the
134.Va PORTSDIR
135environment variable.
136.El
137.Sh DIAGNOSTICS
138Messages will be sent to standard output, not standard error output.
139.Bl -tag -width "WARN: foobaa"
140.It FATAL: ...
141This type of error message suggests that there is some fatal error
142in the port directory.
143For example, if some files need a rewrite, or if
144some inevitable files are missing, this message will show up.
145This kind of errors should be avoided BEFORE submitting
146a port via send-pr to the committers.
147.\"If a submitter submits it without update, committers will need to rewrite
148.\"on behalf of the submitters, which may result in delay of
149.\"the development of operating system itself.
150.It WARN: ...
151This type of error message suggests that some files may (or may not)
152need some fix.
153Basically, warnings are produced when
154.Nm
155is not completely sure about the result.
156For example, complex
157.Pa Makefile Ns No s
158may need some statements that can match the regular expression
159.Nm
160uses for sanity checks.
161In those cases, the user should evaluate the result manually,
162and obey/ignore the result.
163.It OK: ...
164This types of message is used in verbose mode
165.Pq Fl v .
166.El
167.Sh AUTHORS
168.An Joe Marcus Clarke Aq marcus@FreeBSD.org
169.An Michael Haro Aq mharo@FreeBSD.org
170.An Jun-ichiro Hagino Aq itojun@itojun.org
171and
172.An Yoshishige Arai Aq ryo2@on.rim.or.jp .
173.Pp
174Many people have contributed patches and comments/suggestions.
175.Sh BUGS
176.Nm
177is not a magic wand, as described above.
178