| blob | d190ce1663186e8e0ce415f50f569cc07b6708bb |
1 .\" $NetBSD: pkgdepgraph.1,v 1.11 2004/07/28 01:42:43 atatat Exp $
2 .\"
3 .\" Copyright (c) 2002, 2003, 2004 by Andrew Brown <atatat@netbsd.org>
4 .\" Absolutely no warranty.
5 .\"
6 .Dd July 28, 2004
7 .Dt PKGDEPGRAPH 1
8 .Sh NAME
9 .Nm pkgdepgraph
10 .Nd visual representation of installed packages
11 .Sh SYNOPSIS
12 .Nm
13 .Op Fl AaCcDeFfgLloRrsv
14 .Op Fl d Ar pkg_dbdir
15 .Op Fl i Ar impact
16 .Op Fl K Ar packages
17 .Op Fl M Ar make
18 .Op Fl m Ar target
19 .Op Fl O Ar package
20 .Op Fl P Ar pkgsrcdir
21 .Op Fl S Ar package
22 .Op Fl t Ar target
23 .Op Fl U Ar package
24 .Op Pa data ...
25 .Sh DESCRIPTION
26 .Nm
27 emits a
28 .Pa dot
29 language description of the locally installed packages, with the
30 inter-dependencies reduced to a minimal set of edges.
31 It scans each directory under the package database directory for files
32 named
33 .Pa +BUILD_INFO
34 and
35 .Pa +REQUIRED_BY
36 in order to gather its data.
37 .Pp
38 .Nm
39 will also read any files passed to it as arguments (or stdin if it
40 is not connected to a tty), in search of output that resembles that
41 of either
42 .Xr lintpkgsrc 1
43 .Fl i ,
44 .Xr lintpkgsrc 1
45 .Fl g ,
46 .Xr audit-packages 8 ,
47 or the output from a previous incantation of this program.
48 .Pp
49 In the latter case,
50 .Nm
51 will recolor the graph passed as input based, as usual, on information
52 about currently installed pkgs.
53 Packages that are in the input graph, but not currently installed,
54 will be colored black, those that are installed will be colored green,
55 and those that remain out of date for some reason will remain red.
56 .Pp
57 The graph defaults to black, but if data from
58 .Xr lintpkgsrc 1
59 .Fl i
60 or
61 .Pa audit-packages
62 is given, or if a specific package is asserted to be out of date (via the
63 .Fl O
64 option), then nodes (and edges leading from them) will be colored in
65 the following manner:
66 .Bl -tag -width purple
67 .It green
68 The package is completely up to date.
69 .It orange
70 The package is up to date, but some of its dependencies require updating.
71 .It red
72 The package is out of date or has had a security advisory issued
73 against it, and should be replaced.
74 .It purple
75 The package was not found in the local pkgsrc tree.
76 .It blue
77 The package depends on something not found in the local pkgsrc tree.
78 .It black
79 The package has been removed and not yet replaced, or the graph is
80 uncolored.
81 The difference between an uncolored graph and a graph that has been
82 recolored almost entirely black as a result of removing all the
83 packages can be visually detected by the color of the
84 .Nm
85 package with which the graph was recolored.
86 .El
87 .Pp
88 It is important to note that all installed packages fall into one (or
89 more) of the following categories:
90 .Bl -tag -width out-of-date
91 .It installed
92 Any installed package.
93 .It out of date
94 Any package that can be upgraded.
95 .It stale
96 Any package that depends on a package that is out of date.
97 .It leaf
98 Any package that is not depended on by any other package.
99 .El
100 .Pp
101 Selecting the type or types of packages that are listed, and how the
102 information is put to use, can be controlled by the following options:
103 .Bl -tag -width package
104 .It Fl A
105 This option modifies the output of
106 .Fl R
107 to use
108 .Xr pkg_add 1
109 to reinstall deleted packages, instead of building directly from the
110 pkgsrc tree.
111 .It Fl a
112 All packages.
113 This option can be specified more than once to augment the meaning of
114 .Dq all
115 as it relates to the selected output mode.
116 For the default graph output, this option has no effect.
117 When used with
118 .Fl m
119 where the default output is the list of out of date packages, one
120 .Fl a
121 will make
122 .Nm
123 also list stale packages, and a second
124 .Fl a
125 will make it list all installed packages.
126 .It Fl C
127 Asserts
128 .Fl c
129 and adds
130 .Dq CLEANDEPENDS=YES
131 so that all rebuilt dependencies are cleaned as well.
132 .It Fl c
133 Inserts a
134 .Dq make clean
135 command in the set of instructions to rebuild packages (see the
136 .Fl R
137 option) after they are installed.
138 The
139 .Fl c
140 option used to enable graph coloring, but now graph coloring is done
141 automatically if any coloring data is given.
142 .It Fl D
143 Instead of the standard graph output,
144 .Nm
145 lists the packages that need to be deleted, in
146 .Dq least required first
147 order, so that they can be deleted without any dependency problems.
148 This is a good first step to take before rebuilding all your packages
149 that are out of date (see the
150 .Fl R
151 option).
152 This option is an alias for
153 .Fl as .
154 .It Fl d Ar pkg_dbdir
155 The location of the package database files.
156 This defaults to the value of the
157 .Pa PKG_DBDIR
158 environment variable, if it is set, or to
159 .Pa @PKG_DBDIR@ .
160 .It Fl e
161 Adds an
162 .Dq existence check
163 to each of the lines of
164 .Xr sh 1
165 style output so that commands can be skipped if the package is already
166 installed.
167 .It Fl F
168 Makes
169 .Nm
170 emit a series of
171 .Xr sh 1
172 commands that will fetch all the required distfiles for rebuilding out
173 of date packages.
174 This option is an alias for
175 .Fl m Ar fetch .
176 .It Fl f
177 Force a rebuild of all dependent packages.
178 This option is for use in conjunction with the
179 .Fl U
180 option to force a rebuild of all the dependencies of a package to be
181 updated.
182 .It Fl g
183 Add package subgraph groupings.
184 This places all packages with a common prefix (e.g.,
185 .Dq p5
186 or
187 .Dq gimp )
188 in a subgraph with a line around it so you can visually associate
189 packages.
190 .It Fl i Ar impact
191 Specify the impact you want to allow when rebuilding packages.
192 The impact of a given package being rebuilt is a number that reflects
193 the longest path from the
194 .Dq top
195 of the installed packages (those packages upon which most other
196 packages depend) to the
197 .Dq bottom
198 of the installed packages (those packages upon which no other packages
199 depend).
200 A package that needs to be rebuilt but has nothing above it in the
201 tree requiring rebuilding and nothing below it has an impact of 0.
202 Values of 10 or more for
203 .Ar impact
204 will probably eliminate nothing from the rebuild list.
205 The value for
206 .Ar impact
207 can also be the name of a package to be avoided when constructing the
208 list of things to be rebuilt.
209 .It Fl K Ar packages
210 The base location or url from which to install binary packages.
211 This defaults to the value of PKG_PATH, or to PACKAGES with
212 .Dq Dv /All
213 added to the end, or to the value determined for pkgsrcdir (see the
214 .Fl P
215 option) with
216 .Dq Dv /packages/All
217 appended to it.
218 .It Fl L
219 Limit the graph to those packages that are out of date
220 or ultimately depend on some package that is.
221 When used with
222 .Fl m
223 or
224 .Fl s ,
225 this limits the list to
226 .Dq leaf
227 packages that are out of date or stale.
228 .It Fl l
229 Adds package
230 .Dq location
231 information to the labels on the nodes.
232 This is the path to the package under the local pkgsrc tree.
233 .It Fl M Ar make
234 Sets the name or path of the proper
235 .Xr make 1
236 program for the
237 .Xr sh 1
238 commands generated by the
239 .Fl R
240 and
241 .Fl F
242 options.
243 Some systems may have more than one
244 .Xr make 1
245 command or the correct choice might not be named
246 .Dq make .
247 The default value for this is taken from the MAKE environment
248 variable, if it is set, or is simply
249 .Dq make .
250 .It Fl m Ar target
251 Emits generic
252 .Xr sh 1
253 commands to
254 .Dq make Ar target
255 for each listed package.
256 One interesting target to specify is
257 .Ar '$*'
258 since that will yield a script that will pass its own command
259 line arguments to make for processing.
260 .It Fl O Ar package
261 Marks
262 .Ar package
263 as out of date so that you can see the impact of deleting dependent
264 packages and rebuilding everything.
265 This option can be used as a quick alternative to using the output
266 from
267 .Xr lintpkgsrc 1
268 .Fl i
269 for graph coloring information.
270 .It Fl o
271 Adds a package
272 .Dq order
273 number to each node's label.
274 The number indicates only the place of the node in the hierarchy, such
275 that each node has a number greater than that of anything which
276 depends on it, and with the
277 .Dq leaf
278 nodes numbered one.
279 .It Fl P Ar pkgsrcdir
280 The root of the pkgsrc source tree.
281 This defaults to the value of the
282 .Pa PKGSRCDIR
283 environment variable, if it is set, or to
284 .Pa @PKGSRCDIR@ .
285 .It Fl R
286 Instead of the standard graph output, emits a series of
287 .Xr sh 1
288 commands that will rebuild all the out of date packages by rebuilding
289 all the deleted leaf packages.
290 Packages that are out of date should be deleted first (see the
291 .Fl D
292 option).
293 This option is an alias for
294 .Fl eLm Ar target .
295 See the
296 .Fl t
297 option for a description of what value is used for
298 .Ar target .
299 .It Fl r
300 Reverses the order in which the packages are listed.
301 .It Fl S Ar package
302 Selects a subgraph of the installed package base around which to
303 generate output.
304 By default, if a subgraph of
305 .Ar package
306 is requested, only
307 .Ar package
308 and those packages immediately above and below it in the graph will be
309 listed.
310 To select only those immediately below, prefix a
311 .Dq -
312 to the package name.
313 To select all packages below
314 .Ar package ,
315 prefix
316 .Dq --
317 to the package name.
318 To select packages above
319 .Ar package ,
320 use
321 .Dq +
322 and
323 .Dq ++
324 as appropriate.
325 To select all packages remotely connected to
326 .Ar package ,
327 add
328 .Dq =
329 to the beginning.
330 Note: take care when using this option with generated lists or sh
331 scripts.
332 Since the subgraph of packages selected by this option may not include
333 all stale or out of date packages involved in a proper package update
334 procedure, the lists may be incomplete and can cause problems.
335 .It Fl s
336 Print a simple list of packages instead of
337 .Xr sh 1
338 commands.
339 The default output set for this command is out of date packages from
340 the entire package set.
341 Use combinations of
342 .Fl a ,
343 .Fl L ,
344 .Fl O Ar package ,
345 and
346 .Fl S Ar package
347 to select more or other package lists.
348 .It Fl t Ar target
349 Changes the target of the
350 .Fl R
351 output from
352 .Dq install
353 to
354 .Ar target
355 in case you want to
356 .Dq make package
357 or some other target.
358 .It Fl U Ar package
359 Generates a graph with only the out of date dependencies of
360 .Ar package
361 marked in red (ie, packages that are out of date but not dependencies
362 of
363 .Ar package
364 will not be considered out of date).
365 This will show the entire effect of deleting all related packages in
366 order to update the dependencies of the given package.
367 If the
368 .Fl f
369 option is used, then all the dependencies of
370 .Ar package
371 will be marked as out of date and the effect on the installed package
372 base will be accordingly greater.
373 .It Fl v
374 Adds the package version number to the node's label in the graph.
375 .El
376 .Sh ENVIRONMENT
377 .Ss MAKE
378 The default name for the
379 .Dq make
380 program used in the
381 .Xr sh 1
382 commands generated by the
383 .Fl F
384 and
385 .Fl R
386 output modes.
387 .Ss PKG_DBDIR
388 Where to find registered packages instead of
389 .Pa @PKG_DBDIR@ .
390 .Ss PKGSRCDIR
391 Where the pkgsrc tree is located instead of
392 .Pa @PKGSRCDIR@ .
393 .Ss PKG_PATH
394 .Ss PACKAGES
395 Two variables that can be used as a location for binary packages.
396 See the
397 .Fl A
398 and
399 .Fl K
400 options for more details.
401 .Sh EXAMPLES
402 The default output:
403 .Bd -literal -offset indent
404 $ pkgdepgraph | dotty -
405 .Ed
406 .Pp
407 To generate graph output for later use, and a postscript image of it:
408 .Bd -literal -offset indent
409 $ lintpkgsrc -i \*[Gt] pkgdepgraph.in
410 $ audit-packages \*[Gt]\*[Gt] pkgdepgraph.in
411 $ pkgdepgraph -lv pkgdepgraph.in \*[Gt] pkgdepgraph.dot
412 $ dot -Tps pkgdepgraph.dot \*[Gt] pkgdepgraph.ps
413 .Ed
414 .Pp
415 To generate a graph of just the out of date nodes as a gif:
416 .Bd -literal -offset indent
417 $ pkgdepgraph -L pkgdepgraph.in \*[Gt] out-of-date.dot
418 $ dot -Tgif out-of-date.dot \*[Gt] out-of-date.gif
419 .Ed
420 .Pp
421 To make a list of packages that need to be removed in order to bring
422 all packages up to date:
423 .Bd -literal -offset indent
424 $ pkgdepgraph -D pkgdepgraph.in \*[Gt] delete_order
425 $ pkgdepgraph -R pkgdepgraph.in \*[Gt] rebuild.sh
426 .Ed
427 .Pp
428 To rebuild everything that has no other rebuild requirements:
429 .Bd -literal -offset indent
430 $ pkgdepgraph -D pkgdepgraph.in -i0 \*[Gt] delete_order
431 $ pkgdepgraph -R pkgdepgraph.in -i0 \*[Gt] rebuild.sh
432 .Ed
433 .Pp
434 Or, to rebuild everything except those things that would require
435 rebuilding perl:
436 .Bd -literal -offset indent
437 $ pkgdepgraph -D pkgdepgraph.in -iperl \*[Gt] delete_order
438 $ pkgdepgraph -R pkgdepgraph.in -iperl \*[Gt] rebuild.sh
439 .Ed
440 .Pp
441 To subsequently delete all out of date and stale packages:
442 .Bd -literal -offset indent
443 $ pkg_delete `cat delete_order`
444 $ sh rebuild.sh
445 .Ed
446 .Pp
447 You may also find it useful to
448 .Dq pre-fetch
449 all the required distfiles for the rebuild as below, so that you can
450 do all the rebuilding while off-line:
451 .Bd -literal -offset indent
452 $ pkgdepgraph -F pkgdepgraph.in \*[Gt] fetch.sh
453 $ sh fetch.sh
454 .Ed
455 .Pp
456 Running the rebuild script will probably take a while, but if you
457 need to stop it or it stops by itself for any reason, you can rerun
458 the script, and it will pick up where it left off.
459 If there are certain packages that you want installed before others
460 are reinstalled, feel free to reorder the lines in the script.
461 .Pp
462 You can also
463 .Dq make clean
464 wherever you like when the rebuild script is not running, or even
465 update your tree in between runs of the script, though in the latter
466 case, it would be prudent to resume the script in the following manner
467 so that any packages that are newly out of date are removed and
468 replaced.
469 .Bd -literal -offset indent
470 $ pkgdepgraph -D pkgdepgraph.in \*[Gt] delete_order
471 $ pkgdepgraph -R pkgdepgraph.in \*[Gt]\*[Gt] rebuild.sh
472 $ pkg_delete `cat delete_order`
473 $ sh rebuild.sh
474 .Ed
475 .Pp
476 It is important to note that if you have specifically installed a
477 particular package that is a dependency, and another package (or other
478 packages) exist that can satisfy the same dependency, you should
479 probably pre-install that particular package.
480 There is no guarantee that the typical processing order will install
481 the same package.
482 .Pp
483 A similar task is to update all the out of date dependencies of an
484 package, rebuild the package, and any others that might share the same
485 dependencies:
486 .Bd -literal -offset indent
487 $ pkgdepgraph -U mozilla -D pkgdepgraph.in \*[Gt] delete_order
488 $ pkgdepgraph -U mozilla -R pkgdepgraph.in \*[Gt] rebuild.sh
489 $ pkg_delete `cat delete_order`
490 $ sh rebuild.sh
491 .Ed
492 .Pp
493 Or perhaps to rebuild a specific package and all packages which depend
494 on it:
495 .Bd -literal -offset indent
496 $ pkgdepgraph -O glib -D \*[Gt] delete_order
497 $ pkgdepgraph -O glib -R \*[Gt] rebuild.sh
498 $ pkg_delete `cat delete_order`
499 $ sh rebuild.sh
500 .Ed
501 .Pp
502 Finally, to see the current state of the installed packages after some
503 packages have been deleted, and some (but perhaps not all) have been
504 reinstalled:
505 .Bd -literal -offset indent
506 $ pkgdepgraph out-of-date.dot | dot -Tps \*[Gt] current.ps
507 .Ed
508 .Sh SEE ALSO
509 .Xr dot 1 ,
510 .Xr dotty 1 ,
511 .Xr lintpkgsrc 1
512 .Sh AUTHORS
513 .An Andrew Brown Aq atatat@netbsd.org
514 .Sh BUGS
515 .Nm
516 was written in
517 .Xr perl 1 ,
518 but I believe the balance of code layout and comments is actually
519 reasonable, despite what you may think of perl.
520 .Pp
521 The
522 .Dq rebuild
523 output,
524 .Dq fetch
525 output, and the generic
526 .Dq make target
527 output (see the
528 .Fl R ,
529 .Fl F ,
530 and
531 .Fl m
532 options) do not deal very well with packages that have moved within
533 the pkgsrc tree.
534 Feeding the output of
535 .Xr lintpkgsrc 1
536 .Fl g
537 to
538 .Nm
539 can offset this (it contains the current paths to all packages under
540 .Pa PKGSRCDIR )
541 but sometimes is necessary that you edit the generated scripts by hand
542 to work around this.