| blob | 445836853d7661bf838c9d18834d48374a24235a |
2 <head>
9 <!--
10 This manual is for Qi (version 1.0-rc4,
11 30 Jan 2017), which is a simple source builder and package manager.
13 Copyright (C) 2015, 2016, 2017 Matias A. Fonzo, Argentina,
14 Santiago del Estero.
16 Permission is granted to copy, distribute and/or modify this
17 document under the terms of the GNU Free Documentation License,
18 Version 1.3 or any later version published by the Free Software
19 Foundation; with no Invariant Sections, with no Front-Cover Texts,
20 and with no Back-Cover Texts. A copy of the license is included
21 in the section entitled "GNU Free Documentation License".
22 -->
36 </head>
37 <body>
41 <ul>
45 <ul>
48 </li></ul>
51 <ul>
56 </li></ul>
58 <ul>
60 <ul>
63 </li></ul>
67 <ul>
69 </li></ul>
70 </li></ul>
72 <ul>
74 </li></ul>
78 <li><a name="toc_GNU-Free-Documentation-License" href="#GNU-Free-Documentation-License">Appendix A GNU Free Documentation License</a>
80 </li></ul>
81 </div>
87 <p><hr>
91 </div>
110 </ul>
114 </pre>
116 del Estero.
118 <p>The Qi home page can be found at <a href="http://www.dragora.org">http://www.dragora.org</a>.
119 Send bug reports or suggestions to <a href="mailto:dragora-users@nongnu.org">dragora-users@nongnu.org</a>.<!-- /@w -->
123 <p><hr>
128 </div>
133 Qi is a source builder and a package manager:
135 <p>It contains a set of (individual) tools to build, install, remove, and
136 upgrade software packages. It follows the philosophy of simplicity
137 without adding too many features, such as those that can be found in
138 popular package managers. Basically it does two things: builds
139 packages and manages them.
141 <p>Qi constructs the sources using recipe names, files that contain
142 specific instructions to build every source. As result, a binary
143 package is obtained which can be installed, removed, upgraded, or
144 inspected in the system.
146 <p>The packages are managed thanks to an external tool called
148 packages under a single directory hierarchy, it was inspired by both
149 Depot (Carnegie Mellon University) and Stow (Bob Glickstein). In this
150 aspect, Qi complements Graft: it can work with packages, check them,
151 solve conflicts, and more...
155 <p><hr>
160 </div>
165 The synopsis to invoke Qi is:
168 </pre>
171 <dl>
174 <br><dt>‘<samp><span class="samp">pkgadd</span></samp>’<dd>Add the packages to the system using <em>graft(1)</em> for linking.
176 <br><dt>‘<samp><span class="samp">pkgremove</span></samp>’<dd>Remove the packages from the system.
178 <br><dt>‘<samp><span class="samp">pkgupgrade</span></samp>’<dd>Upgrade software packages.
180 <br><dt>‘<samp><span class="samp">pkgbuild</span></samp>’<dd>Build packages using recipe files.
182 <br><dt>‘<samp><span class="samp">pkgorder</span></samp>’<dd>Resolves the build order through .order files.
184 <br><dt>‘<samp><span class="samp">pkgerupt</span></samp>’<dd>Examine packages for debugging purposes.
188 </pre>
191 <p>There are global or common options for the commands, as well as specific to each one.
193 <br><dt>‘<samp><span class="samp">-h</span></samp>’<dd>Show options for the given command and exit.
197 </pre>
198 <strong>Options for command ‘</strong><samp><span class="samp">pkgadd</span></samp><strong>’:</strong>
200 <br><dt>‘<samp><span class="samp">-f</span></samp>’<dd>Force package installation (implies -p).
202 <br><dt>‘<samp><span class="samp">-P</span></samp>’<dd>Extract package on an installation tree.
210 <br><dt>‘<samp><span class="samp">-t</span></samp>’<dd>Target directory for linking.
216 <br><dt>‘<samp><span class="samp">-V</span></samp>’<dd><em>graft(1)</em> very verbose.
218 <br><dt>‘<samp><span class="samp">-w</span></samp>’<dd>Warn about the files that will be linked.
222 </pre>
223 <strong>Options for command ‘</strong><samp><span class="samp">pkgremove</span></samp><strong>’:</strong>
225 <br><dt>‘<samp><span class="samp">-k</span></samp>’<dd>Keep (don't delete) package directory.
227 <br><dt>‘<samp><span class="samp">-P</span></samp>’<dd>Remove from an installation tree.
235 <br><dt>‘<samp><span class="samp">-t</span></samp>’<dd>Target directory for unlinking.
241 <br><dt>‘<samp><span class="samp">-V</span></samp>’<dd><em>graft(1)</em> very verbose.
245 </pre>
246 <strong>Options for command ‘</strong><samp><span class="samp">pkgupgrade</span></samp><strong>’:</strong>
248 <br><dt>‘<samp><span class="samp">-k</span></samp>’<dd>Keep (don't delete) package directory.
264 <br><dt>‘<samp><span class="samp">-w</span></samp>’<dd>Warn about packages that will be upgraded.
268 </pre>
269 <strong>Options for command ‘</strong><samp><span class="samp">pkgbuild</span></samp><strong>’:</strong>
275 <p>Default value is obtained via <em>uname(1)</em> as ‘<samp><span class="samp">uname -m</span></samp>’.
279 <p>This option increment the release number when a package is produced.
281 <br><dt>‘<samp><span class="samp">-j</span></samp>’<dd>Parallel jobs for the compiler
287 <br><dt>‘<samp><span class="samp">-k</span></samp>’<dd>Keep (don't delete) ‘<samp><span class="samp">${srcdir}</span></samp>’ and ‘<samp><span class="samp">${destdir}</span></samp>’.
291 <br><dt>‘<samp><span class="samp">-o</span></samp>’<dd>Where the produced packages are written.
297 <br><dt>‘<samp><span class="samp">-U</span></samp>’<dd>Perform package upgrade after build.
303 </pre>
304 <strong>Options for command ‘</strong><samp><span class="samp">pkgorder</span></samp><strong>’:</strong>
311 Some influential environment variables:
313 <br><dt>‘<samp><span class="samp">QICFLAGS</span></samp>’<dd>C compiler flags for building packages.
317 <br><dt>‘<samp><span class="samp">QICXXFLAGS</span></samp>’<dd>C++ compiler flags for building packages.
321 <br><dt>‘<samp><span class="samp">QILDFLAGS</span></samp>’<dd>Linker flags for building packages.
325 <br><dt>‘<samp><span class="samp">DOPOST</span></samp>’<dd>post-install script control variable.
327 <p>The <samp><span class="env">DOPOST</span></samp> variable is currently used for <samp><span class="command">pkgadd</span></samp>,
328 <samp><span class="command">pkgupgrade</span></samp>, <samp><span class="command">pkgbuild</span></samp> (when option -U is given).
331 script (if any).
337 <p>This is used by: <samp><span class="command">pkgadd</span></samp>, <samp><span class="command">pkgremove</span></samp>,
338 <samp><span class="command">pkgupgrade</span></samp>, <samp><span class="command">pkgbuild</span></samp>.
340 <br><dt>‘<samp><span class="samp">TMPDIR</span></samp>’<dd>Temporary directory (by default <em>/tmp</em>).
342 <p><samp><span class="env">TMPDIR</span></samp> is expanded with random numbers for major security.
344 <p>This is used by: <samp><span class="command">pkgbuild</span></samp>, <samp><span class="command">pkgerupt</span></samp>.
345 </dl>
350 <ul>
351 <li>Command names has been prefixed with ‘<samp><span class="samp">pkg</span></samp>’ to facilitate the
352 set in relation to its purpose.
355 prefix of Qi.
357 <li>All the options can be mixed. Options specified in the
360 default (internal) values will be used instead.
361 </ul>
365 <p><hr>
370 </div>
375 <samp><span class="file">qirc</span></samp> is the configuration file for Qi used at runtime during the
376 installation, removal of a package or when a recipe is built. This
377 file is optional, and it can be useful to define variables and
378 configure external tools (such as a download manager) for default use.
380 <ul>
383 <li>Declaration of values should only take one line, no line break.
385 <li>Assignments like ‘<samp><span class="samp">name=$var</span></samp>’ are only interpreted as
386 literal.
387 </ul>
390 specified in the configuration file. For more information, see
397 Effective user.
400 System-wide.
401 </ol>
403 <p>If you intend to run Qi for a specific user, you should copy the file
404 ‘<samp><span class="samp">${sysconfdir}/qirc</span></samp>’ to <samp><span class="env">${HOME}/.qirc</span></samp> setting
405 ‘<samp><span class="samp">${packagedir}</span></samp>’ and ‘<samp><span class="samp">${targetdir}</span></samp>’ for your <samp><span class="env">$HOME</span></samp>.
409 <p><hr>
414 </div>
419 A package is a suite of programs usually distributed in binary form
420 which may also contain manual pages, documentation, or any other file
421 associated to a specific software.
427 ‘<samp><span class="samp">${packagedir}</span></samp>’ and ‘<samp><span class="samp">${targetdir}</span></samp>’:
429 <p>‘<samp><span class="samp">${packagedir}</span></samp>’ is a common directory tree where the package contents
430 is decompressed (resides). By default the tree is located at
433 <p>‘<samp><span class="samp">${targetdir}</span></samp>’ is a target directory where the links will be
434 made taking ‘<samp><span class="samp">${packagedir}/package_name</span></samp>’ into account.
436 <p>Packages are installed in self-contained directory trees and symbolic
437 links from a common area are made to the package files. This allows
438 multiple versions of the same package to co-exist on the one system.
440 <p>All the links to install or to remove a package are managed using
442 at the same time, certain conflicts may arise between the packages.
444 <p>According to the User's Guide of Graft<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>,
445 a conflict is defined as one of the following conditions:
447 <ul>
448 <li>If the package object is a directory and the target object exists
449 but is not a directory.
451 <li>If the package object is not a directory and the target object
452 exists and is not a symbolic link.
454 <li>If the package object is not a directory and the target object
455 exists and is a symbolic link to something other than the package
456 object.
457 </ul>
460 conflict occurs. But when a package that is going to be removed is in
462 are not in conflict, leaving the links belonging to the original
463 package. This behavior can be changed if the option -p is specified
464 (see the examples below).
469 This sort order is particularly useful just before the actual package
470 installation, because it helps to understand how the package
471 installation works:
474 <li>Detects and reports if the package is already installed.
476 <li>Ignores some signals up to completing the installation:
477 HUP INT QUIT ABRT TERM.
479 <li>The integrity of the file (package) is checked.
481 <li>Creates required directory for the package as
484 <li>Decompress the content of the package in
487 <li>A test of the package is performed before completing the
488 installation to see if there are no conflicts with another package.
489 This is the default behavior if -p is not supplied.
492 the package installation directory to the target directory.
494 <li>If the meta file is readable, the description will be shown for
495 the package.
497 <li>Run post install instructions from <samp><span class="file">post-install</span></samp>, if any.
498 </ol>
500 <p class="noindent"><em>Usage:</em> pkgadd [-hfpVw] [-P <DIR>] [-t <DIR>] [package.tlz ...]
502 <p>To install a single package, simply type:
505 </pre>
506 <p>To install multiple packages at once:
509 </pre>
510 <p>Warn about the files that will be linked:
513 </pre>
514 <ul>
515 <li>This is to verify the content of a package before installing it.
516 </ul>
518 <p>See what happens when a package is installed (very verbose):
521 </pre>
522 <ul>
523 <li>This is for a detailed (long) output.
524 </ul>
526 <p>Installing in a different directory tree and target:
529 </pre>
530 <p>When a package is already installed, <samp><span class="command">pkgadd</span></samp> refuses to
531 continue. This is to keep some control over the database of your
532 packages, if you really want to force the installation of a package,
533 you can use the -f option (which implies -p). See below.
537 <p>Remove objects (files, links or directories) from the target
538 directory that are in conflict with the package directory:
541 </pre>
542 <p>When the -p option is used, it proceeds to install the package
543 normally, but first will try to remove any conflict. Use it with care,
544 combine this option with -V.
549 This sort order is particularly useful just before the actual package
550 deinstallation, because it helps to understand how the package
551 deinstallation works:
554 <li>Look for a package name to remove inside of
555 ‘<samp><span class="samp">${packagedir}</span></samp>’. Package names must be specified using the full
556 package name, such as "name-version-arch+release.tlz" or specifying the
557 package name directory.
559 <li>Ignores some signals up to completing the deinstallation:
560 HUP INT QUIT ABRT TERM.
563 the package installation directory to the target directory:
565 <p>If a conflict exists with another package, those links that are not in
566 conflict will be preserved. It's possible to prune all the conflicts
567 using the -p option.
569 <li>Remove directories made empty by package deletion. This has
570 effect on ‘<samp><span class="samp">${targetdir}</span></samp>’ but not for ‘<samp><span class="samp">${packagedir}</span></samp>’.
572 <li>The package directory is deleted if the option -k is not
573 supplied.
574 </ol>
576 <p class="noindent"><em>Usage:</em> pkgremove [-hkpV] [-P <DIR>] [-t <DIR>] [package_name ...]
578 <p>To remove a package, just execute the command:
581 </pre>
582 <p>To remove multiple versions of the same package:
585 </pre>
586 <p>To remove multiple packages at once:
589 </pre>
590 <p>Detailed output (very verbose):
593 </pre>
594 <p>Removing from a different directory tree and target:
597 </pre>
598 <p>Pruning conflicts:
601 </pre>
605 This sort order is particularly useful just before the actual package
606 upgrade, because it helps to understand how the package upgrade works:
609 <li>Prepare temporary location for the incoming package.
611 <li>Pre-install incoming package into the temporary location.
613 <li>Remove packages under the same name: this is considered
614 as the old packages. (Default behaviour if -k is not supplied).
618 <li>Delete temporary location of the package.
619 </ol>
621 <p class="noindent"><em>Usage:</em> pkgupgrade [-hkVw] [-P <DIR>] [-t <DIR>] [package.tlz ...]
623 <p>Upgrading a package is simple as:
626 </pre>
627 <p class="noindent">‘<samp><span class="samp">pkgupgrade</span></samp>’ uses <samp><span class="command">pkgadd</span></samp> and <samp><span class="command">pkgremove</span></samp> to
628 upgrade software packages. So it inherits the properties of each
629 utility, except here, only the essential options are provided. For
630 example, the option -V (for a detailed output) belongs to when these
631 utilities are invoked. The options -P and -t work in the same way as
632 the previous examples for <samp><span class="command">pkgadd</span></samp>, <samp><span class="command">pkgremove</span></samp>.
633 ‘<samp><span class="samp">pkgupgrade</span></samp>’ will try to update the package or to install it
634 (in case it has not been installed).
636 <p>To see what packages will be updated (if any), always type:
639 </pre>
643 <ul>
644 <li>Some signals like HUP INT QUIT ABRT TERM are ignored on the
645 package installation or deinstallation. The intention is to ignore
646 the cancellation while the package is being installed or removed (e.g.
647 Ctrl+C, terminal window closed, etc.). The installation or removal
648 of a package can be crucial for the proper functioning of the system.
650 <li>The meta file is read from the directory where the package is
651 found.
653 <li>A post-install script is read from
654 ‘<samp><span class="samp">${packagedir}/package_name/var/lib/qi/post-install/name.install</span></samp>’.
656 <li>Default behavior is to upgrade or install a package removing old
657 packages, this is "packages found under the same name". If you want to
658 preserve the multiple versions of the same package, you must pass the
659 -k option.
660 </ul>
664 <p><hr>
669 </div>
674 A recipe is a file telling qi what to do. Most often, the recipe
675 tells qi how to build a binary package from a source tarball.
677 <p>A recipe has two parts: a list of variable definitions and a list of
678 sections. By convention, the syntax of a section is:
681 section lines
682 }
683 </pre>
684 <p>The section name is followed by parentheses, one space and an opening
685 brace. The line finishing the section contains just a closing brace.
686 The section names or the function names currently recognized are
689 <p>The ‘<samp><span class="samp">build</span></samp>’ section is an augmented shell script. This is the main
691 build and produce a package.
696 A "variable" is a <strong>shell variable</strong> defined either in <samp><span class="file">qirc</span></samp>
697 or in a recipe to represent a string of text, called the variable's
698 "value". These values are substituted by explicit request in the
699 definitions of other variables or in calls to external commands.
701 <p>Variables can represent lists of file names, options to pass to
702 compilers, programs to run, directories to look in for source files,
703 directories to write output in, or anything else you can imagine.
705 <p>Definitions of variables in qi have four levels of precedence.
706 Options which define variables from the command-line override those
707 specified in the <samp><span class="file">qirc</span></samp> file, while variables defined in the recipe
708 override those specified in <samp><span class="file">qirc</span></samp>, taking priority over those
709 variables settled by options via command-line. Finally, some variables
710 (arch, jobs, outdir, worktree, tardir, netget, rsync) have default
711 values if they are not defined anywhere.
713 <p>Options that set variables through the command-line can only reference
714 variables defined in <samp><span class="file">qirc</span></samp> and variables with default values.
716 <p>Definitions of variables in <samp><span class="file">qirc</span></samp> can only reference variables
717 previously defined in <samp><span class="file">qirc</span></samp> and variables with default values.
719 <p>Definitions of variables in the recipe can only reference variables
720 settled by command-line, variables previously defined in the recipe,
721 variables defined in <samp><span class="file">qirc</span></samp>, and variables with default values.
726 The three variables ‘<samp><span class="samp">arch</span></samp>’, ‘<samp><span class="samp">jobs</span></samp>’, and ‘<samp><span class="samp">outdir</span></samp>’ can
727 only be set using command line options or in <samp><span class="file">qirc</span></samp>. If not
728 specified, they have default values.
730 <p>‘<samp><span class="samp">arch</span></samp>’ is the architecture to compose the package name. Its
731 value is available in the recipe as ‘<samp><span class="samp">${arch}</span></samp>’. Default value is
734 <p>‘<samp><span class="samp">jobs</span></samp>’ is the number of jobs to pass to the compiler. Its
735 default value is available in the recipe as ‘<samp><span class="samp">${jobs}</span></samp>’. Defaults
738 <p>‘<samp><span class="samp">outdir</span></samp>’ is the directory where the produced packages are
739 written. This variable cannot be redefined in the recipe. Defaults to
742 <p>‘<samp><span class="samp">worktree</span></samp>’ is the working tree where archives, patches, and
743 recipes are expected. This variable cannot be redefined in the
746 <p>The variable ‘<samp><span class="samp">tardir</span></samp>’ is defined in the recipe to the directory
747 where the tarball containing the source can be found. The full name of
748 the tarball is commonly used as ‘<samp><span class="samp">${tardir}/$tarname</span></samp>’. A value
749 of ‘<samp><span class="samp">.</span></samp>’ for ‘<samp><span class="samp">tardir</span></samp>’ sets it to the value of the CWD (Current
750 Working Directory), this means, from where the recipe is located.
752 <p>The two variables ‘<samp><span class="samp">srcdir</span></samp>’ and ‘<samp><span class="samp">destdir</span></samp>’ can be defined in
753 the recipe, as any other variable, but if they are not, Qi uses default
754 values for them when building the package.
756 <p>‘<samp><span class="samp">srcdir</span></samp>’ contains the source code to be compiled, and defaults to
759 <p>‘<samp><span class="samp">destdir</span></samp>’ is the place where the built package will be installed,
760 and defaults to ‘<samp><span class="samp">${TMPDIR}/package-${program}</span></samp>’.
762 <p>If ‘<samp><span class="samp">pkgname</span></samp>’ is left undefined, the special variable
763 ‘<samp><span class="samp">program</span></samp>’ is assigned by default. If ‘<samp><span class="samp">pkgversion</span></samp>’ is left
764 undefined, the special variable ‘<samp><span class="samp">version</span></samp>’ is assigned by default.
766 <p>‘<samp><span class="samp">pkgname</span></samp>’, ‘<samp><span class="samp">pkgversion</span></samp>’, along with ‘<samp><span class="samp">version</span></samp>’,
767 ‘<samp><span class="samp">arch</span></samp>’, and ‘<samp><span class="samp">release</span></samp>’, are used to produce the name of the
768 package in the form
769 ‘<samp><span class="samp">${pkgname}-${pkgversion}-${arch}+${release}.tlz</span></samp>’. All of
770 them must be defined in the recipe, excepting ‘<samp><span class="samp">arch</span></samp>’, which is
771 optional.
773 <ul>
780 <li>‘<samp><span class="samp">release</span></samp>’: release number of the package. It is recommended to
781 increase this number after any significant change in the recipe is made.
782 </ul>
785 the ‘<samp><span class="samp">fetch</span></samp>’ variable. Use double quotes for separated values.
787 <p>The variables ‘<samp><span class="samp">netget</span></samp>’ and ‘<samp><span class="samp">rsync</span></samp>’ can be defined in
788 <samp><span class="file">qirc</span></samp> to establish a network downloader in order to get the
789 sources. If they are not defined, qi uses default values:
791 <p>‘<samp><span class="samp">netget</span></samp>’ is the general network downloader tool for use, and
792 defaults to ‘<samp><span class="samp">wget -c -w1 -t3 --no-check-certificate</span></samp>’.
794 <p>‘<samp><span class="samp">rsync</span></samp>’ is the network tool for sources containing the prefix for
795 the RSYNC protocol, and defaults to
799 package: ‘<samp><span class="samp">description</span></samp>’, ‘<samp><span class="samp">homepage</span></samp>’, ‘<samp><span class="samp">license</span></samp>’.
801 <p>The variable ‘<samp><span class="samp">description</span></samp>’ is special to write the description of the
802 package, which will be shown when installed.
804 <p>A description has two parts: a brief description and a long
805 description. By convention, the syntax of a description is:
808 Brief description.
810 Long description.
811 "
812 </pre>
814 software (called the "blurb"). A new (blank) line is followed to
815 separate the brief description from the long description.
817 <p>An example looks like:
820 A source builder and a package manager.
822 Qi is a source builder and a package manager. It contains a set of
823 tools to build, install, remove, and upgrade software packages.
825 Qi follows the philosophy of the simplicity without adding too many
826 features, such as those that can be found in popular package managers.
827 Basically it does two things: builds packages and manages them.
828 "
829 </pre>
830 <ul>
833 </ul>
835 <p class="noindent">The ‘<samp><span class="samp">homepage</span></samp>’ variable is used simply to declare the main site or
836 home of the source, thus:
839 </pre>
840 <p class="noindent">The variable ‘<samp><span class="samp">license</span></samp>’ is used for license information<a rel="footnote" href="#fn-2" name="fnd-2"><sup>2</sup></a>.
841 Some code in the program can be covered by license A, license B, or
844 conjunction (if that ever happens in a significant way), and comma
845 for heterogeneous licensing. Comma would have lower precedence. Plus
846 added special terms.
849 </pre>
853 The variables <samp><span class="env">QICFLAGS</span></samp>, <samp><span class="env">QICXXFLAGS</span></samp>, and <samp><span class="env">QILDFLAGS</span></samp> have
854 no effect by default. The environment variables such as <samp><span class="env">CFLAGS</span></samp>,
855 <samp><span class="env">CXXFLAGS</span></samp>, and <samp><span class="env">LDFLAGS</span></samp> are unset at compile time.
857 <p>Recommended practices is to set variables in front of ‘<samp><span class="samp">configure</span></samp>’
859 As follows:
861 <blockquote>
862 Variables not defined in a site shell script can be set in the
863 environment passed to configure. However, some packages may run
864 configure again during the build, and the customized values of these
865 variables may be lost. In order to avoid this problem, you should set
866 them in the configure command line, using ‘<samp><span class="samp">VAR=value</span></samp>’. For
867 example:
871 <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>
872 </blockquote>
874 <blockquote>
875 Indeed, while configure can notice the definition of CC in ‘<samp><span class="samp">./configure
876 CC=bizarre-cc</span></samp>’, it is impossible to notice it in ‘<samp><span class="samp">CC=bizarre-cc
879 <p>[...]
881 <p>configure: error: changes in the environment can compromise the build.
883 <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>
884 </blockquote>
886 <blockquote>
887 It is not wise for makefiles to depend for their functioning on
888 environment variables set up outside their control, since this would
889 cause different users to get different results from the same makefile.
890 This is against the whole purpose of most makefiles.
892 <p><a href="http://gnu.org/software/make/manual/make.html#Environment">http://gnu.org/software/make/manual/make.html#Environment</a>
893 </blockquote>
898 The "meta file" is an external file created by <samp><span class="command">pkgbuild</span></samp> when
899 a recipe is processed and when a package is produced. The file is
900 generated as ‘<samp><span class="samp">${full_pkgname}.tlz.txt</span></samp>’ which contains
901 information about the package such as ‘<samp><span class="samp">program</span></samp>’, ‘<samp><span class="samp">version</span></samp>’,
902 ‘<samp><span class="samp">release</span></samp>’. Also definitions of the special variables
903 ‘<samp><span class="samp">fetch</span></samp>’, ‘<samp><span class="samp">description</span></samp>’, ‘<samp><span class="samp">homepage</span></samp>’, ‘<samp><span class="samp">license</span></samp>’.
905 <p>A meta file has the purpose to extract information and the purpose to
906 reflect essential information to the user without having to check
907 inside the package itself.
909 <p>The meta file is basically composed as:
913 variable=value
914 ...
915 </pre>
917 ‘<samp><span class="samp">description</span></samp>’, where each line is interpreted literally and where
918 the description is pre-formatted to fit in (exactly) 80 columns. Plus
921 <p>Followed by new line, the rest is composed by variables; the inclusion
922 of its values, may vary. For example, in addition to the special
923 variables, there are implicit variables such as ‘<samp><span class="samp">blurb</span></samp>’,
926 <p>The ‘<samp><span class="samp">blurb</span></samp>’ variable is related to the special variable
927 ‘<samp><span class="samp">description</span></samp>’. Always taking the first (substantial) line
928 or "brief description".
930 <p>The value of ‘<samp><span class="samp">depends</span></samp>’ only will be included if the
931 <samp><span class="file">depends</span></samp> file is a regular file. See <a href="#Order-files">The depends file</a>.
936 #
937 # Clzip is a lossless data compressor with a user interface similar to
938 # the one of gzip or bzip2. Clzip is about as fast as gzip, compresses
939 # most files more than bzip2, and is better than both from a data
940 # recovery perspective.
941 #
942 # Clzip uses the lzip file format; the files produced by clzip are fully
943 # compatible with lzip-1.4 or newer, and can be rescued with lziprecover.
944 #
945 # Clzip is in fact a C language version of lzip, intended for embedded
946 # devices or systems lacking a C++ compiler.
951 program=clzip
952 version=1.8
953 release=1
960 </pre>
961 <p>Creation of the meta file is made in ‘<samp><span class="samp">${outdir}</span></samp>’.
966 This sort order is particularly useful just before the actual package
967 build, because it helps to understand how a package is being built:
970 <li>A recipe is read from the current directory, if not, it will be
971 looked in ‘<samp><span class="samp">${worktree}/recipes</span></samp>’. Names of recipes can be
972 invoked relative to ‘<samp><span class="samp">${worktree}/recipes</span></samp>’. The recipe must be
973 a regular file and must be readable by the user who is running the
974 command.
976 <li>Checks are made when the recipe is imported (included), essential
977 variable names cannot be empty: ‘<samp><span class="samp">program</span></samp>’, ‘<samp><span class="samp">version</span></samp>’,
978 ‘<samp><span class="samp">release</span></samp>’. Also the main function ‘<samp><span class="samp">build()</span></samp>’ must be present.
980 <li><samp><span class="command">pkgbuild</span></samp> tries to obtain the sources remotely if it
981 does not exist locally (‘<samp><span class="samp">${tardir}</span></samp>’). Once the source is
982 already in place, its timestamp is updated, creating or updating the
983 SHA1 sum.
985 <li>Required directories are created: ‘<samp><span class="samp">${TMPDIR}/$srcdir</span></samp>’,
986 ‘<samp><span class="samp">${outdir}</span></samp>’, ‘<samp><span class="samp">${destdir}/var/lib/qi/recipes</span></samp>’.
988 <li>Sane ownerships and permissions are applied to the full source
991 <li>The main function ‘<samp><span class="samp">build()</span></samp>’ is called. Exits immediately if
992 a command exits with a non-zero status.
994 <li>A package is going to be created under the following conditions:
996 <ul>
999 <li>If the option -n was not given.
1000 </ul>
1002 <p>A copy of the recipe (file) is included on
1003 ‘<samp><span class="samp">${destdir}/var/lib/qi/recipes</span></samp>’ as ‘<samp><span class="samp">${full_pkgname}.recipe</span></samp>’.
1005 <p>If the <samp><span class="file">post-install</span></samp> script is in the current working directory
1006 or from where the recipe name resides, it will be added as
1007 ‘<samp><span class="samp">${destdir}/var/lib/qi/post-install/${full_pkgname}.install</span></samp>’.
1009 <p>The package is produced from the content of ‘<samp><span class="samp">${destdir}</span></samp>’. First,
1010 creating a tarball, and then compressing it using the maximum level of
1013 <li>By default, directories like ‘<samp><span class="samp">${TMPDIR}/$srcdir</span></samp>’ and
1016 <li>If the option -U is given, <samp><span class="command">pkgupgrade</span></samp> is invoked to
1017 install or upgrade the package.
1019 </ol>
1021 <p class="noindent"><em>Usage:</em> pkgbuild [-hiknU] [-a <ARCH>] [-j <JOBS>] [-o <DIR>] [recipe ...]
1023 <p>To build a single package, simply type:
1026 </pre>
1027 <p>Compile passing parallel jobs to the compiler for speed up the process:
1030 </pre>
1031 <p>To build and install or upgrade multiple packages at once:
1034 </pre>
1035 <p>Reading recipes and building from the output of a command:
1038 </pre>
1039 <p>Incrementing the release number after a significant change in a recipe:
1041 </pre>
1043 a specific path name, ‘<samp><span class="samp">${worktree}/recipes</span></samp>’ is used for the
1044 search:
1046 <p>There is a special case for the names of recipes ‘<samp><span class="samp">recipe</span></samp>’.
1047 <samp><span class="command">pkgbuild</span></samp> can complete the recipe name without being required
1048 to be specified in the command-line, only if the name of the recipe is
1052 </pre>
1053 <p>Will complete the search as ‘<samp><span class="samp">${worktree}/recipes/devel/gcc/recipe</span></samp>’.
1062 Some internal functions are available to be applied on the recipe:
1064 <dl>
1065 <dt>‘<samp><span class="samp">unpack()</span></samp>’<dd>The unpack function can decompress multiple (compressed) files while
1066 verifies the integrity. Depending on where the function is called,
1067 the decompression occurs in the current working directory.
1071 <p>The cases supported for the special extensions are: *.tar, *.tar.*,
1072 *.tgz*, *.tbz*, *.tlz*, *.txz*, *.zip, *.ZIP, *.gz, *.bz2, *.lz.
1073 </dl>
1077 <p><hr>
1082 </div>
1087 <samp><span class="command">pkgorder</span></samp> has the purpose to resolve the build order through
1088 .order files. In other words, is a good complement for
1093 <p class="noindent">Basically, <samp><span class="command">pkgorder</span></samp> reads from a declared file which ends in
1094 ".order". The output is an ordered list of recipe names which can be
1095 passed to <samp><span class="command">pkgbuild</span></samp> (via a pipe) to build a number or a series
1096 of packages.
1100 <p>If 'a' depends on 'b' and 'c', and 'c' depends on 'b' as well, the file
1101 might look like:
1104 b.recipe:
1105 c.recipe: b.recipe
1106 </pre>
1107 <p>Each letter represents a recipe name, complete dependencies for
1108 the first recipe name are listed in descending order, which is
1109 printed from right to left, and removed from left to right:
1114 c.recipe
1115 a.recipe
1116 </pre>
1117 <ul>
1118 <li>Commented lines starting with a '#' are allowed. Blank lines,
1119 colons, parentheses, and end of line are removed.
1120 </ul>
1125 When <samp><span class="command">pkgorder</span></samp> read from an order file; by default, it will
1126 proceed to read the dependencies of each recipe. This behavior can be
1127 omitted if the -x option is given.
1129 <p>The procedure for reading the dependencies of each recipe is
1130 extracting the directory location where the order file resides. Then
1131 it iterates over the declared items extracting its location in search
1134 <ul>
1135 <li>The <samp><span class="file">depends</span></samp> file only is read (sequentially) if it is
1136 a regular file and is not empty.
1137 </ul>
1139 <p class="noindent">The special file <samp><span class="file">depends</span></samp> must contain a list of prerequisites
1140 for the recipe. Prerequisites are names of valid recipes, including
1141 its location. The location must be relative to ‘<samp><span class="samp">${worktree}</span></samp>’
1144 <p>Example of a <samp><span class="file">depends</span></samp> file declared for <em>bash.recipe</em>:
1147 </pre>
1152 libs/readline/readline.recipe
1153 core/bash/bash.recipe
1154 ...
1155 </pre>
1160 </pre>
1163 <p><hr>
1168 </div>
1173 <samp><span class="command">pkgerupt</span></samp> is a special command to examine packages for
1174 debugging purposes.
1178 <p>When a package name is given <samp><span class="command">pkgerupt</span></samp> will create a random
1179 directory for the package. The prefix directory where the random
1180 directory is created is controlled by the <samp><span class="env">TMPDIR</span></samp> variable,
1181 by default <samp><span class="env">TMPDIR</span></samp> is assigned to <em>/tmp</em>. Creation mode
1184 <p>The extraction to inspecting a package is equivalent to the shell
1185 instruction:
1187 <pre class="example"> <code>( umask 000 && cd -- $PRVDIR && lzip -cd - | tar -xf - ) < $file</code>
1188 </pre>
1189 <p>The package content is decompressed in the random (private) directory
1192 <p>If there is any substantial change, consider increasing the build
1193 number when repackaging: edit the value of the ‘<samp><span class="samp">release</span></samp>’ variable
1194 (recipe), compose the output file using the new number.
1198 <p><hr>
1203 </div>
1208 Some symbols are used for output messages to help to identify
1209 the messages shown by the tools in Qi. There are four simple
1210 categories where the symbols are represented:
1214 </pre>
1217 <p>This symbols are unique to identify the running tool:
1219 <dl>
1220 <dt>‘<samp><span class="samp">+</span></samp>’<dd>This symbol belongs to the <samp><span class="command">pkgadd</span></samp> tool.
1222 <br><dt>‘<samp><span class="samp">-</span></samp>’<dd>This symbol belongs to the <samp><span class="command">pkgremove</span></samp> tool.
1224 <br><dt>‘<samp><span class="samp">~</span></samp>’<dd>This symbol belongs to the <samp><span class="command">pkgupgrade</span></samp> tool.
1226 <br><dt>‘<samp><span class="samp">#</span></samp>’<dd>This symbol belongs to the <samp><span class="command">pkgbuild</span></samp> tool.
1228 <br><dt>‘<samp><span class="samp">=</span></samp>’<dd>This symbol belongs to the <samp><span class="command">pkgerupt</span></samp> tool.
1230 <br><dt>‘<samp><span class="samp">%</span></samp>’<dd>This symbol is used to scan a package or to warn when
1231 the option is used.
1233 <p>Specific symbols are enclosed between ‘<samp><span class="samp">( )</span></samp>’.
1234 </dl>
1236 <dl>
1239 <p>Preventive symbols are intended to alert the user about unforeseen
1240 or important situations, and to meet requirements before proceeding:
1242 <dt>‘<samp><span class="samp">*</span></samp>’<dd>Normally used for testing compressed sources, obtain remote sources,
1243 or set system permissions.
1245 <p>Preventive symbols are enclosed between ‘<samp><span class="samp">[ ]</span></samp>’.
1246 </dl>
1248 <dl>
1251 <p>Informative symbols are intended to inform users the most essential
1252 tasks during the execution:
1254 <dt>‘<samp><span class="samp">i</span></samp>’<dd>Symbol used when a task is going to be performed or when a task has
1255 been completed.
1257 <br><dt>‘<samp><span class="samp">!</span></samp>’<dd>This symbol informs about deleting files.
1259 <p>Informative symbols are enclosed between ‘<samp><span class="samp">[ ]</span></samp>’.
1260 </dl>
1264 <p>Transitory symbols are part for occasional changes (‘<samp><span class="samp">@</span></samp>’) but no
1265 less important. Also to invoke Qi tools externally (‘<samp><span class="samp">^</span></samp>’).
1267 <p>Transitory symbols are enclosed between ‘<samp><span class="samp">{ }</span></samp>’.
1271 <p><hr>
1272 Next: <a rel="next" accesskey="n" href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>,
1276 </div>
1281 All the conditions of exit codes are described in this chapter.
1283 <dl>
1284 <dt>‘<samp><span class="samp">0</span></samp>’<dd>Successful completion (no errors).
1286 <br><dt>‘<samp><span class="samp">1</span></samp>’<dd><strong>Minor common errors:</strong>
1288 <ul>
1289 <li>Illegal option.
1291 <li>Option requires an argument.
1293 <li>Internal function to load not found.
1295 <li>Program (prerequisite) is not available.
1296 </ul>
1298 <br><dt>‘<samp><span class="samp">2</span></samp>’<dd><strong>Command execution error</strong>
1300 <p>Evaluation of external commands or shell arguments. If it fails,
1301 returns 2.
1303 <br><dt>‘<samp><span class="samp">3</span></samp>’<dd><strong>Integrity check error for compressed files</strong>
1305 <p>Compressed files means:
1307 <ul>
1317 </ul>
1319 <br><dt>‘<samp><span class="samp">4</span></samp>’<dd><strong>File empty, not regular, or expected</strong>
1321 <p>Commonly, it is expected:
1323 <ul>
1324 <li>A binary package (.tlz).
1326 <li>An installed package to remove.
1328 <li>A recipe file.
1330 <li>A file of order (.order).
1331 </ul>
1333 <br><dt>‘<samp><span class="samp">5</span></samp>’<dd><strong>Empty or not defined variable</strong>
1335 <p>This exit code is used for reporting about empty or undefined variables.
1336 Usually, variables of the recipe or assigned arrays that are tested.
1338 <br><dt>‘<samp><span class="samp">6</span></samp>’<dd><strong>Package already installed</strong>
1340 <p>The package directory for an incoming package already exists.
1342 <br><dt>‘<samp><span class="samp">10</span></samp>’<dd><strong>Network manager error</strong>
1344 <p>Exit status from the execution of the network manager tool and its
1345 arguments.
1346 </dl>
1349 Error messages are reported to the standard error.
1350 </td></tr></table>
1354 <p><hr>
1359 </div>
1363 <!-- The GNU Free Documentation License. -->
1366 <!-- This file is intended to be included within another document, -->
1367 <!-- hence no sectioning command or @node. -->
1368 <pre class="display"> Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
1371 Everyone is permitted to copy and distribute verbatim copies
1372 of this license document, but changing it is not allowed.
1373 </pre>
1375 <li>PREAMBLE
1377 <p>The purpose of this License is to make a manual, textbook, or other
1379 assure everyone the effective freedom to copy and redistribute it,
1380 with or without modifying it, either commercially or noncommercially.
1381 Secondarily, this License preserves for the author and publisher a way
1382 to get credit for their work, while not being considered responsible
1383 for modifications made by others.
1386 works of the document must themselves be free in the same sense. It
1387 complements the GNU General Public License, which is a copyleft
1388 license designed for free software.
1390 <p>We have designed this License in order to use it for manuals for free
1391 software, because free software needs free documentation: a free
1392 program should come with manuals providing the same freedoms that the
1393 software does. But this License is not limited to software manuals;
1394 it can be used for any textual work, regardless of subject matter or
1395 whether it is published as a printed book. We recommend this License
1396 principally for works whose purpose is instruction or reference.
1398 <li>APPLICABILITY AND DEFINITIONS
1400 <p>This License applies to any manual or other work, in any medium, that
1401 contains a notice placed by the copyright holder saying it can be
1402 distributed under the terms of this License. Such a notice grants a
1403 world-wide, royalty-free license, unlimited in duration, to use that
1405 refers to any such manual or work. Any member of the public is a
1407 copy, modify or distribute the work in a way requiring permission
1408 under copyright law.
1411 Document or a portion of it, either copied verbatim, or with
1412 modifications and/or translated into another language.
1415 of the Document that deals exclusively with the relationship of the
1416 publishers or authors of the Document to the Document's overall
1417 subject (or to related matters) and contains nothing that could fall
1418 directly within that overall subject. (Thus, if the Document is in
1419 part a textbook of mathematics, a Secondary Section may not explain
1420 any mathematics.) The relationship could be a matter of historical
1421 connection with the subject or with related matters, or of legal,
1422 commercial, philosophical, ethical or political position regarding
1423 them.
1426 are designated, as being those of Invariant Sections, in the notice
1427 that says that the Document is released under this License. If a
1428 section does not fit the above definition of Secondary then it is not
1429 allowed to be designated as Invariant. The Document may contain zero
1430 Invariant Sections. If the Document does not identify any Invariant
1431 Sections then there are none.
1434 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
1435 the Document is released under this License. A Front-Cover Text may
1439 represented in a format whose specification is available to the
1440 general public, that is suitable for revising the document
1441 straightforwardly with generic text editors or (for images composed of
1442 pixels) generic paint programs or (for drawings) some widely available
1443 drawing editor, and that is suitable for input to text formatters or
1444 for automatic translation to a variety of formats suitable for input
1445 to text formatters. A copy made in an otherwise Transparent file
1446 format whose markup, or absence of markup, has been arranged to thwart
1447 or discourage subsequent modification by readers is not Transparent.
1448 An image format is not Transparent if used for any substantial amount
1451 <p>Examples of suitable formats for Transparent copies include plain
1452 ASCII without markup, Texinfo input format, LaTeX input
1453 format, SGML or XML using a publicly available
1454 DTD, and standard-conforming simple HTML,
1455 PostScript or PDF designed for human modification. Examples
1456 of transparent image formats include PNG, XCF and
1457 JPG. Opaque formats include proprietary formats that can be
1458 read and edited only by proprietary word processors, SGML or
1459 XML for which the DTD and/or processing tools are
1460 not generally available, and the machine-generated HTML,
1461 PostScript or PDF produced by some word processors for
1462 output purposes only.
1465 plus such following pages as are needed to hold, legibly, the material
1466 this License requires to appear in the title page. For works in
1468 the text near the most prominent appearance of the work's title,
1469 preceding the beginning of the body of the text.
1472 of the Document to the public.
1475 title either is precisely XYZ or contains XYZ in parentheses following
1476 text that translates XYZ in another language. (Here XYZ stands for a
1478 “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title”
1479 of such a section when you modify the Document means that it remains a
1482 <p>The Document may include Warranty Disclaimers next to the notice which
1483 states that this License applies to the Document. These Warranty
1484 Disclaimers are considered to be included by reference in this
1485 License, but only as regards disclaiming warranties: any other
1486 implication that these Warranty Disclaimers may have is void and has
1487 no effect on the meaning of this License.
1489 <li>VERBATIM COPYING
1491 <p>You may copy and distribute the Document in any medium, either
1492 commercially or noncommercially, provided that this License, the
1493 copyright notices, and the license notice saying this License applies
1494 to the Document are reproduced in all copies, and that you add no other
1495 conditions whatsoever to those of this License. You may not use
1496 technical measures to obstruct or control the reading or further
1497 copying of the copies you make or distribute. However, you may accept
1498 compensation in exchange for copies. If you distribute a large enough
1499 number of copies you must also follow the conditions in section 3.
1501 <p>You may also lend copies, under the same conditions stated above, and
1502 you may publicly display copies.
1504 <li>COPYING IN QUANTITY
1506 <p>If you publish printed copies (or copies in media that commonly have
1507 printed covers) of the Document, numbering more than 100, and the
1508 Document's license notice requires Cover Texts, you must enclose the
1509 copies in covers that carry, clearly and legibly, all these Cover
1510 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
1511 the back cover. Both covers must also clearly and legibly identify
1512 you as the publisher of these copies. The front cover must present
1513 the full title with all words of the title equally prominent and
1514 visible. You may add other material on the covers in addition.
1515 Copying with changes limited to the covers, as long as they preserve
1516 the title of the Document and satisfy these conditions, can be treated
1517 as verbatim copying in other respects.
1519 <p>If the required texts for either cover are too voluminous to fit
1520 legibly, you should put the first ones listed (as many as fit
1521 reasonably) on the actual cover, and continue the rest onto adjacent
1522 pages.
1524 <p>If you publish or distribute Opaque copies of the Document numbering
1525 more than 100, you must either include a machine-readable Transparent
1526 copy along with each Opaque copy, or state in or with each Opaque copy
1527 a computer-network location from which the general network-using
1528 public has access to download using public-standard network protocols
1529 a complete Transparent copy of the Document, free of added material.
1530 If you use the latter option, you must take reasonably prudent steps,
1531 when you begin distribution of Opaque copies in quantity, to ensure
1532 that this Transparent copy will remain thus accessible at the stated
1533 location until at least one year after the last time you distribute an
1534 Opaque copy (directly or through your agents or retailers) of that
1535 edition to the public.
1537 <p>It is requested, but not required, that you contact the authors of the
1538 Document well before redistributing any large number of copies, to give
1539 them a chance to provide you with an updated version of the Document.
1541 <li>MODIFICATIONS
1543 <p>You may copy and distribute a Modified Version of the Document under
1545 the Modified Version under precisely this License, with the Modified
1546 Version filling the role of the Document, thus licensing distribution
1547 and modification of the Modified Version to whoever possesses a copy
1548 of it. In addition, you must do these things in the Modified Version:
1551 <li>Use in the Title Page (and on the covers, if any) a title distinct
1552 from that of the Document, and from those of previous versions
1553 (which should, if there were any, be listed in the History section
1554 of the Document). You may use the same title as a previous version
1555 if the original publisher of that version gives permission.
1557 <li>List on the Title Page, as authors, one or more persons or entities
1558 responsible for authorship of the modifications in the Modified
1559 Version, together with at least five of the principal authors of the
1560 Document (all of its principal authors, if it has fewer than five),
1561 unless they release you from this requirement.
1563 <li>State on the Title page the name of the publisher of the
1564 Modified Version, as the publisher.
1566 <li>Preserve all the copyright notices of the Document.
1568 <li>Add an appropriate copyright notice for your modifications
1569 adjacent to the other copyright notices.
1571 <li>Include, immediately after the copyright notices, a license notice
1572 giving the public permission to use the Modified Version under the
1573 terms of this License, in the form shown in the Addendum below.
1575 <li>Preserve in that license notice the full lists of Invariant Sections
1576 and required Cover Texts given in the Document's license notice.
1578 <li>Include an unaltered copy of this License.
1581 to it an item stating at least the title, year, new authors, and
1582 publisher of the Modified Version as given on the Title Page. If
1584 stating the title, year, authors, and publisher of the Document as
1585 given on its Title Page, then add an item describing the Modified
1586 Version as stated in the previous sentence.
1588 <li>Preserve the network location, if any, given in the Document for
1589 public access to a Transparent copy of the Document, and likewise
1590 the network locations given in the Document for previous versions
1592 You may omit a network location for a work that was published at
1593 least four years before the Document itself, or if the original
1594 publisher of the version it refers to gives permission.
1596 <li>For any section Entitled “Acknowledgements” or “Dedications”, Preserve
1597 the Title of the section, and preserve in the section all the
1598 substance and tone of each of the contributor acknowledgements and/or
1599 dedications given therein.
1601 <li>Preserve all the Invariant Sections of the Document,
1602 unaltered in their text and in their titles. Section numbers
1603 or the equivalent are not considered part of the section titles.
1606 may not be included in the Modified Version.
1609 to conflict in title with any Invariant Section.
1611 <li>Preserve any Warranty Disclaimers.
1612 </ol>
1614 <p>If the Modified Version includes new front-matter sections or
1615 appendices that qualify as Secondary Sections and contain no material
1616 copied from the Document, you may at your option designate some or all
1617 of these sections as invariant. To do this, add their titles to the
1618 list of Invariant Sections in the Modified Version's license notice.
1619 These titles must be distinct from any other section titles.
1622 nothing but endorsements of your Modified Version by various
1623 parties—for example, statements of peer review or that the text has
1624 been approved by an organization as the authoritative definition of a
1625 standard.
1627 <p>You may add a passage of up to five words as a Front-Cover Text, and a
1628 passage of up to 25 words as a Back-Cover Text, to the end of the list
1629 of Cover Texts in the Modified Version. Only one passage of
1630 Front-Cover Text and one of Back-Cover Text may be added by (or
1631 through arrangements made by) any one entity. If the Document already
1632 includes a cover text for the same cover, previously added by you or
1633 by arrangement made by the same entity you are acting on behalf of,
1634 you may not add another; but you may replace the old one, on explicit
1635 permission from the previous publisher that added the old one.
1637 <p>The author(s) and publisher(s) of the Document do not by this License
1638 give permission to use their names for publicity for or to assert or
1639 imply endorsement of any Modified Version.
1641 <li>COMBINING DOCUMENTS
1643 <p>You may combine the Document with other documents released under this
1644 License, under the terms defined in section 4 above for modified
1645 versions, provided that you include in the combination all of the
1646 Invariant Sections of all of the original documents, unmodified, and
1647 list them all as Invariant Sections of your combined work in its
1648 license notice, and that you preserve all their Warranty Disclaimers.
1650 <p>The combined work need only contain one copy of this License, and
1651 multiple identical Invariant Sections may be replaced with a single
1652 copy. If there are multiple Invariant Sections with the same name but
1653 different contents, make the title of each such section unique by
1654 adding at the end of it, in parentheses, the name of the original
1655 author or publisher of that section if known, or else a unique number.
1656 Make the same adjustment to the section titles in the list of
1657 Invariant Sections in the license notice of the combined work.
1660 in the various original documents, forming one section Entitled
1665 <li>COLLECTIONS OF DOCUMENTS
1667 <p>You may make a collection consisting of the Document and other documents
1668 released under this License, and replace the individual copies of this
1669 License in the various documents with a single copy that is included in
1670 the collection, provided that you follow the rules of this License for
1671 verbatim copying of each of the documents in all other respects.
1673 <p>You may extract a single document from such a collection, and distribute
1674 it individually under this License, provided you insert a copy of this
1675 License into the extracted document, and follow this License in all
1676 other respects regarding verbatim copying of that document.
1678 <li>AGGREGATION WITH INDEPENDENT WORKS
1680 <p>A compilation of the Document or its derivatives with other separate
1681 and independent documents or works, in or on a volume of a storage or
1683 resulting from the compilation is not used to limit the legal rights
1684 of the compilation's users beyond what the individual works permit.
1685 When the Document is included in an aggregate, this License does not
1686 apply to the other works in the aggregate which are not themselves
1687 derivative works of the Document.
1690 copies of the Document, then if the Document is less than one half of
1691 the entire aggregate, the Document's Cover Texts may be placed on
1692 covers that bracket the Document within the aggregate, or the
1693 electronic equivalent of covers if the Document is in electronic form.
1694 Otherwise they must appear on printed covers that bracket the whole
1695 aggregate.
1697 <li>TRANSLATION
1699 <p>Translation is considered a kind of modification, so you may
1700 distribute translations of the Document under the terms of section 4.
1701 Replacing Invariant Sections with translations requires special
1702 permission from their copyright holders, but you may include
1703 translations of some or all Invariant Sections in addition to the
1704 original versions of these Invariant Sections. You may include a
1705 translation of this License, and all the license notices in the
1706 Document, and any Warranty Disclaimers, provided that you also include
1707 the original English version of this License and the original versions
1708 of those notices and disclaimers. In case of a disagreement between
1709 the translation and the original version of this License or a notice
1710 or disclaimer, the original version will prevail.
1714 its Title (section 1) will typically require changing the actual
1715 title.
1717 <li>TERMINATION
1719 <p>You may not copy, modify, sublicense, or distribute the Document
1720 except as expressly provided under this License. Any attempt
1721 otherwise to copy, modify, sublicense, or distribute it is void, and
1722 will automatically terminate your rights under this License.
1724 <p>However, if you cease all violation of this License, then your license
1725 from a particular copyright holder is reinstated (a) provisionally,
1726 unless and until the copyright holder explicitly and finally
1727 terminates your license, and (b) permanently, if the copyright holder
1728 fails to notify you of the violation by some reasonable means prior to
1729 60 days after the cessation.
1731 <p>Moreover, your license from a particular copyright holder is
1732 reinstated permanently if the copyright holder notifies you of the
1733 violation by some reasonable means, this is the first time you have
1734 received notice of violation of this License (for any work) from that
1735 copyright holder, and you cure the violation prior to 30 days after
1736 your receipt of the notice.
1738 <p>Termination of your rights under this section does not terminate the
1739 licenses of parties who have received copies or rights from you under
1740 this License. If your rights have been terminated and not permanently
1741 reinstated, receipt of a copy of some or all of the same material does
1742 not give you any rights to use it.
1744 <li>FUTURE REVISIONS OF THIS LICENSE
1746 <p>The Free Software Foundation may publish new, revised versions
1747 of the GNU Free Documentation License from time to time. Such new
1748 versions will be similar in spirit to the present version, but may
1749 differ in detail to address new problems or concerns. See
1752 <p>Each version of the License is given a distinguishing version number.
1753 If the Document specifies that a particular numbered version of this
1755 following the terms and conditions either of that specified version or
1756 of any later version that has been published (not as a draft) by the
1757 Free Software Foundation. If the Document does not specify a version
1758 number of this License, you may choose any version ever published (not
1759 as a draft) by the Free Software Foundation. If the Document
1760 specifies that a proxy can decide which future versions of this
1761 License can be used, that proxy's public statement of acceptance of a
1762 version permanently authorizes you to choose that version for the
1763 Document.
1765 <li>RELICENSING
1768 World Wide Web server that publishes copyrightable works and also
1769 provides prominent facilities for anybody to edit those works. A
1770 public wiki that anybody can edit is an example of such a server. A
1772 site means any set of copyrightable works thus published on the MMC
1773 site.
1776 license published by Creative Commons Corporation, a not-for-profit
1777 corporation with a principal place of business in San Francisco,
1778 California, as well as future copyleft versions of that license
1779 published by that same organization.
1782 in part, as part of another Document.
1785 License, and if all works that were first published under this License
1786 somewhere other than this MMC, and subsequently incorporated in whole
1787 or in part into the MMC, (1) had no cover texts or invariant sections,
1790 <p>The operator of an MMC Site may republish an MMC contained in the site
1792 provided the MMC is eligible for relicensing.
1794 </ol>
1798 <p>To use this License in a document you have written, include a copy of
1799 the License in the document and put the following copyright and
1800 license notices just after the title page:
1803 Permission is granted to copy, distribute and/or modify this document
1804 under the terms of the GNU Free Documentation License, Version 1.3
1805 or any later version published by the Free Software Foundation;
1806 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
1807 Texts. A copy of the license is included in the section entitled ``GNU
1808 Free Documentation License''.
1809 </pre>
1810 <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
1813 <pre class="smallexample"> with the Invariant Sections being <var>list their titles</var>, with
1816 </pre>
1817 <p>If you have Invariant Sections without Cover Texts, or some other
1818 combination of the three, merge those two alternatives to suit the
1819 situation.
1821 <p>If your document contains nontrivial examples of program code, we
1822 recommend releasing these examples in parallel under your choice of
1823 free software license, such as the GNU General Public License,
1824 to permit their use in free software.
1826 <!-- Local Variables: -->
1827 <!-- ispell-local-pdict: "ispell-dict" -->
1828 <!-- End: -->
1831 <p><hr>
1832 Previous: <a rel="previous" accesskey="p" href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>,
1835 </div>
1840 <li><a href="#index-g_t_002eorder-files-19">.order files</a>: <a href="#Order-files">Order files</a></li>
1841 <li><a href="#index-adding-packages-7">adding packages</a>: <a href="#Packages">Packages</a></li>
1842 <li><a href="#index-building-packages-16">building packages</a>: <a href="#Recipes">Recipes</a></li>
1844 <li><a href="#index-examine-packages-21">examine packages</a>: <a href="#Examine-packages">Examine packages</a></li>
1846 <li><a href="#index-internal-functions-18">internal functions</a>: <a href="#Recipes">Recipes</a></li>
1847 <li><a href="#index-introduction-1">introduction</a>: <a href="#Introduction">Introduction</a></li>
1851 <li><a href="#index-output-messages-22">output messages</a>: <a href="#Messages">Messages</a></li>
1854 <li><a href="#index-removing-packages-8">removing packages</a>: <a href="#Packages">Packages</a></li>
1855 <li><a href="#index-special-variables-13">special variables</a>: <a href="#Recipes">Recipes</a></li>
1856 <li><a href="#index-the-depends-file-20">the depends file</a>: <a href="#Order-files">Order files</a></li>
1858 <li><a href="#index-the-qirc-file-5">the qirc file</a>: <a href="#The-qirc-file">The qirc file</a></li>
1859 <li><a href="#index-upgrading-packages-9">upgrading packages</a>: <a href="#Packages">Packages</a></li>
1861 <li><a href="#index-variables-from-the-environment-14">variables from the environment</a>: <a href="#Recipes">Recipes</a></li>
1862 <li><a href="#index-writing-recipes-17">writing recipes</a>: <a href="#Recipes">Recipes</a></li>
1864 <hr>
1865 <a name="texinfo-footnotes-in-document"></a><h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> The official guide
1866 for Graft can be found at
1867 <a href="http://peters.gormand.com.au/Home/tools/graft/graft.html">http://peters.gormand.com.au/Home/tools/graft/graft.html</a>.</p>
1870 The proposal for ‘<samp><span class="samp">license</span></samp>’ was made by Richard M. Stallman at
1871 <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>
1873 <hr></div>
1875 </body></html>
1877 <!--
1878 \x1f
1879 Local Variables:
1880 coding: iso-8859-1
1881 End:
1883 -->