qi: make release of qi 1.1
[dragora.git] / qi / doc / qi.info
blobbd6b78c59d6c0fa7d8356b38b47be04529635b67
1 This is qi.info, produced by makeinfo version 6.5 from qi.texi.
3 This user guide is for Qi (version 1.1, 19 May 2019), which is a simple
4 but well-integrated package manager.
6    Copyright © 2019 Matias Andres Fonzo, Santiago del Estero, Argentina.
8      Permission is granted to copy, distribute and/or modify this
9      document under the terms of the GNU Free Documentation License,
10      Version 1.3 or any later version published by the Free Software
11      Foundation; with no Invariant Sections, with no Front-Cover Texts,
12      and with no Back-Cover Texts.  A copy of the license is included in
13      the section entitled "GNU Free Documentation License".
14 INFO-DIR-SECTION Package management
15 START-INFO-DIR-ENTRY
16 * Qi: (qi).                   A user-friendly package manager.
17 END-INFO-DIR-ENTRY
19 \x1f
20 File: qi.info,  Node: Top,  Next: Introduction,  Up: (dir)
22 Qi user guide
23 *************
25 This user guide is for Qi (version 1.1, 19 May 2019).
27 * Menu:
29 * Introduction::              Description and features of qi
30 * Invoking qi::               Command-line options
31 * The qirc file::             Configuration file
32 * Packages::                  Managing packages
33 * Recipes::                   Building packages
34 * Order files::               Handling build order
35 * Creating packages::         Making Qi packages
36 * Examining packages::        Debugging purposes
37 * Exit status::               Exit codes
38 * Index::
41    Copyright (C) 2019 Matias Fonzo.
43    Qi's home page can be found at <http://www.dragora.org>.
44 Send bug reports or suggestions to <dragora-users@nongnu.org>.
46 \x1f
47 File: qi.info,  Node: Introduction,  Next: Invoking qi,  Prev: Top,  Up: Top
49 1 Introduction
50 **************
52 Qi is a simple but well-integrated package manager.  It can create,
53 install, remove, and upgrade software packages.  Qi produces binary
54 packages using recipes, which are files containing specific instructions
55 to build each package from source.  Qi can manage multiple packages
56 under a single directory hierarchy.  This method allows to maintain a
57 set of packages and multiple versions of them.  This means that Qi could
58 be used as the main package manager or complement the existing one.
60    Qi offers a friendly command line interface, a global configuration
61 file, a simple recipe layout to deploy software packages; also works
62 with binary packages in parallel, speeding up installations and packages
63 in production.  The format used for packages is a simplified but safe
64 POSIX pax archive compressed with lzip.
66    Qi is a modern (POSIX-compliant) shell script released under the
67 terms of the GNU General Public License.  There are only two major
68 dependencies for the magic: graft(1) and tarlz(1), the rest is expected
69 to be found in any Unix-like system.
71 \x1f
72 File: qi.info,  Node: Invoking qi,  Next: The qirc file,  Prev: Introduction,  Up: Top
74 2 Invoking qi
75 *************
77 This chapter describes the synopsis and command line options for invoke
78 Qi.
80      Usage: qi [OPTION]... [FILE]...
82 One mandatory option specifies the operation that 'qi' should perform,
83 other options are meant to detail how this operation should be
84 performed.
86 qi supports the following options to operate:
88 '-b'
89      Build package using recipe names.
91 '-c'
92      Create .tlz package from directory.
94 '-d'
95      Delete packages.
97 '-i'
98      Install packages.
100 '-o'
101      Resolve build order through .order files.
103 '-u'
104      Update packages (implies -i, -d and -p options).
106 '-w'
107      Warn about files that will be linked.
109 '-x'
110      Extract a package for debugging purposes.
112 There are common options between modes:
114 '-N'
115      Do not read the configuration file.
117      This will ignore any value in the qirc file.
119 '-P <DIR>'
120      Package directory for installations.
122      This option sets '${packagedir}'.
124      Only valid for -i, -d, or -u options.
126 '-f'
127      Force option.
129      This option can force the build of a recipe, or force the update of
130      a pre-existing package.
132      Only valid for -b, -u options.
134 '-t <DIR>'
135      Target directory for symbolic links.
137      This option sets '${targetdir}'.
139      Only valid for -i, -d, or -u options.
141 '-k'
142      Keep (don't delete) '${srcdir}' or '${destdir}' in build mode, keep
143      (don't delete) package directory in delete mode.
145      Only valid for -b, -d or -u options.
147 '-p'
148      Prune conflicts on package installations.
150      This option may proceed with the package installation if one or
151      more conflicts occur.
153 '-r /rootdir'
154      Use the fully qualified named directory as the root directory for
155      all qi operations.  The target directory and package directory will
156      be relative to the specified directory, including the log file for
157      graft.
159 '-v'
160      Be verbose (a 2nd -v gives more).
162 Options for build mode (-b):
164 '-O <DIR>'
165      Where the packages produced are written.
167      This option sets '${outdir}'.
169 '-W <DIR>'
170      Where archives, patches, and recipes are expected.
172      This option sets '${worktree}'.
174 '-Z <DIR>'
175      Where (compressed) sources will be found.
177      This option sets '${tardir}'.
179 '-a'
180      Architecture to use.
182      Default value is obtained via uname(1) as 'uname -m'.
184 '-j'
185      Parallel jobs for the compiler.
187      If not specified, default sets to 1.
189 '-1'
190      Increment release number ('${release}' + 1).
192      It will be omitted if the -n option is being used.
194 '-n'
195      Don't create a .tlz package.
197 '-S'
198      Selects the option to skip completed recipes.
200      This means, in interactive mode, when the dialog to summarize
201      recipes is shown.
203 Informative options:
205 '-L'
206      Print default directory locations.
208      This will print the target directory, package directory, working
209      tree, the directory for tarballs, and the output directory for the
210      packages produced.
212 '-h'
213      Display the help describing the options and then exit.
215 '-V'
216      Print the version number and license information.  The version
217      number should be included in all bug reports.
219 Expected non-option arguments are package directories and regular files:
220 recipes or files ending in .tlz, .order.  When FILE is -, qi can read
221 from the standard input.  See examples in *note Packages::.
223 \x1f
224 File: qi.info,  Node: The qirc file,  Next: Packages,  Prev: Invoking qi,  Up: Top
226 3 The qirc file
227 ***************
229 The global 'qirc' file offers a way to define variables and tools (such
230 as a download manager) for default use.  This file is used by qi at
231 runtime, e.g., to build, install, remove or upgrade packages.
233 It has the following rules:
235    * Variables must be declared as 'name=value'.
237    * Declaration of values should only take one line, no line break.
239    * For security reasons, assignments like 'name=$var' are only
240      interpreted as literal.
242 The command line options related to the package directory and target
243 directory plus some of the options used for the build mode can override
244 some values in 'qirc'.  See *note Invoking qi::.
246 The order in which qi looks for this file is:
248   1. '${HOME}/.qirc' Effective user.
250   2. '${sysconfdir}/qirc' System-wide.
252    If you intend to run qi as effective user, the file
253 '${sysconfdir}/qirc' could be copied to '${HOME}/.qirc' setting the
254 paths for '${packagedir}' and '${targetdir}' according to the '$HOME'.
256 \x1f
257 File: qi.info,  Node: Packages,  Next: Recipes,  Prev: The qirc file,  Up: Top
259 4 Packages
260 **********
262 A package is a suite of programs usually distributed in binary form
263 which may also contain manual pages, documentation, or any other file
264 associated to a specific software.
266    The package format used by qi is a simplified POSIX pax archive
267 compressed with lzip.  The file extension for packages is '.tlz'.
269 Both package installation and package de-installation are managed using
270 two important (internal) variables: '${packagedir}' and '${targetdir}',
271 these values can be changed in the configuration file or via options.
273    '${packagedir}' is a common directory tree where the package contents
274 will be decompressed (will reside).
276    '${targetdir}' is a target directory where the links will be made by
277 graft(1) taking '${packagedir}/package_name' into account.
279 Packages are installed in self-contained directory trees and symbolic
280 links from a common area are made to the package files.  This allows
281 multiple versions of the same package to coexist on the same system.
283 4.1 Package conflicts
284 =====================
286 All the links to install or remove a package are handled by graft(1).
287 Since multiple packages can be installed or removed at the same time,
288 certain conflicts may arise between the packages.
290 graft(1) defines a CONFLICT as one of the following conditions:
292    * If the package object is a directory and the target object exists
293      but is not a directory.
295    * If the package object is not a directory and the target object
296      exists and is not a symbolic link.
298    * If the package object is not a directory and the target object
299      exists and is a symbolic link to something other than the package
300      object.
302 The default behavior of qi for an incoming package is to ABORT if a
303 conflict arises.  When a package is going to be deleted, qi tells to
304 graft(1) to remove those parts that are not in conflict, leaving the
305 links to the belonging package.  This behavior can be forced if the -p
306 option is given.
308 4.2 Installing packages
309 =======================
311 To install a single package, simply type:
313      qi -i coreutils-8.30-i586+1.tlz
315 To install multiple packages at once, type:
317      qi -i gcc-8.3.0-i586+1.tlz rafaela-2.2-i586+1.tlz ...
319 Warn about the files that will be linked:
321      qi -w bash-5.0-i586+1.tlz
323    This is to verify the content of a package before installing it.
325 See the process of an installation (very verbose):
327      qi -i -v mariana-3.0-i586+1.tlz
329    A second -v gives more.
331 Installing package in a different location:
333      qi -r /media/floppy -i lzip-1.21-i586+1.tlz
335    The -r option assumes '${targetdir}' and '${packagedir}'.  See:
337      qi -r /home/selk -P /pkgs -t / -i lzip-1.21-i586+1.tlz
339    In this case the content of "lzip-1.21-i586+1.tlz" will be
340 decompressed into '/home/selk/pkgs/lzip-1.21-i586+1'.  Assuming that the
341 main binary for lzip is under
342 '/home/selk/pkgs/lzip-1.21-i586+1/usr/bin/' the target for "usr/bin"
343 will be created at '/home/selk'.  Considering that you have exported the
344 'PATH' as '${HOME}/usr/bin', now the system is able to see the recent
345 lzip.
347 Installing from a list of packages using standard input:
349      cat FILELIST.txt | qi -i -
351    The list of packages must contain full path names to be passed in the
352 installation, e.g.:
353 /var/cache/qi/packages/x86_64/devel/tcl-8.6.9-x86_64+1.tlz
354 /var/cache/qi/packages/x86_64/devel/tk-8.6.9.1-x86_64+1.tlz
355 /var/cache/qi/packages/x86_64/devel/vala-0.42.3-x86_64+1.tlz
357 4.3 Removing packages
358 =====================
360 To remove a package, simply type:
362      qi -d xz-5.2.4-i586+1.tlz
364 Delete mode will match the package name using '${packagedir}' as prefix.
365 For example, if the value of '${packagedir}' is set to /usr/local/pkgs,
366 this will be equal to:
368      qi -d /usr/local/pkgs/xz-5.2.4-i586+1
370 Detailed output (very verbose):
372      qi -d -v /usr/local/pkgs/xz-5.2.4-i586+1
374    A second -v gives more.
376 By default the delete mode does not preserve a package directory after
377 removing its links from '${targetdir}', but this behavior can be changed
378 if the -k option is passed:
380      qi -d -k /usr/local/pkgs/lzip-1.21-i586+1
382    This means that the links to the package can be reactivated, later:
384      cd /usr/local/pkgs && graft -i lzip-1.21-i586+1
386 Removing package from a different location:
388      qi -r /home/cthulhu -P /pkgs -t / -d xz-5.2.4-i586+1
390 Removing a package using standard input:
392      echo "vala-0.42.3-x86_64+1" | qi -d -
394    This will match with the package directory.
396 4.4 Upgrading packages
397 ======================
399 The upgrade mode inherits the properties of the installation and removal
400 process.  To make sure that a package is updated, the package is
401 installed in a temporary directory taking '${packagedir}' into account.
402 Once the incoming package is pre-installed, qi can proceed to search and
403 delete packages that have the same name (considered as previous ones).
404 Finally, the package is re-installed at its final location and the
405 temporary directory is removed.
407 To upgrade a package, just type:
409      qi -u gcc-9.0.1-i586+1.tlz
411    This will proceed to update "gcc-9.0.1-i586+1" removing other
412 versions of "gcc" (if any).
414 If you want to keep the package directories of versions found during the
415 upgrade process, just pass:
417      qi -u -k gcc-9.0.1-i586+1.tlz
419 To see the upgrade process (very verbose):
421      qi -u -v gcc-9.0.1-i586+1.tlz
423    A second -v gives more.
425 To force the upgrade of an existing package:
427      qi -u -f gcc-9.0.1-i586+1.tlz
429 4.4.1 Package blacklist
430 -----------------------
432 To implement general package facilities, either to install, remove or
433 maintain the hierarchy of packages in a clean manner, qi makes use of
434 the pruning operation via graft(1):
436    There is a risk if those are crucial packages for the proper
437 functioning of the system, because it implies the deactivation of
438 symbolic from the target directory, _especially_ when transitioning an
439 incoming package into its final location during upgrade.
441 A blacklist of package names has been devised for the case where a user
442 decides to upgrade all packages in the system, or just the crucial ones,
443 such as the C library.
445    The blacklist is related to the upgrade mode only, consists in
446 installing a package instead of updating it or removing previous
447 versions of it; the content of the package will be updated over the
448 existing content at '${packagedir}', while the existing links from
449 '${targetdir}' will be preserved.  A pruning of links will be carried
450 out in order to re-link possible differences with the recent content,
451 this helps to avoid leaving dead links in the target directory.
453 Since the upgrade mode is also used to install a new package, the
454 mechanism for blacklist is to install a declared package if it does not
455 already exist.  If it already exists, it is verified that the binary
456 package is newer than the package directory in order to perform an
457 update.
459    Package names for the blacklist can be set from the configuration
460 file.
462    ---------- Footnotes ----------
464    (1) The official guide for Graft can be found at
465 <http://peters.gormand.com.au/Home/tools/graft/graft.html>.
467 \x1f
468 File: qi.info,  Node: Recipes,  Next: Order files,  Prev: Packages,  Up: Top
470 5 Recipes
471 *********
473 A recipe is a file telling qi what to do.  Most often, the recipe tells
474 qi how to build a binary package from a source tarball.
476    A recipe has two parts: a list of variable definitions and a list of
477 sections.  By convention, the syntax of a section is:
479      section_name()
480      {
481          section lines
482      }
484    The section name is followed by parentheses, one newline and an
485 opening brace.  The line finishing the section contains just a closing
486 brace.  The section names or the function names currently recognized are
487 'build'.
489    The 'build' section is an augmented shell script.  This is the main
490 section (or *shell function*) which contains the instructions to build
491 and produce a package.
493 5.1 Variables
494 =============
496 A "variable" is a *shell variable* defined either in 'qirc' or in a
497 recipe to represent a string of text, called the variable's "value".
498 These values are substituted by explicit request in the definitions of
499 other variables or in calls to external commands.
501    Variables can represent lists of file names, options to pass to
502 compilers, programs to run, directories to look in for source files,
503 directories to write output to, or anything else you can imagine.
505    Definitions of variables in qi have four levels of precedence.
506 Options which define variables from the command-line override those
507 specified in the 'qirc' file, while variables defined in the recipe
508 override those specified in 'qirc', taking priority over those variables
509 set by command-line options.  Finally, the variables have default values
510 if they are not defined anywhere.
512    Options that set variables through the command-line can only
513 reference variables defined in 'qirc' and variables with default values.
515    Definitions of variables in 'qirc' can only reference variables
516 previously defined in 'qirc' and variables with default values.
518    Definitions of variables in the recipe can only reference variables
519 set by the command-line, variables previously defined in the recipe,
520 variables defined in 'qirc', and variables with default values.
522 5.2 Special variables
523 =====================
525 There are variables which can only be set using the command line options
526 or via 'qirc', there are other special variables which can be defined or
527 redefined in a recipe.  See the following definitions:
529    'outdir' is the directory where the packages produced are written.
530 This variable can not be redefined in the recipe.  Default sets to
531 '/var/cache/qi/packages'.
533    'worktree' is the working tree where archives, patches, and recipes
534 are expected.  This variable can not be redefined in the recipe.
535 Default sets to '/usr/src/qi'.
537    'tardir' is defined in the recipe to the directory where the tarball
538 containing the source can be found.  The full name of the tarball is
539 composed as '${tardir}/$tarname'.  Its value is available in the recipe
540 as '${tardir}'; a value of .  for 'tardir' sets it to the value of CWD
541 (Current Working Directory), this is where the recipe lives.
543    'arch' is the architecture to compose the package name.  Its value is
544 available in the recipe as '${arch}'.  Default value is the output of
545 'uname -m'.
547    'jobs' is the number of parallel jobs to pass to the compiler.  Its
548 value is available in the recipe as '${jobs}'.  The default value is 1.
550    The two variables '${srcdir}' and '${destdir}' can be set in the
551 recipe, as any other variable, but if they are not, qi uses default
552 values for them when building a package.
554    'srcdir' contains the source code to be compiled, and defaults to
555 '${program}-${version}'.  'destdir' is the place where the built package
556 will be installed, and defaults to '${TMPDIR}/package-${program}'.
558    If 'pkgname' is left undefined, the special variable 'program' is
559 assigned by default.  If 'pkgversion' is left undefined, the special
560 variable 'version' is assigned by default.
562    'pkgname' and 'pkgversion' along with: 'version', 'arch', and
563 'release' are used to produce the name of the package in the form:
564 '${pkgname}-${pkgversion}-${arch}+${release}.tlz'
566    A special variable called 'replace' can be used to declare package
567 names that will be replaced at the time of installation.
569 A typical recipe contains the following variables:
571    * 'program': software name.
573      It matches the source name.  It is also used to compose the name of
574      the package if '${pkgname}' is not specified.
576    * 'version': software version.
578      It matches the source name.  It is also used to compose the version
579      of the package if '${pkgversion}' is not specified.
581    * 'arch': software architecture.
583      It is used to compose the architecture of the package in which it
584      is build.
586    * 'release': release number.
588      This is used to reflect the release number of the package.  It is
589      recommended to increase this number after any significant change in
590      the recipe or post-install script.
592 Obtaining sources over the network must be declared in the recipe using
593 the 'fetch' variable.  Use double quotes for separated values.
595    The variables 'netget' and 'rsync' can be defined in 'qirc' to
596 establish a network downloader in order to get the sources.  If they are
597 not defined, qi uses default values:
599    'netget' is the general network downloader tool, defaults sets to
600 'wget -c -w1 -t3 --no-check-certificate'.
602    'rsync' is the network tool for sources containing the prefix for the
603 RSYNC protocol, default sets to 'rsync -v -a -L -z -i --progress'.
605    The variable 'description' is used to print the package description
606 when a package is installed.
608    A description has two parts: a brief description, and a long
609 description.  By convention, the syntax of 'description' is:
611      description="
612      Brief description.
614      Long description.
615      "
617    The first line of the value represented is a brief description of the
618 software (called "blurb").  A blank line separates the _brief
619 description_ from the _long description_, which should contain a more
620 descriptive description of the software.
622 An example looks like:
624      description="
625      The GNU core utilities.
627      The GNU core utilities are the basic file, shell and text manipulation
628      utilities of the GNU operating system.  These are the core utilities
629      which are expected to exist on every operating system.
630      "
632    Please consider a length limit of 78 characters as maximum, because
633 the same one would be used on the meta file creation.  See *note The
634 meta file: Recipes. section.
636    The 'homepage' variable is used to declare the main site or home
637 page:
639      homepage=http://www.gnu.org/software/gcc
641    The variable 'license' is used for license information(1).  Some code
642 in the program can be covered by license A, license B, or license C. For
643 "separate licensing" or "heterogeneous licensing", we suggest using *|*
644 for a disjunction, *&* for a conjunction (if that ever happens in a
645 significant way), and comma for heterogeneous licensing.  Comma would
646 have lower precedence, plus added special terms.
648      license="LGPL, GPL | Artistic + added permission"
650 5.3 Writing recipes
651 ===================
653 Originally, qi was designed for the version 3 of Dragora GNU/Linux (this
654 does not mean that you can't use it in another distribution, just that
655 if you do you will need to test it for your selves).  To aid this here
656 are some references to well written recipes:
658 <http://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes>.
659 <http://notabug.org/dragora/dragora/src/master/recipes>.
661    You can also check the "doc" directory in the distribution sources of
662 qi for some examples.
664 5.4 Building packages
665 =====================
667 A recipe is any valid regular file.  Qi sets priorities for reading a
668 recipe, the order in which qi looks for a recipe is:
670   1. Current working directory.
672   2. If the specified path name does not contain "recipe" as the last
673      component.  Qi will complete it by adding "recipe" to the path
674      name.
676   3. If the recipe is not in the current working directory, it will be
677      searched under '${worktree}/recipes'.  The last component will be
678      completed adding "recipe" to the specified path name.
680 To build a single package, type:
682      qi -b x-apps/xterm
684 Multiple jobs can be passed to the compiler to speed up the build
685 process:
687      qi -b -j3 x-apps/xterm
689 Update or install the package produced (if it is not already installed)
690 when finish:
692      qi -b -j3 -u x-apps/xterm
694 Only process a recipe but do not create the binary package:
696      qi -b -n dict/aspell
698    The options -i or -u have no effect when -n is given.
700 This can be useful to inspect the build process of recipe:
702    qi -b -k -n dict/aspell 2>&1 | tee aspell-buildlog.txt
704    The -k option could preserve the source directory and the destination
705 directory for later inspection.  A log file of the build process will be
706 created redirecting both, standard error and standard output to tee(1).
708 5.5 Variables from the environment
709 ==================================
711 Qi has environment variables which can be used at build time:
713    The variable 'TMPDIR' sets the temporary directory for sources, which
714 is used for package extractions (see *note Examining packages::) and is
715 prepended to the value of '${srcdir}' and '${destdir}' in build mode.
716 By convention its default value is equal to '/usr/src/qi/build'.
718    The variables 'QICFLAGS', 'QICXXFLAGS', and 'QILDFLAGS' have no
719 effect by default.  The environment variables such as 'CFLAGS',
720 'CXXFLAGS', and 'LDFLAGS' are unset at compile time:
722 Recommended practice is to set variables in the command line of
723 'configure' or _make(1)_ instead of exporting to the environment.  As
724 follows:
726      Variables not defined in a site shell script can be set in the
727      environment passed to configure.  However, some packages may run
728      configure again during the build, and the customized values of
729      these variables may be lost.  In order to avoid this problem, you
730      should set them in the configure command line, using 'VAR=value'.
731      For example:
733      './configure CC=/usr/local2/bin/gcc'
735      <http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html>
737      Indeed, while configure can notice the definition of CC in
738      './configure CC=bizarre-cc', it is impossible to notice it in
739      'CC=bizarre-cc ./configure', which, unfortunately, is what most
740      users do.
742      [...]
744      configure: error: changes in the environment can compromise the
745      build.
747      <http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html>
749      It is not wise for makefiles to depend for their functioning on
750      environment variables set up outside their control, since this
751      would cause different users to get different results from the same
752      makefile.  This is against the whole purpose of most makefiles.
754      <http://gnu.org/software/make/manual/make.html#Environment>
756 5.6 The meta file
757 =================
759 The "meta file" is a regular file created during the build mode, it
760 contains information about the package such as program name, program
761 version, release, fetch address, description, and other minor data
762 extracted from processed recipes.  The name of the file is generated as
763 '${full_pkgname}.tlz.txt', and its purpose is to reflect essential
764 information to the user without having to look inside the package
765 content.
767    The content of a meta file looks like:
769      #
770      # The Bourne Again SHell.
771      #
772      # Bash is an sh-compatible shell that incorporates useful features from
773      # the Korn shell (ksh) and C shell (csh).  It is intended to conform to
774      # the IEEE POSIX P1003.2/ISO 9945.2 shell and tools standard.
775      #
776      # It offers functional improvements over sh for both programming and
777      # interactive use.
778      #
780      QICFLAGS="-g0 -Os -mtune=generic -pipe"
781      QICXXFLAGS="-g0 -Os -mtune=generic -pipe"
782      QILDFLAGS="-s"
783      program=bash
784      version=5.0
785      release=1
786      blurb="The Bourne Again SHell."
787      homepage="http://www.gnu.org/software/bash"
788      license="GPLv3+"
789      fetch="ftp://ftp.gnu.org/gnu/bash/bash-5.0.tar.gz"
790      replace=""
792    Package descriptions are extracted from the variable 'description':
793 each line is interpreted literally and pre-formatted to fit in (exactly)
794 *80 columns*, plus the character '#' and a space is prefixed to every
795 line.
797 In addition to the Special variables, there are implicit variables such
798 as 'blurb':
800    The 'blurb' variable is related to the special variable
801 'description'.  Its value is composed using the first (substantial) line
802 of 'description', mentioned as the "brief description".
804    ---------- Footnotes ----------
806    (1) The proposal for 'license' was made by Richard M. Stallman at
807 <http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html>.
809 \x1f
810 File: qi.info,  Node: Order files,  Next: Creating packages,  Prev: Recipes,  Up: Top
812 6 Order files
813 *************
815 The order mode has the purpose of resolving the build order through
816 .order files.  An order file contains a list of recipe names, by default
817 does not perform any action other than to print a resolved list in
818 descending order.  For example, if *a* depends on *b* and *c*, and *c*
819 depends on *b* as well, the file might look like:
821      a: c b
822      b:
823      c: b
825    Each letter represents a recipe name, complete dependencies for the
826 first recipe name are listed in descending order, which is printed from
827 right to left, and removed from left to right:
829    OUTPUT
831      b
832      c
833      a
835    Blank lines, colons and parentheses are simply ignored.  Comment
836 lines beginning with '#' are allowed.
838 An order file could be used to build a series of packages, for example,
839 if the content is:
841      # Image handling libraries
843      libs/libjpeg-turbo: devel/nasm
844      x-libs/jasper: libs/libjpeg-turbo
845      libs/tiff: libs/libjpeg-turbo
847    To proceed with each recipe, we can type:
849      qi -o imglibs.order | qi -b -i -
851    The output of 'qi -o imglibs.order' tells to qi in which order it
852 should build the recipes:
854      devel/nasm
855      libs/libjpeg-turbo
856      x-libs/jasper
857      libs/tiff
859 \x1f
860 File: qi.info,  Node: Creating packages,  Next: Examining packages,  Prev: Order files,  Up: Top
862 7 Creating packages
863 *******************
865 The "creation mode" is an internal function of qi to make new Qi
866 compatible compatible packages, the creation mode is selected by the -c
867 option.  A package is produced using the contents of the Current
868 Directory, and the package file is written out.
870      Usage: qi -c [OUTPUT/PACKAGENAME.TLZ]...
872    The argument for the file name to be written must contain a fully
873 qualified named directory as the output directory where the package
874 produced will be written.  The file name should be composed using the
875 full name: name-version-architecture+release.tlz
877    EXAMPLE
879      cd /usr/local/pkgs
880      cd claws-mail-3.17.1-x86_64+1
881      qi -c /var/cache/qi/packages/x86_64/local/claws-mail-3.17.1-x86_64+1.tlz
883    In this case, the package "claws-mail-3.17.1-x86_64+1.tlz" will be
884 written into '/var/cache/qi/packages/x86_64/local/'.
886 All packages produced are complemented by a checksum file (.sha256).
888 \x1f
889 File: qi.info,  Node: Examining packages,  Next: Exit status,  Prev: Creating packages,  Up: Top
891 8 Examining packages
892 ********************
894 The "extraction mode" serves to examine binary packages for debugging
895 purposes.  The extraction mode is selected by the -x option.  It
896 decompresses a package into a single directory, verifying its integrity
897 and preserving its properties.
899      Usage: qi -x [PACKAGENAME.TLZ]...
901    EXAMPLE
903      qi -x mksh-R56c-x86_64+1.tlz
905    This action will put the content of "mksh-R56c-x86_64+1.tlz" into a
906 single directory, this will be a private directory for the user who
908    requested the action, creation mode will be equal to *u=rwx,g=,o=
909 (0700)*.  The package content will reside on this location, default mask
910 to deploy the content will be equal to *u=rwx,g=rwx,o=rwx (0000)*.
912 The creation of the custom directory is influenced by the value of the
913 'TMPDIR' variable.
915 \x1f
916 File: qi.info,  Node: Exit status,  Next: Index,  Prev: Examining packages,  Up: Top
918 9 Exit status
919 *************
921 All the exit codes are described in this chapter.
924      Successful completion (no errors).
927      Minor common errors:
929         - Help usage on illegal options or required arguments.
931         - Program needed by qi (prerequisite) is not available.
934      Command execution error:
936      This code is used to return the evaluation of external commands and
937      shell arguments in case of error.
940      Integrity check error for compressed files.
942      Compressed files means:
944         - Tarball files from tar(1).  Supported extensions: .tar,
945           .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz, .tar.xz, .txz
947         - Tarball files from tarlz(1).  Supported extensions: .tar.lz,
948           .tlz
950         - Zip files from unzip(1).  Supported extensions: .zip, .ZIP
952         - Gzip files from gzip(1).  Supported extensions: .gz, .Z
954         - Bzip2 files from bzip2(1).  Supported extensions: .bz2
956         - Lzip files from lzip(1).  Supported extensions: .lz
958         - Xz files from xz(1).  Supported extensions: .xz
961      File empty, not regular, or expected.
963      Commonly, it is expected:
965         - An argument for the mode of operation.
967         - A readable file or directory.
969         - A binary package (.tlz).
971         - A valid recipe.
973         - An order file (.order).
975         - A protocol supported by the network downloader tool.
977         - A checksum file (.sha256).
980      Empty or not defined variable:
982      This code is used to report empty or undefined variables; usually,
983      variables coming from a recipe or assigned arrays that are tested.
986      Package already installed:
988      The package directory for an incoming .tlz package already exists.
990 '10'
991      Network manager error:
993      This code is used if the network downloader tool fails for some
994      reason.
996 \x1f
997 File: qi.info,  Node: Index,  Prev: Exit status,  Up: Top
999 Index
1000 *****
1002 \0\b[index\0\b]
1003 * Menu:
1005 * configuration file:                    The qirc file.       (line   6)
1006 * environment variables:                 Recipes.             (line 244)
1007 * exit codes:                            Exit status.         (line   6)
1008 * handling build order:                  Order files.         (line   6)
1009 * introduction:                          Introduction.        (line   6)
1010 * invocation:                            Invoking qi.         (line   6)
1011 * managing packages:                     Packages.            (line   6)
1012 * package blacklist:                     Packages.            (line 176)
1013 * package build:                         Recipes.             (line 200)
1014 * package conflicts:                     Packages.            (line  30)
1015 * package creation:                      Creating packages.   (line   6)
1016 * package de-installation:               Packages.            (line 104)
1017 * package examination:                   Examining packages.  (line   6)
1018 * package installation:                  Packages.            (line  55)
1019 * package upgrade:                       Packages.            (line 143)
1020 * recipes:                               Recipes.             (line   6)
1021 * special variables:                     Recipes.             (line  58)
1022 * the meta file:                         Recipes.             (line 292)
1023 * variables:                             Recipes.             (line  29)
1024 * writing recipes:                       Recipes.             (line 186)
1027 \x1f
1028 Tag Table:
1029 Node: Top\x7f798
1030 Node: Introduction\x7f1573
1031 Node: Invoking qi\x7f2742
1032 Node: The qirc file\x7f6160
1033 Node: Packages\x7f7237
1034 Ref: Packages-Footnote-1\x7f14273
1035 Node: Recipes\x7f14386
1036 Ref: Recipes-Footnote-1\x7f27147
1037 Node: Order files\x7f27292
1038 Node: Creating packages\x7f28594
1039 Node: Examining packages\x7f29634
1040 Node: Exit status\x7f30544
1041 Node: Index\x7f32482
1042 \x1f
1043 End Tag Table
1045 \x1f
1046 Local Variables:
1047 coding: iso-8859-1
1048 End: