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

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

CVSweb <webmaster@jp.NetBSD.org>