NAME

port — FreeBSD Port Tools front-end script

SYNOPSIS

DESCRIPTION

port simplifies testing and submitting Problem Reports (PRs) with a new FreeBSD port, or change/update to an existing ports.

port has the following commands:

create

create a new port from a template

diff

generate diff against original port version

fetch

fetch distfile(s) of new port version

help

display summary for port commands

submit

submit PR with new port, or port change/update

test

automate testing a new port or a port update

COMMANDS

create

Creates a directory for new port from a template

Synopsis:

port create name

name

name of port to create. Generates an error if a file or directory with this name already exists in the current directory.

Example:

% port create libgpg-error

This would create a new directory named libgpg-error and corresponding Makefile, distinfo, pkg-descr, pkg-plist files.

diff

Generates shar(1) file (for new ports) or patch file in unified diff(1) format against original port (for changes or updates), suitable for submitting as PR.

Generated file then passed to the viewer specified in ~/.porttools configuration file. Default viewer is ydiff(1) if present, otherwise - more(1).

Synopsis:

port diff [-h] [-d mode] [-m mode]

-h

display usage summary for this command.

-d mode

select diff generation mode:

GIT

diff against GIT repository (default).

dir

diff against original version of the port in the Ports tree with root at dir (for example, /usr/ports).

suffix

diff against original version of the port with specified directory suffix (for example, .orig) in the parent directory.

-m mode

Override automatic mode selection:

new

generate SHAR as if the port was new

Example:

% port diff -d GIT

This would generate unified diff of modified checked-out working copy of the port against GIT repo.

fetch

Fetch one or more distfiles of new or updated port version and updates checksums. It is a shortcut for typing the following at the shell prompt:

% rm -f distinfo && make fetch && make makesum

Synopsis:

port fetch

Accepts no additional arguments.

help

Displays summary for port commands by dynamically scanning command scripts located in ${PREFIX}/share/porttools.

Synopsis:

port help

Accepts no additional arguments.

submit

Submits PR with new port, or changed or updated port.

Run this command from a directory containing the new port. First, it executes portlint(1) (unless -L option was specified) to verify the port files for correctness, then it automatically detects mode - new, change or update (unless overridden by -m mode option), generates either a shar(1) file (for new ports) or patch file in unified diff(1) format (for changed or updated ports). This file is named according to port's name and version.

Finally, it prepares PR for submittal via send-pr(1) by automatically filling in most of the fields in the standard form, attaching the generated shar or patch file to the PR. If the PR submittal was successful, shar/patch file could be optionally saved to ${ARCHIVE_DIR} if that variable is defined and points to a writable directory.

Synopsis:

port submit [-hL] [-m mode] [-d mode] [-s severity] [-p priority]

-h

display usage summary for this command.

-d mode

select diff generation mode - see the port diff command above for details.

-m mode

Overrides automatic detection of operation mode:

new

submitting new port.

change

changing (but not updating) existing port.

update

updating existing port to newer version.

-s severity

Sets severity of the PR. Valid values are: non-critical, serious, critical. Default is non-critical.

-p priority

Sets priority of the PR. Valid values are: low, medium, high. Default is low.

-L

Skips running portlint(1). Using this option will generate a warning and it strongly discouraged.

-P

Don't send the PR. Just print to stdout (see -P in send-pr(1)).

test

Automates the process of testing a new port (or a port update) by going through the steps recommended by the FreeBSD Porter's Handbook:

• build
• install
• package
• deinstall

Note: build phase can be run under a regular user account, all others require root privileges, so port automatically invokes sudo(1).

The command stops if any errors are encountered during the process.

To avoid interfering with the ports already installed on the build host, PREFIX variable is set so the installation is done to a directory inside BUILDROOT (e.g. /tmp/${PKGNAME}), and PKG_DBDIR points to a temporary package database (e.g. /tmp/pkg_db.xxxxxxx). This allows to test an update to a port already installed on the build system (same or previous version).

This command also detects and lists any files not listed in pkg-plist during ‘Extra files check’ phase.

Synopsis:

port test [-h] [-lLbipcC] [-- port knobs]

-h

display usage summary for this command.

-l

Run portlint(1) only.

-L

Do not run portlint(1).

-b

Stop after build phase.

-i

Stop after install phase.

-p

Stop after package phase.

-c

Do NOT clean before port.

-C

Do NOT clean after port.

--

End of port options. Port knobs may follow.

Examples:

% port test -i -C

This would build and install the port, but would not delete the installed files. This command may be used to manually examine the installed files for correctness.

% port test -- NOPORTDOCS=yes

Tests port without installing documentation (i.e. pass NOPORTDOCS=yes to all make phases). Note: you can list as many port knobs/parameters as needed.

FILES

~/.porttools

FreeBSD Port Tools configuration file. It is generated automatically if missing. See porttools(5) for detailed description of the format.

SEE ALSO

git(1), ydiff(1), diff(1), more(1), portlint(1), shar(1), sudo(1), porttools(5), ports(7)

BUGS

Please report any bugs to Steven Kreuzer ⟨skreuzer@FreeBSD.org⟩.