| blob | 7181f442597de4036b3e7351d695ad73787f15af |
2 <HTML>
3 <HEAD>
6 <CENTER>
7 </CENTER>
12 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
13 <html>
14 <!-- This user guide is for Qi (version 1.1,
15 19 May 2019), which is a simple but well-integrated package manager.
17 Copyright (C) 2019 Matias Andres Fonzo, Santiago del Estero,
18 Argentina.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.3 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
24 Texts. A copy of the license is included in the section entitled
25 "GNU Free Documentation License". -->
26 <!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
27 <head>
41 <!--
65 -->
66 </style>
69 </head>
90 <li><a name="toc-Installing-packages" href="#Installing-packages">4.2 Installing packages</a></li>
95 </ul></li>
96 </ul></li>
103 <li><a name="toc-Variables-from-the-environment" href="#Variables-from-the-environment">5.5 Variables from the environment</a></li>
105 </ul></li>
111 </ul>
112 </div>
117 <p>
118 Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
119 </div>
124 </p>
126 <tr><td align="left" valign="top">• <a href="#Introduction" accesskey="1">Introduction</a>:</td><td> </td><td align="left" valign="top">Description and features of qi
127 </td></tr>
128 <tr><td align="left" valign="top">• <a href="#Invoking-qi" accesskey="2">Invoking qi</a>:</td><td> </td><td align="left" valign="top">Command-line options
129 </td></tr>
130 <tr><td align="left" valign="top">• <a href="#The-qirc-file" accesskey="3">The qirc file</a>:</td><td> </td><td align="left" valign="top">Configuration file
131 </td></tr>
132 <tr><td align="left" valign="top">• <a href="#Packages" accesskey="4">Packages</a>:</td><td> </td><td align="left" valign="top">Managing packages
133 </td></tr>
134 <tr><td align="left" valign="top">• <a href="#Recipes" accesskey="5">Recipes</a>:</td><td> </td><td align="left" valign="top">Building packages
135 </td></tr>
136 <tr><td align="left" valign="top">• <a href="#Order-files" accesskey="6">Order files</a>:</td><td> </td><td align="left" valign="top">Handling build order
137 </td></tr>
138 <tr><td align="left" valign="top">• <a href="#Creating-packages" accesskey="7">Creating packages</a>:</td><td> </td><td align="left" valign="top">Making Qi packages
139 </td></tr>
140 <tr><td align="left" valign="top">• <a href="#Examining-packages" accesskey="8">Examining packages</a>:</td><td> </td><td align="left" valign="top">Debugging purposes
141 </td></tr>
142 <tr><td align="left" valign="top">• <a href="#Exit-status" accesskey="9">Exit status</a>:</td><td> </td><td align="left" valign="top">Exit codes
143 </td></tr>
144 <tr><td align="left" valign="top">• <a href="#Index">Index</a>:</td><td> </td><td align="left" valign="top">
145 </td></tr>
146 </table>
148 <br>
150 </p>
151 <p>Qi’s home page can be found at <a href="http://www.dragora.org">http://www.dragora.org</a>.
152 Send bug reports or suggestions to <a href="mailto:dragora-users@nongnu.org"><span class="nolinebreak">dragora-users</span>@nongnu.org</a>.<!-- /@w -->
153 </p>
154 <hr>
157 <p>
158 Next: <a href="#Invoking-qi" accesskey="n" rel="next">Invoking qi</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
159 </div>
164 <p>Qi is a simple but well-integrated package manager. It can create,
165 install, remove, and upgrade software packages. Qi produces binary
166 packages using recipes, which are files containing specific instructions
167 to build each package from source. Qi can manage multiple packages
168 under a single directory hierarchy. This method allows to maintain a set
169 of packages and multiple versions of them. This means that Qi could be
170 used as the main package manager or complement the existing one.
171 </p>
172 <p>Qi offers a friendly command line interface, a global configuration
173 file, a simple recipe layout to deploy software packages; also works
174 with binary packages in parallel, speeding up installations and packages
175 in production. The format used for packages is a simplified but safe
176 POSIX pax archive compressed with lzip.
177 </p>
178 <p>Qi is a modern (POSIX-compliant) shell script released under the
179 terms of the GNU General Public License. There are only two major
181 to be found in any Unix-like system.
182 </p>
183 <hr>
186 <p>
187 Next: <a href="#The-qirc-file" accesskey="n" rel="next">The qirc file</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
188 </div>
193 <p>This chapter describes the synopsis and command line options for
194 invoke Qi.
195 </p>
198 </pre></div>
201 perform, other options are meant to detail how this operation should be
202 performed.
203 </p>
204 <p>qi supports the following options to operate:
205 </p>
208 <dd><p>Build package using recipe names.
209 </p>
210 </dd>
212 <dd><p>Create .tlz package from directory.
213 </p>
214 </dd>
216 <dd><p>Delete packages.
217 </p>
218 </dd>
220 <dd><p>Install packages.
221 </p>
222 </dd>
224 <dd><p>Resolve build order through .order files.
225 </p>
226 </dd>
228 <dd><p>Update packages (implies -i, -d and -p options).
229 </p>
230 </dd>
232 <dd><p>Warn about files that will be linked.
233 </p>
234 </dd>
236 <dd><p>Extract a package for debugging purposes.
237 </p></dd>
238 </dl>
240 <p>There are common options between modes:
241 </p>
244 <dd><p>Do not read the configuration file.
245 </p>
246 <p>This will ignore any value in the qirc file.
247 </p>
248 </dd>
250 <dd><p>Package directory for installations.
251 </p>
253 </p>
254 <p>Only valid for -i, -d, or -u options.
255 </p>
256 </dd>
258 <dd><p>Force option.
259 </p>
260 <p>This option can force the build of a recipe, or force the update of a
261 pre-existing package.
262 </p>
263 <p>Only valid for -b, -u options.
264 </p>
265 </dd>
267 <dd><p>Target directory for symbolic links.
268 </p>
270 </p>
271 <p>Only valid for -i, -d, or -u options.
272 </p>
273 </dd>
275 <dd><p>Keep (don’t delete) ‘<samp>${srcdir}</samp>’ or ‘<samp>${destdir}</samp>’ in build
276 mode, keep (don’t delete) package directory in delete mode.
277 </p>
278 <p>Only valid for -b, -d or -u options.
279 </p>
280 </dd>
282 <dd><p>Prune conflicts on package installations.
283 </p>
284 <p>This option may proceed with the package installation if one or more
285 conflicts occur.
286 </p>
287 </dd>
289 <dd><p>Use the fully qualified named directory as the root directory for all qi
290 operations. The target directory and package directory will be relative
291 to the specified directory, including the log file for graft.
292 </p>
293 </dd>
296 </p></dd>
297 </dl>
299 <p>Options for build mode (-b):
300 </p>
303 <dd><p>Where the packages produced are written.
304 </p>
306 </p>
307 </dd>
309 <dd><p>Where archives, patches, and recipes are expected.
310 </p>
312 </p>
313 </dd>
315 <dd><p>Where (compressed) sources will be found.
316 </p>
318 </p>
319 </dd>
321 <dd><p>Architecture to use.
322 </p>
324 </p>
325 </dd>
327 <dd><p>Parallel jobs for the compiler.
328 </p>
330 </p>
331 </dd>
334 </p>
335 <p>It will be omitted if the -n option is being used.
336 </p>
337 </dd>
340 </p>
341 </dd>
343 <dd><p>Selects the option to skip completed recipes.
344 </p>
345 <p>This means, in interactive mode, when the dialog
346 to summarize recipes is shown.
347 </p></dd>
348 </dl>
350 <p>Informative options:
351 </p>
354 <dd><p>Print default directory locations.
355 </p>
356 <p>This will print the target directory, package directory, working tree,
357 the directory for tarballs, and the output directory for the packages
358 produced.
359 </p>
360 </dd>
362 <dd><p>Display the help describing the options and then exit.
363 </p>
364 </dd>
366 <dd><p>Print the version number and license information.
367 The version number should be included in all bug reports.
368 </p></dd>
369 </dl>
371 <p>Expected non-option arguments are package directories and regular files:
372 recipes or files ending in .tlz, .order. When FILE is -, qi can read from
374 </p>
376 <hr>
379 <p>
380 Next: <a href="#Packages" accesskey="n" rel="next">Packages</a>, Previous: <a href="#Invoking-qi" accesskey="p" rel="prev">Invoking qi</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
381 </div>
387 (such as a download manager) for default use. This file is used by qi
388 at runtime, e.g., to build, install, remove or upgrade packages.
389 </p>
390 <p>It has the following rules:
391 </p>
392 <ul>
395 </li><li> Declaration of values should only take one line, no line break.
398 interpreted as literal.
399 </li></ul>
401 <p>The command line options related to the package directory and target
402 directory plus some of the options used for the build mode can override
404 </p>
405 <p>The order in which qi looks for this file is:
406 </p>
407 <ol>
409 Effective user.
412 System-wide.
413 </li></ol>
415 <p>If you intend to run qi as effective user, the file
417 setting the paths for ‘<samp>${packagedir}</samp>’ and ‘<samp>${targetdir}</samp>’
419 </p>
421 <hr>
424 <p>
425 Next: <a href="#Recipes" accesskey="n" rel="next">Recipes</a>, Previous: <a href="#The-qirc-file" accesskey="p" rel="prev">The qirc file</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
426 </div>
431 <p>A package is a suite of programs usually distributed in binary form
432 which may also contain manual pages, documentation, or any other file
433 associated to a specific software.
434 </p>
435 <p>The package format used by qi is a simplified POSIX pax archive
437 </p>
438 <p>Both package installation and package de-installation are managed using
441 configuration file or via options.
442 </p>
444 contents will be decompressed (will reside).
445 </p>
448 </p>
449 <p>Packages are installed in self-contained directory trees and symbolic
450 links from a common area are made to the package files. This allows
451 multiple versions of the same package to coexist on the same system.
452 </p>
458 Since multiple packages can be installed or removed at the same time,
459 certain conflicts may arise between the packages.
460 </p>
462 defines a CONFLICT as one of the following conditions:
463 </p>
464 <ul>
465 <li> If the package object is a directory and the target object exists but is
466 not a directory.
468 </li><li> If the package object is not a directory and the target object exists
469 and is not a symbolic link.
471 </li><li> If the package object is not a directory and the target object exists
472 and is a symbolic link to something other than the package object.
473 </li></ul>
475 <p>The default behavior of qi for an incoming package is to ABORT if a
476 conflict arises. When a package is going to be deleted, qi tells to
477 graft(1) to remove those parts that are not in conflict, leaving the
478 links to the belonging package. This behavior can be forced if the
479 -p option is given.
480 </p>
485 <p>To install a single package, simply type:
486 </p>
489 </pre></div>
491 <p>To install multiple packages at once, type:
492 </p>
495 </pre></div>
497 <p>Warn about the files that will be linked:
498 </p>
501 </pre></div>
503 <p>This is to verify the content of a package before installing it.
504 </p>
505 <p>See the process of an installation (very verbose):
506 </p>
509 </pre></div>
511 <p>A second -v gives more.
512 </p>
513 <p>Installing package in a different location:
514 </p>
517 </pre></div>
519 <p>The -r option assumes ‘<samp>${targetdir}</samp>’ and ‘<samp>${packagedir}</samp>’.
520 See:
521 </p>
524 </pre></div>
529 the target for "usr/bin" will be created at ‘<samp>/home/selk</samp>’. Considering
530 that you have exported the <code>PATH</code> as ‘<samp>${HOME}/usr/bin</samp>’, now the
531 system is able to see the recent lzip.
532 </p>
533 <p>Installing from a list of packages using standard input:
534 </p>
537 </pre></div>
539 <p>The list of packages must contain full path names to be passed in the
540 installation, e.g.:
544 </p>
549 <p>To remove a package, simply type:
550 </p>
553 </pre></div>
557 /usr/local/pkgs, this will be equal to:
558 </p>
561 </pre></div>
563 <p>Detailed output (very verbose):
564 </p>
567 </pre></div>
569 <p>A second -v gives more.
570 </p>
571 <p>By default the delete mode does not preserve a package directory after
573 changed if the -k option is passed:
574 </p>
577 </pre></div>
579 <p>This means that the links to the package can be reactivated, later:
580 </p>
583 </pre></div>
585 <p>Removing package from a different location:
586 </p>
589 </pre></div>
591 <p>Removing a package using standard input:
592 </p>
595 </pre></div>
597 <p>This will match with the package directory.
598 </p>
603 <p>The upgrade mode inherits the properties of the installation and removal
604 process. To make sure that a package is updated, the package is installed
606 the incoming package is pre-installed, qi can proceed to search and delete
607 packages that have the same name (considered as previous ones). Finally,
608 the package is re-installed at its final location and the temporary
609 directory is removed.
610 </p>
611 <p>To upgrade a package, just type:
612 </p>
615 </pre></div>
619 </p>
620 <p>If you want to keep the package directories of versions found during the
621 upgrade process, just pass:
622 </p>
625 </pre></div>
627 <p>To see the upgrade process (very verbose):
628 </p>
631 </pre></div>
633 <p>A second -v gives more.
634 </p>
635 <p>To force the upgrade of an existing package:
636 </p>
639 </pre></div>
645 <p>To implement general package facilities, either to install, remove or
646 maintain the hierarchy of packages in a clean manner, qi makes use of the
647 pruning operation via graft(1):
648 </p>
649 <p>There is a risk if those are crucial packages for the proper functioning
650 of the system, because it implies the deactivation of symbolic from the
652 into its final location during upgrade.
653 </p>
654 <p>A blacklist of package names has been devised for the case where
655 a user decides to upgrade all packages in the system, or
656 just the crucial ones, such as the C library.
657 </p>
658 <p>The blacklist is related to the upgrade mode only, consists in installing
659 a package instead of updating it or removing previous versions of it;
660 the content of the package will be updated over the existing content at
663 carried out in order to re-link possible differences with the recent
664 content, this helps to avoid leaving dead links in the target directory.
665 </p>
666 <p>Since the upgrade mode is also used to install a new package, the mechanism
667 for blacklist is to install a declared package if it does not already
668 exist. If it already exists, it is verified that the binary package is
669 newer than the package directory in order to perform an update.
670 </p>
671 <p>Package names for the blacklist can be set from the configuration file.
672 </p>
674 <hr>
677 <p>
678 Next: <a href="#Order-files" accesskey="n" rel="next">Order files</a>, Previous: <a href="#Packages" accesskey="p" rel="prev">Packages</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
679 </div>
684 <p>A recipe is a file telling qi what to do. Most often, the recipe tells
685 qi how to build a binary package from a source tarball.
686 </p>
687 <p>A recipe has two parts: a list of variable definitions and a list of
688 sections. By convention, the syntax of a section is:
689 </p>
692 {
693 section lines
694 }
695 </pre></div>
697 <p>The section name is followed by parentheses, one newline and an opening
698 brace. The line finishing the section contains just a closing brace.
699 The section names or the function names currently recognized are
701 </p>
704 build and produce a package.
705 </p>
710 <p>A "variable" is a <strong>shell variable</strong> defined either in <samp>qirc</samp>
711 or in a recipe to represent a string of text, called the variable’s
713 definitions of other variables or in calls to external commands.
714 </p>
715 <p>Variables can represent lists of file names, options to pass to
716 compilers, programs to run, directories to look in for source files,
717 directories to write output to, or anything else you can imagine.
718 </p>
719 <p>Definitions of variables in qi have four levels of precedence.
720 Options which define variables from the command-line override those
723 variables set by command-line options. Finally, the variables have
724 default values if they are not defined anywhere.
725 </p>
726 <p>Options that set variables through the command-line can only reference
728 </p>
731 </p>
732 <p>Definitions of variables in the recipe can only reference variables
733 set by the command-line, variables previously defined in the recipe,
735 </p>
740 <p>There are variables which can only be set using the command line options or
742 redefined in a recipe. See the following definitions:
743 </p>
745 This variable can not be redefined in the recipe. Default sets to
747 </p>
749 are expected. This variable can not be redefined in the recipe. Default
751 </p>
752 <p>‘<samp>tardir</samp>’ is defined in the recipe to the directory where the tarball
753 containing the source can be found. The full name of the tarball is
755 recipe as ‘<samp>${tardir}</samp>’; a value of . for ‘<samp>tardir</samp>’ sets it to
756 the value of CWD (Current Working Directory), this is where the recipe
757 lives.
758 </p>
759 <p>‘<samp>arch</samp>’ is the architecture to compose the package name. Its value is
762 </p>
765 is 1.
766 </p>
767 <p>The two variables ‘<samp>${srcdir}</samp>’ and ‘<samp>${destdir}</samp>’ can be
768 set in the recipe, as any other variable, but if they are not, qi uses
769 default values for them when building a package.
770 </p>
772 ‘<samp>${program}-${version}</samp>’. ‘<samp>destdir</samp>’ is the place where the
773 built package will be installed, and defaults to
775 </p>
776 <p>If ‘<samp>pkgname</samp>’ is left undefined, the special variable ‘<samp>program</samp>’
779 </p>
780 <p>‘<samp>pkgname</samp>’ and ‘<samp>pkgversion</samp>’ along with: ‘<samp>version</samp>’, ‘<samp>arch</samp>’,
783 </p>
785 names that will be replaced at the time of installation.
786 </p>
787 <p>A typical recipe contains the following variables:
788 </p>
789 <ul>
792 <p>It matches the source name. It is also used to compose the name of the
794 </p>
797 <p>It matches the source name. It is also used to compose the version of the
799 </p>
802 <p>It is used to compose the architecture of the package in which it is
803 build.
804 </p>
807 <p>This is used to reflect the release number of the package. It is
808 recommended to increase this number after any significant change in
809 the recipe or post-install script.
810 </p></li></ul>
812 <p>Obtaining sources over the network must be declared in the recipe using
814 </p>
815 <p>The variables ‘<samp>netget</samp>’ and ‘<samp>rsync</samp>’ can be defined in <samp>qirc</samp>
816 to establish a network downloader in order to get the sources. If they
817 are not defined, qi uses default values:
818 </p>
821 </p>
823 the RSYNC protocol, default sets to
825 </p>
827 when a package is installed.
828 </p>
829 <p>A description has two parts: a brief description, and a long description.
831 </p>
834 Brief description.
836 Long description.
837 "
838 </pre></div>
840 <p>The first line of the value represented is a brief description of the
843 descriptive description of the software.
844 </p>
845 <p>An example looks like:
846 </p>
849 The GNU core utilities.
851 The GNU core utilities are the basic file, shell and text manipulation
852 utilities of the GNU operating system. These are the core utilities
853 which are expected to exist on every operating system.
854 "
855 </pre></div>
858 one would be used on the meta file creation. See
860 </p>
861 <p>The ‘<samp>homepage</samp>’ variable is used to declare the main site or home page:
862 </p>
865 </pre></div>
867 <p>The variable ‘<samp>license</samp>’ is used for license information<a name="DOCF2" href="#FOOT2"><sup>2</sup></a>.
868 Some code in the program can be covered by license A, license B, or
871 (if that ever happens in a significant way), and comma for heterogeneous
872 licensing. Comma would have lower precedence, plus added special terms.
873 </p>
876 </pre></div>
883 does not mean that you can’t use it in another distribution, just that
884 if you do you will need to test it for your selves). To aid this here
885 are some references to well written recipes:
886 </p>
887 <p><a href="http://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes">http://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes</a>.
888 <a href="http://notabug.org/dragora/dragora/src/master/recipes">http://notabug.org/dragora/dragora/src/master/recipes</a>.
889 </p>
891 for some examples.
892 </p>
897 <p>A recipe is any valid regular file. Qi sets priorities for reading a
898 recipe, the order in which qi looks for a recipe is:
899 </p>
900 <ol>
901 <li> Current working directory.
906 </li><li> If the recipe is not in the current working directory, it will be
909 </li></ol>
911 <p>To build a single package, type:
912 </p>
915 </pre></div>
917 <p>Multiple jobs can be passed to the compiler to speed up the build process:
918 </p>
921 </pre></div>
923 <p>Update or install the package produced (if it is not already installed)
924 when finish:
925 </p>
928 </pre></div>
930 <p>Only process a recipe but do not create the binary package:
931 </p>
934 </pre></div>
936 <p>The options -i or -u have no effect when -n is given.
937 </p>
938 <p>This can be useful to inspect the build process of recipe:
939 </p>
941 </p>
942 <p>The -k option could preserve the source directory and the destination
943 directory for later inspection. A log file of the build process will be
944 created redirecting both, standard error and standard output to tee(1).
945 </p>
950 <p>Qi has environment variables which can be used at build time:
951 </p>
954 prepended to the value of ‘<samp>${srcdir}</samp>’ and ‘<samp>${destdir}</samp>’ in
955 build mode. By convention its default value is equal to
957 </p>
958 <p>The variables <code>QICFLAGS</code>, <code>QICXXFLAGS</code>, and <code>QILDFLAGS</code> have
961 </p>
962 <p>Recommended practice is to set variables in the command line of
964 environment. As follows:
965 </p>
966 <blockquote>
967 <p>Variables not defined in a site shell script can be set in the environment
968 passed to configure. However, some packages may run configure again
969 during the build, and the customized values of these variables may be
970 lost. In order to avoid this problem, you should set them in the
972 </p>
974 </p>
975 <p><a href="http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html">http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html</a>
976 </p></blockquote>
978 <blockquote>
979 <p>Indeed, while configure can notice the definition of CC in
982 users do.
983 </p>
984 <p>[...]
985 </p>
986 <p>configure: error: changes in the environment can compromise the build.
987 </p>
988 <p><a href="http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html">http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html</a>
989 </p></blockquote>
991 <blockquote>
992 <p>It is not wise for makefiles to depend for their functioning on
993 environment variables set up outside their control, since this would cause
994 different users to get different results from the same makefile. This is
995 against the whole purpose of most makefiles.
996 </p>
997 <p><a href="http://gnu.org/software/make/manual/make.html#Environment">http://gnu.org/software/make/manual/make.html#Environment</a>
998 </p></blockquote>
1005 contains information about the package such as program name, program
1006 version, release, fetch address, description, and other minor data
1007 extracted from processed recipes. The name of the file is generated as
1009 information to the user without having to look inside the package content.
1010 </p>
1011 <p>The content of a meta file looks like:
1012 </p>
1015 # The Bourne Again SHell.
1016 #
1017 # Bash is an sh-compatible shell that incorporates useful features from
1018 # the Korn shell (ksh) and C shell (csh). It is intended to conform to
1019 # the IEEE POSIX P1003.2/ISO 9945.2 shell and tools standard.
1020 #
1021 # It offers functional improvements over sh for both programming and
1022 # interactive use.
1023 #
1028 program=bash
1029 version=5.0
1030 release=1
1035 replace=""
1036 </pre></div>
1038 <p>Package descriptions are extracted from the variable ‘<samp>description</samp>’:
1039 each line is interpreted literally and pre-formatted to fit in (exactly)
1040 <strong>80 columns</strong>, plus the character ‘<samp>#</samp>’ and a space is prefixed
1041 to every line.
1042 </p>
1043 <p>In addition to the Special variables, there are implicit variables such as
1045 </p>
1048 line of ‘<samp>description</samp>’, mentioned as the "brief description".
1049 </p>
1051 <hr>
1054 <p>
1055 Next: <a href="#Creating-packages" accesskey="n" rel="next">Creating packages</a>, Previous: <a href="#Recipes" accesskey="p" rel="prev">Recipes</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1056 </div>
1061 <p>The order mode has the purpose of resolving the build order through
1062 .order files. An order file contains a list of recipe names, by default
1063 does not perform any action other than to print a resolved list in
1065 <strong>c</strong>, and <strong>c</strong> depends on <strong>b</strong> as well, the file might
1066 look like:
1067 </p>
1070 b:
1071 c: b
1072 </pre></div>
1074 <p>Each letter represents a recipe name, complete dependencies for
1075 the first recipe name are listed in descending order, which is
1076 printed from right to left, and removed from left to right:
1077 </p>
1079 </p>
1082 c
1083 a
1084 </pre></div>
1086 <p>Blank lines, colons and parentheses are simply ignored. Comment lines
1088 </p>
1089 <p>An order file could be used to build a series of packages, for example,
1090 if the content is:
1091 </p>
1095 libs/libjpeg-turbo: devel/nasm
1096 x-libs/jasper: libs/libjpeg-turbo
1097 libs/tiff: libs/libjpeg-turbo
1098 </pre></div>
1100 <p>To proceed with each recipe, we can type:
1101 </p>
1104 </pre></div>
1107 should build the recipes:
1108 </p>
1111 libs/libjpeg-turbo
1112 x-libs/jasper
1113 libs/tiff
1114 </pre></div>
1117 <hr>
1120 <p>
1121 Next: <a href="#Examining-packages" accesskey="n" rel="next">Examining packages</a>, Previous: <a href="#Order-files" accesskey="p" rel="prev">Order files</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1122 </div>
1128 compatible packages, the creation mode is selected by the -c option.
1129 A package is produced using the contents of the Current Directory, and
1130 the package file is written out.
1131 </p>
1134 </pre></div>
1136 <p>The argument for the file name to be written must contain a fully
1137 qualified named directory as the output directory where the package
1138 produced will be written. The file name should be composed using the
1139 full name: name-version-architecture+release.tlz
1140 </p>
1142 </p>
1147 </pre></div>
1151 </p>
1152 <p>All packages produced are complemented by a checksum file (.sha256).
1153 </p>
1155 <hr>
1158 <p>
1159 Next: <a href="#Exit-status" accesskey="n" rel="next">Exit status</a>, Previous: <a href="#Creating-packages" accesskey="p" rel="prev">Creating packages</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1160 </div>
1166 purposes. The extraction mode is selected by the -x option. It
1167 decompresses a package into a single directory, verifying its integrity
1168 and preserving its properties.
1169 </p>
1172 </pre></div>
1175 </p>
1178 </pre></div>
1181 single directory, this will be a private directory for the user who
1182 </p>
1185 mask to deploy the content will be equal to
1187 </p>
1188 <p>The creation of the custom directory is influenced by the value of the
1190 </p>
1192 <hr>
1195 <p>
1196 Next: <a href="#Index" accesskey="n" rel="next">Index</a>, Previous: <a href="#Examining-packages" accesskey="p" rel="prev">Examining packages</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1197 </div>
1202 <p>All the exit codes are described in this chapter.
1203 </p>
1206 <dd><p>Successful completion (no errors).
1207 </p>
1208 </dd>
1210 <dd><p>Minor common errors:
1211 </p>
1213 <li>- Help usage on illegal options or required arguments.
1215 </li><li>- Program needed by qi (prerequisite) is not available.
1216 </li></ul>
1218 </dd>
1220 <dd><p>Command execution error:
1221 </p>
1222 <p>This code is used to return the evaluation of external commands and shell
1223 arguments in case of error.
1224 </p>
1225 </dd>
1227 <dd><p>Integrity check error for compressed files.
1228 </p>
1229 <p>Compressed files means:
1230 </p>
1233 Supported extensions: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
1234 .tar.xz, .txz
1237 Supported extensions: .tar.lz, .tlz
1240 Supported extensions: .zip, .ZIP
1243 Supported extensions: .gz, .Z
1246 Supported extensions: .bz2
1249 Supported extensions: .lz
1252 Supported extensions: .xz
1253 </li></ul>
1255 </dd>
1257 <dd><p>File empty, not regular, or expected.
1258 </p>
1259 <p>Commonly, it is expected:
1260 </p>
1262 <li>- An argument for the mode of operation.
1264 </li><li>- A readable file or directory.
1266 </li><li>- A binary package (.tlz).
1268 </li><li>- A valid recipe.
1270 </li><li>- An order file (.order).
1272 </li><li>- A protocol supported by the network downloader tool.
1274 </li><li>- A checksum file (.sha256).
1275 </li></ul>
1277 </dd>
1279 <dd><p>Empty or not defined variable:
1280 </p>
1281 <p>This code is used to report empty or undefined variables; usually,
1282 variables coming from a recipe or assigned arrays that are tested.
1283 </p>
1284 </dd>
1286 <dd><p>Package already installed:
1287 </p>
1288 <p>The package directory for an incoming .tlz package already exists.
1289 </p>
1290 </dd>
1292 <dd><p>Network manager error:
1293 </p>
1294 <p>This code is used if the network downloader tool fails for some reason.
1295 </p></dd>
1296 </dl>
1299 <hr>
1302 <p>
1303 Previous: <a href="#Exit-status" accesskey="p" rel="prev">Exit status</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1304 </div>
1308 <table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a>
1309
1311
1313
1315
1317
1319
1321
1323
1325
1327
1329
1330 </td></tr></table>
1332 <tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr>
1335 <tr><td></td><td valign="top"><a href="#index-configuration-file">configuration file</a>:</td><td> </td><td valign="top"><a href="#The-qirc-file">The qirc file</a></td></tr>
1338 <tr><td></td><td valign="top"><a href="#index-environment-variables">environment variables</a>:</td><td> </td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1339 <tr><td></td><td valign="top"><a href="#index-exit-codes">exit codes</a>:</td><td> </td><td valign="top"><a href="#Exit-status">Exit status</a></td></tr>
1342 <tr><td></td><td valign="top"><a href="#index-handling-build-order">handling build order</a>:</td><td> </td><td valign="top"><a href="#Order-files">Order files</a></td></tr>
1345 <tr><td></td><td valign="top"><a href="#index-introduction">introduction</a>:</td><td> </td><td valign="top"><a href="#Introduction">Introduction</a></td></tr>
1346 <tr><td></td><td valign="top"><a href="#index-invocation">invocation</a>:</td><td> </td><td valign="top"><a href="#Invoking-qi">Invoking qi</a></td></tr>
1349 <tr><td></td><td valign="top"><a href="#index-managing-packages">managing packages</a>:</td><td> </td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1352 <tr><td></td><td valign="top"><a href="#index-package-blacklist">package blacklist</a>:</td><td> </td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1353 <tr><td></td><td valign="top"><a href="#index-package-build">package build</a>:</td><td> </td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1354 <tr><td></td><td valign="top"><a href="#index-package-conflicts">package conflicts</a>:</td><td> </td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1355 <tr><td></td><td valign="top"><a href="#index-package-creation">package creation</a>:</td><td> </td><td valign="top"><a href="#Creating-packages">Creating packages</a></td></tr>
1356 <tr><td></td><td valign="top"><a href="#index-package-de_002dinstallation">package de-installation</a>:</td><td> </td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1357 <tr><td></td><td valign="top"><a href="#index-package-examination">package examination</a>:</td><td> </td><td valign="top"><a href="#Examining-packages">Examining packages</a></td></tr>
1358 <tr><td></td><td valign="top"><a href="#index-package-installation">package installation</a>:</td><td> </td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1359 <tr><td></td><td valign="top"><a href="#index-package-upgrade">package upgrade</a>:</td><td> </td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1362 <tr><td></td><td valign="top"><a href="#index-recipes">recipes</a>:</td><td> </td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1365 <tr><td></td><td valign="top"><a href="#index-special-variables">special variables</a>:</td><td> </td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1368 <tr><td></td><td valign="top"><a href="#index-the-meta-file">the meta file</a>:</td><td> </td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1371 <tr><td></td><td valign="top"><a href="#index-variables">variables</a>:</td><td> </td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1374 <tr><td></td><td valign="top"><a href="#index-writing-recipes">writing recipes</a>:</td><td> </td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1376 </table>
1377 <table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a>
1378
1380
1382
1384
1386
1388
1390
1392
1394
1396
1398
1399 </td></tr></table>
1402 <hr>
1406 <p>The official guide for Graft can be found at
1407 <a href="http://peters.gormand.com.au/Home/tools/graft/graft.html">http://peters.gormand.com.au/Home/tools/graft/graft.html</a>.</p>
1410 <a href="http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html">http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html</a>.</p>
1411 </div>
1412 <hr>
1416 </body>
1417 </html>
1419 <html>
1420 <head>
1422 </head>
1424 <body>
1426 <center>
1428 </center>
1430 <h4>Prepared by Peter Samuel
1436 <blockquote>
1438 of another tree; to propagate by insertion in another stock; also, to
1439 insert a graft upon. To implant a portion of (living flesh or skin) in
1440 a lesion so as to form an organic union. To join (one thing) to another
1441 as if by grafting, so as to bring about a close union.</em> </p>
1442 </blockquote>
1444 <hr>
1448 <ul>
1458 <ul>
1460 </ul>
1466 <ul>
1471 </ul>
1475 <ul>
1478 Packages</a>
1481 options</a>
1483 <ol>
1488 </ol>
1491 Installation</a>
1494 Packages</a>
1497 directories</a>
1500 and/or directories</a>
1503 and/or directories</a>
1508 package</a>
1511 Upgrading Packages</a>
1520 </ul>
1523 other package management tools</a>
1529 </ul>
1531 <hr>
1540 a suite of programs and files that make up an individual product. For
1542 and preprocessor programs, include files, manual pages and any other
1544 confused with some vendor's definitions that are - by this definition -
1547 <p> Special thanks to Gordon Rowell, Charles Butcher, Charlie Brady,
1548 Robert Maldon and Matias A. Fonzo for design suggestions and contributions.
1549 </p>
1551 <hr>
1555 <p> In any reasonably large environment, many software packages will be
1556 installed. The installation location for these packages usually follows
1557 one of three rationales - each with its own advantages and drawbacks: </p>
1559 <ol>
1561 <li> <p> Each package is isolated from all other packages by
1562 installing it into a self contained directory tree. All binaries,
1563 manual pages, library and configuration files are stored under
1564 a single directory tree. This directory tree contains NO other
1565 files which are not the exclusive domain of the package in
1566 question. </p>
1568 <p> This method makes package demarcation obvious. As each
1569 package is self contained, identification of any file within a
1570 package is immediately apparent. </p>
1572 <p> Multiple versions of packages can be installed fairly easily
1573 to accommodate acceptance testing of new versions and/or legacy
1574 systems. </p>
1576 <p> However, the use of individual package directories can
1578 variables. Some shells may not be able to handle such long
1579 variables. Whenever a new package is added, each user MUST
1581 available. </p>
1583 <li> <p> Packages are installed under a common directory tree.
1584 Binaries for all packages are grouped in a single directory,
1585 manual pages for all packages in another directory and so on.
1586 </p>
1588 <p> This method eliminates the need for continually updating long
1591 available to all users (after a shell rehash if necessary). </p>
1593 <p> However, when a package is to be updated it is often very
1594 difficult to isolate all the files related to a particular
1595 package if they are intermingled with unrelated files. </p>
1599 </ol>
1601 <p> In an effort to maximise the advantages and minimise the
1603 philosophy: </p>
1605 <blockquote>
1606 <p> Packages are installed in self contained directory trees and
1607 symbolic links from a common area are made to the package files. </p>
1608 </blockquote>
1610 <p> This approach allows multiple versions of the same package to co-exist
1611 on the one system. One version is the commonly available version and
1612 symbolic links will be made to this version. New versions can be tested
1613 and once acceptable can replace the current commonly available version.
1614 Older versions can still be used for legacy systems by using the
1616 path name. </p>
1620 required. Any special cases can also be accommodated but these will
1621 usually be in the minority when compared with the number of commonly
1622 available packages. </p>
1624 <hr>
1629 comments regarding the packages listed below reflect their functionality
1630 and behaviour at that time and may not necessarily reflect their current
1631 functionality and behaviour. </p>
1635 the following reasons: </p>
1637 <dl>
1640 <a href="ftp://ftp.andrew.cmu.edu/pub/depot/depot.tar.gz">ftp://ftp.andrew.cmu.edu/pub/depot/depot.tar.gz</a>
1644 <p> It requires a database file to be created which
1645 provides a snapshot of the current state of both the package
1647 inadvertently destroy the package repository if the database
1648 is damaged. </p>
1651 target area, making it almost impossible to accommodate
1654 assumes ALL files in the target area will be under the
1656 modifies Unix file permissions). </p>
1659 difficult for other packages not under the control of
1663 relative to the package target. It assumes that all
1664 packages will be stored under
1668 this mechanism cumbersome. </p>
1671 files in its distribution. Local modifications would be
1672 difficult to quickly implement and test. </p>
1678 database or configuration information. </p>
1683 overridden on the command line and works well during the
1684 install phase. </p>
1687 of the target area, making it difficult to accommodate
1690 assumes ALL files in the target area will be under the
1692 modifies Unix file permissions). </p>
1695 it is difficult for other packages not under the control
1698 target directory - whether it is associated with the package
1699 it is trying to delete or not. This can be time consuming and
1700 potentially dangerous as empty directories are also removed
1701 - even empty directories that do not belong to the package
1702 being removed. </p>
1706 number of symbolic links by making links to directories if
1707 the directory is only associated with a single package. If
1710 into a collection of symbolic links to files rather than
1713 remainder of the directory is only concerned with a single
1714 package. While clever, this feature is probably a waste of
1715 time and effort. It means that the entire package target
1716 must be scanned to determine package ownership of links and
1717 as packages will usually be replaced by newer versions a
1723 mode. </p>
1726 such that they refer to files in the target location rather
1727 than the actual package installation directory. This approach
1728 precludes the use of multiple versions of packages with
1729 different configuration and/or library files. </p>
1732 few hundred lines of code so local modifications can be
1733 accommodated. However there are very few comments in the
1734 code which makes the process of modification difficult. </p>
1736 </dl>
1739 packaging program has been brought to the author's attention. </p>
1741 <dl>
1744 <a href="http://www.ks.uiuc.edu/Development/Computers/docs/sysadmin/Build/encap.html">http://www.ks.uiuc.edu/Development/Computers/docs/sysadmin/Build/encap.html</a>
1747 of Illinois Champaign-Urbana. It has the same underlying
1749 encapsulate packages into self contained directories and use
1750 symbolic links to make them visible in a common location. </p>
1755 compiled packages will live under a single directory hierarchy
1757 then attempts to create a symbolic link tree for ALL the
1758 packages under this area. There doesn't appear to be any
1759 easy way to support the quick addition or removal of a single
1760 package. </p>
1763 features was expected to be available in early 1997, however
1767 specific files from the package tree. This concept has been
1770 </dl>
1773 several another packaging programs have been brought to the author's
1774 attention. Rather than outline their features and whether or not the
1776 to each package and a brief description is given and further research
1777 is left as an exercise for the reader: </p>
1779 <dl>
1783 <dd>
1785 <pre>
1786 <a href="https://os.inf.tu-dresden.de/~adam/stowES/">https://os.inf.tu-dresden.de/~adam/stowES/</a>
1787 </pre>
1790 a Perl script which tries to ease the use of the "stow"
1791 packaging program and software which can be compiled and
1792 installed with autoconf. It automates the compilation and
1793 installation of software packages and provides some useful
1794 functions to maintain your stow packages (e.g., list packages,
1799 <dd>
1801 <pre>
1803 </pre>
1806 it easy to manage installed software across a wide range
1807 of client systems. opt_depot makes it possible to keep all
1808 files associated with a program together in one directory,
1809 so installation and de-installation is simple. opt_depot is
1810 easy to manage, and provides a scheme for installing software
1811 in a truly portable fashion; packages may be installed locally
1812 on client systems, or kept in a central package archive for
1815 <p> This site also has links to several other package
1820 <dd>
1822 <pre>
1824 </pre>
1827 organization and management of software packages. It should
1828 run on any UNIX platform that runs PERL. Similar tools
1829 include: rpm(REDHAT/Mandrake), pkgadd(Slackware/SUN),
1835 <dd>
1837 <pre>
1838 <a href="http://freecode.com/articles/the-universal-source-package">http://freecode.com/articles/the-universal-source-package</a>
1839 </pre>
1845 <p> This site also has links to other package management
1846 programs and similar items of interest. </p>
1848 </dl>
1850 <hr>
1856 while maintaining as simple a mechanism as possible. The principles of
1859 <ul>
1862 from any directory to any other directory. Default
1864 used but can easily be overridden on the command line. </p>
1867 log file can be specified on the command line. If not specified
1868 on the command line a default log file will be used. </p>
1871 directories. If a directory does not exist in the target tree
1872 it will be created (with the same ownership and permissions as
1873 the original if desired). </p>
1876 pathnames rather than relative pathnames. This allows easy
1877 identification of true package locations and facilitates block
1879 deletion and re-installation. </p>
1882 conflict arises. A conflict is defined as one of the following
1883 conditions: </p>
1885 <ul>
1887 <li> If the package object is a directory and the
1888 target object exists but is not a directory.
1890 <li> If the package object is not a directory and the
1891 target object exists and is not a symbolic link.
1893 <li> If the package object is not a directory and the
1894 target object exists and is a symbolic link to
1895 something other than the package object.
1897 <li> If the package directory contains a
1899 but does not match the 32-bit CRC of the package object.
1901 </ul>
1903 <li> <p> Installation conflicts will always be reported. Conflicts
1904 will be reported to standard error. </p>
1907 operations when asked, even when asked not to perform the
1908 operations. </p>
1912 empty directory results and leave the deletion for the operator
1915 used by other packages are not inadvertently removed. This
1916 feature can be permanently disabled by setting a flag in the
1918 command line option. </p>
1921 a package after a conflict arises. This maximises the amount of
1922 deletion that can be performed. </p>
1924 <li> <p> Deletion conflicts will always be reported. Conflicts
1925 will be reported to standard error. </p>
1928 relating to the package at hand. This will allow other packages
1929 to be placed in the target area without fear of intervention by
1933 or delete packages. This feature can be permanently disabled by
1935 by a command line option. </p>
1939 subdirectories during installation. The name of this file is
1942 <li> <p> When installing a directory tree, if the file
1945 file and/or directory names - one per line - which correspond
1946 to files and/or directories in the directory containing the
1954 <li> <p> When installing a directory tree, if the file
1957 file and/or directory names - one per line - which correspond
1958 to files and/or directories in the directory containing the
1966 <li> <p> When installing a directory tree, if the file
1969 directory. If the target files exists and is in conflict with the
1970 package file then the package file will be copied into the target
1978 processing the directory and any subdirectories during
1979 deletion. </p>
1983 will continue processing the directory and any subdirectories
1984 during deletion. </p>
1988 will continue processing the directory and any subdirectories
1989 during deletion. </p>
1992 package directory, during deletion matching files in the target
1993 directory will not be deleted however any
1998 pruning can take the form of a file rename or a file removal
2000 option. If file removal is selected and the file is a non-empty
2001 directory, it will be renamed instead. </p>
2005 processing the directory and any subdirectories during
2006 pruning. </p>
2010 will continue processing the directory and any subdirectories
2011 during pruning. </p>
2015 will continue processing the directory and any subdirectories
2016 during pruning. </p>
2019 package directory, the files in the directory will be ignored
2020 during pruning. Sub-directories will continue to be processed
2021 appropriately. </p>
2023 </ul>
2028 following precedence, from highest to lowest: </p>
2030 <pre>
2032 </pre>
2035 various control files are present: </p>
2037 <center>
2039 <tr>
2041 Install
2042 </th>
2043 </tr>
2045 <tr>
2046 <th>
2048 </th>
2050 <th>
2052 </th>
2054 <th>
2056 </th>
2058 <th>
2060 </th>
2062 <th>
2064 </th>
2065 </tr>
2067 <tr>
2068 <td>
2069 does not exist
2070 </td>
2072 <td>
2073 IGNORE
2074 </td>
2076 <td>
2077 IGNORE
2078 </td>
2080 <td>
2081 SYMLINK
2082 </td>
2084 <td>
2085 COPY
2086 </td>
2087 </tr>
2089 <tr>
2090 <td>
2091 symlink to source
2092 </td>
2094 <td>
2095 IGNORE
2096 </td>
2098 <td>
2099 IGNORE
2100 </td>
2102 <td>
2103 NOP
2104 </td>
2106 <td>
2107 DELETE & COPY
2108 </td>
2109 </tr>
2111 <tr>
2112 <td>
2113 symlink to other
2114 </td>
2116 <td>
2117 IGNORE
2118 </td>
2120 <td>
2121 IGNORE
2122 </td>
2124 <td>
2125 CONFLICT
2126 </td>
2128 <td>
2129 N/A
2130 </td>
2131 </tr>
2133 <tr>
2134 <td>
2135 symlink to other (crc match)
2136 </td>
2138 <td>
2139 N/A
2140 </td>
2142 <td>
2143 N/A
2144 </td>
2146 <td>
2147 N/A
2148 </td>
2150 <td>
2151 NOP
2152 </td>
2153 </tr>
2155 <tr>
2156 <td>
2157 symlink to other (crc diff)
2158 </td>
2160 <td>
2161 N/A
2162 </td>
2164 <td>
2165 N/A
2166 </td>
2168 <td>
2169 N/A
2170 </td>
2172 <td>
2173 COPY.new
2174 </td>
2175 </tr>
2177 <tr>
2178 <td>
2179 file
2180 </td>
2182 <td>
2183 IGNORE
2184 </td>
2186 <td>
2187 IGNORE
2188 </td>
2190 <td>
2191 CONFLICT
2192 </td>
2194 <td>
2195 N/A
2196 </td>
2197 </tr>
2199 <tr>
2200 <td>
2201 file (crc match)
2202 </td>
2204 <td>
2205 N/A
2206 </td>
2208 <td>
2209 N/A
2210 </td>
2212 <td>
2213 N/A
2214 </td>
2216 <td>
2217 NOP
2218 </td>
2219 </tr>
2221 <tr>
2222 <td>
2223 file (crc diff)
2224 </td>
2226 <td>
2227 N/A
2228 </td>
2230 <td>
2231 N/A
2232 </td>
2234 <td>
2235 N/A
2236 </td>
2238 <td>
2239 COPY.new
2240 </td>
2241 </tr>
2243 <tr>
2244 <td>
2245 not a file
2246 </td>
2248 <td>
2249 IGNORE
2250 </td>
2252 <td>
2253 IGNORE
2254 </td>
2256 <td>
2257 CONFLICT
2258 </td>
2260 <td>
2261 CONFLICT
2262 </td>
2263 </tr>
2265 <tr>
2267 Delete
2268 </th>
2269 </tr>
2271 <tr>
2272 <th>
2274 </th>
2276 <th>
2278 </th>
2280 <th>
2282 </th>
2284 <th>
2286 </th>
2288 <th>
2290 </th>
2291 </tr>
2293 <tr>
2294 <td>
2295 does not exist
2296 </td>
2298 <td>
2299 NOP
2300 </td>
2302 <td>
2303 NOP
2304 </td>
2306 <td>
2307 NOP
2308 </td>
2310 <td>
2311 NOP
2312 </td>
2313 </tr>
2315 <tr>
2316 <td>
2317 symlink to source
2318 </td>
2320 <td>
2321 DELETE
2322 </td>
2324 <td>
2325 DELETE
2326 </td>
2328 <td>
2329 DELETE
2330 </td>
2332 <td>
2333 DELETE & DELETE.new
2334 </td>
2335 </tr>
2337 <tr>
2338 <td>
2339 symlink to other
2340 </td>
2342 <td>
2343 CONFLICT
2344 </td>
2346 <td>
2347 CONFLICT
2348 </td>
2350 <td>
2351 CONFLICT
2352 </td>
2354 <td>
2355 N/A
2356 </td>
2357 </tr>
2359 <tr>
2360 <td>
2361 symlink to other (crc match)
2362 </td>
2364 <td>
2365 N/A
2366 </td>
2368 <td>
2369 N/A
2370 </td>
2372 <td>
2373 N/A
2374 </td>
2376 <td>
2377 DELETE.new
2378 </td>
2379 </tr>
2381 <tr>
2382 <td>
2383 symlink to other (crc diff)
2384 </td>
2386 <td>
2387 N/A
2388 </td>
2390 <td>
2391 N/A
2392 </td>
2394 <td>
2395 N/A
2396 </td>
2398 <td>
2399 NOP
2400 </td>
2401 </tr>
2403 <tr>
2404 <td>
2405 file
2406 </td>
2408 <td>
2409 NOTE
2410 </td>
2412 <td>
2413 NOTE
2414 </td>
2416 <td>
2417 CONFLICT
2418 </td>
2420 <td>
2421 N/A
2422 </td>
2423 </tr>
2425 <tr>
2426 <td>
2427 file (crc match)
2428 </td>
2430 <td>
2431 N/A
2432 </td>
2434 <td>
2435 N/A
2436 </td>
2438 <td>
2439 N/A
2440 </td>
2442 <td>
2443 DELETE.new
2444 </td>
2445 </tr>
2447 <tr>
2448 <td>
2449 file (crc diff)
2450 </td>
2452 <td>
2453 N/A
2454 </td>
2456 <td>
2457 N/A
2458 </td>
2460 <td>
2461 N/A
2462 </td>
2464 <td>
2465 NOP
2466 </td>
2467 </tr>
2469 <tr>
2470 <td>
2471 not a file
2472 </td>
2474 <td>
2475 CONFLICT
2476 </td>
2478 <td>
2479 CONFLICT
2480 </td>
2482 <td>
2483 CONFLICT
2484 </td>
2486 <td>
2487 CONFLICT
2488 </td>
2489 </tr>
2491 <tr>
2493 Prune
2494 </th>
2495 </tr>
2497 <tr>
2498 <th>
2500 </th>
2502 <th>
2504 </th>
2506 <th>
2508 </th>
2510 <th>
2512 </th>
2514 <th>
2516 </th>
2517 </tr>
2519 <tr>
2520 <td>
2521 does not exist
2522 </td>
2524 <td>
2525 NOP
2526 </td>
2528 <td>
2529 NOP
2530 </td>
2532 <td>
2533 NOP
2534 </td>
2536 <td>
2537 N/A
2538 </td>
2539 </tr>
2541 <tr>
2542 <td>
2543 symlink to source
2544 </td>
2546 <td>
2547 NOP
2548 </td>
2550 <td>
2551 NOP
2552 </td>
2554 <td>
2555 NOP
2556 </td>
2558 <td>
2559 N/A
2560 </td>
2561 </tr>
2563 <tr>
2564 <td>
2565 symlink to other
2566 </td>
2568 <td>
2569 PRUNE
2570 </td>
2572 <td>
2573 PRUNE
2574 </td>
2576 <td>
2577 PRUNE
2578 </td>
2580 <td>
2581 N/A
2582 </td>
2583 </tr>
2585 <tr>
2586 <td>
2587 file
2588 </td>
2590 <td>
2591 PRUNE
2592 </td>
2594 <td>
2595 PRUNE
2596 </td>
2598 <td>
2599 PRUNE
2600 </td>
2602 <td>
2603 N/A
2604 </td>
2605 </tr>
2607 <tr>
2608 <td>
2609 not a file
2610 </td>
2612 <td>
2613 PRUNE
2614 </td>
2616 <td>
2617 PRUNE
2618 </td>
2620 <td>
2621 PRUNE
2622 </td>
2624 <td>
2625 N/A
2626 </td>
2627 </tr>
2628 </table>
2629 </center>
2631 <hr>
2636 used a configuration file to map the installed location of each package to
2637 its target directory (that is the directory in which the symbolic links
2638 would be created). Work proceeded at a regular pace and by November 1997
2640 subsequent versions, the configuration file had been removed in favour of
2641 using default source and target directories. </p>
2650 (Peter Bray, Robert Maldon and others) also reported some deprecation
2660 option was silently ignored if the effective user was not root. </p>
2665 style and internals. No new behaviours or features were added to the
2668 <p> Matias made some more suggestions and improvements up to and including
2672 default locations as well as introducing some tighter controls on the
2675 <hr>
2684 <p> Your operating system and its file system(s) should also support
2685 symbolic links. If you can't make symbolic links then you can't use
2694 may be possible that you're using a home grown installation of
2696 modules as the author's development environment. </p>
2698 <p> If this is the case you'll see compile failures for the following modules
2699 if they are unavailable: </p>
2701 <pre>
2702 File::Basename
2703 Getopt::Long
2704 </pre>
2707 available. </p>
2712 <pre>
2715 </pre>
2717 <p> If you don't have these modules and you do not intend to use
2719 without issue. </p>
2723 <ol>
2727 <pre>
2728 gunzip -c graft-2.16.tar.gz | tar xvf -
2729 </pre>
2732 directory: </p>
2734 <pre>
2735 cd graft-2.16
2736 </pre>
2739 running the command </p>
2741 <pre>
2742 make -f Makefile.dist
2743 </pre>
2747 <pre>
2748 cp Makefile.dist Makefile
2749 chmod 644 Makefile
2751 ######################################################
2752 # #
2753 # You'll now need to modify the Makefile #
2754 # variables to suit your local conditions. #
2755 # #
2756 ######################################################
2758 make: *** [Makefile] Error 1
2759 </pre>
2761 <p> You can ignore the error message. That is just there to
2764 </p>
2767 modified to suit your local requirements: </p>
2769 <dl>
2771 <dt>
2772 <pre>
2775 </pre>
2777 <dd> <p> These two variables control your default
2779 directories. Most sites will probably choose to
2788 line but is not fully qualified, the value specified
2790 line argument. </p>
2793 not fully qualified will have the value specified
2795 arguments. </p>
2796 <dt>
2797 <pre>
2802 </pre>
2804 <dd> <p> There should be no need to modify these
2806 a directory that is different from your default
2807 package installation directory. If you do modify
2810 you must change these values then perhaps you've
2812 re-read of this document may be in order. </p>
2814 <dt>
2815 <pre>
2817 </pre>
2819 <dd> <p> This variable refers to the location
2825 If you are using an operating system that comes with
2827 Linux - then you don't need to worry about
2830 location. </p>
2832 <p> Most Unix, Linux and other Unix like operating
2834 modifying this value is probably unnecessary. </p>
2836 <dt>
2837 <pre>
2839 </pre>
2847 <dt>
2848 <pre>
2850 </pre>
2854 your local needs. An alternative name can be
2855 specified on the command line. </p>
2857 <p> If you want logging disabled by default, set the
2860 <dt>
2861 <pre>
2866 </pre>
2868 <dd> <p> These variables hold the names of the
2871 you change these values, try to choose obvious names.
2872 If you want the files to appear in a simple directory
2873 listing, do not use file names that begin with a
2876 <dt>
2877 <pre>
2879 </pre>
2881 <dd> <p> This variable holds the names of the
2882 files and/or directories that should never be
2884 repositories as used by systems such as
2886 value is empty but if you wish to specify values,
2887 simply add them to the variable using only
2888 whitespace as a separator. For example: </p>
2890 <pre>
2891 GRAFT-NEVER = CVS RCS SCCS .lock
2892 </pre>
2894 <dt>
2895 <pre>
2897 </pre>
2900 the files and/or directories specified by
2907 directory. </p>
2909 <p> The sense of this value is reversed by use of
2912 <p> The automatic exclusion is bypassed completely
2915 file. </p>
2917 <dt>
2918 <pre>
2920 </pre>
2922 <dd> <p> This variable sets the suffix name of
2926 <dt>
2927 <pre>
2929 </pre>
2931 <dd> <p> This variable sets the suffix name of configuration
2932 files that will be copied to the target directory when
2933 the target object is in conflict with the package
2934 object. The files will be copied as
2937 <dt>
2938 <pre>
2940 </pre>
2947 superuser privileges are not required and the
2949 disabled. </p>
2951 <p> If you are installing a private copy of
2960 <dt>
2961 <pre>
2963 </pre>
2966 will create new directories as required. By setting
2968 the original user id, group id and file modes will be
2969 carried over to the new directory. This variable is
2973 option. </p>
2975 <dt>
2976 <pre>
2978 </pre>
2986 reminding the user that a directory has been emptied.
2987 The sense of this variable can be reversed using the
2990 <p> It's probably not good practise to set this value
2992 as place holders by a number of different packages. If
2995 command line option. </p>
2998 remove conflicting files or rename them. If
3001 delete conflicting objects. If
3004 rename conflicting objects. The sense of this variable
3006 line option. </p>
3008 </dl>
3014 <pre>
3015 make clean
3016 </pre>
3020 <pre>
3021 rm -f graft
3022 </pre>
3026 <pre>
3027 make
3028 </pre>
3032 <pre>
3033 /usr/bin/perl -wc graft.pl
3034 graft.pl syntax OK
3035 sed \
3036 -e 's#xCONFIG-SUFFIXx#.new#g' \
3037 -e 's#xDELETEOBJECTSx#0#g' \
3038 -e 's#xGRAFT-CONFIGx#.graft-config#g' \
3039 -e 's#xGRAFT-EXCLUDEx#.graft-exclude#g' \
3040 -e 's#xGRAFT-IGNOREx#.nograft#g' \
3041 -e 's#xGRAFT-INCLUDEx#.graft-include#g' \
3042 -e 's#xGRAFT-NEVERx##g' \
3043 -e 's#xLOGFILEx#/var/log/graft#g' \
3044 -e 's#xNEVERGRAFTx#0#g' \
3045 -e 's#xPACKAGEDIRx#/usr/local/pkgs#g' \
3046 -e 's#xPERLx#/usr/bin/perl#g' \
3047 -e 's#xPRESERVEPERMSx#0#g' \
3048 -e 's#xPRUNED-SUFFIXx#.pruned#g' \
3049 -e 's#xSUPERUSERx#1#g' \
3050 -e 's#xTARGETDIRx#/usr/local#g' \
3052 chmod +x graft
3053 /usr/bin/perl -wc graft
3054 graft syntax OK
3055 if [ -n "" ]; \
3056 then \
3057 AUTOIGNORE=1; \
3058 else \
3059 AUTOIGNORE=0; \
3060 fi; \
3061 sed \
3063 -e 's#xCONFIG-SUFFIXx#.new#g' \
3064 -e 's#xDELETEOBJECTSx#0#g' \
3065 -e 's#xDOCx#/usr/local/pkgs/graft-2.16/doc#g' \
3066 -e 's#xGRAFT-CONFIGx#.graft-config#g' \
3067 -e 's#xGRAFT-EXCLUDEx#.graft-exclude#g' \
3068 -e 's#xGRAFT-IGNOREx#.nograft#g' \
3069 -e 's#xGRAFT-INCLUDEx#.graft-include#g' \
3070 -e 's#xGRAFT-NEVERx##g' \
3071 -e 's#xLOGFILEx#/var/log/graft#g' \
3072 -e 's#xNEVERGRAFTx#0#g' \
3073 -e 's#xPACKAGEDIRx#/usr/local/pkgs#g' \
3074 -e 's#xPERLx#/usr/bin/perl#g' \
3075 -e 's#xPRESERVEPERMSx#0#g' \
3076 -e 's#xPRUNED-SUFFIXx#.pruned#g' \
3077 -e 's#xSUPERUSERx#1#g' \
3078 -e 's#xTARGETDIRx#/usr/local#g' \
3079 -e 's#xVERSIONx#2.16#g' \
3081 </pre>
3086 then manually create this directory using whatever procedures
3087 are appropriate for your operating system. </p>
3093 <pre>
3095 </pre>
3099 </p>
3101 <pre>
3103 </pre>
3106 documentation by executing: </p>
3108 <pre>
3109 make install
3110 </pre>
3114 <pre>
3115 mkdir -p /usr/local/pkgs/graft-2.16/bin
3116 cp graft /usr/local/pkgs/graft-2.16/bin
3118 for i in graft.1; \
3119 do \
3120 manpage=`basename $i`; \
3121 man=`expr $i : '.*\.\(.\)'`; \
3122 mkdir -p /usr/local/pkgs/graft-2.16/man/man$man; \
3123 cp $i /usr/local/pkgs/graft-2.16/man/man$man/$manpage; \
3125 done
3127 for i in graft.html graft.pdf graft.ps graft.txt; \
3128 do \
3129 mkdir -p /usr/local/pkgs/graft-2.16/doc; \
3130 cp doc/$i /usr/local/pkgs/graft-2.16/doc; \
3132 touch /usr/local/pkgs/graft-2.16/doc/.nograft; \
3133 done
3134 </pre>
3136 </ol>
3141 later date, please run the following commands: </p>
3143 <pre>
3144 make clean
3145 make install
3146 </pre>
3149 NOT reflect your current configuration. </p>
3154 RPM and Debian installation packages. Obviously you'll need one or more of
3156 system. </p>
3160 package in the current directory: </p>
3162 <pre>
3163 make rpm
3164 </pre>
3168 <pre>
3169 make deb
3170 </pre>
3172 <p> The creation of these packages is somewhat experimental. Please let the
3173 author know if you have issues. </p>
3175 <hr>
3178 bootstrap problem</a></h3>
3184 <p> <strong>However if you are a creator of an operating system
3185 distribution then this section may be relevant.</strong> </p>
3200 <pre>
3201 /usr/local/pkgs/graft-2.16
3202 /usr/local/pkgs/perl-5.18.2
3203 </pre>
3205 <p> you can resolve this dilemma by executing the following commands:
3206 </p>
3208 <pre>
3211 </pre>
3214 default package installation directory (as specified by
3217 </p>
3219 <p> If you don't wish to use the default directories you can use the
3223 <pre>
3224 /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
3225 /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
3226 </pre>
3230 </p>
3232 <pre>
3234 </pre>
3239 directory of the distribution. Thanks to Gordon Rowell for providing it.</p>
3245 below for details. </p>
3247 <hr>
3254 be compiled and installed in such a way that any package dependent
3255 files are referenced with the ACTUAL package installation directory
3261 separate multiple versions of the same package without any problems. </p>
3267 <p> All of the details concerning actions, package locations and target
3270 deprecated in favour of a log file). </p>
3274 <pre>
3275 graft -i [-P|u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
3276 graft -d [-D] [-u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
3277 graft -p [-D] [-u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
3278 graft -L
3279 </pre>
3283 <ol>
3287 <pre>
3288 graft -i [-C] [-P|u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
3289 </pre>
3291 <dl>
3294 <dd>
3295 <p> Install symbolic links from the package
3296 installation directory to the target directory.
3297 Requires superuser privileges if
3302 <dd>
3305 exclusion of files and/or directories whose
3306 names exactly match the values specified by
3311 exclusion of files and/or directories whose
3312 names exactly match the values specified by
3318 directory, if the directory contains a
3320 file. </p>
3323 reflect the behaviour of this option based on the
3325 are no objects specified for
3327 be silently ignored and will not appear in the help
3328 message nor in the manual page. </p>
3331 <dd>
3332 <p> Preserve modes and ownerships when creating new
3333 directories or copying files if
3336 preserve modes and ownerships if the option is not
3337 provided on the command line. </p>
3339 <p> Do not preserve modes and ownerships when
3340 creating new directories or copying files if
3343 Preserve modes and ownerships if the option is not
3344 provided on the command line. </p>
3348 <p> This option will be silently ignored if the
3352 reflect the behaviour of this option based on the
3354 option will be silently ignored and will not appear
3355 in the help message nor in the manual page if
3360 <dd>
3361 <p> Superuser privileges are not required when
3362 installing packages. </p>
3366 <p> This option is only available if
3371 reflect the behaviour of this option based on the
3373 option will be silently ignored and will not appear
3374 in the help message nor in the manual page if
3379 <dd>
3380 <p> Specify an alternate log file instead of the
3387 <pre>
3391 </pre>
3393 <p> This shows that a development version of
3400 that a conflict occurred during this
3402 was a symbolic link to something other than
3406 <dd>
3407 <p> List actions but do not perform them. Implies
3408 the very verbose option. Does not require
3409 superuser privileges regardless of the value of
3413 <dd>
3417 <dd>
3421 <dd>
3422 <p> Use the fully qualified named directory as the
3423 root directory for all graft operations. The source
3424 directory, target directory and log file will all
3425 be relative to this specific directory. </p>
3430 <dd>
3433 each package installation directory in the
3438 directory. (Yes that really is two
3440 installation directory is </p>
3442 <pre>
3443 /usr/local/depot/gzip-1.2.4
3444 </pre>
3447 </p>
3449 <pre>
3450 /usr/local
3451 </pre>
3456 <dd>
3460 qualified directory and it must exist. </p>
3465 <dd>
3467 a fully qualified directory, use it as the
3468 package installation directory. If
3470 directory, prepend it with the value of
3474 </dl>
3480 <pre>
3481 graft -d [-D] [-u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
3482 </pre>
3484 <dl>
3487 <dd>
3488 <p> Delete symbolic links from the package target
3489 directory to the package installation
3490 directory. Requires superuser privileges if
3495 <dd>
3496 <p> Delete empty directories if
3499 provided on the command line, notify the user
3500 that a directory has been emptied. </p>
3502 <p> Do not delete empty directories if
3505 directory has been emptied. If the option is
3506 not provided on the command line, delete empty
3507 directories. </p>
3510 reflect the behaviour of this option based on the
3514 <dd>
3515 <p> Superuser privileges are not required when
3516 deleting packages. </p>
3518 <p> This option is only available if
3523 reflect the behaviour of this option based on the
3525 option will be silently ignored and will not appear
3526 in the help message nor in the manual page if
3531 <dd>
3532 <p> Specify an alternate log file instead of the
3539 <pre>
3543 </pre>
3545 <p> This shows that a development version of
3549 entries indicate that conflicts occurred during
3550 this action - the files
3553 exist. </p>
3556 <dd>
3557 <p> List actions but do not perform them. Implies
3558 the very verbose option. Does not require
3559 superuser privileges regardless of the value of
3563 <dd>
3567 <dd>
3571 <dd>
3572 <p> Use the fully qualified named directory as the
3573 root directory for all graft operations. The source
3574 directory, target directory and log file will all
3575 be relative to this specific directory. </p>
3580 <dd>
3583 each package installation directory in the
3588 directory. (Yes that really is two
3590 installation directory is </p>
3592 <pre>
3593 /usr/local/depot/gzip-1.2.4
3594 </pre>
3597 </p>
3599 <pre>
3600 /usr/local
3601 </pre>
3606 <dd>
3610 qualified directory and it must exist. </p>
3615 <dd>
3617 a fully qualified directory, use it as the
3618 package installation directory. If
3620 directory, prepend it with the value of
3624 </dl>
3630 <pre>
3631 graft -p [-D] [-u] [-l log] [-n] [-v|V] [-r /rootdir] [-s|-t target] package(s)
3632 </pre>
3634 <dl>
3637 <dd>
3638 <p> Prune objects (files, links or directories)
3639 from the package target directory that are in
3640 conflict with the package installation
3641 directory. Requires superuser privileges if
3646 <dd>
3647 <p> Remove conflicting objects if
3651 is not provided on the command line. </p>
3653 <p> Rename conflicting objects to
3657 if the option is not provided in the command
3658 line. </p>
3660 <p> If a directory is to be removed and it is not
3661 empty, it will be renamed as
3663 warning message will be given regardless of the
3664 sense of this flag. </p>
3667 reflect the behaviour of this option based on the
3671 <dd>
3672 <p> Superuser privileges are not required when
3673 pruning packages. </p>
3675 <p> This option is only available if
3680 reflect the behaviour of this option based on the
3682 option will be silently ignored and will not appear
3683 in the help message nor in the manual page if
3688 <dd>
3689 <p> Specify an alternate log file instead of the
3696 <pre>
3698 </pre>
3700 <p> This shows that a development version of
3706 <dd>
3707 <p> List actions but do not perform them. Implies
3708 the very verbose option. Does not require
3709 superuser privileges regardless of the value of
3713 <dd>
3717 <dd>
3721 <dd>
3722 <p> Use the fully qualified named directory as the
3723 root directory for all graft operations. The source
3724 directory, target directory and log file will all
3725 be relative to this specific directory. </p>
3730 <dd>
3733 each package installation directory in the
3738 directory. (Yes that really is two
3740 installation directory is </p>
3742 <pre>
3743 /usr/local/depot/gzip-1.2.4
3744 </pre>
3747 </p>
3749 <pre>
3750 /usr/local
3751 </pre>
3756 <dd>
3760 qualified directory and it must exist. </p>
3765 <dd>
3767 a fully qualified directory, use it as the
3768 package installation directory. If
3770 directory, prepend it with the value of
3774 </dl>
3778 <pre>
3779 graft -L
3780 </pre>
3782 <dl>
3785 <dd>
3786 <p> This is a special mode and it overrides all
3787 other command line arguments. When present
3790 graft log file, the target directory, and the
3791 package directory in a form suitable for creating
3792 environment variables for Bourne like shells. The
3794 follows: </p>
3796 <pre>
3797 GRAFT_PERL=/usr/bin/perl
3798 GRAFT_LOGFILE=/var/log/graft
3799 GRAFT_TARGETDIR=/usr/local
3800 GRAFT_PACKAGEDIR=/usr/local/pkgs
3801 </pre>
3803 <p> You can set these environment variables using
3804 one of the following methods. </p>
3806 <pre>
3807 eval "$(graft -L)" # modern shells such as bash, zsh etc
3808 eval "`graft -L`" # older shells such as sh etc
3809 </pre>
3811 </dl>
3813 </ol>
3819 <p> Before creating the symbolic links from the target directory to
3821 will perform. Execute the following command: </p>
3823 <pre>
3825 </pre>
3830 directory will be used and the package installation directory will be
3831 taken from the fully qualified package argument or the default value
3832 will be prepended to the package argument if it is not fully qualified.
3833 </p>
3837 <ul>
3843 target. </p>
3854 </p>
3865 contents and any subdirectories will be bypassed by
3868 <li> <p> READING include file
3873 a list of file and/or directory names from the directory that
3880 <p> The file name mentioned in this message appears in the
3887 <p> The file name mentioned in this message does not appear in the
3894 <p> The directory name mentioned in this message appears
3896 in the directory currently being processed. It will be
3902 <p> The directory name mentioned in this message does not
3904 exists in the directory currently being processed. It will not
3907 <li> <p> READING exclude file
3912 a list of file and/or directory names from the directory that
3916 <li> <p> IGNORE include file
3924 so the latter file will be ignored. </p>
3929 <p> The file name mentioned in this message appears in the
3936 <p> The directory name mentioned in this message appears
3938 in the directory currently being processed. It will not be
3944 One of the following conditions was encountered: </p>
3946 <ul>
3948 <li> The package object is a directory and the
3949 target object exists but it not a directory.
3951 <li> The package object is not a directory and the
3952 target object exists and is not a symbolic
3953 link.
3955 <li> The package object is not a directory and the
3956 target object exists and is a symbolic link to
3957 something other than the package object.
3959 </ul>
3961 <p> Conflicts are ALWAYS reported on standard error. If you wish
3962 to see if the installation of a package will have any
3963 conflicts, you can execute: </p>
3965 <pre>
3967 </pre>
3970 is displayed then you can safely conclude that this package
3972 </p>
3974 </ul>
3977 package you would execute the command: </p>
3979 <pre>
3980 graft -i -n kermit-5A190
3981 </pre>
3983 You should see output resembling:
3985 <pre>
3986 Installing links to /usr/local/pkgs/kermit-5A190 in /usr/local
3987 Processing /usr/local/pkgs/kermit-5A190
3989 NOP /usr/local/pkgs/kermit-5A190/bin and /usr/local/bin are both directories
3990 Processing /usr/local/pkgs/kermit-5A190/bin
3993 NOP /usr/local/pkgs/kermit-5A190/man and /usr/local/man are both directories
3994 Processing /usr/local/pkgs/kermit-5A190/man
3995 NOP /usr/local/pkgs/kermit-5A190/man/man1 and /usr/local/man/man1 are both directories
3996 Processing /usr/local/pkgs/kermit-5A190/man/man1
3998 MKDIR /usr/local/doc
3999 Processing /usr/local/pkgs/kermit-5A190/doc
4006 NOP /usr/local/pkgs/kermit-5A190/lib and /usr/local/lib are both directories
4007 Processing /usr/local/pkgs/kermit-5A190/lib
4015 </pre>
4017 <p> This output shows you that most of the directories already exist
4019 in the relevant target directory to each of the files in the
4026 the directory on the NFS server under the file system in which it
4027 really lives. You should be familiar with the peculiarities of the
4029 any directories directly under mount points used by the
4037 actions, you can execute: </p>
4039 <pre>
4041 </pre>
4045 <pre>
4046 graft -i kermit-5A190
4047 </pre>
4050 conflict. If you wish to see more information you can specify one of
4051 the verbose flags. For a minimum of output you can execute: </p>
4053 <pre>
4054 graft -i -v kermit-5A190
4055 </pre>
4059 <pre>
4060 Processing /usr/local/pkgs/kermit-5A190
4061 Processing /usr/local/pkgs/kermit-5A190/bin
4062 Processing /usr/local/pkgs/kermit-5A190/man
4063 Processing /usr/local/pkgs/kermit-5A190/man/man1
4064 Processing /usr/local/pkgs/kermit-5A190/doc
4065 Processing /usr/local/pkgs/kermit-5A190/lib
4066 </pre>
4070 <pre>
4071 graft -i -V kermit-5A190
4072 </pre>
4076 links. </p>
4078 <pre>
4079 Installing links to /usr/local/pkgs/kermit-5A190 in /usr/local
4080 Processing /usr/local/pkgs/kermit-5A190
4082 NOP /usr/local/pkgs/kermit-5A190/bin and /usr/local/bin are both directories
4083 Processing /usr/local/pkgs/kermit-5A190/bin
4086 NOP /usr/local/pkgs/kermit-5A190/man and /usr/local/man are both directories
4087 Processing /usr/local/pkgs/kermit-5A190/man
4088 NOP /usr/local/pkgs/kermit-5A190/man/man1 and /usr/local/man/man1 are both directories
4089 Processing /usr/local/pkgs/kermit-5A190/man/man1
4091 NOP /usr/local/pkgs/kermit-5A190/doc and /usr/local/doc are both directories
4092 Processing /usr/local/pkgs/kermit-5A190/doc
4099 NOP /usr/local/pkgs/kermit-5A190/lib and /usr/local/lib are both directories
4100 Processing /usr/local/pkgs/kermit-5A190/lib
4108 </pre>
4119 <p> You may have the need to place only part of a package under the control
4122 <ul>
4124 <li> <p> The contents of one package conflict with another package.
4128 <li> <p> A package directory is obviously the exclusive domain of
4129 the package and no benefit will be gained by creating symbolic
4130 links to its files. For example
4134 installed the package such that it refers to its files by their
4138 </ul>
4142 <pre>
4144 </pre>
4148 <pre>
4149 /usr/local/pkgs/perl-5.18.2/lib/perl5/.nograft
4150 </pre>
4154 directory and anything below it would not be created. </p>
4160 <p> There may be the occasional need to include specific files and/or
4161 directories in a directory, rather than the entire directory tree itself. An
4162 example of such an occurrence would be the case where a package
4163 contains a number of subdirectories, only one of which is required to
4167 directories in a package directory by creating the file </p>
4169 <pre>
4170 .graft-include
4171 </pre>
4176 - one per line - of the files and/or directories you wish to include. </p>
4179 contains the following directories: </p>
4181 <pre>
4182 /usr/local/pkgs/a2ps-4.13b/bin
4183 /usr/local/pkgs/a2ps-4.13b/etc
4184 /usr/local/pkgs/a2ps-4.13b/include
4185 /usr/local/pkgs/a2ps-4.13b/info
4186 /usr/local/pkgs/a2ps-4.13b/lib
4187 /usr/local/pkgs/a2ps-4.13b/man
4188 /usr/local/pkgs/a2ps-4.13b/share
4189 </pre>
4195 contain </p>
4197 <pre>
4198 bin
4199 </pre>
4207 <p> There may be the occasional need to exclude specific files and/or
4208 directories from a directory, rather than the entire directory itself. An
4209 example of such an occurrence would be the case where files from different
4211 names for a number of their configuration files for example. </p>
4214 directories from a package directory by creating the file </p>
4216 <pre>
4217 .graft-exclude
4218 </pre>
4223 - one per line - of the files and/or directories you wish to exclude. </p>
4227 <pre>
4228 /usr/local/pkgs/sudo-1.5.3/etc/sudoers
4229 </pre>
4233 <pre>
4234 /usr/local/etc/sudoers
4235 </pre>
4239 <pre>
4240 /usr/local/pkgs/sudo-1.5.3/etc/visudo
4241 </pre>
4245 <pre>
4246 /usr/local/etc/visudo
4247 </pre>
4251 <pre>
4252 /usr/local/pkgs/sudo-1.5.3/etc/.graft-exclude
4253 </pre>
4257 <pre>
4258 sudoers
4259 </pre>
4272 package directory as a repository for configuration files. In this case you
4275 directory. Files in conflict would also be copied but would have a default
4277 Conflict discovery is achieved using a simple 32-bit CRC check. This
4278 feature has been added to assist operating system distributors manage
4279 system configuration files, specifically it was added at the request of the
4281 distribution. </p>
4283 <p> Consider the following example. You may wish to upgrade the
4285 order to preserve any local user modifications to the relevant
4287 package as follows: </p>
4289 <pre>
4290 /usr/local/pkgs/openssh-server-6.61/etc/default/.graft-config
4291 /usr/local/pkgs/openssh-server-6.61/etc/init.d/.graft-config
4292 /usr/local/pkgs/openssh-server-6.61/etc/init/.graft-config
4293 /usr/local/pkgs/openssh-server-6.61/etc/network/if-up.d/.graft-config
4294 /usr/local/pkgs/openssh-server-6.61/etc/pam.d/.graft-config
4295 /usr/local/pkgs/openssh-server-6.61/etc/ufw/applications.d/.graft-config
4296 /usr/local/pkgs/openssh-server-6.61/lib/systemd/system/.graft-config
4297 </pre>
4299 <p> The other directories in the distribution would not require any control
4300 files. </p>
4302 <p> Imagine that the local administrator has made some changes to
4304 to support two-factor authentication for example. As the distribution
4305 maintainer you do not want to reverse this local change so when the local
4309 their changes with any new features supported by the upgrade. </p>
4311 <p> To take full advantage of this feature you may need to explicitly set the
4312 target directory as follows: </p>
4314 <pre>
4315 graft -i -t / openssh-server-6.61
4316 </pre>
4322 <p> Some packages can be successfully used when only part of their
4324 recalcitrant and need some special hand holding which can only be
4329 When installed in its own directory </p>
4331 <pre>
4332 /usr/local/pkgs/perl-5.18.2
4333 </pre>
4337 <pre>
4341 </pre>
4347 <pre>
4348 touch /usr/local/pkgs/perl-5.18.2/lib/.nograft
4349 graft -i perl-5.18.2
4350 </pre>
4352 or
4354 <pre>
4355 graft -it /usr/local/bin perl-5.18.2/bin
4356 graft -it /usr/local/man perl-5.18.2/man
4357 </pre>
4362 <pre>
4364 </pre>
4368 <pre>
4373 </pre>
4384 this problem. </p>
4388 <pre>
4391 </pre>
4393 <p> Using this approach, the correct executables and manual pages are
4395 directories. </p>
4400 Packages</a></h3>
4402 <p> If you wish to upgrade a package - let's assume you wish to upgrade
4404 these steps. </p>
4408 <pre>
4409 /usr/local/pkgs/kermit-6.0.192
4410 </pre>
4412 <p> Once you'd tested it to your satisfaction, you'd need to delete the
4416 <pre>
4417 graft -d -n kermit-5A190
4418 </pre>
4422 <pre>
4423 Uninstalling links from /usr/local to /usr/local/pkgs/kermit-5A190
4424 Processing /usr/local/pkgs/kermit-5A190
4425 Processing /usr/local/pkgs/kermit-5A190/bin
4426 UNLINK /usr/local/bin/kermit
4427 UNLINK /usr/local/bin/wart
4428 Processing /usr/local/pkgs/kermit-5A190/man
4429 Processing /usr/local/pkgs/kermit-5A190/man/man1
4430 UNLINK /usr/local/man/man1/kermit.1
4431 Processing /usr/local/pkgs/kermit-5A190/doc
4432 UNLINK /usr/local/doc/ckccfg.doc
4433 UNLINK /usr/local/doc/ckuins.doc
4434 UNLINK /usr/local/doc/ckc190.upd
4435 UNLINK /usr/local/doc/ckcker.upd
4436 UNLINK /usr/local/doc/ckaaaa.hlp
4437 UNLINK /usr/local/doc/ckuaaa.hlp
4438 Processing /usr/local/pkgs/kermit-5A190/lib
4439 UNLINK /usr/local/lib/ckedemo.ini
4440 UNLINK /usr/local/lib/ckeracu.ini
4441 UNLINK /usr/local/lib/ckermit.ini
4442 UNLINK /usr/local/lib/ckermod.ini
4443 UNLINK /usr/local/lib/cketest.ini
4444 UNLINK /usr/local/lib/ckevt.ini
4445 UNLINK /usr/local/lib/ckurzsz.ini
4446 UNLINK /usr/local/lib/.testing
4447 </pre>
4449 <p> If you're happy with the output from the test deletion you can delete
4451 failure occurs unless you use one of the verbose options. </p>
4455 <pre>
4456 graft -dV kermit-5A190
4457 </pre>
4461 <pre>
4462 Uninstalling links from /usr/local to /usr/local/pkgs/kermit-5A190
4463 Processing /usr/local/pkgs/kermit-5A190
4464 Processing /usr/local/pkgs/kermit-5A190/bin
4465 UNLINK /usr/local/bin/kermit
4466 UNLINK /usr/local/bin/wart
4467 Processing /usr/local/pkgs/kermit-5A190/man
4468 Processing /usr/local/pkgs/kermit-5A190/man/man1
4469 UNLINK /usr/local/man/man1/kermit.1
4470 Processing /usr/local/pkgs/kermit-5A190/doc
4471 UNLINK /usr/local/doc/ckccfg.doc
4472 UNLINK /usr/local/doc/ckuins.doc
4473 UNLINK /usr/local/doc/ckc190.upd
4474 UNLINK /usr/local/doc/ckcker.upd
4475 UNLINK /usr/local/doc/ckaaaa.hlp
4476 UNLINK /usr/local/doc/ckuaaa.hlp
4477 EMPTY /usr/local/doc is now empty. Delete manually if necessary.
4478 Processing /usr/local/pkgs/kermit-5A190/lib
4479 UNLINK /usr/local/lib/ckedemo.ini
4480 UNLINK /usr/local/lib/ckeracu.ini
4481 UNLINK /usr/local/lib/ckermit.ini
4482 UNLINK /usr/local/lib/ckermod.ini
4483 UNLINK /usr/local/lib/cketest.ini
4484 UNLINK /usr/local/lib/ckevt.ini
4485 UNLINK /usr/local/lib/ckurzsz.ini
4486 </pre>
4490 deletion, it will either notify you or delete the directory depending
4492 line options. It's probably better practise not to automatically
4493 delete empty directories as they may be used by other packages - such
4494 as lock file directories for example. </p>
4497 to do this immediately as some legacy systems may depend on features
4498 provided by the older version or you may feel the need for further
4499 testing before feeling confident that the old version can be removed):
4500 </p>
4502 <pre>
4503 rm -rf /usr/local/pkgs/kermit-5A190
4504 </pre>
4508 <pre>
4509 graft -i -n kermit-6.0.192
4510 </pre>
4514 package by executing: </p>
4516 <pre>
4517 graft -i kermit-6.0.192
4518 </pre>
4523 control</a></h3>
4527 installation. </p>
4530 It consists of three files installed in: </p>
4532 <pre>
4533 /usr/local/bin/weblint
4534 /usr/local/lib/global.weblintrc
4535 /usr/local/man/man1/weblint.1
4536 </pre>
4538 <p> The first step is to create a new copy of the package in its own
4539 directory: </p>
4541 <pre>
4542 /usr/local/pkgs/weblint-1.017
4543 </pre>
4545 <p> Ensure that any references to library files are now made to
4547 </p>
4553 <pre>
4554 graft -pV weblint-1.017
4555 </pre>
4559 <pre>
4560 Pruning files in /usr/local which conflict with /usr/local/pkgs/weblint-1.017
4561 Processing /usr/local/pkgs/weblint-1.017
4562 Processing /usr/local/pkgs/weblint-1.017/man
4563 Processing /usr/local/pkgs/weblint-1.017/man/man1
4564 RENAME /usr/local/man/man1/weblint.1
4565 Processing /usr/local/pkgs/weblint-1.017/bin
4566 RENAME /usr/local/bin/weblint
4567 Processing /usr/local/pkgs/weblint-1.017/lib
4568 RENAME /usr/local/lib/global.weblintrc
4569 </pre>
4571 <p> If you elected to delete conflicting files instead of renaming them
4572 you'd use: </p>
4574 <pre>
4575 graft -pDV weblint-1.017
4576 </pre>
4580 <pre>
4581 Pruning files in /usr/local which conflict with /usr/local/pkgs/weblint-1.017
4582 Processing /usr/local/pkgs/weblint-1.017
4583 Processing /usr/local/pkgs/weblint-1.017/man
4584 Processing /usr/local/pkgs/weblint-1.017/man/man1
4585 UNLINK /usr/local/man/man1/weblint.1
4586 Processing /usr/local/pkgs/weblint-1.017/bin
4587 UNLINK /usr/local/bin/weblint
4588 Processing /usr/local/pkgs/weblint-1.017/lib
4589 UNLINK /usr/local/lib/global.weblintrc
4590 </pre>
4593 place: </p>
4595 <pre>
4596 graft -i weblint-1.017
4597 </pre>
4601 <p> If we renamed conflicting files, they can be removed once the
4604 <pre>
4605 rm /usr/local/man/man1/weblint.1.pruned
4606 rm /usr/local/bin/weblint.pruned
4607 rm /usr/local/lib/global.weblintrc.pruned
4608 </pre>
4616 one of the following possibilities: </p>
4618 <center>
4620 <tr>
4621 <th>
4622 Package Object
4623 </th>
4625 <th>
4626 Target Object
4627 </th>
4628 </tr>
4630 <tr>
4631 <td>
4632 directory
4633 </td>
4635 <td>
4636 not a directory
4637 </td>
4638 </tr>
4640 <tr>
4641 <td>
4642 file
4643 </td>
4645 <td>
4646 directory
4647 </td>
4648 </tr>
4650 <tr>
4651 <td>
4652 file
4653 </td>
4655 <td>
4656 file
4657 </td>
4658 </tr>
4660 <tr>
4661 <td>
4662 file
4663 </td>
4665 <td>
4666 symbolic link to something other than the package object
4667 </td>
4668 </tr>
4669 </table>
4670 </center>
4673 package it will report the conflict and exit. </p>
4675 <p> Resolving the conflict depends on the nature of the conflict and is
4676 beyond the scope of this discussion - however most conflicts will
4678 the same package actually installed in the target directory or a file
4679 name clash between two (or more) different packages. </p>
4681 <p> Conflicts arising from the pre-existence of a package in the target
4686 <p> File name clash conflicts can be resolved by the use of either a
4691 </p>
4694 report the conflict and continue deleting the remainder of the package.
4696 possible. Conflicts that arise during deletion will probably be the
4697 result of an incorrectly installed package or the installation of other
4700 <p> Conflict messages are written to standard error. All other messages
4701 are written to standard output. To quickly determine if a package will
4705 <pre>
4707 </pre>
4709 <p> If you don't see any output then you can safely assume that there will
4712 <p> See the comprehensive table above describing how
4720 under the following conditions: </p>
4722 <center>
4724 <tr>
4725 <th>
4726 Exit Status
4727 </th>
4729 <th>
4730 Condition
4731 </th>
4732 </tr>
4734 <tr>
4735 <td>
4736 <center>
4738 </center>
4739 </td>
4741 <td>
4742 All operations succeeded.
4743 </td>
4744 </tr>
4746 <tr>
4747 <td>
4748 <center>
4750 </center>
4751 </td>
4753 <td>
4754 A conflict occurred during installation.
4755 </td>
4756 </tr>
4758 <tr>
4759 <td>
4760 <center>
4762 </center>
4763 </td>
4765 <td>
4766 Command line syntax was incorrect.
4767 </td>
4768 </tr>
4770 <tr>
4771 <td>
4772 <center>
4774 </center>
4775 </td>
4777 <td>
4778 One or more packages listed on the command line does not
4779 exist. Other valid packages listed on the command line were
4780 processed correctly.
4781 </td>
4782 </tr>
4784 <tr>
4785 <td>
4786 <center>
4788 </center>
4789 </td>
4791 <td>
4793 result of a permission error. Any other error condition will
4794 override this condition.
4795 </td>
4796 </tr>
4797 </table>
4798 </center>
4800 <hr>
4803 management tools</a></h2>
4805 <p> Most Unix vendors have released their own package management tools with
4811 to these package managers rather than a competitor. The author has used
4813 </p>
4815 <ul>
4817 <li> <p> Many useful packages available in the public domain and from
4818 other commercial sources are not shipped with most flavours of
4820 environment beyond the set of packages provided by your vendor.
4821 Vendor based packages can still be maintained using the vendor's
4823 </p>
4825 <li> <p> The vendor based management tools are usually used to maintain
4826 single instances of a package on each machine. It is often
4827 difficult to have multiple versions of the same package coexisting
4829 versions of a package to support legacy, production and development
4830 requirements simultaneously. </p>
4832 <li> <p> Another common problem with vendor supplied software is
4833 the speed at which upgrades are available. The large vendors are not
4834 known for providing quick fixes to many of their packages. (Notable
4835 exceptions to this are the vendors of operating systems based on
4836 open source software who can draw on the enormous number of users
4837 who submit patches because the source code is available). Using
4839 a package (if one exists of course) and install it in a different
4840 location to the vendor copy. When the vendor releases a new version of
4841 the package, it can be installed using the vendor's package management
4843 version of the package is better than the public domain version). </p>
4845 <li> <p> Sometimes, a vendor's package doesn't quite perform in the
4846 manner you'd like. It may be making assumptions about your file
4847 system(s) that are incorrect for your environment or it may not
4848 have all the features you'd like. If an alternative package is
4849 available - either in the public domain or from other commercial
4852 </ul>
4854 <hr>
4860 <pre>
4861 <a href="http://peters.gormand.com.au/Home/tools/graft">http://peters.gormand.com.au/Home/tools/graft</a>
4862 </pre>
4864 <hr>
4871 <p> You should have received a copy of the GNU General Public License
4872 along with this program; if not, write to the Free Software Foundation,
4874 it from the Free Software Foundation's web site: </p>
4876 <pre>
4879 </pre>
4882 <hr>
4884 </body>
4885 </html>
4887 <!-- html code generated by txt2tags 2.6. (http://txt2tags.org) -->
4888 <!-- cmdline: txt2tags -t html pkgmanagement.t2t -->
4889 </BODY></HTML>