.\" port.1
.\"
.\" Copyright (c) 2002 Apple Computer, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of Apple Computer, Inc. nor the names of its
.\"    contributors may be used to endorse or promote products derived from
.\"    this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 24, 2002
.Dt PORT 1 "Apple Computer, Inc."
.Os
.Sh NAME
.Nm port
.Nd build darwin ports
.Sh SYNOPSIS
.Nm
.Op Fl vdqfonausbckt
.Op Fl D Ar portdir
.Ar target
.Op Ar portname
.Op Ar options ...
.Op Ar variants ...
.Nm
.Ic provides
.Ar file
.Sh DESCRIPTION
.Nm
is designed to read and execute the build instructions of a darwin port. If no 
.Ar portdir
or
.Ar portname
is specified, the current working directory is assumed.
If no
.Ar target
is specified, the usage is displayed.
Port 
.Ar options 
are specified as key=value pairs and take precedence over individual port options and system-wide settings.
.Pp
Port
.Ar variants
are specified as +name, which indicates the variant is desired, and -name, which indicates the variant is not desired. In case of ambiguities, a port can be fully specified with the format
.Ar version_revision+variants
.Pp
Installed ports can be activated or deactivated without being uninstalled. A port can be installed if another version/variant is installed but deactivated.
.Pp
The
.Ic provides
command determines which port owns a given file.
.Sh OPTIONS
.Bl -tag -width -indent
.It Fl v
verbose mode (generate verbose messages)
.It Fl d
debug mode (generate debugging messages, implies
.Fl v )
.It Fl q
quiet mode (suppress messages)
.It Fl c
autoclean mode (execute clean after install)
.It Fl k
keep mode (don't autoclean after install)
.It Fl n
dont follow dependencies in upgrade (only for upgrading)
.It Fl a
upgrade all installed ports (only for upgrading)
.It Fl u
uninstall non-active ports when upgrading and uninstalling
.It Fl D
specify
.Ar portdir
.It Fl f
force mode (ignore state file)
.It Fl o
honor state files older than Portfile
.It Fl s
source-only mode (only build and install from source, ignores all binary archives, does not create/recreate binary archives) (only applies when archive mode is enabled)
.It Fl b
binary-only mode (only build and install from binary archives, ignores source, fails when no archive present, and does not create/recreate binary archives from source) (only applies when archive mode is enabled)
.It Fl t
enable trace mode debug facilities on platforms that support it
.El
.Sh USER TARGETS
.Nm
knows several targets. The ones commonly used by users of DarwinPorts are:
.Ss install
Install and activate
.Ar portname .
.Ss uninstall
Deactivate and uninstall
.Ar portname .
To uninstall all installed but inactive ports, specify
.Fl u .
For example:
.Pp
.Dl "port uninstall vim"
.Dl "port -u uninstall"
.Ss activate
Activate the installed
.Ar portname .
.Ss deactivate
Deactivate the installed
.Ar portname .
.Ss installed
List all installed ports.
.Ss outdated
List the installed ports that need upgrading.
.Ss upgrade
Upgrade the installed
.Ar portname .
To upgrade all ports, specify
.Fl a .
For example:
.Pp
.Dl "port upgrade vim"
.Dl "port -a upgrade"
.Pp
To upgrade
.Ar portname
wihtout following its dependencies, specify
.Fl n .
For example:
.Pp
.Dl "port -n upgrade ethereal"
.Ss selfupdate
Updates the DarwinPorts system, both the dports tree and if needed the base tools, installing the newest infrastructure if available. To update you would typically do:
.Pp
.Dl "sudo port -d selfupdate"
.Ss sync
Performs a sync operation only on the dports tree of a DarwinPorts installation, pulling in the latest revision available of the Portfiles. To update you would do:
.Pp
.Dl "sudo port -d sync"
.Ss clean
Clean the files used for building
.Ar portname .
To just remove the work files, specify
.Fl -work .
To remove the distribution files (tarballs, etc), specify
.Fl -dist .
To remove the archive(s) for the current version of a port, specify
.Fl -archive .
To remove the work files, distribution files and archives, specify
.Fl -all .
For example:
.Pp
.Dl "port clean --dist vim"
.Dl "port clean --archive vim"
.Pp
To remove only certain version(s) of a port's archives (
.Ar version
is any valid UNIX glob pattern), you can use:
.Pp
.Dl "port clean --archive vim 6.2.114"
.Pp
or:
.Pp
.Dl "port clean --archive vim '6.*'"
.Ss list
List all available ports.
.Ss search
Search for an available port whose name matches a regular expression.
.Pp
.Dl "port search vim"
.Pp
.Ss info
Displays the meta-information about an available
.Ar portname .
.Ss variants
Lists the build variants available for
.Ar portname .
.Ss deps
Lists the other ports that are required for building and running
.Ar portname .
.Ss contents
Lists the files installed by
.Ar portname .
.Ss version
Display the release number of the installed DarwinPorts infrastructure.
.Sh DEVELOPER TARGETS
The targets that are often used by Port developers are intended to provide access to the different phases of a Port's build process:
.Ss unarchive
Unpack the port from a pre-built binary archive. When archive mode is enabled, this command is called automatically, prior to
.Ar fetch ,
to check for an existing binary archive to unpack. If found, it is unpacked and all stages up to
.Ar install
are then skipped.
.Ss fetch
Fetches the distribution files required to build
.Ar portname .
.Ss extract
Extracts the distribution files for
.Ar portname .
.Ss patch
Applies any required patches to 
.Ar portname's
extracted distribution files.
.Ss configure
Runs any configure process for
.Ar portname .
.Ss build
Build
.Ar portname .
.Ss destroot
Installs
.Ar portname
to a temporary directory.
.Ss test
Tests
.Ar portname .
.Ss archive
Archive the port for a later
.Ar unarchive .
When archive mode is enabled, binary archives will be created automatically whenever an
.Ar install
is performed, or when the
.Ar archive
target is called explicitly.
.Ss livecheck
Check if the distfiles didn't change and can be fetched and if the software hasn't been
updated since the Portfile was modified.
.Sh PACKAGING TARGETS
There are also targets for producing installable packages of ports:
.Pp
.Ss pkg
Creates an OS X installer package of
.Ar portname.
.Ss mpkg
Creates an OS X installer metapackage of 
.Ar portname
and its dependencies.
.Ss dmg
Creates an internet-enabled disk image containing an OS X package of
.Ar portname .
.Ss rpmpackage
Creates an RPM package of
.Ar portname .
.Sh EXAMPLE
The following demonstrates invoking
.Nm
with the "extract" target on
.Ar portdir
"textproc/figlet" and extract.suffix set to ".tgz":
.Pp
.Dl "port extract -D textproc/figlet extract.suffix=.tgz"
.Pp
.Sh DIAGNOSTICS
.Ex -std
.Sh SEE ALSO
.Xr portfile 7 ,
.Xr porthier 7 ,
.Xr portstyle 7
.Sh AUTHORS
.An Landon Fuller Aq landonf@opendarwin.org
.An Kevin Van Vechten Aq kevin@opendarwin.org
.An Jordan K. Hubbard Aq jkh@opendarwin.org
.An Ole Guldberg Jensen Aq olegb@opendarwin.org
.An Robert Shaw Aq rshaw@opendarwin.org
.An Chris Ridd Aq cjr@opendarwin.org