qi/doc/qi.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- This user guide is for Qi (version 1.0-rc59,
   4 29 March 2019), which is a simple but well-integrated package manager.
   5
   6 Copyright (C) 2019 Matias Andres Fonzo, Santiago del Estero,
   7 Argentina.
   8
   9 Permission is granted to copy, distribute and/or modify this document
  10 under the terms of the GNU Free Documentation License, Version 1.3 or
  11 any later version published by the Free Software Foundation; with no
  12 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  13 Texts.  A copy of the license is included in the section entitled
  14 "GNU Free Documentation License". -->
  15 <!-- Created by GNU Texinfo 6.6, http://www.gnu.org/software/texinfo/ -->
  16 <head>
  17 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  18 <title>Qi user guide</title>
  19
  20 <meta name="description" content="Qi user guide">
  21 <meta name="keywords" content="Qi user guide">
  22 <meta name="resource-type" content="document">
  23 <meta name="distribution" content="global">
  24 <meta name="Generator" content="makeinfo">
  25 <link href="#Top" rel="start" title="Top">
  26 <link href="#Index" rel="index" title="Index">
  27 <link href="#SEC_Contents" rel="contents" title="Table of Contents">
  28 <link href="dir.html#Top" rel="up" title="(dir)">
  29 <style type="text/css">
  30 <!--
  31 a.summary-letter {text-decoration: none}
  32 blockquote.indentedblock {margin-right: 0em}
  33 div.display {margin-left: 3.2em}
  34 div.example {margin-left: 3.2em}
  35 div.lisp {margin-left: 3.2em}
  36 kbd {font-style: oblique}
  37 pre.display {font-family: inherit}
  38 pre.format {font-family: inherit}
  39 pre.menu-comment {font-family: serif}
  40 pre.menu-preformatted {font-family: serif}
  41 span.nolinebreak {white-space: nowrap}
  42 span.roman {font-family: initial; font-weight: normal}
  43 span.sansserif {font-family: sans-serif; font-weight: normal}
  44 ul.no-bullet {list-style: none}
  45 -->
  46 </style>
  47
  48
  49 </head>
  50
  51 <body lang="en">
  52 <h1 class="settitle" align="center">Qi user guide</h1>
  53
  54
  55
  56
  57
  58 <span id="SEC_Contents"></span>
  59 <h2 class="contents-heading">Table of Contents</h2>
  60
  61 <div class="contents">
  62
  63 <ul class="no-bullet">
  64   <li><a id="toc-Introduction-1" href="#Introduction">1 Introduction</a></li>
  65   <li><a id="toc-Invoking-qi-1" href="#Invoking-qi">2 Invoking qi</a></li>
  66   <li><a id="toc-The-qirc-file-1" href="#The-qirc-file">3 The qirc file</a></li>
  67   <li><a id="toc-Packages-1" href="#Packages">4 Packages</a>
  68   <ul class="no-bullet">
  69     <li><a id="toc-Package-conflicts" href="#Package-conflicts">4.1 Package conflicts</a></li>
  70     <li><a id="toc-Installing-packages" href="#Installing-packages">4.2 Installing packages</a></li>
  71     <li><a id="toc-Removing-packages" href="#Removing-packages">4.3 Removing packages</a></li>
  72     <li><a id="toc-Upgrading-packages" href="#Upgrading-packages">4.4 Upgrading packages</a>
  73     <ul class="no-bullet">
  74       <li><a id="toc-Package-blacklist" href="#Package-blacklist">4.4.1 Package blacklist</a></li>
  75     </ul></li>
  76   </ul></li>
  77   <li><a id="toc-Recipes-1" href="#Recipes">5 Recipes</a>
  78   <ul class="no-bullet">
  79     <li><a id="toc-Variables" href="#Variables">5.1 Variables</a></li>
  80     <li><a id="toc-Special-variables" href="#Special-variables">5.2 Special variables</a></li>
  81     <li><a id="toc-Building-packages" href="#Building-packages">5.3 Building packages</a></li>
  82     <li><a id="toc-Variables-from-the-environment" href="#Variables-from-the-environment">5.4 Variables from the environment</a></li>
  83     <li><a id="toc-The-meta-file" href="#The-meta-file">5.5 The meta file</a></li>
  84   </ul></li>
  85   <li><a id="toc-Order-files-1" href="#Order-files">6 Order files</a></li>
  86   <li><a id="toc-Examining-packages-1" href="#Examining-packages">7 Examining packages</a></li>
  87   <li><a id="toc-Exit-status-1" href="#Exit-status">8 Exit status</a></li>
  88   <li><a id="toc-GNU-Free-Documentation-License" href="#License">Appendix A GNU Free Documentation License</a></li>
  89   <li><a id="toc-Index-1" href="#Index">Index</a></li>
  90 </ul>
  91 </div>
  92
  93
  94 <span id="Top"></span><div class="header">
  95 <p>
  96 Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
  97 </div>
  98 <span id="SEC_Top"></span>
  99 <p>This user guide is for Qi (version 1.0-rc59,
 100 29 March 2019).
 101 </p>
 102 <table class="menu" border="0" cellspacing="0">
 103 <tr><td align="left" valign="top">&bull; <a href="#Introduction" accesskey="1">Introduction</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Description and features of qi
 104 </td></tr>
 105 <tr><td align="left" valign="top">&bull; <a href="#Invoking-qi" accesskey="2">Invoking qi</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Command-line options
 106 </td></tr>
 107 <tr><td align="left" valign="top">&bull; <a href="#The-qirc-file" accesskey="3">The qirc file</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Configuration file
 108 </td></tr>
 109 <tr><td align="left" valign="top">&bull; <a href="#Packages" accesskey="4">Packages</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Managing packages
 110 </td></tr>
 111 <tr><td align="left" valign="top">&bull; <a href="#Recipes" accesskey="5">Recipes</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Building packages
 112 </td></tr>
 113 <tr><td align="left" valign="top">&bull; <a href="#Order-files" accesskey="6">Order files</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Handling build order
 114 </td></tr>
 115 <tr><td align="left" valign="top">&bull; <a href="#Examining-packages" accesskey="7">Examining packages</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Debugging purposes
 116 </td></tr>
 117 <tr><td align="left" valign="top">&bull; <a href="#Exit-status" accesskey="8">Exit status</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Exit codes
 118 </td></tr>
 119 <tr><td align="left" valign="top">&bull; <a href="#License" accesskey="9">License</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">GNU Free Documentation License
 120 </td></tr>
 121 <tr><td align="left" valign="top">&bull; <a href="#Index">Index</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 122 </td></tr>
 123 </table>
 124
 125 <br>
 126 <p>Copyright (C) 2019 Matias Fonzo.
 127 </p>
 128 <p>Qi&rsquo;s home page can be found at <a href="http://www.dragora.org">http://www.dragora.org</a>.
 129 Send&nbsp;bug&nbsp;reports&nbsp;or&nbsp;suggestions&nbsp;to&nbsp;<a href="mailto:dragora-users@nongnu.org"><span class="nolinebreak">dragora-users</span>@nongnu.org</a>.<!-- /@w -->
 130 </p>
 131 <hr>
 132 <span id="Introduction"></span><div class="header">
 133 <p>
 134 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> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 135 </div>
 136 <span id="Introduction-1"></span><h2 class="chapter">1 Introduction</h2>
 137 <span id="index-introduction"></span>
 138
 139 <p>Qi is a simple but well-integrated package manager.  It can creates,
 140 install, remove, and upgrade software packages.  Qi produces binary
 141 packages using recipe names, these are files containing specific
 142 instructions to build every source.  Qi can manage multiple packages
 143 under a single directory hierarchy, this method allows to maintain a set
 144 of packages and multiple versions of them.  This means that Qi could be
 145 used as the main package manager or complement the existing one.
 146 </p>
 147 <p>Qi offers a friendly command line interface, a global configuration file,
 148 a simple recipe layout to deploy software packages; also works with binary
 149 packages in parallel, speeding up installations and packages in
 150 production.  The used format for packages is a simplified but safe POSIX
 151 pax archive compressed with lzip.
 152 </p>
 153 <p>Qi is a modern (POSIX-compliant) shell script released under the terms of
 154 the GNU General Public License.  There are only two major dependencies for
 155 the magic: graft(1) and tarlz(1), the rest is expected to be found in any
 156 Unix-like system.
 157 </p>
 158 <hr>
 159 <span id="Invoking-qi"></span><div class="header">
 160 <p>
 161 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> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 162 </div>
 163 <span id="Invoking-qi-1"></span><h2 class="chapter">2 Invoking qi</h2>
 164 <span id="index-invocation"></span>
 165
 166 <p>This chapter describes the synopsis and command line options for
 167 invoke Qi.
 168 </p>
 169 <div class="example">
 170 <pre class="example">Usage: qi [<var>OPTION</var>]... [<var>FILE</var>]...
 171 </pre></div>
 172
 173 <p>One mandatory option specifies the operation that &lsquo;<samp>qi</samp>&rsquo; should
 174 perform, other options are meant to detail how this operation should be
 175 performed.
 176 </p>
 177 <p>qi supports the following options to operate:
 178 </p>
 179 <dl compact="compact">
 180 <dt><code>-b</code></dt>
 181 <dd><p>Build package using recipe names.
 182 </p>
 183 </dd>
 184 <dt><code>-c</code></dt>
 185 <dd><p>Create .tlz package from directory.
 186 </p>
 187 </dd>
 188 <dt><code>-d</code></dt>
 189 <dd><p>Delete packages.
 190 </p>
 191 </dd>
 192 <dt><code>-i</code></dt>
 193 <dd><p>Install packages.
 194 </p>
 195 </dd>
 196 <dt><code>-o</code></dt>
 197 <dd><p>Resolve build order through .order files.
 198 </p>
 199 </dd>
 200 <dt><code>-u</code></dt>
 201 <dd><p>Update packages (implies -i, -d and -p options).
 202 </p>
 203 </dd>
 204 <dt><code>-w</code></dt>
 205 <dd><p>Warn about files that will be linked.
 206 </p>
 207 </dd>
 208 <dt><code>-x</code></dt>
 209 <dd><p>Extract a package for debugging purposes.
 210 </p></dd>
 211 </dl>
 212
 213 <p>There are common options between modes:
 214 </p>
 215 <dl compact="compact">
 216 <dt><code>-N</code></dt>
 217 <dd><p>Do not read the configuration file.
 218 </p>
 219 <p>This will omit any value on the qirc file.
 220 </p>
 221 </dd>
 222 <dt><code>-P &lt;DIR&gt;</code></dt>
 223 <dd><p>Package directory for installations.
 224 </p>
 225 <p>This option sets &lsquo;<samp>${packagedir}</samp>&rsquo;.
 226 </p>
 227 <p>Only valid for -i, -d, or -u options.
 228 </p>
 229 </dd>
 230 <dt><code>-f</code></dt>
 231 <dd><p>Force option.
 232 </p>
 233 <p>This can force the build of a recipe, or update a pre-existing package.
 234 </p>
 235 <p>Only valid for -b, -u options.
 236 </p>
 237 </dd>
 238 <dt><code>-t &lt;DIR&gt;</code></dt>
 239 <dd><p>Target directory for symbolic links.
 240 </p>
 241 <p>This option sets &lsquo;<samp>${targetdir}</samp>&rsquo;.
 242 </p>
 243 <p>Only valid for -i, -d, or -u options.
 244 </p>
 245 </dd>
 246 <dt><code>-k</code></dt>
 247 <dd><p>Keep (don&rsquo;t delete) &lsquo;<samp>${srcdir}</samp>&rsquo; or &lsquo;<samp>${destdir}</samp>&rsquo; on build
 248 mode.
 249 </p>
 250 <p>Keep (don&rsquo;t delete) package directory on delete mode.
 251 </p>
 252 <p>Only valid for -b, -d or -u options.
 253 </p>
 254 </dd>
 255 <dt><code>-p</code></dt>
 256 <dd><p>Prune conflicts on package installations.
 257 </p>
 258 <p>This option may proceed with the package installation if one or
 259 more conflicts occur.
 260 </p>
 261 </dd>
 262 <dt><code>-r /rootdir</code></dt>
 263 <dd><p>Use the fully qualified named directory as the root directory for all
 264 qi operations.  The target directory and package directory will
 265 be relative to the specified directory.
 266 </p>
 267 </dd>
 268 <dt><code>-v</code></dt>
 269 <dd><p>Be verbose (a 2nd -v gives more).
 270 </p></dd>
 271 </dl>
 272
 273 <p>Options for build mode (-b):
 274 </p>
 275 <dl compact="compact">
 276 <dt><code>-O &lt;DIR&gt;</code></dt>
 277 <dd><p>Where the produced packages are written.
 278 </p>
 279 <p>This option sets &lsquo;<samp>${outdir}</samp>&rsquo;.
 280 </p>
 281 </dd>
 282 <dt><code>-W &lt;DIR&gt;</code></dt>
 283 <dd><p>Where archives, patches, and recipes are expected.
 284 </p>
 285 <p>This option sets &lsquo;<samp>${worktree}</samp>&rsquo;.
 286 </p>
 287 </dd>
 288 <dt><code>-Z &lt;DIR&gt;</code></dt>
 289 <dd><p>Where (compressed) sources will be found.
 290 </p>
 291 <p>This option sets &lsquo;<samp>${tardir}</samp>&rsquo;.
 292 </p>
 293 </dd>
 294 <dt><code>-a</code></dt>
 295 <dd><p>Architecture to use.
 296 </p>
 297 <p>Default value is obtained via uname(1) as &lsquo;<samp>uname -m</samp>&rsquo;.
 298 </p>
 299 </dd>
 300 <dt><code>-j</code></dt>
 301 <dd><p>Parallel jobs for the compiler.
 302 </p>
 303 <p>If not specified, default sets to 1.
 304 </p>
 305 </dd>
 306 <dt><code>-1</code></dt>
 307 <dd><p>Increment release number (&lsquo;<samp>${release}</samp>&rsquo; + 1).
 308 </p>
 309 <p>It will be omitted if the -n option is being used.
 310 </p>
 311 </dd>
 312 <dt><code>-n</code></dt>
 313 <dd><p>Don&rsquo;t create a .tlz package.
 314 </p>
 315 </dd>
 316 <dt><code>-S</code></dt>
 317 <dd><p>Selects the option to skip completed recipes.
 318 </p>
 319 <p>This means, in interactive mode, when the dialog
 320 to summarize recipes is showed.
 321 </p></dd>
 322 </dl>
 323
 324 <p>Informative options:
 325 </p>
 326 <dl compact="compact">
 327 <dt><code>-L</code></dt>
 328 <dd><p>Print default directory locations.
 329 </p>
 330 <p>This will print the target directory, package directory, working tree,
 331 the directory for tarballs, and the output directory for produced
 332 packages.
 333 </p>
 334 </dd>
 335 <dt><code>-h</code></dt>
 336 <dd><p>Display the help describing the options and then exit.
 337 </p>
 338 </dd>
 339 <dt><code>-V</code></dt>
 340 <dd><p>Print the version number and license information.
 341 The version number should be included in all bug reports.
 342 </p></dd>
 343 </dl>
 344
 345 <p>Expected arguments beyond of options are package directories and regular
 346 files: recipes or files ending in .tlz, .order.  When FILE is -, qi can
 347 read from the standard input.  See examples in <a href="#Packages">Packages</a>.
 348 </p>
 349
 350 <hr>
 351 <span id="The-qirc-file"></span><div class="header">
 352 <p>
 353 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> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 354 </div>
 355 <span id="The-qirc-file-1"></span><h2 class="chapter">3 The qirc file</h2>
 356 <span id="index-configuration-file"></span>
 357
 358 <p>The global <samp>qirc</samp> file offers a way to define variables and tools
 359 (such as a download manager) for default use.  This file is used by qi
 360 at runtime for e.g to build, install, remove or upgrade packages.
 361 </p>
 362 <p>It has the following rules:
 363 </p>
 364 <ul>
 365 <li> Variables must be declared as &lsquo;<samp>name=value</samp>&rsquo;.
 366
 367 </li><li> Declaration of values should only take one line, no line break.
 368
 369 </li><li> For security reasons, assignments like &lsquo;<samp>name=$var</samp>&rsquo; are only
 370 interpreted as literal.
 371 </li></ul>
 372
 373 <p>The command line options related to the package directory and target
 374 directory plus some of the options used for the build mode can override
 375 some values in <samp>qirc</samp>.  See <a href="#Invoking-qi">Invoking qi</a>.
 376 </p>
 377 <p>The order in which qi looks for this file is:
 378 </p>
 379 <ol>
 380 <li> <code>${HOME}/.qirc</code>
 381  Effective user.
 382
 383 </li><li> &lsquo;<samp>${sysconfdir}/qirc</samp>&rsquo;
 384  System-wide.
 385 </li></ol>
 386
 387 <p>If you intend to run qi as effective user, the file
 388 &lsquo;<samp>${sysconfdir}/qirc</samp>&rsquo; could be copied to <code>${HOME}/.qirc</code>
 389 setting the paths for &lsquo;<samp>${packagedir}</samp>&rsquo; and &lsquo;<samp>${targetdir}</samp>&rsquo;
 390 according to the <code>$HOME</code>.
 391 </p>
 392
 393 <hr>
 394 <span id="Packages"></span><div class="header">
 395 <p>
 396 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> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 397 </div>
 398 <span id="Packages-1"></span><h2 class="chapter">4 Packages</h2>
 399 <span id="index-managing-packages"></span>
 400
 401 <p>A package is a suite of programs usually distributed in binary form
 402 which may also contain manual pages, documentation, or any other file
 403 associated to a specific software.
 404 </p>
 405 <p>The package format used by qi is a simplified POSIX pax archive
 406 compressed with lzip.  The file extension for packages ends in .tlz
 407 </p>
 408 <p>Both package installation and package de-installation are managed using
 409 two important (internal) variables: &lsquo;<samp>${packagedir}</samp>&rsquo; and
 410 &lsquo;<samp>${targetdir}</samp>&rsquo;, these values can be changed in the
 411 configuration file or via options.
 412 </p>
 413 <p>&lsquo;<samp>${packagedir}</samp>&rsquo; is a common directory tree where the package
 414 contents will be decompressed (will reside).
 415 </p>
 416 <p>&lsquo;<samp>${targetdir}</samp>&rsquo; is a target directory where the links will be
 417 made by graft(1) taking &lsquo;<samp>${packagedir}/package_name</samp>&rsquo; into account.
 418 </p>
 419 <p>Packages are installed in self-contained directory trees and symbolic
 420 links from a common area are made to the package files.  This allows
 421 multiple versions of the same package to co-exist on the one system.
 422 </p>
 423 <span id="Package-conflicts"></span><h3 class="section">4.1 Package conflicts</h3>
 424 <span id="index-package-conflicts"></span>
 425
 426 <p>All the links to install or remove a package are handled by graft(1).
 427 Since multiple packages can be installed or removed at the same time,
 428 certain conflicts may arise between the packages.
 429 </p>
 430 <p>graft<a id="DOCF1" href="#FOOT1"><sup>1</sup></a>
 431 defines a CONFLICT as one of the following conditions:
 432 </p>
 433 <ul>
 434 <li> If the package object is a directory and the target object exists but is
 435 not a directory.
 436
 437 </li><li> If the package object is not a directory and the target object exists
 438 and is not a symbolic link.
 439
 440 </li><li> If the package object is not a directory and the target object exists
 441 and is a symbolic link to something other than the package object.
 442 </li></ul>
 443
 444 <p>The default behavior of qi for an incoming package is to ABORT if a
 445 conflict arises.  When a package is going to be deleted, qi tells to
 446 graft(1) to remove those parts that are not in conflict, leaving the
 447 links to the belonging package.  This behavior can be forced if the
 448 -p option is given.
 449 </p>
 450 <span id="Installing-packages"></span><h3 class="section">4.2 Installing packages</h3>
 451 <span id="index-package-installation"></span>
 452
 453 <p>To install a single package, simply type:
 454 </p>
 455 <div class="example">
 456 <pre class="example">qi -i coreutils-8.30-i586+1.tlz
 457 </pre></div>
 458
 459 <p>To install multiple packages at once, type:
 460 </p>
 461 <div class="example">
 462 <pre class="example">qi -i gcc-8.3.0-i586+1.tlz rafaela-2.2-i586+1.tlz ...
 463 </pre></div>
 464
 465 <p>Warn about the files that will be linked:
 466 </p>
 467 <div class="example">
 468 <pre class="example">qi -w bash-5.0-i586+1.tlz
 469 </pre></div>
 470
 471 <p>This is to verify the content of a package before installing it.
 472 </p>
 473 <p>See the process of an installation (very verbose):
 474 </p>
 475 <div class="example">
 476 <pre class="example">qi -i -v mariana-3.0-i586+1.tlz
 477 </pre></div>
 478
 479 <p>A second -v gives more.
 480 </p>
 481 <p>Installing package in a different location:
 482 </p>
 483 <div class="example">
 484 <pre class="example">qi -r /media/floppy -i lzip-1.21-i586+1.tlz
 485 </pre></div>
 486
 487 <p>The -r option assumes &lsquo;<samp>${targetdir}</samp>&rsquo; and &lsquo;<samp>${packagedir}</samp>&rsquo;.
 488 See:
 489 </p>
 490 <div class="example">
 491 <pre class="example">qi -r /home/selk -P /pkgs -t / -i lzip-1.21-i586+1.tlz
 492 </pre></div>
 493
 494 <p>In this case the content of &quot;lzip-1.21-i586+1.tlz&quot; will be decompressed
 495 into &lsquo;<samp>/home/selk/pkgs/lzip-1.21-i586+1</samp>&rsquo;.  Assuming that the main
 496 binary for lzip is under &lsquo;<samp>/home/selk/pkgs/lzip-1.21-i586+1/usr/bin/</samp>&rsquo;
 497 the target for &quot;usr/bin&quot; will be created at &lsquo;<samp>/home/selk</samp>&rsquo;.  Considering
 498 that you have exported the <code>PATH</code> as &lsquo;<samp>${HOME}/usr/bin</samp>&rsquo;, now the
 499 system is able to see the recent lzip.
 500 </p>
 501 <p>Installing from a list of packages using standard input:
 502 </p>
 503 <div class="example">
 504 <pre class="example">cat FILELIST.txt | qi -i -
 505 </pre></div>
 506
 507 <p>The list of packages must contain full path names to be passed in the
 508 installation, e.g:
 509 /var/cache/qi/packages/x86_64/devel/tcl-8.6.9-x86_64+1.tlz
 510 /var/cache/qi/packages/x86_64/devel/tk-8.6.9.1-x86_64+1.tlz
 511 /var/cache/qi/packages/x86_64/devel/vala-0.42.3-x86_64+1.tlz
 512 </p>
 513 <span id="Removing-packages"></span><h3 class="section">4.3 Removing packages</h3>
 514 <span id="index-package-de_002dinstallation"></span>
 515
 516 <p>To remove a package, simply type:
 517 </p>
 518 <div class="example">
 519 <pre class="example">qi -d xz-5.2.4-i586+1.tlz
 520 </pre></div>
 521
 522 <p>Delete mode will match the package name using &lsquo;<samp>${packagedir}</samp>&rsquo; as
 523 prefix.  For example, if the value of &lsquo;<samp>${packagedir}</samp>&rsquo; is set to
 524 /usr/local/pkgs, this will be equal to:
 525 </p>
 526 <div class="example">
 527 <pre class="example">qi -d /usr/local/pkgs/xz-5.2.4-i586+1
 528 </pre></div>
 529
 530 <p>Detailed output (very verbose):
 531 </p>
 532 <div class="example">
 533 <pre class="example">qi -d -v /usr/local/pkgs/xz-5.2.4-i586+1
 534 </pre></div>
 535
 536 <p>A second -v gives more.
 537 </p>
 538 <p>By default the delete mode does not preserve a package directory after
 539 removing its links from &lsquo;<samp>${targetdir}</samp>&rsquo;, but this behavior can be
 540 changed if the -k option is passed:
 541 </p>
 542 <div class="example">
 543 <pre class="example">qi -d -k /usr/local/pkgs/lzip-1.21-i586+1
 544 </pre></div>
 545
 546 <p>This means that the links to the package can be reactivated, later:
 547 </p>
 548 <div class="example">
 549 <pre class="example">cd /usr/local/pkgs &amp;&amp; graft -i lzip-1.21-i586+1
 550 </pre></div>
 551
 552 <p>Removing package from a different location:
 553 </p>
 554 <div class="example">
 555 <pre class="example">qi -r /home/cthulhu -P /pkgs -t / -d xz-5.2.4-i586+1
 556 </pre></div>
 557
 558 <p>Removing a package using standard input:
 559 </p>
 560 <div class="example">
 561 <pre class="example">echo &quot;vala-0.42.3-x86_64+1&quot; | qi -d -
 562 </pre></div>
 563
 564 <p>This will match with the package directory.
 565 </p>
 566 <span id="Upgrading-packages"></span><h3 class="section">4.4 Upgrading packages</h3>
 567 <span id="index-package-upgrade"></span>
 568
 569 <p>The upgrade mode inherits the properties of the installation and removal
 570 process.  To make sure that a package is updated, the package is installed
 571 in a temporary directory taking &lsquo;<samp>${packagedir}</samp>&rsquo; into account.  Once
 572 the incoming package is pre-installed, qi can proceed to search and delete
 573 packages that have the same name (considered as previous ones).  Finally,
 574 the package is re-installed at its final location and the temporary
 575 directory is removed.
 576 </p>
 577 <p>To upgrade a package, just type:
 578 </p>
 579 <div class="example">
 580 <pre class="example">qi -u gcc-9.0.1-i586+1.tlz
 581 </pre></div>
 582
 583 <p>This will proceed to update &quot;gcc-9.0.1-i586+1&quot; removing other versions
 584 of &quot;gcc&quot; (if any).
 585 </p>
 586 <p>If you want to keep the package directory of found versions during the
 587 upgrade process, just pass:
 588 </p>
 589 <div class="example">
 590 <pre class="example">qi -u -k gcc-9.0.1-i586+1.tlz
 591 </pre></div>
 592
 593 <p>To see the upgrade process (very verbose):
 594 </p>
 595 <div class="example">
 596 <pre class="example">qi -u -v gcc-9.0.1-i586+1.tlz
 597 </pre></div>
 598
 599 <p>A second -v gives more.
 600 </p>
 601 <p>To force the upgrade of an existing package:
 602 </p>
 603 <div class="example">
 604 <pre class="example">qi -u -f gcc-9.0.1-i586+1.tlz
 605 </pre></div>
 606
 607 <span id="Package-blacklist"></span><h4 class="subsection">4.4.1 Package blacklist</h4>
 608 <span id="index-package-blacklist"></span>
 609
 610 <p>To enforce general package facilities, either to install, remove or
 611 maintain the hierarchy of packages in a clean manner, qi makes use of the
 612 pruning operation via graft(1):
 613 </p>
 614 <p>There is a risk if those are crucial packages for the proper functioning
 615 of the system, because it implies to deactivate symbolic links from the
 616 target directory, <em>especially</em> when transitioning an incoming package
 617 into its final location during upgrade.
 618 </p>
 619 <p>A blacklist for declare package names has been devised for this cases,
 620 in case that a user decides to upgrade all packages in the system or,
 621 just the crucial ones, such as the C library.
 622 </p>
 623 <p>The blacklist is related to the upgrade mode only, consists in installing
 624 a package instead of updating it or removing previous versions of it;
 625 the content of the package will be updated over the existing content at
 626 &lsquo;<samp>${packagedir}</samp>&rsquo;, while the existing links from
 627 &lsquo;<samp>${targetdir}</samp>&rsquo; will be preserved.  A pruning of links will carried
 628 out in order to re-link possible differences with the recent content, this
 629 helps to avoid having dead links in the target directory.
 630 </p>
 631 <p>Since the upgrade mode is also used to install a new package, the mechanism
 632 for blacklist is to install a declared package if it does not already
 633 exist, if it already exists, it is verified that the binary package is
 634 newer than the package directory in order to perform an update.
 635 </p>
 636 <p>Package names for the blacklist can be set from the configuration file.
 637 </p>
 638
 639 <hr>
 640 <span id="Recipes"></span><div class="header">
 641 <p>
 642 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> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 643 </div>
 644 <span id="Recipes-1"></span><h2 class="chapter">5 Recipes</h2>
 645 <span id="index-recipes"></span>
 646
 647 <p>A recipe is a file telling qi what to do.  Most often, the recipe tells to
 648 qi how to build a binary package from a source tarball.
 649 </p>
 650 <p>A recipe has two parts: a list of variable definitions and a list of
 651 sections.  By convention, the syntax of a section is:
 652 </p>
 653 <div class="example">
 654 <pre class="example">section_name()
 655 {
 656     section lines
 657 }
 658 </pre></div>
 659
 660 <p>The section name is followed by parentheses, one newline and an opening
 661 brace.  The line finishing the section contains just a closing brace.
 662 The section names or the function names currently recognized are
 663 &lsquo;<samp>build</samp>&rsquo;.
 664 </p>
 665 <p>The &lsquo;<samp>build</samp>&rsquo; section is an augmented shell script.  This is the main
 666 section (or <strong>shell function</strong>) which contains the instructions to
 667 build and produce a package.
 668 </p>
 669 <span id="Variables"></span><h3 class="section">5.1 Variables</h3>
 670 <span id="index-variables"></span>
 671
 672 <p>A &quot;variable&quot; is a <strong>shell variable</strong> defined either in <samp>qirc</samp>
 673 or in a recipe to represent a string of text, called the variable&rsquo;s
 674 &quot;value&quot;.  These values are substituted by explicit request in the
 675 definitions of other variables or in calls to external commands.
 676 </p>
 677 <p>Variables can represent lists of file names, options to pass to
 678 compilers, programs to run, directories to look in for source files,
 679 directories to write output in, or anything else you can imagine.
 680 </p>
 681 <p>Definitions of variables in qi have four levels of precedence.
 682 Options which define variables from the command-line override those
 683 specified in the <samp>qirc</samp> file, while variables defined in the recipe
 684 override those specified in <samp>qirc</samp>, taking priority over those
 685 variables settled by options via command-line.  Finally, the variables
 686 have default values if they are not defined anywhere.
 687 </p>
 688 <p>Options that set variables through the command-line can only reference
 689 variables defined in <samp>qirc</samp> and variables with default values.
 690 </p>
 691 <p>Definitions of variables in <samp>qirc</samp> can only reference variables
 692 previously defined in <samp>qirc</samp> and variables with default values.
 693 </p>
 694 <p>Definitions of variables in the recipe can only reference variables
 695 settled by command-line, variables previously defined in the recipe,
 696 variables defined in <samp>qirc</samp>, and variables with default values.
 697 </p>
 698 <span id="Special-variables"></span><h3 class="section">5.2 Special variables</h3>
 699 <span id="index-special-variables"></span>
 700
 701 <p>There are variables which can only be set using the command line options or
 702 via <samp>qirc</samp>, there are other special variables which can be defined or
 703 redefined in a recipe.  See the following definitions:
 704 </p>
 705 <p>&lsquo;<samp>outdir</samp>&rsquo; is the directory where the produced packages are written.
 706 This variable can not be redefined in the recipe.  Default sets to
 707 &lsquo;<samp>/var/cache/qi/packages</samp>&rsquo;.
 708 </p>
 709 <p>&lsquo;<samp>worktree</samp>&rsquo; is the working tree where archives, patches, and recipes
 710 are expected.  This variable can not be redefined in the recipe.  Default
 711 sets to &lsquo;<samp>/usr/src/qi</samp>&rsquo;.
 712 </p>
 713 <p>&lsquo;<samp>tardir</samp>&rsquo; is defined in the recipe to the directory where the tarball
 714 containing the source can be found.  The full name of the tarball is
 715 composed as &lsquo;<samp>${tardir}/$tarname</samp>&rsquo;.  Its value is available in the
 716 recipe as &lsquo;<samp>${tardir}</samp>&rsquo;; a value of . for &lsquo;<samp>tardir</samp>&rsquo; sets it to
 717 the value of CWD (Current Working Directory), this is where the recipe
 718 lives.
 719 </p>
 720 <p>&lsquo;<samp>arch</samp>&rsquo; is the architecture to compose the package name.  Its value is
 721 available in the recipe as &lsquo;<samp>${arch}</samp>&rsquo;.  Default value is the output
 722 of &lsquo;<samp>uname -m</samp>&rsquo;.
 723 </p>
 724 <p>&lsquo;<samp>jobs</samp>&rsquo; is the number of parallel jobs to pass to the compiler.  Its
 725 value is available in the recipe as &lsquo;<samp>${jobs}</samp>&rsquo;.  Default sets to
 726 &lsquo;<samp>1</samp>&rsquo;.
 727 </p>
 728 <p>The two variables &lsquo;<samp>${srcdir}</samp>&rsquo; and &lsquo;<samp>${destdir}</samp>&rsquo; can be
 729 set in the recipe, as any other variable, but if they are not, qi uses
 730 default values for them when building a package.
 731 </p>
 732 <p>&lsquo;<samp>srcdir</samp>&rsquo; contains the source code to be compiled, and defaults to
 733 &lsquo;<samp>${program}-${version}</samp>&rsquo;.  &lsquo;<samp>destdir</samp>&rsquo; is the place where the
 734 built package will be installed, and defaults to
 735 &lsquo;<samp>${TMPDIR}/package-${program}</samp>&rsquo;.
 736 </p>
 737 <p>If &lsquo;<samp>pkgname</samp>&rsquo; is left undefined, the special variable &lsquo;<samp>program</samp>&rsquo;
 738 is assigned by default.  If &lsquo;<samp>pkgversion</samp>&rsquo; is left undefined, the
 739 special variable &lsquo;<samp>version</samp>&rsquo; is assigned by default.
 740 </p>
 741 <p>&lsquo;<samp>pkgname</samp>&rsquo; and &lsquo;<samp>pkgversion</samp>&rsquo; along with: &lsquo;<samp>version</samp>&rsquo;, &lsquo;<samp>arch</samp>&rsquo;,
 742 and &lsquo;<samp>release</samp>&rsquo; are used to produce the name of the package in the form:
 743 &lsquo;<samp>${pkgname}-${pkgversion}-${arch}+${release}.tlz</samp>&rsquo;
 744 </p>
 745 <p>A special variable called &lsquo;<samp>replace</samp>&rsquo; can be used to declare package
 746 names that will be replaced at the time of installation.
 747 </p>
 748 <p>A typical recipe contains the following variables:
 749 </p>
 750 <ul>
 751 <li> &lsquo;<samp>program</samp>&rsquo;: software name.
 752
 753 <p>It matches the source name.  It is also used to compose the name of the
 754 package if &lsquo;<samp>${pkgname}</samp>&rsquo; is not specified.
 755 </p>
 756 </li><li> &lsquo;<samp>version</samp>&rsquo;: software version.
 757
 758 <p>It matches the source name.  It is also used to compose the version of the
 759 package if &lsquo;<samp>${pkgversion}</samp>&rsquo; is not specified.
 760 </p>
 761 </li><li> &lsquo;<samp>arch</samp>&rsquo;: software architecture.
 762
 763 <p>It is used to compose the architecture of the package in which it is
 764 build.
 765 </p>
 766 </li><li> &lsquo;<samp>release</samp>&rsquo;: release number.
 767
 768 <p>This is used to reflect the release number of the package.  It is
 769 recommended to increase this number after any significant change in
 770 the recipe or post-install script.
 771 </p></li></ul>
 772
 773 <p>Obtaining sources over the network must be declared in the recipe using
 774 the &lsquo;<samp>fetch</samp>&rsquo; variable.  Use double quotes for separated values.
 775 </p>
 776 <p>The variables &lsquo;<samp>netget</samp>&rsquo; and &lsquo;<samp>rsync</samp>&rsquo; can be defined in <samp>qirc</samp>
 777 to establish a network downloader in order to get the sources.  If they
 778 are not defined, qi uses default values:
 779 </p>
 780 <p>&lsquo;<samp>netget</samp>&rsquo; is the general network downloader tool, defaults sets to
 781 &lsquo;<samp>wget -c -w1 -t3 --no-check-certificate</samp>&rsquo;.
 782 </p>
 783 <p>&lsquo;<samp>rsync</samp>&rsquo; is the network tool for sources containing the prefix for
 784 the RSYNC protocol, default sets to
 785 &lsquo;<samp>rsync -v -a -L -z -i --progress</samp>&rsquo;.
 786 </p>
 787 <p>The variable &lsquo;<samp>description</samp>&rsquo; is used to print the package description
 788 when a package is installed.
 789 </p>
 790 <p>A description has two parts: a brief description, and a long description.
 791 By convention, the syntax of &lsquo;<samp>description</samp>&rsquo; is:
 792 </p>
 793 <div class="example">
 794 <pre class="example">description=&quot;
 795 Brief description.
 796
 797 Long description.
 798 &quot;
 799 </pre></div>
 800
 801 <p>The first (substantial) line of the value is a brief description of the
 802 software (called &quot;blurb&quot;).  A newline follows to separate the <em>brief
 803 description</em> from the <em>long description</em>.
 804 </p>
 805 <p>An example looks like:
 806 </p>
 807 <div class="example">
 808 <pre class="example">description=&quot;
 809 The GNU core utilities.
 810
 811 The GNU core utilities are the basic file, shell and text manipulation
 812 utilities of the GNU operating system.  These are the core utilities
 813 which are expected to exist on every operating system.
 814 &quot;
 815 </pre></div>
 816
 817 <p>Please consider a length limit of 78 characters as maximum, because the same
 818 one would be used on the meta file creation.  See
 819 <a href="#Recipes">The meta file</a> section.
 820 </p>
 821 <p>The &lsquo;<samp>homepage</samp>&rsquo; variable is used to declare the main site or home page:
 822 </p>
 823 <div class="example">
 824 <pre class="example">homepage=http://www.gnu.org/software/gcc
 825 </pre></div>
 826
 827 <p>The variable &lsquo;<samp>license</samp>&rsquo; is used for license information<a id="DOCF2" href="#FOOT2"><sup>2</sup></a>.
 828 Some code in the program can be covered by license A, license B, or
 829 license C.  For &quot;separate licensing&quot; or &quot;heterogeneous licensing&quot;, we
 830 suggest using <strong>|</strong> for a disjunction, <strong>&amp;</strong> for a conjunction
 831 (if that ever happens in a significant way), and comma for heterogeneous
 832 licensing.  Comma would have lower precedence, plus added special terms.
 833 </p>
 834 <div class="example">
 835 <pre class="example">license=&quot;LGPL, GPL | Artistic + added permission&quot;
 836 </pre></div>
 837
 838 <span id="Building-packages"></span><h3 class="section">5.3 Building packages</h3>
 839 <span id="index-package-build"></span>
 840
 841 <p>A recipe is any valid regular file, qi sets priorities to read a recipe,
 842 for example, the Current Working Directory has priority over the working
 843 tree (or where the recipes reside); the &lsquo;<samp>${worktree}/recipes</samp>&rsquo; is
 844 the second place where to find a recipe, we complete the possibility of
 845 using the directory name to invoke a recipe if it contains &quot;recipe&quot; as a
 846 valid file name.
 847 </p>
 848 <p>To build a single package, type:
 849 </p>
 850 <div class="example">
 851 <pre class="example">qi -b x-apps/xterm
 852 </pre></div>
 853
 854 <p>Multiple jobs can be passed to the compiler for speed up the build process:
 855 </p>
 856 <div class="example">
 857 <pre class="example">qi -b -j3 x-apps/xterm
 858 </pre></div>
 859
 860 <p>Update or install the produced package (if it is not already installed)
 861 when finish:
 862 </p>
 863 <div class="example">
 864 <pre class="example">qi -b -j3 -u x-apps/xterm
 865 </pre></div>
 866
 867 <p>Only process a recipe but do not create the binary package:
 868 </p>
 869 <div class="example">
 870 <pre class="example">qi -b -n dict/aspell
 871 </pre></div>
 872
 873 <p>The options -i or -u have no effect when -n is given.
 874 </p>
 875 <p>This can be useful to inspect the build process of recipe:
 876 </p>
 877 <p>qi -b -k -n dict/aspell 2&gt;&amp;1 | tee aspell-buildlog.txt
 878 </p>
 879 <p>The -k option could preserve the source directory and the destination
 880 directory for later inspection.  A log file of the build process will be
 881 created redirecting both, standard error and standard output to tee(1).
 882 </p>
 883 <span id="Variables-from-the-environment"></span><h3 class="section">5.4 Variables from the environment</h3>
 884 <span id="index-environment-variables"></span>
 885
 886 <p>Qi has environment variables which can be used at build time:
 887 </p>
 888 <p>The variable <code>TMPDIR</code> sets the temporary directory for sources, by
 889 default, this is used to prepend &lsquo;<samp>${srcdir}</samp>&rsquo; and
 890 &lsquo;<samp>${destdir}</samp>&rsquo;.  By convention its value is &lsquo;<samp>/tmp</samp>&rsquo;.
 891 </p>
 892 <p>The variables <code>QICFLAGS</code>, <code>QICXXFLAGS</code>, and <code>QILDFLAGS</code> have
 893 no effect by default.  The environment variables such as <code>CFLAGS</code>,
 894 <code>CXXFLAGS</code>, and <code>LDFLAGS</code> are unset at compile time:
 895 </p>
 896 <p>Recommended practices is to set variables in front of &lsquo;<samp>configure</samp>&rsquo;
 897 or in front of <em>make(1)</em> instead of exporting to the environment.
 898 As follows:
 899 </p>
 900 <blockquote>
 901 <p>Variables not defined in a site shell script can be set in the environment
 902 passed to configure.  However, some packages may run configure again
 903 during the build, and the customized values of these variables may be
 904 lost.  In order to avoid this problem, you should set them in the
 905 configure command line, using &lsquo;<samp>VAR=value</samp>&rsquo;.  For example:
 906 </p>
 907 <p><code>./configure CC=/usr/local2/bin/gcc</code>
 908 </p>
 909 <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>
 910 </p></blockquote>
 911
 912 <blockquote>
 913 <p>Indeed, while configure can notice the definition of CC in
 914 &lsquo;<samp>./configure CC=bizarre-cc</samp>&rsquo;, it is impossible to notice it in
 915 &lsquo;<samp>CC=bizarre-cc ./configure</samp>&rsquo;, which, unfortunately, is what most
 916 users do.
 917 </p>
 918 <p>[...]
 919 </p>
 920 <p>configure: error: changes in the environment can compromise the build.
 921 </p>
 922 <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>
 923 </p></blockquote>
 924
 925 <blockquote>
 926 <p>It is not wise for makefiles to depend for their functioning on
 927 environment variables set up outside their control, since this would cause
 928 different users to get different results from the same makefile.  This is
 929 against the whole purpose of most makefiles.
 930 </p>
 931 <p><a href="http://gnu.org/software/make/manual/make.html#Environment">http://gnu.org/software/make/manual/make.html#Environment</a>
 932 </p></blockquote>
 933
 934 <span id="The-meta-file"></span><h3 class="section">5.5 The meta file</h3>
 935 <span id="index-the-meta-file"></span>
 936
 937 <p>The &quot;meta file&quot; is a regular file created during the build mode, it
 938 contains information about the package such as program name, program
 939 version, release, fetch address, description, and other minor data
 940 extracted from the processed recipe.  The name of the file is generated as
 941 &lsquo;<samp>${full_pkgname}.tlz.txt</samp>&rsquo;, it has the purpose to reflect essential
 942 information to the user without having to look inside the package content.
 943 </p>
 944 <p>The content of a meta file looks like:
 945 </p>
 946 <div class="example">
 947 <pre class="example">#
 948 # The Bourne Again SHell.
 949 #
 950 # Bash is an sh-compatible shell that incorporates useful features from
 951 # the Korn shell (ksh) and C shell (csh).  It is intended to conform to
 952 # the IEEE POSIX P1003.2/ISO 9945.2 shell and tools standard.
 953 #
 954 # It offers functional improvements over sh for both programming and
 955 # interactive use.
 956 #
 957
 958 QICFLAGS=&quot;-g0 -Os -mtune=generic -pipe&quot;
 959 QICXXFLAGS=&quot;-g0 -Os -mtune=generic -pipe&quot;
 960 QILDFLAGS=&quot;-s&quot;
 961 program=bash
 962 version=5.0
 963 release=1
 964 blurb=&quot;The Bourne Again SHell.&quot;
 965 homepage=&quot;http://www.gnu.org/software/bash&quot;
 966 license=&quot;GPLv3+&quot;
 967 fetch=&quot;ftp://ftp.gnu.org/gnu/bash/bash-5.0.tar.gz&quot;
 968 replace=&quot;&quot;
 969 </pre></div>
 970
 971 <p>A package description is extracted from the variable &lsquo;<samp>description</samp>&rsquo;,
 972 each line will be interpreted literally and pre-formatted to fit in
 973 (exactly) 80 columns, plus the character &lsquo;<samp># </samp>&rsquo; will be prefixed to
 974 each line in the description.
 975 </p>
 976 <p>In addition to the special variables, there are implicit variables such as
 977 &lsquo;<samp>blurb</samp>&rsquo;:
 978 </p>
 979 <p>The &lsquo;<samp>blurb</samp>&rsquo; variable is related to the special variable
 980 &lsquo;<samp>description</samp>&rsquo;.  Its value is composed using the first (substantial)
 981 line of &lsquo;<samp>description</samp>&rsquo; (mentioned as the &quot;brief description&quot;).
 982 </p>
 983
 984 <hr>
 985 <span id="Order-files"></span><div class="header">
 986 <p>
 987 Next: <a href="#Examining-packages" accesskey="n" rel="next">Examining packages</a>, Previous: <a href="#Recipes" accesskey="p" rel="prev">Recipes</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 988 </div>
 989 <span id="Order-files-1"></span><h2 class="chapter">6 Order files</h2>
 990 <span id="index-handling-build-order"></span>
 991
 992 <p>The order mode has the purpose to resolve the build order through
 993 .order files.  A .order file contains a list of recipe names, by default
 994 does not perform any action other than to print a resolved list in descending
 995 order.  For example, if <strong>a</strong> depends on <strong>b</strong> and <strong>c</strong>,
 996 and <strong>c</strong> depends on <strong>b</strong> as well, the file might look like:
 997 </p>
 998 <div class="example">
 999 <pre class="example">a: c b
1000 b:
1001 c: b
1002 </pre></div>
1003
1004 <p>Each letter represents a recipe name, complete dependencies for
1005 the first recipe name are listed in descending order, which is
1006 printed from right to left, and removed from left to right:
1007 </p>
1008 <p><small>OUTPUT</small>
1009 </p>
1010 <div class="example">
1011 <pre class="example">b
1012 c
1013 a
1014 </pre></div>
1015
1016 <p>Declaration of blank lines, colons, parentheses, and end of line are
1017 ignored.  Comments are allowed for lines that begin with &lsquo;<samp>#</samp>&rsquo;.
1018 </p>
1019 <p>An order file could be used to build a serie of packages, for example, if
1020 the content is:
1021 </p>
1022 <div class="example">
1023 <pre class="example"># Image handling libraries
1024 libs/libjpeg-turbo: devel/nasm
1025 x-libs/jasper: libs/libjpeg-turbo
1026 libs/tiff: libs/libjpeg-turbo
1027 </pre></div>
1028
1029 <p>To proceed with each recipe, we can type:
1030 </p>
1031 <div class="example">
1032 <pre class="example">qi -o imglibs.order | qi -b -i -
1033 </pre></div>
1034
1035 <p>The output of &lsquo;<samp>qi -o imglibs.order</samp>&rsquo; tells to qi in which order it
1036 should build the recipes/packages:
1037 </p>
1038 <div class="example">
1039 <pre class="example">devel/nasm
1040 libs/libjpeg-turbo
1041 x-libs/jasper
1042 libs/tiff
1043 </pre></div>
1044
1045
1046 <hr>
1047 <span id="Examining-packages"></span><div class="header">
1048 <p>
1049 Next: <a href="#Exit-status" accesskey="n" rel="next">Exit status</a>, Previous: <a href="#Order-files" accesskey="p" rel="prev">Order files</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1050 </div>
1051 <span id="Examining-packages-1"></span><h2 class="chapter">7 Examining packages</h2>
1052 <span id="index-package-examination"></span>
1053
1054 <p>There is an option to make use of the &quot;extraction mode&quot; which serves to
1055 examine binary packages for debugging purposes.  The extraction mode
1056 consists of decompressing a package into a single directory, verifying
1057 its integrity and preserving its properties.
1058 </p>
1059 <div class="example">
1060 <pre class="example">qi -x mksh-R56c-x86_64+1.tlz
1061 </pre></div>
1062
1063 <p>This action will put the content of &quot;mksh-R56c-x86_64+1.tlz&quot; into a
1064 single directory, which is a private directory for the user who requested
1065 the action, creation mode will be 0700 <strong>(u=,g=rwx,o=rwx)</strong>.  The
1066 package content will reside on this location, default mask to deploy the
1067 content will be 0000 <strong>(u=rwx,g=rwx,o=rwx)</strong>.
1068 </p>
1069 <p>The creation of the custom directory is influenced by the value of the
1070 <code>TMPDIR</code> variable.
1071 </p>
1072
1073 <hr>
1074 <span id="Exit-status"></span><div class="header">
1075 <p>
1076 Next: <a href="#License" accesskey="n" rel="next">License</a>, Previous: <a href="#Examining-packages" accesskey="p" rel="prev">Examining packages</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1077 </div>
1078 <span id="Exit-status-1"></span><h2 class="chapter">8 Exit status</h2>
1079 <span id="index-exit-codes"></span>
1080
1081 <p>All the conditions of exit codes are described in this chapter.
1082 </p>
1083 <dl compact="compact">
1084 <dt>&lsquo;<samp>0</samp>&rsquo;</dt>
1085 <dd><p>Successful completion (no errors).
1086 </p>
1087 </dd>
1088 <dt>&lsquo;<samp>1</samp>&rsquo;</dt>
1089 <dd><p>Minor common errors:
1090 </p>
1091 <ul class="no-bullet">
1092 <li>- Help usage on illegal options or required arguments.
1093
1094 </li><li>- Program needed by qi (prerequisite) is not available.
1095 </li></ul>
1096
1097 </dd>
1098 <dt>&lsquo;<samp>2</samp>&rsquo;</dt>
1099 <dd><p>Command execution error:
1100 </p>
1101 <p>This code is used to return the evaluation of external commands and shell
1102 arguments in case of error.
1103 </p>
1104 </dd>
1105 <dt>&lsquo;<samp>3</samp>&rsquo;</dt>
1106 <dd><p>Integrity check error for compressed files.
1107 </p>
1108 <p>Compressed files means:
1109 </p>
1110 <ul class="no-bullet">
1111 <li>- Tarball files from tar(1).
1112 Supported extension: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
1113 .tar.xz, .txz
1114
1115 </li><li>- Tarballs files from tarlz(1).
1116 Supported extension: .tar.lz, .tlz
1117
1118 </li><li>- Zip files from unzip(1).
1119 Supported extension: .zip, .ZIP
1120
1121 </li><li>- Gzip files from gzip(1).
1122 Supported extension: .gz, .Z
1123
1124 </li><li>- Bzip2 files from bzip2(1).
1125 Supported extension: .bz2
1126
1127 </li><li>- Lzip files from lzip(1).
1128 Supported extension: .lz
1129
1130 </li><li>- Xz files from xz(1).
1131 Supported extension: .xz
1132 </li></ul>
1133
1134 </dd>
1135 <dt>&lsquo;<samp>4</samp>&rsquo;</dt>
1136 <dd><p>File empty, not regular, or expected.
1137 </p>
1138 <p>Commonly, it is expected:
1139 </p>
1140 <ul class="no-bullet">
1141 <li>- An argument for the mode of operation.
1142
1143 </li><li>- A readable file or directory.
1144
1145 </li><li>- A binary package (.tlz).
1146
1147 </li><li>- A valid recipe.
1148
1149 </li><li>- An order file (.order).
1150
1151 </li><li>- A protocol supported by the network downloader tool.
1152
1153 </li><li>- A checksum file (.sha256).
1154 </li></ul>
1155
1156 </dd>
1157 <dt>&lsquo;<samp>5</samp>&rsquo;</dt>
1158 <dd><p>Empty or not defined variable:
1159 </p>
1160 <p>This code is used to report empty or undefined variables; usually,
1161 variables coming from a recipe, or assigned arrays that are tested.
1162 </p>
1163 </dd>
1164 <dt>&lsquo;<samp>6</samp>&rsquo;</dt>
1165 <dd><p>Package already installed:
1166 </p>
1167 <p>The package directory for an incoming .tlz package that already exists.
1168 </p>
1169 </dd>
1170 <dt>&lsquo;<samp>10</samp>&rsquo;</dt>
1171 <dd><p>Network manager error:
1172 </p>
1173 <p>This code is used if the network downloader tool fails for some reason.
1174 </p></dd>
1175 </dl>
1176
1177
1178 <hr>
1179 <span id="License"></span><div class="header">
1180 <p>
1181 Next: <a href="#Index" accesskey="n" rel="next">Index</a>, Previous: <a href="#Exit-status" accesskey="p" rel="prev">Exit status</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1182 </div>
1183 <span id="GNU-Free-Documentation-License"></span><h2 class="appendix">Appendix A GNU Free Documentation License</h2>
1184
1185 <div align="center">Version 1.3, 3 November 2008
1186 </div>
1187
1188 <div class="display">
1189 <pre class="display">Copyright &copy; 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
1190 <a href="http://fsf.org/">http://fsf.org/</a>
1191
1192 Everyone is permitted to copy and distribute verbatim copies
1193 of this license document, but changing it is not allowed.
1194 </pre></div>
1195
1196 <ol start="0">
1197 <li> PREAMBLE
1198
1199 <p>The purpose of this License is to make a manual, textbook, or other
1200 functional and useful document <em>free</em> in the sense of freedom: to
1201 assure everyone the effective freedom to copy and redistribute it,
1202 with or without modifying it, either commercially or noncommercially.
1203 Secondarily, this License preserves for the author and publisher a way
1204 to get credit for their work, while not being considered responsible
1205 for modifications made by others.
1206 </p>
1207 <p>This License is a kind of &ldquo;copyleft&rdquo;, which means that derivative
1208 works of the document must themselves be free in the same sense.  It
1209 complements the GNU General Public License, which is a copyleft
1210 license designed for free software.
1211 </p>
1212 <p>We have designed this License in order to use it for manuals for free
1213 software, because free software needs free documentation: a free
1214 program should come with manuals providing the same freedoms that the
1215 software does.  But this License is not limited to software manuals;
1216 it can be used for any textual work, regardless of subject matter or
1217 whether it is published as a printed book.  We recommend this License
1218 principally for works whose purpose is instruction or reference.
1219 </p>
1220 </li><li> APPLICABILITY AND DEFINITIONS
1221
1222 <p>This License applies to any manual or other work, in any medium, that
1223 contains a notice placed by the copyright holder saying it can be
1224 distributed under the terms of this License.  Such a notice grants a
1225 world-wide, royalty-free license, unlimited in duration, to use that
1226 work under the conditions stated herein.  The &ldquo;Document&rdquo;, below,
1227 refers to any such manual or work.  Any member of the public is a
1228 licensee, and is addressed as &ldquo;you&rdquo;.  You accept the license if you
1229 copy, modify or distribute the work in a way requiring permission
1230 under copyright law.
1231 </p>
1232 <p>A &ldquo;Modified Version&rdquo; of the Document means any work containing the
1233 Document or a portion of it, either copied verbatim, or with
1234 modifications and/or translated into another language.
1235 </p>
1236 <p>A &ldquo;Secondary Section&rdquo; is a named appendix or a front-matter section
1237 of the Document that deals exclusively with the relationship of the
1238 publishers or authors of the Document to the Document&rsquo;s overall
1239 subject (or to related matters) and contains nothing that could fall
1240 directly within that overall subject.  (Thus, if the Document is in
1241 part a textbook of mathematics, a Secondary Section may not explain
1242 any mathematics.)  The relationship could be a matter of historical
1243 connection with the subject or with related matters, or of legal,
1244 commercial, philosophical, ethical or political position regarding
1245 them.
1246 </p>
1247 <p>The &ldquo;Invariant Sections&rdquo; are certain Secondary Sections whose titles
1248 are designated, as being those of Invariant Sections, in the notice
1249 that says that the Document is released under this License.  If a
1250 section does not fit the above definition of Secondary then it is not
1251 allowed to be designated as Invariant.  The Document may contain zero
1252 Invariant Sections.  If the Document does not identify any Invariant
1253 Sections then there are none.
1254 </p>
1255 <p>The &ldquo;Cover Texts&rdquo; are certain short passages of text that are listed,
1256 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
1257 the Document is released under this License.  A Front-Cover Text may
1258 be at most 5 words, and a Back-Cover Text may be at most 25 words.
1259 </p>
1260 <p>A &ldquo;Transparent&rdquo; copy of the Document means a machine-readable copy,
1261 represented in a format whose specification is available to the
1262 general public, that is suitable for revising the document
1263 straightforwardly with generic text editors or (for images composed of
1264 pixels) generic paint programs or (for drawings) some widely available
1265 drawing editor, and that is suitable for input to text formatters or
1266 for automatic translation to a variety of formats suitable for input
1267 to text formatters.  A copy made in an otherwise Transparent file
1268 format whose markup, or absence of markup, has been arranged to thwart
1269 or discourage subsequent modification by readers is not Transparent.
1270 An image format is not Transparent if used for any substantial amount
1271 of text.  A copy that is not &ldquo;Transparent&rdquo; is called &ldquo;Opaque&rdquo;.
1272 </p>
1273 <p>Examples of suitable formats for Transparent copies include plain
1274 ASCII without markup, Texinfo input format, LaTeX input
1275 format, SGML or XML using a publicly available
1276 DTD, and standard-conforming simple HTML,
1277 PostScript or PDF designed for human modification.  Examples
1278 of transparent image formats include PNG, XCF and
1279 JPG.  Opaque formats include proprietary formats that can be
1280 read and edited only by proprietary word processors, SGML or
1281 XML for which the DTD and/or processing tools are
1282 not generally available, and the machine-generated HTML,
1283 PostScript or PDF produced by some word processors for
1284 output purposes only.
1285 </p>
1286 <p>The &ldquo;Title Page&rdquo; means, for a printed book, the title page itself,
1287 plus such following pages as are needed to hold, legibly, the material
1288 this License requires to appear in the title page.  For works in
1289 formats which do not have any title page as such, &ldquo;Title Page&rdquo; means
1290 the text near the most prominent appearance of the work&rsquo;s title,
1291 preceding the beginning of the body of the text.
1292 </p>
1293 <p>The &ldquo;publisher&rdquo; means any person or entity that distributes copies
1294 of the Document to the public.
1295 </p>
1296 <p>A section &ldquo;Entitled XYZ&rdquo; means a named subunit of the Document whose
1297 title either is precisely XYZ or contains XYZ in parentheses following
1298 text that translates XYZ in another language.  (Here XYZ stands for a
1299 specific section name mentioned below, such as &ldquo;Acknowledgements&rdquo;,
1300 &ldquo;Dedications&rdquo;, &ldquo;Endorsements&rdquo;, or &ldquo;History&rdquo;.)  To &ldquo;Preserve the Title&rdquo;
1301 of such a section when you modify the Document means that it remains a
1302 section &ldquo;Entitled XYZ&rdquo; according to this definition.
1303 </p>
1304 <p>The Document may include Warranty Disclaimers next to the notice which
1305 states that this License applies to the Document.  These Warranty
1306 Disclaimers are considered to be included by reference in this
1307 License, but only as regards disclaiming warranties: any other
1308 implication that these Warranty Disclaimers may have is void and has
1309 no effect on the meaning of this License.
1310 </p>
1311 </li><li> VERBATIM COPYING
1312
1313 <p>You may copy and distribute the Document in any medium, either
1314 commercially or noncommercially, provided that this License, the
1315 copyright notices, and the license notice saying this License applies
1316 to the Document are reproduced in all copies, and that you add no other
1317 conditions whatsoever to those of this License.  You may not use
1318 technical measures to obstruct or control the reading or further
1319 copying of the copies you make or distribute.  However, you may accept
1320 compensation in exchange for copies.  If you distribute a large enough
1321 number of copies you must also follow the conditions in section 3.
1322 </p>
1323 <p>You may also lend copies, under the same conditions stated above, and
1324 you may publicly display copies.
1325 </p>
1326 </li><li> COPYING IN QUANTITY
1327
1328 <p>If you publish printed copies (or copies in media that commonly have
1329 printed covers) of the Document, numbering more than 100, and the
1330 Document&rsquo;s license notice requires Cover Texts, you must enclose the
1331 copies in covers that carry, clearly and legibly, all these Cover
1332 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
1333 the back cover.  Both covers must also clearly and legibly identify
1334 you as the publisher of these copies.  The front cover must present
1335 the full title with all words of the title equally prominent and
1336 visible.  You may add other material on the covers in addition.
1337 Copying with changes limited to the covers, as long as they preserve
1338 the title of the Document and satisfy these conditions, can be treated
1339 as verbatim copying in other respects.
1340 </p>
1341 <p>If the required texts for either cover are too voluminous to fit
1342 legibly, you should put the first ones listed (as many as fit
1343 reasonably) on the actual cover, and continue the rest onto adjacent
1344 pages.
1345 </p>
1346 <p>If you publish or distribute Opaque copies of the Document numbering
1347 more than 100, you must either include a machine-readable Transparent
1348 copy along with each Opaque copy, or state in or with each Opaque copy
1349 a computer-network location from which the general network-using
1350 public has access to download using public-standard network protocols
1351 a complete Transparent copy of the Document, free of added material.
1352 If you use the latter option, you must take reasonably prudent steps,
1353 when you begin distribution of Opaque copies in quantity, to ensure
1354 that this Transparent copy will remain thus accessible at the stated
1355 location until at least one year after the last time you distribute an
1356 Opaque copy (directly or through your agents or retailers) of that
1357 edition to the public.
1358 </p>
1359 <p>It is requested, but not required, that you contact the authors of the
1360 Document well before redistributing any large number of copies, to give
1361 them a chance to provide you with an updated version of the Document.
1362 </p>
1363 </li><li> MODIFICATIONS
1364
1365 <p>You may copy and distribute a Modified Version of the Document under
1366 the conditions of sections 2 and 3 above, provided that you release
1367 the Modified Version under precisely this License, with the Modified
1368 Version filling the role of the Document, thus licensing distribution
1369 and modification of the Modified Version to whoever possesses a copy
1370 of it.  In addition, you must do these things in the Modified Version:
1371 </p>
1372 <ol type="A" start="1">
1373 <li> Use in the Title Page (and on the covers, if any) a title distinct
1374 from that of the Document, and from those of previous versions
1375 (which should, if there were any, be listed in the History section
1376 of the Document).  You may use the same title as a previous version
1377 if the original publisher of that version gives permission.
1378
1379 </li><li> List on the Title Page, as authors, one or more persons or entities
1380 responsible for authorship of the modifications in the Modified
1381 Version, together with at least five of the principal authors of the
1382 Document (all of its principal authors, if it has fewer than five),
1383 unless they release you from this requirement.
1384
1385 </li><li> State on the Title page the name of the publisher of the
1386 Modified Version, as the publisher.
1387
1388 </li><li> Preserve all the copyright notices of the Document.
1389
1390 </li><li> Add an appropriate copyright notice for your modifications
1391 adjacent to the other copyright notices.
1392
1393 </li><li> Include, immediately after the copyright notices, a license notice
1394 giving the public permission to use the Modified Version under the
1395 terms of this License, in the form shown in the Addendum below.
1396
1397 </li><li> Preserve in that license notice the full lists of Invariant Sections
1398 and required Cover Texts given in the Document&rsquo;s license notice.
1399
1400 </li><li> Include an unaltered copy of this License.
1401
1402 </li><li> Preserve the section Entitled &ldquo;History&rdquo;, Preserve its Title, and add
1403 to it an item stating at least the title, year, new authors, and
1404 publisher of the Modified Version as given on the Title Page.  If
1405 there is no section Entitled &ldquo;History&rdquo; in the Document, create one
1406 stating the title, year, authors, and publisher of the Document as
1407 given on its Title Page, then add an item describing the Modified
1408 Version as stated in the previous sentence.
1409
1410 </li><li> Preserve the network location, if any, given in the Document for
1411 public access to a Transparent copy of the Document, and likewise
1412 the network locations given in the Document for previous versions
1413 it was based on.  These may be placed in the &ldquo;History&rdquo; section.
1414 You may omit a network location for a work that was published at
1415 least four years before the Document itself, or if the original
1416 publisher of the version it refers to gives permission.
1417
1418 </li><li> For any section Entitled &ldquo;Acknowledgements&rdquo; or &ldquo;Dedications&rdquo;, Preserve
1419 the Title of the section, and preserve in the section all the
1420 substance and tone of each of the contributor acknowledgements and/or
1421 dedications given therein.
1422
1423 </li><li> Preserve all the Invariant Sections of the Document,
1424 unaltered in their text and in their titles.  Section numbers
1425 or the equivalent are not considered part of the section titles.
1426
1427 </li><li> Delete any section Entitled &ldquo;Endorsements&rdquo;.  Such a section
1428 may not be included in the Modified Version.
1429
1430 </li><li> Do not retitle any existing section to be Entitled &ldquo;Endorsements&rdquo; or
1431 to conflict in title with any Invariant Section.
1432
1433 </li><li> Preserve any Warranty Disclaimers.
1434 </li></ol>
1435
1436 <p>If the Modified Version includes new front-matter sections or
1437 appendices that qualify as Secondary Sections and contain no material
1438 copied from the Document, you may at your option designate some or all
1439 of these sections as invariant.  To do this, add their titles to the
1440 list of Invariant Sections in the Modified Version&rsquo;s license notice.
1441 These titles must be distinct from any other section titles.
1442 </p>
1443 <p>You may add a section Entitled &ldquo;Endorsements&rdquo;, provided it contains
1444 nothing but endorsements of your Modified Version by various
1445 parties&mdash;for example, statements of peer review or that the text has
1446 been approved by an organization as the authoritative definition of a
1447 standard.
1448 </p>
1449 <p>You may add a passage of up to five words as a Front-Cover Text, and a
1450 passage of up to 25 words as a Back-Cover Text, to the end of the list
1451 of Cover Texts in the Modified Version.  Only one passage of
1452 Front-Cover Text and one of Back-Cover Text may be added by (or
1453 through arrangements made by) any one entity.  If the Document already
1454 includes a cover text for the same cover, previously added by you or
1455 by arrangement made by the same entity you are acting on behalf of,
1456 you may not add another; but you may replace the old one, on explicit
1457 permission from the previous publisher that added the old one.
1458 </p>
1459 <p>The author(s) and publisher(s) of the Document do not by this License
1460 give permission to use their names for publicity for or to assert or
1461 imply endorsement of any Modified Version.
1462 </p>
1463 </li><li> COMBINING DOCUMENTS
1464
1465 <p>You may combine the Document with other documents released under this
1466 License, under the terms defined in section 4 above for modified
1467 versions, provided that you include in the combination all of the
1468 Invariant Sections of all of the original documents, unmodified, and
1469 list them all as Invariant Sections of your combined work in its
1470 license notice, and that you preserve all their Warranty Disclaimers.
1471 </p>
1472 <p>The combined work need only contain one copy of this License, and
1473 multiple identical Invariant Sections may be replaced with a single
1474 copy.  If there are multiple Invariant Sections with the same name but
1475 different contents, make the title of each such section unique by
1476 adding at the end of it, in parentheses, the name of the original
1477 author or publisher of that section if known, or else a unique number.
1478 Make the same adjustment to the section titles in the list of
1479 Invariant Sections in the license notice of the combined work.
1480 </p>
1481 <p>In the combination, you must combine any sections Entitled &ldquo;History&rdquo;
1482 in the various original documents, forming one section Entitled
1483 &ldquo;History&rdquo;; likewise combine any sections Entitled &ldquo;Acknowledgements&rdquo;,
1484 and any sections Entitled &ldquo;Dedications&rdquo;.  You must delete all
1485 sections Entitled &ldquo;Endorsements.&rdquo;
1486 </p>
1487 </li><li> COLLECTIONS OF DOCUMENTS
1488
1489 <p>You may make a collection consisting of the Document and other documents
1490 released under this License, and replace the individual copies of this
1491 License in the various documents with a single copy that is included in
1492 the collection, provided that you follow the rules of this License for
1493 verbatim copying of each of the documents in all other respects.
1494 </p>
1495 <p>You may extract a single document from such a collection, and distribute
1496 it individually under this License, provided you insert a copy of this
1497 License into the extracted document, and follow this License in all
1498 other respects regarding verbatim copying of that document.
1499 </p>
1500 </li><li> AGGREGATION WITH INDEPENDENT WORKS
1501
1502 <p>A compilation of the Document or its derivatives with other separate
1503 and independent documents or works, in or on a volume of a storage or
1504 distribution medium, is called an &ldquo;aggregate&rdquo; if the copyright
1505 resulting from the compilation is not used to limit the legal rights
1506 of the compilation&rsquo;s users beyond what the individual works permit.
1507 When the Document is included in an aggregate, this License does not
1508 apply to the other works in the aggregate which are not themselves
1509 derivative works of the Document.
1510 </p>
1511 <p>If the Cover Text requirement of section 3 is applicable to these
1512 copies of the Document, then if the Document is less than one half of
1513 the entire aggregate, the Document&rsquo;s Cover Texts may be placed on
1514 covers that bracket the Document within the aggregate, or the
1515 electronic equivalent of covers if the Document is in electronic form.
1516 Otherwise they must appear on printed covers that bracket the whole
1517 aggregate.
1518 </p>
1519 </li><li> TRANSLATION
1520
1521 <p>Translation is considered a kind of modification, so you may
1522 distribute translations of the Document under the terms of section 4.
1523 Replacing Invariant Sections with translations requires special
1524 permission from their copyright holders, but you may include
1525 translations of some or all Invariant Sections in addition to the
1526 original versions of these Invariant Sections.  You may include a
1527 translation of this License, and all the license notices in the
1528 Document, and any Warranty Disclaimers, provided that you also include
1529 the original English version of this License and the original versions
1530 of those notices and disclaimers.  In case of a disagreement between
1531 the translation and the original version of this License or a notice
1532 or disclaimer, the original version will prevail.
1533 </p>
1534 <p>If a section in the Document is Entitled &ldquo;Acknowledgements&rdquo;,
1535 &ldquo;Dedications&rdquo;, or &ldquo;History&rdquo;, the requirement (section 4) to Preserve
1536 its Title (section 1) will typically require changing the actual
1537 title.
1538 </p>
1539 </li><li> TERMINATION
1540
1541 <p>You may not copy, modify, sublicense, or distribute the Document
1542 except as expressly provided under this License.  Any attempt
1543 otherwise to copy, modify, sublicense, or distribute it is void, and
1544 will automatically terminate your rights under this License.
1545 </p>
1546 <p>However, if you cease all violation of this License, then your license
1547 from a particular copyright holder is reinstated (a) provisionally,
1548 unless and until the copyright holder explicitly and finally
1549 terminates your license, and (b) permanently, if the copyright holder
1550 fails to notify you of the violation by some reasonable means prior to
1551 60 days after the cessation.
1552 </p>
1553 <p>Moreover, your license from a particular copyright holder is
1554 reinstated permanently if the copyright holder notifies you of the
1555 violation by some reasonable means, this is the first time you have
1556 received notice of violation of this License (for any work) from that
1557 copyright holder, and you cure the violation prior to 30 days after
1558 your receipt of the notice.
1559 </p>
1560 <p>Termination of your rights under this section does not terminate the
1561 licenses of parties who have received copies or rights from you under
1562 this License.  If your rights have been terminated and not permanently
1563 reinstated, receipt of a copy of some or all of the same material does
1564 not give you any rights to use it.
1565 </p>
1566 </li><li> FUTURE REVISIONS OF THIS LICENSE
1567
1568 <p>The Free Software Foundation may publish new, revised versions
1569 of the GNU Free Documentation License from time to time.  Such new
1570 versions will be similar in spirit to the present version, but may
1571 differ in detail to address new problems or concerns.  See
1572 <a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>.
1573 </p>
1574 <p>Each version of the License is given a distinguishing version number.
1575 If the Document specifies that a particular numbered version of this
1576 License &ldquo;or any later version&rdquo; applies to it, you have the option of
1577 following the terms and conditions either of that specified version or
1578 of any later version that has been published (not as a draft) by the
1579 Free Software Foundation.  If the Document does not specify a version
1580 number of this License, you may choose any version ever published (not
1581 as a draft) by the Free Software Foundation.  If the Document
1582 specifies that a proxy can decide which future versions of this
1583 License can be used, that proxy&rsquo;s public statement of acceptance of a
1584 version permanently authorizes you to choose that version for the
1585 Document.
1586 </p>
1587 </li><li> RELICENSING
1588
1589 <p>&ldquo;Massive Multiauthor Collaboration Site&rdquo; (or &ldquo;MMC Site&rdquo;) means any
1590 World Wide Web server that publishes copyrightable works and also
1591 provides prominent facilities for anybody to edit those works.  A
1592 public wiki that anybody can edit is an example of such a server.  A
1593 &ldquo;Massive Multiauthor Collaboration&rdquo; (or &ldquo;MMC&rdquo;) contained in the
1594 site means any set of copyrightable works thus published on the MMC
1595 site.
1596 </p>
1597 <p>&ldquo;CC-BY-SA&rdquo; means the Creative Commons Attribution-Share Alike 3.0
1598 license published by Creative Commons Corporation, a not-for-profit
1599 corporation with a principal place of business in San Francisco,
1600 California, as well as future copyleft versions of that license
1601 published by that same organization.
1602 </p>
1603 <p>&ldquo;Incorporate&rdquo; means to publish or republish a Document, in whole or
1604 in part, as part of another Document.
1605 </p>
1606 <p>An MMC is &ldquo;eligible for relicensing&rdquo; if it is licensed under this
1607 License, and if all works that were first published under this License
1608 somewhere other than this MMC, and subsequently incorporated in whole
1609 or in part into the MMC, (1) had no cover texts or invariant sections,
1610 and (2) were thus incorporated prior to November 1, 2008.
1611 </p>
1612 <p>The operator of an MMC Site may republish an MMC contained in the site
1613 under CC-BY-SA on the same site at any time before August 1, 2009,
1614 provided the MMC is eligible for relicensing.
1615 </p>
1616 </li></ol>
1617
1618 <span id="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></span><h3 class="heading">ADDENDUM: How to use this License for your documents</h3>
1619
1620 <p>To use this License in a document you have written, include a copy of
1621 the License in the document and put the following copyright and
1622 license notices just after the title page:
1623 </p>
1624 <div class="example">
1625 <pre class="example">  Copyright (C)  <var>year</var>  <var>your name</var>.
1626   Permission is granted to copy, distribute and/or modify this document
1627   under the terms of the GNU Free Documentation License, Version 1.3
1628   or any later version published by the Free Software Foundation;
1629   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
1630   Texts.  A copy of the license is included in the section entitled ``GNU
1631   Free Documentation License''.
1632 </pre></div>
1633
1634 <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
1635 replace the &ldquo;with&hellip;Texts.&rdquo; line with this:
1636 </p>
1637 <div class="example">
1638 <pre class="example">    with the Invariant Sections being <var>list their titles</var>, with
1639     the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts
1640     being <var>list</var>.
1641 </pre></div>
1642
1643 <p>If you have Invariant Sections without Cover Texts, or some other
1644 combination of the three, merge those two alternatives to suit the
1645 situation.
1646 </p>
1647 <p>If your document contains nontrivial examples of program code, we
1648 recommend releasing these examples in parallel under your choice of
1649 free software license, such as the GNU General Public License,
1650 to permit their use in free software.
1651 </p>
1652
1653
1654 <hr>
1655 <span id="Index"></span><div class="header">
1656 <p>
1657 Previous: <a href="#License" accesskey="p" rel="prev">License</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1658 </div>
1659 <span id="Index-1"></span><h2 class="unnumbered">Index</h2>
1660
1661 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a>
1662  &nbsp;
1663 <a class="summary-letter" href="#Index_cp_letter-E"><b>E</b></a>
1664  &nbsp;
1665 <a class="summary-letter" href="#Index_cp_letter-H"><b>H</b></a>
1666  &nbsp;
1667 <a class="summary-letter" href="#Index_cp_letter-I"><b>I</b></a>
1668  &nbsp;
1669 <a class="summary-letter" href="#Index_cp_letter-M"><b>M</b></a>
1670  &nbsp;
1671 <a class="summary-letter" href="#Index_cp_letter-P"><b>P</b></a>
1672  &nbsp;
1673 <a class="summary-letter" href="#Index_cp_letter-R"><b>R</b></a>
1674  &nbsp;
1675 <a class="summary-letter" href="#Index_cp_letter-S"><b>S</b></a>
1676  &nbsp;
1677 <a class="summary-letter" href="#Index_cp_letter-T"><b>T</b></a>
1678  &nbsp;
1679 <a class="summary-letter" href="#Index_cp_letter-V"><b>V</b></a>
1680  &nbsp;
1681 </td></tr></table>
1682 <table class="index-cp" border="0">
1683 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
1684 <tr><td colspan="4"> <hr></td></tr>
1685 <tr><th id="Index_cp_letter-C">C</th><td></td><td></td></tr>
1686 <tr><td></td><td valign="top"><a href="#index-configuration-file">configuration file</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-qirc-file">The qirc file</a></td></tr>
1687 <tr><td colspan="4"> <hr></td></tr>
1688 <tr><th id="Index_cp_letter-E">E</th><td></td><td></td></tr>
1689 <tr><td></td><td valign="top"><a href="#index-environment-variables">environment variables</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1690 <tr><td></td><td valign="top"><a href="#index-exit-codes">exit codes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exit-status">Exit status</a></td></tr>
1691 <tr><td colspan="4"> <hr></td></tr>
1692 <tr><th id="Index_cp_letter-H">H</th><td></td><td></td></tr>
1693 <tr><td></td><td valign="top"><a href="#index-handling-build-order">handling build order</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Order-files">Order files</a></td></tr>
1694 <tr><td colspan="4"> <hr></td></tr>
1695 <tr><th id="Index_cp_letter-I">I</th><td></td><td></td></tr>
1696 <tr><td></td><td valign="top"><a href="#index-introduction">introduction</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Introduction">Introduction</a></td></tr>
1697 <tr><td></td><td valign="top"><a href="#index-invocation">invocation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-qi">Invoking qi</a></td></tr>
1698 <tr><td colspan="4"> <hr></td></tr>
1699 <tr><th id="Index_cp_letter-M">M</th><td></td><td></td></tr>
1700 <tr><td></td><td valign="top"><a href="#index-managing-packages">managing packages</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1701 <tr><td colspan="4"> <hr></td></tr>
1702 <tr><th id="Index_cp_letter-P">P</th><td></td><td></td></tr>
1703 <tr><td></td><td valign="top"><a href="#index-package-blacklist">package blacklist</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1704 <tr><td></td><td valign="top"><a href="#index-package-build">package build</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1705 <tr><td></td><td valign="top"><a href="#index-package-conflicts">package conflicts</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1706 <tr><td></td><td valign="top"><a href="#index-package-de_002dinstallation">package de-installation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1707 <tr><td></td><td valign="top"><a href="#index-package-examination">package examination</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Examining-packages">Examining packages</a></td></tr>
1708 <tr><td></td><td valign="top"><a href="#index-package-installation">package installation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1709 <tr><td></td><td valign="top"><a href="#index-package-upgrade">package upgrade</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Packages">Packages</a></td></tr>
1710 <tr><td colspan="4"> <hr></td></tr>
1711 <tr><th id="Index_cp_letter-R">R</th><td></td><td></td></tr>
1712 <tr><td></td><td valign="top"><a href="#index-recipes">recipes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1713 <tr><td colspan="4"> <hr></td></tr>
1714 <tr><th id="Index_cp_letter-S">S</th><td></td><td></td></tr>
1715 <tr><td></td><td valign="top"><a href="#index-special-variables">special variables</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1716 <tr><td colspan="4"> <hr></td></tr>
1717 <tr><th id="Index_cp_letter-T">T</th><td></td><td></td></tr>
1718 <tr><td></td><td valign="top"><a href="#index-the-meta-file">the meta file</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1719 <tr><td colspan="4"> <hr></td></tr>
1720 <tr><th id="Index_cp_letter-V">V</th><td></td><td></td></tr>
1721 <tr><td></td><td valign="top"><a href="#index-variables">variables</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1722 <tr><td colspan="4"> <hr></td></tr>
1723 </table>
1724 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a>
1725  &nbsp;
1726 <a class="summary-letter" href="#Index_cp_letter-E"><b>E</b></a>
1727  &nbsp;
1728 <a class="summary-letter" href="#Index_cp_letter-H"><b>H</b></a>
1729  &nbsp;
1730 <a class="summary-letter" href="#Index_cp_letter-I"><b>I</b></a>
1731  &nbsp;
1732 <a class="summary-letter" href="#Index_cp_letter-M"><b>M</b></a>
1733  &nbsp;
1734 <a class="summary-letter" href="#Index_cp_letter-P"><b>P</b></a>
1735  &nbsp;
1736 <a class="summary-letter" href="#Index_cp_letter-R"><b>R</b></a>
1737  &nbsp;
1738 <a class="summary-letter" href="#Index_cp_letter-S"><b>S</b></a>
1739  &nbsp;
1740 <a class="summary-letter" href="#Index_cp_letter-T"><b>T</b></a>
1741  &nbsp;
1742 <a class="summary-letter" href="#Index_cp_letter-V"><b>V</b></a>
1743  &nbsp;
1744 </td></tr></table>
1745
1746 <div class="footnote">
1747 <hr>
1748 <h4 class="footnotes-heading">Footnotes</h4>
1749
1750 <h3><a id="FOOT1" href="#DOCF1">(1)</a></h3>
1751 <p>The official guide for Graft can be found at
1752 <a href="http://peters.gormand.com.au/Home/tools/graft/graft.html">http://peters.gormand.com.au/Home/tools/graft/graft.html</a>.</p>
1753 <h3><a id="FOOT2" href="#DOCF2">(2)</a></h3>
1754 <p>The proposal for &lsquo;<samp>license</samp>&rsquo; was made by Richard M. Stallman at
1755 <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>
1756 </div>
1757 <hr>
1758
1759
1760
1761 </body>
1762 </html>