website/manual/en/html_node/pkgmanagement.html

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