path: root/ports-mgmt/portmaster/files/portmaster.8

.\" Copyright (c) 2006-2007 Doug Barton dougb@FreeBSD.org
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
.\"
.\" $FreeBSD$
.\"
.Dd January 9, 2007
.Dt PORTMASTER 8
.Os
.Sh NAME
.Nm portmaster
.Nd manage your ports without external databases or languages
.Sh SYNOPSIS
.Nm
.Op Fl CGgntv [B|b] [uf|i] [D|d] m Ar arguments for make
.Op Ar full name of port directory in /var/db/pkg
.Nm
.Op Fl CGgntv [B|b] [uf|i] [D|d] m Ar arguments for make
.Op Ar full path to /usr/ports/foo/bar
.Nm
.Op Fl CGgntv [B|b] [uf|i] [D|d] m Ar arguments for make
.Op Ar Multiple full names/paths from either of the above
.Nm
.Op Fl CGgntv [B|b] [uf|i] [D|d] m Ar arguments for make
.Op Ar glob pattern from /var/db/pkg
.Nm
.Op Fl CGgntv [B|b] [uf|i] [D|d] m Ar arguments for make
.Op Fl p Ar port directory in /usr/ports
.Nm
.Op Fl CGgntv [B|b] [uf|i] [D|d] m Ar arguments for make
.Op . [Use in /usr/ports/foo/bar to build that port]
.Nm
.Op Fl CGgntv [B|b] [uf|i] [D|d] m Ar arguments for make
.Fl o Ar <new port dir in /usr/ports> <installed port>
.Nm
.Op Fl CGgntv [B|b] [uf|i] [D|d] m Ar arguments for make
.Fl r Ar name/glob of port in /var/db/pkg
.Nm
.Op Fl CGgntv [B|b] [uf|i] [D|d] m Ar arguments for make
.Fl a
.Nm
.Fl [l|L]
.Nm
.Op Fl b [D|d]
.Fl e Ar name of port directory in
.Pa /var/db/pkg
.Nm
.Op Fl b [D|d]
.Fl s
.Nm
.Fl h
.Pp
.Sh DESCRIPTION
The
.Nm
utility is a simple tool for managing your ports.
It uses no external database to track what you
have installed.
Rather it uses the existing ports infrastructure,
including what is located in
.Pa /var/db/pkg .
The focus of this tool is to keep the dependency
tracking information for your ports up to date,
which allows you to update a specific port without
having to update all of the ports
.Dq above
it.
In the rare case where you do need to recompile
ports which depend on a port you are updating,
the
.Fl r
option exists to accomplish this.
.Pp
By default
.Nm
will first recurse through the port to update,
and all of its dependencies (if any) to handle
any port OPTIONS via the 'make config' interface.
It will then start building all ports that need
updating.
While recursing through dependencies,
a 'make checksum' process will be launched
in the background to either verify that the
correct distfiles are available,
or start downloading the new ones.
If you stop
.Nm
with ^C, an attempt will be made to kill off all
the child processes started for this purpose.
.Pp
If the recursion through the ports for 'make
config' does not find a port that needs updating,
the dependency check step will be skipped prior
to building the port specified on the command line.
In addition to this optimization,
information about up-to-date dependencies,
choices made on which ports to build for
interactive mode,
and ports already visited for 'make config' are
all cached to enhance performance and prevent
duplicated efforts.
.Pp
While recursing through the dependencies,
if a port is marked IS_INTERACTIVE this will
be flagged.
In the absence of this notification,
under normal circumstances the only user interaction
required after the port starts building is to answer
questions about the deletion of stale distfiles.
This can be eliminated with the
.Fl d
option.
.Pp
While checking dependencies, if a port has CONFLICTS
set, the list will be checked against your installed ports,
and if you have installed an alternate version of a port
that is required by the port you are building,
it will be used in place of the default dependency.
.Pp
If there is no
.Fl B
option specified when updating an existing port,
a backup package will be created before
.Xr pkg_delete 1
is called.
If there is no
.Fl b
option specified, the backup package will be deleted
once the new version of the port is successfully installed.
If the installation fails for whatever reason,
a helpful message will be printed, along with instructions
on where to find the backup package.
.Pp
At the conclusion of a successful installation,
whether of an individual port, a list of ports,
or when using the
.Fl a
option, any
.Pa pkg-message
files that were installed during the installation
will be displayed.
.Sh OPTIONS
The options are as follows:
.Bl -tag -width F1
.It Fl B
prevents creation of the backup package for the installed port
.It Fl C
prevents 'make clean' being run in port directory
.It Fl G
prevents the recursive 'make config'
.It Fl b
create and keep a backup package of an installed port
.It Fl g
create a package of the new port
.It Fl n
do not actually perform any updates
.It Fl t
recurse dependencies thoroughly, using all-depends-list
.It Fl v
verbose output
.It Fl u
unattended mode, accepts defaults for all
.Nm
dialogues
.It Fl f
always rebuild ports (overrides -i)
.It Fl i
interactive update mode
.It Fl D
prevents cleaning of distfiles
.It Fl d
always clean distfiles
.It Fl m Ar arguments for make
any arguments to supply to
.Xr make 1
.It Fl p Ar port directory in /usr/ports
Specify the full path to a port directory
.It Fl o Ar <new port dir in /usr/ports> <installed port>
Replace the installed port with a port from a different origin
.It Fl r Ar name/glob of port in /var/db/pkg
rebuild port, and all ports that depend on it
.It Fl a
check all ports, update as necessary
.It Fl l
list all installed ports by category
.It Fl L
list all installed ports by category, and search for updates
.It Fl e Ar name of port directory in /var/db/pkg
Expunge port using
.Xr pkg_delete 1 ,
and optionally removing all distfiles.
Calls
.Fl s
mode after it is done expunging in case removing
the port causes a dependency to no longer be
necessary.
.It Fl s
clean out stale ports that used to be depended on
.It Fl h
display help file
.El
.Sh MAKE ENVIRONMENT
If the directory pointed to by the PKGREPOSITORY
variable exists (by default
.Pa /usr/ports/packages/All )
then it will be used to store new and backup packages.
.Pp
The UPGRADE_TOOL variable is set to
.Dq portmaster ,
and the UPGRADE_PORT and UPGRADE_PORT_VER variables
are set to the full package name string and version
of the existing package being replaced, if any.
.Sh FILES
.Bl -tag -width ".Pa $HOME/.portmasterrc" -compact
.It Pa /etc/portmaster.rc
.It Pa $HOME/.portmasterrc
Optional system and user configuration files.
The variables set in the script's getopts routine
can be specified in these files to enable those options.
.It Pa /var/db/pkg/*/+IGNOREME
If this file exists,
.Nm
will ignore this port for the purpose of dependency
updates.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
The following is an example of a typical usage
of the
.Nm
command:
.Pp
.Dl "portmaster fooport-1.23"
.Dl "portmaster fooport"
.Dl "portmaster fooport-1.23 barport-4.56"
.Dl "portmaster -p /usr/ports/foo/fooport"
.Dl "portmaster foo/fooport"
.Dl "portmaster -r fooport-1.23"
.Dl "portmaster -o emulators/linux_base-fc4 linux_base-8-8.0_15"
.Pp
.Dl "portmaster -L | grep -B1 '	'"
Print only the ports that have available updates.
(Note that the whitespace between single quotes is a tab.)
.Sh SEE ALSO
.Xr make 1 ,
.Xr pkg_delete 1 ,
.Xr ports 7
.Sh AUTHORS
This
manual page was written by
.An Doug Barton <dougb@FreeBSD.org> .