.\" port.1
.\"
.\" Copyright (c) 2004-2011 The MacPorts Project
.\" Copyright (c) 2002-2003 Apple 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 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 April 29, 2007
.Dt PORT 1 "MacPorts"
.Os
.Sh NAME
.Nm port
.Nd operate on individual or multiple Mac
.Ar ports
.Sh SYNOPSIS
.Nm
.Op Fl bcdfknopqRstuvy
.Op Fl D Ar portdir
.Op Fl F Ar cmdfile
.Op Ar action
.Op Ar actionflags
.Op Oo Ar portname | pseudo-portname | port-url Oc
.Op Oo Ar @version Oc Oo +/-variant ... Oc ... Oo option=value ... Oc
.Sh DESCRIPTION
.Nm
is designed to operate on individual or multiple Mac
.Ar ports ,
optionally within a single call, based on the requested
.Ar action .
If no
.Ar portdir
or
.Ar portname
is specified, the current working directory is assumed; if no
.Ar action
is specified the port command enters interactive mode, in which commands are read via stdin. Batch commands may be
passed via a
.Ar cmdfile .
Port 
.Ar options 
are passed as key=value pairs and take precedence over individual
.Ar portname
options as specified in its Portfile and system-wide settings.
.Pp
Port
.Ar variants
can specified as
.Ar +name ,
which indicates the variant is desired, or
.Ar -name ,
indicating the contrary. In case of ambiguities, a port can be fully specified with the
.Ar @version_revision+variants
format.
.Pp
Installed ports can be activated or deactivated without being uninstalled. A port can be installed if all other
version/variant(s) combinations installed at any given moment are deactivated.
.Pp
The
.Nm
command knows various
.Ar pseudo-portnames
that will expand to the specified set of ports from the available ports tree(s). These may be used in place of a
.Ar portname .
Common options are:
.Pp
.Bl -bullet -offset indent -compact
.It
.Ar all :
all the ports in each ports tree listed in
.Ar sources.conf
.Pp
.It
.Ar current :
the port in the current working directory.
.Pp
.It
.Ar active :
set of installed and active ports.
.Pp
.It
.Ar inactive :
set of installed but inactive ports.
.Pp
.It
.Ar actinact :
set of installed ports that have both an active version and one or more inactive versions.
.Pp
.It
.Ar installed :
set of all installed ports.
.Pp
.It
.Ar uninstalled :
ports in the ports tree(s) that aren't installed.
.Pp
.It
.Ar outdated :
installed ports that are out of date with respect to their current version/revision in the ports tree(s)
.Pp
.It
.Ar obsolete :
set of ports that are installed but no longer exist in any port tree
.Pp
.It
.Ar requested :
installed ports that were explicitly asked for.
.Pp
.It
.Ar unrequested :
installed ports that were installed only to satisfy dependencies.
.Pp
.It
.Ar leaves :
installed ports that are unrequested and have no dependents.
.Pp
.El
Sets of ports can also be specified with
.Ar pseudo-portname selectors ,
which expand to the ports in which the value of the
.Ar Portfile
key corresponding to the selector's name (in either singular or plural form where applicable)
matches the given regular expression. Usage is:
.Ar selector:regex
.Pp
Available selectors are:
.Pp
.Bl -bullet -offset indent -compact
.It
.Ar name
.It
.Ar version
.It
.Ar revision
.It
.Ar epoch
.It
.Ar variant
.It
.Ar variants
.It
.Ar category
.It
.Ar categories
.It
.Ar maintainer
.It
.Ar maintainers
.It
.Ar platform
.It
.Ar platforms
.It
.Ar description
.It
.Ar long_description
.It
.Ar homepage
.It
.Ar portdir
.El
.Pp
.Pp
Other pseudo-portname selectors match ports which have a particular relationship to
another port. These will match ports that are direct or recursive dependencies or dependents
of the given portname:
.Pp
.Bl -bullet -offset indent -compact
.It
.Ar depof
.It
.Ar rdepof
.It
.Ar dependentof
.It
.Ar rdependentof
.El
.Pp
.Ar portnames
containing valid UNIX glob patterns will also expand to the set of matching ports. Any
.Ar action
passed to
.Nm
will be invoked on each of them. For example:
.Pp
.Dl port list variant:no_ssl
.Dl port uninstall name:sql
.Dl port echo depof:mysql5
.\" COMMENT: glob pattern expansion in portnames:
.\" write an example here that illustrats better glob pattern expansion in portnames, but that does not employ
.\" logical operators (and, or, not, !) because I still haven't gotten to them yet.
.Dl port echo apache*
.Pp
Logical operators "and", "or", "not", "!", "(" and ")" may be used to combine individual
.Ar portnames ,
port glob patterns and/or
.Ar pseudo-portnames
to construct complex port expressions that expand to the set of matching ports. For example:
.Pp
.Dl port upgrade installed and "apache*"
.Dl port echo maintainer:jberry and uninstalled and \e(\ category:java and not commons*\ \e)
.\" COMMENT: more complex exmaples here would be useful.
.\" PENDING: port-url explanation. Proposed text:
.\".Pp
.\"A
.\".Ar portname
.\"may also be specified as a URL pointing to the location of the
.\".Ar portdir
.\" ...
.Pp
The
.Nm
command also recognizes several command line flags and
.Ar targets :
.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 n
don't upgrade dependencies (affects upgrade and install)
.It Fl R
also upgrade dependents (only affects upgrade) - note that this does not upgrade dependents' dependencies
.It Fl u
uninstall non-active ports when upgrading and uninstalling
.It Fl f
force mode (ignore state file)
.It Fl o
honor state files older than Portfile
.It Fl s
source-only mode (build and install from source, do not attempt to fetch binary archives)
.It Fl b
binary-only mode (build and install from binary archives, ignore source, abort if no archive available)
.It Fl c
autoclean mode (execute clean after install)
.It Fl k
keep mode (don't autoclean after install)
.It Fl D
specify
.Ar portdir
.It Fl F
Read and process the
.Ar file
of commands specified by the argument. If the argument is '-', then read commands from stdin. If the option is given multiple times, then multiple files will be read.
.It Fl p
Despite any errors encountered, proceed to process multiple ports and commands.
.It Fl y
Perform a dry run. All of the steps to build the ports and their dependencies are computed, but not actually performed. With the verbose flag, every step is reported; otherwise there is just one message per port, which allows you to easily determine the recursive deps of a port (and the order in which they will be built).
.It Fl t
enable trace mode debug facilities on platforms that support it (Mac OS X). This feature is two-folded. It consists in automatically detecting and reporting undeclared dependencies based on what files the port reads or what programs the port executes. In verbose mode, it will also report unused dependencies for each stage of the port installation. It also consists in forbidding and reporting file creation and file writes outside allowed directories (temporary directories and ${workpath}).
.El
.Sh USER TARGETS
Targets most commonly used by regular MacPorts users are:
.Ss search
Search for an available port. By default, the search string is treated as a case-insensitive glob,
and is matched against the name and description fields. To have the search string treated as
a regular expression, as a literal, or in a case-sensitive manner, use
.Fl -regex,
.Fl -exact,
or
.Fl -case-sensitive,
respectively. To match against a different set of fields, use one or more
.Fl -<field-name>
options. To display each result on a single line, use
.Fl -line.
For example:
.Pp
.Dl "port search vim"
.Dl "port search --regex --depends_build 'docbook.*[0-9]+'"
.Pp
.Ss info
Displays meta-information available for
.Ar portname .
Specific meta-information may be requested through an option such as
.Fl -maintainer
or
.Fl -category
(recognized field names are those from the PortIndex, see "port help
info" for a complete list). If no specific fields are specified, a
useful default collection of fields will be displayed. If the global option
.Fl q
is in effect, the meta-info fields will not be labeled.
If the option
.Fl -line
is provided, all such data will be consolidated into a single line per port,
suitable for processing in a pipe of commands.
If the option
.Fl -pretty
is provided, the information will be formatted in a somewhat more
attractive fashion for human readers. This is the default when no
options at all are specified to info.
If the option
.Fl -index
is provided, the information will be pulled from the PortIndex rather than
from the Portfile (in this case variant information, such as dependencies,
will not affect the output).
.Pp
For example:
.br
.Dl "port info vim +ruby"
.Dl "port info --category --name apache*"
.Dl "port -q info --category --name --version category:java"
.Dl "port info --line --category --name all"
.Dl "port info --pretty --fullname --depends gtk2"
.Dl "port info --index python24"
.Ss notes
Displays notes for 
.Ar portname
(useful information concerning setup and use of the port).
.Ss variants
Lists the build variants available for
.Ar portname .
.Ss deps
Lists the other ports that are required to build and run
.Ar portname .
This is simply an alias for "info --pretty --fullname --depends".
.Ss rdeps
Recursively lists the other ports that are required to build and run
.Ar portname .
To display the full dependency tree instead of only showing each port once, use
.Fl -full .
To take dependency information from the PortIndex instead of the Portfile
(faster, but does not take variant selections into account), use
.Fl -index .
To exclude dependencies that are only needed at build time (i.e.
depends_fetch, depends_extract, depends_build), use
.Fl -no-build .
.Ss dependents
Lists the installed ports that depend on the port
.Ar portname .
.Ss rdependents
Recursively lists the installed ports that depend on the port
.Ar portname .
To display the full tree of dependents instead of only showing each port once, use
.Fl -full .
.Ss install
Install and activate
.Ar portname .
.Ss uninstall
Deactivate and uninstall
.Ar portname .
To uninstall all installed but inactive ports, use
.Fl u .
To recursively uninstall all dependents of
.Ar portname
before uninstalling the port itself, use
.Fl -follow-dependents .
To uninstall
.Ar portname
and then recursively uninstall all its dependencies, use
.Fl -follow-dependencies .
This will not uninstall dependencies that are marked as requested or that have other dependents.
.Pp
For example:
.Pp
.Dl "port uninstall vim"
.Dl "port -u uninstall"
.Dl "port uninstall --follow-dependents python24"
.Ss select
For a given
.Ar group ,
selects a
.Ar version
to be the default by creating appropriate symbolic links.
For instance,
.Ic "python"
might be linked to
.Ic "python2.6" .
Available select groups are installed as subdirectories of
.Ar ${prefix}/etc/select/ .
To list the available versions in a group, use
.Fl -list .
To see which version is currently selected for a group, use
.Fl -show .
To change the selected version for a group, use
.Fl -set .
.Pp
For example:
.Pp
.Dl "port select --list python"
.Dl "port select --show gcc"
.Dl "port select --set gcc mp-gcc44"
.Pp
.Ss activate
Activate the installed
.Ar portname .
.Ss deactivate
Deactivate the installed
.Ar portname .
.Ss setrequested
Mark
.Ar portname
as requested.
.Ss unsetrequested
Mark
.Ar portname
as unrequested.
.Ss installed
Show the installed versions and variants for
.Ar portname .
If no
.Ar portname
is given, all installed ports are shown.
.Ss location
Print the install location of a given port.
.Ss contents
Lists the files installed by
.Ar portname .
.Ss provides
Determines which port owns a given file and can take either a relative or absolute path. For example:
.Pp
.Dl "port provides /opt/local/etc/irssi.conf"
.Dl "port provides include/tiff.h"
.Ss sync
Performs a sync operation only on the ports tree of a MacPorts installation, pulling in the latest
revision available of the
.Ar Portfiles
from the MacPorts rsync server. To update you would normally do:
.Pp
.Dl "sudo port -d sync"
.Pp
If any of the ports tree(s) uses a file: URL that points to a local subversion working copy,
.Ic sync
will perform an
.Ic "svn update"
on the working copy with the user set to the owner of the working copy.
.Ss outdated
List the installed ports that need upgrading.
.Ss upgrade
The upgrade target works on a port and its dependencies. If you
want to change this behaviour, look at the switches for n (no
dependencies) and R (dependents) below.
.Pp    
Upgrade the installed
.Ar portname .
For example:
.Pp
.Dl "port upgrade vim"
.Pp
To upgrade all installed ports:
.Pp
.Dl "port upgrade installed"
.Pp
To upgrade
.Ar portname
and the ports that depend on it:
.Pp
.Dl "port -R upgrade libiconv"
.Pp
To force an upgrade (rebuild) use:
.Pp
.Dl "port upgrade --force vim"
.Pp
To upgrade
.Ar portname
without following its dependencies, use
.Fl n .
For example:
.Pp
.Dl "port -n upgrade wireshark"
.Pp  
Note that in selecting the variants to use in the upgraded build of the 
port, any variants specified on the command line take highest precedence, 
then the variants active in the latest installed version of the port, and 
finally the global variants specified in variants.conf, if any.  Note that 
upgrade will not normally rebuild a port only to change the selected 
variants; you can either specify --enforce-variants, or deactivate the port and reinstall it 
with different variants. 
.Ss clean
Clean the files used for building
.Ar portname .
To just remove the work files, use the
.Fl -work
.Ar actionflag .
This is the default when no flag is given.
To remove the distribution files (tarballs, etc), specify
.Fl -dist .
To remove the work files, distribution files and logs, pass
.Fl -all .
To remove log files for certain port, pass
.Fl -logs .
For example:
.Pp
.Dl "port clean --dist vim"
.Dl "port clean --logs vim"
.Pp
.Ss log
Parses and shows log files for
.Ar portname .
To filter log files by some criterions use
.Fl -phase 
to specify phase you want to show and
.Fl -verbosity
to specify message category (msg, info, debug)
For example:
.Pp
.Dl "port log --phase configure vim"
.Dl "port log --phase fetch --verbosity debug vim"
.Pp
.Ss echo
Writes to stdout the arguments passed to
.Nm .
This follows the expansion of
.Ar pseudo-portnames ,
portname glob patterns,
.Ar pseudo-portname selectors
and the evaluation of port expressions.
.Nm echo 
may be used to determine the exact set of ports to which a given string of arguments will expand, without performing any further operations on them. For example:
.Pp
.Dl port echo category:net
.Dl port echo maintainer:jmpp and name:netw
.Dl port echo maintainer:jmpp and \e(\ net* or category:text\ \e)
.Pp
.Ss list
If no argument is given, display a list of the latest version of all available ports.
If portname(s) are given as arguments, display a list of the latest version of each port.
.Ss mirror
Create/update a local mirror of distfiles used for ports given on the command line.  The filemap database can be reset by using the
.Fl -new
option (though if no database is found, it will be created automatically).
If the fetched file does not match the checksum given in the Portfile, it is
deleted.  This can be used with
.Ar pseudo-portnames ,
eg,
.Ar all ,
to mirror everything.  Note that if you use
.Ar all ,
you'll most likely want to use
.Fl p
so
.Nm
doesn't quit on the first download failure.
.Ss version
Display the release number of the installed MacPorts infrastructure.
.Ss platform
Display the platform information for the current system.
.Ss selfupdate
Updates the MacPorts system, ports tree(s) and base tools if needed, from the MacPorts rsync server,
installing the newest infrastructure available. To update you would typically do:
.Pp
.Dl "sudo port selfupdate"
.Pp
See
.Ic sync
for more information about updating ports tree(s).
.Ss load
Provides a shortcut to using launchctl to load a port's daemon (as installed
in /Library/LaunchDaemons).  It runs:
.Pp
.Dl launchctl load -w /Library/LaunchDaemons/org.macports.${port}.plist
.Ss unload
A shortcut to launchctl, like load, but unloads the daemon.
.Ss gohome
Loads the home page for the given 
.Ar portname 
in the default web browser.
.Ss usage
Displays a condensed usage summary.
.Ss help
Displays a summary of all available actions and port command syntax on stdout.
.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 dir
Displays the path to the directory containing
.Ar portname .
.Ss work
Displays the path to the work directory for
.Ar portname .
.Ss cd
Changes the current working directory to the one containing
.Ar portname .
Only useful in interactive mode.
.Ss file
Displays the path to the Portfile for
.Ar portname .
.Ss url
Displays the URL for the path of the given
.Ar portname ,
which can be passed as port-url
.Ss cat
Concatenates and prints the contents of
.Ar Portfile
on stdout.
.Ss edit
Opens
.Ar Portfile 
with your default editor specified in your shell's environment variable. Alias
.Ar ed
also invokes this command.
.Pp
You can also use the
.Fl -editor
flag on the command line to specify an alternative editor. For example:
.Dl port edit --editor nano apache2
.Pp
.Ss ed
An alias for
.Ic edit .
.Ss fetch
Fetches the distribution files required to build
.Ar portname .
.Ss checksum
Compute the checksums of the distribution files for 
.Ar portname ,
and compare them to the checksums listed in 
.Ar Portfile .
.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 lint
Verifies Portfile for
.Ar portname .
To nitpick about whitespace and patchfile names, use
.Fl -nitpick .
.Ss distcheck
Check if the distfiles haven't changed and can be fetched.
.Ss distfiles
Display each distfile, its checksums, and the URLs used to fetch it.
.Ss livecheck
Check if the software hasn't been updated since the Portfile was last 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 mdmg
Creates an internet-enabled disk image containing an OS X metapackage of
.Ar portname
and its dependencies.
.Ss rpm
Creates an RPM binary package of
.Ar portname ,
similar to a tgz "archive".
.Ss srpm
Creates a SRPM source package of
.Ar portname ,
similar to a xar "portpkg".
.Ss dpkg
Creates a DEB binary package of
.Ar portname .
.Sh EXAMPLES
The following demonstrates invoking
.Nm
with the
.Ar 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 FILES
.Bl -tag -width
.It Va ${prefix}/etc/macports/macports.conf
Global configuration file for the MacPorts system.
.It Va ${prefix}/etc/macports/sources.conf
Global listing of the ports trees used by MacPorts. This file also enables rsync synchronization.
.It Va ${prefix}/etc/macports/variants.conf
Global variants used when a port is installed.
.It Va ~/.macports/macports.conf
User configuration file for the MacPorts system. It overrides the global
.Ar macports.conf
file.
.El
.Sh DIAGNOSTICS
.Ex -std
.Sh SEE ALSO
.Xr macports.conf 5 ,
.Xr portfile 7 ,
.Xr portgroup 7 ,
.Xr portstyle 7 ,
.Xr porthier 7
.Sh AUTHORS
.An "Landon Fuller" Aq landonf@macports.org
.An "James Berry" Aq jberry@macports.org
.An "Jordan K. Hubbard" Aq jkh@macports.org
.An "Juan Manuel Palacios" Aq jmpp@macports.org
.An "Kevin Van Vechten" Aq kevin@opendarwin.org
.An "Ole Guldberg Jensen" Aq olegb@opendarwin.org
.An "Robert Shaw" Aq rshaw@opendarwin.org
.An "Chris Ridd" Aq cjr@opendarwin.org
.An "Matt Anton" Aq matt@opendarwin.org
.An "Joe Auty" Aq joe@opendarwin.org