path: root/pkgtools/pkg_rolling-replace/files/pkg_rolling-replace.8

.\" $NetBSD: pkg_rolling-replace.8,v 1.17 2010/02/01 09:33:21 sno Exp $
.Dd February 1, 2010
.Dt PKG_ROLLING-REPLACE 8
.Os
.Sh NAME
.Nm pkg_rolling-replace
.Nd rebuild or update packages using 'make replace' in tsorted order
.Sh SYNOPSIS
.Nm
.Op Fl hFknrsuv
.Op Fl D Ar bool
.Op Fl j Ar jobs
.Op Fl L Ar path
.Op Fl X Ar pkgs
.Op Fl x Ar pkgs
.Sh DESCRIPTION
.Nm
runs
.Dq make replace
on packages that have been marked to have unsafe dependencies or have
been marked to be rebuilt.
Optionally it can replace any outdated packages (as reported by
.Xr pkg_chk 8 )
as well.
.Pp
Whenever
.Dq make replace
is run on a package, all installed packages
that depend on it are marked with the
.Dq unsafe_depends_strict=YES
flag.
If the version of the replaced package has changed, this indicates
that it may no longer be ABI-compatible so
.Dq unsafe_depends=YES
is also set for all packages that depend on it.
Running
.Nm
with no arguments will restore such packages to a safe state by
building a dependency graph, running
.Xr tsort 1
on it, and running
.Dq make replace
in the resulting topological order.
The dependency graph and topological sort are re-calculated after each
.Dq make replace ,
in case it causes additional packages to be marked unsafe.
.Pp
The user can mark additional packages to be rebuilt by setting the
.Dq rebuild=YES
flag on them using the command
.Dl % pkg_admin set rebuild=YES Aq pkg
.Pp
If the
.Fl u
option is given,
.Nm
will use
.Xr pkg_chk 8
to check for packages for which the version in pkgsrc is different
than the installed version, and run
.Dq make replace
on those packages as well (tsorting them along with the unsafe/rebuild
packages).
(Usually this results in packages being upgraded to newer versions,
assuming the pkgsrc tree is more recent than the currently installed
packages.)
.Ss Options
.Bl -tag -width xxxxxxxx
.It Fl h
Brief help.
.It Fl F
Just fetches the sources of all mismatched packages required to be updated
(and it's dependencies).
.It Fl k
Keep on going, even on error during handling current package.
Warning: This could (potential will) rebuild package depending
on the failed package, anyway. This may cause a broken tree.
Use with caution!
.It Fl j Ar jobs
Enables a pkgsrc tunable (MAKE_JOBS=<n>) to allow parallel build while
compiling a package. It's unset by default.
.It Fl n
Display actions that would be taken, but don't actually run
.Dq make replace
or change any flags on installed packages.
This option attempts to calculate the new packages that would be
marked unsafe after each
.Dq make replace .
.It Fl r
Just replace packages, do not build binary packages.
.It Fl s
Enable strict mode.
This makes
.Nm
look at
.Dq unsafe_depends_strict
tags instead of
.Dq unsafe_depends
tags.
This will replace packages more aggressively and can be used to solve
shared library problems.
.It Fl u
Use
.Xl pkg_chk 8
to check for outdated packages, and replace those too.
.It Fl v
Verbose output.
.It Fl D Ar bool
Sets the
.Dq USE_DESTDIR=<bool>
for the given bool. The default value is
.Dq NO
to ensure the same behaviour for pkgsrc developers when the act as users
and update their system. To disable the default behaviour, use
.Dq OFF
as value for the
.Dq -D
parameter.
.It Fl L Ar path
Logs each build (each command output from the commands which are run for
packages) to given path. The full log file name is composed from the path
given by this argument, the category name of the package and the package
name:
.Dq given-path/category/pkgname .
The specified path must exists and being user writable of the invoking
user or any parent directory must be writable by the invoking user.
Potentially existing log in the same file name will be overwritten.
.It Fl X Ar pkgs
Exclude the comma-separated list of package base names
from being rebuilt for any reason.
.It Fl x Ar pkgs
Exclude the comma-separated list of package base names
from the check for outdated packages.
This has no effect if the
.Fl u
flag is not given,
and does not prevent packages from being rebuilt for any other reason
(such as being a dependency of another package that is also rebuilt,
or having any of the
.Xr pkg_admin 1
.Dq unsafe_depends ,
.Dq unsafe_depends_strict ,
or
.Dq rebuild
variables set to
.Dq YES ) .
.El
.Sh ENVIRONMENT
.Nm
uses the following environment variables.
.Bl -tag -width xxxx
.It Ev MAKECONF
Path to
.Pa mk.conf .
Defaults to
.Pa @MAKECONF@ , @PREFIX@/etc/mk.conf ,
or
.Pa /etc/mk.conf .
.It Ev PKGSRCDIR
Base of pkgsrc tree.
If not set in the environment, then this variable is read from
.Pa ${MAKECONF} .
If it is still not set, and if the current working directory
appears to be inside a pkgsrc tree, then this variable
is set to the base of that pkgsrc tree.
Finally, if
.Pa /usr/pkgsrc
appears to contain a pkgsrc tree, then that is used as a last resort.
.It Ev PKG_DBDIR
pkgsrc database directory.
If not set in environment then defaults to
.Pa /var/db/pkg .
.El
.Sh EXAMPLES
To update all packages on the system and ensure correct shared library
dependencies:
.Bd -literal -offset indent
pkg_rolling-replace -rsuv
.Ed
.Pp
To update all packages on the system, do as little rebuilding as possible,
and also produce binary packages:
.Bd -literal -offset indent
pkg_rolling-replace -uv
.Ed
.Pp
To fetch all distfiles for the packages requiring an update on the system
(packages with different version numbers than installed), and exit after it:
.Bd -literal -offset indent
pkg_rolling-replace -F
.Ed
.Pp
To update gtk2+ and all packages that depend on it, except openoffice2:
.Bd -literal -offset indent
pkg_admin set rebuild=YES gtk2+
pkg_rolling-replace -rsv -X openoffice2
.Ed
.Pp
To force rebuild of gtk2+ and all packages that depend on it, keep
going on even if one package fails, except openoffice2 - log to
.Dq /var/log/pkg_rr :
.Bd -literal -offset indent
pkg_admin set rebuild=YES gtk2+
pkg_rolling-replace -krsv -L /var/log/pkg_rr -X openoffice2
.Ed
.Pp
To mark all packages that compiled against X11 as needing rebuild
(used after switching to X11_TYPE=modular):
.Bd -literal -offset indent
cd /var/db/pkg \*[Am]\*[Am] grep "blddep x11-links" */* | cut -d/ -f1 | \\
sort -u | xargs pkg_admin set rebuild=YES
.Ed
.Sh AUTHORS
.An -nosplit
.An Nick Goffee
.Aq ngoffee@bbn.com ,
with initial idea and many suggestions from
.An Greg Troxel
.Aq gdt@ir.bbn.com .
The options
.Fl s
and
.Fl r
were added by
.An Tobias Nygren
.Aq tnn@NetBSD.org .
The options
.Fl k ,
.Fl j ,
.Fl D ,
.Fl F
and
.Fl L
were added by
.An Jens Rehsack
.Aq sno@NetBSD.org .
.Sh BUGS
.Nm
does not run fully automatically when any significant number of
packages need to be replaced.
.Pp
.Nm
does not run fully automatically when the PKGNAME of a package
changes.