1 \input texinfo @c -*-texinfo-*-
3 @comment %**start of header
5 @settitle Qi user guide
6 @documentencoding ISO-8859-1
8 @comment %**end of header
11 @set UPDATED 1 April 2019
14 This user guide is for Qi (version @value{VERSION},
15 @value{UPDATED}), which is a simple but well-integrated package manager.
17 Copyright @copyright{} 2019 Matias Andres Fonzo, Santiago del Estero,
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.3 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
25 Texts. A copy of the license is included in the section entitled
26 ``GNU Free Documentation License''.
30 @dircategory Package management
32 * Qi: (qi). A user-friendly package manager.
38 @subtitle for version @value{VERSION}, @value{UPDATED}
39 @author Matias Fonzo (@email{selk@@dragora.org})
42 @vskip 0pt plus 1filll
52 This user guide is for Qi (version @value{VERSION},
57 * Introduction:: Description and features of qi
58 * Invoking qi:: Command-line options
59 * The qirc file:: Configuration file
60 * Packages:: Managing packages
61 * Recipes:: Building packages
62 * Order files:: Handling build order
63 * Creating packages:: Making Qi packages
64 * Examining packages:: Debugging purposes
65 * Exit status:: Exit codes
66 * License:: GNU Free Documentation License
71 Copyright (C) 2019 Matias Fonzo.
73 Qi's home page can be found at @uref{http://www.dragora.org}.
74 @w{Send bug reports or suggestions to @email{dragora-users@@nongnu.org}.}
80 Qi is a simple but well-integrated package manager. It can creates,
81 install, remove, and upgrade software packages. Qi produces binary
82 packages using recipe names, these are files containing specific
83 instructions to build every source. Qi can manage multiple packages
84 under a single directory hierarchy, this method allows to maintain a set
85 of packages and multiple versions of them. This means that Qi could be
86 used as the main package manager or complement the existing one.
88 Qi offers a friendly command line interface, a global configuration file,
89 a simple recipe layout to deploy software packages; also works with binary
90 packages in parallel, speeding up installations and packages in
91 production. The used format for packages is a simplified but safe POSIX
92 pax archive compressed with lzip.
94 Qi is a modern (POSIX-compliant) shell script released under the terms of
95 the GNU General Public License. There are only two major dependencies for
96 the magic: graft(1) and tarlz(1), the rest is expected to be found in any
103 This chapter describes the synopsis and command line options for
107 Usage: qi [@var{OPTION}]... [@var{FILE}]...
111 One mandatory option specifies the operation that @samp{qi} should
112 perform, other options are meant to detail how this operation should be
116 qi supports the following options to operate:
120 Build package using recipe names.
123 Create .tlz package from directory.
132 Resolve build order through .order files.
135 Update packages (implies -i, -d and -p options).
138 Warn about files that will be linked.
141 Extract a package for debugging purposes.
145 There are common options between modes:
149 Do not read the configuration file.
151 This will omit any value on the qirc file.
154 Package directory for installations.
156 This option sets @samp{$@{packagedir@}}.
158 Only valid for -i, -d, or -u options.
163 This option can force the build of a recipe, or force the update of a
164 pre-existing package.
166 Only valid for -b, -u options.
169 Target directory for symbolic links.
171 This option sets @samp{$@{targetdir@}}.
173 Only valid for -i, -d, or -u options.
176 Keep (don't delete) @samp{$@{srcdir@}} or @samp{$@{destdir@}} on build
177 mode, keep (don't delete) package directory on delete mode.
179 Only valid for -b, -d or -u options.
182 Prune conflicts on package installations.
184 This option may proceed with the package installation if one or more
188 Use the fully qualified named directory as the root directory for all qi
189 operations. The target directory and package directory will be relative
190 to the specified directory, including the log file for graft.
193 Be verbose (a 2nd -v gives more).
197 Options for build mode (-b):
201 Where the produced packages are written.
203 This option sets @samp{$@{outdir@}}.
206 Where archives, patches, and recipes are expected.
208 This option sets @samp{$@{worktree@}}.
211 Where (compressed) sources will be found.
213 This option sets @samp{$@{tardir@}}.
218 Default value is obtained via uname(1) as @samp{uname -m}.
221 Parallel jobs for the compiler.
223 If not specified, default sets to 1.
226 Increment release number (@samp{$@{release@}} + 1).
228 It will be omitted if the -n option is being used.
231 Don't create a .tlz package.
234 Selects the option to skip completed recipes.
236 This means, in interactive mode, when the dialog
237 to summarize recipes is showed.
245 Print default directory locations.
247 This will print the target directory, package directory, working tree,
248 the directory for tarballs, and the output directory for produced
252 Display the help describing the options and then exit.
255 Print the version number and license information.
256 The version number should be included in all bug reports.
260 Expected arguments beyond of options are package directories and regular
261 files: recipes or files ending in .tlz, .order. When FILE is -, qi can
262 read from the standard input. See examples in @ref{Packages}.
266 @chapter The qirc file
267 @cindex configuration file
269 The global @file{qirc} file offers a way to define variables and tools
270 (such as a download manager) for default use. This file is used by qi
271 at runtime for e.g to build, install, remove or upgrade packages.
274 It has the following rules:
277 @item Variables must be declared as @samp{name=value}.
279 @item Declaration of values should only take one line, no line break.
281 @item For security reasons, assignments like @samp{name=$var} are only
282 interpreted as literal.
286 The command line options related to the package directory and target
287 directory plus some of the options used for the build mode can override
288 some values in @file{qirc}. See @ref{Invoking qi}.
291 The order in which qi looks for this file is:
295 @env{$@{HOME@}/.qirc}
299 @samp{$@{sysconfdir@}/qirc}
303 If you intend to run qi as effective user, the file
304 @samp{$@{sysconfdir@}/qirc} could be copied to @env{$@{HOME@}/.qirc}
305 setting the paths for @samp{$@{packagedir@}} and @samp{$@{targetdir@}}
306 according to the @env{$HOME}.
311 @cindex managing packages
313 A package is a suite of programs usually distributed in binary form
314 which may also contain manual pages, documentation, or any other file
315 associated to a specific software.
317 The package format used by qi is a simplified POSIX pax archive
318 compressed with lzip. The file extension for packages ends in .tlz
321 Both package installation and package de-installation are managed using
322 two important (internal) variables: @samp{$@{packagedir@}} and
323 @samp{$@{targetdir@}}, these values can be changed in the
324 configuration file or via options.
326 @samp{$@{packagedir@}} is a common directory tree where the package
327 contents will be decompressed (will reside).
329 @samp{$@{targetdir@}} is a target directory where the links will be
330 made by graft(1) taking @samp{$@{packagedir@}/package_name} into account.
333 Packages are installed in self-contained directory trees and symbolic
334 links from a common area are made to the package files. This allows
335 multiple versions of the same package to co-exist on the one system.
337 @section Package conflicts
338 @cindex package conflicts
340 All the links to install or remove a package are handled by graft(1).
341 Since multiple packages can be installed or removed at the same time,
342 certain conflicts may arise between the packages.
345 graft@footnote{The official guide for Graft can be found at
346 @url{http://peters.gormand.com.au/Home/tools/graft/graft.html}.}
347 defines a CONFLICT as one of the following conditions:
351 If the package object is a directory and the target object exists but is
355 If the package object is not a directory and the target object exists
356 and is not a symbolic link.
359 If the package object is not a directory and the target object exists
360 and is a symbolic link to something other than the package object.
364 The default behavior of qi for an incoming package is to ABORT if a
365 conflict arises. When a package is going to be deleted, qi tells to
366 graft(1) to remove those parts that are not in conflict, leaving the
367 links to the belonging package. This behavior can be forced if the
370 @section Installing packages
371 @cindex package installation
373 To install a single package, simply type:
376 qi -i coreutils-8.30-i586+1.tlz
380 To install multiple packages at once, type:
383 qi -i gcc-8.3.0-i586+1.tlz rafaela-2.2-i586+1.tlz ...
387 Warn about the files that will be linked:
390 qi -w bash-5.0-i586+1.tlz
393 This is to verify the content of a package before installing it.
396 See the process of an installation (very verbose):
399 qi -i -v mariana-3.0-i586+1.tlz
402 A second -v gives more.
405 Installing package in a different location:
408 qi -r /media/floppy -i lzip-1.21-i586+1.tlz
411 The -r option assumes @samp{$@{targetdir@}} and @samp{$@{packagedir@}}.
415 qi -r /home/selk -P /pkgs -t / -i lzip-1.21-i586+1.tlz
418 In this case the content of "lzip-1.21-i586+1.tlz" will be decompressed
419 into @samp{/home/selk/pkgs/lzip-1.21-i586+1}. Assuming that the main
420 binary for lzip is under @samp{/home/selk/pkgs/lzip-1.21-i586+1/usr/bin/}
421 the target for "usr/bin" will be created at @samp{/home/selk}. Considering
422 that you have exported the @env{PATH} as @samp{$@{HOME@}/usr/bin}, now the
423 system is able to see the recent lzip.
426 Installing from a list of packages using standard input:
429 cat FILELIST.txt | qi -i -
432 The list of packages must contain full path names to be passed in the
434 /var/cache/qi/packages/x86_64/devel/tcl-8.6.9-x86_64+1.tlz
435 /var/cache/qi/packages/x86_64/devel/tk-8.6.9.1-x86_64+1.tlz
436 /var/cache/qi/packages/x86_64/devel/vala-0.42.3-x86_64+1.tlz
438 @section Removing packages
439 @cindex package de-installation
441 To remove a package, simply type:
444 qi -d xz-5.2.4-i586+1.tlz
448 Delete mode will match the package name using @samp{$@{packagedir@}} as
449 prefix. For example, if the value of @samp{$@{packagedir@}} is set to
450 /usr/local/pkgs, this will be equal to:
453 qi -d /usr/local/pkgs/xz-5.2.4-i586+1
457 Detailed output (very verbose):
460 qi -d -v /usr/local/pkgs/xz-5.2.4-i586+1
463 A second -v gives more.
466 By default the delete mode does not preserve a package directory after
467 removing its links from @samp{$@{targetdir@}}, but this behavior can be
468 changed if the -k option is passed:
471 qi -d -k /usr/local/pkgs/lzip-1.21-i586+1
474 This means that the links to the package can be reactivated, later:
477 cd /usr/local/pkgs && graft -i lzip-1.21-i586+1
481 Removing package from a different location:
484 qi -r /home/cthulhu -P /pkgs -t / -d xz-5.2.4-i586+1
488 Removing a package using standard input:
491 echo "vala-0.42.3-x86_64+1" | qi -d -
494 This will match with the package directory.
496 @section Upgrading packages
497 @cindex package upgrade
499 The upgrade mode inherits the properties of the installation and removal
500 process. To make sure that a package is updated, the package is installed
501 in a temporary directory taking @samp{$@{packagedir@}} into account. Once
502 the incoming package is pre-installed, qi can proceed to search and delete
503 packages that have the same name (considered as previous ones). Finally,
504 the package is re-installed at its final location and the temporary
505 directory is removed.
508 To upgrade a package, just type:
511 qi -u gcc-9.0.1-i586+1.tlz
514 This will proceed to update "gcc-9.0.1-i586+1" removing other versions
518 If you want to keep the package directory of found versions during the
519 upgrade process, just pass:
522 qi -u -k gcc-9.0.1-i586+1.tlz
526 To see the upgrade process (very verbose):
529 qi -u -v gcc-9.0.1-i586+1.tlz
532 A second -v gives more.
535 To force the upgrade of an existing package:
538 qi -u -f gcc-9.0.1-i586+1.tlz
541 @subsection Package blacklist
542 @cindex package blacklist
544 To enforce general package facilities, either to install, remove or
545 maintain the hierarchy of packages in a clean manner, qi makes use of the
546 pruning operation via graft(1):
548 There is a risk if those are crucial packages for the proper functioning
549 of the system, because it implies to deactivate symbolic links from the
550 target directory, @emph{especially} when transitioning an incoming package
551 into its final location during upgrade.
554 A blacklist for declare package names has been devised for this cases,
555 in case that a user decides to upgrade all packages in the system or,
556 just the crucial ones, such as the C library.
558 The blacklist is related to the upgrade mode only, consists in installing
559 a package instead of updating it or removing previous versions of it;
560 the content of the package will be updated over the existing content at
561 @samp{$@{packagedir@}}, while the existing links from
562 @samp{$@{targetdir@}} will be preserved. A pruning of links will carried
563 out in order to re-link possible differences with the recent content, this
564 helps to avoid having dead links in the target directory.
567 Since the upgrade mode is also used to install a new package, the mechanism
568 for blacklist is to install a declared package if it does not already
569 exist, if it already exists, it is verified that the binary package is
570 newer than the package directory in order to perform an update.
572 Package names for the blacklist can be set from the configuration file.
579 A recipe is a file telling qi what to do. Most often, the recipe tells to
580 qi how to build a binary package from a source tarball.
582 A recipe has two parts: a list of variable definitions and a list of
583 sections. By convention, the syntax of a section is:
592 The section name is followed by parentheses, one newline and an opening
593 brace. The line finishing the section contains just a closing brace.
594 The section names or the function names currently recognized are
597 The @samp{build} section is an augmented shell script. This is the main
598 section (or @strong{shell function}) which contains the instructions to
599 build and produce a package.
604 A "variable" is a @strong{shell variable} defined either in @file{qirc}
605 or in a recipe to represent a string of text, called the variable's
606 "value". These values are substituted by explicit request in the
607 definitions of other variables or in calls to external commands.
609 Variables can represent lists of file names, options to pass to
610 compilers, programs to run, directories to look in for source files,
611 directories to write output in, or anything else you can imagine.
613 Definitions of variables in qi have four levels of precedence.
614 Options which define variables from the command-line override those
615 specified in the @file{qirc} file, while variables defined in the recipe
616 override those specified in @file{qirc}, taking priority over those
617 variables settled by options via command-line. Finally, the variables
618 have default values if they are not defined anywhere.
620 Options that set variables through the command-line can only reference
621 variables defined in @file{qirc} and variables with default values.
623 Definitions of variables in @file{qirc} can only reference variables
624 previously defined in @file{qirc} and variables with default values.
626 Definitions of variables in the recipe can only reference variables
627 settled by command-line, variables previously defined in the recipe,
628 variables defined in @file{qirc}, and variables with default values.
630 @section Special variables
631 @cindex special variables
633 There are variables which can only be set using the command line options or
634 via @file{qirc}, there are other special variables which can be defined or
635 redefined in a recipe. See the following definitions:
637 @samp{outdir} is the directory where the produced packages are written.
638 This variable can not be redefined in the recipe. Default sets to
639 @samp{/var/cache/qi/packages}.
641 @samp{worktree} is the working tree where archives, patches, and recipes
642 are expected. This variable can not be redefined in the recipe. Default
643 sets to @samp{/usr/src/qi}.
645 @samp{tardir} is defined in the recipe to the directory where the tarball
646 containing the source can be found. The full name of the tarball is
647 composed as @samp{$@{tardir@}/$tarname}. Its value is available in the
648 recipe as @samp{$@{tardir@}}; a value of . for @samp{tardir} sets it to
649 the value of CWD (Current Working Directory), this is where the recipe
652 @samp{arch} is the architecture to compose the package name. Its value is
653 available in the recipe as @samp{$@{arch@}}. Default value is the output
656 @samp{jobs} is the number of parallel jobs to pass to the compiler. Its
657 value is available in the recipe as @samp{$@{jobs@}}. Default sets to
660 The two variables @samp{$@{srcdir@}} and @samp{$@{destdir@}} can be
661 set in the recipe, as any other variable, but if they are not, qi uses
662 default values for them when building a package.
664 @samp{srcdir} contains the source code to be compiled, and defaults to
665 @samp{$@{program@}-$@{version@}}. @samp{destdir} is the place where the
666 built package will be installed, and defaults to
667 @samp{$@{TMPDIR@}/package-$@{program@}}.
669 If @samp{pkgname} is left undefined, the special variable @samp{program}
670 is assigned by default. If @samp{pkgversion} is left undefined, the
671 special variable @samp{version} is assigned by default.
673 @samp{pkgname} and @samp{pkgversion} along with: @samp{version}, @samp{arch},
674 and @samp{release} are used to produce the name of the package in the form:
675 @samp{$@{pkgname@}-$@{pkgversion@}-$@{arch@}+$@{release@}.tlz}
677 A special variable called @samp{replace} can be used to declare package
678 names that will be replaced at the time of installation.
681 A typical recipe contains the following variables:
684 @item @samp{program}: software name.
686 It matches the source name. It is also used to compose the name of the
687 package if @samp{$@{pkgname@}} is not specified.
689 @item @samp{version}: software version.
691 It matches the source name. It is also used to compose the version of the
692 package if @samp{$@{pkgversion@}} is not specified.
694 @item @samp{arch}: software architecture.
696 It is used to compose the architecture of the package in which it is
699 @item @samp{release}: release number.
701 This is used to reflect the release number of the package. It is
702 recommended to increase this number after any significant change in
703 the recipe or post-install script.
707 Obtaining sources over the network must be declared in the recipe using
708 the @samp{fetch} variable. Use double quotes for separated values.
710 The variables @samp{netget} and @samp{rsync} can be defined in @file{qirc}
711 to establish a network downloader in order to get the sources. If they
712 are not defined, qi uses default values:
714 @samp{netget} is the general network downloader tool, defaults sets to
715 @samp{wget -c -w1 -t3 --no-check-certificate}.
717 @samp{rsync} is the network tool for sources containing the prefix for
718 the RSYNC protocol, default sets to
719 @samp{rsync -v -a -L -z -i --progress}.
721 The variable @samp{description} is used to print the package description
722 when a package is installed.
724 A description has two parts: a brief description, and a long description.
725 By convention, the syntax of @samp{description} is:
735 The first (substantial) line of the value is a brief description of the
736 software (called "blurb"). A newline follows to separate the @emph{brief
737 description} from the @emph{long description}.
740 An example looks like:
744 The GNU core utilities.
746 The GNU core utilities are the basic file, shell and text manipulation
747 utilities of the GNU operating system. These are the core utilities
748 which are expected to exist on every operating system.
752 Please consider a length limit of 78 characters as maximum, because the same
753 one would be used on the meta file creation. See
754 @ref{Recipes, The meta file} section.
756 The @samp{homepage} variable is used to declare the main site or home page:
759 homepage=http://www.gnu.org/software/gcc
762 The variable @samp{license} is used for license information@footnote{
763 The proposal for @samp{license} was made by Richard M. Stallman at
764 @url{http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html}.}.
765 Some code in the program can be covered by license A, license B, or
766 license C. For "separate licensing" or "heterogeneous licensing", we
767 suggest using @strong{|} for a disjunction, @strong{&} for a conjunction
768 (if that ever happens in a significant way), and comma for heterogeneous
769 licensing. Comma would have lower precedence, plus added special terms.
772 license="LGPL, GPL | Artistic + added permission"
775 @section Building packages
776 @cindex package build
778 A recipe is any valid regular file, qi sets priorities to read a recipe,
779 for example, the Current Working Directory has priority over the working
780 tree (or where the recipes reside); the @samp{$@{worktree@}/recipes} is
781 the second place where to find a recipe, we complete the possibility of
782 using the directory name to invoke a recipe if it contains "recipe" as a
786 To build a single package, type:
793 Multiple jobs can be passed to the compiler for speed up the build process:
796 qi -b -j3 x-apps/xterm
800 Update or install the produced package (if it is not already installed)
804 qi -b -j3 -u x-apps/xterm
808 Only process a recipe but do not create the binary package:
814 The options -i or -u have no effect when -n is given.
817 This can be useful to inspect the build process of recipe:
819 qi -b -k -n dict/aspell 2>&1 | tee aspell-buildlog.txt
821 The -k option could preserve the source directory and the destination
822 directory for later inspection. A log file of the build process will be
823 created redirecting both, standard error and standard output to tee(1).
825 @section Variables from the environment
826 @cindex environment variables
828 Qi has environment variables which can be used at build time:
830 The variable @env{TMPDIR} sets the temporary directory for sources, which is
831 used for package extractions (see @ref{Examining packages}) and to prepend
832 the value of @samp{$@{srcdir@}} and @samp{$@{destdir@}} on build mode. By
833 convention its default value is equal to @samp{/usr/src/qi/build}.
835 The variables @env{QICFLAGS}, @env{QICXXFLAGS}, and @env{QILDFLAGS} have
836 no effect by default. The environment variables such as @env{CFLAGS},
837 @env{CXXFLAGS}, and @env{LDFLAGS} are unset at compile time:
840 Recommended practices is to set variables in front of @samp{configure}
841 or in front of @emph{make(1)} instead of exporting to the environment.
845 Variables not defined in a site shell script can be set in the environment
846 passed to configure. However, some packages may run configure again
847 during the build, and the customized values of these variables may be
848 lost. In order to avoid this problem, you should set them in the
849 configure command line, using @samp{VAR=value}. For example:
851 @code{./configure CC=/usr/local2/bin/gcc}
853 @url{http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html}
857 Indeed, while configure can notice the definition of CC in
858 @samp{./configure CC=bizarre-cc}, it is impossible to notice it in
859 @samp{CC=bizarre-cc ./configure}, which, unfortunately, is what most
864 configure: error: changes in the environment can compromise the build.
866 @url{http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html}
870 It is not wise for makefiles to depend for their functioning on
871 environment variables set up outside their control, since this would cause
872 different users to get different results from the same makefile. This is
873 against the whole purpose of most makefiles.
875 @url{http://gnu.org/software/make/manual/make.html#Environment}
878 @section The meta file
879 @cindex the meta file
881 The "meta file" is a regular file created during the build mode, it
882 contains information about the package such as program name, program
883 version, release, fetch address, description, and other minor data
884 extracted from processed recipes. The name of the file is generated as
885 @samp{$@{full_pkgname@}.tlz.txt}, it has the purpose to reflect essential
886 information to the user without having to look inside the package content.
888 The content of a meta file looks like:
892 # The Bourne Again SHell.
894 # Bash is an sh-compatible shell that incorporates useful features from
895 # the Korn shell (ksh) and C shell (csh). It is intended to conform to
896 # the IEEE POSIX P1003.2/ISO 9945.2 shell and tools standard.
898 # It offers functional improvements over sh for both programming and
902 QICFLAGS="-g0 -Os -mtune=generic -pipe"
903 QICXXFLAGS="-g0 -Os -mtune=generic -pipe"
908 blurb="The Bourne Again SHell."
909 homepage="http://www.gnu.org/software/bash"
911 fetch="ftp://ftp.gnu.org/gnu/bash/bash-5.0.tar.gz"
915 Package descriptions are extracted from the variable @samp{description}:
916 each line is interpreted literally and pre-formatted to fit in (exactly)
917 @strong{80 columns}, plus the character @samp{#} and a space is prefixed
921 In addition to the Special variables, there are implicit variables such as
924 The @samp{blurb} variable is related to the special variable
925 @samp{description}. Its value is composed using the first (substantial)
926 line of @samp{description}, mentioned as the "brief description".
931 @cindex handling build order
933 The order mode has the purpose to resolve the build order through
934 .order files. An order file contains a list of recipe names, by default
935 does not perform any action other than to print a resolved list in
936 descending order. For example, if @strong{a} depends on @strong{b} and
937 @strong{c}, and @strong{c} depends on @strong{b} as well, the file might
946 Each letter represents a recipe name, complete dependencies for
947 the first recipe name are listed in descending order, which is
948 printed from right to left, and removed from left to right:
958 Declaration of blank lines, colons, parentheses, and end of line are
959 simply ignored. Comments are allowed for lines that begin with @samp{#}.
962 An order file could be used to build a serie of packages, for example, if
966 # Image handling libraries
968 libs/libjpeg-turbo: devel/nasm
969 x-libs/jasper: libs/libjpeg-turbo
970 libs/tiff: libs/libjpeg-turbo
973 To proceed with each recipe, we can type:
976 qi -o imglibs.order | qi -b -i -
979 The output of @samp{qi -o imglibs.order} tells to qi in which order it
980 should build the recipes:
990 @node Creating packages
991 @chapter Creating packages
992 @cindex package creation
994 The "creation mode" is an internal function of qi to make new Qi compatible
995 packages, the creation mode is available through the -c option. A package
996 is produced using the contents of the Current Directory, finally the
997 package is written out to the file name.
1000 Usage: qi -c [@var{OUTPUT/packagename.tlz}]...
1003 The argument for the file name to be written must contain a fully
1004 qualified named directory as the output directory where the produced
1005 package will be written. The file name should be composed using the
1006 full name: name-version-architecture+release.tlz
1012 cd claws-mail-3.17.1-x86_64+1
1013 qi -c /var/cache/qi/packages/x86_64/local/claws-mail-3.17.1-x86_64+1.tlz
1016 In this case, the package "claws-mail-3.17.1-x86_64+1.tlz" will be written
1017 into @samp{/var/cache/qi/packages/x86_64/local/}.
1020 All produced packages are complemented by a checksum file (.sha256).
1023 @node Examining packages
1024 @chapter Examining packages
1025 @cindex package examination
1027 There is an option to make use of the "extraction mode" which serves to
1028 examine binary packages for debugging purposes. The extraction mode
1029 consists of decompressing a package into a single directory, verifying
1030 its integrity and preserving its properties.
1033 qi -x mksh-R56c-x86_64+1.tlz
1036 This action will put the content of "mksh-R56c-x86_64+1.tlz" into a
1037 single directory, which is a private directory for the user who requested
1038 the action, creation mode will be equal to @strong{u=,g=rwx,o=rwx (0700)}.
1039 The package content will reside on this location, default mask to deploy
1040 the content will be equal to @strong{u=rwx,g=rwx,o=rwx (0000)}.
1043 The creation of the custom directory is influenced by the value of the
1044 @env{TMPDIR} variable.
1048 @chapter Exit status
1051 All the conditions of exit codes are described in this chapter.
1055 Successful completion (no errors).
1058 Minor common errors:
1061 @item Help usage on illegal options or required arguments.
1063 @item Program needed by qi (prerequisite) is not available.
1067 Command execution error:
1069 This code is used to return the evaluation of external commands and shell
1070 arguments in case of error.
1073 Integrity check error for compressed files.
1075 Compressed files means:
1078 @item Tarball files from tar(1).
1079 Supported extensions: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
1082 @item Tarballs files from tarlz(1).
1083 Supported extensions: .tar.lz, .tlz
1085 @item Zip files from unzip(1).
1086 Supported extensions: .zip, .ZIP
1088 @item Gzip files from gzip(1).
1089 Supported extensions: .gz, .Z
1091 @item Bzip2 files from bzip2(1).
1092 Supported extensions: .bz2
1094 @item Lzip files from lzip(1).
1095 Supported extensions: .lz
1097 @item Xz files from xz(1).
1098 Supported extensions: .xz
1102 File empty, not regular, or expected.
1104 Commonly, it is expected:
1107 @item An argument for the mode of operation.
1109 @item A readable file or directory.
1111 @item A binary package (.tlz).
1113 @item A valid recipe.
1115 @item An order file (.order).
1117 @item A protocol supported by the network downloader tool.
1119 @item A checksum file (.sha256).
1123 Empty or not defined variable:
1125 This code is used to report empty or undefined variables; usually,
1126 variables coming from a recipe or assigned arrays that are tested.
1129 Package already installed:
1131 The package directory for an incoming .tlz package that already exists.
1134 Network manager error:
1136 This code is used if the network downloader tool fails for some reason.
1141 @appendix GNU Free Documentation License