.\"-
.\" Copyright (c) 2000-2005 Dag-Erling Coïdan Smørgrav
.\" 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: ports/ports-mgmt/porteasy/src/porteasy.8,v 1.19 2005/09/11 13:05:04 des Exp $
.\"
.Dd August 12, 2005
.Dt PORTEASY 8
.Os
.Sh NAME
.Nm porteasy
.Nd fetch and build ports
.Sh SYNOPSIS
.Nm
.Op Fl AabCceFfhIikLlRSsuVvw
.Op Fl D Ar date
.Op Fl d Ar dir
.Op Fl p Ar dir
.Op Fl r Ar dir
.Op Fl t Ar tag
.Op Ar port | Fl D Ns Ar VAR | Fl D Ns Ar VAR Ns = Ns Ar VAL ...
.Sh DESCRIPTION
.Nm
maintains an updated ports tree, and fetches and builds ports
automatically, keeping track of dependencies.
.Pp
The following options are available:
.Bl -tag -width Fl
.It Fl a
Use one of the FreeBSD project's anonymous CVS servers.
Note that this forces the use of
.Xr ssh 1 ,
regardless of the
.Fl R
and
.Fl S
options.
.It Fl b
Build the selected ports.
.It Fl C
Don't clean port directories after building.
.It Fl c
Clean the selected ports.
.It Fl D Ar date
Specify a date to use for
.Xr cvs 1
operations.
.It Fl d Ar dir
Specify the package database directory (normally
.Pa /var/db/pkg ) .
.It Fl e
Deselect ports that are already installed.
.It Fl F
Force installation and registration, even if the port is already
installed.
.It Fl f
Fetch the selected ports.
.It Fl h
Show a summary of options and parameters.
.It Fl I
Select installed ports.
.It Fl i
Describe the selected ports.
.It Fl k
Build packages for the selected ports.
.It Fl L
List the packing lists for the selected ports.
.It Fl l
List the selected ports.
.It Fl p Ar dir
Specify the ports directory (normally
.Pa /usr/ports ) .
.It Fl R
Force the use of
.Xr rsh 1
to connect to remote CVS repositories.
By default,
.Nm
respects the existing
.Ev CVS_RSH
setting.
This option is ignored when using anoncvs.
.It Fl r Ar dir
Specify the location of the CVS repository.
.It Fl S
Force the use of
.Xr ssh 1
to connect to remote CVS repositories.
By default,
.Nm
respects the existing
.Ev CVS_RSH
setting.
This option is ignored when using anoncvs.
.It Fl s
Indicate the installation status of the selected ports.
Each selected port is listed with a symbol indicating its status:
.Bl -tag -width 3n
.It Ql \&!
Not installed.
.It Ql " "
Up-to-date.
.It Ql \&<
Older than the version in the ports tree.
.It Ql \&>
Newer than the version in the ports tree.
.El
.Pp
If the
.Fl s
option is specified and no ports are specified on the command line,
all installed ports are selected as if the
.Fl I
option had been specified.
.It Fl t Ar tag
Specify a tag to use for
.Xr cvs 1
operations.
.It Fl u
Update all necessary files using
.Xr cvs 1 .
.It Fl V
Show the
.Nm
version number and exit.
.It Fl v
Verbose mode: show more information about what is being done.
.It Fl w
Show the URL of the port's web site if there is one listed in the port
description.
.El
.Ss Environment settings
Any command line argument of the form
.Fl D Ns Ar VAR ,
.Fl D Ns Ar VAR Ns = Ns Ar VAL
or
.Ar VAR Ns = Ns Ar VAL
is interpreted as a variable assignment which will be exported into
subprocesses' environments.
Thus compile-time configuration options can be specified on the
.Nm
command line.
.Ss Port names
The port names listed on the command line may be either unqualified or
fully qualified.
A fully qualified port name is the path to the port directory relative
to the root of the ports tree (i.e. the port's category and name
separated by a slash).
An unqualified port name is the name of the package built by the
intended port, or part of that name.
.Pp
Unqualified names need to be looked up in the ports index, which is
usually slightly out of date, so fully qualified names should be used
whenever possible.
.Ss Sequence of operation
This section describes the operations performed by
.Nm
and the order in which they are performed.
.Bl -tag -width indent
.It Update ports tree infrastructure
If the
.Fl u
option was specified, the root of the ports tree and important
subdirectories
.Po
.Pa Mk ,
.Pa Templates
and
.Pa Tools
.Pc
are updated using
.Xr cvs 1 .
If possible, an up-to-date index is retrieved from the
.Fx
website; otherwise, the version obtained from CVS will be used.
.It Select ports
The selection list is initialized with the ports listed on the command
line (and, if the
.Fl I
option was specified, all installed ports) marked as explicit
dependencies.
Any unqualified names are looked up in the index, using simple
heuristics to identify incompletely named ports.
If a certain match is not found,
.Nm
prints a list of possible matches and exits.
.Pp
All direct and indirect dependencies (except, if the
.Fl e
option was specified,
those that are already installed) are also selected and marked as
dependencies.
.It Update ports tree and discover dependencies
If the
.Fl u
option was specified, the port directories for all selected ports are
updated using
.Xr cvs 1 .
Each selected port's Makefile is scanned to discover dependencies,
which are in turn selected and marked as implicit dependencies.
This process is repeated until no new dependencies are found.
.It Deselect installed ports
.Pp
If the
.Fl e
option was specified,
.Nm
checks to see if any of the selected ports are already installed;
those that are are deselected.
This process is not very accurate, as it sometimes fails to detect
that an older or alternate version of a selected port is installed.
.It List selected ports
If the
.Fl l
option was specified, the fully qualified name and package name of all
selected ports are listed.
Explicitly selected ports are indicated with a star.
.It List installed ports
If the
.Fl s
option was specified, all selected ports are listed with their status.
.It Show packing lists
If the
.Fk L
option was specified, the packing lists for all explicitly selected
ports are shown.
.It Describe selected ports
If the
.Fl i
option was specified,
.Nm
prints a description of each port that was specified on the command
line.
.It Show the URLs of the selected ports' web sites
If the
.Fl w
option was specified,
.Nm
prints the URL of the web site of each port that was specified on the
command line, if a URL is listed in that port's description.
.It Clean the tree
If the
.Fl c
option was specified,
.Nm
runs the
.Sq clean
target on every selected port.
If no ports were selected,
.Nm
runs the
.Sq clean
target on every known port that is present in the tree.
.It Fetch ports
If at least one of the
.Fl b ,
.Fl f
or
.Fl k
options was specified,
.Nm
runs the
.Sq checksum
target on every selected port.
This fetches the distfiles and verifies their checksums.
.It Build, install, package, clean ports
If one or both of the
.Fl f
or
.Fl k
options were specified,
.Nm
runs the
.Sq install
or
.Sq package
target, followed by the
.Sq clean
target (unless the
.Fl C
option was specified), on every explicitly selected port.
.Nm
lets the ports system handle dependencies on its own, since the
reported dependencies are sometimes too inclusive.
.El
.Sh IMPLEMENTATION NOTES
There may be a significant difference between what ports are selected
(and listed if the
.Fl l
option is specified) and what ports are actually installed and/or have
packages built for them, since implicitly selected ports that are
already installed, or somehow pass the dependency check (e.g. because
an alternate, equivalent port has been installed) will be passed over
by the ports system, as indeed they should.
.Pp
.Nm
tries to minimize the number of times
.Xr cvs 1
is invoked, since the overhead involved in connecting to a remote
server is usually quite high (and the user might have to type a
password every time), but prefers correctness to performance.
The maximum number of invocations is (2 + NC + NP), where NC and NP
are the number of distinct categories and ports (including master
directories and dependencies).
.Sh ENVIRONMENT
.Bl -tag -width PORTEASY_OPTIONS
.It Ev PORTEASY_OPTIONS
Specifies a set of default options for
.Nm .
These options can be overridden by command line parameters.
.El
.Pp
The following variables are removed from the environment before any
work is performed:
.Ev CLASSPATH ,
.Ev LD_* ,
.Ev JAVA_* ,
.Ev USE_* ,
.Ev WANT_* .
.Sh FILES
.Nm
maintains and operates on a ports tree, normally
.Pa /usr/ports .
Some information is gathered from the package database, normally
located in
.Pa /var/db/pkg .
.Sh AUTHORS
.Nm
was written by
.An Dag-Erling Smørgrav Aq des@FreeBSD.org .
Several people contributed their comments and suggestions, most
notably
.An Eivind Eklund Aq eivind@FreeBSD.org .