path: root/pkgtools/pkgdepgraph/files/pkgdepgraph.0

PKGDEPGRAPH(1)          NetBSD General Commands Manual          PKGDEPGRAPH(1)

NNAAMMEE
     ppkkggddeeppggrraapphh - visual representation of installed packages

SSYYNNOOPPSSIISS
     ppkkggddeeppggrraapphh [--AAaaCCccDDeeFFffggLLllooRRrrssvv] [--dd _p_k_g___d_b_d_i_r] [--KK _p_a_c_k_a_g_e_s] [--MM _m_a_k_e]
                 [--mm _t_a_r_g_e_t] [--OO _p_a_c_k_a_g_e] [--PP _p_k_g_s_r_c_d_i_r] [--SS _p_a_c_k_a_g_e]
                 [--tt _t_a_r_g_e_t] [--UU _p_a_c_k_a_g_e] [_d_a_t_a _._._.]

DDEESSCCRRIIPPTTIIOONN
     ppkkggddeeppggrraapphh emits a _d_o_t 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 _+_B_U_I_L_D___I_N_F_O and _+_R_E_Q_U_I_R_E_D___B_Y in order to gather its data.

     ppkkggddeeppggrraapphh 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 lintpkgsrc(1) --ii, audit-packages(1), or the output from a pre-
     vious incantation of this program.

     In the latter case, ppkkggddeeppggrraapphh 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.

     The graph defaults to black, but if data from lintpkgsrc(1) --ii or
     _a_u_d_i_t_-_p_a_c_k_a_g_e_s is given, or if a specific package is asserted to be out
     of date (via the --OO option), then nodes (and edges leading from them)
     will be colored in the following manner:

     green   The package is completely up to date.

     orange  The package is up to date, but some of its dependencies require
             updating.

     red     The package is out of date or has had a security advisory issued
             against it, and should be replaced.

     purple  The package was not found in the local pkgsrc tree.

     blue    The package depends on something not found in the local pkgsrc
             tree.

     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 ppkkggddeeppggrraapphh package with which the graph was recol-
             ored.

     It is important to note that all installed packages fall into one (or
     more) of the following categories:

     installed    Any installed package.

     out of date  Any package that can be upgraded.

     stale        Any package that depends on a package that is out of date.

     leaf         Any package that is not depended on by any other package.

     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:

     --AA       This option modifies the output of --RR to use pkg_add(1) to rein-
              stall deleted packages, instead of building directly from the
              pkgsrc tree.

     --aa       All packages.  This option can be specified more than once to
              augment the meaning of ``all'' as it relates to the selected
              output mode.  For the default graph output, this option has no
              effect.  When used with --mm where the default output is the list
              of out of date packages, one --aa will make ppkkggddeeppggrraapphh also list
              stale packages, and a second --aa will make it list all installed
              packages.

     --CC       Asserts --cc and adds ``CLEANDEPENDS=YES'' so that all rebuilt
              dependencies are cleaned as well.

     --cc       Inserts a ``make clean'' command in the set of instructions to
              rebuild packages (see the --RR option) after they are installed.
              The --cc option used to enable graph coloring, but now graph col-
              oring is done automatically if any coloring data is given.

     --DD       Instead of the standard graph output, ppkkggddeeppggrraapphh lists the
              packages that need to be deleted, in ``least required first''
              order, so that they can be deleted without any dependency prob-
              lems.  This is a good first step to take before rebuilding all
              your packages that are out of date (see the --RR option).  This
              option is an alias for --aass.

     --dd _p_k_g___d_b_d_i_r
              The location of the package database files.  This defaults to
              the value of the _P_K_G___D_B_D_I_R environment variable, if it is set,
              or to _@_P_K_G___D_B_D_I_R_@.

     --ee       Adds an ``existence check'' to each of the lines of sh(1) style
              output so that commands can be skipped if the package is already
              installed.

     --FF       Makes ppkkggddeeppggrraapphh emit a series of sh(1) commands that will
              fetch all the required distfiles for rebuilding out of date
              packages.  This option is an alias for --mm _f_e_t_c_h.

     --ff       Force a rebuild of all dependent packages.  This option is for
              use in conjunction with the --UU option to force a rebuild of all
              the dependencies of a package to be updated.

     --gg       Add package subgraph groupings.  This places all packages with a
              common prefix (e.g., ``p5'' or ``gimp'') in a subgraph with a
              line around it so you can visually associate packages.

     --KK _p_a_c_k_a_g_e_s
              The base location or url from which to install binary packages.
              This defaults to the value of PKG_PATH, or to PACKAGES with
              ``/All'' added to the end, or to the value determined for pkgsr-
              cdir (see the --PP option) with ``/packages/All'' appended to it.

     --LL       Limit the graph to those packages that are out of date or ulti-
              mately depend on some package that is.  When used with --mm or --ss,
              this limits the list to ``leaf'' packages that are out of date
              or stale.

     --ll       Adds package ``location'' information to the labels on the
              nodes.  This is the path to the package under the local pkgsrc
              tree.

     --MM _m_a_k_e  Sets the name or path of the proper make(1) program for the
              sh(1) commands generated by the --RR and --FF options.  Some systems
              may have more than one make(1) command or the correct choice
              might not be named ``make''.  The default value for this is
              taken from the MAKE environment variable, if it is set, or is
              simply ``make''.

     --mm _t_a_r_g_e_t
              Emits generic sh(1) commands to ``make _t_a_r_g_e_t'' for each listed
              package.  One interesting target to specify is _'_$_*_' since that
              will yield a script that will pass its own command line argu-
              ments to make for processing.

     --OO _p_a_c_k_a_g_e
              Marks _p_a_c_k_a_g_e 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 lintpkgsrc(1) --ii for graph coloring information.

     --oo       Adds a package ``order'' number to each node's label.  The num-
              ber 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 ``leaf'' nodes numbered one.

     --PP _p_k_g_s_r_c_d_i_r
              The root of the pkgsrc source tree.  This defaults to the value
              of the _P_K_G_S_R_C_D_I_R environment variable, if it is set, or to
              _@_P_K_G_S_R_C_D_I_R_@.

     --RR       Instead of the standard graph output, emits a series of 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 --DD option).  This
              option is an alias for --eeLLmm _t_a_r_g_e_t.  See the --tt option for a
              description of what value is used for _t_a_r_g_e_t.

     --rr       Reverses the order in which the packages are listed.

     --SS _p_a_c_k_a_g_e
              Selects a subgraph of the installed package base around which to
              generate output.  By default, if a subgraph of _p_a_c_k_a_g_e is
              requested, only _p_a_c_k_a_g_e and those packages immediately above and
              below it in the graph will be listed.  To select only those
              immediately below, prefix a ``-'' to the package name.  To
              select all packages below _p_a_c_k_a_g_e, prefix ``--'' to the package
              name.  To select packages above _p_a_c_k_a_g_e, use ``+'' and ``++'' as
              appropriate.  To select all packages remotely connected to
              _p_a_c_k_a_g_e, add ``='' to the beginning.  Note: take care when using
              this option with generated lists or sh scripts.  Since the sub-
              graph 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.

     --ss       Print a simple list of packages instead of sh commands.  The
              default output set for this command is out of date packages from
              the entire package set.  Use combinations of --aa, --LL, --OO _p_a_c_k_a_g_e,
              and --SS _p_a_c_k_a_g_e to select more or other package lists.

     --tt _t_a_r_g_e_t
              Changes the target of the --RR output from ``install'' to _t_a_r_g_e_t
              in case you want to ``make package'' or some other target.

     --UU _p_a_c_k_a_g_e
              Generates a graph with only the out of date dependencies of
              _p_a_c_k_a_g_e marked in red (ie, packages that are out of date but not
              dependencies of _p_a_c_k_a_g_e will not be considered out of date).
              This will show the entire effect of deleting all related pack-
              ages in order to update the dependencies of the given package.
              If the --ff option is used, then all the dependencies of _p_a_c_k_a_g_e
              will be marked as out of date and the effect on the installed
              package base will be accordingly greater.

     --vv       Adds the package version number to the node's label in the
              graph.

EENNVVIIRROONNMMEENNTT
   MMAAKKEE
     The default name for the ``make'' program used in the sh(1) commands gen-
     erated by the --FF and --RR output modes.

   PPKKGG__DDBBDDIIRR
     Where to find registered packages instead of _@_P_K_G___D_B_D_I_R_@.

   PPKKGGSSRRCCDDIIRR
     Where the pkgsrc tree is located instead of _@_P_K_G_S_R_C_D_I_R_@.

   PPKKGG__PPAATTHH
   PPAACCKKAAGGEESS
     Two variables that can be used as a location for binary packages.  See
     the --AA and --KK options for more details.

EEXXAAMMPPLLEESS
     The default output:

           $ pkgdepgraph | dotty -

     To generate graph output for later use, and a postscript image of it:

           $ lintpkgsrc -i > pkgdepgraph.in
           $ audit-packages >> pkgdepgraph.in
           $ pkgdepgraph -lv pkgdepgraph.in > pkgdepgraph.dot
           $ dot -Tps pkgdepgraph.dot > pkgdepgraph.ps

     To generate a graph of just the out of date nodes as a gif:

           $ pkgdepgraph -L pkgdepgraph.in > out-of-date.dot
           $ dot -Tgif out-of-date.dot > out-of-date.gif

     To make a list of packages that need to be removed in order to bring all
     packages up to date:

           $ pkgdepgraph -D pkgdepgraph.in > delete_order
           $ pkgdepgraph -R pkgdepgraph.in > rebuild.sh

     To subsequently delete all out of date and stale packages:

           $ pkg_delete `cat delete_order`
           $ sh rebuild.sh

     You may also find it useful to ``pre-fetch'' all the required distfiles
     for the rebuild as below, so that you can do all the rebuilding while
     off-line:

           $ pkgdepgraph -F pkgdepgraph.in > fetch.sh
           $ sh fetch.sh

     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.

     You can also ``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.

           $ pkgdepgraph -D pkgdepgraph.in > delete_order
           $ pkgdepgraph -R pkgdepgraph.in >> rebuild.sh
           $ pkg_delete `cat delete_order`
           $ sh rebuild.sh

     It is important to note that if you have specifically installed a partic-
     ular package that is a dependency, and another package (or other pack-
     ages) exist that can satisfy the same dependency, you should probably
     pre-install that particular package.  There is no guarantee that the typ-
     ical processing order will install the same package.

     A similar task is to update all the out of date dependencies of an pack-
     age, rebuild the package, and any others that might share the same depen-
     dencies:

           $ pkgdepgraph -U mozilla -D pkgdepgraph.in > delete_order
           $ pkgdepgraph -U mozilla -R pkgdepgraph.in > rebuild.sh
           $ pkg_delete `cat delete_order`
           $ sh rebuild.sh

     Or perhaps to rebuild a specific package and all packages which depend on
     it:

           $ pkgdepgraph -O glib -D > delete_order
           $ pkgdepgraph -O glib -R > rebuild.sh
           $ pkg_delete `cat delete_order`
           $ sh rebuild.sh

     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:

           $ pkgdepgraph out-of-date.dot | dot -Tps > current.ps

SSEEEE AALLSSOO
     dot(1), dotty(1), lintpkgsrc(1)

AAUUTTHHOORRSS
     Andrew Brown <atatat@netbsd.org>

BBUUGGSS
     ppkkggddeeppggrraapphh was written in perl(1), but I believe the balance of code
     layout and comments is actually reasonable, despite what you may think of
     perl.

     The ``rebuild'' output, ``fetch'' output, and the generic ``make target''
     output (see the --RR, --FF, and --mm options) do not deal very well with pack-
     ages that have moved within the pkgsrc tree.  It is necessary that you
     edit the rebuild script by hand to work around this.

NetBSD 1.6                       March 6, 2003                      NetBSD 1.6