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