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 25 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.
535 Since updating a package can be crucial and so to perform a successful
536 upgrade, from start to finish, you will want to ignore some important
537 system signals during the upgrade process, those signals are SIGHUP,
538 SIGINT, SIGQUIT, SIGABRT, and SIGTERM.
541 To upgrade a package, just type:
544 qi upgrade gcc_9.0.1_i586-1@@devel.tlz
547 This will proceed to upgrade "gcc_9.0.1_i586-1@@devel" removing any other
548 version of "gcc" (if any).
551 If you want to keep the package directories of versions found during the
552 upgrade process, just pass:
555 qi upgrade --keep gcc_9.0.1_i586-1@@devel.tlz
559 To see the upgrade process:
562 qi upgrade --verbose gcc_9.0.1_i586-1@@devel.tlz
565 A second --verbose or -v option gives more (very verbose).
568 To force the upgrade of an existing package:
571 qi upgrade --force gcc_9.0.1_i586-1@@devel.tlz
574 @subsection Package blacklist
575 @cindex package blacklist
577 To implement general package facilities, either to install, remove or
578 maintain the hierarchy of packages in a clean manner, qi makes use of the
579 pruning operation via graft(1) by default:
581 There is a risk if those are crucial packages for the proper functioning
582 of the system, because it implies the deactivation of symbolic from the
583 target directory, @emph{especially} when transitioning an incoming package
584 into its final location during an upgrade.
587 A blacklist of package names has been devised for the case where
588 a user decides to upgrade all the packages in the system, or
589 just the crucial ones, such as the C library.
591 The blacklist is related to the upgrade command only, consists in installing
592 a package instead of updating it or removing previous versions of it;
593 the content of the package will be updated over the existing content at
594 @samp{$@{packagedir@}}, while the existing links from
595 @samp{$@{targetdir@}} will be preserved. A pruning of links will be
596 carried out in order to re-link possible differences with the recent
597 content, this helps to avoid leaving dead links in the target directory.
600 Package names for the blacklist to be declared must be set from the
608 A recipe is a file telling qi what to do. Most often, the recipe tells
609 qi how to build a binary package from a source tarball.
611 A recipe has two parts: a list of variable definitions and a list of
612 sections. By convention, the syntax of a section is:
621 The section name is followed by parentheses, one newline and an opening
622 brace. The line finishing the section contains just a closing brace.
623 The section names or the function names currently recognized are
626 The @samp{build} section (or @strong{shell function}) is an augmented
627 shell script that contains the main instructions for building a software
633 A "variable" is a @strong{shell variable} defined either in @file{qirc}
634 or in a recipe to represent a string of text, called the variable's
635 "value". These values are substituted by explicit request in the
636 definitions of other variables or in calls to external commands.
638 Variables can represent lists of file names, options to pass to
639 compilers, programs to run, directories to look in for source files,
640 directories to write output to, or anything else you can imagine.
642 Definitions of variables in qi have four levels of precedence.
643 Options which define variables from the command-line override those
644 specified in the @file{qirc} file, while variables defined in the recipe
645 override those specified in @file{qirc}, taking priority over those
646 variables set by command-line options. Finally, the variables have
647 default values if they are not defined anywhere.
649 Options that set variables through the command-line can only reference
650 variables defined in @file{qirc} and variables with default values.
652 Definitions of variables in @file{qirc} can only reference variables
653 previously defined in @file{qirc} and variables with default values.
655 Definitions of variables in the recipe can only reference variables
656 set by the command-line, variables previously defined in the recipe,
657 variables defined in @file{qirc}, and variables with default values.
659 @section Special variables
660 @cindex special variables
662 There are variables which can only be set using the command line options or
663 via @file{qirc}, there are other special variables which can be defined or
664 redefined in a recipe. See the following definitions:
666 @samp{outdir} is the directory where the packages produced are written.
667 This variable can be redefined per-recipe. Default sets to
668 @samp{/var/cache/qi/packages}.
670 @samp{worktree} is the working tree where archives, patches, and recipes
671 are expected. This variable can not be redefined in the recipe. Default
672 sets to @samp{/usr/src/qi}.
674 @samp{tardir} is defined in the recipe to the directory where the tarball
675 containing the source can be found. The full name of the tarball is
676 composed as @samp{$@{tardir@}/$tarname}. Its value is available in the
677 recipe as @samp{$@{tardir@}}; a value of . for @samp{tardir} sets it to
678 the value of CWD (Current Working Directory), this is where the recipe
681 @samp{arch} is the architecture to compose the package name. Its value is
682 available in the recipe as @samp{$@{arch@}}. Default value is the one
683 that was set in the Qi configuration.
685 @samp{jobs} is the number of parallel jobs to pass to the compiler. Its
686 value is available in the recipe as @samp{$@{jobs@}}. The default value
689 The two variables @samp{$@{srcdir@}} and @samp{$@{destdir@}} can be
690 set in the recipe, as any other variable, but if they are not, qi uses
691 default values for them when building a package.
693 @samp{srcdir} contains the source code to be compiled, and defaults to
694 @samp{$@{program@}-$@{version@}}. @samp{destdir} is the place where the
695 built package will be installed, and defaults to
696 @samp{$@{TMPDIR@}/package-$@{program@}}.
698 If @samp{pkgname} is left undefined, the special variable @samp{program}
699 is assigned by default. If @samp{pkgversion} is left undefined, the
700 special variable @samp{version} is assigned by default.
702 @samp{pkgname} and @samp{pkgversion} along with: @samp{version}, @samp{arch},
703 @samp{release}, and (optionally) @samp{pkgcategory} are used to produce the
704 package name in the form:
705 @samp{$@{pkgname@}_$@{pkgversion@}_$@{arch@}-$@{release@}[@@$@{pkgcategory@}].tlz}
707 @samp{pkgcategory} is an optional special variable that can be defined on the
708 recipe to categorize the package name. If it is defined, then the
709 package output will be composed as
710 @samp{$@{pkgname@}_$@{pkgversion@}_$@{arch@}-$@{release@}[@@$@{pkgcategory@}.tlz}.
711 Automatically, the value of @samp{pkgcategory} will be prefixed using the
712 @samp{@@} (at) symbol which will be added to the last part of the package name.
714 A special variable called @samp{replace} can be used to declare package names
715 that will be replaced at installation time.
717 The special variables @samp{keep_srcdir} and @samp{keep_destdir} are provided
718 in order to preserve the directories @samp{$@{srcdir@}} or @samp{$@{destdir@}},
719 if those exists as such. Note: The declaration of these variables are subject
720 to manual deactivation; its purpose in recipes is to preserve the directories
721 that relate to the package's build (source) and destination directory, that is
722 so that another recipe can get a new package (or meta package) from there. For
723 example, the declarations can be done as:
726 keep_srcdir=keep_srcdir
727 keep_destdir=keep_destdir
730 Then from another recipe you would proceed to copy the necessary files that
731 will compose the meta package, from the main function you must deactivate
732 the variables at the end:
739 This will leave the 'keep_srcdir' and 'keep_destdir' variables blank to
740 continue with the rest of the recipes.
743 A typical recipe contains the following variables:
746 @item @samp{program}: Software name.
748 It matches the source name. It is also used to compose the name of the
749 package if @samp{$@{pkgname@}} is not specified.
751 @item @samp{version}: Software version.
753 It matches the source name. It is also used to compose the version of the
754 package if @samp{$@{pkgversion@}} is not specified.
756 @item @samp{arch}: Software architecture.
758 It is used to compose the architecture of the package in which it is
761 @item @samp{release}: Release number.
763 This is used to reflect the release number of the package. It is
764 recommended to increase this number after any significant change in
765 the recipe or post-install script.
767 @item @samp{pkgcategory}: Package category.
769 Optional but recommended variable to categorize the package name when it is
774 Obtaining sources over the network must be declared in the recipe using
775 the @samp{fetch} variable.
777 The variables @samp{netget} and @samp{rsync} can be defined in @file{qirc}
778 to establish a network downloader in order to get the sources. If they
779 are not defined, qi uses default values:
781 @samp{netget} is the general network downloader tool, defaults sets to
782 @samp{wget -c -w1 -t3 --no-check-certificate}.
784 @samp{rsync} is the network tool for sources containing the prefix for
785 the RSYNC protocol, default sets to
786 @samp{rsync -v -a -L -z -i --progress}.
788 The variable @samp{description} is used to print the package description
789 when a package is installed.
791 A description has two parts: a brief description, and a long description.
792 By convention, the syntax of @samp{description} is:
802 The first line of the value represented is a brief description of the
803 software (called "blurb"). A blank line separates the @emph{brief
804 description} from the @emph{long description}, which should contain a more
805 descriptive description of the software.
808 An example looks like:
812 The GNU core utilities.
814 The GNU core utilities are the basic file, shell and text manipulation
815 utilities of the GNU operating system. These are the core utilities
816 which are expected to exist on every operating system.
820 Please consider a length limit of 78 characters as maximum, because the same
821 one would be used on the meta file creation. See
822 @ref{Recipes, The meta file} section.
824 The @samp{homepage} variable is used to declare the main site or home page:
827 homepage=http://www.gnu.org/software/gcc
830 The variable @samp{license} is used for license information@footnote{
831 The proposal for @samp{license} was made by Richard M. Stallman at
832 @url{http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html}.}.
833 Some code in the program can be covered by license A, license B, or
834 license C. For "separate licensing" or "heterogeneous licensing", we
835 suggest using @strong{|} for a disjunction, @strong{&} for a conjunction
836 (if that ever happens in a significant way), and comma for heterogeneous
837 licensing. Comma would have lower precedence, plus added special terms.
840 license="LGPL, GPL | Artistic - added permission"
843 @section Writing recipes
844 @cindex writing recipes
846 Originally, Qi was designed for the version 3 of Dragora GNU/Linux; this
847 doesn't mean you can't use it in another distribution, just that if you do,
848 you'll have to try it out for yourself. To help with this, here are some
849 references to well-written recipes:
852 @item @url{http://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes}
853 @item @url{http://notabug.org/dragora/dragora/src/master/recipes}
856 @section Building packages
857 @cindex package build
859 A recipe is any valid regular file. Qi sets priorities for reading a
860 recipe, the order in which qi looks for a recipe is:
864 Current working directory.
867 If the specified path name does not contain "recipe" as the last
868 component. Qi will complete it by adding "recipe" to the path name.
871 If the recipe is not in the current working directory, it will be
872 searched under @samp{$@{worktree@}/recipes}. The last component will be
873 completed adding "recipe" to the specified path name.
877 To build a single package, type:
880 qi build x-apps/xterm
884 Multiple jobs can be passed to the compiler to speed up the build process:
887 qi build --jobs 3 x-apps/xterm
891 Update or install the produced package (if not already installed) when the
895 qi build -j3 --upgrade x-apps/xterm
899 Only process a recipe but do not create the binary package:
902 qi build --no-package dict/aspell
905 The options --install or --upgrade have no effect when --no-package
909 This can be useful to inspect the build process of recipe:
911 qi build --keep --no-package dict/aspell 2>&1 | tee aspell-log.txt
913 The --keep option could preserve the source directory and the destination
914 directory for later inspection. A log file of the build process will be
915 created redirecting both, standard error and standard output to tee(1).
917 @section Variables from the environment
918 @cindex environment variables
920 Qi has environment variables which can be used at build time:
922 The variable @env{TMPDIR} sets the temporary directory for sources, which is
923 used for package extractions (see @ref{Examining packages}) and is
924 prepended to the value of @samp{$@{srcdir@}} and @samp{$@{destdir@}} in
925 build command. By convention its default value is equal to
926 @samp{/usr/src/qi/build}.
928 The variables @env{QICFLAGS}, @env{QICXXFLAGS}, and @env{QILDFLAGS} have
929 no effect by default. The environment variables such as @env{CFLAGS},
930 @env{CXXFLAGS}, and @env{LDFLAGS} are unset at compile time:
933 Recommended practice is to set variables in the command line of
934 @samp{configure} or @emph{make(1)} instead of exporting to the
935 environment. As follows:
937 @url{http://www.gnu.org/software/make/manual/html_node/Environment.html}
939 It is not wise for makefiles to depend for their functioning on environment
940 variables set up outside their control, since this would cause different
941 users to get different results from the same makefile. This is against the
942 whole purpose of most makefiles.
945 Setting environment variables for configure is deprecated because running
946 configure in varying environments can be dangerous.
948 @url{http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html}
950 Variables not defined in a site shell script can be set in the environment
951 passed to configure. However, some packages may run configure again
952 during the build, and the customized values of these variables may be
953 lost. In order to avoid this problem, you should set them in the
954 configure command line, using @samp{VAR=value}. For example:
956 @code{./configure CC=/usr/local2/bin/gcc}
959 @url{http://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html}
961 If for instance the user runs @samp{CC=bizarre-cc ./configure}, then the cache,
962 config.h, and many other output files depend upon bizarre-cc being the C
963 compiler. If for some reason the user runs ./configure again, or if it is
964 run via @samp{./config.status --recheck}, (See Automatic Remaking, and see
965 config.status Invocation), then the configuration can be inconsistent,
966 composed of results depending upon two different compilers.
968 Indeed, while configure can notice the definition of CC in @samp{./configure
969 CC=bizarre-cc}, it is impossible to notice it in @samp{CC=bizarre-cc
970 ./configure}, which, unfortunately, is what most users do.
972 configure: error: changes in the environment can compromise the build.
975 @section The meta file
976 @cindex the meta file
978 The "meta file" is a regular file created during the build command, it
979 contains information about the package such as package name, package
980 version, architecture, release, fetch address, description, and other
981 minor data extracted from processed recipes. The name of the file is
982 generated as @samp{$@{full_pkgname@}.tlz.txt}, and its purpose is to
983 reflect essential information to the user without having to look inside
984 the package content. The file format is also intended to be used by
985 other scripts or by common Unix tools.
987 The content of a meta file looks like:
991 # Pattern scanning and processing language.
993 # The awk utility interprets a special-purpose programming language
994 # that makes it possible to handle simple data-reformatting jobs
995 # with just a few lines of code. It is a free version of 'awk'.
997 # GNU awk implements the AWK utility which is part of
998 # IEEE Std 1003.1 Shell and Utilities (XCU).
1002 QICXXFLAGS="-g0 -Os"
1009 full_pkgname=gawk_5.0.1_amd64-1@@tools
1010 blurb="Pattern scanning and processing language."
1011 homepage="http://www.gnu.org/software/gawk"
1013 fetch="http://ftp.gnu.org/gnu/gawk/gawk-5.0.1.tar.lz"
1017 Package descriptions are extracted from the variable @samp{description}
1018 where each line is interpreted literally and pre-formatted to fit in
1019 (exactly) @strong{80 columns}, plus the character @samp{#} and a blank
1020 space is prefixed to every line (shell comments).
1023 In addition to the Special variables, there are implicit variables such as
1026 The @samp{blurb} variable is related to the special variable
1027 @samp{description}. Its value is made from the first (substantial)
1028 line of @samp{description}, mentioned as the "brief description".
1032 @chapter Order files
1033 @cindex handling build order
1035 The order command has the purpose of resolving the build order through
1036 .order files. An order file contains a list of recipe names, by default
1037 does not perform any action other than to print a resolved list in
1038 descending order. For example, if @strong{a} depends on @strong{b} and
1039 @strong{c}, and @strong{c} depends on @strong{b} as well, the file might
1048 Each letter represents a recipe name, complete dependencies for
1049 the first recipe name are listed in descending order, which is
1050 printed from right to left, and removed from left to right:
1060 Blank lines, colons and parentheses are simply ignored. Comment lines
1061 beginning with @samp{#} are allowed.
1064 An order file could be used to build a series of packages, for example,
1068 # Image handling libraries
1070 libs/libjpeg-turbo: devel/nasm
1071 x-libs/jasper: libs/libjpeg-turbo
1072 libs/tiff: libs/libjpeg-turbo
1075 To proceed with each recipe, we can type:
1078 qi order imglibs.order | qi build --install -
1081 The output of @samp{qi order imglibs.order} tells to qi in which order it
1082 should build the recipes:
1092 @node Creating packages
1093 @chapter Creating packages
1094 @cindex package creation
1096 The creation command is an internal function of qi to make new Qi
1097 compatible packages. A package is produced using the contents of
1098 the Current Working Directory and the package file is written out.
1101 Usage: qi create [@var{Output/PackageName.tlz}]...
1104 The argument for the file name to be written must contain a fully
1105 qualified named directory as the output directory where the package
1106 produced will be written. The file name should be composed using the
1107 full name: name-version-architecture-release[@@pkgcategory].tlz
1113 cd claws-mail_3.17.1_amd64-1@@x-apps
1114 qi create /var/cache/qi/packages/claws-mail_3.17.1_amd64-1@@x-apps
1117 In this case, the package "claws-mail_3.17.1_amd64-1@@x-apps" will be
1118 written into @samp{/var/cache/qi/packages/}.
1121 All packages produced are complemented by a checksum file (.sha256).
1124 @node Examining packages
1125 @chapter Examining packages
1126 @cindex package examination
1128 The extraction command serves to examine binary packages for debugging
1129 purposes. It decompresses a package into a single directory, verifying
1130 its integrity and preserving all of it properties (owner and permission).
1133 Usage: qi extract [@var{packagename.tlz}]...
1139 qi extract mksh_R56c_amd64-1@@shells.tlz
1142 This action will put the content of "mksh_R56c_amd64-1@@shells.tlz" into a
1143 single directory, this is a private directory for the user who requested
1144 the action, creation operation will be equal to @strong{u=rwx,g=,o= (0700)}.
1145 The package content will reside on this location, default mask to deploy
1146 the content will be equal to @strong{u=rwx,g=rwx,o=rwx (0000)}.
1149 Note: the creation of the custom directory is influenced by the value
1150 of the @env{TMPDIR} variable.
1154 @chapter Exit status
1157 All the exit codes are described in this chapter.
1161 Successful completion (no errors).
1164 Minor common errors:
1167 @item Help usage on illegal options or required arguments.
1169 @item Program needed by qi (prerequisite) is not available.
1173 Command execution error:
1175 This code is used to return the evaluation of an external command or shell
1176 arguments in case of failure.
1179 Integrity check error for compressed files.
1181 Compressed files means:
1184 @item A tarball file from tar(1).
1185 Supported extensions: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
1188 @item A tarball file from tarlz(1).
1189 Supported extensions: .tar.lz, .tlz
1191 @item Zip files from unzip(1).
1192 Supported extensions: .zip, .ZIP
1194 @item Gzip files from gzip(1).
1195 Supported extensions: .gz, .Z
1197 @item Bzip2 files from bzip2(1).
1198 Supported extension: .bz2
1200 @item Lzip files from lzip(1).
1201 Supported extension: .lz
1203 @item Xz files from xz(1).
1204 Supported extension: .xz
1208 File empty, not regular, or expected.
1210 It's commonly expected:
1213 @item An argument for giving commands.
1215 @item A regular file or readable directory.
1217 @item An expected extension: .tlz, .sha256, .order.
1219 @item A protocol supported by the network downloader tool.
1223 Empty or not defined variable:
1225 This code is used to report empty or undefined variables (usually
1226 variables coming from a recipe or assigned arrays that are tested).
1229 Package already installed:
1231 The package directory for an incoming .tlz package already exists.
1234 Network manager error:
1236 This code is used if the network downloader tool fails for some reason.