website: start adding content to the manual
[dragora.git] / website / manual / en / graft.html
blob281bbb4a82624e01057e99c74ab00736039cb7ea
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>
7 <body>
9 <center>
10 <h1><em>Graft</em> - a package management utility</h1>
11 </center>
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>
16 <h4>$Revision: 2.16 $</h4>
17 <h4>$Date: 2018/04/16 14:54:07 $</h4>
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>
27 <hr>
29 <h2><a name="contents">Contents</a></h2>
31 <ul>
33 <li> <a href="#intro">Introduction</a>
35 <li> <a href="#rationale">Rationale</a>
37 <li> <a href="#research">Research</a>
39 <li> <a href="#design">Design</a>
41 <ul>
42 <li> <a href="#precedence">Control file precedence &amp; conflict resolution</a>
43 </ul>
45 <li> <a href="#history">History</a>
47 <li> <a href="#installation">Installation</a>
49 <ul>
50 <li> <a href="#rpm_and_deb">Creating RPM and DEB packages</a>
52 <li> <a href="#gotchas">Grafting <em>Graft</em> and
53 <em>Perl</em> - the bootstrap problem</a>
54 </ul>
56 <li> <a href="#using-graft">Using <em>Graft</em></a>
58 <ul>
60 <li> <a href="#compiling-packages">Compiling
61 Packages</a>
63 <li><a href="#usage"><em>Graft</em> command line
64 options</a>
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>
73 <li> <a href="#testing">Testing the <em>Graft</em>
74 Installation</a>
76 <li> <a href="#installing-packages">Installing
77 Packages</a>
79 <li> <a href="#bypass">Bypassing package
80 directories</a>
82 <li> <a href="#include">Including specific files
83 and/or directories</a>
85 <li> <a href="#exclude">Excluding specific files
86 and/or directories</a>
88 <li> <a href="#config_dirs">Grafting configuration files</a>
90 <li><a href="#partial-graft">Grafting part of a
91 package</a>
93 <li> <a href="#deleting-packages">Deleting and/or
94 Upgrading Packages</a>
96 <li><a href="#transitioning">Transitioning a package to
97 <em>Graft</em> control</a>
99 <li> <a href="#conflicts">Conflict Processing</a>
101 <li> <a href="#exitstatus">Exit Status</a>
103 </ul>
105 <li> <a href="#other-pkg-tools">Using <em>Graft</em> with
106 other package management tools</a>
108 <li> <a href="#availability">Availability</a>
110 <li> <a href="#license">License</a>
112 </ul>
114 <hr>
116 <h2><a name="intro">Introduction</a></h2>
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>
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>
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>
134 <hr>
136 <h2><a name="rationale">Rationale</a></h2>
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>
142 <ol>
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>
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>
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>
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>
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>
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>
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>
180 <li> <p> A combination of methods (1) and (2). </p>
182 </ol>
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>
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>
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>
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>
207 <hr>
209 <h2><a name="research">Research</a></h2>
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>
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>
220 <dl>
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>
225 <dd> <p> <em>Depot</em> is very flexible yet cumbersome. </p>
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>
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>
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>
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>
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>
257 <dt> <em>Stow</em>
258 <a href="https://www.gnu.org/software/stow/">https://www.gnu.org/software/stow/</a>
260 <dd> <p> <em>Stow</em> is a stateless system. It requires no
261 database or configuration information. </p>
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>
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>
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>
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>
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>
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>
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>
319 </dl>
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>
324 <dl>
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>
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>
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>
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>
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>
353 </dl>
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>
362 <dl>
364 <dt> <em>stowES</em>
366 <dd>
368 <pre>
369 <a href="https://os.inf.tu-dresden.de/~adam/stowES/">https://os.inf.tu-dresden.de/~adam/stowES/</a>
370 </pre>
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>
380 <dt> <em>opt_depot</em>
382 <dd>
384 <pre>
385 <a href="https://github.com/jonabbey/opt_depot">https://github.com/jonabbey/opt_depot</a>
386 </pre>
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>
398 <p> This site also has links to several other package
399 management utilities, including <em>Graft</em>. </p>
401 <dt> <em>relink</em>
403 <dd>
405 <pre>
406 <a href="http://sourceforge.net/projects/relink/">http://sourceforge.net/projects/relink/</a>
407 </pre>
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>
416 <dt> <em>univSrcPkg</em>
418 <dd>
420 <pre>
421 <a href="http://freecode.com/articles/the-universal-source-package">http://freecode.com/articles/the-universal-source-package</a>
422 </pre>
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>
428 <p> This site also has links to other package management
429 programs and similar items of interest. </p>
431 </dl>
433 <hr>
435 <h2><a name="design">Design</a></h2>
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>
442 <ul>
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>
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>
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>
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>
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>
468 <ul>
470 <li> If the package object is a directory and the
471 target object exists but is not a directory.
473 <li> If the package object is not a directory and the
474 target object exists and is not a symbolic link.
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.
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.
484 </ul>
486 <li> <p> Installation conflicts will always be reported. Conflicts
487 will be reported to standard error. </p>
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>
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>
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>
507 <li> <p> Deletion conflicts will always be reported. Conflicts
508 will be reported to standard error. </p>
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>
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>
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>
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>
534 <p> The <tt>.nograft</tt> file takes priority over the
535 <tt>.graft-exclude</tt> file. </p>
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>
546 <p> The <tt>.graft-exclude</tt> file takes priority over the
547 <tt>.graft-include</tt> file. </p>
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>
556 <p> The <tt>.graft-include</tt> file takes priority over the
557 <tt>.graft-config</tt> file. </p>
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>
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>
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>
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>
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>
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>
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>
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>
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>
606 </ul>
608 <h3><a name="precedence">Control file precedence &amp; conflict resolution</a></h3>
610 <p> As stated above, the various <em>Graft</em> control files have the
611 following precedence, from highest to lowest: </p>
613 <pre>
614 .nograft &gt; .graft-exclude &gt; .graft-include &gt; .graft-config
615 </pre>
617 <p> The following table summarises the activities of <em>Graft</em> when
618 various control files are present: </p>
620 <center>
621 <table summary="Control File Precedence" border=2 cellpadding=3>
622 <tr>
623 <th colspan=5>
624 Install
625 </th>
626 </tr>
628 <tr>
629 <th>
630 <em>Target</em>
631 </th>
633 <th>
634 <em>.nograft</em>
635 </th>
637 <th>
638 <em>.graft-exclude</em>
639 </th>
641 <th>
642 <em>.graft-include</em>
643 </th>
645 <th>
646 <em>.graft-config</em>
647 </th>
648 </tr>
650 <tr>
651 <td>
652 does not exist
653 </td>
655 <td>
656 IGNORE
657 </td>
659 <td>
660 IGNORE
661 </td>
663 <td>
664 SYMLINK
665 </td>
667 <td>
668 COPY
669 </td>
670 </tr>
672 <tr>
673 <td>
674 symlink to source
675 </td>
677 <td>
678 IGNORE
679 </td>
681 <td>
682 IGNORE
683 </td>
685 <td>
687 </td>
689 <td>
690 DELETE &amp; COPY
691 </td>
692 </tr>
694 <tr>
695 <td>
696 symlink to other
697 </td>
699 <td>
700 IGNORE
701 </td>
703 <td>
704 IGNORE
705 </td>
707 <td>
708 CONFLICT
709 </td>
711 <td>
713 </td>
714 </tr>
716 <tr>
717 <td>
718 symlink to other (crc match)
719 </td>
721 <td>
723 </td>
725 <td>
727 </td>
729 <td>
731 </td>
733 <td>
735 </td>
736 </tr>
738 <tr>
739 <td>
740 symlink to other (crc diff)
741 </td>
743 <td>
745 </td>
747 <td>
749 </td>
751 <td>
753 </td>
755 <td>
756 COPY.new
757 </td>
758 </tr>
760 <tr>
761 <td>
762 file
763 </td>
765 <td>
766 IGNORE
767 </td>
769 <td>
770 IGNORE
771 </td>
773 <td>
774 CONFLICT
775 </td>
777 <td>
779 </td>
780 </tr>
782 <tr>
783 <td>
784 file (crc match)
785 </td>
787 <td>
789 </td>
791 <td>
793 </td>
795 <td>
797 </td>
799 <td>
801 </td>
802 </tr>
804 <tr>
805 <td>
806 file (crc diff)
807 </td>
809 <td>
811 </td>
813 <td>
815 </td>
817 <td>
819 </td>
821 <td>
822 COPY.new
823 </td>
824 </tr>
826 <tr>
827 <td>
828 not a file
829 </td>
831 <td>
832 IGNORE
833 </td>
835 <td>
836 IGNORE
837 </td>
839 <td>
840 CONFLICT
841 </td>
843 <td>
844 CONFLICT
845 </td>
846 </tr>
848 <tr>
849 <th colspan=5>
850 Delete
851 </th>
852 </tr>
854 <tr>
855 <th>
856 <em>Target</em>
857 </th>
859 <th>
860 <em>.nograft</em>
861 </th>
863 <th>
864 <em>.graft-exclude</em>
865 </th>
867 <th>
868 <em>.graft-include</em>
869 </th>
871 <th>
872 <em>.graft-config</em>
873 </th>
874 </tr>
876 <tr>
877 <td>
878 does not exist
879 </td>
881 <td>
883 </td>
885 <td>
887 </td>
889 <td>
891 </td>
893 <td>
895 </td>
896 </tr>
898 <tr>
899 <td>
900 symlink to source
901 </td>
903 <td>
904 DELETE
905 </td>
907 <td>
908 DELETE
909 </td>
911 <td>
912 DELETE
913 </td>
915 <td>
916 DELETE &amp; DELETE.new
917 </td>
918 </tr>
920 <tr>
921 <td>
922 symlink to other
923 </td>
925 <td>
926 CONFLICT
927 </td>
929 <td>
930 CONFLICT
931 </td>
933 <td>
934 CONFLICT
935 </td>
937 <td>
939 </td>
940 </tr>
942 <tr>
943 <td>
944 symlink to other (crc match)
945 </td>
947 <td>
949 </td>
951 <td>
953 </td>
955 <td>
957 </td>
959 <td>
960 DELETE.new
961 </td>
962 </tr>
964 <tr>
965 <td>
966 symlink to other (crc diff)
967 </td>
969 <td>
971 </td>
973 <td>
975 </td>
977 <td>
979 </td>
981 <td>
983 </td>
984 </tr>
986 <tr>
987 <td>
988 file
989 </td>
991 <td>
992 NOTE
993 </td>
995 <td>
996 NOTE
997 </td>
999 <td>
1000 CONFLICT
1001 </td>
1003 <td>
1005 </td>
1006 </tr>
1008 <tr>
1009 <td>
1010 file (crc match)
1011 </td>
1013 <td>
1015 </td>
1017 <td>
1019 </td>
1021 <td>
1023 </td>
1025 <td>
1026 DELETE.new
1027 </td>
1028 </tr>
1030 <tr>
1031 <td>
1032 file (crc diff)
1033 </td>
1035 <td>
1037 </td>
1039 <td>
1041 </td>
1043 <td>
1045 </td>
1047 <td>
1049 </td>
1050 </tr>
1052 <tr>
1053 <td>
1054 not a file
1055 </td>
1057 <td>
1058 CONFLICT
1059 </td>
1061 <td>
1062 CONFLICT
1063 </td>
1065 <td>
1066 CONFLICT
1067 </td>
1069 <td>
1070 CONFLICT
1071 </td>
1072 </tr>
1074 <tr>
1075 <th colspan=5>
1076 Prune
1077 </th>
1078 </tr>
1080 <tr>
1081 <th>
1082 <em>Target</em>
1083 </th>
1085 <th>
1086 <em>.nograft</em>
1087 </th>
1089 <th>
1090 <em>.graft-exclude</em>
1091 </th>
1093 <th>
1094 <em>.graft-include</em>
1095 </th>
1097 <th>
1098 <em>.graft-config</em>
1099 </th>
1100 </tr>
1102 <tr>
1103 <td>
1104 does not exist
1105 </td>
1107 <td>
1109 </td>
1111 <td>
1113 </td>
1115 <td>
1117 </td>
1119 <td>
1121 </td>
1122 </tr>
1124 <tr>
1125 <td>
1126 symlink to source
1127 </td>
1129 <td>
1131 </td>
1133 <td>
1135 </td>
1137 <td>
1139 </td>
1141 <td>
1143 </td>
1144 </tr>
1146 <tr>
1147 <td>
1148 symlink to other
1149 </td>
1151 <td>
1152 PRUNE
1153 </td>
1155 <td>
1156 PRUNE
1157 </td>
1159 <td>
1160 PRUNE
1161 </td>
1163 <td>
1165 </td>
1166 </tr>
1168 <tr>
1169 <td>
1170 file
1171 </td>
1173 <td>
1174 PRUNE
1175 </td>
1177 <td>
1178 PRUNE
1179 </td>
1181 <td>
1182 PRUNE
1183 </td>
1185 <td>
1187 </td>
1188 </tr>
1190 <tr>
1191 <td>
1192 not a file
1193 </td>
1195 <td>
1196 PRUNE
1197 </td>
1199 <td>
1200 PRUNE
1201 </td>
1203 <td>
1204 PRUNE
1205 </td>
1207 <td>
1209 </td>
1210 </tr>
1211 </table>
1212 </center>
1214 <hr>
1216 <h2><a name="history">History</a></h2>
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>
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>
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>
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>
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>
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>
1258 <hr>
1260 <h2><a name="installation">Installation</a></h2>
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>
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>
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>
1281 <p> If this is the case you'll see compile failures for the following modules
1282 if they are unavailable: </p>
1284 <pre>
1285 File::Basename
1286 Getopt::Long
1287 </pre>
1289 <p> You will not be able to install <em>Graft</em> until these modules are
1290 available. </p>
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>
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>
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>
1304 <p> Follow these instructions to install <em>Graft</em>: </p>
1306 <ol>
1308 <li> <p> Unpack the gzipped <em>Graft</em> distribution: </p>
1310 <pre>
1311 gunzip -c graft-2.16.tar.gz | tar xvf -
1312 </pre>
1314 <li> <p> change directories to the <em>Graft</em> distribution
1315 directory: </p>
1317 <pre>
1318 cd graft-2.16
1319 </pre>
1321 <li> <p> Create an writable version of the <tt>Makefile</tt> by
1322 running the command </p>
1324 <pre>
1325 make -f Makefile.dist
1326 </pre>
1328 <p> You'll see output similar to </p>
1330 <pre>
1331 cp Makefile.dist Makefile
1332 chmod 644 Makefile
1334 ######################################################
1336 # You'll now need to modify the Makefile #
1337 # variables to suit your local conditions. #
1339 ######################################################
1341 make: *** [Makefile] Error 1
1342 </pre>
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>
1349 <li> <p> Edit the <tt>Makefile</tt>. The following variables should be
1350 modified to suit your local requirements: </p>
1352 <dl>
1354 <dt>
1355 <pre>
1356 <strong>PACKAGEDIR</strong> = /usr/local/pkgs
1357 <strong>TARGETDIR</strong> = /usr/local
1358 </pre>
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>
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>
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>
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>
1397 <dt>
1398 <pre>
1399 <strong>PERL</strong> = /usr/bin/perl
1400 </pre>
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>
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>
1419 <dt>
1420 <pre>
1421 <strong>BUILDPERL</strong> = $(PERL)
1422 </pre>
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>
1430 <dt>
1431 <pre>
1432 <strong>LOGFILE</strong> = /var/log/graft
1433 </pre>
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>
1440 <p> If you want logging disabled by default, set the
1441 value of <strong>LOGFILE</strong> to <tt>/dev/null</tt>. </p>
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>
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>
1459 <dt>
1460 <pre>
1461 <strong>GRAFT-NEVER</strong> =
1462 </pre>
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>
1473 <pre>
1474 GRAFT-NEVER = CVS RCS SCCS .lock
1475 </pre>
1477 <dt>
1478 <pre>
1479 <strong>NEVERGRAFT</strong> = 0
1480 </pre>
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>
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>
1492 <p> The sense of this value is reversed by use of
1493 the <strong>-C</strong> command line option.
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>
1500 <dt>
1501 <pre>
1502 <strong>PRUNED-SUFFIX</strong> = .pruned
1503 </pre>
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>
1509 <dt>
1510 <pre>
1511 <strong>CONFIG-SUFFIX</strong> = .new
1512 </pre>
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>
1520 <dt>
1521 <pre>
1522 <strong>SUPERUSER</strong> = 1
1523 </pre>
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>
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>
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>
1543 <dt>
1544 <pre>
1545 <strong>PRESERVEPERMS</strong> = 0
1546 </pre>
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>
1558 <dt>
1559 <pre>
1560 <strong>DELETEOBJECTS</strong> = 0
1561 </pre>
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>
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>
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>
1591 </dl>
1593 <p> Save your changes and exit from the editor. </p>
1595 <li> <p> Remove any existing executables by running: </p>
1597 <pre>
1598 make clean
1599 </pre>
1601 <p> You should see output similar to: </p>
1603 <pre>
1604 rm -f graft
1605 </pre>
1607 <li> <p> Create the <em>Graft</em> executable by running: </p>
1609 <pre>
1610 make
1611 </pre>
1613 <p> You should see output similar to: </p>
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>
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>
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>
1676 <pre>
1677 * nfshost:/export/sparc-SunOS-5.5.1/usr/local/&amp;
1678 </pre>
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>
1684 <pre>
1685 mkdir /export/sparc-SunOS-5.5.1/usr/local/pkgs/graft-2.16
1686 </pre>
1688 <li> <p> Install the <em>Graft</em> executable, manual page and
1689 documentation by executing: </p>
1691 <pre>
1692 make install
1693 </pre>
1695 <p> You should see output similar to: </p>
1697 <pre>
1698 mkdir -p /usr/local/pkgs/graft-2.16/bin
1699 cp graft /usr/local/pkgs/graft-2.16/bin
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
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>
1719 </ol>
1721 <p> <em>Graft</em> is now installed and ready to be used. </p>
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>
1726 <pre>
1727 make clean
1728 make install
1729 </pre>
1731 <p> Failure to do this may result in a <em>Graft</em> manual page that does
1732 NOT reflect your current configuration. </p>
1734 <h3><a name="rpm_and_deb">Creating RPM and DEB packages</a></h3>
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>
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>
1745 <pre>
1746 make rpm
1747 </pre>
1749 <p> or </p>
1751 <pre>
1752 make deb
1753 </pre>
1755 <p> The creation of these packages is somewhat experimental. Please let the
1756 author know if you have issues. </p>
1758 <hr>
1760 <h3><a name="gotchas">Grafting <em>Graft</em> and <em>Perl</em> - the
1761 bootstrap problem</a></h3>
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>
1767 <p> <strong>However if you are a creator of an operating system
1768 distribution then this section may be relevant.</strong> </p>
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>
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>
1781 <p> Assuming that <em>Graft</em> and <em>Perl</em> are installed in </p>
1783 <pre>
1784 /usr/local/pkgs/graft-2.16
1785 /usr/local/pkgs/perl-5.18.2
1786 </pre>
1788 <p> you can resolve this dilemma by executing the following commands:
1789 </p>
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>
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>
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>
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>
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>
1815 <pre>
1816 graft -i <em>package</em>
1817 </pre>
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>
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>
1830 <hr>
1832 <h2><a name="using-graft">Using <em>Graft</em></a></h2>
1834 <h3><a name="compiling-packages">Compiling Packages</a></h3>
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>
1846 <hr width="25%">
1848 <h3><a name="usage"><em>Graft</em> command line options</a></h3>
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>
1855 <p> <em>Graft</em>'s command line options can be summarised as: </p>
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>
1864 <p> <em>Graft</em> has four basic actions: </p>
1866 <ol>
1868 <li> <p> <a name="graft-i"><strong>Install</strong></a> </p>
1870 <pre>
1871 graft -i [-C] [-P|u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
1872 </pre>
1874 <dl>
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>
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>
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>
1898 <p> Can only be used with the -i option. </p>
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>
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>
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>
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>
1929 <p> Cannot be used with the <strong>-u</strong> option. </p>
1931 <p> This option will be silently ignored if the
1932 effective user of <em>Graft</em> is not root. </p>
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>
1942 <dt> <strong>-u</strong>
1943 <dd>
1944 <p> Superuser privileges are not required when
1945 installing packages. </p>
1947 <p> Cannot be used with the <strong>-P</strong> option. </p>
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>
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>
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>
1968 <p> Log entries have the form: </p>
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>
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>
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>
1995 <dt> <strong>-v</strong>
1996 <dd>
1997 <p> Be verbose. </p>
1999 <dt> <strong>-V</strong>
2000 <dd>
2001 <p> Be very verbose. </p>
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>
2010 <p> Can only be used by the superuser. </p>
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>
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>
2025 <pre>
2026 /usr/local/depot/gzip-1.2.4
2027 </pre>
2029 <p> the package will be <em>grafted</em> into
2030 </p>
2032 <pre>
2033 /usr/local
2034 </pre>
2036 <p> Cannot be used with the <strong>-t</strong> option. </p>
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>
2045 <p> Cannot be used with the <strong>-s</strong> option. </p>
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>
2057 </dl>
2059 <hr width="10%">
2061 <li> <p> <a name="graft-d"><strong>Delete</strong></a> </p>
2063 <pre>
2064 graft -d [-D] [-u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
2065 </pre>
2067 <dl>
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>
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>
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>
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>
2096 <dt> <strong>-u</strong>
2097 <dd>
2098 <p> Superuser privileges are not required when
2099 deleting packages. </p>
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>
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>
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>
2120 <p> Log entries have the form: </p>
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>
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>
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>
2145 <dt> <strong>-v</strong>
2146 <dd>
2147 <p> Be verbose. </p>
2149 <dt> <strong>-V</strong>
2150 <dd>
2151 <p> Be very verbose. </p>
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>
2160 <p> Can only be used by the superuser. </p>
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>
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>
2175 <pre>
2176 /usr/local/depot/gzip-1.2.4
2177 </pre>
2179 <p> the package will be <em>grafted</em> into
2180 </p>
2182 <pre>
2183 /usr/local
2184 </pre>
2186 <p> Cannot be used with the <strong>-t</strong> option. </p>
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>
2195 <p> Cannot be used with the <strong>-s</strong> option. </p>
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>
2207 </dl>
2209 <hr width="10%">
2211 <li> <p> <a name="graft-p"><strong>Prune</strong></a> </p>
2213 <pre>
2214 graft -p [-D] [-u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
2215 </pre>
2217 <dl>
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>
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>
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>
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>
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>
2253 <dt> <strong>-u</strong>
2254 <dd>
2255 <p> Superuser privileges are not required when
2256 pruning packages. </p>
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>
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>
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>
2277 <p> Log entries have the form: </p>
2279 <pre>
2280 879126283 1.10+ P /usr/local/pkgs/weblint-1.017 /usr/local
2281 </pre>
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>
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>
2295 <dt> <strong>-v</strong>
2296 <dd>
2297 <p> Be verbose. </p>
2299 <dt> <strong>-V</strong>
2300 <dd>
2301 <p> Be very verbose. </p>
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>
2310 <p> Can only be used by the superuser. </p>
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>
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>
2325 <pre>
2326 /usr/local/depot/gzip-1.2.4
2327 </pre>
2329 <p> the package will be <em>grafted</em> into
2330 </p>
2332 <pre>
2333 /usr/local
2334 </pre>
2336 <p> Cannot be used with the <strong>-t</strong> option. </p>
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>
2345 <p> Cannot be used with the <strong>-s</strong> option. </p>
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>
2357 </dl>
2359 <li> <p> <a name="graft-L"><strong>Information</strong></a> </p>
2361 <pre>
2362 graft -L
2363 </pre>
2365 <dl>
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>
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>
2386 <p> You can set these environment variables using
2387 one of the following methods. </p>
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>
2394 </dl>
2396 </ol>
2398 <hr width="25%">
2400 <h3><a name="testing">Testing the <em>Graft</em> Installation</a></h3>
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>
2406 <pre>
2407 graft -i -n <em>package-name</em>
2408 </pre>
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>
2418 <p> <em>Graft</em> will report on the following actions: </p>
2420 <ul>
2422 <li> <p> Installing links to <em>package-location</em> in
2423 <em>package-target</em> </p>
2425 <p> Indicates the real package location and its <em>grafted</em>
2426 target. </p>
2428 <li> <p> Processing <em>package-directory</em> </p>
2430 <p> Indicates which package directory is being processed. </p>
2432 <li> <p> MKDIR <em>dirname</em> </p>
2434 <p> This destination directory will be created. </p>
2436 <li> <p> SYMLINK <em>dest-package-file</em> -&gt; <em>package-file</em>
2437 </p>
2439 <p> This symbolic link will be created. </p>
2441 <li> <p> NOP <em>string</em> </p>
2443 <p> No action was necessary for this package object. </p>
2445 <li> <p> BYPASS <em>dirname</em> - .nograft file found</p>
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>
2451 <li> <p> READING include file
2452 <em>package-dir</em><tt>/.graft-include</tt> </p>
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>
2460 <li> <p> INCLUDE file <em>package-file</em> - listed in
2461 <em>package-dir</em><tt>/.graft-include</tt> </p>
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>
2467 <li> <p> IGNORE file <em>package-file</em> - not listed in
2468 <em>package-dir</em><tt>/.graft-include</tt> </p>
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>
2474 <li> <p> INCLUDE directory <em>package-directory</em> - listed in
2475 <em>package-dir</em><tt>/.graft-include</tt> </p>
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>
2482 <li> <p> IGNORE directory <em>package-file</em> - not listed in
2483 <em>package-dir</em><tt>/.graft-include</tt> </p>
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>
2490 <li> <p> READING exclude file
2491 <em>package-dir</em><tt>/.graft-exclude</tt> </p>
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>
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>
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>
2509 <li> <p> EXCLUDE file <em>package-file</em> - listed in
2510 <em>package-dir</em><tt>/.graft-exclude</tt> </p>
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>
2516 <li> <p> EXCLUDE directory <em>package-directory</em> - listed in
2517 <em>package-dir</em><tt>/.graft-exclude</tt> </p>
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>
2524 <li> <p> CONFLICT <em>message</em> </p>
2526 <p> <em>Graft</em> could not successfully process a package object.
2527 One of the following conditions was encountered: </p>
2529 <ul>
2531 <li> The package object is a directory and the
2532 target object exists but it not a directory.
2534 <li> The package object is not a directory and the
2535 target object exists and is not a symbolic
2536 link.
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.
2542 </ul>
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>
2548 <pre>
2549 graft -i -n <em>package-name</em> &gt; /dev/null
2550 </pre>
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>
2557 </ul>
2559 <p> If you were to test the installation of the <em>kermit-5A190</em>
2560 package you would execute the command: </p>
2562 <pre>
2563 graft -i -n kermit-5A190
2564 </pre>
2566 You should see output resembling:
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>
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>
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>
2615 <hr width="25%">
2617 <h3><a name="installing-packages">Installing Packages</a></h3>
2619 <p> Once you have ensured that <em>Graft</em> will perform the correct
2620 actions, you can execute: </p>
2622 <pre>
2623 graft -i <em>package-name</em>
2624 </pre>
2626 <p> So to install <em>kermit</em> you would execute: </p>
2628 <pre>
2629 graft -i kermit-5A190
2630 </pre>
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>
2636 <pre>
2637 graft -i -v kermit-5A190
2638 </pre>
2640 <p> You should see the following output: </p>
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>
2651 <p> If you choose the very verbose option by executing: </p>
2653 <pre>
2654 graft -i -V kermit-5A190
2655 </pre>
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>
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>
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>
2698 <hr width="25%">
2700 <h3><a name="bypass">Bypassing package directories</a></h3>
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>
2705 <ul>
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>
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>
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>
2721 </ul>
2723 <p> You can force <em>Graft</em> to bypass a directory by creating the file </p>
2725 <pre>
2726 <em>package-name/dir/dir/</em>.nograft
2727 </pre>
2729 <p> Using the second example above, if you were to create the file: </p>
2731 <pre>
2732 /usr/local/pkgs/perl-5.18.2/lib/perl5/.nograft
2733 </pre>
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>
2739 <hr width="25%">
2741 <h3><a name="include">Including specific files and/or directories</a></h3>
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>
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>
2752 <pre>
2753 .graft-include
2754 </pre>
2756 <p> in the same directory. </p>
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>
2761 <p> Consider the <em>a2ps</em> package for example. When installed it
2762 contains the following directories: </p>
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>
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>
2780 <pre>
2782 </pre>
2784 <p> Now only the <tt>bin</tt> directory will be <em>grafted</em>. </p>
2786 <hr width="25%">
2788 <h3><a name="exclude">Excluding specific files and/or directories</a></h3>
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>
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>
2799 <pre>
2800 .graft-exclude
2801 </pre>
2803 <p> in the same directory. </p>
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>
2808 <p> For example, if you did not wish the file </p>
2810 <pre>
2811 /usr/local/pkgs/sudo-1.5.3/etc/sudoers
2812 </pre>
2814 <p> to be <em>grafted</em> as </p>
2816 <pre>
2817 /usr/local/etc/sudoers
2818 </pre>
2820 <p> but you did want </p>
2822 <pre>
2823 /usr/local/pkgs/sudo-1.5.3/etc/visudo
2824 </pre>
2826 <p> to be <em>grafted</em> as </p>
2828 <pre>
2829 /usr/local/etc/visudo
2830 </pre>
2832 <p> you would create the file </p>
2834 <pre>
2835 /usr/local/pkgs/sudo-1.5.3/etc/.graft-exclude
2836 </pre>
2838 <p> and ensure its contents contained the line: </p>
2840 <pre>
2841 sudoers
2842 </pre>
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>
2850 <hr width="25%">
2852 <h3><a name="config_dirs">Grafting configuration files</a></h3>
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>
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>
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>
2882 <p> The other directories in the distribution would not require any control
2883 files. </p>
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>
2894 <p> To take full advantage of this feature you may need to explicitly set the
2895 target directory as follows: </p>
2897 <pre>
2898 graft -i -t / openssh-server-6.61
2899 </pre>
2901 <hr width="25%">
2903 <h3><a name="partial-graft">Grafting part of a package</a></h3>
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>
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>
2914 <pre>
2915 /usr/local/pkgs/perl-5.18.2
2916 </pre>
2918 <p> there are three subdirectories </p>
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>
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>
2930 <pre>
2931 touch /usr/local/pkgs/perl-5.18.2/lib/.nograft
2932 graft -i perl-5.18.2
2933 </pre>
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>
2942 <p> Now let's consider a recalcitrant package - <em>ObjectStore</em> version
2943 4.0.2.a.0. When installed in </p>
2945 <pre>
2946 /usr/local/pkgs/ostore-4.0.2.a.0
2947 </pre>
2949 <p> the following files and directories are available: </p>
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>
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>
2969 <p> The solution is to use two partial <em>grafts</em>: </p>
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>
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>
2980 <hr width="25%">
2982 <h3><a name="deleting-packages">Deleting and/or Upgrading
2983 Packages</a></h3>
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>
2989 <p> Firstly, you'd compile and install <em>kermit-6.0.192</em> in </p>
2991 <pre>
2992 /usr/local/pkgs/kermit-6.0.192
2993 </pre>
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>
2999 <pre>
3000 graft -d -n kermit-5A190
3001 </pre>
3003 <p> You'll see output similar to </p>
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>
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>
3036 <p> If you execute: </p>
3038 <pre>
3039 graft -dV kermit-5A190
3040 </pre>
3042 <p> you'll see: </p>
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>
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>
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>
3085 <pre>
3086 rm -rf /usr/local/pkgs/kermit-5A190
3087 </pre>
3089 <p> Now you can <em>graft</em> the new version of <em>kermit</em>. Execute: </p>
3091 <pre>
3092 graft -i -n kermit-6.0.192
3093 </pre>
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>
3099 <pre>
3100 graft -i kermit-6.0.192
3101 </pre>
3103 <hr width="25%">
3105 <h3><a name="transitioning">Transitioning a package to <em>Graft</em>
3106 control</a></h3>
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>
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>
3115 <pre>
3116 /usr/local/bin/weblint
3117 /usr/local/lib/global.weblintrc
3118 /usr/local/man/man1/weblint.1
3119 </pre>
3121 <p> The first step is to create a new copy of the package in its own
3122 directory: </p>
3124 <pre>
3125 /usr/local/pkgs/weblint-1.017
3126 </pre>
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>
3132 <p> Test the new installation to ensure it behaves as expected. </p>
3134 <p> Then prune the old files from <tt>/usr/local/*</tt> using: </p>
3136 <pre>
3137 graft -pV weblint-1.017
3138 </pre>
3140 <p> You'd expect to see output similar to: </p>
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>
3154 <p> If you elected to delete conflicting files instead of renaming them
3155 you'd use: </p>
3157 <pre>
3158 graft -pDV weblint-1.017
3159 </pre>
3161 <p> and you'd see output similar to: </p>
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>
3175 <p> Now the new version of <em>weblint</em> 1.017 can be <em>grafted</em> in
3176 place: </p>
3178 <pre>
3179 graft -i weblint-1.017
3180 </pre>
3182 <p> The <em>grafted</em> version of <em>weblint</em> can now be tested. </p>
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>
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>
3193 <hr width="25%">
3195 <h3><a name="conflicts">Conflict Processing</a></h3>
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>
3201 <center>
3202 <table summary="Conflcits" border=2 cellpadding=3>
3203 <tr>
3204 <th>
3205 Package Object
3206 </th>
3208 <th>
3209 Target Object
3210 </th>
3211 </tr>
3213 <tr>
3214 <td>
3215 directory
3216 </td>
3218 <td>
3219 not a directory
3220 </td>
3221 </tr>
3223 <tr>
3224 <td>
3225 file
3226 </td>
3228 <td>
3229 directory
3230 </td>
3231 </tr>
3233 <tr>
3234 <td>
3235 file
3236 </td>
3238 <td>
3239 file
3240 </td>
3241 </tr>
3243 <tr>
3244 <td>
3245 file
3246 </td>
3248 <td>
3249 symbolic link to something other than the package object
3250 </td>
3251 </tr>
3252 </table>
3253 </center>
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>
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>
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>
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>
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>
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>
3288 <pre>
3289 graft -i -n <em>package</em> &gt; /dev/null
3290 </pre>
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>
3295 <p> See the comprehensive table above describing how
3296 <a href="#precedence">conflicts are handled</a> for more details. </p>
3298 <hr width="25%">
3300 <h3><a name="exitstatus">Exit Status</a></h3>
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>
3305 <center>
3306 <table summary="Exit Status" border=2 cellpadding=3>
3307 <tr>
3308 <th>
3309 Exit Status
3310 </th>
3312 <th>
3313 Condition
3314 </th>
3315 </tr>
3317 <tr>
3318 <td>
3319 <center>
3320 <strong>0</strong>
3321 </center>
3322 </td>
3324 <td>
3325 All operations succeeded.
3326 </td>
3327 </tr>
3329 <tr>
3330 <td>
3331 <center>
3332 <strong>1</strong>
3333 </center>
3334 </td>
3336 <td>
3337 A conflict occurred during installation.
3338 </td>
3339 </tr>
3341 <tr>
3342 <td>
3343 <center>
3344 <strong>2</strong>
3345 </center>
3346 </td>
3348 <td>
3349 Command line syntax was incorrect.
3350 </td>
3351 </tr>
3353 <tr>
3354 <td>
3355 <center>
3356 <strong>3</strong>
3357 </center>
3358 </td>
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>
3367 <tr>
3368 <td>
3369 <center>
3370 <strong>4</strong>
3371 </center>
3372 </td>
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>
3383 <hr>
3385 <h2><a name="other-pkg-tools">Using <em>Graft</em> with other package
3386 management tools</a></h2>
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>
3398 <ul>
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>
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>
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>
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>
3435 </ul>
3437 <hr>
3439 <h2><a name="availability">Availability</a></h2>
3441 <p> The latest version of <em>Graft</em> should always be available from: </p>
3443 <pre>
3444 <a href="http://peters.gormand.com.au/Home/tools/graft">http://peters.gormand.com.au/Home/tools/graft</a>
3445 </pre>
3447 <hr>
3449 <h2><a name="license">License</a></h2>
3451 <p> <em>Graft</em> is licensed under the terms of the GNU General Public
3452 License, Version 2, June 1991. </p>
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>
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>
3465 <hr>
3467 </body>
3468 </html>