.\" $NetBSD: pkgdepgraph.1,v 1.13 2013/07/20 21:50:53 wiz Exp $ .\" .\" Copyright (c) 2002, 2003, 2004 by Andrew Brown .\" Absolutely no warranty. .\" .Dd July 28, 2004 .Dt PKGDEPGRAPH 1 .Sh NAME .Nm pkgdepgraph .Nd visual representation of installed packages .Sh SYNOPSIS .Nm .Op Fl AaCcDeFfgLloRrsv .Op Fl d Ar pkg_dbdir .Op Fl i Ar impact .Op Fl K Ar packages .Op Fl M Ar make .Op Fl m Ar target .Op Fl O Ar package .Op Fl P Ar pkgsrcdir .Op Fl S Ar package .Op Fl t Ar target .Op Fl U Ar package .Op Pa data ... .Sh DESCRIPTION .Nm emits a .Pa dot language description of the locally installed packages, with the inter-dependencies reduced to a minimal set of edges. It scans each directory under the package database directory for files named .Pa +BUILD_INFO and .Pa +REQUIRED_BY in order to gather its data. .Pp .Nm will also read any files passed to it as arguments (or stdin if it is not connected to a tty), in search of output that resembles that of either .Xr lintpkgsrc 1 .Fl i , .Xr lintpkgsrc 1 .Fl g , .Xr audit-packages 8 , or the output from a previous incantation of this program. .Pp In the latter case, .Nm will recolor the graph passed as input based, as usual, on information about currently installed pkgs. Packages that are in the input graph, but not currently installed, will be colored black, those that are installed will be colored green, and those that remain out of date for some reason will remain red. .Pp The graph defaults to black, but if data from .Xr lintpkgsrc 1 .Fl i or .Pa audit-packages is given, or if a specific package is asserted to be out of date (via the .Fl O option), then nodes (and edges leading from them) will be colored in the following manner: .Bl -tag -width purple .It green The package is completely up to date. .It orange The package is up to date, but some of its dependencies require updating. .It red The package is out of date or has had a security advisory issued against it, and should be replaced. .It purple The package was not found in the local pkgsrc tree. .It blue The package depends on something not found in the local pkgsrc tree. .It black The package has been removed and not yet replaced, or the graph is uncolored. The difference between an uncolored graph and a graph that has been recolored almost entirely black as a result of removing all the packages can be visually detected by the color of the .Nm package with which the graph was recolored. .El .Pp It is important to note that all installed packages fall into one (or more) of the following categories: .Bl -tag -width out-of-date .It installed Any installed package. .It out of date Any package that can be upgraded. .It stale Any package that depends on a package that is out of date. .It leaf Any package that is not depended on by any other package. .El .Pp Selecting the type or types of packages that are listed, and how the information is put to use, can be controlled by the following options: .Bl -tag -width package .It Fl A This option modifies the output of .Fl R to use .Xr pkg_add 1 to reinstall deleted packages, instead of building directly from the pkgsrc tree. .It Fl a All packages. This option can be specified more than once to augment the meaning of .Dq all as it relates to the selected output mode. For the default graph output, this option has no effect. When used with .Fl m where the default output is the list of out of date packages, one .Fl a will make .Nm also list stale packages, and a second .Fl a will make it list all installed packages. .It Fl C Asserts .Fl c and adds .Dq CLEANDEPENDS=YES so that all rebuilt dependencies are cleaned as well. .It Fl c Inserts a .Dq make clean command in the set of instructions to rebuild packages (see the .Fl R option) after they are installed. The .Fl c option used to enable graph coloring, but now graph coloring is done automatically if any coloring data is given. .It Fl D Instead of the standard graph output, .Nm lists the packages that need to be deleted, in .Dq least required first order, so that they can be deleted without any dependency problems. This is a good first step to take before rebuilding all your packages that are out of date (see the .Fl R option). This option is an alias for .Fl as . .It Fl d Ar pkg_dbdir The location of the package database files. This defaults to the value of the .Pa PKG_DBDIR environment variable, if it is set, or to .Pa @PKG_DBDIR@ . .It Fl e Adds an .Dq existence check to each of the lines of .Xr sh 1 style output so that commands can be skipped if the package is already installed. .It Fl F Makes .Nm emit a series of .Xr sh 1 commands that will fetch all the required distfiles for rebuilding out of date packages. This option is an alias for .Fl m Ar fetch . .It Fl f Force a rebuild of all dependent packages. This option is for use in conjunction with the .Fl U option to force a rebuild of all the dependencies of a package to be updated. .It Fl g Add package subgraph groupings. This places all packages with a common prefix (e.g., .Dq p5 or .Dq gimp ) in a subgraph with a line around it so you can visually associate packages. .It Fl i Ar impact Specify the impact you want to allow when rebuilding packages. The impact of a given package being rebuilt is a number that reflects the longest path from the .Dq top of the installed packages (those packages upon which most other packages depend) to the .Dq bottom of the installed packages (those packages upon which no other packages depend). A package that needs to be rebuilt but has nothing above it in the tree requiring rebuilding and nothing below it has an impact of 0. Values of 10 or more for .Ar impact will probably eliminate nothing from the rebuild list. The value for .Ar impact can also be the name of a package to be avoided when constructing the list of things to be rebuilt. .It Fl K Ar packages The base location or url from which to install binary packages. This defaults to the value of PKG_PATH, or to PACKAGES with .Dq Dv /All added to the end, or to the value determined for pkgsrcdir (see the .Fl P option) with .Dq Dv /packages/All appended to it. .It Fl L Limit the graph to those packages that are out of date or ultimately depend on some package that is. When used with .Fl m or .Fl s , this limits the list to .Dq leaf packages that are out of date or stale. .It Fl l Adds package .Dq location information to the labels on the nodes. This is the path to the package under the local pkgsrc tree. .It Fl M Ar make Sets the name or path of the proper .Xr make 1 program for the .Xr sh 1 commands generated by the .Fl R and .Fl F options. Some systems may have more than one .Xr make 1 command or the correct choice might not be named .Dq make . The default value for this is taken from the MAKE environment variable, if it is set, or is simply .Dq make . .It Fl m Ar target Emits generic .Xr sh 1 commands to .Dq make Ar target for each listed package. One interesting target to specify is .Ar '$*' since that will yield a script that will pass its own command line arguments to make for processing. .It Fl O Ar package Marks .Ar package as out of date so that you can see the impact of deleting dependent packages and rebuilding everything. This option can be used as a quick alternative to using the output from .Xr lintpkgsrc 1 .Fl i for graph coloring information. .It Fl o Adds a package .Dq order number to each node's label. The number indicates only the place of the node in the hierarchy, such that each node has a number greater than that of anything which depends on it, and with the .Dq leaf nodes numbered one. .It Fl P Ar pkgsrcdir The root of the pkgsrc source tree. This defaults to the value of the .Pa PKGSRCDIR environment variable, if it is set, or to .Pa @PKGSRCDIR@ . .It Fl R Instead of the standard graph output, emits a series of .Xr sh 1 commands that will rebuild all the out of date packages by rebuilding all the deleted leaf packages. Packages that are out of date should be deleted first (see the .Fl D option). This option is an alias for .Fl eLm Ar target . See the .Fl t option for a description of what value is used for .Ar target . .It Fl r Reverses the order in which the packages are listed. .It Fl S Ar package Selects a subgraph of the installed package base around which to generate output. By default, if a subgraph of .Ar package is requested, only .Ar package and those packages immediately above and below it in the graph will be listed. To select only those immediately below, prefix a .Dq - to the package name. To select all packages below .Ar package , prefix .Dq -- to the package name. To select packages above .Ar package , use .Dq + and .Dq ++ as appropriate. To select all packages remotely connected to .Ar package , add .Dq = to the beginning. Note: take care when using this option with generated lists or sh scripts. Since the subgraph of packages selected by this option may not include all stale or out of date packages involved in a proper package update procedure, the lists may be incomplete and can cause problems. .It Fl s Print a simple list of packages instead of .Xr sh 1 commands. The default output set for this command is out of date packages from the entire package set. Use combinations of .Fl a , .Fl L , .Fl O Ar package , and .Fl S Ar package to select more or other package lists. .It Fl t Ar target Changes the target of the .Fl R output from .Dq install to .Ar target in case you want to .Dq make package or some other target. .It Fl U Ar package Generates a graph with only the out of date dependencies of .Ar package marked in red (ie, packages that are out of date but not dependencies of .Ar package will not be considered out of date). This will show the entire effect of deleting all related packages in order to update the dependencies of the given package. If the .Fl f option is used, then all the dependencies of .Ar package will be marked as out of date and the effect on the installed package base will be accordingly greater. .It Fl v Adds the package version number to the node's label in the graph. .El .Sh ENVIRONMENT .Ss MAKE The default name for the .Dq make program used in the .Xr sh 1 commands generated by the .Fl F and .Fl R output modes. .Ss PKG_DBDIR Where to find registered packages instead of .Pa @PKG_DBDIR@ . .Ss PKGSRCDIR Where the pkgsrc tree is located instead of .Pa @PKGSRCDIR@ . .Ss PKG_PATH .Ss PACKAGES Two variables that can be used as a location for binary packages. See the .Fl A and .Fl K options for more details. .Sh EXAMPLES The default output: .Bd -literal -offset indent $ pkgdepgraph | dotty - .Ed .Pp To generate graph output for later use, and a postscript image of it: .Bd -literal -offset indent $ lintpkgsrc -i \*[Gt] pkgdepgraph.in $ audit-packages \*[Gt]\*[Gt] pkgdepgraph.in $ pkgdepgraph -lv pkgdepgraph.in \*[Gt] pkgdepgraph.dot $ dot -Tps pkgdepgraph.dot \*[Gt] pkgdepgraph.ps .Ed .Pp To generate a graph of just the out of date nodes as a gif: .Bd -literal -offset indent $ pkgdepgraph -L pkgdepgraph.in \*[Gt] out-of-date.dot $ dot -Tgif out-of-date.dot \*[Gt] out-of-date.gif .Ed .Pp To make a list of packages that need to be removed in order to bring all packages up to date: .Bd -literal -offset indent $ pkgdepgraph -D pkgdepgraph.in \*[Gt] delete_order $ pkgdepgraph -R pkgdepgraph.in \*[Gt] rebuild.sh .Ed .Pp To rebuild everything that has no other rebuild requirements: .Bd -literal -offset indent $ pkgdepgraph -D pkgdepgraph.in -i0 \*[Gt] delete_order $ pkgdepgraph -R pkgdepgraph.in -i0 \*[Gt] rebuild.sh .Ed .Pp Or, to rebuild everything except those things that would require rebuilding perl: .Bd -literal -offset indent $ pkgdepgraph -D pkgdepgraph.in -iperl \*[Gt] delete_order $ pkgdepgraph -R pkgdepgraph.in -iperl \*[Gt] rebuild.sh .Ed .Pp To subsequently delete all out of date and stale packages: .Bd -literal -offset indent $ pkg_delete `cat delete_order` $ sh rebuild.sh .Ed .Pp You may also find it useful to .Dq pre-fetch all the required distfiles for the rebuild as below, so that you can do all the rebuilding while off-line: .Bd -literal -offset indent $ pkgdepgraph -F pkgdepgraph.in \*[Gt] fetch.sh $ sh fetch.sh .Ed .Pp Running the rebuild script will probably take a while, but if you need to stop it or it stops by itself for any reason, you can rerun the script, and it will pick up where it left off. If there are certain packages that you want installed before others are reinstalled, feel free to reorder the lines in the script. .Pp You can also .Dq make clean wherever you like when the rebuild script is not running, or even update your tree in between runs of the script, though in the latter case, it would be prudent to resume the script in the following manner so that any packages that are newly out of date are removed and replaced. .Bd -literal -offset indent $ pkgdepgraph -D pkgdepgraph.in \*[Gt] delete_order $ pkgdepgraph -R pkgdepgraph.in \*[Gt]\*[Gt] rebuild.sh $ pkg_delete `cat delete_order` $ sh rebuild.sh .Ed .Pp It is important to note that if you have specifically installed a particular package that is a dependency, and another package (or other packages) exist that can satisfy the same dependency, you should probably pre-install that particular package. There is no guarantee that the typical processing order will install the same package. .Pp A similar task is to update all the out of date dependencies of an package, rebuild the package, and any others that might share the same dependencies: .Bd -literal -offset indent $ pkgdepgraph -U mozilla -D pkgdepgraph.in \*[Gt] delete_order $ pkgdepgraph -U mozilla -R pkgdepgraph.in \*[Gt] rebuild.sh $ pkg_delete `cat delete_order` $ sh rebuild.sh .Ed .Pp Or perhaps to rebuild a specific package and all packages which depend on it: .Bd -literal -offset indent $ pkgdepgraph -O glib -D \*[Gt] delete_order $ pkgdepgraph -O glib -R \*[Gt] rebuild.sh $ pkg_delete `cat delete_order` $ sh rebuild.sh .Ed .Pp Finally, to see the current state of the installed packages after some packages have been deleted, and some (but perhaps not all) have been reinstalled: .Bd -literal -offset indent $ pkgdepgraph out-of-date.dot | dot -Tps \*[Gt] current.ps .Ed .Sh SEE ALSO .Xr dot 1 , .Xr dotty 1 , .Xr lintpkgsrc 1 .Sh AUTHORS .An Andrew Brown Aq Mt atatat@netbsd.org .Sh BUGS .Nm was written in .Xr perl 1 , but I believe the balance of code layout and comments is actually reasonable, despite what you may think of perl. .Pp The .Dq rebuild output, .Dq fetch output, and the generic .Dq make target output (see the .Fl R , .Fl F , and .Fl m options) do not deal very well with packages that have moved within the pkgsrc tree. Feeding the output of .Xr lintpkgsrc 1 .Fl g to .Nm can offset this (it contains the current paths to all packages under .Pa PKGSRCDIR ) but sometimes is necessary that you edit the generated scripts by hand to work around this.