website/manual/en/graft.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <title>Graft</title>
   5 </head>
   6
   7 <body>
   8
   9 <center>
  10 <h1><em>Graft</em> - a package management utility</h1>
  11 </center>
  12
  13 <h4>Prepared by Peter Samuel
  14 <a href="mailto:peter.r.samuel@gmail.com"><tt>&lt;peter.r.samuel@gmail.com&gt;</tt></a></h4>
  15
  16 <h4>$Revision: 2.16 $</h4>
  17 <h4>$Date: 2018/04/16 14:54:07 $</h4>
  18
  19 <blockquote>
  20     <p> <em><strong>graft:</strong> To insert (a graft) in a branch or stem
  21     of another tree; to propagate by insertion in another stock; also, to
  22     insert a graft upon. To implant a portion of (living flesh or skin) in
  23     a lesion so as to form an organic union. To join (one thing) to another
  24     as if by grafting, so as to bring about a close union.</em> </p>
  25 </blockquote>
  26
  27 <hr>
  28
  29 <h2><a name="contents">Contents</a></h2>
  30
  31     <ul>
  32
  33         <li> <a href="#intro">Introduction</a>
  34
  35         <li> <a href="#rationale">Rationale</a>
  36
  37         <li> <a href="#research">Research</a>
  38
  39         <li> <a href="#design">Design</a>
  40
  41             <ul>
  42                 <li> <a href="#precedence">Control file precedence &amp; conflict resolution</a>
  43             </ul>
  44
  45         <li> <a href="#history">History</a>
  46
  47         <li> <a href="#installation">Installation</a>
  48
  49             <ul>
  50                 <li> <a href="#rpm_and_deb">Creating RPM and DEB packages</a>
  51
  52                 <li> <a href="#gotchas">Grafting <em>Graft</em> and
  53                 <em>Perl</em> - the bootstrap problem</a>
  54             </ul>
  55
  56         <li> <a href="#using-graft">Using <em>Graft</em></a>
  57
  58             <ul>
  59
  60                 <li> <a href="#compiling-packages">Compiling
  61                 Packages</a>
  62
  63                 <li><a href="#usage"><em>Graft</em> command line
  64                 options</a>
  65
  66                     <ol>
  67                         <li><a href="#graft-i">Install</a>
  68                         <li><a href="#graft-d">Delete</a>
  69                         <li><a href="#graft-p">Prune</a>
  70                         <li><a href="#graft-L">Information</a>
  71                     </ol>
  72
  73                 <li> <a href="#testing">Testing the <em>Graft</em>
  74                 Installation</a>
  75
  76                 <li> <a href="#installing-packages">Installing
  77                 Packages</a>
  78
  79                 <li> <a href="#bypass">Bypassing package
  80                 directories</a>
  81
  82                 <li> <a href="#include">Including specific files
  83                 and/or directories</a>
  84
  85                 <li> <a href="#exclude">Excluding specific files
  86                 and/or directories</a>
  87
  88                 <li> <a href="#config_dirs">Grafting configuration files</a>
  89
  90                 <li><a href="#partial-graft">Grafting part of a
  91                 package</a>
  92
  93                 <li> <a href="#deleting-packages">Deleting and/or
  94                 Upgrading Packages</a>
  95
  96                 <li><a href="#transitioning">Transitioning a package to
  97                 <em>Graft</em> control</a>
  98
  99                 <li> <a href="#conflicts">Conflict Processing</a>
 100
 101                 <li> <a href="#exitstatus">Exit Status</a>
 102
 103             </ul>
 104
 105             <li> <a href="#other-pkg-tools">Using <em>Graft</em> with
 106             other package management tools</a>
 107
 108             <li> <a href="#availability">Availability</a>
 109
 110             <li> <a href="#license">License</a>
 111
 112     </ul>
 113
 114 <hr>
 115
 116 <h2><a name="intro">Introduction</a></h2>
 117
 118 <p> <em>Graft</em> provides a mechanism for managing multiple packages
 119 under a single directory hierarchy. It was inspired by both <em>Depot</em>
 120 (Carnegie Mellon University) and <em>Stow</em> (Bob Glickstein). </p>
 121
 122 <p> For the purposes of this discussion a <em>package</em> is defined as
 123 a suite of programs and files that make up an individual product. For
 124 example, the <em>package</em> known as <em>gcc</em> consists of the compiler
 125 and preprocessor programs, include files, manual pages and any other
 126 associated file or program. The concept of a <em>package</em> should not be
 127 confused with some vendor's definitions that are - by this definition -
 128 actually collections of <em>packages</em>. </p>
 129
 130 <p> Special thanks to Gordon Rowell, Charles Butcher, Charlie Brady,
 131 Robert Maldon and Matias A. Fonzo for design suggestions and contributions.
 132 </p>
 133
 134 <hr>
 135
 136 <h2><a name="rationale">Rationale</a></h2>
 137
 138 <p> In any reasonably large environment, many software packages will be
 139 installed. The installation location for these packages usually follows
 140 one of three rationales - each with its own advantages and drawbacks: </p>
 141
 142     <ol>
 143
 144         <li> <p> Each package is isolated from all other packages by
 145         installing it into a self contained directory tree. All binaries,
 146         manual pages, library and configuration files are stored under
 147         a single directory tree. This directory tree contains NO other
 148         files which are not the exclusive domain of the package in
 149         question. </p>
 150
 151         <p> This method makes package demarcation obvious. As each
 152         package is self contained, identification of any file within a
 153         package is immediately apparent. </p>
 154
 155         <p> Multiple versions of packages can be installed fairly easily
 156         to accommodate acceptance testing of new versions and/or legacy
 157         systems. </p>
 158
 159         <p> However, the use of individual package directories can
 160         lead to VERY long <strong>$PATH</strong> and <strong>$MANPATH</strong> environment
 161         variables. Some shells may not be able to handle such long
 162         variables. Whenever a new package is added, each user MUST
 163         update their <strong>$PATH</strong> and <strong>$MANPATH</strong> to make the package
 164         available. </p>
 165
 166         <li> <p> Packages are installed under a common directory tree.
 167         Binaries for all packages are grouped in a single directory,
 168         manual pages for all packages in another directory and so on.
 169         </p>
 170
 171         <p> This method eliminates the need for continually updating long
 172         <strong>$PATH</strong> variables for each user. As soon as a package is
 173         placed into the common '<tt>bin</tt>' directory it is immediately
 174         available to all users (after a shell rehash if necessary). </p>
 175
 176         <p> However, when a package is to be updated it is often very
 177         difficult to isolate all the files related to a particular
 178         package if they are intermingled with unrelated files. </p>
 179
 180         <li> <p> A combination of methods (1) and (2). </p>
 181
 182     </ol>
 183
 184 <p> In an effort to maximise the advantages and minimise the
 185 disadvantages, <em>Depot</em>, <em>Stow</em> and <em>Graft</em> adopt a similar
 186 philosophy: </p>
 187
 188 <blockquote>
 189     <p> Packages are installed in self contained directory trees and
 190     symbolic links from a common area are made to the package files. </p>
 191 </blockquote>
 192
 193 <p> This approach allows multiple versions of the same package to co-exist
 194 on the one system. One version is the commonly available version and
 195 symbolic links will be made to this version. New versions can be tested
 196 and once acceptable can replace the current commonly available version.
 197 Older versions can still be used for legacy systems by using the
 198 '<em>real</em>' path name to the package instead of the '<em>common</em>'
 199 path name. </p>
 200
 201 <p> The size and complexity of environment variables such as <strong>$PATH</strong>
 202 and <strong>$MANPATH</strong> is minimised because only the common area is
 203 required. Any special cases can also be accommodated but these will
 204 usually be in the minority when compared with the number of commonly
 205 available packages. </p>
 206
 207 <hr>
 208
 209 <h2><a name="research">Research</a></h2>
 210
 211 <p> <strong>Note:</strong> Development of <em>Graft</em> began in late 1996. The
 212 comments regarding the packages listed below reflect their functionality
 213 and behaviour at that time and may not necessarily reflect their current
 214 functionality and behaviour. </p>
 215
 216 <p> As stated earlier, <em>Graft</em> was inspired by <em>Depot</em> and
 217 <em>Stow</em>. Both these systems were examined and finally rejected for
 218 the following reasons: </p>
 219
 220     <dl>
 221
 222         <dt> <em>Depot</em>
 223             <a href="ftp://ftp.andrew.cmu.edu/pub/depot/depot.tar.gz">ftp://ftp.andrew.cmu.edu/pub/depot/depot.tar.gz</a>
 224
 225             <dd> <p> <em>Depot</em> is very flexible yet cumbersome. </p>
 226
 227             <p> It requires a database file to be created which
 228             provides a snapshot of the current state of both the package
 229             repository and the <em>Depot</em> target. It is possible to
 230             inadvertently destroy the package repository if the database
 231             is damaged. </p>
 232
 233             <p> <em>Depot</em> assumes &quot;<em>ownership</em>&quot; of the
 234             target area, making it almost impossible to accommodate
 235             packages that are not under the control of <em>Depot</em>.
 236             ("<em>Ownership</em>" in this case means that <em>Depot</em>
 237             assumes ALL files in the target area will be under the
 238             control of <em>Depot</em>. It does not imply that <em>Depot</em>
 239             modifies Unix file permissions). </p>
 240
 241             <p> Because of <em>Depot</em>'s assumed <em>ownership</em> it is
 242             difficult for other packages not under the control of
 243             <em>Depot</em> to be placed in the same target area. </p>
 244
 245             <p> <em>Depot</em> attempts to impose a fixed package repository
 246             relative to the package target. It assumes that all
 247             packages will be stored under
 248             '<tt><em>dir</em>/depot/<em>package</em></tt>' and the target
 249             will be '<tt><em>dir</em></tt>'. This can be overridden on
 250             the command line but the internals of <em>Depot</em> make
 251             this mechanism cumbersome. </p>
 252
 253             <p> <em>Depot</em> is written in C and there are many source
 254             files in its distribution. Local modifications would be
 255             difficult to quickly implement and test. </p>
 256
 257         <dt> <em>Stow</em>
 258              <a href="https://www.gnu.org/software/stow/">https://www.gnu.org/software/stow/</a>
 259
 260             <dd> <p> <em>Stow</em> is a stateless system. It requires no
 261             database or configuration information. </p>
 262
 263             <p> Like <em>Depot</em>, it assumes that the package repository
 264             will be stored under '<tt><em>dir</em>/stow/<em>package</em></tt>'
 265             and the target will be '<tt><em>dir</em></tt>'. This can be
 266             overridden on the command line and works well during the
 267             install phase. </p>
 268
 269             <p> <em>Stow</em> assumes &quot;<em>ownership</em>&quot;
 270             of the target area, making it difficult to accommodate
 271             packages that are not under the control of <em>Stow</em>.
 272             ("<em>Ownership</em>" in this case means that <em>Stow</em>
 273             assumes ALL files in the target area will be under the
 274             control of <em>Stow</em>. It does not imply that <em>Stow</em>
 275             modifies Unix file permissions). </p>
 276
 277             <p> Because of <em>Stow</em>'s assumed <em>ownership</em>
 278             it is difficult for other packages not under the control
 279             of <em>Stow</em> to be placed in the same target area. When
 280             deleting packages, <em>Stow</em> examines everything in the
 281             target directory - whether it is associated with the package
 282             it is trying to delete or not. This can be time consuming and
 283             potentially dangerous as empty directories are also removed
 284             - even empty directories that do not belong to the package
 285             being removed. </p>
 286
 287             <p> <em>Stow</em> has a clever feature of <em>folding</em> and
 288             <em>unfolding</em> directories. It attempts to optimise the
 289             number of symbolic links by making links to directories if
 290             the directory is only associated with a single package. If
 291             at a later date <em>Stow</em> discovers another package that
 292             needs that directory it will <em>unfold</em> that directory
 293             into a collection of symbolic links to files rather than
 294             a single symbolic link to the directory. <em>Stow</em> will
 295             <em>fold</em> the directory when removing packages if the
 296             remainder of the directory is only concerned with a single
 297             package. While clever, this feature is probably a waste of
 298             time and effort. It means that the entire package target
 299             must be scanned to determine package ownership of links and
 300             as packages will usually be replaced by newer versions a
 301             directory <em>fold</em> will probably be short lived. </p>
 302
 303             <p> <em>Stow</em> will sometimes miss potential conflicts when
 304             run in <em>show only</em> mode. The conflicts may occur when a
 305             directory is unfolded and will not show up in <em>show only</em>
 306             mode. </p>
 307
 308             <p> <em>Stow</em>'s author suggests that packages be compiled
 309             such that they refer to files in the target location rather
 310             than the actual package installation directory. This approach
 311             precludes the use of multiple versions of packages with
 312             different configuration and/or library files. </p>
 313
 314             <p> <em>Stow</em> is written in <em>Perl</em> and is only a
 315             few hundred lines of code so local modifications can be
 316             accommodated. However there are very few comments in the
 317             code which makes the process of modification difficult. </p>
 318
 319     </dl>
 320
 321 <p> Since the release of <em>Graft</em> 1.6, the existence of yet another
 322 packaging program has been brought to the author's attention. </p>
 323
 324     <dl>
 325
 326         <dt> <em>Encap</em>
 327              <a href="http://www.ks.uiuc.edu/Development/Computers/docs/sysadmin/Build/encap.html">http://www.ks.uiuc.edu/Development/Computers/docs/sysadmin/Build/encap.html</a>
 328
 329             <dd> <p> <em>Encap</em> grew out of work begun at the University
 330             of Illinois Champaign-Urbana.  It has the same underlying
 331             philosophy as <em>Depot</em>, <em>Stow</em> and <em>Graft</em> -
 332             encapsulate packages into self contained directories and use
 333             symbolic links to make them visible in a common location. </p>
 334
 335             <p> <em>Encap</em> uses a combination of a <em>csh</em> wrapper
 336             and a <em>Perl</em> program to accomplish its work. Like both
 337             <em>Depot</em> and <em>Stow</em>, <em>Encap</em> assumes that all
 338             compiled packages will live under a single directory hierarchy
 339             - by default '<tt><em>dir</em>/encap/<em>package</em></tt>'. It
 340             then attempts to create a symbolic link tree for ALL the
 341             packages under this area. There doesn't appear to be any
 342             easy way to support the quick addition or removal of a single
 343             package. </p>
 344
 345             <p> A new release of <em>Encap</em> incorporating many new
 346             features was expected to be available in early 1997, however
 347             no release greater than version 1.2 has been forthcoming. </p>
 348
 349             <p> One good feature of <em>Encap</em> is the ability to exclude
 350             specific files from the package tree. This concept has been
 351             incorporated into <em>Graft</em> 1.7 and above. </p>
 352
 353     </dl>
 354
 355 <p> Since the release of <em>Graft</em> 2.3, the existence of
 356 several another packaging programs have been brought to the author's
 357 attention. Rather than outline their features and whether or not the
 358 author feels they are superior (or inferior) to <em>Graft</em>, a reference
 359 to each package and a brief description is given and further research
 360 is left as an exercise for the reader: </p>
 361
 362     <dl>
 363
 364         <dt> <em>stowES</em>
 365
 366             <dd>
 367
 368 <pre>
 369 <a href="https://os.inf.tu-dresden.de/~adam/stowES/">https://os.inf.tu-dresden.de/~adam/stowES/</a>
 370 </pre>
 371
 372             <p> &quot;<em>stowES (stow Enhancement Script) is
 373             a Perl script which tries to ease the use of the "stow"
 374             packaging program and software which can be compiled and
 375             installed with autoconf. It automates the compilation and
 376             installation of software packages and provides some useful
 377             functions to maintain your stow packages (e.g., list packages,
 378             check packages for integrity, etc.).</em>&quot; </p>
 379
 380         <dt> <em>opt_depot</em>
 381
 382             <dd>
 383
 384 <pre>
 385 <a href="https://github.com/jonabbey/opt_depot">https://github.com/jonabbey/opt_depot</a>
 386 </pre>
 387
 388             <p> &quot;<em>opt_depot is a suite of Perl scripts which makes
 389             it easy to manage installed software across a wide range
 390             of client systems. opt_depot makes it possible to keep all
 391             files associated with a program together in one directory,
 392             so installation and de-installation is simple. opt_depot is
 393             easy to manage, and provides a scheme for installing software
 394             in a truly portable fashion; packages may be installed locally
 395             on client systems, or kept in a central package archive for
 396             NFS access. </em>&quot;</p>
 397
 398             <p> This site also has links to several other package
 399             management utilities, including <em>Graft</em>. </p>
 400
 401         <dt> <em>relink</em>
 402
 403             <dd>
 404
 405 <pre>
 406 <a href="http://sourceforge.net/projects/relink/">http://sourceforge.net/projects/relink/</a>
 407 </pre>
 408
 409             <p> &quot;<em>relink is a package management tool for
 410             organization and management of software packages. It should
 411             run on any UNIX platform that runs PERL.  Similar tools
 412             include: rpm(REDHAT/Mandrake), pkgadd(Slackware/SUN),
 413             stow(GNU) and depot(CMU)</em>&quot; </p>
 414
 415
 416         <dt> <em>univSrcPkg</em>
 417
 418             <dd>
 419
 420 <pre>
 421 <a href="http://freecode.com/articles/the-universal-source-package">http://freecode.com/articles/the-universal-source-package</a>
 422 </pre>
 423
 424         <p> <a href="mailto:bud@sistema.it">Bud Bruegger</a> has written
 425         a brief paper outlining his thoughts on a &quot;<em>Universal Source
 426         Package</em>&quot; solution. </p>
 427
 428         <p> This site also has links to other package management
 429         programs and similar items of interest. </p>
 430
 431     </dl>
 432
 433 <hr>
 434
 435 <h2><a name="design">Design</a></h2>
 436
 437 <p> This brings us to <em>Graft</em>. <em>Graft</em> has been designed to
 438 use the best features of <em>Depot</em>, <em>Stow</em> and <em>Encap</em>
 439 while maintaining as simple a mechanism as possible. The principles of
 440 <em>Graft</em> are: </p>
 441
 442     <ul>
 443
 444         <li> <p> <em>Graft</em> will allow packages to be <em>grafted</em>
 445         from any directory to any other directory. Default
 446         <tt>installation</tt> and <tt>target</tt> directories will be
 447         used but can easily be overridden on the command line. </p>
 448
 449         <li> <p> <em>Graft</em> will log its actions to a log file. The
 450         log file can be specified on the command line. If not specified
 451         on the command line a default log file will be used. </p>
 452
 453         <li> <p> <em>Graft</em> will NOT create symbolic links to
 454         directories. If a directory does not exist in the target tree
 455         it will be created (with the same ownership and permissions as
 456         the original if desired). </p>
 457
 458         <li> <p> <em>Graft</em> will create symbolic links with full
 459         pathnames rather than relative pathnames. This allows easy
 460         identification of true package locations and facilitates block
 461         movement of a target tree without the need for <em>Graft</em>
 462         deletion and re-installation. </p>
 463
 464         <li> <p> <em>Graft</em> will cease installation of a package if a
 465         conflict arises. A conflict is defined as one of the following
 466         conditions: </p>
 467
 468             <ul>
 469
 470                 <li> If the package object is a directory and the
 471                 target object exists but is not a directory.
 472
 473                 <li> If the package object is not a directory and the
 474                 target object exists and is not a symbolic link.
 475
 476                 <li> If the package object is not a directory and the
 477                 target object exists and is a symbolic link to
 478                 something other than the package object.
 479
 480                 <li> If the package directory contains a
 481                 <tt>.graft-config</tt> file and the target object exists
 482                 but does not match the 32-bit CRC of the package object.
 483
 484             </ul>
 485
 486         <li> <p> Installation conflicts will always be reported. Conflicts
 487         will be reported to standard error. </p>
 488
 489         <li> <p> <em>Graft</em> will attempt to display all possible
 490         operations when asked, even when asked not to perform the
 491         operations. </p>
 492
 493         <li> <p> <em>Graft</em> will not delete directories when
 494         uninstalling. <em>Graft</em> will print an appropriate message if an
 495         empty directory results and leave the deletion for the operator
 496         to perform outside the scope of <em>Graft</em>'s operations. This
 497         ensures that <em>place holder</em> directories that may be
 498         used by other packages are not inadvertently removed. This
 499         feature can be permanently disabled by setting a flag in the
 500         <tt>Makefile</tt>. It can also be temporarily disabled using a
 501         command line option. </p>
 502
 503         <li> <p> <em>Graft</em> will continue to delete the remainder of
 504         a package after a conflict arises. This maximises the amount of
 505         deletion that can be performed. </p>
 506
 507         <li> <p> Deletion conflicts will always be reported. Conflicts
 508         will be reported to standard error. </p>
 509
 510         <li> <p> <em>Graft</em> will only concern itself with files
 511         relating to the package at hand. This will allow other packages
 512         to be placed in the target area without fear of intervention by
 513         <em>Graft</em>. </p>
 514
 515         <li> <p> <em>Graft</em> will only allow the superuser to install
 516         or delete packages. This feature can be permanently disabled by
 517         setting a flag in the <tt>Makefile</tt> or it may be overridden
 518         by a command line option. </p>
 519
 520         <li> <p> If the file <tt>.nograft</tt> exists in any package
 521         directory, <em>Graft</em> will bypass that directory and any
 522         subdirectories during installation. The name of this file is
 523         specified in the <tt>Makefile</tt>. </p>
 524
 525         <li> <p> When installing a directory tree, if the file
 526         <tt>.graft-exclude</tt> exists in any package directory,
 527         <em>Graft</em> will assume that the file contains a list of
 528         file and/or directory names - one per line - which correspond
 529         to files and/or directories in the directory containing the
 530         <tt>.graft-exclude</tt> file. These files and/or directories
 531         will NOT be <em>grafted</em>. The name of this file is specified
 532         in the <tt>Makefile</tt>. </p>
 533
 534         <p> The <tt>.nograft</tt> file takes priority over the
 535         <tt>.graft-exclude</tt> file. </p>
 536
 537         <li> <p> When installing a directory tree, if the file
 538         <tt>.graft-include</tt> exists in any package directory,
 539         <em>Graft</em> will assume that the file contains a list of
 540         file and/or directory names - one per line - which correspond
 541         to files and/or directories in the directory containing the
 542         <tt>.graft-include</tt> file. ONLY the files and/or directories
 543         listed in the <tt>.graft-include</tt> will be <em>grafted</em>. The
 544         name of this file is specified in the <tt>Makefile</tt>. </p>
 545
 546         <p> The <tt>.graft-exclude</tt> file takes priority over the
 547         <tt>.graft-include</tt> file. </p>
 548
 549         <li> <p> When installing a directory tree, if the file
 550         <tt>.graft-config</tt> exists in a package directory, the contents
 551         of the directory will be <strong>copied</strong> to the target
 552         directory. If the target files exists and is in conflict with the
 553         package file then the package file will be copied into the target
 554         directory as <tt>file<em>.new</em></tt>. </p>
 555
 556         <p> The <tt>.graft-include</tt> file takes priority over the
 557         <tt>.graft-config</tt> file. </p>
 558
 559         <li> <p> If the file <tt>.nograft</tt> exists in any package
 560         directory, it will be ignored and <em>Graft</em> will continue
 561         processing the directory and any subdirectories during
 562         deletion. </p>
 563
 564         <li> <p> If the file <tt>.graft-exclude</tt> exists in any
 565         package directory, its contents will be ignored and <em>Graft</em>
 566         will continue processing the directory and any subdirectories
 567         during deletion. </p>
 568
 569         <li> <p> If the file <tt>.graft-include</tt> exists in any
 570         package directory, its contents will be ignored and <em>Graft</em>
 571         will continue processing the directory and any subdirectories
 572         during deletion. </p>
 573
 574         <li> <p> If the file <tt>.graft-config</tt> exists in any
 575         package directory, during deletion matching files in the target
 576         directory will not be deleted however any
 577         <tt>file<em>.new</em></tt> files will be deleted. </p>
 578
 579         <li> <p> As an aid to transitioning systems to <em>Graft</em>,
 580         <em>Graft</em> will allow conflicting files to be pruned. This
 581         pruning can take the form of a file rename or a file removal
 582         depending on either a <tt>Makefile</tt> flag or a command line
 583         option. If file removal is selected and the file is a non-empty
 584         directory, it will be renamed instead. </p>
 585
 586         <li> <p> If the file <tt>.nograft</tt> exists in any package
 587         directory, it will be ignored and <em>Graft</em> will continue
 588         processing the directory and any subdirectories during
 589         pruning. </p>
 590
 591         <li> <p> If the file <tt>.graft-exclude</tt> exists in any
 592         package directory, its contents will be ignored and <em>Graft</em>
 593         will continue processing the directory and any subdirectories
 594         during pruning. </p>
 595
 596         <li> <p> If the file <tt>.graft-include</tt> exists in any
 597         package directory, its contents will be ignored and <em>Graft</em>
 598         will continue processing the directory and any subdirectories
 599         during pruning. </p>
 600
 601         <li> <p> If the file <tt>.graft-config</tt> exists in any
 602         package directory, the files in the directory will be ignored
 603         during pruning. Sub-directories will continue to be processed
 604         appropriately. </p>
 605
 606     </ul>
 607
 608 <h3><a name="precedence">Control file precedence &amp; conflict resolution</a></h3>
 609
 610 <p> As stated above, the various <em>Graft</em> control files have the
 611 following precedence, from highest to lowest: </p>
 612
 613 <pre>
 614     .nograft &gt; .graft-exclude &gt; .graft-include &gt; .graft-config
 615 </pre>
 616
 617 <p> The following table summarises the activities of <em>Graft</em> when
 618 various control files are present: </p>
 619
 620 <center>
 621 <table summary="Control File Precedence" border=2 cellpadding=3>
 622     <tr>
 623         <th colspan=5>
 624             Install
 625         </th>
 626     </tr>
 627
 628     <tr>
 629         <th>
 630             <em>Target</em>
 631         </th>
 632
 633         <th>
 634             <em>.nograft</em>
 635         </th>
 636
 637         <th>
 638             <em>.graft-exclude</em>
 639         </th>
 640
 641         <th>
 642             <em>.graft-include</em>
 643         </th>
 644
 645         <th>
 646             <em>.graft-config</em>
 647         </th>
 648     </tr>
 649
 650     <tr>
 651         <td>
 652             does not exist
 653         </td>
 654
 655         <td>
 656             IGNORE
 657         </td>
 658
 659         <td>
 660             IGNORE
 661         </td>
 662
 663         <td>
 664             SYMLINK
 665         </td>
 666
 667         <td>
 668             COPY
 669         </td>
 670     </tr>
 671
 672     <tr>
 673         <td>
 674             symlink to source
 675         </td>
 676
 677         <td>
 678             IGNORE
 679         </td>
 680
 681         <td>
 682             IGNORE
 683         </td>
 684
 685         <td>
 686             NOP
 687         </td>
 688
 689         <td>
 690             DELETE &amp; COPY
 691         </td>
 692     </tr>
 693
 694     <tr>
 695         <td>
 696             symlink to other
 697         </td>
 698
 699         <td>
 700             IGNORE
 701         </td>
 702
 703         <td>
 704             IGNORE
 705         </td>
 706
 707         <td>
 708             CONFLICT
 709         </td>
 710
 711         <td>
 712             N/A
 713         </td>
 714     </tr>
 715
 716     <tr>
 717         <td>
 718             symlink to other (crc match)
 719         </td>
 720
 721         <td>
 722             N/A
 723         </td>
 724
 725         <td>
 726             N/A
 727         </td>
 728
 729         <td>
 730             N/A
 731         </td>
 732
 733         <td>
 734             NOP
 735         </td>
 736     </tr>
 737
 738     <tr>
 739         <td>
 740             symlink to other (crc diff)
 741         </td>
 742
 743         <td>
 744             N/A
 745         </td>
 746
 747         <td>
 748             N/A
 749         </td>
 750
 751         <td>
 752             N/A
 753         </td>
 754
 755         <td>
 756             COPY.new
 757         </td>
 758     </tr>
 759
 760     <tr>
 761         <td>
 762             file
 763         </td>
 764
 765         <td>
 766             IGNORE
 767         </td>
 768
 769         <td>
 770             IGNORE
 771         </td>
 772
 773         <td>
 774             CONFLICT
 775         </td>
 776
 777         <td>
 778             N/A
 779         </td>
 780     </tr>
 781
 782     <tr>
 783         <td>
 784             file (crc match)
 785         </td>
 786
 787         <td>
 788             N/A
 789         </td>
 790
 791         <td>
 792             N/A
 793         </td>
 794
 795         <td>
 796             N/A
 797         </td>
 798
 799         <td>
 800             NOP
 801         </td>
 802     </tr>
 803
 804     <tr>
 805         <td>
 806             file (crc diff)
 807         </td>
 808
 809         <td>
 810             N/A
 811         </td>
 812
 813         <td>
 814             N/A
 815         </td>
 816
 817         <td>
 818             N/A
 819         </td>
 820
 821         <td>
 822             COPY.new
 823         </td>
 824     </tr>
 825
 826     <tr>
 827         <td>
 828             not a file
 829         </td>
 830
 831         <td>
 832             IGNORE
 833         </td>
 834
 835         <td>
 836             IGNORE
 837         </td>
 838
 839         <td>
 840             CONFLICT
 841         </td>
 842
 843         <td>
 844             CONFLICT
 845         </td>
 846     </tr>
 847
 848     <tr>
 849         <th colspan=5>
 850             Delete
 851         </th>
 852     </tr>
 853
 854     <tr>
 855         <th>
 856             <em>Target</em>
 857         </th>
 858
 859         <th>
 860             <em>.nograft</em>
 861         </th>
 862
 863         <th>
 864             <em>.graft-exclude</em>
 865         </th>
 866
 867         <th>
 868             <em>.graft-include</em>
 869         </th>
 870
 871         <th>
 872             <em>.graft-config</em>
 873         </th>
 874     </tr>
 875
 876     <tr>
 877         <td>
 878             does not exist
 879         </td>
 880
 881         <td>
 882             NOP
 883         </td>
 884
 885         <td>
 886             NOP
 887         </td>
 888
 889         <td>
 890             NOP
 891         </td>
 892
 893         <td>
 894             NOP
 895         </td>
 896     </tr>
 897
 898     <tr>
 899         <td>
 900             symlink to source
 901         </td>
 902
 903         <td>
 904             DELETE
 905         </td>
 906
 907         <td>
 908             DELETE
 909         </td>
 910
 911         <td>
 912             DELETE
 913         </td>
 914
 915         <td>
 916             DELETE &amp; DELETE.new
 917         </td>
 918     </tr>
 919
 920     <tr>
 921         <td>
 922             symlink to other
 923         </td>
 924
 925         <td>
 926             CONFLICT
 927         </td>
 928
 929         <td>
 930             CONFLICT
 931         </td>
 932
 933         <td>
 934             CONFLICT
 935         </td>
 936
 937         <td>
 938             N/A
 939         </td>
 940     </tr>
 941
 942     <tr>
 943         <td>
 944             symlink to other (crc match)
 945         </td>
 946
 947         <td>
 948             N/A
 949         </td>
 950
 951         <td>
 952             N/A
 953         </td>
 954
 955         <td>
 956             N/A
 957         </td>
 958
 959         <td>
 960             DELETE.new
 961         </td>
 962     </tr>
 963
 964     <tr>
 965         <td>
 966             symlink to other (crc diff)
 967         </td>
 968
 969         <td>
 970             N/A
 971         </td>
 972
 973         <td>
 974             N/A
 975         </td>
 976
 977         <td>
 978             N/A
 979         </td>
 980
 981         <td>
 982             NOP
 983         </td>
 984     </tr>
 985
 986     <tr>
 987         <td>
 988             file
 989         </td>
 990
 991         <td>
 992             NOTE
 993         </td>
 994
 995         <td>
 996             NOTE
 997         </td>
 998
 999         <td>
1000             CONFLICT
1001         </td>
1002
1003         <td>
1004             N/A
1005         </td>
1006     </tr>
1007
1008     <tr>
1009         <td>
1010             file (crc match)
1011         </td>
1012
1013         <td>
1014             N/A
1015         </td>
1016
1017         <td>
1018             N/A
1019         </td>
1020
1021         <td>
1022             N/A
1023         </td>
1024
1025         <td>
1026             DELETE.new
1027         </td>
1028     </tr>
1029
1030     <tr>
1031         <td>
1032             file (crc diff)
1033         </td>
1034
1035         <td>
1036             N/A
1037         </td>
1038
1039         <td>
1040             N/A
1041         </td>
1042
1043         <td>
1044             N/A
1045         </td>
1046
1047         <td>
1048             NOP
1049         </td>
1050     </tr>
1051
1052     <tr>
1053         <td>
1054             not a file
1055         </td>
1056
1057         <td>
1058             CONFLICT
1059         </td>
1060
1061         <td>
1062             CONFLICT
1063         </td>
1064
1065         <td>
1066             CONFLICT
1067         </td>
1068
1069         <td>
1070             CONFLICT
1071         </td>
1072     </tr>
1073
1074     <tr>
1075         <th colspan=5>
1076             Prune
1077         </th>
1078     </tr>
1079
1080     <tr>
1081         <th>
1082             <em>Target</em>
1083         </th>
1084
1085         <th>
1086             <em>.nograft</em>
1087         </th>
1088
1089         <th>
1090             <em>.graft-exclude</em>
1091         </th>
1092
1093         <th>
1094             <em>.graft-include</em>
1095         </th>
1096
1097         <th>
1098             <em>.graft-config</em>
1099         </th>
1100     </tr>
1101
1102     <tr>
1103         <td>
1104             does not exist
1105         </td>
1106
1107         <td>
1108             NOP
1109         </td>
1110
1111         <td>
1112             NOP
1113         </td>
1114
1115         <td>
1116             NOP
1117         </td>
1118
1119         <td>
1120             N/A
1121         </td>
1122     </tr>
1123
1124     <tr>
1125         <td>
1126             symlink to source
1127         </td>
1128
1129         <td>
1130             NOP
1131         </td>
1132
1133         <td>
1134             NOP
1135         </td>
1136
1137         <td>
1138             NOP
1139         </td>
1140
1141         <td>
1142             N/A
1143         </td>
1144     </tr>
1145
1146     <tr>
1147         <td>
1148             symlink to other
1149         </td>
1150
1151         <td>
1152             PRUNE
1153         </td>
1154
1155         <td>
1156             PRUNE
1157         </td>
1158
1159         <td>
1160             PRUNE
1161         </td>
1162
1163         <td>
1164             N/A
1165         </td>
1166     </tr>
1167
1168     <tr>
1169         <td>
1170             file
1171         </td>
1172
1173         <td>
1174             PRUNE
1175         </td>
1176
1177         <td>
1178             PRUNE
1179         </td>
1180
1181         <td>
1182             PRUNE
1183         </td>
1184
1185         <td>
1186             N/A
1187         </td>
1188     </tr>
1189
1190     <tr>
1191         <td>
1192             not a file
1193         </td>
1194
1195         <td>
1196             PRUNE
1197         </td>
1198
1199         <td>
1200             PRUNE
1201         </td>
1202
1203         <td>
1204             PRUNE
1205         </td>
1206
1207         <td>
1208             N/A
1209         </td>
1210     </tr>
1211 </table>
1212 </center>
1213
1214 <hr>
1215
1216 <h2><a name="history">History</a></h2>
1217
1218 <p> Development on <em>Graft</em> began in October 1996. The initial design
1219 used a configuration file to map the installed location of each package to
1220 its target directory (that is the directory in which the symbolic links
1221 would be created). Work proceeded at a regular pace and by November 1997
1222 <em>Graft</em> version <em>2.1</em> was released. In this, and all
1223 subsequent versions, the configuration file had been removed in favour of
1224 using default source and target directories. </p>
1225
1226 <p> No further work was performed until September 2000 when the concept of
1227 bypassing or including files and directories using <tt>.nograft</tt> or
1228 <tt>.graft-include</tt> files was introduced in <em>Graft</em> version
1229 <em>2.3</em>. </p>
1230
1231 <p> Again nothing changed until February 2002 when Rod Whitby identified a
1232 bug in the handling of <tt>.graft-include</tt> files. Several other users
1233 (Peter Bray, Robert Maldon and others) also reported some deprecation
1234 warnings when using <em>Graft</em> with <em>Perl</em> version
1235 <em>5.6.0</em>. <em>Graft</em> version <em>2.4</em> was the end of
1236 <em>Graft</em> development for over a decade. </p>
1237
1238 <p> In May 2015 Matias A. Fonzo contacted the author wishing to use
1239 <em>Graft</em> in the
1240 <a href="http://www.dragora.org/">Dragora GNU/Linux</a>
1241 distribution. Matias' usage of <em>Graft</em> lead to <em>Graft</em>
1242 version <em>2.5</em> in June 2015 whereby the <tt>-P</tt> command line
1243 option was silently ignored if the effective user was not root.  </p>
1244
1245 <p> Since the release of  <em>Graft</em> version <em>2.4</em> the author's
1246 <em>Perl</em> code had improved somewhat so <em>Graft</em> version
1247 <em>2.6</em> released in July 2015 represented a major clean up of coding
1248 style and internals. No new behaviours or features were added to the
1249 <em>2.6</em> release. </p>
1250
1251 <p> Matias made some more suggestions and improvements up to and including
1252 <em>Graft</em> version <em>2.16</em> in April 2018. These changes added
1253 the <tt>.graft-config</tt> control file, the <tt>-r /rootdir</tt> option for
1254 specifying a new root directory, the <tt>-L</tt> option for displaying
1255 default locations as well as introducing some tighter controls on the
1256 messages and exit status of <em>Graft</em> under various conditions. </p>
1257
1258 <hr>
1259
1260 <h2><a name="installation">Installation</a></h2>
1261
1262 <p> Before installing <em>Graft</em> you'll need <em>Perl</em>
1263 5.<em>x</em>. <em>Graft</em> version 2.<em>x</em> requires features only
1264 available with <em>Perl</em> 5.<em>x</em> and will not run with
1265 <em>Perl</em> 4.<em>x</em>. </p>
1266
1267 <p> Your operating system and its file system(s) should also support
1268 symbolic links. If you can't make symbolic links then you can't use
1269 <em>Graft</em>! <em>Graft</em> will exit gracefully if your version of
1270 <em>Perl</em> does not support symbolic links. It will also exit gracefully
1271 if you attempt to <em>graft</em> a package into a file system that does not
1272 support symbolic links - from a Linux <tt>ext4</tt> file system into an
1273 <tt>vfat</tt> file system for example. </p>
1274
1275 <p> <em>Graft</em> has been written to ensure it uses <em>Perl</em> modules
1276 that are considered part of the core <em>Perl</em> distribution. However it
1277 may be possible that you're using a home grown installation of
1278 <em>Perl</em> or some distribution that doesn't have the same <em>Perl</em>
1279 modules as the author's development environment. </p>
1280
1281 <p> If this is the case you'll see compile failures for the following modules
1282 if they are unavailable: </p>
1283
1284 <pre>
1285    File::Basename
1286    Getopt::Long
1287 </pre>
1288
1289 <p> You will not be able to install <em>Graft</em> until these modules are
1290 available. </p>
1291
1292 <p> You may also see run-time failures when using <em>Graft</em> with
1293 <tt>.graft-config</tt> files if the following modules are unavailable: </p>
1294
1295 <pre>
1296    Compress::Raw::Zlib    (<em>used in install and delete modes</em>)
1297    File::Copy             (<em>only used in install mode</em>)
1298 </pre>
1299
1300 <p> If you don't have these modules and you do not intend to use
1301 <tt>.graft-config</tt> files then you can continue to use <em>Graft</em>
1302 without issue. </p>
1303
1304 <p> Follow these instructions to install <em>Graft</em>: </p>
1305
1306     <ol>
1307
1308         <li> <p> Unpack the gzipped <em>Graft</em> distribution: </p>
1309
1310 <pre>
1311     gunzip -c graft-2.16.tar.gz | tar xvf -
1312 </pre>
1313
1314         <li> <p> change directories to the <em>Graft</em> distribution
1315         directory: </p>
1316
1317 <pre>
1318     cd graft-2.16
1319 </pre>
1320
1321         <li> <p> Create an writable version of the <tt>Makefile</tt> by
1322         running the command </p>
1323
1324 <pre>
1325     make -f Makefile.dist
1326 </pre>
1327
1328         <p> You'll see output similar to </p>
1329
1330 <pre>
1331     cp Makefile.dist Makefile
1332     chmod 644 Makefile
1333
1334     ######################################################
1335     #                                                    #
1336     #       You'll now need to modify the Makefile       #
1337     #      variables to suit your local conditions.      #
1338     #                                                    #
1339     ######################################################
1340
1341     make: *** [Makefile] Error 1
1342 </pre>
1343
1344         <p> You can ignore the error message. That is just there to
1345         prevent the creation of the <em>graft</em> executable before you've
1346         made your site specific configurations to the <tt>Makefile</tt>.
1347         </p>
1348
1349         <li> <p> Edit the <tt>Makefile</tt>. The following variables should be
1350         modified to suit your local requirements: </p>
1351
1352             <dl>
1353
1354                 <dt>
1355 <pre>
1356 <strong>PACKAGEDIR</strong>     = /usr/local/pkgs
1357 <strong>TARGETDIR</strong>      = /usr/local
1358 </pre>
1359
1360                     <dd> <p> These two variables control your default
1361                     package <tt>installation</tt> and <tt>target</tt>
1362                     directories. Most sites will probably choose to
1363                     install packages under a common <tt>installation</tt>
1364                     directory and then <em>graft</em> them into a common
1365                     <tt>target</tt> directory. </p>
1366
1367                     <p> If no specific <tt>target</tt> directory is
1368                     given on the command line, <em>Graft</em> will use
1369                     the default value specified by <strong>TARGETDIR</strong>. If
1370                     a <tt>target</tt> directory is given on the command
1371                     line but is not fully qualified, the value specified
1372                     by <strong>TARGETDIR</strong> will be prepended to the command
1373                     line argument. </p>
1374
1375                     <p> Package names provided to <em>Graft</em> that are
1376                     not fully qualified will have the value specified
1377                     by <strong>PACKAGEDIR</strong> prepended to the command line
1378                     arguments. </p>
1379                 <dt>
1380 <pre>
1381 <strong>TOP</strong>            = $(PACKAGEDIR)/graft-$(VERSION)
1382 <strong>BIN</strong>            = $(TOP)/bin
1383 <strong>MAN</strong>            = $(TOP)/man
1384 <strong>DOC</strong>            = $(TOP)/doc
1385 </pre>
1386
1387                     <dd> <p> There should be no need to modify these
1388                     values unless you wish to install <em>Graft</em> into
1389                     a directory that is different from your default
1390                     package installation directory. If you do modify
1391                     <strong>TOP</strong> you should not change the values of
1392                     <strong>BIN</strong>, <strong>MAN</strong> and <strong>DOC</strong>. If you feel
1393                     you must change these values then perhaps you've
1394                     misunderstood the concept behind <em>Graft</em> so a
1395                     re-read of this document may be in order. </p>
1396
1397                 <dt>
1398 <pre>
1399 <strong>PERL</strong>           = /usr/bin/perl
1400 </pre>
1401
1402                     <dd> <p> This variable refers to the location
1403                     of the <em>Perl</em> 5.<em>x</em> that will be used by
1404                     the <em>Graft</em> executable. If you plan on
1405                     <em>grafting</em> <em>Perl</em> then this value should
1406                     be the <em>grafted</em> location of <em>Perl</em>
1407                     rather than the installation location of <em>Perl</em>.
1408                     If you are using an operating system that comes with
1409                     <em>Perl</em> 5.<em>x</em> - such as RedHat or Ubuntu
1410                     Linux - then you don't need to worry about
1411                     <em>grafting</em> <em>Perl</em> so the value of
1412                     <strong>PERL</strong> should reflect its installed
1413                     location. </p>
1414
1415                     <p> Most Unix, Linux and other Unix like operating
1416                     systems ship with <em>Perl</em> these days so
1417                     modifying this value is probably unnecessary. </p>
1418
1419                 <dt>
1420 <pre>
1421 <strong>BUILDPERL</strong>      = $(PERL)
1422 </pre>
1423
1424                     <dd> <p> <em>Perl</em> is required during the
1425                     <tt>make</tt>. You'll only need to change this if
1426                     the current installed location of <em>Perl</em> is
1427                     different to the future <em>grafted</em> location of
1428                     <em>Perl</em>. </p>
1429
1430                 <dt>
1431 <pre>
1432 <strong>LOGFILE</strong>                = /var/log/graft
1433 </pre>
1434
1435                     <dd> <p> <em>Graft</em> logs all of its actions to a log
1436                     file. Modify the value of <strong>LOGFILE</strong> to suit
1437                     your local needs. An alternative name can be
1438                     specified on the command line. </p>
1439
1440                     <p> If you want logging disabled by default, set the
1441                     value of <strong>LOGFILE</strong> to <tt>/dev/null</tt>. </p>
1442
1443                 <dt>
1444 <pre>
1445 <strong>GRAFT-IGNORE</strong>   = .nograft
1446 <strong>GRAFT-EXCLUDE</strong>  = .graft-exclude
1447 <strong>GRAFT-INCLUDE</strong>  = .graft-include
1448 <strong>GRAFT-CONFIG</strong>   = .graft-config
1449 </pre>
1450
1451                     <dd> <p> These variables hold the names of the
1452                     special <em>Graft</em> files that control whether or
1453                     not subdirectories or files are <em>grafted</em>. If
1454                     you change these values, try to choose obvious names.
1455                     If you want the files to appear in a simple directory
1456                     listing, do not use file names that begin with a
1457                     dot &quot;.&quot; character. </p>
1458
1459                 <dt>
1460 <pre>
1461 <strong>GRAFT-NEVER</strong>    =
1462 </pre>
1463
1464                     <dd> <p> This variable holds the names of the
1465                     files and/or directories that should never be
1466                     <em>grafted</em>. Typically these may be source code
1467                     repositories as used by systems such as
1468                     <em>CVS</em>, or perhaps lockfiles. The default
1469                     value is empty but if you wish to specify values,
1470                     simply add them to the variable using only
1471                     whitespace as a separator. For example: </p>
1472
1473 <pre>
1474 GRAFT-NEVER     = CVS RCS SCCS .lock
1475 </pre>
1476
1477                 <dt>
1478 <pre>
1479 <strong>NEVERGRAFT</strong>     = 0
1480 </pre>
1481
1482                     <dd> <p> If this variable is set to <strong>1</strong>,
1483                     the files and/or directories specified by
1484                     <strong>GRAFT-NEVER</strong> will be automatically excluded
1485                     from the <em>grafted</em> directory. </p>
1486
1487                     <p> If this variable is set to <strong>0</strong>, the files
1488                     and/or directories specified by <strong>GRAFT-NEVER</strong>
1489                     will be not be excluded from the <em>grafted</em>
1490                     directory. </p>
1491
1492                     <p> The sense of this value is reversed by use of
1493                     the <strong>-C</strong> command line option.
1494
1495                     <p> The automatic exclusion is bypassed completely
1496                     if the <em>grafted</em> directory contains either
1497                     a <tt>.nograft</tt> or <tt>.graft-include</tt>
1498                     file. </p>
1499
1500                 <dt>
1501 <pre>
1502 <strong>PRUNED-SUFFIX</strong>  = .pruned
1503 </pre>
1504
1505                     <dd> <p> This variable sets the suffix name of
1506                     <em>pruned</em> files. <em>Pruned</em> files will be
1507                     renamed <em>filename</em><tt>.pruned</tt>. </p>
1508
1509                 <dt>
1510 <pre>
1511 <strong>CONFIG-SUFFIX</strong>  = .new
1512 </pre>
1513
1514                     <dd> <p> This variable sets the suffix name of configuration
1515                     files that will be copied to the target directory when
1516                     the target object is in conflict with the package
1517                     object. The files will be copied as
1518                     <em>filename</em><tt>.new</tt>. </p>
1519
1520                 <dt>
1521 <pre>
1522 <strong>SUPERUSER</strong>      = 1
1523 </pre>
1524
1525                     <dd> <p> If this variable is set to <strong>1</strong> only
1526                     the superuser can <em>install</em>, <em>delete</em>
1527                     or <em>prune</em> packages. This can be overridden
1528                     by the use of the <strong>-u</strong> command line
1529                     option. If this variable is set to <strong>0</strong>,
1530                     superuser privileges are not required and the
1531                     <strong>-u</strong> override command line option is
1532                     disabled. </p>
1533
1534                     <p> If you are installing a private copy of
1535                     <em>Graft</em> to manage packages in your home
1536                     directory you should set <strong>SUPERUSER</strong> to
1537                     <strong>0</strong>. </p>
1538
1539                     <p> If you're using <em>Graft</em> to manage a global
1540                     set of packages you should set <strong>SUPERUSER</strong>
1541                     to <strong>1</strong>. </p>
1542
1543                 <dt>
1544 <pre>
1545 <strong>PRESERVEPERMS</strong>  = 0
1546 </pre>
1547
1548                     <dd> <p> When <em>grafting</em> packages, <em>Graft</em>
1549                     will create new directories as required. By setting
1550                     <strong>PRESERVEPERMS</strong> to <strong>1</strong>,
1551                     the original user id, group id and file modes will be
1552                     carried over to the new directory. This variable is
1553                     used only if <strong>SUPERUSER</strong> is set to
1554                     <strong>1</strong>. The sense of this variable can be
1555                     reversed using the <strong>-P</strong> command line
1556                     option. </p>
1557
1558                 <dt>
1559 <pre>
1560 <strong>DELETEOBJECTS</strong>  = 0
1561 </pre>
1562
1563                     <dd> <p> When deleting <em>grafted</em> packages,
1564                     <em>Graft</em> may leave empty directories. Setting
1565                     <strong>DELETEOBJECTS</strong> to <strong>1</strong>
1566                     will allow <em>Graft</em> to delete these directories.
1567                     If <strong>DELETEOBJECTS</strong> is <strong>0</strong>
1568                     then <em>Graft</em> will display an appropriate message
1569                     reminding the user that a directory has been emptied.
1570                     The sense of this variable can be reversed using the
1571                     <strong>-D</strong> command line option. </p>
1572
1573                     <p> It's probably not good practise to set this value
1574                     to <strong>1</strong> as some directories may be used
1575                     as place holders by a number of different packages. If
1576                     the value is set to <strong>0</strong> deletion of
1577                     directories can be forced via the <strong>-D</strong>
1578                     command line option. </p>
1579
1580                     <p> When pruning packages, <em>graft</em> can either
1581                     remove conflicting files or rename them. If
1582                     <strong>DELETEOBJECTS</strong> is set to
1583                     <strong>1</strong> the default prune action will be to
1584                     delete conflicting objects. If
1585                     <strong>DELETEOBJECTS</strong> is set to
1586                     <strong>0</strong> the default prune action will be to
1587                     rename conflicting objects. The sense of this variable
1588                     can be reversed using the <strong>-D</strong> command
1589                     line option. </p>
1590
1591             </dl>
1592
1593         <p> Save your changes and exit from the editor. </p>
1594
1595         <li> <p> Remove any existing executables by running: </p>
1596
1597 <pre>
1598     make clean
1599 </pre>
1600
1601         <p> You should see output similar to: </p>
1602
1603 <pre>
1604     rm -f graft
1605 </pre>
1606
1607         <li> <p> Create the <em>Graft</em> executable by running: </p>
1608
1609 <pre>
1610     make
1611 </pre>
1612
1613         <p> You should see output similar to: </p>
1614
1615 <pre>
1616     /usr/bin/perl -wc graft.pl
1617     graft.pl syntax OK
1618     sed                                         \
1619         -e 's#xCONFIG-SUFFIXx#.new#g'           \
1620         -e 's#xDELETEOBJECTSx#0#g'              \
1621         -e 's#xGRAFT-CONFIGx#.graft-config#g'   \
1622         -e 's#xGRAFT-EXCLUDEx#.graft-exclude#g' \
1623         -e 's#xGRAFT-IGNOREx#.nograft#g'        \
1624         -e 's#xGRAFT-INCLUDEx#.graft-include#g' \
1625         -e 's#xGRAFT-NEVERx##g'                 \
1626         -e 's#xLOGFILEx#/var/log/graft#g'       \
1627         -e 's#xNEVERGRAFTx#0#g'                 \
1628         -e 's#xPACKAGEDIRx#/usr/local/pkgs#g'   \
1629         -e 's#xPERLx#/usr/bin/perl#g'           \
1630         -e 's#xPRESERVEPERMSx#0#g'              \
1631         -e 's#xPRUNED-SUFFIXx#.pruned#g'        \
1632         -e 's#xSUPERUSERx#1#g'                  \
1633         -e 's#xTARGETDIRx#/usr/local#g'         \
1634         &lt; graft.pl &gt; graft
1635     chmod +x graft
1636     /usr/bin/perl -wc graft
1637     graft syntax OK
1638     if [ -n &quot;&quot; ];                                       \
1639     then                                                \
1640         AUTOIGNORE=1;                                   \
1641     else                                                \
1642         AUTOIGNORE=0;                                   \
1643     fi;                                                 \
1644     sed                                                 \
1645         -e &quot;s#xAUTOIGNOREx#$AUTOIGNORE#g&quot;               \
1646         -e 's#xCONFIG-SUFFIXx#.new#g'                   \
1647         -e 's#xDELETEOBJECTSx#0#g'                      \
1648         -e 's#xDOCx#/usr/local/pkgs/graft-2.16/doc#g'   \
1649         -e 's#xGRAFT-CONFIGx#.graft-config#g'           \
1650         -e 's#xGRAFT-EXCLUDEx#.graft-exclude#g'         \
1651         -e 's#xGRAFT-IGNOREx#.nograft#g'                \
1652         -e 's#xGRAFT-INCLUDEx#.graft-include#g'         \
1653         -e 's#xGRAFT-NEVERx##g'                         \
1654         -e 's#xLOGFILEx#/var/log/graft#g'               \
1655         -e 's#xNEVERGRAFTx#0#g'                         \
1656         -e 's#xPACKAGEDIRx#/usr/local/pkgs#g'           \
1657         -e 's#xPERLx#/usr/bin/perl#g'                   \
1658         -e 's#xPRESERVEPERMSx#0#g'                      \
1659         -e 's#xPRUNED-SUFFIXx#.pruned#g'                \
1660         -e 's#xSUPERUSERx#1#g'                          \
1661         -e 's#xTARGETDIRx#/usr/local#g'                 \
1662         -e 's#xVERSIONx#2.16#g'                         \
1663         &lt; graft.man &gt; graft.1
1664 </pre>
1665
1666         <li> <p> If you're using the <em>automounter</em> under Solaris
1667         2.<em>x</em>, the installation process may not be able to directly
1668         create the directory specified by <strong>TOP</strong>. If this is the case
1669         then manually create this directory using whatever procedures
1670         are appropriate for your operating system. </p>
1671
1672         <p> For example, if the <tt>/usr/local</tt> mount point is under the
1673         control of the <em>automounter</em> via an entry in the
1674         <tt>auto_pkgs</tt> map: </p>
1675
1676 <pre>
1677     *   nfshost:/export/sparc-SunOS-5.5.1/usr/local/&amp;
1678 </pre>
1679
1680         <p> you'll need to create the <em>Graft</em> installation directory
1681         by executing the following command on the machine <em>nfshost</em>:
1682         </p>
1683
1684 <pre>
1685     mkdir /export/sparc-SunOS-5.5.1/usr/local/pkgs/graft-2.16
1686 </pre>
1687
1688         <li> <p> Install the <em>Graft</em> executable, manual page and
1689         documentation by executing: </p>
1690
1691 <pre>
1692     make install
1693 </pre>
1694
1695         <p> You should see output similar to: </p>
1696
1697 <pre>
1698     mkdir -p /usr/local/pkgs/graft-2.16/bin
1699     cp graft /usr/local/pkgs/graft-2.16/bin
1700
1701     for i in graft.1;                                              \
1702     do                                                             \
1703         manpage=`basename $i`;                                     \
1704         man=`expr $i : '.*\.\(.\)'`;                               \
1705         mkdir -p /usr/local/pkgs/graft-2.16/man/man$man;           \
1706         cp $i /usr/local/pkgs/graft-2.16/man/man$man/$manpage;     \
1707         chmod 644 /usr/local/pkgs/graft-2.16/man/man$man/$manpage; \
1708     done
1709
1710     for i in graft.html graft.pdf graft.ps graft.txt;              \
1711     do                                                             \
1712         mkdir -p /usr/local/pkgs/graft-2.16/doc;                   \
1713         cp doc/$i /usr/local/pkgs/graft-2.16/doc;                  \
1714         chmod 644 /usr/local/pkgs/graft-2.16/doc/$i;               \
1715         touch /usr/local/pkgs/graft-2.16/doc/.nograft;             \
1716     done
1717 </pre>
1718
1719     </ol>
1720
1721 <p> <em>Graft</em> is now installed and ready to be used. </p>
1722
1723 <p> <strong>NOTE:</strong> If you make changes to your <em>Graft</em> installation at a
1724 later date, please run the following commands: </p>
1725
1726 <pre>
1727     make clean
1728     make install
1729 </pre>
1730
1731 <p> Failure to do this may result in a <em>Graft</em> manual page that does
1732 NOT reflect your current configuration. </p>
1733
1734 <h3><a name="rpm_and_deb">Creating RPM and DEB packages</a></h3>
1735
1736 <p> Beginning with <em>Graft</em> 2.11 there is now the ability to create
1737 RPM and Debian installation packages. Obviously you'll need one or more of
1738 the <em>rpmbuild</em> and <em>dpkg-deb</em> packages installed on your
1739 system. </p>
1740
1741 <p> After editing the <tt>Makefile</tt> to suit your environment simply run
1742 the appropriate <tt>make</tt> command to create the binary installation
1743 package in the current directory: </p>
1744
1745 <pre>
1746     make rpm
1747 </pre>
1748
1749 <p> or </p>
1750
1751 <pre>
1752     make deb
1753 </pre>
1754
1755 <p> The creation of these packages is somewhat experimental. Please let the
1756 author know if you have issues. </p>
1757
1758 <hr>
1759
1760 <h3><a name="gotchas">Grafting <em>Graft</em> and <em>Perl</em> - the
1761 bootstrap problem</a></h3>
1762
1763 <p> <strong>If you are using an operating system that comes with <em>Perl</em>
1764 5.<em>x</em> - such as RedHat or Ubuntu Linux - then you don't need to worry
1765 about <em>grafting</em> <em>Perl</em>, so this section can be ignored.</strong> </p>
1766
1767 <p> <strong>However if you are a creator of an operating system
1768 distribution then this section may be relevant.</strong> </p>
1769
1770 <p> Embedded into the <em>Graft</em> executable is the location of the
1771 <em>Perl</em> executable. If you've understood the concept behind
1772 <em>Graft</em> then this location may be the <em>grafted</em> location of
1773 <em>Perl</em> rather than the true location of <em>Perl</em>. </p>
1774
1775 <p> This presents a dilemma when you come to <em>graft</em> both <em>Graft</em>
1776 and <em>Perl</em>. You can't run the <em>grafted</em> location of the
1777 <em>Graft</em> executable because it doesn't exist yet, and you can't run
1778 the real location of the <em>Graft</em> executable because <em>Perl</em>
1779 hasn't been <em>grafted</em> yet. </p>
1780
1781 <p> Assuming that <em>Graft</em> and <em>Perl</em> are installed in </p>
1782
1783 <pre>
1784     /usr/local/pkgs/graft-2.16
1785     /usr/local/pkgs/perl-5.18.2
1786 </pre>
1787
1788 <p> you can resolve this dilemma by executing the following commands:
1789 </p>
1790
1791 <pre>
1792     /usr/local/pkgs/perl-5.18.2/bin/perl /usr/local/pkgs/graft-2.16/bin/graft -i graft-2.16
1793     /usr/local/pkgs/perl-5.18.2/bin/perl /usr/local/pkgs/graft-2.16/bin/graft -i perl-5.18.2
1794 </pre>
1795
1796 <p> This will <em>graft</em> both <em>Graft</em> and <em>Perl</em> from the
1797 default package installation directory (as specified by
1798 <strong>PACKAGEDIR</strong> in the <tt>Makefile</tt>) into your default target
1799 directory (as specified by <strong>TARGETDIR</strong> in the <tt>Makefile</tt>).
1800 </p>
1801
1802 <p> If you don't wish to use the default directories you can use the
1803 following commands to <em>graft</em> the packages into <tt>/pkgs</tt>
1804 instead of <tt>/usr/local</tt> for example: </p>
1805
1806 <pre>
1807     /usr/local/pkgs/perl-5.18.2/bin/perl /usr/local/pkgs/graft-2.16/bin/graft -i -t /pkgs /usr/local/pkgs/graft-2.16
1808     /usr/local/pkgs/perl-5.18.2/bin/perl /usr/local/pkgs/graft-2.16/bin/graft -i -t /pkgs /usr/local/pkgs/perl-5.18.2
1809 </pre>
1810
1811 <p> Now both <em>Graft</em> and <em>Perl</em> have been <em>grafted</em> and any
1812 other package can be <em>grafted</em> by executing the simpler command:
1813 </p>
1814
1815 <pre>
1816     graft -i <em>package</em>
1817 </pre>
1818
1819 <p> The <em>Graft</em> distribution includes a program called
1820 <tt>graftBootStrap.sh</tt> which allows you to easily <em>graft</em> both
1821 <em>Graft</em> and <em>Perl</em>. It can be found in the <em>contrib</em>
1822 directory of the distribution. Thanks to Gordon Rowell for providing it.</p>
1823
1824 <p> You may also find the <tt>-L</tt> command line option to be useful to
1825 programmatically determine where <em>Graft</em> expects to find
1826 <em>Perl</em> along with the default locations of its log file, target and
1827 package directories. See the <a href="#graft-L">Information</a> section
1828 below for details. </p>
1829
1830 <hr>
1831
1832 <h2><a name="using-graft">Using <em>Graft</em></a></h2>
1833
1834 <h3><a name="compiling-packages">Compiling Packages</a></h3>
1835
1836 <p> Any packages you wish to place under the control of <em>Graft</em> should
1837 be compiled and installed in such a way that any package dependent
1838 files are referenced with the ACTUAL package installation directory
1839 rather than the common area in which <em>Graft</em> will be creating
1840 symbolic links. For example, ensure that <em>Perl</em> version
1841 <em>5.18.2</em> is looking for its library files in
1842 <tt>/usr/local/pkgs/perl-5.18.2/lib/perl5</tt> instead of
1843 <tt>/usr/local/lib/perl5</tt>. This approach will allow you to easily
1844 separate multiple versions of the same package without any problems. </p>
1845
1846 <hr width="25%">
1847
1848 <h3><a name="usage"><em>Graft</em> command line options</a></h3>
1849
1850 <p> All of the details concerning actions, package locations and target
1851 directories are passed to <em>Graft</em> on the command line.
1852 (<em>Graft</em> 1.<em>x</em> used a configuration file. This has now been
1853 deprecated in favour of a log file). </p>
1854
1855 <p> <em>Graft</em>'s command line options can be summarised as: </p>
1856
1857 <pre>
1858     graft -i [-P|u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
1859     graft -d [-D] [-u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
1860     graft -p [-D] [-u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
1861     graft -L
1862 </pre>
1863
1864 <p> <em>Graft</em> has four basic actions: </p>
1865
1866     <ol>
1867
1868         <li> <p> <a name="graft-i"><strong>Install</strong></a> </p>
1869
1870 <pre>
1871     graft -i [-C] [-P|u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
1872 </pre>
1873
1874             <dl>
1875
1876                 <dt> <strong>-i</strong>
1877                     <dd>
1878                         <p> Install symbolic links from the package
1879                         installation directory to the target directory.
1880                         Requires superuser privileges if
1881                         <strong>SUPERUSER</strong> was set to <strong>1</strong> in the
1882                         <tt>Makefile</tt>. </p>
1883
1884                 <dt> <strong>-C</strong>
1885                     <dd>
1886                         <p> If <strong>NEVERGRAFT</strong> was set to <strong>1</strong>
1887                         in the <tt>Makefile</tt>, disable the automatic
1888                         exclusion of files and/or directories whose
1889                         names exactly match the values specified by
1890                         <strong>GRAFT-NEVER</strong> in the <tt>Makefile</tt>. </p>
1891
1892                         <p> If <strong>NEVERGRAFT</strong> was set to <strong>0</strong>
1893                         in the <tt>Makefile</tt>, force the automatic
1894                         exclusion of files and/or directories whose
1895                         names exactly match the values specified by
1896                         <strong>GRAFT-NEVER</strong> in the <tt>Makefile</tt>. </p>
1897
1898                         <p> Can only be used with the -i option. </p>
1899
1900                         <p> This option is ignored for each <em>grafted</em>
1901                         directory, if the directory contains a
1902                         <tt>.nograft</tt> or <tt>.graft-include</tt>
1903                         file. </p>
1904
1905                         <p> The <em>Graft</em> manual page will correctly
1906                         reflect the behaviour of this option based on the
1907                         values specified in the <tt>Makefile</tt>. If there
1908                         are no objects specified for
1909                         <strong>GRAFT-NEVER</strong> then this option will
1910                         be silently ignored and will not appear in the help
1911                         message nor in the manual page. </p>
1912
1913                 <dt> <strong>-P</strong>
1914                     <dd>
1915                         <p> Preserve modes and ownerships when creating new
1916                         directories or copying files if
1917                         <strong>PRESERVEPERMS</strong> was set to
1918                         <strong>0</strong> in the <tt>Makefile</tt>. Do not
1919                         preserve modes and ownerships if the option is not
1920                         provided on the command line. </p>
1921
1922                         <p> Do not preserve modes and ownerships when
1923                         creating new directories or copying files if
1924                         <strong>PRESERVEPERMS</strong> was set to
1925                         <strong>1</strong> in the <tt>Makefile</tt>.
1926                         Preserve modes and ownerships if the option is not
1927                         provided on the command line. </p>
1928
1929                         <p> Cannot be used with the <strong>-u</strong> option. </p>
1930
1931                         <p> This option will be silently ignored if the
1932                         effective user of <em>Graft</em> is not root. </p>
1933
1934                         <p> The <em>Graft</em> manual page will correctly
1935                         reflect the behaviour of this option based on the
1936                         values specified in the <tt>Makefile</tt>. This
1937                         option will be silently ignored and will not appear
1938                         in the help message nor in the manual page if
1939                         <strong>SUPERUSER</strong> was set to
1940                         <strong>0</strong> in the <tt>Makefile</tt>. </p>
1941
1942                 <dt> <strong>-u</strong>
1943                     <dd>
1944                         <p> Superuser privileges are not required when
1945                         installing packages. </p>
1946
1947                         <p> Cannot be used with the <strong>-P</strong> option. </p>
1948
1949                         <p> This option is only available if
1950                         <strong>SUPERUSER</strong> was set to
1951                         <strong>1</strong> in the <tt>Makefile</tt>. </p>
1952
1953                         <p> The <em>Graft</em> manual page will correctly
1954                         reflect the behaviour of this option based on the
1955                         values specified in the <tt>Makefile</tt>. This
1956                         option will be silently ignored and will not appear
1957                         in the help message nor in the manual page if
1958                         <strong>SUPERUSER</strong> was set to
1959                         <strong>0</strong> in the <tt>Makefile</tt>. </p>
1960
1961                 <dt> <strong>-l <em>log</em></strong>
1962                     <dd>
1963                         <p> Specify an alternate log file instead of the
1964                         default specified by <strong>LOGFILE</strong> in the
1965                         <tt>Makefile</tt>. No logging is performed if
1966                         the <strong>-n</strong> option is used. </p>
1967
1968                         <p> Log entries have the form: </p>
1969
1970 <pre>
1971     878790215   1.10+   I    /usr/local/pkgs/cpio-2.4.2            /usr/local
1972     878888916   2.1     I    /usr/local/pkgs/gzip-1.2.4            /usr/local
1973     878888916   2.1     IC   /usr/local/pkgs/gzip-1.2.4/bin/gzip   invalid symlink
1974 </pre>
1975
1976                         <p> This shows that a development version of
1977                         <em>graft</em> (1.10+) was used to install
1978                         symbolic links from <tt>/usr/local/pkgs/cpio-2.4.2</tt>
1979                         to <tt>/usr/local</tt>. A new version of
1980                         <em>graft</em> (2.1) was used to install symbolic
1981                         links from <tt>/usr/local/pkgs/gzip-1.2.4</tt> to
1982                         <tt>/usr/local</tt>. The <tt>IC</tt> entry indicates
1983                         that a conflict occurred during this
1984                         installation - the file <tt>/usr/local/pkgs/bin/gzip</tt>
1985                         was a symbolic link to something other than
1986                         <tt>/usr/local/pkgs/gzip-1.2.4/bin/gzip</tt>. </p>
1987
1988                 <dt> <strong>-n</strong>
1989                     <dd>
1990                         <p> List actions but do not perform them. Implies
1991                         the very verbose option. Does not require
1992                         superuser privileges regardless of the value of
1993                         <strong>SUPERUSER</strong> in the <tt>Makefile</tt>. </p>
1994
1995                 <dt> <strong>-v</strong>
1996                     <dd>
1997                         <p> Be verbose. </p>
1998
1999                 <dt> <strong>-V</strong>
2000                     <dd>
2001                         <p> Be very verbose. </p>
2002
2003                 <dt> <strong>-r <em>/rootdir</em></strong>
2004                     <dd>
2005                         <p> Use the fully qualified named directory as the
2006                         root directory for all graft operations. The source
2007                         directory, target directory and log file will all
2008                         be relative to this specific directory. </p>
2009
2010                         <p> Can only be used by the superuser. </p>
2011
2012                 <dt> <strong>-s</strong>
2013                     <dd>
2014                         <p> <em>Stow</em>/<em>Depot</em> compatibility mode.
2015                         Infer the <em>Graft</em> target directory from
2016                         each package installation directory in the
2017                         manner of <em>Stow</em> and <em>Depot</em>. </p>
2018
2019                         <p> Target directory is the <tt>dirname</tt> of the
2020                         <tt>dirname</tt> of the package installation
2021                         directory. (Yes that really is two
2022                         <tt>dirname</tt>s). So if the package
2023                         installation directory is </p>
2024
2025 <pre>
2026     /usr/local/depot/gzip-1.2.4
2027 </pre>
2028
2029                         <p> the package will be <em>grafted</em> into
2030                         </p>
2031
2032 <pre>
2033     /usr/local
2034 </pre>
2035
2036                         <p> Cannot be used with the <strong>-t</strong> option. </p>
2037
2038                 <dt> <strong>-t <em>target</em></strong>
2039                     <dd>
2040                         <p> Override the default <em>graft</em> target
2041                         directory with <strong><em>target</em></strong>. The value
2042                         of <strong><em>target</em></strong> must be a fully
2043                         qualified directory and it must exist. </p>
2044
2045                         <p> Cannot be used with the <strong>-s</strong> option. </p>
2046
2047                 <dt> <strong>package</strong>
2048                     <dd>
2049                         <p> Install the named package. If <strong>package</strong> is
2050                         a fully qualified directory, use it as the
2051                         package installation directory. If
2052                         <strong>package</strong> is not a fully qualified
2053                         directory, prepend it with the value of
2054                         <strong>PACKAGEDIR</strong> as specified in the
2055                         <tt>Makefile</tt>. </p>
2056
2057             </dl>
2058
2059 <hr width="10%">
2060
2061         <li> <p> <a name="graft-d"><strong>Delete</strong></a> </p>
2062
2063 <pre>
2064     graft -d [-D] [-u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
2065 </pre>
2066
2067             <dl>
2068
2069                 <dt> <strong>-d</strong>
2070                     <dd>
2071                         <p> Delete symbolic links from the package target
2072                         directory to the package installation
2073                         directory. Requires superuser privileges if
2074                         <strong>SUPERUSER</strong> was set to <strong>1</strong> in the
2075                         <tt>Makefile</tt>. </p>
2076
2077                 <dt> <strong>-D</strong>
2078                     <dd>
2079                         <p> Delete empty directories if
2080                         <strong>DELETEOBJECTS</strong> was set to <strong>0</strong> in the
2081                         <tt>Makefile</tt>. If the option is not
2082                         provided on the command line, notify the user
2083                         that a directory has been emptied. </p>
2084
2085                         <p> Do not delete empty directories if
2086                         <strong>DELETEOBJECTS</strong> was set to <strong>1</strong> in the
2087                         <tt>Makefile</tt>. Notify the user that a
2088                         directory has been emptied. If the option is
2089                         not provided on the command line, delete empty
2090                         directories. </p>
2091
2092                         <p> The <em>Graft</em> manual page will correctly
2093                         reflect the behaviour of this option based on the
2094                         values specified in the <tt>Makefile</tt>. </p>
2095
2096                 <dt> <strong>-u</strong>
2097                     <dd>
2098                         <p> Superuser privileges are not required when
2099                         deleting packages. </p>
2100
2101                         <p> This option is only available if
2102                         <strong>SUPERUSER</strong> was set to
2103                         <strong>1</strong> in the <tt>Makefile</tt>. </p>
2104
2105                         <p> The <em>Graft</em> manual page will correctly
2106                         reflect the behaviour of this option based on the
2107                         values specified in the <tt>Makefile</tt>. This
2108                         option will be silently ignored and will not appear
2109                         in the help message nor in the manual page if
2110                         <strong>SUPERUSER</strong> was set to
2111                         <strong>0</strong> in the <tt>Makefile</tt>. </p>
2112
2113                 <dt> <strong>-l <em>log</em></strong>
2114                     <dd>
2115                         <p> Specify an alternate log file instead of the
2116                         default specified by <strong>LOGFILE</strong> in the
2117                         <tt>Makefile</tt>. No logging is performed if
2118                         the <strong>-n</strong> option is used. </p>
2119
2120                         <p> Log entries have the form: </p>
2121
2122 <pre>
2123     879126278       1.10+   D       /usr/local/pkgs/weblint-1.017     /usr/local
2124     879126278       1.10+   DC      /usr/local/pkgs/weblint-1.017/bin/weblint  file exists
2125     879126278       1.10+   DC      /usr/local/pkgs/weblint-1.017/man/man1/weblint.1  file exists
2126 </pre>
2127
2128                         <p> This shows that a development version of
2129                         <em>graft</em> (1.10+) was used to delete
2130                         symbolic links from <tt>/usr/local</tt> to
2131                         <tt>/usr/local/pkgs/weblint-1.017</tt>. The <tt>DC</tt>
2132                         entries indicate that conflicts occurred during
2133                         this action - the files
2134                         <tt>/usr/local/bin/weblint</tt> and
2135                         <tt>/usr/local/man/man1/weblint.1</tt> already
2136                         exist. </p>
2137
2138                 <dt> <strong>-n</strong>
2139                     <dd>
2140                         <p> List actions but do not perform them. Implies
2141                         the very verbose option. Does not require
2142                         superuser privileges regardless of the value of
2143                         <strong>SUPERUSER</strong> in the <tt>Makefile</tt>. </p>
2144
2145                 <dt> <strong>-v</strong>
2146                     <dd>
2147                         <p> Be verbose. </p>
2148
2149                 <dt> <strong>-V</strong>
2150                     <dd>
2151                         <p> Be very verbose. </p>
2152
2153                 <dt> <strong>-r <em>/rootdir</em></strong>
2154                     <dd>
2155                         <p> Use the fully qualified named directory as the
2156                         root directory for all graft operations. The source
2157                         directory, target directory and log file will all
2158                         be relative to this specific directory. </p>
2159
2160                         <p> Can only be used by the superuser. </p>
2161
2162                 <dt> <strong>-s</strong>
2163                     <dd>
2164                         <p> <em>Stow</em>/<em>Depot</em> compatibility mode.
2165                         Infer the <em>Graft</em> target directory from
2166                         each package installation directory in the
2167                         manner of <em>Stow</em> and <em>Depot</em>. </p>
2168
2169                         <p> Target directory is the <tt>dirname</tt> of the
2170                         <tt>dirname</tt> of the package installation
2171                         directory. (Yes that really is two
2172                         <tt>dirname</tt>s). So if the package
2173                         installation directory is </p>
2174
2175 <pre>
2176     /usr/local/depot/gzip-1.2.4
2177 </pre>
2178
2179                         <p> the package will be <em>grafted</em> into
2180                         </p>
2181
2182 <pre>
2183     /usr/local
2184 </pre>
2185
2186                         <p> Cannot be used with the <strong>-t</strong> option. </p>
2187
2188                 <dt> <strong>-t <em>target</em></strong>
2189                     <dd>
2190                         <p> Override the default <em>graft</em> target
2191                         directory with <strong><em>target</em></strong>. The value
2192                         of <strong><em>target</em></strong> must be a fully
2193                         qualified directory and it must exist. </p>
2194
2195                         <p> Cannot be used with the <strong>-s</strong> option. </p>
2196
2197                 <dt> <strong>package</strong>
2198                     <dd>
2199                         <p> Delete the named package. If <strong>package</strong> is
2200                         a fully qualified directory, use it as the
2201                         package installation directory. If
2202                         <strong>package</strong> is not a fully qualified
2203                         directory, prepend it with the value of
2204                         <strong>PACKAGEDIR</strong> as specified in the
2205                         <tt>Makefile</tt>. </p>
2206
2207             </dl>
2208
2209 <hr width="10%">
2210
2211         <li> <p> <a name="graft-p"><strong>Prune</strong></a> </p>
2212
2213 <pre>
2214     graft -p [-D] [-u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
2215 </pre>
2216
2217             <dl>
2218
2219                 <dt> <strong>-p</strong>
2220                     <dd>
2221                         <p> Prune objects (files, links or directories)
2222                         from the package target directory that are in
2223                         conflict with the package installation
2224                         directory. Requires superuser privileges if
2225                         <strong>SUPERUSER</strong> was set to <strong>1</strong> in the
2226                         <tt>Makefile</tt>. </p>
2227
2228                 <dt> <strong>-D</strong>
2229                     <dd>
2230                         <p> Remove conflicting objects if
2231                         <strong>DELETEOBJECTS</strong> was set to <strong>0</strong> in the
2232                         <tt>Makefile</tt>. Rename conflicting objects
2233                         as <tt><em>object</em>.pruned</tt> if the option
2234                         is not provided on the command line. </p>
2235
2236                         <p> Rename conflicting objects to
2237                         <tt><em>object</em>.pruned</tt> if
2238                         <strong>DELETEOBJECTS</strong> was set to <strong>1</strong> in the
2239                         <tt>Makefile</tt>. Remove conflicting objects
2240                         if the option is not provided in the command
2241                         line. </p>
2242
2243                         <p> If a directory is to be removed and it is not
2244                         empty, it will be renamed as
2245                         <tt><em>dir</em>.pruned</tt> and a suitable
2246                         warning message will be given regardless of the
2247                         sense of this flag. </p>
2248
2249                         <p> The <em>Graft</em> manual page will correctly
2250                         reflect the behaviour of this option based on the
2251                         values specified in the <tt>Makefile</tt>. </p>
2252
2253                 <dt> <strong>-u</strong>
2254                     <dd>
2255                         <p> Superuser privileges are not required when
2256                         pruning packages. </p>
2257
2258                         <p> This option is only available if
2259                         <strong>SUPERUSER</strong> was set to
2260                         <strong>1</strong> in the <tt>Makefile</tt>. </p>
2261
2262                         <p> The <em>Graft</em> manual page will correctly
2263                         reflect the behaviour of this option based on the
2264                         values specified in the <tt>Makefile</tt>. This
2265                         option will be silently ignored and will not appear
2266                         in the help message nor in the manual page if
2267                         <strong>SUPERUSER</strong> was set to
2268                         <strong>0</strong> in the <tt>Makefile</tt>. </p>
2269
2270                 <dt> <strong>-l <em>log</em></strong>
2271                     <dd>
2272                         <p> Specify an alternate log file instead of the
2273                         default specified by <strong>LOGFILE</strong> in the
2274                         <tt>Makefile</tt>. No logging is performed if
2275                         the <strong>-n</strong> option is used. </p>
2276
2277                         <p> Log entries have the form: </p>
2278
2279 <pre>
2280     879126283       1.10+   P       /usr/local/pkgs/weblint-1.017     /usr/local
2281 </pre>
2282
2283                         <p> This shows that a development version of
2284                         <em>graft</em> (1.10+) was used to delete objects
2285                         from <tt>/usr/local</tt> that were in conflict with
2286                         <tt>/usr/local/pkgs/weblint-1.017</tt>. </p>
2287
2288                 <dt> <strong>-n</strong>
2289                     <dd>
2290                         <p> List actions but do not perform them. Implies
2291                         the very verbose option. Does not require
2292                         superuser privileges regardless of the value of
2293                         <strong>SUPERUSER</strong> in the <tt>Makefile</tt>. </p>
2294
2295                 <dt> <strong>-v</strong>
2296                     <dd>
2297                         <p> Be verbose. </p>
2298
2299                 <dt> <strong>-V</strong>
2300                     <dd>
2301                         <p> Be very verbose. </p>
2302
2303                 <dt> <strong>-r <em>/rootdir</em></strong>
2304                     <dd>
2305                         <p> Use the fully qualified named directory as the
2306                         root directory for all graft operations. The source
2307                         directory, target directory and log file will all
2308                         be relative to this specific directory. </p>
2309
2310                         <p> Can only be used by the superuser. </p>
2311
2312                 <dt> <strong>-s</strong>
2313                     <dd>
2314                         <p> <em>Stow</em>/<em>Depot</em> compatibility mode.
2315                         Infer the <em>Graft</em> target directory from
2316                         each package installation directory in the
2317                         manner of <em>Stow</em> and <em>Depot</em>. </p>
2318
2319                         <p> Target directory is the <tt>dirname</tt> of the
2320                         <tt>dirname</tt> of the package installation
2321                         directory. (Yes that really is two
2322                         <tt>dirname</tt>s). So if the package
2323                         installation directory is </p>
2324
2325 <pre>
2326     /usr/local/depot/gzip-1.2.4
2327 </pre>
2328
2329                         <p> the package will be <em>grafted</em> into
2330                         </p>
2331
2332 <pre>
2333     /usr/local
2334 </pre>
2335
2336                         <p> Cannot be used with the <strong>-t</strong> option. </p>
2337
2338                 <dt> <strong>-t <em>target</em></strong>
2339                     <dd>
2340                         <p> Override the default <em>graft</em> target
2341                         directory with <strong><em>target</em></strong>. The value
2342                         of <strong><em>target</em></strong> must be a fully
2343                         qualified directory and it must exist. </p>
2344
2345                         <p> Cannot be used with the <strong>-s</strong> option. </p>
2346
2347                 <dt> <strong>package</strong>
2348                     <dd>
2349                         <p> Prune the named package. If <strong>package</strong> is
2350                         a fully qualified directory, use it as the
2351                         package installation directory. If
2352                         <strong>package</strong> is not a fully qualified
2353                         directory, prepend it with the value of
2354                         <strong>PACKAGEDIR</strong> as specified in the
2355                         <tt>Makefile</tt>. </p>
2356
2357             </dl>
2358
2359         <li> <p> <a name="graft-L"><strong>Information</strong></a> </p>
2360
2361 <pre>
2362     graft -L
2363 </pre>
2364
2365             <dl>
2366
2367                 <dt> <strong>-L</strong>
2368                     <dd>
2369                         <p> This is a special mode and it overrides all
2370                         other command line arguments. When present
2371                         <strong>graft</strong> will display the
2372                         <strong>default</strong> locations for Perl, the
2373                         graft log file, the target directory, and the
2374                         package directory in a form suitable for creating
2375                         environment variables for Bourne like shells. The
2376                         output will appear on <strong>STDOUT</strong> as
2377                         follows: </p>
2378
2379 <pre>
2380     GRAFT_PERL=/usr/bin/perl
2381     GRAFT_LOGFILE=/var/log/graft
2382     GRAFT_TARGETDIR=/usr/local
2383     GRAFT_PACKAGEDIR=/usr/local/pkgs
2384 </pre>
2385
2386                           <p> You can set these environment variables using
2387                           one of the following methods. </p>
2388
2389 <pre>
2390     eval "$(graft -L)"    # modern shells such as bash, zsh etc
2391     eval "`graft -L`"     # older shells such as sh etc
2392 </pre>
2393
2394             </dl>
2395
2396     </ol>
2397
2398 <hr width="25%">
2399
2400 <h3><a name="testing">Testing the <em>Graft</em> Installation</a></h3>
2401
2402 <p> Before creating the symbolic links from the target directory to
2403 the package directory, you may wish to see what actions <em>Graft</em>
2404 will perform. Execute the following command: </p>
2405
2406 <pre>
2407     graft -i -n <em>package-name</em>
2408 </pre>
2409
2410 <p> The <tt>-i</tt> option tells <em>Graft</em> to install the package and
2411 the <tt>-n</tt> option tells <em>Graft</em> to report on its actions
2412 without actually performing them. The default <em>Graft</em> target
2413 directory will be used and the package installation directory will be
2414 taken from the fully qualified package argument or the default value
2415 will be prepended to the package argument if it is not fully qualified.
2416 </p>
2417
2418 <p> <em>Graft</em> will report on the following actions: </p>
2419
2420     <ul>
2421
2422         <li> <p> Installing links to <em>package-location</em> in
2423         <em>package-target</em> </p>
2424
2425         <p> Indicates the real package location and its <em>grafted</em>
2426         target. </p>
2427
2428         <li> <p> Processing <em>package-directory</em> </p>
2429
2430         <p> Indicates which package directory is being processed. </p>
2431
2432         <li> <p> MKDIR <em>dirname</em> </p>
2433
2434         <p> This destination directory will be created. </p>
2435
2436         <li> <p> SYMLINK <em>dest-package-file</em> -&gt; <em>package-file</em>
2437         </p>
2438
2439         <p> This symbolic link will be created. </p>
2440
2441         <li> <p> NOP <em>string</em> </p>
2442
2443         <p> No action was necessary for this package object. </p>
2444
2445         <li> <p> BYPASS <em>dirname</em> - .nograft file found</p>
2446
2447         <p> This directory contains a file called <tt>.nograft</tt> so its
2448         contents and any subdirectories will be bypassed by
2449         <em>Graft</em>. </p>
2450
2451         <li> <p> READING include file
2452         <em>package-dir</em><tt>/.graft-include</tt> </p>
2453
2454         <p> The directory currently being processed by <em>Graft</em>
2455         contains a file called <tt>.graft-include</tt> which contains
2456         a list of file and/or directory names from the directory that
2457         should only be <em>grafted</em>. The contents of this file are
2458         being read by <em>Graft</em>. </p>
2459
2460         <li> <p> INCLUDE file <em>package-file</em> - listed in
2461         <em>package-dir</em><tt>/.graft-include</tt> </p>
2462
2463         <p> The file name mentioned in this message appears in the
2464         <em>.graft-include</em> file and the file exists in the directory
2465         currently being processed. It will be <tt>grafted</tt>. </p>
2466
2467         <li> <p> IGNORE file <em>package-file</em> - not listed in
2468         <em>package-dir</em><tt>/.graft-include</tt> </p>
2469
2470         <p> The file name mentioned in this message does not appear in the
2471         <em>.graft-include</em> file and the file exists in the directory
2472         currently being processed. It will not be <tt>grafted</tt>. </p>
2473
2474         <li> <p> INCLUDE directory <em>package-directory</em> - listed in
2475         <em>package-dir</em><tt>/.graft-include</tt> </p>
2476
2477         <p> The directory name mentioned in this message appears
2478         in the <em>.graft-include</em> file and the directory exists
2479         in the directory currently being processed. It will be
2480         <tt>grafted</tt>. </p>
2481
2482         <li> <p> IGNORE directory <em>package-file</em> - not listed in
2483         <em>package-dir</em><tt>/.graft-include</tt> </p>
2484
2485         <p> The directory name mentioned in this message does not
2486         appear in the <em>.graft-include</em> file and the directory
2487         exists in the directory currently being processed. It will not
2488         be <tt>grafted</tt>. </p>
2489
2490         <li> <p> READING exclude file
2491         <em>package-dir</em><tt>/.graft-exclude</tt> </p>
2492
2493         <p> The directory currently being processed by <em>Graft</em>
2494         contains a file called <tt>.graft-exclude</tt> which contains
2495         a list of file and/or directory names from the directory that
2496         should not be <em>grafted</em>. The contents of this file are
2497         being read by <em>Graft</em>. </p>
2498
2499         <li> <p> IGNORE include file
2500         <em>package-dir</em><tt>/.graft-include</tt>, overridden by exclude
2501         file <em>package-dir</em><tt>/.graft-exclude</tt> </p>
2502
2503         <p> The directory currently being processed by <em>Graft</em>
2504         contains a file called <tt>.graft-exclude</tt> as well as a file
2505         called <tt>.graft-include</tt>. The <tt>.graft-exclude</tt>
2506         file takes precedence over the <tt>.graft-include</tt> file,
2507         so the latter file will be ignored. </p>
2508
2509         <li> <p> EXCLUDE file <em>package-file</em> - listed in
2510         <em>package-dir</em><tt>/.graft-exclude</tt> </p>
2511
2512         <p> The file name mentioned in this message appears in the
2513         <em>.graft-exclude</em> file and the file exists in the directory
2514         currently being processed. It will not be <tt>grafted</tt>. </p>
2515
2516         <li> <p> EXCLUDE directory <em>package-directory</em> - listed in
2517         <em>package-dir</em><tt>/.graft-exclude</tt> </p>
2518
2519         <p> The directory name mentioned in this message appears
2520         in the <em>.graft-exclude</em> file and the directory exists
2521         in the directory currently being processed. It will not be
2522         <tt>grafted</tt>. </p>
2523
2524         <li> <p> CONFLICT <em>message</em> </p>
2525
2526         <p> <em>Graft</em> could not successfully process a package object.
2527         One of the following conditions was encountered: </p>
2528
2529             <ul>
2530
2531                 <li> The package object is a directory and the
2532                 target object exists but it not a directory.
2533
2534                 <li> The package object is not a directory and the
2535                 target object exists and is not a symbolic
2536                 link.
2537
2538                 <li> The package object is not a directory and the
2539                 target object exists and is a symbolic link to
2540                 something other than the package object.
2541
2542             </ul>
2543
2544         <p> Conflicts are ALWAYS reported on standard error. If you wish
2545         to see if the installation of a package will have any
2546         conflicts, you can execute: </p>
2547
2548 <pre>
2549     graft -i -n <em>package-name</em> &gt; /dev/null
2550 </pre>
2551
2552         <p> Only <tt>CONFLICT</tt> messages will be displayed. If nothing
2553         is displayed then you can safely conclude that this package
2554         can be installed using <em>Graft</em> without any conflicts.
2555         </p>
2556
2557     </ul>
2558
2559 <p> If you were to test the installation of the <em>kermit-5A190</em>
2560 package you would execute the command: </p>
2561
2562 <pre>
2563     graft -i -n kermit-5A190
2564 </pre>
2565
2566 You should see output resembling:
2567
2568 <pre>
2569     Installing   links to /usr/local/pkgs/kermit-5A190 in /usr/local
2570     Processing   /usr/local/pkgs/kermit-5A190
2571     SYMLINK      /usr/local/README -&gt; /usr/local/pkgs/kermit-5A190/README
2572     NOP          /usr/local/pkgs/kermit-5A190/bin and /usr/local/bin are both directories
2573     Processing   /usr/local/pkgs/kermit-5A190/bin
2574     SYMLINK      /usr/local/bin/kermit -&gt; /usr/local/pkgs/kermit-5A190/bin/kermit
2575     SYMLINK      /usr/local/bin/wart -&gt; /usr/local/pkgs/kermit-5A190/bin/wart
2576     NOP          /usr/local/pkgs/kermit-5A190/man and /usr/local/man are both directories
2577     Processing   /usr/local/pkgs/kermit-5A190/man
2578     NOP          /usr/local/pkgs/kermit-5A190/man/man1 and /usr/local/man/man1 are both directories
2579     Processing   /usr/local/pkgs/kermit-5A190/man/man1
2580     SYMLINK      /usr/local/man/man1/kermit.1 -&gt; /usr/local/pkgs/kermit-5A190/man/man1/kermit.1
2581     MKDIR        /usr/local/doc
2582     Processing   /usr/local/pkgs/kermit-5A190/doc
2583     SYMLINK      /usr/local/doc/ckccfg.doc -&gt; /usr/local/pkgs/kermit-5A190/doc/ckccfg.doc
2584     SYMLINK      /usr/local/doc/ckuins.doc -&gt; /usr/local/pkgs/kermit-5A190/doc/ckuins.doc
2585     SYMLINK      /usr/local/doc/ckc190.upd -&gt; /usr/local/pkgs/kermit-5A190/doc/ckc190.upd
2586     SYMLINK      /usr/local/doc/ckcker.upd -&gt; /usr/local/pkgs/kermit-5A190/doc/ckcker.upd
2587     SYMLINK      /usr/local/doc/ckaaaa.hlp -&gt; /usr/local/pkgs/kermit-5A190/doc/ckaaaa.hlp
2588     SYMLINK      /usr/local/doc/ckuaaa.hlp -&gt; /usr/local/pkgs/kermit-5A190/doc/ckuaaa.hlp
2589     NOP          /usr/local/pkgs/kermit-5A190/lib and /usr/local/lib are both directories
2590     Processing   /usr/local/pkgs/kermit-5A190/lib
2591     SYMLINK      /usr/local/lib/ckedemo.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckedemo.ini
2592     SYMLINK      /usr/local/lib/ckeracu.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckeracu.ini
2593     SYMLINK      /usr/local/lib/ckermit.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckermit.ini
2594     SYMLINK      /usr/local/lib/ckermod.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckermod.ini
2595     SYMLINK      /usr/local/lib/cketest.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/cketest.ini
2596     SYMLINK      /usr/local/lib/ckevt.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckevt.ini
2597     SYMLINK      /usr/local/lib/ckurzsz.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckurzsz.ini
2598 </pre>
2599
2600 <p> This output shows you that most of the directories already exist
2601 (indicated by the <tt>NOP</tt> flags). A symbolic link will be created
2602 in the relevant target directory to each of the files in the
2603 <em>kermit-5A190</em> package. One directory exists in the
2604 <em>kermit-5A190</em> package that does not exist in the target -
2605 <tt>doc</tt>. This directory will be created by <em>Graft</em>. </p>
2606
2607 <p> <strong>NOTE</strong>: If you are using the <em>automounter</em> you may not be
2608 able to create the directory <tt>/usr/local/doc</tt>. You'll have to create
2609 the directory on the NFS server under the file system in which it
2610 really lives. You should be familiar with the peculiarities of the
2611 <em>automounter</em> and your specific site configuration before creating
2612 any directories directly under mount points used by the
2613 <em>automounter</em>. </p>
2614
2615 <hr width="25%">
2616
2617 <h3><a name="installing-packages">Installing Packages</a></h3>
2618
2619 <p> Once you have ensured that <em>Graft</em> will perform the correct
2620 actions, you can execute: </p>
2621
2622 <pre>
2623     graft -i <em>package-name</em>
2624 </pre>
2625
2626 <p> So to install <em>kermit</em> you would execute: </p>
2627
2628 <pre>
2629     graft -i kermit-5A190
2630 </pre>
2631
2632 <p> There will be no output from <em>Graft</em> unless it encounters a
2633 conflict. If you wish to see more information you can specify one of
2634 the verbose flags. For a minimum of output you can execute: </p>
2635
2636 <pre>
2637     graft -i -v kermit-5A190
2638 </pre>
2639
2640 <p> You should see the following output: </p>
2641
2642 <pre>
2643     Processing   /usr/local/pkgs/kermit-5A190
2644     Processing   /usr/local/pkgs/kermit-5A190/bin
2645     Processing   /usr/local/pkgs/kermit-5A190/man
2646     Processing   /usr/local/pkgs/kermit-5A190/man/man1
2647     Processing   /usr/local/pkgs/kermit-5A190/doc
2648     Processing   /usr/local/pkgs/kermit-5A190/lib
2649 </pre>
2650
2651 <p> If you choose the very verbose option by executing: </p>
2652
2653 <pre>
2654     graft -i -V kermit-5A190
2655 </pre>
2656
2657 <p> the output will be the same as that when the <tt>-n</tt> option was
2658 used, however this time <em>Graft</em> will actually create the symbolic
2659 links. </p>
2660
2661 <pre>
2662     Installing   links to /usr/local/pkgs/kermit-5A190 in /usr/local
2663     Processing   /usr/local/pkgs/kermit-5A190
2664     SYMLINK      /usr/local/README -&gt; /usr/local/pkgs/kermit-5A190/README
2665     NOP          /usr/local/pkgs/kermit-5A190/bin and /usr/local/bin are both directories
2666     Processing   /usr/local/pkgs/kermit-5A190/bin
2667     SYMLINK      /usr/local/bin/kermit -&gt; /usr/local/pkgs/kermit-5A190/bin/kermit
2668     SYMLINK      /usr/local/bin/wart -&gt; /usr/local/pkgs/kermit-5A190/bin/wart
2669     NOP          /usr/local/pkgs/kermit-5A190/man and /usr/local/man are both directories
2670     Processing   /usr/local/pkgs/kermit-5A190/man
2671     NOP          /usr/local/pkgs/kermit-5A190/man/man1 and /usr/local/man/man1 are both directories
2672     Processing   /usr/local/pkgs/kermit-5A190/man/man1
2673     SYMLINK      /usr/local/man/man1/kermit.1 -&gt; /usr/local/pkgs/kermit-5A190/man/man1/kermit.1
2674     NOP          /usr/local/pkgs/kermit-5A190/doc and /usr/local/doc are both directories
2675     Processing   /usr/local/pkgs/kermit-5A190/doc
2676     SYMLINK      /usr/local/doc/ckccfg.doc -&gt; /usr/local/pkgs/kermit-5A190/doc/ckccfg.doc
2677     SYMLINK      /usr/local/doc/ckuins.doc -&gt; /usr/local/pkgs/kermit-5A190/doc/ckuins.doc
2678     SYMLINK      /usr/local/doc/ckc190.upd -&gt; /usr/local/pkgs/kermit-5A190/doc/ckc190.upd
2679     SYMLINK      /usr/local/doc/ckcker.upd -&gt; /usr/local/pkgs/kermit-5A190/doc/ckcker.upd
2680     SYMLINK      /usr/local/doc/ckaaaa.hlp -&gt; /usr/local/pkgs/kermit-5A190/doc/ckaaaa.hlp
2681     SYMLINK      /usr/local/doc/ckuaaa.hlp -&gt; /usr/local/pkgs/kermit-5A190/doc/ckuaaa.hlp
2682     NOP          /usr/local/pkgs/kermit-5A190/lib and /usr/local/lib are both directories
2683     Processing   /usr/local/pkgs/kermit-5A190/lib
2684     SYMLINK      /usr/local/lib/ckedemo.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckedemo.ini
2685     SYMLINK      /usr/local/lib/ckeracu.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckeracu.ini
2686     SYMLINK      /usr/local/lib/ckermit.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckermit.ini
2687     SYMLINK      /usr/local/lib/ckermod.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckermod.ini
2688     SYMLINK      /usr/local/lib/cketest.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/cketest.ini
2689     SYMLINK      /usr/local/lib/ckevt.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckevt.ini
2690     SYMLINK      /usr/local/lib/ckurzsz.ini -&gt; /usr/local/pkgs/kermit-5A190/lib/ckurzsz.ini
2691 </pre>
2692
2693 <p> <strong>NOTE</strong>: In this case the <tt>/usr/local/doc</tt> directory was not
2694 created by <em>Graft</em> because <tt>/usr/local</tt> is a mount point
2695 controlled by the <em>automounter</em>. The <tt>doc</tt> directory was
2696 created manually prior to executing <em>Graft</em>. </p>
2697
2698 <hr width="25%">
2699
2700 <h3><a name="bypass">Bypassing package directories</a></h3>
2701
2702 <p> You may have the need to place only part of a package under the control
2703 of <em>Graft</em>. Examples of such occasions may be: </p>
2704
2705     <ul>
2706
2707         <li> <p> The contents of one package conflict with another package.
2708         For example <tt>/usr/local/pkgs/gcc-2.7.2.1/lib/libiberty.a</tt> and
2709         <tt>/usr/local/pkgs/gdb-4.16/lib/libiberty.a</tt>. </p>
2710
2711         <li> <p> A package directory is obviously the exclusive domain of
2712         the package and no benefit will be gained by creating symbolic
2713         links to its files. For example
2714         <tt>/usr/local/pkgs/perl-5.18.2/lib/perl5</tt>. </p>
2715
2716         <p> <strong>NOTE</strong>: This will ONLY work if you originally compiled and
2717         installed the package such that it refers to its files by their
2718         '<em>real</em>' pathnames and NOT by the virtual pathnames
2719         provided by <em>Graft</em>. </p>
2720
2721     </ul>
2722
2723 <p> You can force <em>Graft</em> to bypass a directory by creating the file </p>
2724
2725 <pre>
2726     <em>package-name/dir/dir/</em>.nograft
2727 </pre>
2728
2729 <p> Using the second example above, if you were to create the file: </p>
2730
2731 <pre>
2732     /usr/local/pkgs/perl-5.18.2/lib/perl5/.nograft
2733 </pre>
2734
2735 <p> <em>Graft</em> would create directories and symbolic links for every file
2736 and directory down to <tt>/usr/local/pkgs/perl-5.18.2/lib</tt>. The <tt>perl5</tt>
2737 directory and anything below it would not be created. </p>
2738
2739 <hr width="25%">
2740
2741 <h3><a name="include">Including specific files and/or directories</a></h3>
2742
2743 <p> There may be the occasional need to include specific files and/or
2744 directories in a directory, rather than the entire directory tree itself. An
2745 example of such an occurrence would be the case where a package
2746 contains a number of subdirectories, only one of which is required to
2747 be <em>grafted</em>. </p>
2748
2749 <p> You can force <em>Graft</em> to only include any number of files and/or
2750 directories in a package directory by creating the file </p>
2751
2752 <pre>
2753     .graft-include
2754 </pre>
2755
2756 <p> in the same directory. </p>
2757
2758 <p> <tt>.graft-include</tt> will contain a list of file and/or directory names
2759 - one per line - of the files and/or directories you wish to include. </p>
2760
2761 <p> Consider the <em>a2ps</em> package for example. When installed it
2762 contains the following directories: </p>
2763
2764 <pre>
2765     /usr/local/pkgs/a2ps-4.13b/bin
2766     /usr/local/pkgs/a2ps-4.13b/etc
2767     /usr/local/pkgs/a2ps-4.13b/include
2768     /usr/local/pkgs/a2ps-4.13b/info
2769     /usr/local/pkgs/a2ps-4.13b/lib
2770     /usr/local/pkgs/a2ps-4.13b/man
2771     /usr/local/pkgs/a2ps-4.13b/share
2772 </pre>
2773
2774 <p> The only directory you wish to <em>graft</em> is the <tt>bin</tt>
2775 directory. You could place a <tt>.nograft</tt> file in each of the other
2776 directories, <strong>OR</strong> you could create a single <tt>.graft-include</tt>
2777 file in <tt>/usr/local/pkgs/a2ps-4.13b/.graft-include</tt>. This file would
2778 contain </p>
2779
2780 <pre>
2781     bin
2782 </pre>
2783
2784 <p> Now only the <tt>bin</tt> directory will be <em>grafted</em>. </p>
2785
2786 <hr width="25%">
2787
2788 <h3><a name="exclude">Excluding specific files and/or directories</a></h3>
2789
2790 <p> There may be the occasional need to exclude specific files and/or
2791 directories from a directory, rather than the entire directory itself. An
2792 example of such an occurrence would be the case where files from different
2793 packages have the same name. <em>Emacs</em> and <em>Xemacs</em> use the same
2794 names for a number of their configuration files for example. </p>
2795
2796 <p> You can force <em>Graft</em> to exclude any number of files and/or
2797 directories from a package directory by creating the file </p>
2798
2799 <pre>
2800     .graft-exclude
2801 </pre>
2802
2803 <p> in the same directory. </p>
2804
2805 <p> <tt>.graft-exclude</tt> will contain a list of file and/or directory names
2806 - one per line - of the files and/or directories you wish to exclude. </p>
2807
2808 <p> For example, if you did not wish the file </p>
2809
2810 <pre>
2811     /usr/local/pkgs/sudo-1.5.3/etc/sudoers
2812 </pre>
2813
2814 <p> to be <em>grafted</em> as </p>
2815
2816 <pre>
2817     /usr/local/etc/sudoers
2818 </pre>
2819
2820 <p> but you did want </p>
2821
2822 <pre>
2823     /usr/local/pkgs/sudo-1.5.3/etc/visudo
2824 </pre>
2825
2826 <p> to be <em>grafted</em> as </p>
2827
2828 <pre>
2829     /usr/local/etc/visudo
2830 </pre>
2831
2832 <p> you would create the file </p>
2833
2834 <pre>
2835     /usr/local/pkgs/sudo-1.5.3/etc/.graft-exclude
2836 </pre>
2837
2838 <p> and ensure its contents contained the line: </p>
2839
2840 <pre>
2841     sudoers
2842 </pre>
2843
2844 <p> <strong>NOTE:</strong> Any entries made in a <tt>.graft-exclude</tt> file will
2845 override the same entries made in a <tt>.graft-include</tt> file. That is,
2846 if a file or directory name is listen in both a <tt>.graft-exclude</tt>
2847 and a <tt>.graft-include</tt> file, it will be <strong>excluded</strong> from the
2848 <em>graft</em>. </p>
2849
2850 <hr width="25%">
2851
2852 <h3><a name="config_dirs">Grafting configuration files</a></h3>
2853
2854 <p> Beginning with <em>Graft</em> 2.11 there is now the ability to treat a
2855 package directory as a repository for configuration files. In this case you
2856 would place a <tt>.graft-config</tt> file in the package directory and any
2857 files in that directory would be <strong>copied</strong> to the target
2858 directory. Files in conflict would also be copied but would have a default
2859 suffix of <em>.new</em> to ensure the existing file is not clobbered.
2860 Conflict discovery is achieved using a simple 32-bit CRC check. This
2861 feature has been added to assist operating system distributors manage
2862 system configuration files, specifically it was added at the request of the
2863 maintainer of the <a href="http://www.dragora.org/">Dragora GNU/Linux</a>
2864 distribution. </p>
2865
2866 <p> Consider the following example. You may wish to upgrade the
2867 <em>openssh</em> server as part of an upgrade to your distribution. In
2868 order to preserve any local user modifications to the relevant
2869 configuration files you would add a <tt>.graft-config</tt> file to the
2870 package as follows: </p>
2871
2872 <pre>
2873     /usr/local/pkgs/openssh-server-6.61/etc/default/.graft-config
2874     /usr/local/pkgs/openssh-server-6.61/etc/init.d/.graft-config
2875     /usr/local/pkgs/openssh-server-6.61/etc/init/.graft-config
2876     /usr/local/pkgs/openssh-server-6.61/etc/network/if-up.d/.graft-config
2877     /usr/local/pkgs/openssh-server-6.61/etc/pam.d/.graft-config
2878     /usr/local/pkgs/openssh-server-6.61/etc/ufw/applications.d/.graft-config
2879     /usr/local/pkgs/openssh-server-6.61/lib/systemd/system/.graft-config
2880 </pre>
2881
2882 <p> The other directories in the distribution would not require any control
2883 files. </p>
2884
2885 <p> Imagine that the local administrator has made some changes to
2886 <tt>/etc/pam.d/sshd</tt> such as adding additional authentication methods
2887 to support two-factor authentication for example. As the distribution
2888 maintainer you do not want to reverse this local change so when the local
2889 administrator upgrades the distribution, <em>Graft</em>
2890 <strong>copies</strong> the new <tt>/etc/pam.d/sshd</tt> file to
2891 <tt>/etc/pam.d/sshd.new</tt> which allows the local administrator to merge
2892 their changes with any new features supported by the upgrade. </p>
2893
2894 <p> To take full advantage of this feature you may need to explicitly set the
2895 target directory as follows: </p>
2896
2897 <pre>
2898     graft -i -t / openssh-server-6.61
2899 </pre>
2900
2901 <hr width="25%">
2902
2903 <h3><a name="partial-graft">Grafting part of a package</a></h3>
2904
2905 <p> Some packages can be successfully used when only part of their
2906 installation directory is <em>grafted</em>. Other packages are
2907 recalcitrant and need some special hand holding which can only be
2908 solved by <em>grafting</em> each section of the package separately. </p>
2909
2910 <p> The first scenario can be handled by either <tt>.nograft</tt> files or
2911 partial <em>grafts</em>. Consider <em>Perl</em> version <em>5.18.2</em>.
2912 When installed in its own directory </p>
2913
2914 <pre>
2915     /usr/local/pkgs/perl-5.18.2
2916 </pre>
2917
2918 <p> there are three subdirectories </p>
2919
2920 <pre>
2921     drwxr-sr-x   2 psamuel  bisg         512 Oct 30  1996 bin
2922     drwxr-sr-x   3 psamuel  bisg         512 Oct 30  1996 lib
2923     drwxr-sr-x   4 psamuel  bisg         512 Oct 30  1996 man
2924 </pre>
2925
2926 <p> Everything in the <tt>lib</tt> directory is exclusive to <em>Perl</em>
2927 and does not require <em>grafting</em>. Therefore, <em>perl-5.18.2</em> can
2928 be <em>grafted</em> using either of the following two methods: </p>
2929
2930 <pre>
2931     touch /usr/local/pkgs/perl-5.18.2/lib/.nograft
2932     graft -i perl-5.18.2
2933 </pre>
2934
2935 or
2936
2937 <pre>
2938     graft -it /usr/local/bin perl-5.18.2/bin
2939     graft -it /usr/local/man perl-5.18.2/man
2940 </pre>
2941
2942 <p> Now let's consider a recalcitrant package - <em>ObjectStore</em> version
2943 4.0.2.a.0. When installed in </p>
2944
2945 <pre>
2946     /usr/local/pkgs/ostore-4.0.2.a.0
2947 </pre>
2948
2949 <p> the following files and directories are available: </p>
2950
2951 <pre>
2952     -rwxrwxr-x   1 pauln    one3        1089 Oct 31  1996 Copyright
2953     drwxrwxrwx   8 pauln    one3         512 Oct  2  1996 common
2954     drwxrwxrwx   6 pauln    one3         512 Oct 31  1996 sunpro
2955     -rw-r-----   1 root     one3     1900544 Apr 29  1997 txn.log
2956 </pre>
2957
2958 <p> The executable programs that need to be <em>grafted</em> are in
2959 <tt>sunpro/bin</tt> and the manual pages that need to be <em>grafted</em>
2960 are in <tt>common/man</tt>. Everything else in the package does not
2961 need to be <em>grafted</em>. If the entire package was to be
2962 <em>grafted</em> the result would be two directories that are not in the
2963 regular <strong>$PATH</strong> and <strong>$MANPATH</strong> environment variables - namely
2964 <tt>/usr/local/common/man</tt> and <tt>/usr/local/sunpro/bin</tt>, plus a host of
2965 other directories that are not relevant for <em>grafting</em>. No amount
2966 of <tt>.nograft</tt> and <tt>.graft-exclude</tt> juggling will solve
2967 this problem. </p>
2968
2969 <p> The solution is to use two partial <em>grafts</em>: </p>
2970
2971 <pre>
2972     graft -it /usr/local/bin ostore-4.0.2.a.0/sunpro/bin
2973     graft -it /usr/local/man ostore-4.0.2.a.0/common/bin
2974 </pre>
2975
2976 <p> Using this approach, the correct executables and manual pages are
2977 available without the need to <em>graft</em> unnecessary files and
2978 directories. </p>
2979
2980 <hr width="25%">
2981
2982 <h3><a name="deleting-packages">Deleting and/or Upgrading
2983 Packages</a></h3>
2984
2985 <p> If you wish to upgrade a package - let's assume you wish to upgrade
2986 <em>kermit</em> from version 5A190 to version 6.0.192 - you'd follow
2987 these steps. </p>
2988
2989 <p> Firstly, you'd compile and install <em>kermit-6.0.192</em> in </p>
2990
2991 <pre>
2992     /usr/local/pkgs/kermit-6.0.192
2993 </pre>
2994
2995 <p> Once you'd tested it to your satisfaction, you'd need to delete the
2996 symbolic links to the current <em>grafted</em> version. You can check
2997 which actions <em>Graft</em> will perform by executing: </p>
2998
2999 <pre>
3000     graft -d -n kermit-5A190
3001 </pre>
3002
3003 <p> You'll see output similar to </p>
3004
3005 <pre>
3006     Uninstalling links from /usr/local to /usr/local/pkgs/kermit-5A190
3007     Processing   /usr/local/pkgs/kermit-5A190
3008     Processing   /usr/local/pkgs/kermit-5A190/bin
3009     UNLINK       /usr/local/bin/kermit
3010     UNLINK       /usr/local/bin/wart
3011     Processing   /usr/local/pkgs/kermit-5A190/man
3012     Processing   /usr/local/pkgs/kermit-5A190/man/man1
3013     UNLINK       /usr/local/man/man1/kermit.1
3014     Processing   /usr/local/pkgs/kermit-5A190/doc
3015     UNLINK       /usr/local/doc/ckccfg.doc
3016     UNLINK       /usr/local/doc/ckuins.doc
3017     UNLINK       /usr/local/doc/ckc190.upd
3018     UNLINK       /usr/local/doc/ckcker.upd
3019     UNLINK       /usr/local/doc/ckaaaa.hlp
3020     UNLINK       /usr/local/doc/ckuaaa.hlp
3021     Processing   /usr/local/pkgs/kermit-5A190/lib
3022     UNLINK       /usr/local/lib/ckedemo.ini
3023     UNLINK       /usr/local/lib/ckeracu.ini
3024     UNLINK       /usr/local/lib/ckermit.ini
3025     UNLINK       /usr/local/lib/ckermod.ini
3026     UNLINK       /usr/local/lib/cketest.ini
3027     UNLINK       /usr/local/lib/ckevt.ini
3028     UNLINK       /usr/local/lib/ckurzsz.ini
3029     UNLINK       /usr/local/lib/.testing
3030 </pre>
3031
3032 <p> If you're happy with the output from the test deletion you can delete
3033 the <em>grafted</em> package. Once again, you'll only see output if a
3034 failure occurs unless you use one of the verbose options. </p>
3035
3036 <p> If you execute: </p>
3037
3038 <pre>
3039     graft -dV kermit-5A190
3040 </pre>
3041
3042 <p> you'll see: </p>
3043
3044 <pre>
3045     Uninstalling links from /usr/local to /usr/local/pkgs/kermit-5A190
3046     Processing   /usr/local/pkgs/kermit-5A190
3047     Processing   /usr/local/pkgs/kermit-5A190/bin
3048     UNLINK       /usr/local/bin/kermit
3049     UNLINK       /usr/local/bin/wart
3050     Processing   /usr/local/pkgs/kermit-5A190/man
3051     Processing   /usr/local/pkgs/kermit-5A190/man/man1
3052     UNLINK       /usr/local/man/man1/kermit.1
3053     Processing   /usr/local/pkgs/kermit-5A190/doc
3054     UNLINK       /usr/local/doc/ckccfg.doc
3055     UNLINK       /usr/local/doc/ckuins.doc
3056     UNLINK       /usr/local/doc/ckc190.upd
3057     UNLINK       /usr/local/doc/ckcker.upd
3058     UNLINK       /usr/local/doc/ckaaaa.hlp
3059     UNLINK       /usr/local/doc/ckuaaa.hlp
3060     EMPTY        /usr/local/doc is now empty. Delete manually if necessary.
3061     Processing   /usr/local/pkgs/kermit-5A190/lib
3062     UNLINK       /usr/local/lib/ckedemo.ini
3063     UNLINK       /usr/local/lib/ckeracu.ini
3064     UNLINK       /usr/local/lib/ckermit.ini
3065     UNLINK       /usr/local/lib/ckermod.ini
3066     UNLINK       /usr/local/lib/cketest.ini
3067     UNLINK       /usr/local/lib/ckevt.ini
3068     UNLINK       /usr/local/lib/ckurzsz.ini
3069 </pre>
3070
3071 <p> <strong>NOTE</strong>: In this case the existence of an empty directory has been
3072 discovered. If <em>Graft</em> empties a directory during a package
3073 deletion, it will either notify you or delete the directory depending
3074 on the combination of variables in the <tt>Makefile</tt> and command
3075 line options.  It's probably better practise not to automatically
3076 delete empty directories as they may be used by other packages - such
3077 as lock file directories for example. </p>
3078
3079 <p> Now you can remove the <em>real</em> package contents. (You may not wish
3080 to do this immediately as some legacy systems may depend on features
3081 provided by the older version or you may feel the need for further
3082 testing before feeling confident that the old version can be removed):
3083 </p>
3084
3085 <pre>
3086     rm -rf /usr/local/pkgs/kermit-5A190
3087 </pre>
3088
3089 <p> Now you can <em>graft</em> the new version of <em>kermit</em>. Execute: </p>
3090
3091 <pre>
3092     graft -i -n kermit-6.0.192
3093 </pre>
3094
3095 <p> to ensure that the <em>grafting</em> will proceed without error. Once
3096 you are satisfied that this is the case you can <em>graft</em> the new
3097 package by executing: </p>
3098
3099 <pre>
3100     graft -i kermit-6.0.192
3101 </pre>
3102
3103 <hr width="25%">
3104
3105 <h3><a name="transitioning">Transitioning a package to <em>Graft</em>
3106 control</a></h3>
3107
3108 <p> <em>Graft</em> can be used to easily transition a package from its
3109 current installation in your target directory to a <em>grafted</em>
3110 installation. </p>
3111
3112 <p> As an example, let's consider the package <em>weblint</em> version 1.017.
3113 It consists of three files installed in: </p>
3114
3115 <pre>
3116     /usr/local/bin/weblint
3117     /usr/local/lib/global.weblintrc
3118     /usr/local/man/man1/weblint.1
3119 </pre>
3120
3121 <p> The first step is to create a new copy of the package in its own
3122 directory: </p>
3123
3124 <pre>
3125     /usr/local/pkgs/weblint-1.017
3126 </pre>
3127
3128 <p> Ensure that any references to library files are now made to
3129 <tt>/usr/local/pkgs/weblint-1.017/lib</tt> instead of <tt>/usr/local/lib</tt>.
3130 </p>
3131
3132 <p> Test the new installation to ensure it behaves as expected. </p>
3133
3134 <p> Then prune the old files from <tt>/usr/local/*</tt> using: </p>
3135
3136 <pre>
3137     graft -pV weblint-1.017
3138 </pre>
3139
3140 <p> You'd expect to see output similar to: </p>
3141
3142 <pre>
3143     Pruning      files in /usr/local which conflict with /usr/local/pkgs/weblint-1.017
3144     Processing   /usr/local/pkgs/weblint-1.017
3145     Processing   /usr/local/pkgs/weblint-1.017/man
3146     Processing   /usr/local/pkgs/weblint-1.017/man/man1
3147     RENAME       /usr/local/man/man1/weblint.1
3148     Processing   /usr/local/pkgs/weblint-1.017/bin
3149     RENAME       /usr/local/bin/weblint
3150     Processing   /usr/local/pkgs/weblint-1.017/lib
3151     RENAME       /usr/local/lib/global.weblintrc
3152 </pre>
3153
3154 <p> If you elected to delete conflicting files instead of renaming them
3155 you'd use: </p>
3156
3157 <pre>
3158     graft -pDV weblint-1.017
3159 </pre>
3160
3161 <p> and you'd see output similar to: </p>
3162
3163 <pre>
3164     Pruning      files in /usr/local which conflict with /usr/local/pkgs/weblint-1.017
3165     Processing   /usr/local/pkgs/weblint-1.017
3166     Processing   /usr/local/pkgs/weblint-1.017/man
3167     Processing   /usr/local/pkgs/weblint-1.017/man/man1
3168     UNLINK       /usr/local/man/man1/weblint.1
3169     Processing   /usr/local/pkgs/weblint-1.017/bin
3170     UNLINK       /usr/local/bin/weblint
3171     Processing   /usr/local/pkgs/weblint-1.017/lib
3172     UNLINK       /usr/local/lib/global.weblintrc
3173 </pre>
3174
3175 <p> Now the new version of <em>weblint</em> 1.017 can be <em>grafted</em> in
3176 place: </p>
3177
3178 <pre>
3179     graft -i weblint-1.017
3180 </pre>
3181
3182 <p> The <em>grafted</em> version of <em>weblint</em> can now be tested. </p>
3183
3184 <p> If we renamed conflicting files, they can be removed once the
3185 <em>grafted</em> <em>weblint</em> has been satisfactorily tested: </p>
3186
3187 <pre>
3188     rm /usr/local/man/man1/weblint.1.pruned
3189     rm /usr/local/bin/weblint.pruned
3190     rm /usr/local/lib/global.weblintrc.pruned
3191 </pre>
3192
3193 <hr width="25%">
3194
3195 <h3><a name="conflicts">Conflict Processing</a></h3>
3196
3197 <p> Occasionally <em>Graft</em> will fail to completely install a package. This
3198 occurs because <em>Graft</em> encounters a conflict. A conflict is defined as
3199 one of the following possibilities: </p>
3200
3201 <center>
3202 <table summary="Conflcits" border=2 cellpadding=3>
3203     <tr>
3204         <th>
3205             Package Object
3206         </th>
3207
3208         <th>
3209             Target Object
3210         </th>
3211     </tr>
3212
3213     <tr>
3214         <td>
3215             directory
3216         </td>
3217
3218         <td>
3219             not a directory
3220         </td>
3221     </tr>
3222
3223     <tr>
3224         <td>
3225             file
3226         </td>
3227
3228         <td>
3229             directory
3230         </td>
3231     </tr>
3232
3233     <tr>
3234         <td>
3235             file
3236         </td>
3237
3238         <td>
3239             file
3240         </td>
3241     </tr>
3242
3243     <tr>
3244         <td>
3245             file
3246         </td>
3247
3248         <td>
3249             symbolic link to something other than the package object
3250         </td>
3251     </tr>
3252 </table>
3253 </center>
3254
3255 <p> If <em>Graft</em> encounters such a conflict during the installation of a
3256 package it will report the conflict and exit. </p>
3257
3258 <p> Resolving the conflict depends on the nature of the conflict and is
3259 beyond the scope of this discussion - however most conflicts will
3260 either be the result of attempting to <em>graft</em> a package on top of
3261 the same package actually installed in the target directory or a file
3262 name clash between two (or more) different packages. </p>
3263
3264 <p> Conflicts arising from the pre-existence of a package in the target
3265 directory can be resolved using <em>graft</em>'s prune mechanism
3266 described above in <a href="#transitioning">&quot;Transitioning a
3267 package to <em>Graft</em> control&quot;</a>. </p>
3268
3269 <p> File name clash conflicts can be resolved by the use of either a
3270 <a href="#bypass"><tt>.nograft</tt></a> or
3271 <a href="#exclude"><tt>.graft-exclude</tt></a> file or by
3272 <em>grafting</em> only part of a package as described above in
3273 <a href="#partial-graft">&quot;Grafting part of a package&quot;</a>.
3274 </p>
3275
3276 <p> If <em>Graft</em> encounters a conflict while deleting a package, it will
3277 report the conflict and continue deleting the remainder of the package.
3278 In this way <em>Graft</em> will delete as much of the package as
3279 possible. Conflicts that arise during deletion will probably be the
3280 result of an incorrectly installed package or the installation of other
3281 components of the same package without the use of <em>Graft</em>. </p>
3282
3283 <p> Conflict messages are written to standard error. All other messages
3284 are written to standard output. To quickly determine if a package will
3285 have any conflicts when <em>grafted</em>, redirect standard output to
3286 <tt>/dev/null</tt> </p>
3287
3288 <pre>
3289     graft -i -n <em>package</em> &gt; /dev/null
3290 </pre>
3291
3292 <p> If you don't see any output then you can safely assume that there will
3293 be no conflicts when <em>grafting</em> this package. </p>
3294
3295 <p> See the comprehensive table above describing how
3296 <a href="#precedence">conflicts are handled</a> for more details. </p>
3297
3298 <hr width="25%">
3299
3300 <h3><a name="exitstatus">Exit Status</a></h3>
3301
3302 <p> <em>Graft</em> will terminate with an exit status of either 0, 1, 2, 3 or 4
3303 under the following conditions: </p>
3304
3305 <center>
3306 <table summary="Exit Status" border=2 cellpadding=3>
3307     <tr>
3308         <th>
3309             Exit Status
3310         </th>
3311
3312         <th>
3313             Condition
3314         </th>
3315     </tr>
3316
3317     <tr>
3318         <td>
3319             <center>
3320             <strong>0</strong>
3321             </center>
3322         </td>
3323
3324         <td>
3325             All operations succeeded.
3326         </td>
3327     </tr>
3328
3329     <tr>
3330         <td>
3331             <center>
3332             <strong>1</strong>
3333             </center>
3334         </td>
3335
3336         <td>
3337             A conflict occurred during installation.
3338         </td>
3339     </tr>
3340
3341     <tr>
3342         <td>
3343             <center>
3344             <strong>2</strong>
3345             </center>
3346         </td>
3347
3348         <td>
3349             Command line syntax was incorrect.
3350         </td>
3351     </tr>
3352
3353     <tr>
3354         <td>
3355             <center>
3356             <strong>3</strong>
3357             </center>
3358         </td>
3359
3360         <td>
3361             One or more packages listed on the command line does not
3362             exist. Other valid packages listed on the command line were
3363             processed correctly.
3364         </td>
3365     </tr>
3366
3367     <tr>
3368         <td>
3369             <center>
3370             <strong>4</strong>
3371             </center>
3372         </td>
3373
3374         <td>
3375             The log file <tt>/var/log/graft</tt> could not be updated. Usually a
3376             result of a permission error. Any other error condition will
3377             override this condition.
3378         </td>
3379     </tr>
3380 </table>
3381 </center>
3382
3383 <hr>
3384
3385 <h2><a name="other-pkg-tools">Using <em>Graft</em> with other package
3386 management tools</a></h2>
3387
3388 <p> Most Unix vendors have released their own package management tools with
3389 their operating systems. Examples of this are Solaris 2.<em>x</em> with its
3390 <em>SVR4 Package Manager</em> <tt>pkgadd</tt>, RedHat Linux with its
3391 <em>RedHat Package Manager</em> <tt>rpm</tt>, Ubuntu Linux (and other Debian
3392 Linux derivatives) with its <tt>dpkg</tt> system and HP-UX 10.<em>x</em> with
3393 its <tt>swinstall</tt> suite. <em>Graft</em> has been designed as an adjunct
3394 to these package managers rather than a competitor. The author has used
3395 <em>Graft</em> successfully with all of the operating systems mentioned here.
3396 </p>
3397
3398 <ul>
3399
3400     <li> <p> Many useful packages available in the public domain and from
3401     other commercial sources are not shipped with most flavours of
3402     Unix. <em>Graft</em> can be used to maintain a rich package
3403     environment beyond the set of packages provided by your vendor.
3404     Vendor based packages can still be maintained using the vendor's
3405     tools and <em>Graft</em> can be used to maintain your own packages.
3406     </p>
3407
3408     <li> <p> The vendor based management tools are usually used to maintain
3409     single instances of a package on each machine. It is often
3410     difficult to have multiple versions of the same package coexisting
3411     on the same machine. <em>Graft</em> can be used to maintain multiple
3412     versions of a package to support legacy, production and development
3413     requirements simultaneously. </p>
3414
3415     <li> <p> Another common problem with vendor supplied software is
3416     the speed at which upgrades are available. The large vendors are not
3417     known for providing quick fixes to many of their packages. (Notable
3418     exceptions to this are the vendors of operating systems based on
3419     open source software who can draw on the enormous number of users
3420     who submit patches because the source code is available). Using
3421     <em>Graft</em> you can obtain a working public domain version of
3422     a package (if one exists of course) and install it in a different
3423     location to the vendor copy. When the vendor releases a new version of
3424     the package, it can be installed using the vendor's package management
3425     tool and your <em>grafted</em> copy can be removed (only if the vendor's
3426     version of the package is better than the public domain version). </p>
3427
3428     <li> <p> Sometimes, a vendor's package doesn't quite perform in the
3429     manner you'd like. It may be making assumptions about your file
3430     system(s) that are incorrect for your environment or it may not
3431     have all the features you'd like. If an alternative package is
3432     available - either in the public domain or from other commercial
3433     sources - it can be installed and <em>grafted</em> accordingly. </p>
3434
3435 </ul>
3436
3437 <hr>
3438
3439 <h2><a name="availability">Availability</a></h2>
3440
3441 <p> The latest version of <em>Graft</em> should always be available from: </p>
3442
3443 <pre>
3444     <a href="http://peters.gormand.com.au/Home/tools/graft">http://peters.gormand.com.au/Home/tools/graft</a>
3445 </pre>
3446
3447 <hr>
3448
3449 <h2><a name="license">License</a></h2>
3450
3451 <p> <em>Graft</em> is licensed under the terms of the GNU General Public
3452 License, Version 2, June 1991. </p>
3453
3454 <p> You should have received a copy of the GNU General Public License
3455 along with this program; if not, write to the Free Software Foundation,
3456 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA, or download
3457 it from the Free Software Foundation's web site: </p>
3458
3459 <pre>
3460     <a href="http://www.gnu.org/copyleft/gpl.html">http://www.gnu.org/copyleft/gpl.html</a>
3461     <a href="http://www.gnu.org/copyleft/gpl.txt">http://www.gnu.org/copyleft/gpl.txt</a>
3462 </pre>
3463
3464
3465 <hr>
3466
3467 </body>
3468 </html>