PORTSCAN(1)

NAME
portscan - scan the FreeBSD Ports Collection

SYNOPSIS
portscan [-l logdir] [-q regexp] [-o flag] -p portsdir [origin ...]

DESCRIPTION
portscan scans the FreeBSD Ports Collection for variable and target misspellings and other mistakes. At the moment it flags unknown variables and targets.

The entire collection is scanned if no port origins are given.

The following options are available:

-l logdir
    Save the log result into logdir instead of outputting to stdout. The log files will be dated and will include the current SVN revision or Git commit hash of portsdir. portscan creates portscan-latest.log and portscan-previous.log symlinks to point to the latest or previous results.

-q regexp
    Filter returned values based on the given regular expressions.

-o flag
    Select what to scan for. This flag can be specified multiple times. If it is not given portscan will default to categories, clones, option-default-descriptions, unknown-targets, and unknown-variables.

-o all
    Enable all of the below scanners.

-o categories
    Check categories for unhooked, wrong, or misordered entries.

-o clones
    Scan for variables that are set twice.

-o option-default-descriptions [=editdist]
    Report redundant option descriptions that match the default descriptions in Mk/bsd.options.desc.mk. editdist is the edit distance between the default and port option description. It defaults to 3.

-o options
    Include port options and option groups in the result. Use -q to filter the options.

-o unknown-targets
    Scan for unknown or unrecognized targets.

-o unknown-variables
    Scan for unknown or unrecognized variables.

-o variable-values [=regex]
    Output variable values. If unconstrained this will output the value of every variable one by one. Use -q to filter the values and regex to select only a subset of all variables.

-p portsdir
    The port directory to scan. This argument is mandatory.

OUTPUT
The output is composed of whitespace delimited fields type, origin, name. type is made up of the following characters:

C   Unsorted category Makefile

Ce  Nonexistent port referenced by category Makefile

Cu  Unhooked port missing in category Makefile

E   Parser or IO errors encountered during the scan

OD  Redundant port option description that matches the default one

OG  Port option group

O   Port option

V   Unknown variable

Vc  Variable that is set twice or more

Vv  Variable value

T   Unknown target

origin is the origin of the variable or target.

name is the variable or target name. name might contain whitespace as part of its value. name never starts with whitespace. Any tools that consumes portscan output should keep this in mind.

EXIT STATUS
portscan will exit with one of the following values:

0   The collection was scanned successfully. An exit status of 0 does not mean there were no issues in the scanned ports.

1   An error occurred.

2   There were no changes when compared to previous results. Only possible when -l was passed to portscan.

EXAMPLES
The output can have many lines (approximately 12000 lines at the time of writing) and will have many false positives. To not be overwhelmed it is best to run portscan daily in an iterative manner and compare the results with diff(1) to flag new problems:

    portscan -l . -p /usr/ports
    diff -u portscan-previous.log portscan-latest.log

Scan category Makefiles for mistakes:

    portscan -o categories -p /usr/ports

SEE ALSO
portclippy(1), portedit(1), portfmt(1)

AUTHORS
Tobias Kortkamp <tobik@FreeBSD.org>