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 20 Apr 2020
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-2020 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
70 Copyright (C) 2019-2020 Matias Fonzo.
72 Qi's home page can be found at @uref{https://www.dragora.org}.
73 @w{Send bug reports or suggestions to @email{dragora-users@@nongnu.org}.}
79 Qi is a simple but well-integrated package manager. It can create,
80 install, remove, and upgrade software packages. Qi produces binary
81 packages using recipes, which are files containing specific instructions
82 to build each package from source. Qi can manage multiple packages
83 under a single directory hierarchy. This method allows to maintain a set
84 of packages and multiple versions of them. This means that Qi could be
85 used as the main package manager or complement the existing one.
87 Qi offers a friendly command line interface, a global configuration
88 file, a simple recipe layout to deploy software packages; also works
89 with binary packages in parallel, speeding up installations and packages
90 in production. The format used for packages is a simplified but safe
91 POSIX pax archive compressed with lzip.
93 Qi is a modern (POSIX-compliant) shell script released under the
94 terms of the GNU General Public License. There are only two major
95 dependencies for the magic: graft(1) and tarlz(1), the rest is expected
96 to be found in any Unix-like system.
102 This chapter describes the synopsis and command line options for
106 Usage: qi [@var{OPTION}]... [@var{FILE}]...
110 One mandatory option specifies the operation that @samp{qi} should
111 perform, other options are meant to detail how this operation should be
115 qi supports the following options to operate:
119 Build package using recipe names.
122 Create .tlz package from directory.
131 Resolve build order through .order files.
134 Upgrade packages (implies -i, -d and -p options).
137 Warn about files that will be linked.
140 Extract a package for debugging purposes.
144 There are common options between modes:
148 Do not read the configuration file.
150 This will ignore any value in the qirc file.
153 Package directory for installations.
155 This option sets @samp{$@{packagedir@}}.
157 Only valid for -i, -d, or -u options.
162 This option can force the build of a recipe, or force the upgrade of a
163 pre-existing package.
165 Only valid for -b, -u options.
168 Target directory for symbolic links.
170 This option sets @samp{$@{targetdir@}}.
172 Only valid for -i, -d, or -u options.
175 Keep (don't delete) @samp{$@{srcdir@}} or @samp{$@{destdir@}} in build
176 mode, keep (don't delete) package directory in delete mode.
178 Only valid for -b, -d or -u options.
181 Prune conflicts on package installations.
183 This option may proceed with the package installation if one or more
187 Use the fully qualified named directory as the root directory for all qi
188 operations. The target directory and package directory will be relative
189 to the specified directory, including the log file for graft.
192 Be verbose (a 2nd -v gives more).
196 Options for build mode (-b):
200 Where the packages produced are written.
202 This option sets @samp{$@{outdir@}}.
205 Where archives, patches, and recipes are expected.
207 This option sets @samp{$@{worktree@}}.
210 Where (compressed) sources will be found.
212 This option sets @samp{$@{tardir@}}.
217 Default value is obtained via uname(1) as @samp{uname -m}.
220 Parallel jobs for the compiler.
222 If not specified, default sets to 1.
225 Increment release number (@samp{$@{release@}} + 1).
227 It will be omitted if the -n option is being used.
230 Don't create a .tlz package.
233 Selects the option to skip completed recipes.
235 This means, in interactive mode, when the dialog to
236 summarize recipes is shown.
244 Print default directory locations.
246 This will print the target directory, package directory, working tree,
247 the directory for tarballs, and the output directory for the packages
251 Display the help describing the options and then exit.
254 Print the version number and license information.
255 The version number should be included in all bug reports.
259 Expected non-option arguments are package directories and regular files:
260 recipes or files ending in .tlz, .order.
262 When FILE is -, qi can read from the standard input. See examples at
267 @chapter The qirc file
268 @cindex configuration file
270 The global @file{qirc} file offers a way to define variables and tools
271 (such as a download manager) for default use. This file is used by qi
272 at runtime, e.g., to build, install, remove or upgrade packages.
274 Variables and their possible values must be declared as any other
275 variable in the shell.
278 The command line options related to the package directory and target
279 directory and some of the command line options used for the build mode,
280 have the power to override the values declared on @file{qirc}.
281 See @ref{Invoking qi}.
284 The order in which qi looks for this file is:
288 @env{$@{HOME@}/.qirc}
292 @samp{$@{sysconfdir@}/qirc}
296 If you intend to run qi as effective user, the file
297 @samp{$@{sysconfdir@}/qirc} could be copied to @env{$@{HOME@}/.qirc}
298 setting the paths for @samp{$@{packagedir@}} and @samp{$@{targetdir@}}
299 according to the @env{$HOME}.
304 @cindex managing packages
306 A package is a suite of programs usually distributed in binary form
307 which may also contain manual pages, documentation, or any other file
308 associated to a specific software.
310 The package format used by qi is a simplified POSIX pax archive
311 compressed with lzip. The file extension for packages is @samp{.tlz}.
314 Both package installation and package de-installation are managed using
315 two important (internal) variables: @samp{$@{packagedir@}} and
316 @samp{$@{targetdir@}}, these values can be changed in the
317 configuration file or via options.
319 @samp{$@{packagedir@}} is a common directory tree where the package
320 contents will be decompressed (will reside).
322 @samp{$@{targetdir@}} is a target directory where the links will be
323 made by graft(1) taking @samp{$@{packagedir@}/package_name} into account.
326 Packages are installed in self-contained directory trees and symbolic
327 links from a common area are made to the package files. This allows
328 multiple versions of the same package to coexist on the same system.
330 @section Package conflicts
331 @cindex package conflicts
333 All the links to install or remove a package are handled by graft(1).
334 Since multiple packages can be installed or removed at the same time,
335 certain conflicts may arise between the packages.
338 graft@footnote{The official guide for Graft can be found at
339 @url{http://peters.gormand.com.au/Home/tools/graft/graft.html}.}
340 defines a CONFLICT as one of the following conditions:
344 If the package object is a directory and the target object exists but is
348 If the package object is not a directory and the target object exists
349 and is not a symbolic link.
352 If the package object is not a directory and the target object exists
353 and is a symbolic link to something other than the package object.
357 The default behavior of qi for an incoming package is to ABORT if a
358 conflict arises. When a package is going to be deleted, qi tells to
359 graft(1) to remove those parts that are not in conflict, leaving the
360 links to the belonging package. This behavior can be forced if the
363 @section Installing packages
364 @cindex package installation
366 To install a single package, simply type:
369 qi -i coreutils-8.30-i586+1.tlz
373 To install multiple packages at once, type:
376 qi -i gcc-8.3.0-i586+1.tlz rafaela-2.2-i586+1.tlz ...
380 Warn about the files that will be linked:
383 qi -w bash-5.0-i586+1.tlz
386 This is to verify the content of a package before installing it.
389 See the process of an installation (very verbose):
392 qi -i -v mariana-3.0-i586+1.tlz
395 A second -v gives more.
398 Installing package in a different location:
401 qi -r /media/floppy -i lzip-1.21-i586+1.tlz
404 The -r option assumes @samp{$@{targetdir@}} and @samp{$@{packagedir@}}.
408 qi -r /home/selk -P /pkgs -t / -i lzip-1.21-i586+1.tlz
411 In this case the content of "lzip-1.21-i586+1.tlz" will be decompressed
412 into @samp{/home/selk/pkgs/lzip-1.21-i586+1}. Assuming that the main
413 binary for lzip is under @samp{/home/selk/pkgs/lzip-1.21-i586+1/usr/bin/}
414 the target for "usr/bin" will be created at @samp{/home/selk}. Considering
415 that you have exported the @env{PATH} as @samp{$@{HOME@}/usr/bin}, now the
416 system is able to see the recent lzip.
419 Installing from a list of packages using standard input:
422 cat FILELIST.txt | qi -i -
425 The list of packages must contain full path names to be passed in the
427 /var/cache/qi/packages/tcl-8.6.9-x86_64+1.tlz
428 /var/cache/qi/packages/tk-8.6.9.1-x86_64+1.tlz
429 /var/cache/qi/packages/vala-0.42.3-x86_64+1.tlz
431 @section Removing packages
432 @cindex package de-installation
434 To remove a package, simply type:
437 qi -d xz-5.2.4-i586+1.tlz
441 Delete mode will match the package name using @samp{$@{packagedir@}} as
442 prefix. For example, if the value of @samp{$@{packagedir@}} is set to
443 /usr/pkg, this will be equal to:
446 qi -d /usr/pkg/xz-5.2.4-i586+1
450 Detailed output (very verbose):
453 qi -d -v /usr/pkg/xz-5.2.4-i586+1
456 A second -v gives more.
459 By default the delete mode does not preserve a package directory after
460 removing its links from @samp{$@{targetdir@}}, but this behavior can be
461 changed if the -k option is passed:
464 qi -d -k /usr/pkg/lzip-1.21-i586+1
467 This means that the links to the package can be reactivated, later:
470 cd /usr/pkg && graft -i lzip-1.21-i586+1
474 Removing package from a different location:
477 qi -r /home/cthulhu -P /pkgs -t / -d xz-5.2.4-i586+1
481 Removing a package using standard input:
484 echo "vala-0.42.3-x86_64+1" | qi -d -
487 This will match with the package directory.
489 @section Upgrading packages
490 @cindex package upgrade
492 The upgrade mode inherits the properties of the installation and removal
493 process. To make sure that a package is updated, the package is installed
494 in a temporary directory taking @samp{$@{packagedir@}} into account. Once
495 the incoming package is pre-installed, qi can proceed to search and delete
496 packages that have the same name (considered as previous ones). Finally,
497 the package is re-installed at its final location and the temporary
498 directory is removed.
501 To upgrade a package, just type:
504 qi -u gcc-9.0.1-i586+1.tlz
507 This will proceed to upgrade "gcc-9.0.1-i586+1" removing any other version
511 If you want to keep the package directories of versions found during the
512 upgrade process, just pass:
515 qi -u -k gcc-9.0.1-i586+1.tlz
519 To see the upgrade process (very verbose):
522 qi -u -v gcc-9.0.1-i586+1.tlz
525 A second -v gives more.
528 To force the upgrade of an existing package:
531 qi -u -f gcc-9.0.1-i586+1.tlz
534 @subsection Package blacklist
535 @cindex package blacklist
537 To implement general package facilities, either to install, remove or
538 maintain the hierarchy of packages in a clean manner, qi makes use of the
539 pruning operation via graft(1) by default:
541 There is a risk if those are crucial packages for the proper functioning
542 of the system, because it implies the deactivation of symbolic from the
543 target directory, @emph{especially} when transitioning an incoming package
544 into its final location during upgrade.
547 A blacklist of package names has been devised for the case where
548 a user decides to upgrade all packages in the system, or
549 just the crucial ones, such as the C library.
551 The blacklist is related to the upgrade mode only, consists in installing
552 a package instead of updating it or removing previous versions of it;
553 the content of the package will be updated over the existing content at
554 @samp{$@{packagedir@}}, while the existing links from
555 @samp{$@{targetdir@}} will be preserved. A pruning of links will be
556 carried out in order to re-link possible differences with the recent
557 content, this helps to avoid leaving dead links in the target directory.
560 The package names for the blacklist to be declared must be set from
561 the configuration file.
568 A recipe is a file telling qi what to do. Most often, the recipe tells
569 qi how to build a binary package from a source tarball.
571 A recipe has two parts: a list of variable definitions and a list of
572 sections. By convention, the syntax of a section is:
581 The section name is followed by parentheses, one newline and an opening
582 brace. The line finishing the section contains just a closing brace.
583 The section names or the function names currently recognized are
586 The @samp{build} section is an augmented shell script. This is the main
587 section (or @strong{shell function}) which contains the instructions to
588 build and produce a package.
593 A "variable" is a @strong{shell variable} defined either in @file{qirc}
594 or in a recipe to represent a string of text, called the variable's
595 "value". These values are substituted by explicit request in the
596 definitions of other variables or in calls to external commands.
598 Variables can represent lists of file names, options to pass to
599 compilers, programs to run, directories to look in for source files,
600 directories to write output to, or anything else you can imagine.
602 Definitions of variables in qi have four levels of precedence.
603 Options which define variables from the command-line override those
604 specified in the @file{qirc} file, while variables defined in the recipe
605 override those specified in @file{qirc}, taking priority over those
606 variables set by command-line options. Finally, the variables have
607 default values if they are not defined anywhere.
609 Options that set variables through the command-line can only reference
610 variables defined in @file{qirc} and variables with default values.
612 Definitions of variables in @file{qirc} can only reference variables
613 previously defined in @file{qirc} and variables with default values.
615 Definitions of variables in the recipe can only reference variables
616 set by the command-line, variables previously defined in the recipe,
617 variables defined in @file{qirc}, and variables with default values.
619 @section Special variables
620 @cindex special variables
622 There are variables which can only be set using the command line options or
623 via @file{qirc}, there are other special variables which can be defined or
624 redefined in a recipe. See the following definitions:
626 @samp{outdir} is the directory where the packages produced are written.
627 This variable can be redefined per-recipe. Default sets to
628 @samp{/var/cache/qi/packages}.
630 @samp{worktree} is the working tree where archives, patches, and recipes
631 are expected. This variable can not be redefined in the recipe. Default
632 sets to @samp{/usr/src/qi}.
634 @samp{tardir} is defined in the recipe to the directory where the tarball
635 containing the source can be found. The full name of the tarball is
636 composed as @samp{$@{tardir@}/$tarname}. Its value is available in the
637 recipe as @samp{$@{tardir@}}; a value of . for @samp{tardir} sets it to
638 the value of CWD (Current Working Directory), this is where the recipe
641 @samp{arch} is the architecture to compose the package name. Its value is
642 available in the recipe as @samp{$@{arch@}}. Default value is the output
645 @samp{jobs} is the number of parallel jobs to pass to the compiler. Its
646 value is available in the recipe as @samp{$@{jobs@}}. The default value
649 The two variables @samp{$@{srcdir@}} and @samp{$@{destdir@}} can be
650 set in the recipe, as any other variable, but if they are not, qi uses
651 default values for them when building a package.
653 @samp{srcdir} contains the source code to be compiled, and defaults to
654 @samp{$@{program@}-$@{version@}}. @samp{destdir} is the place where the
655 built package will be installed, and defaults to
656 @samp{$@{TMPDIR@}/package-$@{program@}}.
658 If @samp{pkgname} is left undefined, the special variable @samp{program}
659 is assigned by default. If @samp{pkgversion} is left undefined, the
660 special variable @samp{version} is assigned by default.
662 @samp{pkgname} and @samp{pkgversion} along with: @samp{version}, @samp{arch},
663 @samp{release}, and (optionally) @samp{pkgcategory} are used to produce the
664 package name in the form:
665 @samp{$@{pkgname@}-$@{pkgversion@}-$@{arch@}+$@{release@}[@@$@{pkgcategory@}].tlz}
667 @samp{pkgcategory} is an optional special variable that can be defined on the
668 recipe to categorize the package name. If it is defined, then the
669 package output will be composed as
670 @samp{$@{pkgname@}-$@{pkgversion@}-$@{arch@}+$@{release@}@@$@{pkgcategory@}.tlz}.
671 Automatically, the value of @samp{pkgcategory} will be prefixed using the
674 A special variable called @samp{replace} can be used to declare package names
675 that will be replaced at installation time.
678 A typical recipe contains the following variables:
681 @item @samp{program}: Software name.
683 It matches the source name. It is also used to compose the name of the
684 package if @samp{$@{pkgname@}} is not specified.
686 @item @samp{version}: Software version.
688 It matches the source name. It is also used to compose the version of the
689 package if @samp{$@{pkgversion@}} is not specified.
691 @item @samp{arch}: Software architecture.
693 It is used to compose the architecture of the package in which it is
696 @item @samp{release}: Release number.
698 This is used to reflect the release number of the package. It is
699 recommended to increase this number after any significant change in
700 the recipe or post-install script.
702 @item @samp{pkgcategory}: Package category.
704 Optional but recommended variable to categorize the package name when it is
709 Obtaining sources over the network must be declared in the recipe using
710 the @samp{fetch} variable.
712 The variables @samp{netget} and @samp{rsync} can be defined in @file{qirc}
713 to establish a network downloader in order to get the sources. If they
714 are not defined, qi uses default values:
716 @samp{netget} is the general network downloader tool, defaults sets to
717 @samp{wget -c -w1 -t3 --no-check-certificate}.
719 @samp{rsync} is the network tool for sources containing the prefix for
720 the RSYNC protocol, default sets to
721 @samp{rsync -v -a -L -z -i --progress}.
723 The variable @samp{description} is used to print the package description
724 when a package is installed.
726 A description has two parts: a brief description, and a long description.
727 By convention, the syntax of @samp{description} is:
737 The first line of the value represented is a brief description of the
738 software (called "blurb"). A blank line separates the @emph{brief
739 description} from the @emph{long description}, which should contain a more
740 descriptive description of the software.
743 An example looks like:
747 The GNU core utilities.
749 The GNU core utilities are the basic file, shell and text manipulation
750 utilities of the GNU operating system. These are the core utilities
751 which are expected to exist on every operating system.
755 Please consider a length limit of 78 characters as maximum, because the same
756 one would be used on the meta file creation. See
757 @ref{Recipes, The meta file} section.
759 The @samp{homepage} variable is used to declare the main site or home page:
762 homepage=http://www.gnu.org/software/gcc
765 The variable @samp{license} is used for license information@footnote{
766 The proposal for @samp{license} was made by Richard M. Stallman at
767 @url{http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html}.}.
768 Some code in the program can be covered by license A, license B, or
769 license C. For "separate licensing" or "heterogeneous licensing", we
770 suggest using @strong{|} for a disjunction, @strong{&} for a conjunction
771 (if that ever happens in a significant way), and comma for heterogeneous
772 licensing. Comma would have lower precedence, plus added special terms.
775 license="LGPL, GPL | Artistic + added permission"
778 @section Writing recipes
779 @cindex writing recipes
781 Originally, Qi was designed for the version 3 of Dragora GNU/Linux; this
782 doesn't mean you can't use it in another distribution, just that if you do,
783 you'll have to try it out for yourself. To help with this, here are some
784 references to well-written recipes:
787 @item @url{http://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes}
788 @item @url{http://notabug.org/dragora/dragora/src/master/recipes}
791 @section Building packages
792 @cindex package build
794 A recipe is any valid regular file. Qi sets priorities for reading a
795 recipe, the order in which qi looks for a recipe is:
799 Current working directory.
802 If the specified path name does not contain "recipe" as the last
803 component. Qi will complete it by adding "recipe" to the path name.
806 If the recipe is not in the current working directory, it will be
807 searched under @samp{$@{worktree@}/recipes}. The last component will be
808 completed adding "recipe" to the specified path name.
812 To build a single package, type:
819 Multiple jobs can be passed to the compiler to speed up the build process:
822 qi -b -j3 x-apps/xterm
826 Update or install the package produced (if it is not already installed)
830 qi -b -j3 -u x-apps/xterm
834 Only process a recipe but do not create the binary package:
840 The options -i or -u have no effect when -n is given.
843 This can be useful to inspect the build process of recipe:
845 qi -b -k -n dict/aspell 2>&1 | tee aspell-buildlog.txt
847 The -k option could preserve the source directory and the destination
848 directory for later inspection. A log file of the build process will be
849 created redirecting both, standard error and standard output to tee(1).
851 @section Variables from the environment
852 @cindex environment variables
854 Qi has environment variables which can be used at build time:
856 The variable @env{TMPDIR} sets the temporary directory for sources, which is
857 used for package extractions (see @ref{Examining packages}) and is
858 prepended to the value of @samp{$@{srcdir@}} and @samp{$@{destdir@}} in
859 build mode. By convention its default value is equal to
860 @samp{/usr/src/qi/build}.
862 The variables @env{QICFLAGS}, @env{QICXXFLAGS}, and @env{QILDFLAGS} have
863 no effect by default. The environment variables such as @env{CFLAGS},
864 @env{CXXFLAGS}, and @env{LDFLAGS} are unset at compile time:
867 Recommended practice is to set variables in the command line of
868 @samp{configure} or @emph{make(1)} instead of exporting to the
869 environment. As follows:
871 @url{http://www.gnu.org/software/make/manual/html_node/Environment.html}
873 It is not wise for makefiles to depend for their functioning on environment
874 variables set up outside their control, since this would cause different
875 users to get different results from the same makefile. This is against the
876 whole purpose of most makefiles.
879 Setting environment variables for configure is deprecated because running
880 configure in varying environments can be dangerous.
882 @url{http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html}
884 Variables not defined in a site shell script can be set in the environment
885 passed to configure. However, some packages may run configure again
886 during the build, and the customized values of these variables may be
887 lost. In order to avoid this problem, you should set them in the
888 configure command line, using @samp{VAR=value}. For example:
890 @code{./configure CC=/usr/local2/bin/gcc}
893 @url{http://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html}
895 If for instance the user runs @samp{CC=bizarre-cc ./configure}, then the cache,
896 config.h, and many other output files depend upon bizarre-cc being the C
897 compiler. If for some reason the user runs ./configure again, or if it is
898 run via @samp{./config.status --recheck}, (See Automatic Remaking, and see
899 config.status Invocation), then the configuration can be inconsistent,
900 composed of results depending upon two different compilers.
902 Indeed, while configure can notice the definition of CC in @samp{./configure
903 CC=bizarre-cc}, it is impossible to notice it in @samp{CC=bizarre-cc
904 ./configure}, which, unfortunately, is what most users do.
906 configure: error: changes in the environment can compromise the build.
909 @section The meta file
910 @cindex the meta file
912 The "meta file" is a regular file created during the build mode, it
913 contains information about the package such as package name, package
914 version, architecture, release, fetch address, description, and other
915 minor data extracted from processed recipes. The name of the file is
916 generated as @samp{$@{full_pkgname@}.tlz.txt}, and its purpose is to
917 reflect essential information to the user without having to look inside
918 the package content. The file format is also intended to be used by
919 other scripts or by common Unix tools.
921 The content of a meta file looks like:
925 # Pattern scanning and processing language.
927 # The awk utility interprets a special-purpose programming language
928 # that makes it possible to handle simple data-reformatting jobs
929 # with just a few lines of code. It is a free version of 'awk'.
931 # GNU awk implements the AWK utility which is part of
932 # IEEE Std 1003.1 Shell and Utilities (XCU).
943 full_pkgname=gawk-5.0.1-x86_64+1@@tools
944 blurb="Pattern scanning and processing language."
945 homepage="http://www.gnu.org/software/gawk"
947 fetch="http://ftp.gnu.org/gnu/gawk/gawk-5.0.1.tar.lz"
951 Package descriptions are extracted from the variable @samp{description}
952 where each line is interpreted literally and pre-formatted to fit in
953 (exactly) @strong{80 columns}, plus the character @samp{#} and a blank
954 space is prefixed to every line (shell comments).
957 In addition to the Special variables, there are implicit variables such as
960 The @samp{blurb} variable is related to the special variable
961 @samp{description}. Its value is made from the first (substantial)
962 line of @samp{description}, mentioned as the "brief description".
967 @cindex handling build order
969 The order mode has the purpose of resolving the build order through
970 .order files. An order file contains a list of recipe names, by default
971 does not perform any action other than to print a resolved list in
972 descending order. For example, if @strong{a} depends on @strong{b} and
973 @strong{c}, and @strong{c} depends on @strong{b} as well, the file might
982 Each letter represents a recipe name, complete dependencies for
983 the first recipe name are listed in descending order, which is
984 printed from right to left, and removed from left to right:
994 Blank lines, colons and parentheses are simply ignored. Comment lines
995 beginning with @samp{#} are allowed.
998 An order file could be used to build a series of packages, for example,
1002 # Image handling libraries
1004 libs/libjpeg-turbo: devel/nasm
1005 x-libs/jasper: libs/libjpeg-turbo
1006 libs/tiff: libs/libjpeg-turbo
1009 To proceed with each recipe, we can type:
1012 qi -o imglibs.order | qi -b -i -
1015 The output of @samp{qi -o imglibs.order} tells to qi in which order it
1016 should build the recipes:
1026 @node Creating packages
1027 @chapter Creating packages
1028 @cindex package creation
1030 The "creation mode" is an internal function of qi to make new Qi compatible
1031 compatible packages, the creation mode is selected by the -c option.
1032 A package is produced using the contents of the Current Directory, and
1033 the package file is written out.
1036 Usage: qi -c [@var{Output/PackageName.tlz}]...
1039 The argument for the file name to be written must contain a fully
1040 qualified named directory as the output directory where the package
1041 produced will be written. The file name should be composed using the
1042 full name: name-version-architecture+release.tlz
1048 cd claws-mail-3.17.1-x86_64+1
1049 qi -c /var/cache/qi/packages/claws-mail-3.17.1-x86_64+1.tlz
1052 In this case, the package "claws-mail-3.17.1-x86_64+1.tlz" will be written
1053 into @samp{/var/cache/qi/packages/}.
1056 All packages produced are complemented by a checksum file (.sha256).
1059 @node Examining packages
1060 @chapter Examining packages
1061 @cindex package examination
1063 The "extraction mode" serves to examine binary packages for debugging
1064 purposes. The extraction mode is selected by the -x option. It
1065 decompresses a package into a single directory, verifying its integrity
1066 and preserving its properties.
1069 Usage: qi -x [@var{packagename.tlz}]...
1075 qi -x mksh-R56c-x86_64+1.tlz
1078 This action will put the content of "mksh-R56c-x86_64+1.tlz" into a
1079 single directory, this will be a private directory for the user who
1081 requested the action, creation mode will be equal to @strong{u=rwx,g=,o=
1082 (0700)}. The package content will reside on this location, default
1083 mask to deploy the content will be equal to
1084 @strong{u=rwx,g=rwx,o=rwx (0000)}.
1087 The creation of the custom directory is influenced by the value of the
1088 @env{TMPDIR} variable.
1092 @chapter Exit status
1095 All the exit codes are described in this chapter.
1099 Successful completion (no errors).
1102 Minor common errors:
1105 @item Help usage on illegal options or required arguments.
1107 @item Program needed by qi (prerequisite) is not available.
1111 Command execution error:
1113 This code is used to return the evaluation of external commands and shell
1114 arguments in case of error.
1117 Integrity check error for compressed files.
1119 Compressed files means:
1122 @item Tarball files from tar(1).
1123 Supported extensions: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
1126 @item Tarball files from tarlz(1).
1127 Supported extensions: .tar.lz, .tlz
1129 @item Zip files from unzip(1).
1130 Supported extensions: .zip, .ZIP
1132 @item Gzip files from gzip(1).
1133 Supported extensions: .gz, .Z
1135 @item Bzip2 files from bzip2(1).
1136 Supported extension: .bz2
1138 @item Lzip files from lzip(1).
1139 Supported extension: .lz
1141 @item Xz files from xz(1).
1142 Supported extension: .xz
1146 File empty, not regular, or expected.
1148 Commonly, it is expected:
1151 @item An argument for the mode of operation.
1153 @item A readable file or directory.
1155 @item A binary package (.tlz).
1157 @item A valid recipe.
1159 @item An order file (.order).
1161 @item A protocol supported by the network downloader tool.
1163 @item A checksum file (.sha256).
1167 Empty or not defined variable:
1169 This code is used to report empty or undefined variables; usually,
1170 variables coming from a recipe or assigned arrays that are tested.
1173 Package already installed:
1175 The package directory for an incoming .tlz package already exists.
1178 Network manager error:
1180 This code is used if the network downloader tool fails for some reason.