.\" $NetBSD: pkg_rolling-replace.8,v 1.24 2023/06/03 11:54:24 gdt 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 BFhknrsuv
.Op Fl D Ar VARIABLE=VALUE
.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,
to be mismatched, or marked to be rebuilt.
Optionally it can discover, mark and replace any mismatched 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.
.Nm
will pass
.Dq IN_PKG_ROLLING_REPLACE=1
to make, so users can set flags depending on interactive usage and
batch-replace in their @MAKECONF@.
.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).  This results in packages being upgraded to newer versions,
in the normal case where the pkgsrc tree is more recent than the
currently installed packages.  The packages discovered this way will
be marked as mismatched, so that in a re-run of
.Nm
you don't need to repeat the
.Fl u
flag.
.Ss Options
.Bl -tag -width xxxxxxxx
.It Fl B
Pass
.Dq -B
to
.Xr pkg_chk 8
to also mark any packages with any change in build version data.
.It Fl D Ar VARIABLE=VALUE
Passes VARIABLE=VALUE to each make call.
.Dq -D
can be specified more than once to pass several variables to make.
.It Fl F
Just fetches the sources of all mismatched packages required to be updated
(and it's dependencies).
.It Fl h
Brief help.
.It Fl k
Keep going, even when replacing a package fails.  This will very
likely rebuild packages depending on the failed package, and the
resulting inconsistency may cause problems.  However, it is useful for
unattended operation to accomplish most of the work, allowing a later
return to identifying and resolving individual package issues.
.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 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
Do not build binary packages.  (The flag is chosen for 'replace', as
opposed to 'make package replace'.)
.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 that in theory do not need to be replaced,
but it can solve shared library issues that arise if this theory is
incorrect.
.It Fl u
Use
.Xr pkg_chk 8
to check for mismatched packages, mark them with 'mismatch=YES',
and replace those also.
Otherwise, consider packages marked 'mismatch=YES' to be mismatched.
Marking with 'mismatch=YES' only occurs if the calling user can write
to the package database. It is not an error if this fails; it just does not
persist the status.
.It Fl v
Verbose output.
.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 mismatched packages.
This 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 @PKG_DBDIR@ .
.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 @PKG_DBDIR@ \*[Am]\*[Am] grep "blddep x11-links" */* | cut -d/ -f1 | \\
sort -u | xargs pkg_admin set rebuild=YES
.Ed
.Pp
To compile all packages heavily parallel, use
.Bd -literal -offset indent
pkg_rolling-replace -D MAKE_JOBS=8
.Ed
.Sh AUTHORS
Originally developed at BBN by
.An -nosplit
.An Nick Goffee ,
with initial idea and many suggestions from
.An Greg Troxel
.Aq gdt@NetBSD.org .
The options
.Fl s
and
.Fl r
were added by
.An Tobias Nygren
.Aq tnn@NetBSD.org .
The options
.Fl k ,
.Fl D ,
.Fl F
and
.Fl L
were added by
.An Jens Rehsack
.Aq sno@NetBSD.org .
.Sh BUGS
.Nm
is based on PKGPATH, and thus will malfunction if invoking replace in
that directory does not replace the correct PKGNAME.  This is a known
problem with multi-version packages, specifically with installed
packages that are not the default version.
.Pp
While not strictly a bug,
.Nm
will often not run to completion when operating on a large number of
packages because it is likely that at least one of them will not
rebuild cleanly.  In addition to errors that show up in bulk builds,
packages sometimes have bugs where they don't build if some
non-required packages are installed, or if an older version of the
package itself is installed.  These are bugs in the underlying
packages that would be observed with a manual make replace, without
this program.  Please do not report such errors as
.Nm
issues.
.Pp
.Nm
when run as a non-root user cannot set the 'mismatch=YES' flag.  This
can occur when one expects to use 'sudo' for 'make replace'.