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 18 Jul 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 for invoking Qi.
105 Usage: qi COMMAND [@var{OPTION}...] [@var{FILE}]...
109 One mandatory command specifies the operation that @samp{qi} should
110 perform, options are meant to detail how this operation should be
111 performed during or after the process.
114 Qi supports the following commands:
118 Warn about files that will be installed.
130 Extract packages for debugging purposes.
133 Create a .tlz package from directory.
136 Build packages using recipe names.
139 Resolve build order through .order files
143 Options when installing, removing, or upgrading software packages:
148 Force upgrade of pre-existing packages.
152 Keep directories when build/remove/upgrade.
154 Keep (don't delete) the package directory when using remove/upgrade command.
156 This will also try to preserve the directories @samp{$@{srcdir@}} and
157 @samp{$@{destdir@}} when using build command. Its effect is available in
158 recipes as @samp{$@{keep_srcdir@}} and @samp{$@{keep_destdir@}}. See
159 @ref{Recipes, Special variables} for details.
166 @itemx --packagedir=<dir>
167 Set directory for package installations.
170 @itemx --targetdir=<dir>
171 Set target directory for symbolic links.
174 @itemx --rootdir=<dir>
175 Use the fully qualified named directory as the root directory for all qi
178 Note: the target directory and the package directory will be
179 relative to the specified directory, excepting the graft log file.
183 Options when building software packages using recipes:
187 @itemx --architecture
188 Set architecture name for the package.
192 Parallel jobs for the compiler.
194 This option sets the variable @samp{$@{jobs@}}. If not specified, default
198 @itemx --skip-questions
199 Skip questions on completed recipes.
203 Increment release number (@samp{$@{release@}} + 1).
205 The effect of this option will be omitted if --no-package is being used.
209 Do not create a .tlz package.
213 Install package after the build.
217 Upgrade package after the build.
220 @itemx --outdir=<dir>
221 Where the packages produced will be written.
223 This option sets the variable @samp{$@{outdir@}}.
226 @itemx --worktree=<dir>
227 Where archives, patches, recipes are expected.
229 This option sets the variable @samp{$@{worktree@}}.
232 @itemx --sourcedir=<dir>
233 Where compressed sources will be found.
235 This option sets the variable @samp{$@{tardir@}}.
244 Be verbose (an extra -v gives more).
246 It sets the verbosity level, default sets to 0.
248 The value 1 is used for more verbosity while the value 2 is too detailed.
249 Although at the moment it is limited to graft(1) verbosity.
253 Do not read the configuration file.
255 This will ignore reading the qirc file.
258 @itemx --show-location
259 Print default directory locations and exit.
261 This will print the target directory, package directory, working tree,
262 the directory for sources, and the output directory for the packages
267 Display the usage and exit.
272 This will print the (short) version information and then exit.
274 The same can be achieved if Qi is invoked as @samp{qi version}.
277 When FILE is -, qi can read from the standard input. See examples from
278 the @ref{Packages} section.
280 Exit status: 0 for a normal exit, 1 for minor common errors (help usage,
281 support not available, etc), 2 to indicate a command execution error;
282 3 for integrity check error on compressed files, 4 for empty, not
283 regular, or expected files, 5 for empty or not defined variables,
284 6 when a package already exist, 10 for network manager errors.
285 For more details, see the @ref{Exit status} section.
289 @chapter The qirc file
290 @cindex configuration file
292 The global @file{qirc} file offers a way to define variables and tools
293 (such as a download manager) for default use. This file is used by qi
294 at runtime, e.g., to build, install, remove or upgrade packages.
296 Variables and their possible values must be declared as any other
297 variable in the shell.
300 The command line options related to the package directory and target
301 directory and some of the command line options used for the build command,
302 have the power to override the values declared on @file{qirc}.
303 See @ref{Invoking qi}.
306 The order in which qi looks for this file is:
310 @env{$@{HOME@}/.qirc}
314 @samp{$@{sysconfdir@}/qirc}
318 If you intend to run qi as effective user, the file
319 @samp{$@{sysconfdir@}/qirc} could be copied to @env{$@{HOME@}/.qirc}
320 setting the paths for @samp{$@{packagedir@}} and @samp{$@{targetdir@}}
321 according to the @env{$HOME}.
326 @cindex managing packages
328 A package is a suite of programs usually distributed in binary form
329 which may also contain manual pages, documentation, or any other file
330 associated to a specific software.
332 The package format used by qi is a simplified POSIX pax archive
333 compressed using lzip@footnote{For more details about tarlz and the
334 lzip format, visit @url{https://lzip.nongnu.org/tarlz.html}.}. The
335 file extension for packages ends in @samp{.tlz}.
338 Both package installation and package de-installation are managed using
339 two important (internal) variables: @samp{$@{packagedir@}} and
340 @samp{$@{targetdir@}}, these values can be changed in the
341 configuration file or via options.
343 @samp{$@{packagedir@}} is a common directory tree where the package
344 contents will be decompressed (will reside).
346 @samp{$@{targetdir@}} is a target directory where the links will be
347 made by graft(1) taking @samp{$@{packagedir@}/package_name} into account.
350 Packages are installed in self-contained directory trees and symbolic
351 links from a common area are made to the package files. This allows
352 multiple versions of the same package to coexist on the same system.
354 @section Package conflicts
355 @cindex package conflicts
357 All the links to install or remove a package are handled by graft(1).
358 Since multiple packages can be installed or removed at the same time,
359 certain conflicts may arise between the packages.
362 graft@footnote{The official guide for Graft can be found at
363 @url{http://peters.gormand.com.au/Home/tools/graft/graft.html}.}
364 defines a CONFLICT as one of the following conditions:
368 If the package object is a directory and the target object exists but is
372 If the package object is not a directory and the target object exists
373 and is not a symbolic link.
376 If the package object is not a directory and the target object exists
377 and is a symbolic link to something other than the package object.
381 The default behavior of qi for an incoming package is to ABORT if a
382 conflict arises. When a package is going to be deleted, qi tells to
383 graft(1) to remove those parts that are not in conflict, leaving the
384 links to the belonging package. This behavior can be forced if the
385 --prune option is given.
387 @section Installing packages
388 @cindex package installation
390 To install a single package, simply type:
393 qi install coreutils_8.30_i586-1@@tools.tlz
397 To install multiple packages at once, type:
400 qi install gcc_8.3.0_i586-1@@devel.tlz rafaela_2.2_i586-1@@legacy.tlz ...
404 Warn about the files that will be linked:
407 qi warn bash_5.0_i586-1@@shells.tlz
410 This is to verify the content of a package before installing it.
413 See the process of an installation:
416 qi install --verbose mariana_3.0_i586-1@@woman.tlz
419 A second --verbose or -v option gives more (very verbose).
422 Installing package in a different location:
425 qi install --rootdir=/media/floppy lzip_1.21_i586-1@@compressors.tlz
428 Important: the --rootdir option assumes @samp{$@{targetdir@}} and
429 @samp{$@{packagedir@}}. See the following example:
432 qi install --rootdir=/home/selk lzip_1.21_i586-1@@compressors.tlz
435 The content of "lzip_1.21_i586-1@@compressors.tlz" will be decompressed
436 into @samp{/home/selk/pkgs/lzip_1.21_i586-1@@compressors}.
437 Assuming that the main binary for lzip is under
438 @samp{/home/selk/pkgs/lzip_1.21_i586-1@@compressors/usr/bin/}
439 the target for "usr/bin" will be created at @samp{/home/selk}. Considering
440 that you have exported the @env{PATH} as @samp{$@{HOME@}/usr/bin}, now the
441 system is able to see the recent lzip command.
444 Installing from a list of packages using standard input:
447 qi install - < PACKAGELIST.txt
450 Or in combination with another tool:
452 sort -u PACKAGELIST.txt | qi install -
455 The sort command will read and sorts the list of declared packages,
456 while trying to have unique entries for each statement. The output
457 produced is captured by Qi to install each package.
459 An example of a list containing package names is:
461 /var/cache/qi/packages/amd64/tcl_8.6.9_amd64-1@@devel.tlz
462 /var/cache/qi/packages/amd64/tk_8.6.9.1_amd64-1@@devel.tlz
463 /var/cache/qi/packages/amd64/vala_0.42.3_amd64-1@@devel.tlz
466 @section Removing packages
467 @cindex package de-installation
469 To remove a package, simply type:
472 qi remove xz_5.2.4_i586-1@@compressors.tlz
476 Remove command will match the package name using @samp{$@{packagedir@}} as
477 prefix. For example, if the value of @samp{$@{packagedir@}} has been
478 set to /usr/pkg, this will be equal to:
481 qi remove /usr/pkg/xz_5.2.4_i586-1@@compressors
488 qi remove --verbose /usr/pkg/xz_5.2.4_i586-1@@compressors
491 A second --verbose or -v option gives more (very verbose).
494 By default the remove command does not preserve a package directory after
495 removing its links from @samp{$@{targetdir@}}, but this behavior can be
496 changed if the --keep option is passed:
499 qi remove --keep /usr/pkg/lzip_1.21_i586-1@@compressors
502 This means that the links to the package can be reactivated, later:
505 cd /usr/pkg && graft -i lzip_1.21_i586-1@@compressors
509 Removing package from a different location:
512 qi remove --rootdir=/home/cthulhu xz_5.2.4_i586-1@@compressors
516 Removing a package using standard input:
519 echo vala_0.42.3_amd64-1@@devel | qi remove -
522 This will match with the package directory.
524 @section Upgrading packages
525 @cindex package upgrade
527 The upgrade command inherits the properties of the installation and removal
528 process. To make sure that a package is updated, the package is installed
529 in a temporary directory taking @samp{$@{packagedir@}} into account. Once
530 the incoming package is pre-installed, qi can proceed to search and delete
531 packages that have the same name (considered as previous ones). Finally,
532 the package is re-installed at its final location and the temporary
533 directory is removed.
536 To upgrade a package, just type:
539 qi upgrade gcc_9.0.1_i586-1@@devel.tlz
542 This will proceed to upgrade "gcc_9.0.1_i586-1@@devel" removing any other
543 version of "gcc" (if any).
546 If you want to keep the package directories of versions found during the
547 upgrade process, just pass:
550 qi upgrade --keep gcc_9.0.1_i586-1@@devel.tlz
554 To see the upgrade process:
557 qi upgrade --verbose gcc_9.0.1_i586-1@@devel.tlz
560 A second --verbose or -v option gives more (very verbose).
563 To force the upgrade of an existing package:
566 qi upgrade --force gcc_9.0.1_i586-1@@devel.tlz
569 @subsection Package blacklist
570 @cindex package blacklist
572 To implement general package facilities, either to install, remove or
573 maintain the hierarchy of packages in a clean manner, qi makes use of the
574 pruning operation via graft(1) by default:
576 There is a risk if those are crucial packages for the proper functioning
577 of the system, because it implies the deactivation of symbolic from the
578 target directory, @emph{especially} when transitioning an incoming package
579 into its final location during an upgrade.
582 A blacklist of package names has been devised for the case where
583 a user decides to upgrade all the packages in the system, or
584 just the crucial ones, such as the C library.
586 The blacklist is related to the upgrade command only, consists in installing
587 a package instead of updating it or removing previous versions of it;
588 the content of the package will be updated over the existing content at
589 @samp{$@{packagedir@}}, while the existing links from
590 @samp{$@{targetdir@}} will be preserved. A pruning of links will be
591 carried out in order to re-link possible differences with the recent
592 content, this helps to avoid leaving dead links in the target directory.
595 Package names for the blacklist to be declared must be set from the
603 A recipe is a file telling qi what to do. Most often, the recipe tells
604 qi how to build a binary package from a source tarball.
606 A recipe has two parts: a list of variable definitions and a list of
607 sections. By convention, the syntax of a section is:
616 The section name is followed by parentheses, one newline and an opening
617 brace. The line finishing the section contains just a closing brace.
618 The section names or the function names currently recognized are
621 The @samp{build} section (or @strong{shell function}) is an augmented
622 shell script that contains the main instructions for building a software
628 A "variable" is a @strong{shell variable} defined either in @file{qirc}
629 or in a recipe to represent a string of text, called the variable's
630 "value". These values are substituted by explicit request in the
631 definitions of other variables or in calls to external commands.
633 Variables can represent lists of file names, options to pass to
634 compilers, programs to run, directories to look in for source files,
635 directories to write output to, or anything else you can imagine.
637 Definitions of variables in qi have four levels of precedence.
638 Options which define variables from the command-line override those
639 specified in the @file{qirc} file, while variables defined in the recipe
640 override those specified in @file{qirc}, taking priority over those
641 variables set by command-line options. Finally, the variables have
642 default values if they are not defined anywhere.
644 Options that set variables through the command-line can only reference
645 variables defined in @file{qirc} and variables with default values.
647 Definitions of variables in @file{qirc} can only reference variables
648 previously defined in @file{qirc} and variables with default values.
650 Definitions of variables in the recipe can only reference variables
651 set by the command-line, variables previously defined in the recipe,
652 variables defined in @file{qirc}, and variables with default values.
654 @section Special variables
655 @cindex special variables
657 There are variables which can only be set using the command line options or
658 via @file{qirc}, there are other special variables which can be defined or
659 redefined in a recipe. See the following definitions:
661 @samp{outdir} is the directory where the packages produced are written.
662 This variable can be redefined per-recipe. Default sets to
663 @samp{/var/cache/qi/packages}.
665 @samp{worktree} is the working tree where archives, patches, and recipes
666 are expected. This variable can not be redefined in the recipe. Default
667 sets to @samp{/usr/src/qi}.
669 @samp{tardir} is defined in the recipe to the directory where the tarball
670 containing the source can be found. The full name of the tarball is
671 composed as @samp{$@{tardir@}/$tarname}. Its value is available in the
672 recipe as @samp{$@{tardir@}}; a value of . for @samp{tardir} sets it to
673 the value of CWD (Current Working Directory), this is where the recipe
676 @samp{arch} is the architecture to compose the package name. Its value is
677 available in the recipe as @samp{$@{arch@}}. Default value is the one
678 that was set in the Qi configuration.
680 @samp{jobs} is the number of parallel jobs to pass to the compiler. Its
681 value is available in the recipe as @samp{$@{jobs@}}. The default value
684 The two variables @samp{$@{srcdir@}} and @samp{$@{destdir@}} can be
685 set in the recipe, as any other variable, but if they are not, qi uses
686 default values for them when building a package.
688 @samp{srcdir} contains the source code to be compiled, and defaults to
689 @samp{$@{program@}-$@{version@}}. @samp{destdir} is the place where the
690 built package will be installed, and defaults to
691 @samp{$@{TMPDIR@}/package-$@{program@}}.
693 If @samp{pkgname} is left undefined, the special variable @samp{program}
694 is assigned by default. If @samp{pkgversion} is left undefined, the
695 special variable @samp{version} is assigned by default.
697 @samp{pkgname} and @samp{pkgversion} along with: @samp{version}, @samp{arch},
698 @samp{release}, and (optionally) @samp{pkgcategory} are used to produce the
699 package name in the form:
700 @samp{$@{pkgname@}_$@{pkgversion@}_$@{arch@}-$@{release@}[@@$@{pkgcategory@}].tlz}
702 @samp{pkgcategory} is an optional special variable that can be defined on the
703 recipe to categorize the package name. If it is defined, then the
704 package output will be composed as
705 @samp{$@{pkgname@}_$@{pkgversion@}_$@{arch@}-$@{release@}[@@$@{pkgcategory@}.tlz}.
706 Automatically, the value of @samp{pkgcategory} will be prefixed using the
707 @samp{@@} (at) symbol which will be added to the last part of the package name.
709 A special variable called @samp{replace} can be used to declare package names
710 that will be replaced at installation time.
712 The special variables @samp{keep_srcdir} and @samp{keep_destdir} are provided
713 in order to preserve the directories @samp{$@{srcdir@}} or @samp{$@{destdir@}},
714 if those exists as such. Note: The declaration of these variables are subject
715 to manual deactivation; its purpose in recipes is to preserve the directories
716 that relate to the package's build (source) and destination directory, that is
717 so that another recipe can get a new package (or meta package) from there. For
718 example, the declarations can be done as:
721 keep_srcdir=keep_srcdir
722 keep_destdir=keep_destdir
725 Then from another recipe you would proceed to copy the necessary files that
726 will compose the meta package, from the main function you must deactivate
727 the variables at the end:
734 This will leave the 'keep_srcdir' and 'keep_destdir' variables blank to
735 continue with the rest of the recipes.
738 A typical recipe contains the following variables:
741 @item @samp{program}: Software name.
743 It matches the source name. It is also used to compose the name of the
744 package if @samp{$@{pkgname@}} is not specified.
746 @item @samp{version}: Software version.
748 It matches the source name. It is also used to compose the version of the
749 package if @samp{$@{pkgversion@}} is not specified.
751 @item @samp{arch}: Software architecture.
753 It is used to compose the architecture of the package in which it is
756 @item @samp{release}: Release number.
758 This is used to reflect the release number of the package. It is
759 recommended to increase this number after any significant change in
760 the recipe or post-install script.
762 @item @samp{pkgcategory}: Package category.
764 Optional but recommended variable to categorize the package name when it is
769 Obtaining sources over the network must be declared in the recipe using
770 the @samp{fetch} variable.
772 The variables @samp{netget} and @samp{rsync} can be defined in @file{qirc}
773 to establish a network downloader in order to get the sources. If they
774 are not defined, qi uses default values:
776 @samp{netget} is the general network downloader tool, defaults sets to
777 @samp{wget -c -w1 -t3 --no-check-certificate}.
779 @samp{rsync} is the network tool for sources containing the prefix for
780 the RSYNC protocol, default sets to
781 @samp{rsync -v -a -L -z -i --progress}.
783 The variable @samp{description} is used to print the package description
784 when a package is installed.
786 A description has two parts: a brief description, and a long description.
787 By convention, the syntax of @samp{description} is:
797 The first line of the value represented is a brief description of the
798 software (called "blurb"). A blank line separates the @emph{brief
799 description} from the @emph{long description}, which should contain a more
800 descriptive description of the software.
803 An example looks like:
807 The GNU core utilities.
809 The GNU core utilities are the basic file, shell and text manipulation
810 utilities of the GNU operating system. These are the core utilities
811 which are expected to exist on every operating system.
815 Please consider a length limit of 78 characters as maximum, because the same
816 one would be used on the meta file creation. See
817 @ref{Recipes, The meta file} section.
819 The @samp{homepage} variable is used to declare the main site or home page:
822 homepage=http://www.gnu.org/software/gcc
825 The variable @samp{license} is used for license information@footnote{
826 The proposal for @samp{license} was made by Richard M. Stallman at
827 @url{http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html}.}.
828 Some code in the program can be covered by license A, license B, or
829 license C. For "separate licensing" or "heterogeneous licensing", we
830 suggest using @strong{|} for a disjunction, @strong{&} for a conjunction
831 (if that ever happens in a significant way), and comma for heterogeneous
832 licensing. Comma would have lower precedence, plus added special terms.
835 license="LGPL, GPL | Artistic - added permission"
838 @section Writing recipes
839 @cindex writing recipes
841 Originally, Qi was designed for the version 3 of Dragora GNU/Linux; this
842 doesn't mean you can't use it in another distribution, just that if you do,
843 you'll have to try it out for yourself. To help with this, here are some
844 references to well-written recipes:
847 @item @url{http://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes}
848 @item @url{http://notabug.org/dragora/dragora/src/master/recipes}
851 @section Building packages
852 @cindex package build
854 A recipe is any valid regular file. Qi sets priorities for reading a
855 recipe, the order in which qi looks for a recipe is:
859 Current working directory.
862 If the specified path name does not contain "recipe" as the last
863 component. Qi will complete it by adding "recipe" to the path name.
866 If the recipe is not in the current working directory, it will be
867 searched under @samp{$@{worktree@}/recipes}. The last component will be
868 completed adding "recipe" to the specified path name.
872 To build a single package, type:
875 qi build x-apps/xterm
879 Multiple jobs can be passed to the compiler to speed up the build process:
882 qi build --jobs 3 x-apps/xterm
886 Update or install the produced package (if not already installed) when the
890 qi build -j3 --upgrade x-apps/xterm
894 Only process a recipe but do not create the binary package:
897 qi build --no-package dict/aspell
900 The options --install or --upgrade have no effect when --no-package
904 This can be useful to inspect the build process of recipe:
906 qi build --keep --no-package dict/aspell 2>&1 | tee aspell-log.txt
908 The --keep option could preserve the source directory and the destination
909 directory for later inspection. A log file of the build process will be
910 created redirecting both, standard error and standard output to tee(1).
912 @section Variables from the environment
913 @cindex environment variables
915 Qi has environment variables which can be used at build time:
917 The variable @env{TMPDIR} sets the temporary directory for sources, which is
918 used for package extractions (see @ref{Examining packages}) and is
919 prepended to the value of @samp{$@{srcdir@}} and @samp{$@{destdir@}} in
920 build command. By convention its default value is equal to
921 @samp{/usr/src/qi/build}.
923 The variables @env{QICFLAGS}, @env{QICXXFLAGS}, and @env{QILDFLAGS} have
924 no effect by default. The environment variables such as @env{CFLAGS},
925 @env{CXXFLAGS}, and @env{LDFLAGS} are unset at compile time:
928 Recommended practice is to set variables in the command line of
929 @samp{configure} or @emph{make(1)} instead of exporting to the
930 environment. As follows:
932 @url{http://www.gnu.org/software/make/manual/html_node/Environment.html}
934 It is not wise for makefiles to depend for their functioning on environment
935 variables set up outside their control, since this would cause different
936 users to get different results from the same makefile. This is against the
937 whole purpose of most makefiles.
940 Setting environment variables for configure is deprecated because running
941 configure in varying environments can be dangerous.
943 @url{http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html}
945 Variables not defined in a site shell script can be set in the environment
946 passed to configure. However, some packages may run configure again
947 during the build, and the customized values of these variables may be
948 lost. In order to avoid this problem, you should set them in the
949 configure command line, using @samp{VAR=value}. For example:
951 @code{./configure CC=/usr/local2/bin/gcc}
954 @url{http://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html}
956 If for instance the user runs @samp{CC=bizarre-cc ./configure}, then the cache,
957 config.h, and many other output files depend upon bizarre-cc being the C
958 compiler. If for some reason the user runs ./configure again, or if it is
959 run via @samp{./config.status --recheck}, (See Automatic Remaking, and see
960 config.status Invocation), then the configuration can be inconsistent,
961 composed of results depending upon two different compilers.
963 Indeed, while configure can notice the definition of CC in @samp{./configure
964 CC=bizarre-cc}, it is impossible to notice it in @samp{CC=bizarre-cc
965 ./configure}, which, unfortunately, is what most users do.
967 configure: error: changes in the environment can compromise the build.
970 @section The meta file
971 @cindex the meta file
973 The "meta file" is a regular file created during the build command, it
974 contains information about the package such as package name, package
975 version, architecture, release, fetch address, description, and other
976 minor data extracted from processed recipes. The name of the file is
977 generated as @samp{$@{full_pkgname@}.tlz.txt}, and its purpose is to
978 reflect essential information to the user without having to look inside
979 the package content. The file format is also intended to be used by
980 other scripts or by common Unix tools.
982 The content of a meta file looks like:
986 # Pattern scanning and processing language.
988 # The awk utility interprets a special-purpose programming language
989 # that makes it possible to handle simple data-reformatting jobs
990 # with just a few lines of code. It is a free version of 'awk'.
992 # GNU awk implements the AWK utility which is part of
993 # IEEE Std 1003.1 Shell and Utilities (XCU).
1004 full_pkgname=gawk_5.0.1_amd64-1@@tools
1005 blurb="Pattern scanning and processing language."
1006 homepage="http://www.gnu.org/software/gawk"
1008 fetch="http://ftp.gnu.org/gnu/gawk/gawk-5.0.1.tar.lz"
1012 Package descriptions are extracted from the variable @samp{description}
1013 where each line is interpreted literally and pre-formatted to fit in
1014 (exactly) @strong{80 columns}, plus the character @samp{#} and a blank
1015 space is prefixed to every line (shell comments).
1018 In addition to the Special variables, there are implicit variables such as
1021 The @samp{blurb} variable is related to the special variable
1022 @samp{description}. Its value is made from the first (substantial)
1023 line of @samp{description}, mentioned as the "brief description".
1027 @chapter Order files
1028 @cindex handling build order
1030 The order command has the purpose of resolving the build order through
1031 .order files. An order file contains a list of recipe names, by default
1032 does not perform any action other than to print a resolved list in
1033 descending order. For example, if @strong{a} depends on @strong{b} and
1034 @strong{c}, and @strong{c} depends on @strong{b} as well, the file might
1043 Each letter represents a recipe name, complete dependencies for
1044 the first recipe name are listed in descending order, which is
1045 printed from right to left, and removed from left to right:
1055 Blank lines, colons and parentheses are simply ignored. Comment lines
1056 beginning with @samp{#} are allowed.
1059 An order file could be used to build a series of packages, for example,
1063 # Image handling libraries
1065 libs/libjpeg-turbo: devel/nasm
1066 x-libs/jasper: libs/libjpeg-turbo
1067 libs/tiff: libs/libjpeg-turbo
1070 To proceed with each recipe, we can type:
1073 qi order imglibs.order | qi build --install -
1076 The output of @samp{qi order imglibs.order} tells to qi in which order it
1077 should build the recipes:
1087 @node Creating packages
1088 @chapter Creating packages
1089 @cindex package creation
1091 The creation command is an internal function of qi to make new Qi
1092 compatible packages. A package is produced using the contents of
1093 the Current Working Directory and the package file is written out.
1096 Usage: qi create [@var{Output/PackageName.tlz}]...
1099 The argument for the file name to be written must contain a fully
1100 qualified named directory as the output directory where the package
1101 produced will be written. The file name should be composed using the
1102 full name: name-version-architecture-release[@@pkgcategory].tlz
1108 cd claws-mail_3.17.1_amd64-1@@x-apps
1109 qi create /var/cache/qi/packages/claws-mail_3.17.1_amd64-1@@x-apps
1112 In this case, the package "claws-mail_3.17.1_amd64-1@@x-apps" will be
1113 written into @samp{/var/cache/qi/packages/}.
1116 All packages produced are complemented by a checksum file (.sha256).
1119 @node Examining packages
1120 @chapter Examining packages
1121 @cindex package examination
1123 The extraction command serves to examine binary packages for debugging
1124 purposes. It decompresses a package into a single directory, verifying
1125 its integrity and preserving all of it properties (owner and permission).
1128 Usage: qi extract [@var{packagename.tlz}]...
1134 qi extract mksh_R56c_amd64-1@@shells.tlz
1137 This action will put the content of "mksh_R56c_amd64-1@@shells.tlz" into a
1138 single directory, this is a private directory for the user who requested
1139 the action, creation operation will be equal to @strong{u=rwx,g=,o= (0700)}.
1140 The package content will reside on this location, default mask to deploy
1141 the content will be equal to @strong{u=rwx,g=rwx,o=rwx (0000)}.
1144 Note: the creation of the custom directory is influenced by the value
1145 of the @env{TMPDIR} variable.
1149 @chapter Exit status
1152 All the exit codes are described in this chapter.
1156 Successful completion (no errors).
1159 Minor common errors:
1162 @item Help usage on illegal options or required arguments.
1164 @item Program needed by qi (prerequisite) is not available.
1168 Command execution error:
1170 This code is used to return the evaluation of an external command or shell
1171 arguments in case of failure.
1174 Integrity check error for compressed files.
1176 Compressed files means:
1179 @item A tarball file from tar(1).
1180 Supported extensions: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
1183 @item A tarball file from tarlz(1).
1184 Supported extensions: .tar.lz, .tlz
1186 @item Zip files from unzip(1).
1187 Supported extensions: .zip, .ZIP
1189 @item Gzip files from gzip(1).
1190 Supported extensions: .gz, .Z
1192 @item Bzip2 files from bzip2(1).
1193 Supported extension: .bz2
1195 @item Lzip files from lzip(1).
1196 Supported extension: .lz
1198 @item Xz files from xz(1).
1199 Supported extension: .xz
1203 File empty, not regular, or expected.
1205 It's commonly expected:
1208 @item An argument for giving commands.
1210 @item A regular file or readable directory.
1212 @item An expected extension: .tlz, .sha256, .order.
1214 @item A protocol supported by the network downloader tool.
1218 Empty or not defined variable:
1220 This code is used to report empty or undefined variables (usually
1221 variables coming from a recipe or assigned arrays that are tested).
1224 Package already installed:
1226 The package directory for an incoming .tlz package already exists.
1229 Network manager error:
1231 This code is used if the network downloader tool fails for some reason.