.\"     $OpenBSD: portcheck.1,v 1.1 2018/06/26 05:38:49 espie Exp $
.\"
.\" Copyright (c) 2013 Vadim Zhukov
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 26 2018 $
.Dt PORTCHECK 1
.Os
.Sh NAME
.Nm portcheck
.Nd validate a port before submitting
.Sh SYNOPSIS
.Nm
.Op Fl dNP
.Op Fl p Ar portsdir
.Op Fl x Ar pattern
.Pp
.Nm
.Fl A
.Op Fl dP
.Op Fl p Ar portsdir
.Op Fl x Ar pattern
.Op Ar subdir ...
.Sh DESCRIPTION
.Nm
is used to validate the
.Ox
port or port hierarchy in current directory.
It should be used before submitting ports for review to avoid making
common mistakes.
.Nm
verifies that directory and file structure for a port is in place and
that no bogus files exist.
.Pp
When it's done,
.Nm
will print detected value of port's
.Ev PKGPATH
to standard output, unless it fails in detection.
In the latter case, the
.Fl p
option should be provided.
All other (error) messages from
.Nm
end up on standard error output.
.Pp
By default,
.Nm
automatically picks up nearest parent directory named
.Dq ports ,
with an optional
.Dq mystuff
or
.Dq openbsd-wip
subdirectory component, as the ports root directory.
For example: if the port being imported is located in
.Pa /home/joe/cvs/ports/openbsd-wip/devel/p5-Foo ,
then the root ports directory will be detected as being
.Pa /home/joe/cvs/ports/openbsd-wip .
To override this behaviour, see the
.Fl p
option.
.Pp
The following options are available:
.Bl -tag -width Ds
.It Fl A
Intended for running
.Nm
on the whole ports tree, i.e., the one lying in
.Ev PORTSDIR .
This option adds several ignore patterns (see
.Fl x
option description) and disables some other checks (e.g., for missing
distinfo).
.Ev PKGPATH
determining and printing won't be done.
Implicit change of working directory to the ports tree root is done
before starting any checks.
Also, in this mode one or more
.Ar subdir
arguments could be specified, to narrow the check only for given
subdirectories of ports tree root.
.It Fl d
Show debugging information such as calling of check routines.
.It Fl P
Disable expensive checks that use
.Dq print-plist-with-depends
target, e.g., proper usage of
.Xr gtk-update-icon-cache 1 ,
.Xr update-desktop-database 1
and
.Xr update-mime-database 1 .
.It Fl p Ar portsdir
Forces the given directory to be treated as ports root directory.
Cancels autodetection of the root ports directory made by default.
This option is useful, e.g., when you have a temporary ports tree in
a non-standard location.
.It Fl N
Intended to be used when working on new ports.
Enables the checks like the presence of REVISION markers and non-0.0
.Ev SHARED_LIBS .
It also enables checks for the presence of CVS directories that could
be left by mistake when creating a new port based on another one.
.It Fl x
Excludes files and subdirectories matching given shell globbing pattern
from any checks.
Note that matching is done against relative path, and not against
absoulte path or base name either.
I.e., to exclude the
.Dq x11/kde4/libs/logs
from checks, you must pass the whole line as argument, not just
.Dq logs .
Multiple -x options may be specified.
.El
.Sh EXAMPLES
To validate a new port you've just prepared, go to port's directory and
run:
.Bd -literal -offset indent
$ portcheck -N
.Ed
.Pp
If you were working on updating of an existing port in CVS tree:
.Bd -literal -offset indent
$ portcheck
.Ed
.Pp
To run a global check of the whole
.Dq devel
category in ports tree, use the
.Fl A
option instead:
.Bd -literal -offset indent
$ portcheck -Ap /usr/ports devel
.Ed
.Sh SEE ALSO
.Xr portimport 1
.Sh HISTORY
This utility was split from
.Xr portimport 1
in 2013 and first appeared in
.Ox 5.5 .