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