Annotation of pkgsrc/pkgtools/pkg_rolling-replace/files/pkg_rolling-replace.8, revision 1.24
1.24 ! gdt 1: .\" $NetBSD: pkg_rolling-replace.8,v 1.23 2023/03/05 20:23:59 triaxx 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
1.24 ! gdt 68: packages). This results in packages being upgraded to newer versions,
! 69: in the normal case where the pkgsrc tree is more recent than the
! 70: currently installed packages. The packages discovered this way will
! 71: be marked as mismatched, so that in a re-run of
1.21 rhialto 72: .Nm
73: you don't need to repeat the
74: .Fl u
75: flag.
1.1 gdt 76: .Ss Options
77: .Bl -tag -width xxxxxxxx
1.20 abs 78: .It Fl B
79: Pass
80: .Dq -B
81: to
1.21 rhialto 82: .Xr pkg_chk 8
1.20 abs 83: to also mark any packages with any change in build version data.
1.19 sno 84: .It Fl D Ar VARIABLE=VALUE
85: Passes VARIABLE=VALUE to each make call.
86: .Dq -D
87: can be specified more than once to pass several variables to make.
1.15 sno 88: .It Fl F
89: Just fetches the sources of all mismatched packages required to be updated
90: (and it's dependencies).
1.18 wiz 91: .It Fl h
92: Brief help.
1.15 sno 93: .It Fl k
1.24 ! gdt 94: Keep going, even when replacing a package fails. This will very
! 95: likely rebuild packages depending on the failed package, and the
! 96: resulting inconsistency may cause problems. However, it is useful for
! 97: unattended operation to accomplish most of the work, allowing a later
! 98: return to identifying and resolving individual package issues.
1.18 wiz 99: .It Fl L Ar path
100: Logs each build (each command output from the commands which are run for
101: packages) to given path.
102: The full log file name is composed from the path given by this
103: argument, the category name of the package and the package name:
104: .Dq given-path/category/pkgname .
105: The specified path must exists and being user writable of the invoking
106: user or any parent directory must be writable by the invoking user.
107: Potentially existing log in the same file name will be overwritten.
1.1 gdt 108: .It Fl n
1.2 wiz 109: Display actions that would be taken, but don't actually run
110: .Dq make replace
111: or change any flags on installed packages.
112: This option attempts to calculate the new packages that would be
113: marked unsafe after each
114: .Dq make replace .
1.7 tnn 115: .It Fl r
1.24 ! gdt 116: Do not build binary packages. (The flag is chosen for 'replace', as
! 117: opposed to 'make package replace'.)
1.7 tnn 118: .It Fl s
1.8 wiz 119: Enable strict mode.
120: This makes
1.7 tnn 121: .Nm
1.8 wiz 122: look at
1.7 tnn 123: .Dq unsafe_depends_strict
124: tags instead of
125: .Dq unsafe_depends
1.8 wiz 126: tags.
1.24 ! gdt 127: This will replace packages that in theory do not need to be replaced,
! 128: but it can solve shared library issues that arise if this theory is
! 129: incorrect.
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',
1.24 ! gdt 134: and replace those also.
1.21 rhialto 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.24 ! gdt 229: Originally developed at BBN by
1.2 wiz 230: .An -nosplit
1.24 ! gdt 231: .An Nick Goffee ,
1.1 gdt 232: with initial idea and many suggestions from
233: .An Greg Troxel
1.24 ! gdt 234: .Aq gdt@NetBSD.org .
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
1.24 ! gdt 253: is based on PKGPATH, and thus will malfunction if invoking replace in
! 254: that directory does not replace the correct PKGNAME. This is a known
! 255: problem with multi-version packages, specifically with installed
! 256: packages that are not the default version.
1.15 sno 257: .Pp
1.24 ! gdt 258: While not strictly a bug,
1.15 sno 259: .Nm
1.24 ! gdt 260: will often not run to completion when operating on a large number of
! 261: packages because it is likely that at least one of them will not
! 262: rebuild cleanly. In addition to errors that show up in bulk builds,
! 263: packages sometimes have bugs where they don't build if some
! 264: non-required packages are installed, or if an older version of the
! 265: package itself is installed. These are bugs in the underlying
! 266: packages that would be observed with a manual make replace, without
! 267: this program. Please do not report such errors as
! 268: .Nm
! 269: issues.
! 270: .Pp
! 271: .Nm
! 272: when run as a non-root user cannot set the 'mismatch=YES' flag. This
! 273: can occur when one expects to use 'sudo' for 'make replace'.
CVSweb <webmaster@jp.NetBSD.org>