Annotation of pkgsrc/pkgtools/pkg_rolling-replace/files/pkg_rolling-replace.8, revision 1.19

1.19    ! sno         1: .\" $NetBSD: pkg_rolling-replace.8,v 1.18 2010/02/01 12:25:07 wiz Exp $
1.17      sno         2: .Dd February 1, 2010
1.1       gdt         3: .Dt PKG_ROLLING-REPLACE 8
1.2       wiz         4: .Os
1.1       gdt         5: .Sh NAME
                      6: .Nm pkg_rolling-replace
                      7: .Nd rebuild or update packages using 'make replace' in tsorted order
                      8: .Sh SYNOPSIS
                      9: .Nm
1.18      wiz        10: .Op Fl Fhknrsuv
1.19    ! sno        11: .Op Fl D Ar VARIABLE=VALUE
1.15      sno        12: .Op Fl L Ar path
1.14      wiz        13: .Op Fl X Ar pkgs
1.1       gdt        14: .Op Fl x Ar pkgs
                     15: .Sh DESCRIPTION
                     16: .Nm
1.2       wiz        17: runs
                     18: .Dq make replace
1.7       tnn        19: on packages that have been marked to have unsafe dependencies or have
                     20: been marked to be rebuilt.
                     21: Optionally it can replace any outdated packages (as reported by
1.1       gdt        22: .Xr pkg_chk 8 )
                     23: as well.
                     24: .Pp
1.2       wiz        25: Whenever
                     26: .Dq make replace
                     27: is run on a package, all installed packages
                     28: that depend on it are marked with the
1.7       tnn        29: .Dq unsafe_depends_strict=YES
1.8       wiz        30: flag.
                     31: If the version of the replaced package has changed, this indicates
1.7       tnn        32: that it may no longer be ABI-compatible so
1.2       wiz        33: .Dq unsafe_depends=YES
1.7       tnn        34: is also set for all packages that depend on it.
1.2       wiz        35: Running
1.1       gdt        36: .Nm
                     37: with no arguments will restore such packages to a safe state by
                     38: building a dependency graph, running
                     39: .Xr tsort 1
1.2       wiz        40: on it, and running
                     41: .Dq make replace
                     42: in the resulting topological order.
1.1       gdt        43: The dependency graph and topological sort are re-calculated after each
1.2       wiz        44: .Dq make replace ,
                     45: in case it causes additional packages to be marked unsafe.
1.19    ! sno        46: .Nm
        !            47: will pass
        !            48: .Dq IN_PKG_ROLLING_REPLACE=1
        !            49: to make, so users can set flags depending on interactive usage and
        !            50: batch-replace in their @MAKECONF@.
1.1       gdt        51: .Pp
                     52: The user can mark additional packages to be rebuilt by setting the
1.2       wiz        53: .Dq rebuild=YES
                     54: flag on them using the command
                     55: .Dl % pkg_admin set rebuild=YES Aq pkg
1.1       gdt        56: .Pp
                     57: If the
                     58: .Fl u
                     59: option is given,
                     60: .Nm
                     61: will use
1.12      tnn        62: .Xr pkg_chk 8
1.1       gdt        63: to check for packages for which the version in pkgsrc is different
1.2       wiz        64: than the installed version, and run
                     65: .Dq make replace
                     66: on those packages as well (tsorting them along with the unsafe/rebuild
                     67: packages).
1.1       gdt        68: (Usually this results in packages being upgraded to newer versions,
                     69: assuming the pkgsrc tree is more recent than the currently installed
                     70: packages.)
                     71: .Ss Options
                     72: .Bl -tag -width xxxxxxxx
1.19    ! sno        73: .It Fl D Ar VARIABLE=VALUE
        !            74: Passes VARIABLE=VALUE to each make call.
        !            75: .Dq -D
        !            76: can be specified more than once to pass several variables to make.
1.15      sno        77: .It Fl F
                     78: Just fetches the sources of all mismatched packages required to be updated
                     79: (and it's dependencies).
1.18      wiz        80: .It Fl h
                     81: Brief help.
1.15      sno        82: .It Fl k
                     83: Keep on going, even on error during handling current package.
                     84: Warning: This could (potential will) rebuild package depending
1.18      wiz        85: on the failed package, anyway.
                     86: This may cause a broken tree.
1.15      sno        87: Use with caution!
1.18      wiz        88: .It Fl L Ar path
                     89: Logs each build (each command output from the commands which are run for
                     90: packages) to given path.
                     91: The full log file name is composed from the path given by this
                     92: argument, the category name of the package and the package name:
                     93: .Dq given-path/category/pkgname .
                     94: The specified path must exists and being user writable of the invoking
                     95: user or any parent directory must be writable by the invoking user.
                     96: Potentially existing log in the same file name will be overwritten.
1.1       gdt        97: .It Fl n
1.2       wiz        98: Display actions that would be taken, but don't actually run
                     99: .Dq make replace
                    100: or change any flags on installed packages.
                    101: This option attempts to calculate the new packages that would be
                    102: marked unsafe after each
                    103: .Dq make replace .
1.7       tnn       104: .It Fl r
                    105: Just replace packages, do not build binary packages.
                    106: .It Fl s
1.8       wiz       107: Enable strict mode.
                    108: This makes
1.7       tnn       109: .Nm
1.8       wiz       110: look at
1.7       tnn       111: .Dq unsafe_depends_strict
                    112: tags instead of
                    113: .Dq unsafe_depends
1.8       wiz       114: tags.
                    115: This will replace packages more aggressively and can be used to solve
1.7       tnn       116: shared library problems.
1.1       gdt       117: .It Fl u
                    118: Use
                    119: .Xl pkg_chk 8
                    120: to check for outdated packages, and replace those too.
                    121: .It Fl v
                    122: Verbose output.
1.14      wiz       123: .It Fl X Ar pkgs
                    124: Exclude the comma-separated list of package base names
                    125: from being rebuilt for any reason.
1.1       gdt       126: .It Fl x Ar pkgs
1.9       apb       127: Exclude the comma-separated list of package base names
                    128: from the check for outdated packages.
                    129: This has no effect if the
1.1       gdt       130: .Fl u
1.9       apb       131: flag is not given,
                    132: and does not prevent packages from being rebuilt for any other reason
                    133: (such as being a dependency of another package that is also rebuilt,
                    134: or having any of the
1.14      wiz       135: .Xr pkg_admin 1
1.9       apb       136: .Dq unsafe_depends ,
                    137: .Dq unsafe_depends_strict ,
                    138: or
                    139: .Dq rebuild
                    140: variables set to
                    141: .Dq YES ) .
1.1       gdt       142: .El
                    143: .Sh ENVIRONMENT
                    144: .Nm
                    145: uses the following environment variables.
                    146: .Bl -tag -width xxxx
1.3       tnn       147: .It Ev MAKECONF
                    148: Path to
                    149: .Pa mk.conf .
                    150: Defaults to
1.11      apb       151: .Pa @MAKECONF@ , @PREFIX@/etc/mk.conf ,
1.5       tnn       152: or
1.11      apb       153: .Pa /etc/mk.conf .
1.1       gdt       154: .It Ev PKGSRCDIR
1.2       wiz       155: Base of pkgsrc tree.
1.11      apb       156: If not set in the environment, then this variable is read from
                    157: .Pa ${MAKECONF} .
                    158: If it is still not set, and if the current working directory
                    159: appears to be inside a pkgsrc tree, then this variable
                    160: is set to the base of that pkgsrc tree.
                    161: Finally, if
1.3       tnn       162: .Pa /usr/pkgsrc
1.11      apb       163: appears to contain a pkgsrc tree, then that is used as a last resort.
1.1       gdt       164: .It Ev PKG_DBDIR
                    165: pkgsrc database directory.
                    166: If not set in environment then defaults to
1.2       wiz       167: .Pa /var/db/pkg .
1.1       gdt       168: .El
1.14      wiz       169: .Sh EXAMPLES
                    170: To update all packages on the system and ensure correct shared library
                    171: dependencies:
                    172: .Bd -literal -offset indent
                    173: pkg_rolling-replace -rsuv
                    174: .Ed
                    175: .Pp
                    176: To update all packages on the system, do as little rebuilding as possible,
                    177: and also produce binary packages:
                    178: .Bd -literal -offset indent
                    179: pkg_rolling-replace -uv
                    180: .Ed
                    181: .Pp
1.15      sno       182: To fetch all distfiles for the packages requiring an update on the system
                    183: (packages with different version numbers than installed), and exit after it:
                    184: .Bd -literal -offset indent
                    185: pkg_rolling-replace -F
                    186: .Ed
                    187: .Pp
1.14      wiz       188: To update gtk2+ and all packages that depend on it, except openoffice2:
                    189: .Bd -literal -offset indent
                    190: pkg_admin set rebuild=YES gtk2+
                    191: pkg_rolling-replace -rsv -X openoffice2
                    192: .Ed
                    193: .Pp
1.15      sno       194: To force rebuild of gtk2+ and all packages that depend on it, keep
                    195: going on even if one package fails, except openoffice2 - log to
                    196: .Dq /var/log/pkg_rr :
                    197: .Bd -literal -offset indent
                    198: pkg_admin set rebuild=YES gtk2+
                    199: pkg_rolling-replace -krsv -L /var/log/pkg_rr -X openoffice2
                    200: .Ed
                    201: .Pp
1.14      wiz       202: To mark all packages that compiled against X11 as needing rebuild
                    203: (used after switching to X11_TYPE=modular):
                    204: .Bd -literal -offset indent
                    205: cd /var/db/pkg \*[Am]\*[Am] grep "blddep x11-links" */* | cut -d/ -f1 | \\
                    206: sort -u | xargs pkg_admin set rebuild=YES
                    207: .Ed
1.19    ! sno       208: .Pp
        !           209: To compile all packages heavily parallel, use
        !           210: .Bd -literal -offset indent
        !           211: pkg_rolling-replace -D MAKE_JOBS=8
        !           212: .Ed
1.1       gdt       213: .Sh AUTHORS
1.2       wiz       214: .An -nosplit
1.1       gdt       215: .An Nick Goffee
                    216: .Aq ngoffee@bbn.com ,
                    217: with initial idea and many suggestions from
                    218: .An Greg Troxel
                    219: .Aq gdt@ir.bbn.com .
1.8       wiz       220: The options
                    221: .Fl s
                    222: and
                    223: .Fl r
                    224: were added by
1.7       tnn       225: .An Tobias Nygren
                    226: .Aq tnn@NetBSD.org .
1.15      sno       227: The options
                    228: .Fl k ,
1.17      sno       229: .Fl D ,
1.15      sno       230: .Fl F
                    231: and
                    232: .Fl L
                    233: were added by
                    234: .An Jens Rehsack
                    235: .Aq sno@NetBSD.org .
1.1       gdt       236: .Sh BUGS
                    237: .Nm
                    238: does not run fully automatically when any significant number of
                    239: packages need to be replaced.
1.15      sno       240: .Pp
                    241: .Nm
                    242: does not run fully automatically when the PKGNAME of a package
                    243: changes.

CVSweb <webmaster@jp.NetBSD.org>