PKG_ROLLING-REPLACE(8)

NAME
pkg_rolling-replace - rebuild or update packages using 'make replace' in tsorted order

SYNOPSIS
pkg_rolling-replace [-BFhknrsuv] [-D VARIABLE=VALUE] [-L path] [-X pkgs] [-x pkgs]

DESCRIPTION
pkg_rolling-replace runs “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 pkg_chk(8)) as well.

Whenever “make replace” is run on a package, all installed packages that depend on it are marked with the “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 “unsafe_depends=YES” is also set for all packages that depend on it. Running pkg_rolling-replace with no arguments will restore such packages to a safe state by building a dependency graph, running tsort(1) on it, and running “make replace” in the resulting topological order. The dependency graph and topological sort are re-calculated after each “make replace”, in case it causes additional packages to be marked unsafe. pkg_rolling-replace will pass “IN_PKG_ROLLING_REPLACE=1” to make, so users can set flags depending on interactive usage and batch-replace in their /etc/mk.conf.

The user can mark additional packages to be rebuilt by setting the “rebuild=YES” flag on them using the command
    % pkg_admin set rebuild=YES <pkg>

If the -u option is given, pkg_rolling-replace will use pkg_chk(8) to check for packages for which the version in pkgsrc is different than the installed version, and run “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 pkg_rolling-replace you don't need to repeat the -u flag.

  Options

-B  Pass “-B” to pkg_chk(8) to also mark any packages with any change in build version data.

-D VARIABLE=VALUE
    Passes VARIABLE=VALUE to each make call. “-D” can be specified more than once to pass several variables to make.

-F  Just fetches the sources of all mismatched packages required to be updated (and it's dependencies).

-h  Brief help.

-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.

-L 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: “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.

-n  Display actions that would be taken, but don't actually run “make replace” or change any flags on installed packages. This option attempts to calculate the new packages that would be marked unsafe after each “make replace”.

-r  Do not build binary packages. (The flag is chosen for 'replace', as opposed to 'make package replace'.)

-s  Enable strict mode. This makes pkg_rolling-replace look at “unsafe_depends_strict” tags instead of “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.

-u  Use 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.

-v  Verbose output.

-X pkgs
    Exclude the comma-separated list of package base names from being rebuilt for any reason.

-x 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 pkg_admin(1) “unsafe_depends”, “unsafe_depends_strict”, or “rebuild” variables set to “YES”).

ENVIRONMENT
pkg_rolling-replace uses the following environment variables.

MAKECONF
    Path to mk.conf. Defaults to /etc/mk.conf, /usr/pkg/etc/mk.conf, or /etc/mk.conf.

PKGSRCDIR
    Base of pkgsrc tree. If not set in the environment, then this variable is read from ${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 /usr/pkgsrc appears to contain a pkgsrc tree, then that is used as a last resort.

PKG_DBDIR
    pkgsrc database directory. If not set in environment then defaults to /usr/pkg/pkgdb.

EXAMPLES
To update all packages on the system and ensure correct shared library dependencies:

    pkg_rolling-replace -rsuv

To update all packages on the system, do as little rebuilding as possible, and also produce binary packages:

    pkg_rolling-replace -uv

To fetch all distfiles for the packages requiring an update on the system (packages with different version numbers than installed), and exit after it:

    pkg_rolling-replace -F

To update gtk2+ and all packages that depend on it, except openoffice2:

    pkg_admin set rebuild=YES gtk2+
    pkg_rolling-replace -rsv -X openoffice2

To force rebuild of gtk2+ and all packages that depend on it, keep going on even if one package fails, except openoffice2 - log to “/var/log/pkg_rr”:

    pkg_admin set rebuild=YES gtk2+
    pkg_rolling-replace -krsv -L /var/log/pkg_rr -X openoffice2

To mark all packages that compiled against X11 as needing rebuild (used after switching to X11_TYPE=modular):

    cd /usr/pkg/pkgdb  grep "blddep x11-links" */* | cut -d/ -f1 | \
    sort -u | xargs pkg_admin set rebuild=YES

To compile all packages heavily parallel, use

    pkg_rolling-replace -D MAKE_JOBS=8

AUTHORS
Originally developed at BBN by -nosplit Nick Goffee, with initial idea and many suggestions from Greg Troxel <gdt@NetBSD.org>. The options -s and -r were added by Tobias Nygren <tnn@NetBSD.org>. The options -k, -D, -F and -L were added by Jens Rehsack <sno@NetBSD.org>.

BUGS
pkg_rolling-replace 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.

While not strictly a bug, pkg_rolling-replace 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 pkg_rolling-replace issues.

pkg_rolling-replace 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'.