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,
   4 09 May 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.1, http://www.gnu.org/software/texinfo/ -->
  16 <head>
  17 <title>Qi user guide</title>
  18
  19 <meta name="description" content="Qi user guide">
  20 <meta name="keywords" content="Qi user guide">
  21 <meta name="resource-type" content="document">
  22 <meta name="distribution" content="global">
  23 <meta name="Generator" content="makeinfo">
  24 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  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 blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
  34 blockquote.smallquotation {font-size: smaller}
  35 div.display {margin-left: 3.2em}
  36 div.example {margin-left: 3.2em}
  37 div.lisp {margin-left: 3.2em}
  38 div.smalldisplay {margin-left: 3.2em}
  39 div.smallexample {margin-left: 3.2em}
  40 div.smalllisp {margin-left: 3.2em}
  41 kbd {font-style: oblique}
  42 pre.display {font-family: inherit}
  43 pre.format {font-family: inherit}
  44 pre.menu-comment {font-family: serif}
  45 pre.menu-preformatted {font-family: serif}
  46 pre.smalldisplay {font-family: inherit; font-size: smaller}
  47 pre.smallexample {font-size: smaller}
  48 pre.smallformat {font-family: inherit; font-size: smaller}
  49 pre.smalllisp {font-size: smaller}
  50 span.nolinebreak {white-space: nowrap}
  51 span.roman {font-family: initial; font-weight: normal}
  52 span.sansserif {font-family: sans-serif; font-weight: normal}
  53 ul.no-bullet {list-style: none}
  54 -->
  55 </style>
  56
  57
  58 </head>
  59
  60 <body lang="en">
  61 <h1 class="settitle" align="center">Qi user guide</h1>
  62
  63
  64
  65
  66
  67 <a name="SEC_Contents"></a>
  68 <h2 class="contents-heading">Table of Contents</h2>
  69
  70 <div class="contents">
  71
  72 <ul class="no-bullet">
  73   <li><a name="toc-Introduction-1" href="#Introduction">1 Introduction</a></li>
  74   <li><a name="toc-Invoking-qi-1" href="#Invoking-qi">2 Invoking qi</a></li>
  75   <li><a name="toc-The-qirc-file-1" href="#The-qirc-file">3 The qirc file</a></li>
  76   <li><a name="toc-Packages-1" href="#Packages">4 Packages</a>
  77   <ul class="no-bullet">
  78     <li><a name="toc-Package-conflicts" href="#Package-conflicts">4.1 Package conflicts</a></li>
  79     <li><a name="toc-Installing-packages" href="#Installing-packages">4.2 Installing packages</a></li>
  80     <li><a name="toc-Removing-packages" href="#Removing-packages">4.3 Removing packages</a></li>
  81     <li><a name="toc-Upgrading-packages" href="#Upgrading-packages">4.4 Upgrading packages</a>
  82     <ul class="no-bullet">
  83       <li><a name="toc-Package-blacklist" href="#Package-blacklist">4.4.1 Package blacklist</a></li>
  84     </ul></li>
  85   </ul></li>
  86   <li><a name="toc-Recipes-1" href="#Recipes">5 Recipes</a>
  87   <ul class="no-bullet">
  88     <li><a name="toc-Variables" href="#Variables">5.1 Variables</a></li>
  89     <li><a name="toc-Special-variables" href="#Special-variables">5.2 Special variables</a></li>
  90     <li><a name="toc-Writing-recipes" href="#Writing-recipes">5.3 Writing recipes</a></li>
  91     <li><a name="toc-Building-packages" href="#Building-packages">5.4 Building packages</a></li>
  92     <li><a name="toc-Variables-from-the-environment" href="#Variables-from-the-environment">5.5 Variables from the environment</a></li>
  93     <li><a name="toc-The-meta-file" href="#The-meta-file">5.6 The meta file</a></li>
  94   </ul></li>
  95   <li><a name="toc-Order-files-1" href="#Order-files">6 Order files</a></li>
  96   <li><a name="toc-Creating-packages-1" href="#Creating-packages">7 Creating packages</a></li>
  97   <li><a name="toc-Examining-packages-1" href="#Examining-packages">8 Examining packages</a></li>
  98   <li><a name="toc-Exit-status-1" href="#Exit-status">9 Exit status</a></li>
  99   <li><a name="toc-Index-1" href="#Index">Index</a></li>
 100 </ul>
 101 </div>
 102
 103
 104 <a name="Top"></a>
 105 <div class="header">
 106 <p>
 107 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>
 108 </div>
 109 <a name="SEC_Top"></a>
 110
 111 <p>This user guide is for Qi (version 1.0,
 112 09 May 2019).
 113 </p>
 114 <table class="menu" border="0" cellspacing="0">
 115 <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
 116 </td></tr>
 117 <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
 118 </td></tr>
 119 <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
 120 </td></tr>
 121 <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
 122 </td></tr>
 123 <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
 124 </td></tr>
 125 <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
 126 </td></tr>
 127 <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
 128 </td></tr>
 129 <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
 130 </td></tr>
 131 <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
 132 </td></tr>
 133 <tr><td align="left" valign="top">&bull; <a href="#Index">Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 134 </td></tr>
 135 </table>
 136
 137 <br>
 138 <p>Copyright (C) 2019 Matias Fonzo.
 139 </p>
 140 <p>Qi&rsquo;s home page can be found at <a href="http://www.dragora.org">http://www.dragora.org</a>.
 141 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 -->
 142 </p>
 143 <hr>
 144 <a name="Introduction"></a>
 145 <div class="header">
 146 <p>
 147 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>
 148 </div>
 149 <a name="Introduction-1"></a>
 150 <h2 class="chapter">1 Introduction</h2>
 151 <a name="index-introduction"></a>
 152
 153 <p>Qi is a simple but well-integrated package manager.  It can create,
 154 install, remove, and upgrade software packages.  Qi produces binary
 155 packages using recipes, which are files containing specific instructions
 156 to build each package from source.  Qi can manage multiple packages
 157 under a single directory hierarchy.  This method allows to maintain a set
 158 of packages and multiple versions of them.  This means that Qi could be
 159 used as the main package manager or complement the existing one.
 160 </p>
 161 <p>Qi offers a friendly command line interface, a global configuration
 162 file, a simple recipe layout to deploy software packages; also works
 163 with binary packages in parallel, speeding up installations and packages
 164 in production.  The format used for packages is a simplified but safe
 165 POSIX pax archive compressed with lzip.
 166 </p>
 167 <p>Qi is a modern (POSIX-compliant) shell script released under the
 168 terms of the GNU General Public License.  There are only two major
 169 dependencies for the magic: graft(1) and tarlz(1), the rest is expected
 170 to be found in any Unix-like system.
 171 </p>
 172 <hr>
 173 <a name="Invoking-qi"></a>
 174 <div class="header">
 175 <p>
 176 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>
 177 </div>
 178 <a name="Invoking-qi-1"></a>
 179 <h2 class="chapter">2 Invoking qi</h2>
 180 <a name="index-invocation"></a>
 181
 182 <p>This chapter describes the synopsis and command line options for
 183 invoke Qi.
 184 </p>
 185 <div class="example">
 186 <pre class="example">Usage: qi [<var>OPTION</var>]... [<var>FILE</var>]...
 187 </pre></div>
 188
 189 <p>One mandatory option specifies the operation that &lsquo;<samp>qi</samp>&rsquo; should
 190 perform, other options are meant to detail how this operation should be
 191 performed.
 192 </p>
 193 <p>qi supports the following options to operate:
 194 </p>
 195 <dl compact="compact">
 196 <dt><code>-b</code></dt>
 197 <dd><p>Build package using recipe names.
 198 </p>
 199 </dd>
 200 <dt><code>-c</code></dt>
 201 <dd><p>Create .tlz package from directory.
 202 </p>
 203 </dd>
 204 <dt><code>-d</code></dt>
 205 <dd><p>Delete packages.
 206 </p>
 207 </dd>
 208 <dt><code>-i</code></dt>
 209 <dd><p>Install packages.
 210 </p>
 211 </dd>
 212 <dt><code>-o</code></dt>
 213 <dd><p>Resolve build order through .order files.
 214 </p>
 215 </dd>
 216 <dt><code>-u</code></dt>
 217 <dd><p>Update packages (implies -i, -d and -p options).
 218 </p>
 219 </dd>
 220 <dt><code>-w</code></dt>
 221 <dd><p>Warn about files that will be linked.
 222 </p>
 223 </dd>
 224 <dt><code>-x</code></dt>
 225 <dd><p>Extract a package for debugging purposes.
 226 </p></dd>
 227 </dl>
 228
 229 <p>There are common options between modes:
 230 </p>
 231 <dl compact="compact">
 232 <dt><code>-N</code></dt>
 233 <dd><p>Do not read the configuration file.
 234 </p>
 235 <p>This will ignore any value in the qirc file.
 236 </p>
 237 </dd>
 238 <dt><code>-P &lt;DIR&gt;</code></dt>
 239 <dd><p>Package directory for installations.
 240 </p>
 241 <p>This option sets &lsquo;<samp>${packagedir}</samp>&rsquo;.
 242 </p>
 243 <p>Only valid for -i, -d, or -u options.
 244 </p>
 245 </dd>
 246 <dt><code>-f</code></dt>
 247 <dd><p>Force option.
 248 </p>
 249 <p>This option can force the build of a recipe, or force the update of a
 250 pre-existing package.
 251 </p>
 252 <p>Only valid for -b, -u options.
 253 </p>
 254 </dd>
 255 <dt><code>-t &lt;DIR&gt;</code></dt>
 256 <dd><p>Target directory for symbolic links.
 257 </p>
 258 <p>This option sets &lsquo;<samp>${targetdir}</samp>&rsquo;.
 259 </p>
 260 <p>Only valid for -i, -d, or -u options.
 261 </p>
 262 </dd>
 263 <dt><code>-k</code></dt>
 264 <dd><p>Keep (don&rsquo;t delete) &lsquo;<samp>${srcdir}</samp>&rsquo; or &lsquo;<samp>${destdir}</samp>&rsquo; in build
 265 mode, keep (don&rsquo;t delete) package directory in delete mode.
 266 </p>
 267 <p>Only valid for -b, -d or -u options.
 268 </p>
 269 </dd>
 270 <dt><code>-p</code></dt>
 271 <dd><p>Prune conflicts on package installations.
 272 </p>
 273 <p>This option may proceed with the package installation if one or more
 274 conflicts occur.
 275 </p>
 276 </dd>
 277 <dt><code>-r /rootdir</code></dt>
 278 <dd><p>Use the fully qualified named directory as the root directory for all qi
 279 operations.  The target directory and package directory will be relative
 280 to the specified directory, including the log file for graft.
 281 </p>
 282 </dd>
 283 <dt><code>-v</code></dt>
 284 <dd><p>Be verbose (a 2nd -v gives more).
 285 </p></dd>
 286 </dl>
 287
 288 <p>Options for build mode (-b):
 289 </p>
 290 <dl compact="compact">
 291 <dt><code>-O &lt;DIR&gt;</code></dt>
 292 <dd><p>Where the packages produced are written.
 293 </p>
 294 <p>This option sets &lsquo;<samp>${outdir}</samp>&rsquo;.
 295 </p>
 296 </dd>
 297 <dt><code>-W &lt;DIR&gt;</code></dt>
 298 <dd><p>Where archives, patches, and recipes are expected.
 299 </p>
 300 <p>This option sets &lsquo;<samp>${worktree}</samp>&rsquo;.
 301 </p>
 302 </dd>
 303 <dt><code>-Z &lt;DIR&gt;</code></dt>
 304 <dd><p>Where (compressed) sources will be found.
 305 </p>
 306 <p>This option sets &lsquo;<samp>${tardir}</samp>&rsquo;.
 307 </p>
 308 </dd>
 309 <dt><code>-a</code></dt>
 310 <dd><p>Architecture to use.
 311 </p>
 312 <p>Default value is obtained via uname(1) as &lsquo;<samp>uname -m</samp>&rsquo;.
 313 </p>
 314 </dd>
 315 <dt><code>-j</code></dt>
 316 <dd><p>Parallel jobs for the compiler.
 317 </p>
 318 <p>If not specified, default sets to 1.
 319 </p>
 320 </dd>
 321 <dt><code>-1</code></dt>
 322 <dd><p>Increment release number (&lsquo;<samp>${release}</samp>&rsquo; + 1).
 323 </p>
 324 <p>It will be omitted if the -n option is being used.
 325 </p>
 326 </dd>
 327 <dt><code>-n</code></dt>
 328 <dd><p>Don&rsquo;t create a .tlz package.
 329 </p>
 330 </dd>
 331 <dt><code>-S</code></dt>
 332 <dd><p>Selects the option to skip completed recipes.
 333 </p>
 334 <p>This means, in interactive mode, when the dialog
 335 to summarize recipes is shown.
 336 </p></dd>
 337 </dl>
 338
 339 <p>Informative options:
 340 </p>
 341 <dl compact="compact">
 342 <dt><code>-L</code></dt>
 343 <dd><p>Print default directory locations.
 344 </p>
 345 <p>This will print the target directory, package directory, working tree,
 346 the directory for tarballs, and the output directory for the packages
 347 produced.
 348 </p>
 349 </dd>
 350 <dt><code>-h</code></dt>
 351 <dd><p>Display the help describing the options and then exit.
 352 </p>
 353 </dd>
 354 <dt><code>-V</code></dt>
 355 <dd><p>Print the version number and license information.
 356 The version number should be included in all bug reports.
 357 </p></dd>
 358 </dl>
 359
 360 <p>Expected non-option arguments are package directories and regular files:
 361 recipes or files ending in .tlz, .order.  When FILE is -, qi can read from
 362 the standard input.  See examples in <a href="#Packages">Packages</a>.
 363 </p>
 364
 365 <hr>
 366 <a name="The-qirc-file"></a>
 367 <div class="header">
 368 <p>
 369 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>
 370 </div>
 371 <a name="The-qirc-file-1"></a>
 372 <h2 class="chapter">3 The qirc file</h2>
 373 <a name="index-configuration-file"></a>
 374
 375 <p>The global <samp>qirc</samp> file offers a way to define variables and tools
 376 (such as a download manager) for default use.  This file is used by qi
 377 at runtime, e.g., to build, install, remove or upgrade packages.
 378 </p>
 379 <p>It has the following rules:
 380 </p>
 381 <ul>
 382 <li> Variables must be declared as &lsquo;<samp>name=value</samp>&rsquo;.
 383
 384 </li><li> Declaration of values should only take one line, no line break.
 385
 386 </li><li> For security reasons, assignments like &lsquo;<samp>name=$var</samp>&rsquo; are only
 387 interpreted as literal.
 388 </li></ul>
 389
 390 <p>The command line options related to the package directory and target
 391 directory plus some of the options used for the build mode can override
 392 some values in <samp>qirc</samp>.  See <a href="#Invoking-qi">Invoking qi</a>.
 393 </p>
 394 <p>The order in which qi looks for this file is:
 395 </p>
 396 <ol>
 397 <li> <code>${HOME}/.qirc</code>
 398  Effective user.
 399
 400 </li><li> &lsquo;<samp>${sysconfdir}/qirc</samp>&rsquo;
 401  System-wide.
 402 </li></ol>
 403
 404 <p>If you intend to run qi as effective user, the file
 405 &lsquo;<samp>${sysconfdir}/qirc</samp>&rsquo; could be copied to <code>${HOME}/.qirc</code>
 406 setting the paths for &lsquo;<samp>${packagedir}</samp>&rsquo; and &lsquo;<samp>${targetdir}</samp>&rsquo;
 407 according to the <code>$HOME</code>.
 408 </p>
 409
 410 <hr>
 411 <a name="Packages"></a>
 412 <div class="header">
 413 <p>
 414 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>
 415 </div>
 416 <a name="Packages-1"></a>
 417 <h2 class="chapter">4 Packages</h2>
 418 <a name="index-managing-packages"></a>
 419
 420 <p>A package is a suite of programs usually distributed in binary form
 421 which may also contain manual pages, documentation, or any other file
 422 associated to a specific software.
 423 </p>
 424 <p>The package format used by qi is a simplified POSIX pax archive
 425 compressed with lzip.  The file extension for packages is &lsquo;<samp>.tlz</samp>&rsquo;.
 426 </p>
 427 <p>Both package installation and package de-installation are managed using
 428 two important (internal) variables: &lsquo;<samp>${packagedir}</samp>&rsquo; and
 429 &lsquo;<samp>${targetdir}</samp>&rsquo;, these values can be changed in the
 430 configuration file or via options.
 431 </p>
 432 <p>&lsquo;<samp>${packagedir}</samp>&rsquo; is a common directory tree where the package
 433 contents will be decompressed (will reside).
 434 </p>
 435 <p>&lsquo;<samp>${targetdir}</samp>&rsquo; is a target directory where the links will be
 436 made by graft(1) taking &lsquo;<samp>${packagedir}/package_name</samp>&rsquo; into account.
 437 </p>
 438 <p>Packages are installed in self-contained directory trees and symbolic
 439 links from a common area are made to the package files.  This allows
 440 multiple versions of the same package to coexist on the same system.
 441 </p>
 442 <a name="Package-conflicts"></a>
 443 <h3 class="section">4.1 Package conflicts</h3>
 444 <a name="index-package-conflicts"></a>
 445
 446 <p>All the links to install or remove a package are handled by graft(1).
 447 Since multiple packages can be installed or removed at the same time,
 448 certain conflicts may arise between the packages.
 449 </p>
 450 <p>graft<a name="DOCF1" href="#FOOT1"><sup>1</sup></a>
 451 defines a CONFLICT as one of the following conditions:
 452 </p>
 453 <ul>
 454 <li> If the package object is a directory and the target object exists but is
 455 not a directory.
 456
 457 </li><li> If the package object is not a directory and the target object exists
 458 and is not a symbolic link.
 459
 460 </li><li> If the package object is not a directory and the target object exists
 461 and is a symbolic link to something other than the package object.
 462 </li></ul>
 463
 464 <p>The default behavior of qi for an incoming package is to ABORT if a
 465 conflict arises.  When a package is going to be deleted, qi tells to
 466 graft(1) to remove those parts that are not in conflict, leaving the
 467 links to the belonging package.  This behavior can be forced if the
 468 -p option is given.
 469 </p>
 470 <a name="Installing-packages"></a>
 471 <h3 class="section">4.2 Installing packages</h3>
 472 <a name="index-package-installation"></a>
 473
 474 <p>To install a single package, simply type:
 475 </p>
 476 <div class="example">
 477 <pre class="example">qi -i coreutils-8.30-i586+1.tlz
 478 </pre></div>
 479
 480 <p>To install multiple packages at once, type:
 481 </p>
 482 <div class="example">
 483 <pre class="example">qi -i gcc-8.3.0-i586+1.tlz rafaela-2.2-i586+1.tlz ...
 484 </pre></div>
 485
 486 <p>Warn about the files that will be linked:
 487 </p>
 488 <div class="example">
 489 <pre class="example">qi -w bash-5.0-i586+1.tlz
 490 </pre></div>
 491
 492 <p>This is to verify the content of a package before installing it.
 493 </p>
 494 <p>See the process of an installation (very verbose):
 495 </p>
 496 <div class="example">
 497 <pre class="example">qi -i -v mariana-3.0-i586+1.tlz
 498 </pre></div>
 499
 500 <p>A second -v gives more.
 501 </p>
 502 <p>Installing package in a different location:
 503 </p>
 504 <div class="example">
 505 <pre class="example">qi -r /media/floppy -i lzip-1.21-i586+1.tlz
 506 </pre></div>
 507
 508 <p>The -r option assumes &lsquo;<samp>${targetdir}</samp>&rsquo; and &lsquo;<samp>${packagedir}</samp>&rsquo;.
 509 See:
 510 </p>
 511 <div class="example">
 512 <pre class="example">qi -r /home/selk -P /pkgs -t / -i lzip-1.21-i586+1.tlz
 513 </pre></div>
 514
 515 <p>In this case the content of &quot;lzip-1.21-i586+1.tlz&quot; will be decompressed
 516 into &lsquo;<samp>/home/selk/pkgs/lzip-1.21-i586+1</samp>&rsquo;.  Assuming that the main
 517 binary for lzip is under &lsquo;<samp>/home/selk/pkgs/lzip-1.21-i586+1/usr/bin/</samp>&rsquo;
 518 the target for &quot;usr/bin&quot; will be created at &lsquo;<samp>/home/selk</samp>&rsquo;.  Considering
 519 that you have exported the <code>PATH</code> as &lsquo;<samp>${HOME}/usr/bin</samp>&rsquo;, now the
 520 system is able to see the recent lzip.
 521 </p>
 522 <p>Installing from a list of packages using standard input:
 523 </p>
 524 <div class="example">
 525 <pre class="example">cat FILELIST.txt | qi -i -
 526 </pre></div>
 527
 528 <p>The list of packages must contain full path names to be passed in the
 529 installation, e.g.:
 530 /var/cache/qi/packages/x86_64/devel/tcl-8.6.9-x86_64+1.tlz
 531 /var/cache/qi/packages/x86_64/devel/tk-8.6.9.1-x86_64+1.tlz
 532 /var/cache/qi/packages/x86_64/devel/vala-0.42.3-x86_64+1.tlz
 533 </p>
 534 <a name="Removing-packages"></a>
 535 <h3 class="section">4.3 Removing packages</h3>
 536 <a name="index-package-de_002dinstallation"></a>
 537
 538 <p>To remove a package, simply type:
 539 </p>
 540 <div class="example">
 541 <pre class="example">qi -d xz-5.2.4-i586+1.tlz
 542 </pre></div>
 543
 544 <p>Delete mode will match the package name using &lsquo;<samp>${packagedir}</samp>&rsquo; as
 545 prefix.  For example, if the value of &lsquo;<samp>${packagedir}</samp>&rsquo; is set to
 546 /usr/local/pkgs, this will be equal to:
 547 </p>
 548 <div class="example">
 549 <pre class="example">qi -d /usr/local/pkgs/xz-5.2.4-i586+1
 550 </pre></div>
 551
 552 <p>Detailed output (very verbose):
 553 </p>
 554 <div class="example">
 555 <pre class="example">qi -d -v /usr/local/pkgs/xz-5.2.4-i586+1
 556 </pre></div>
 557
 558 <p>A second -v gives more.
 559 </p>
 560 <p>By default the delete mode does not preserve a package directory after
 561 removing its links from &lsquo;<samp>${targetdir}</samp>&rsquo;, but this behavior can be
 562 changed if the -k option is passed:
 563 </p>
 564 <div class="example">
 565 <pre class="example">qi -d -k /usr/local/pkgs/lzip-1.21-i586+1
 566 </pre></div>
 567
 568 <p>This means that the links to the package can be reactivated, later:
 569 </p>
 570 <div class="example">
 571 <pre class="example">cd /usr/local/pkgs &amp;&amp; graft -i lzip-1.21-i586+1
 572 </pre></div>
 573
 574 <p>Removing package from a different location:
 575 </p>
 576 <div class="example">
 577 <pre class="example">qi -r /home/cthulhu -P /pkgs -t / -d xz-5.2.4-i586+1
 578 </pre></div>
 579
 580 <p>Removing a package using standard input:
 581 </p>
 582 <div class="example">
 583 <pre class="example">echo &quot;vala-0.42.3-x86_64+1&quot; | qi -d -
 584 </pre></div>
 585
 586 <p>This will match with the package directory.
 587 </p>
 588 <a name="Upgrading-packages"></a>
 589 <h3 class="section">4.4 Upgrading packages</h3>
 590 <a name="index-package-upgrade"></a>
 591
 592 <p>The upgrade mode inherits the properties of the installation and removal
 593 process.  To make sure that a package is updated, the package is installed
 594 in a temporary directory taking &lsquo;<samp>${packagedir}</samp>&rsquo; into account.  Once
 595 the incoming package is pre-installed, qi can proceed to search and delete
 596 packages that have the same name (considered as previous ones).  Finally,
 597 the package is re-installed at its final location and the temporary
 598 directory is removed.
 599 </p>
 600 <p>To upgrade a package, just type:
 601 </p>
 602 <div class="example">
 603 <pre class="example">qi -u gcc-9.0.1-i586+1.tlz
 604 </pre></div>
 605
 606 <p>This will proceed to update &quot;gcc-9.0.1-i586+1&quot; removing other versions
 607 of &quot;gcc&quot; (if any).
 608 </p>
 609 <p>If you want to keep the package directories of versions found during the
 610 upgrade process, just pass:
 611 </p>
 612 <div class="example">
 613 <pre class="example">qi -u -k gcc-9.0.1-i586+1.tlz
 614 </pre></div>
 615
 616 <p>To see the upgrade process (very verbose):
 617 </p>
 618 <div class="example">
 619 <pre class="example">qi -u -v gcc-9.0.1-i586+1.tlz
 620 </pre></div>
 621
 622 <p>A second -v gives more.
 623 </p>
 624 <p>To force the upgrade of an existing package:
 625 </p>
 626 <div class="example">
 627 <pre class="example">qi -u -f gcc-9.0.1-i586+1.tlz
 628 </pre></div>
 629
 630 <a name="Package-blacklist"></a>
 631 <h4 class="subsection">4.4.1 Package blacklist</h4>
 632 <a name="index-package-blacklist"></a>
 633
 634 <p>To implement general package facilities, either to install, remove or
 635 maintain the hierarchy of packages in a clean manner, qi makes use of the
 636 pruning operation via graft(1):
 637 </p>
 638 <p>There is a risk if those are crucial packages for the proper functioning
 639 of the system, because it implies the deactivation of symbolic from the
 640 target directory, <em>especially</em> when transitioning an incoming package
 641 into its final location during upgrade.
 642 </p>
 643 <p>A blacklist of package names has been devised for the case where
 644 a user decides to upgrade all packages in the system, or
 645 just the crucial ones, such as the C library.
 646 </p>
 647 <p>The blacklist is related to the upgrade mode only, consists in installing
 648 a package instead of updating it or removing previous versions of it;
 649 the content of the package will be updated over the existing content at
 650 &lsquo;<samp>${packagedir}</samp>&rsquo;, while the existing links from
 651 &lsquo;<samp>${targetdir}</samp>&rsquo; will be preserved.  A pruning of links will be
 652 carried out in order to re-link possible differences with the recent
 653 content, this helps to avoid leaving dead links in the target directory.
 654 </p>
 655 <p>Since the upgrade mode is also used to install a new package, the mechanism
 656 for blacklist is to install a declared package if it does not already
 657 exist.  If it already exists, it is verified that the binary package is
 658 newer than the package directory in order to perform an update.
 659 </p>
 660 <p>Package names for the blacklist can be set from the configuration file.
 661 </p>
 662
 663 <hr>
 664 <a name="Recipes"></a>
 665 <div class="header">
 666 <p>
 667 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>
 668 </div>
 669 <a name="Recipes-1"></a>
 670 <h2 class="chapter">5 Recipes</h2>
 671 <a name="index-recipes"></a>
 672
 673 <p>A recipe is a file telling qi what to do.  Most often, the recipe tells
 674 qi how to build a binary package from a source tarball.
 675 </p>
 676 <p>A recipe has two parts: a list of variable definitions and a list of
 677 sections.  By convention, the syntax of a section is:
 678 </p>
 679 <div class="example">
 680 <pre class="example">section_name()
 681 {
 682     section lines
 683 }
 684 </pre></div>
 685
 686 <p>The section name is followed by parentheses, one newline and an opening
 687 brace.  The line finishing the section contains just a closing brace.
 688 The section names or the function names currently recognized are
 689 &lsquo;<samp>build</samp>&rsquo;.
 690 </p>
 691 <p>The &lsquo;<samp>build</samp>&rsquo; section is an augmented shell script.  This is the main
 692 section (or <strong>shell function</strong>) which contains the instructions to
 693 build and produce a package.
 694 </p>
 695 <a name="Variables"></a>
 696 <h3 class="section">5.1 Variables</h3>
 697 <a name="index-variables"></a>
 698
 699 <p>A &quot;variable&quot; is a <strong>shell variable</strong> defined either in <samp>qirc</samp>
 700 or in a recipe to represent a string of text, called the variable&rsquo;s
 701 &quot;value&quot;.  These values are substituted by explicit request in the
 702 definitions of other variables or in calls to external commands.
 703 </p>
 704 <p>Variables can represent lists of file names, options to pass to
 705 compilers, programs to run, directories to look in for source files,
 706 directories to write output to, or anything else you can imagine.
 707 </p>
 708 <p>Definitions of variables in qi have four levels of precedence.
 709 Options which define variables from the command-line override those
 710 specified in the <samp>qirc</samp> file, while variables defined in the recipe
 711 override those specified in <samp>qirc</samp>, taking priority over those
 712 variables set by command-line options.  Finally, the variables have
 713 default values if they are not defined anywhere.
 714 </p>
 715 <p>Options that set variables through the command-line can only reference
 716 variables defined in <samp>qirc</samp> and variables with default values.
 717 </p>
 718 <p>Definitions of variables in <samp>qirc</samp> can only reference variables
 719 previously defined in <samp>qirc</samp> and variables with default values.
 720 </p>
 721 <p>Definitions of variables in the recipe can only reference variables
 722 set by the command-line, variables previously defined in the recipe,
 723 variables defined in <samp>qirc</samp>, and variables with default values.
 724 </p>
 725 <a name="Special-variables"></a>
 726 <h3 class="section">5.2 Special variables</h3>
 727 <a name="index-special-variables"></a>
 728
 729 <p>There are variables which can only be set using the command line options or
 730 via <samp>qirc</samp>, there are other special variables which can be defined or
 731 redefined in a recipe.  See the following definitions:
 732 </p>
 733 <p>&lsquo;<samp>outdir</samp>&rsquo; is the directory where the packages produced are written.
 734 This variable can not be redefined in the recipe.  Default sets to
 735 &lsquo;<samp>/var/cache/qi/packages</samp>&rsquo;.
 736 </p>
 737 <p>&lsquo;<samp>worktree</samp>&rsquo; is the working tree where archives, patches, and recipes
 738 are expected.  This variable can not be redefined in the recipe.  Default
 739 sets to &lsquo;<samp>/usr/src/qi</samp>&rsquo;.
 740 </p>
 741 <p>&lsquo;<samp>tardir</samp>&rsquo; is defined in the recipe to the directory where the tarball
 742 containing the source can be found.  The full name of the tarball is
 743 composed as &lsquo;<samp>${tardir}/$tarname</samp>&rsquo;.  Its value is available in the
 744 recipe as &lsquo;<samp>${tardir}</samp>&rsquo;; a value of . for &lsquo;<samp>tardir</samp>&rsquo; sets it to
 745 the value of CWD (Current Working Directory), this is where the recipe
 746 lives.
 747 </p>
 748 <p>&lsquo;<samp>arch</samp>&rsquo; is the architecture to compose the package name.  Its value is
 749 available in the recipe as &lsquo;<samp>${arch}</samp>&rsquo;.  Default value is the output
 750 of &lsquo;<samp>uname -m</samp>&rsquo;.
 751 </p>
 752 <p>&lsquo;<samp>jobs</samp>&rsquo; is the number of parallel jobs to pass to the compiler.  Its
 753 value is available in the recipe as &lsquo;<samp>${jobs}</samp>&rsquo;.  The default value
 754 is 1.
 755 </p>
 756 <p>The two variables &lsquo;<samp>${srcdir}</samp>&rsquo; and &lsquo;<samp>${destdir}</samp>&rsquo; can be
 757 set in the recipe, as any other variable, but if they are not, qi uses
 758 default values for them when building a package.
 759 </p>
 760 <p>&lsquo;<samp>srcdir</samp>&rsquo; contains the source code to be compiled, and defaults to
 761 &lsquo;<samp>${program}-${version}</samp>&rsquo;.  &lsquo;<samp>destdir</samp>&rsquo; is the place where the
 762 built package will be installed, and defaults to
 763 &lsquo;<samp>${TMPDIR}/package-${program}</samp>&rsquo;.
 764 </p>
 765 <p>If &lsquo;<samp>pkgname</samp>&rsquo; is left undefined, the special variable &lsquo;<samp>program</samp>&rsquo;
 766 is assigned by default.  If &lsquo;<samp>pkgversion</samp>&rsquo; is left undefined, the
 767 special variable &lsquo;<samp>version</samp>&rsquo; is assigned by default.
 768 </p>
 769 <p>&lsquo;<samp>pkgname</samp>&rsquo; and &lsquo;<samp>pkgversion</samp>&rsquo; along with: &lsquo;<samp>version</samp>&rsquo;, &lsquo;<samp>arch</samp>&rsquo;,
 770 and &lsquo;<samp>release</samp>&rsquo; are used to produce the name of the package in the form:
 771 &lsquo;<samp>${pkgname}-${pkgversion}-${arch}+${release}.tlz</samp>&rsquo;
 772 </p>
 773 <p>A special variable called &lsquo;<samp>replace</samp>&rsquo; can be used to declare package
 774 names that will be replaced at the time of installation.
 775 </p>
 776 <p>A typical recipe contains the following variables:
 777 </p>
 778 <ul>
 779 <li> &lsquo;<samp>program</samp>&rsquo;: software name.
 780
 781 <p>It matches the source name.  It is also used to compose the name of the
 782 package if &lsquo;<samp>${pkgname}</samp>&rsquo; is not specified.
 783 </p>
 784 </li><li> &lsquo;<samp>version</samp>&rsquo;: software version.
 785
 786 <p>It matches the source name.  It is also used to compose the version of the
 787 package if &lsquo;<samp>${pkgversion}</samp>&rsquo; is not specified.
 788 </p>
 789 </li><li> &lsquo;<samp>arch</samp>&rsquo;: software architecture.
 790
 791 <p>It is used to compose the architecture of the package in which it is
 792 build.
 793 </p>
 794 </li><li> &lsquo;<samp>release</samp>&rsquo;: release number.
 795
 796 <p>This is used to reflect the release number of the package.  It is
 797 recommended to increase this number after any significant change in
 798 the recipe or post-install script.
 799 </p></li></ul>
 800
 801 <p>Obtaining sources over the network must be declared in the recipe using
 802 the &lsquo;<samp>fetch</samp>&rsquo; variable.  Use double quotes for separated values.
 803 </p>
 804 <p>The variables &lsquo;<samp>netget</samp>&rsquo; and &lsquo;<samp>rsync</samp>&rsquo; can be defined in <samp>qirc</samp>
 805 to establish a network downloader in order to get the sources.  If they
 806 are not defined, qi uses default values:
 807 </p>
 808 <p>&lsquo;<samp>netget</samp>&rsquo; is the general network downloader tool, defaults sets to
 809 &lsquo;<samp>wget -c -w1 -t3 --no-check-certificate</samp>&rsquo;.
 810 </p>
 811 <p>&lsquo;<samp>rsync</samp>&rsquo; is the network tool for sources containing the prefix for
 812 the RSYNC protocol, default sets to
 813 &lsquo;<samp>rsync -v -a -L -z -i --progress</samp>&rsquo;.
 814 </p>
 815 <p>The variable &lsquo;<samp>description</samp>&rsquo; is used to print the package description
 816 when a package is installed.
 817 </p>
 818 <p>A description has two parts: a brief description, and a long description.
 819 By convention, the syntax of &lsquo;<samp>description</samp>&rsquo; is:
 820 </p>
 821 <div class="example">
 822 <pre class="example">description=&quot;
 823 Brief description.
 824
 825 Long description.
 826 &quot;
 827 </pre></div>
 828
 829 <p>The first line of the value represented is a brief description of the
 830 software (called &quot;blurb&quot;).  A blank line separates the <em>brief
 831 description</em> from the <em>long description</em>, which should contain a more
 832 descriptive description of the software.
 833 </p>
 834 <p>An example looks like:
 835 </p>
 836 <div class="example">
 837 <pre class="example">description=&quot;
 838 The GNU core utilities.
 839
 840 The GNU core utilities are the basic file, shell and text manipulation
 841 utilities of the GNU operating system.  These are the core utilities
 842 which are expected to exist on every operating system.
 843 &quot;
 844 </pre></div>
 845
 846 <p>Please consider a length limit of 78 characters as maximum, because the same
 847 one would be used on the meta file creation.  See
 848 <a href="#Recipes">The meta file</a> section.
 849 </p>
 850 <p>The &lsquo;<samp>homepage</samp>&rsquo; variable is used to declare the main site or home page:
 851 </p>
 852 <div class="example">
 853 <pre class="example">homepage=http://www.gnu.org/software/gcc
 854 </pre></div>
 855
 856 <p>The variable &lsquo;<samp>license</samp>&rsquo; is used for license information<a name="DOCF2" href="#FOOT2"><sup>2</sup></a>.
 857 Some code in the program can be covered by license A, license B, or
 858 license C.  For &quot;separate licensing&quot; or &quot;heterogeneous licensing&quot;, we
 859 suggest using <strong>|</strong> for a disjunction, <strong>&amp;</strong> for a conjunction
 860 (if that ever happens in a significant way), and comma for heterogeneous
 861 licensing.  Comma would have lower precedence, plus added special terms.
 862 </p>
 863 <div class="example">
 864 <pre class="example">license=&quot;LGPL, GPL | Artistic + added permission&quot;
 865 </pre></div>
 866
 867 <a name="Writing-recipes"></a>
 868 <h3 class="section">5.3 Writing recipes</h3>
 869 <a name="index-writing-recipes"></a>
 870
 871 <p>Originally, qi was designed for the version 3 of Dragora GNU/Linux (this
 872 does not mean that you can&rsquo;t use it in another distribution, just that
 873 if you do you will need to test it for your selves).  To aid this here
 874 are some references to well written recipes:
 875 </p>
 876 <p><a href="http://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes">http://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes</a>.
 877 <a href="http://notabug.org/dragora/dragora/src/master/recipes">http://notabug.org/dragora/dragora/src/master/recipes</a>.
 878 </p>
 879 <p>You can also check the &quot;doc&quot; directory in the distribution sources of qi
 880 for some examples.
 881 </p>
 882 <a name="Building-packages"></a>
 883 <h3 class="section">5.4 Building packages</h3>
 884 <a name="index-package-build"></a>
 885
 886 <p>A recipe is any valid regular file.  Qi sets priorities for reading a
 887 recipe, the order in which qi looks for a recipe is:
 888 </p>
 889 <ol>
 890 <li> Current working directory.
 891
 892 </li><li> If the specified path name does not contain &quot;recipe&quot; as the last
 893 component.  Qi will complete it by adding &quot;recipe&quot; to the path name.
 894
 895 </li><li> If the recipe is not in the current working directory, it will be
 896 searched under &lsquo;<samp>${worktree}/recipes</samp>&rsquo;.  The last component will be
 897 completed adding &quot;recipe&quot; to the specified path name.
 898 </li></ol>
 899
 900 <p>To build a single package, type:
 901 </p>
 902 <div class="example">
 903 <pre class="example">qi -b x-apps/xterm
 904 </pre></div>
 905
 906 <p>Multiple jobs can be passed to the compiler to speed up the build process:
 907 </p>
 908 <div class="example">
 909 <pre class="example">qi -b -j3 x-apps/xterm
 910 </pre></div>
 911
 912 <p>Update or install the package produced (if it is not already installed)
 913 when finish:
 914 </p>
 915 <div class="example">
 916 <pre class="example">qi -b -j3 -u x-apps/xterm
 917 </pre></div>
 918
 919 <p>Only process a recipe but do not create the binary package:
 920 </p>
 921 <div class="example">
 922 <pre class="example">qi -b -n dict/aspell
 923 </pre></div>
 924
 925 <p>The options -i or -u have no effect when -n is given.
 926 </p>
 927 <p>This can be useful to inspect the build process of recipe:
 928 </p>
 929 <p>qi -b -k -n dict/aspell 2&gt;&amp;1 | tee aspell-buildlog.txt
 930 </p>
 931 <p>The -k option could preserve the source directory and the destination
 932 directory for later inspection.  A log file of the build process will be
 933 created redirecting both, standard error and standard output to tee(1).
 934 </p>
 935 <a name="Variables-from-the-environment"></a>
 936 <h3 class="section">5.5 Variables from the environment</h3>
 937 <a name="index-environment-variables"></a>
 938
 939 <p>Qi has environment variables which can be used at build time:
 940 </p>
 941 <p>The variable <code>TMPDIR</code> sets the temporary directory for sources, which is
 942 used for package extractions (see <a href="#Examining-packages">Examining packages</a>) and is
 943 prepended to the value of &lsquo;<samp>${srcdir}</samp>&rsquo; and &lsquo;<samp>${destdir}</samp>&rsquo; in
 944 build mode.  By convention its default value is equal to
 945 &lsquo;<samp>/usr/src/qi/build</samp>&rsquo;.
 946 </p>
 947 <p>The variables <code>QICFLAGS</code>, <code>QICXXFLAGS</code>, and <code>QILDFLAGS</code> have
 948 no effect by default.  The environment variables such as <code>CFLAGS</code>,
 949 <code>CXXFLAGS</code>, and <code>LDFLAGS</code> are unset at compile time:
 950 </p>
 951 <p>Recommended practice is to set variables in the command line of
 952 &lsquo;<samp>configure</samp>&rsquo; or <em>make(1)</em> instead of exporting to the
 953 environment.  As follows:
 954 </p>
 955 <blockquote>
 956 <p>Variables not defined in a site shell script can be set in the environment
 957 passed to configure.  However, some packages may run configure again
 958 during the build, and the customized values of these variables may be
 959 lost.  In order to avoid this problem, you should set them in the
 960 configure command line, using &lsquo;<samp>VAR=value</samp>&rsquo;.  For example:
 961 </p>
 962 <p><code>./configure CC=/usr/local2/bin/gcc</code>
 963 </p>
 964 <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>
 965 </p></blockquote>
 966
 967 <blockquote>
 968 <p>Indeed, while configure can notice the definition of CC in
 969 &lsquo;<samp>./configure CC=bizarre-cc</samp>&rsquo;, it is impossible to notice it in
 970 &lsquo;<samp>CC=bizarre-cc ./configure</samp>&rsquo;, which, unfortunately, is what most
 971 users do.
 972 </p>
 973 <p>[...]
 974 </p>
 975 <p>configure: error: changes in the environment can compromise the build.
 976 </p>
 977 <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>
 978 </p></blockquote>
 979
 980 <blockquote>
 981 <p>It is not wise for makefiles to depend for their functioning on
 982 environment variables set up outside their control, since this would cause
 983 different users to get different results from the same makefile.  This is
 984 against the whole purpose of most makefiles.
 985 </p>
 986 <p><a href="http://gnu.org/software/make/manual/make.html#Environment">http://gnu.org/software/make/manual/make.html#Environment</a>
 987 </p></blockquote>
 988
 989 <a name="The-meta-file"></a>
 990 <h3 class="section">5.6 The meta file</h3>
 991 <a name="index-the-meta-file"></a>
 992
 993 <p>The &quot;meta file&quot; is a regular file created during the build mode, it
 994 contains information about the package such as program name, program
 995 version, release, fetch address, description, and other minor data
 996 extracted from processed recipes.  The name of the file is generated as
 997 &lsquo;<samp>${full_pkgname}.tlz.txt</samp>&rsquo;, and its purpose is to reflect essential
 998 information to the user without having to look inside the package content.
 999 </p>
1000 <p>The content of a meta file looks like:
1001 </p>
1002 <div class="example">
1003 <pre class="example">#
1004 # The Bourne Again SHell.
1005 #
1006 # Bash is an sh-compatible shell that incorporates useful features from
1007 # the Korn shell (ksh) and C shell (csh).  It is intended to conform to
1008 # the IEEE POSIX P1003.2/ISO 9945.2 shell and tools standard.
1009 #
1010 # It offers functional improvements over sh for both programming and
1011 # interactive use.
1012 #
1013
1014 QICFLAGS=&quot;-g0 -Os -mtune=generic -pipe&quot;
1015 QICXXFLAGS=&quot;-g0 -Os -mtune=generic -pipe&quot;
1016 QILDFLAGS=&quot;-s&quot;
1017 program=bash
1018 version=5.0
1019 release=1
1020 blurb=&quot;The Bourne Again SHell.&quot;
1021 homepage=&quot;http://www.gnu.org/software/bash&quot;
1022 license=&quot;GPLv3+&quot;
1023 fetch=&quot;ftp://ftp.gnu.org/gnu/bash/bash-5.0.tar.gz&quot;
1024 replace=&quot;&quot;
1025 </pre></div>
1026
1027 <p>Package descriptions are extracted from the variable &lsquo;<samp>description</samp>&rsquo;:
1028 each line is interpreted literally and pre-formatted to fit in (exactly)
1029 <strong>80 columns</strong>, plus the character &lsquo;<samp>#</samp>&rsquo; and a space is prefixed
1030 to every line.
1031 </p>
1032 <p>In addition to the Special variables, there are implicit variables such as
1033 &lsquo;<samp>blurb</samp>&rsquo;:
1034 </p>
1035 <p>The &lsquo;<samp>blurb</samp>&rsquo; variable is related to the special variable
1036 &lsquo;<samp>description</samp>&rsquo;.  Its value is composed using the first (substantial)
1037 line of &lsquo;<samp>description</samp>&rsquo;, mentioned as the &quot;brief description&quot;.
1038 </p>
1039
1040 <hr>
1041 <a name="Order-files"></a>
1042 <div class="header">
1043 <p>
1044 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>
1045 </div>
1046 <a name="Order-files-1"></a>
1047 <h2 class="chapter">6 Order files</h2>
1048 <a name="index-handling-build-order"></a>
1049
1050 <p>The order mode has the purpose of resolving the build order through
1051 .order files.  An order file contains a list of recipe names, by default
1052 does not perform any action other than to print a resolved list in
1053 descending order.  For example, if <strong>a</strong> depends on <strong>b</strong> and
1054 <strong>c</strong>, and <strong>c</strong> depends on <strong>b</strong> as well, the file might
1055 look like:
1056 </p>
1057 <div class="example">
1058 <pre class="example">a: c b
1059 b:
1060 c: b
1061 </pre></div>
1062
1063 <p>Each letter represents a recipe name, complete dependencies for
1064 the first recipe name are listed in descending order, which is
1065 printed from right to left, and removed from left to right:
1066 </p>
1067 <p><small>OUTPUT</small>
1068 </p>
1069 <div class="example">
1070 <pre class="example">b
1071 c
1072 a
1073 </pre></div>
1074
1075 <p>Blank lines, colons and parentheses are simply ignored.  Comment lines
1076 beginning with &lsquo;<samp>#</samp>&rsquo; are allowed.
1077 </p>
1078 <p>An order file could be used to build a series of packages, for example,
1079 if the content is:
1080 </p>
1081 <div class="example">
1082 <pre class="example"># Image handling libraries
1083
1084 libs/libjpeg-turbo: devel/nasm
1085 x-libs/jasper: libs/libjpeg-turbo
1086 libs/tiff: libs/libjpeg-turbo
1087 </pre></div>
1088
1089 <p>To proceed with each recipe, we can type:
1090 </p>
1091 <div class="example">
1092 <pre class="example">qi -o imglibs.order | qi -b -i -
1093 </pre></div>
1094
1095 <p>The output of &lsquo;<samp>qi -o imglibs.order</samp>&rsquo; tells to qi in which order it
1096 should build the recipes:
1097 </p>
1098 <div class="example">
1099 <pre class="example">devel/nasm
1100 libs/libjpeg-turbo
1101 x-libs/jasper
1102 libs/tiff
1103 </pre></div>
1104
1105
1106 <hr>
1107 <a name="Creating-packages"></a>
1108 <div class="header">
1109 <p>
1110 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>
1111 </div>
1112 <a name="Creating-packages-1"></a>
1113 <h2 class="chapter">7 Creating packages</h2>
1114 <a name="index-package-creation"></a>
1115
1116 <p>The &quot;creation mode&quot; is an internal function of qi to make new Qi compatible
1117 compatible packages, the creation mode is selected by the -c option.
1118 A package is produced using the contents of the Current Directory, and
1119 the package file is written out.
1120 </p>
1121 <div class="example">
1122 <pre class="example">Usage: qi -c [<var>OUTPUT/packagename.tlz</var>]...
1123 </pre></div>
1124
1125 <p>The argument for the file name to be written must contain a fully
1126 qualified named directory as the output directory where the package
1127 produced will be written.  The file name should be composed using the
1128 full name: name-version-architecture+release.tlz
1129 </p>
1130 <p><small>EXAMPLE</small>
1131 </p>
1132 <div class="example">
1133 <pre class="example">cd /usr/local/pkgs
1134 cd claws-mail-3.17.1-x86_64+1
1135 qi -c /var/cache/qi/packages/x86_64/local/claws-mail-3.17.1-x86_64+1.tlz
1136 </pre></div>
1137
1138 <p>In this case, the package &quot;claws-mail-3.17.1-x86_64+1.tlz&quot; will be written
1139 into &lsquo;<samp>/var/cache/qi/packages/x86_64/local/</samp>&rsquo;.
1140 </p>
1141 <p>All packages produced are complemented by a checksum file (.sha256).
1142 </p>
1143
1144 <hr>
1145 <a name="Examining-packages"></a>
1146 <div class="header">
1147 <p>
1148 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>
1149 </div>
1150 <a name="Examining-packages-1"></a>
1151 <h2 class="chapter">8 Examining packages</h2>
1152 <a name="index-package-examination"></a>
1153
1154 <p>The &quot;extraction mode&quot; serves to examine binary packages for debugging
1155 purposes. The extraction mode is selected by the -x option.  It
1156 decompresses a package into a single directory, verifying its integrity
1157 and preserving its properties.
1158 </p>
1159 <div class="example">
1160 <pre class="example">Usage: qi -x [<var>packagename.tlz</var>]...
1161 </pre></div>
1162
1163 <p><small>EXAMPLE</small>
1164 </p>
1165 <div class="example">
1166 <pre class="example">qi -x mksh-R56c-x86_64+1.tlz
1167 </pre></div>
1168
1169 <p>This action will put the content of &quot;mksh-R56c-x86_64+1.tlz&quot; into a
1170 single directory, this will be a private directory for the user who
1171 </p>
1172 <p>requested the action, creation mode will be equal to <strong>u=rwx,g=,o=
1173 (0700)</strong>.  The package content will reside on this location, default
1174 mask to deploy the content will be equal to
1175 <strong>u=rwx,g=rwx,o=rwx (0000)</strong>.
1176 </p>
1177 <p>The creation of the custom directory is influenced by the value of the
1178 <code>TMPDIR</code> variable.
1179 </p>
1180
1181 <hr>
1182 <a name="Exit-status"></a>
1183 <div class="header">
1184 <p>
1185 Next: <a href="#Index" accesskey="n" rel="next">Index</a>, Previous: <a href="#Examining-packages" accesskey="p" rel="prev">Examining packages</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1186 </div>
1187 <a name="Exit-status-1"></a>
1188 <h2 class="chapter">9 Exit status</h2>
1189 <a name="index-exit-codes"></a>
1190
1191 <p>All the exit codes are described in this chapter.
1192 </p>
1193 <dl compact="compact">
1194 <dt>&lsquo;<samp>0</samp>&rsquo;</dt>
1195 <dd><p>Successful completion (no errors).
1196 </p>
1197 </dd>
1198 <dt>&lsquo;<samp>1</samp>&rsquo;</dt>
1199 <dd><p>Minor common errors:
1200 </p>
1201 <ul class="no-bullet">
1202 <li>- Help usage on illegal options or required arguments.
1203
1204 </li><li>- Program needed by qi (prerequisite) is not available.
1205 </li></ul>
1206
1207 </dd>
1208 <dt>&lsquo;<samp>2</samp>&rsquo;</dt>
1209 <dd><p>Command execution error:
1210 </p>
1211 <p>This code is used to return the evaluation of external commands and shell
1212 arguments in case of error.
1213 </p>
1214 </dd>
1215 <dt>&lsquo;<samp>3</samp>&rsquo;</dt>
1216 <dd><p>Integrity check error for compressed files.
1217 </p>
1218 <p>Compressed files means:
1219 </p>
1220 <ul class="no-bullet">
1221 <li>- Tarball files from tar(1).
1222 Supported extensions: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
1223 .tar.xz, .txz
1224
1225 </li><li>- Tarball files from tarlz(1).
1226 Supported extensions: .tar.lz, .tlz
1227
1228 </li><li>- Zip files from unzip(1).
1229 Supported extensions: .zip, .ZIP
1230
1231 </li><li>- Gzip files from gzip(1).
1232 Supported extensions: .gz, .Z
1233
1234 </li><li>- Bzip2 files from bzip2(1).
1235 Supported extensions: .bz2
1236
1237 </li><li>- Lzip files from lzip(1).
1238 Supported extensions: .lz
1239
1240 </li><li>- Xz files from xz(1).
1241 Supported extensions: .xz
1242 </li></ul>
1243
1244 </dd>
1245 <dt>&lsquo;<samp>4</samp>&rsquo;</dt>
1246 <dd><p>File empty, not regular, or expected.
1247 </p>
1248 <p>Commonly, it is expected:
1249 </p>
1250 <ul class="no-bullet">
1251 <li>- An argument for the mode of operation.
1252
1253 </li><li>- A readable file or directory.
1254
1255 </li><li>- A binary package (.tlz).
1256
1257 </li><li>- A valid recipe.
1258
1259 </li><li>- An order file (.order).
1260
1261 </li><li>- A protocol supported by the network downloader tool.
1262
1263 </li><li>- A checksum file (.sha256).
1264 </li></ul>
1265
1266 </dd>
1267 <dt>&lsquo;<samp>5</samp>&rsquo;</dt>
1268 <dd><p>Empty or not defined variable:
1269 </p>
1270 <p>This code is used to report empty or undefined variables; usually,
1271 variables coming from a recipe or assigned arrays that are tested.
1272 </p>
1273 </dd>
1274 <dt>&lsquo;<samp>6</samp>&rsquo;</dt>
1275 <dd><p>Package already installed:
1276 </p>
1277 <p>The package directory for an incoming .tlz package already exists.
1278 </p>
1279 </dd>
1280 <dt>&lsquo;<samp>10</samp>&rsquo;</dt>
1281 <dd><p>Network manager error:
1282 </p>
1283 <p>This code is used if the network downloader tool fails for some reason.
1284 </p></dd>
1285 </dl>
1286
1287
1288 <hr>
1289 <a name="Index"></a>
1290 <div class="header">
1291 <p>
1292 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>
1293 </div>
1294 <a name="Index-1"></a>
1295 <h2 class="unnumbered">Index</h2>
1296
1297 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a>
1298  &nbsp;
1299 <a class="summary-letter" href="#Index_cp_letter-E"><b>E</b></a>
1300  &nbsp;
1301 <a class="summary-letter" href="#Index_cp_letter-H"><b>H</b></a>
1302  &nbsp;
1303 <a class="summary-letter" href="#Index_cp_letter-I"><b>I</b></a>
1304  &nbsp;
1305 <a class="summary-letter" href="#Index_cp_letter-M"><b>M</b></a>
1306  &nbsp;
1307 <a class="summary-letter" href="#Index_cp_letter-P"><b>P</b></a>
1308  &nbsp;
1309 <a class="summary-letter" href="#Index_cp_letter-R"><b>R</b></a>
1310  &nbsp;
1311 <a class="summary-letter" href="#Index_cp_letter-S"><b>S</b></a>
1312  &nbsp;
1313 <a class="summary-letter" href="#Index_cp_letter-T"><b>T</b></a>
1314  &nbsp;
1315 <a class="summary-letter" href="#Index_cp_letter-V"><b>V</b></a>
1316  &nbsp;
1317 <a class="summary-letter" href="#Index_cp_letter-W"><b>W</b></a>
1318  &nbsp;
1319 </td></tr></table>
1320 <table class="index-cp" border="0">
1321 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
1322 <tr><td colspan="4"> <hr></td></tr>
1323 <tr><th><a name="Index_cp_letter-C">C</a></th><td></td><td></td></tr>
1324 <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>
1325 <tr><td colspan="4"> <hr></td></tr>
1326 <tr><th><a name="Index_cp_letter-E">E</a></th><td></td><td></td></tr>
1327 <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>
1328 <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>
1329 <tr><td colspan="4"> <hr></td></tr>
1330 <tr><th><a name="Index_cp_letter-H">H</a></th><td></td><td></td></tr>
1331 <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>
1332 <tr><td colspan="4"> <hr></td></tr>
1333 <tr><th><a name="Index_cp_letter-I">I</a></th><td></td><td></td></tr>
1334 <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>
1335 <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>
1336 <tr><td colspan="4"> <hr></td></tr>
1337 <tr><th><a name="Index_cp_letter-M">M</a></th><td></td><td></td></tr>
1338 <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>
1339 <tr><td colspan="4"> <hr></td></tr>
1340 <tr><th><a name="Index_cp_letter-P">P</a></th><td></td><td></td></tr>
1341 <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>
1342 <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>
1343 <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>
1344 <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>
1345 <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>
1346 <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>
1347 <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>
1348 <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>
1349 <tr><td colspan="4"> <hr></td></tr>
1350 <tr><th><a name="Index_cp_letter-R">R</a></th><td></td><td></td></tr>
1351 <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>
1352 <tr><td colspan="4"> <hr></td></tr>
1353 <tr><th><a name="Index_cp_letter-S">S</a></th><td></td><td></td></tr>
1354 <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>
1355 <tr><td colspan="4"> <hr></td></tr>
1356 <tr><th><a name="Index_cp_letter-T">T</a></th><td></td><td></td></tr>
1357 <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>
1358 <tr><td colspan="4"> <hr></td></tr>
1359 <tr><th><a name="Index_cp_letter-V">V</a></th><td></td><td></td></tr>
1360 <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>
1361 <tr><td colspan="4"> <hr></td></tr>
1362 <tr><th><a name="Index_cp_letter-W">W</a></th><td></td><td></td></tr>
1363 <tr><td></td><td valign="top"><a href="#index-writing-recipes">writing recipes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
1364 <tr><td colspan="4"> <hr></td></tr>
1365 </table>
1366 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a>
1367  &nbsp;
1368 <a class="summary-letter" href="#Index_cp_letter-E"><b>E</b></a>
1369  &nbsp;
1370 <a class="summary-letter" href="#Index_cp_letter-H"><b>H</b></a>
1371  &nbsp;
1372 <a class="summary-letter" href="#Index_cp_letter-I"><b>I</b></a>
1373  &nbsp;
1374 <a class="summary-letter" href="#Index_cp_letter-M"><b>M</b></a>
1375  &nbsp;
1376 <a class="summary-letter" href="#Index_cp_letter-P"><b>P</b></a>
1377  &nbsp;
1378 <a class="summary-letter" href="#Index_cp_letter-R"><b>R</b></a>
1379  &nbsp;
1380 <a class="summary-letter" href="#Index_cp_letter-S"><b>S</b></a>
1381  &nbsp;
1382 <a class="summary-letter" href="#Index_cp_letter-T"><b>T</b></a>
1383  &nbsp;
1384 <a class="summary-letter" href="#Index_cp_letter-V"><b>V</b></a>
1385  &nbsp;
1386 <a class="summary-letter" href="#Index_cp_letter-W"><b>W</b></a>
1387  &nbsp;
1388 </td></tr></table>
1389
1390 <div class="footnote">
1391 <hr>
1392 <h4 class="footnotes-heading">Footnotes</h4>
1393
1394 <h3><a name="FOOT1" href="#DOCF1">(1)</a></h3>
1395 <p>The official guide for Graft can be found at
1396 <a href="http://peters.gormand.com.au/Home/tools/graft/graft.html">http://peters.gormand.com.au/Home/tools/graft/graft.html</a>.</p>
1397 <h3><a name="FOOT2" href="#DOCF2">(2)</a></h3>
1398 <p>The proposal for &lsquo;<samp>license</samp>&rsquo; was made by Richard M. Stallman at
1399 <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>
1400 </div>
1401 <hr>
1402
1403
1404
1405 </body>
1406 </html>