3 @c This is part of the Qi user guide.
4 @c Copyright (C) 2019-2022 Matias Fonzo, <selk@dragora.org>.
5 @c See the file qi-header.texi for copying conditions.
7 @c If something is modified here, be aware of the increase of VERSION in
8 @c qi-header.texi, this will produce the result of the manual: qi.info
10 @node Introduction to Qi
11 @chapter Introduction to Qi
12 @cindex introduction to qi
14 Qi is a simple but well-integrated package manager. It can create,
15 install, remove, and upgrade software packages. Qi produces binary
16 packages using recipes, which are files containing specific instructions
17 to build each package from source. Qi can manage multiple packages
18 under a single directory hierarchy. This method allows to maintain a set
19 of packages and multiple versions of them. This means that Qi could be
20 used as the main package manager or complement the existing one.
22 Qi offers a friendly command line interface, a global configuration
23 file, a simple recipe layout to deploy software packages; also works
24 with binary packages in parallel, speeding up installations and packages
25 in production. The format used for packages is a simplified and safer
26 variant of POSIX pax archive compressed in lzip format.
28 Qi is a modern (POSIX-compliant) shell script released under the
29 terms of the GNU General Public License. There are only two major
30 dependencies for the magic: graft(1) and tarlz(1), the rest is expected
31 to be found in any Unix-like system.
37 This chapter describes the synopsis for invoking Qi.
40 Usage: qi COMMAND [@var{OPTION}...] [@var{FILE}]...
44 One mandatory command specifies the operation that @samp{qi} should
45 perform, options are meant to detail how this operation should be
46 performed during or after the process.
49 Qi supports the following commands:
53 Warn about files that will be installed.
65 Extract packages for debugging purposes.
68 Create a .tlz package from directory.
71 Build packages using recipe names.
74 Resolve build order through .order files
78 Options when installing, removing, or upgrading software packages:
83 Force upgrade of pre-existing packages.
87 Keep directories when build/remove/upgrade.
89 Keep (don't delete) the package directory when using remove/upgrade command.
91 This will also try to preserve the directories @samp{$@{srcdir@}} and
92 @samp{$@{destdir@}} when using build command. Its effect is available in
93 recipes as @samp{$@{keep_srcdir@}} and @samp{$@{keep_destdir@}}. See
94 @ref{Recipes, Special variables} for details.
101 @itemx --packagedir=<dir>
102 Set directory for package installations.
105 @itemx --targetdir=<dir>
106 Set target directory for symbolic links.
109 @itemx --rootdir=<dir>
110 Use the fully qualified named directory as the root directory for all qi
113 Note: the target directory and the package directory will be
114 relative to the specified directory, excepting the graft log file.
118 Options when building software packages using recipes:
122 @itemx --architecture
123 Set architecture name for the package.
127 Parallel jobs for the compiler.
129 This option sets the variable @samp{$@{jobs@}}. If not specified, default
133 @itemx --skip-questions
134 Skip questions on completed recipes.
138 Increment release number (@samp{$@{release@}} + 1).
140 The effect of this option will be omitted if --no-package is being used.
144 Do not create a .tlz package.
148 Install package after the build.
152 Upgrade package after the build.
155 @itemx --outdir=<dir>
156 Where the packages produced will be written.
158 This option sets the variable @samp{$@{outdir@}}.
161 @itemx --worktree=<dir>
162 Where archives, patches, recipes are expected.
164 This option sets the variable @samp{$@{worktree@}}.
167 @itemx --sourcedir=<dir>
168 Where compressed sources will be found.
170 This option sets the variable @samp{$@{tardir@}}.
179 Be verbose (an extra -v gives more).
181 It sets the verbosity level, default sets to 0.
183 The value 1 is used for more verbosity while the value 2 is too detailed.
184 Although at the moment it is limited to graft(1) verbosity.
188 Do not read the configuration file.
190 This will ignore reading the qirc file.
193 @itemx --show-location
194 Print default directory locations and exit.
196 This will print the target directory, package directory, working tree,
197 the directory for sources, and the output directory for the packages
198 produced. The output will appear on STDOUT as follows:
201 QI_TARGETDIR=/usr/local
202 QI_PACKAGEDIR=/usr/local/pkgs
203 QI_WORKTREE=/usr/src/qi
204 QI_TARDIR=/usr/src/qi/sources
205 QI_OUTDIR=/var/cache/qi/packages
208 You can set these environment variables using one of the following methods:
210 @code{eval "$(qi -L)"}
212 This will display the default locations taking into account the values set
213 from the qirc configuration file. You can deny the influence of the
214 configuration file by setting the option @samp{-N}.
216 @code{eval "$(qi -N -L)"}
218 Or you can adjust the new locations using the command-line options, e.g:
220 @code{eval "$(qi -N --targetdir=/directory -L)"}
224 Display the usage and exit.
229 This will print the (short) version information and then exit.
231 The same can be achieved if Qi is invoked as @samp{qi version}.
234 When FILE is -, qi can read from the standard input. See examples from
235 the @ref{Packages} section.
237 Exit status: 0 for a normal exit, 1 for minor common errors (help usage,
238 support not available, etc), 2 to indicate a command execution error;
239 3 for integrity check error on compressed files, 4 for empty, not
240 regular, or expected files, 5 for empty or not defined variables,
241 6 when a package already exist, 10 for network manager errors.
242 For more details, see the @ref{Qi exit status} section.
246 @chapter The qirc file
247 @cindex configuration file
249 The global @file{qirc} file offers a way to define variables and tools
250 (such as a download manager) for default use. This file is used by qi
251 at runtime, e.g., to build, install, remove or upgrade packages.
253 Variables and their possible values must be declared as any other
254 variable in the shell.
257 The command line options related to the package directory and target
258 directory and some of the command line options used for the build command,
259 have the power to override the values declared on @file{qirc}.
260 See @ref{Invoking qi}.
263 The order in which qi looks for this file is:
267 @env{$@{HOME@}/.qirc}
271 @samp{$@{sysconfdir@}/qirc}
275 If you intend to run qi as effective user, the file
276 @samp{$@{sysconfdir@}/qirc} could be copied to @env{$@{HOME@}/.qirc}
277 setting the paths for @samp{$@{packagedir@}} and @samp{$@{targetdir@}}
278 according to the @env{$HOME}.
283 @cindex managing packages
285 A package is a suite of programs usually distributed in binary form
286 which may also contain manual pages, documentation, or any other file
287 associated to a specific software.
289 The package format used by qi is a simplified POSIX pax archive
290 compressed using lzip@footnote{For more details about tarlz and the
291 lzip format, visit @url{https://lzip.nongnu.org/tarlz.html}.}. The
292 file extension for packages ends in @samp{.tlz}.
295 Both package installation and package de-installation are managed using
296 two important (internal) variables: @samp{$@{packagedir@}} and
297 @samp{$@{targetdir@}}, these values can be changed in the
298 configuration file or via options.
300 @samp{$@{packagedir@}} is a common directory tree where the package
301 contents will be decompressed (will reside).
303 @samp{$@{targetdir@}} is a target directory where the links will be
304 made by graft(1) taking @samp{$@{packagedir@}/package_name} into account.
307 Packages are installed in self-contained directory trees and symbolic
308 links from a common area are made to the package files. This allows
309 multiple versions of the same package to coexist on the same system.
311 @section Package conflicts
312 @cindex package conflicts
314 All the links to install or remove a package are handled by graft(1).
315 Since multiple packages can be installed or removed at the same time,
316 certain conflicts may arise between the packages.
319 graft@footnote{The official guide for Graft can be found at
320 @url{https://peters.gormand.com.au/Home/tools/graft/graft.html}.}
321 defines a CONFLICT as one of the following conditions:
325 If the package object is a directory and the target object exists but is
329 If the package object is not a directory and the target object exists
330 and is not a symbolic link.
333 If the package object is not a directory and the target object exists
334 and is a symbolic link to something other than the package object.
338 The default behavior of qi for an incoming package is to ABORT if a
339 conflict arises. When a package is going to be deleted, qi tells to
340 graft(1) to remove those parts that are not in conflict, leaving the
341 links to the belonging package. This behavior can be forced if the
342 --prune option is given.
344 @section Installing packages
345 @cindex package installation
347 To install a single package, simply type:
350 qi install coreutils_8.30_i586-1@@tools.tlz
354 To install multiple packages at once, type:
357 qi install gcc_8.3.0_i586-1@@devel.tlz rafaela_2.2_i586-1@@legacy.tlz ...
361 Warn about the files that will be linked:
364 qi warn bash_5.0_i586-1@@shells.tlz
367 This is to verify the content of a package before installing it.
370 See the process of an installation:
373 qi install --verbose mariana_3.0_i586-1@@woman.tlz
376 A second --verbose or -v option gives more (very verbose).
379 Installing package in a different location:
382 qi install --rootdir=/media/floppy lzip_1.21_i586-1@@compressors.tlz
385 Important: the --rootdir option assumes @samp{$@{targetdir@}} and
386 @samp{$@{packagedir@}}. See the following example:
389 qi install --rootdir=/home/selk lzip_1.21_i586-1@@compressors.tlz
392 The content of "lzip_1.21_i586-1@@compressors.tlz" will be decompressed
393 into @samp{/home/selk/pkgs/lzip_1.21_i586-1@@compressors}.
394 Assuming that the main binary for lzip is under
395 @samp{/home/selk/pkgs/lzip_1.21_i586-1@@compressors/usr/bin/}
396 the target for "usr/bin" will be created at @samp{/home/selk}. Considering
397 that you have exported the @env{PATH} as @samp{$@{HOME@}/usr/bin}, now the
398 system is able to see the recent lzip command.
401 Installing from a list of packages using standard input:
404 qi install - < PACKAGELIST.txt
407 Or in combination with another tool:
409 sort -u PACKAGELIST.txt | qi install -
412 The sort command will read and sorts the list of declared packages,
413 while trying to have unique entries for each statement. The output
414 produced is captured by Qi to install each package.
416 An example of a list containing package names is:
418 /var/cache/qi/packages/amd64/tcl_8.6.9_amd64-1@@devel.tlz
419 /var/cache/qi/packages/amd64/tk_8.6.9.1_amd64-1@@devel.tlz
420 /var/cache/qi/packages/amd64/vala_0.42.3_amd64-1@@devel.tlz
423 @section Removing packages
424 @cindex package de-installation
426 To remove a package, simply type:
429 qi remove xz_5.2.4_i586-1@@compressors.tlz
433 Remove command will match the package name using @samp{$@{packagedir@}} as
434 prefix. For example, if the value of @samp{$@{packagedir@}} has been
435 set to /usr/pkg, this will be equal to:
438 qi remove /usr/pkg/xz_5.2.4_i586-1@@compressors
445 qi remove --verbose /usr/pkg/xz_5.2.4_i586-1@@compressors
448 A second --verbose or -v option gives more (very verbose).
451 By default the remove command does not preserve a package directory after
452 removing its links from @samp{$@{targetdir@}}, but this behavior can be
453 changed if the --keep option is passed:
456 qi remove --keep /usr/pkg/lzip_1.21_i586-1@@compressors
459 This means that the links to the package can be reactivated, later:
462 cd /usr/pkg && graft -i lzip_1.21_i586-1@@compressors
466 Removing package from a different location:
469 qi remove --rootdir=/home/cthulhu xz_5.2.4_i586-1@@compressors
473 Removing a package using standard input:
476 echo vala_0.42.3_amd64-1@@devel | qi remove -
479 This will match with the package directory.
481 @section Upgrading packages
482 @cindex package upgrade
484 The upgrade command inherits the properties of the installation and removal
485 process. To make sure that a package is updated, the package is installed
486 in a temporary directory taking @samp{$@{packagedir@}} into account. Once
487 the incoming package is pre-installed, qi can proceed to search and delete
488 packages that have the same name (considered as previous ones). Finally,
489 the package is re-installed at its final location and the temporary
490 directory is removed.
492 Since updating a package can be crucial and so to perform a successful
493 upgrade, from start to finish, you will want to ignore some important
494 system signals during the upgrade process, those signals are SIGHUP,
495 SIGINT, SIGQUIT, SIGABRT, and SIGTERM.
498 To upgrade a package, just type:
501 qi upgrade gcc_9.0.1_i586-1@@devel.tlz
504 This will proceed to upgrade "gcc_9.0.1_i586-1@@devel" removing any other
505 version of "gcc" (if any).
508 If you want to keep the package directories of versions found during the
509 upgrade process, just pass:
512 qi upgrade --keep gcc_9.0.1_i586-1@@devel.tlz
516 To see the upgrade process:
519 qi upgrade --verbose gcc_9.0.1_i586-1@@devel.tlz
522 A second --verbose or -v option gives more (very verbose).
525 To force the upgrade of an existing package:
528 qi upgrade --force gcc_9.0.1_i586-1@@devel.tlz
531 @subsection Package blacklist
532 @cindex package blacklist
534 To implement general package facilities, either to install, remove or
535 maintain the hierarchy of packages in a clean manner, qi makes use of the
536 pruning operation via graft(1) by default:
538 There is a risk if those are crucial packages for the proper functioning
539 of the system, because it implies the deactivation of symbolic from the
540 target directory, @emph{especially} when transitioning an incoming package
541 into its final location during an upgrade.
544 A blacklist of package names has been devised for the case where
545 a user decides to upgrade all the packages in the system, or
546 just the crucial ones, such as the C library.
548 The blacklist is related to the upgrade command only, consists in installing
549 a package instead of updating it or removing previous versions of it;
550 the content of the package will be updated over the existing content at
551 @samp{$@{packagedir@}}, while the existing links from
552 @samp{$@{targetdir@}} will be preserved. A pruning of links will be
553 carried out in order to re-link possible differences with the recent
554 content, this helps to avoid leaving dead links in the target directory.
557 Package names for the blacklist to be declared must be set from the
558 configuration file. By default, it is declared using the package name,
559 which is more than enough for critical system packages, but if you want to
560 be more specific, you can declare a package using:
561 @samp{$@{pkgname@}_$@{pkgversion@}_$@{arch@}-$@{release@}} where
562 the package category is avoided for common matching. See
563 @ref{Recipes, Special variables} for a description of these variables.
569 A recipe is a file telling qi what to do. Most often, the recipe tells
570 qi how to build a binary package from a source tarball.
572 A recipe has two parts: a list of variable definitions and a list of
573 sections. By convention, the syntax of a section is:
582 The section name is followed by parentheses, one newline and an opening
583 brace. The line finishing the section contains just a closing brace.
584 The section names or the function names currently recognized are
587 The @samp{build} section (or @strong{shell function}) is an augmented
588 shell script that contains the main instructions to build software
591 If there are other functions defined by the packager, Qi detects them
597 A "variable" is a @strong{shell variable} defined either in @file{qirc}
598 or in a recipe to represent a string of text, called the variable's
599 "value". These values are substituted by explicit request in the
600 definitions of other variables or in calls to external commands.
602 Variables can represent lists of file names, options to pass to
603 compilers, programs to run, directories to look in for source files,
604 directories to write output to, or anything else you can imagine.
606 Definitions of variables in qi have four levels of precedence.
607 Options which define variables from the command-line override those
608 specified in the @file{qirc} file, while variables defined in the recipe
609 override those specified in @file{qirc}, taking priority over those
610 variables set by command-line options. Finally, the variables have
611 default values if they are not defined anywhere.
613 Options that set variables through the command-line can only reference
614 variables defined in @file{qirc} and variables with default values.
616 Definitions of variables in @file{qirc} can only reference variables
617 previously defined in @file{qirc} and variables with default values.
619 Definitions of variables in the recipe can only reference variables
620 set by the command-line, variables previously defined in the recipe,
621 variables defined in @file{qirc}, and variables with default values.
623 @section Special variables
624 @cindex special variables
626 There are variables which can only be set using the command line options or
627 via @file{qirc}, there are other special variables which can be defined or
628 redefined in a recipe. See the following definitions:
630 @samp{outdir} is the directory where the packages produced are written.
631 This variable can be redefined per-recipe. Default sets to
632 @samp{/var/cache/qi/packages}.
634 @samp{worktree} is the working tree where archives, patches, and recipes
635 are expected. This variable can not be redefined in the recipe. Default
636 sets to @samp{/usr/src/qi}.
638 @samp{tardir} is defined in the recipe to the directory where the tarball
639 containing the source can be found. The full name of the tarball is
640 composed as @samp{$@{tardir@}/$tarname}. Its value is available in the
641 recipe as @samp{$@{tardir@}}; a value of . for @samp{tardir} sets it to
642 the value of CWD (Current Working Directory), this is where the recipe
645 @samp{arch} is the architecture to compose the package name. Its value is
646 available in the recipe as @samp{$@{arch@}}. Default value is the one
647 that was set in the Qi configuration.
649 @samp{jobs} is the number of parallel jobs to pass to the compiler. Its
650 value is available in the recipe as @samp{$@{jobs@}}. The default value
653 The two variables @samp{$@{srcdir@}} and @samp{$@{destdir@}} can be
654 set in the recipe, as any other variable, but if they are not, qi uses
655 default values for them when building a package.
657 @samp{srcdir} contains the source code to be compiled, and defaults to
658 @samp{$@{program@}-$@{version@}}. @samp{destdir} is the place where the
659 built package will be installed, and defaults to
660 @samp{$@{TMPDIR@}/package-$@{program@}}.
662 If @samp{pkgname} is left undefined, the special variable @samp{program}
663 is assigned by default. If @samp{pkgversion} is left undefined, the
664 special variable @samp{version} is assigned by default.
666 @samp{pkgname} and @samp{pkgversion} along with: @samp{version}, @samp{arch},
667 @samp{release}, and (optionally) @samp{pkgcategory} are used to produce the
668 package name in the form:
669 @samp{$@{pkgname@}_$@{pkgversion@}_$@{arch@}-$@{release@}[@@$@{pkgcategory@}].tlz}
671 @samp{pkgcategory} is an optional special variable that can be defined on the
672 recipe to categorize the package name. If it is defined, then the
673 package output will be composed as
674 @samp{$@{pkgname@}_$@{pkgversion@}_$@{arch@}-$@{release@}[@@$@{pkgcategory@}.tlz}.
675 Automatically, the value of @samp{pkgcategory} will be prefixed using the
676 @samp{@@} (at) symbol which will be added to the last part of the package name.
678 A special variable called @samp{replace} can be used to declare package names
679 that will be replaced at installation time.
681 The special variables @samp{keep_srcdir} and @samp{keep_destdir} are provided
682 in order to preserve the directories @samp{$@{srcdir@}} or @samp{$@{destdir@}},
683 if those exists as such. Note: The declaration of these variables are subject
684 to manual deactivation; its purpose in recipes is to preserve the directories
685 that relate to the package's build (source) and destination directory, that is
686 so that another recipe can get a new package (or meta package) from there. For
687 example, the declarations can be done as:
690 keep_srcdir=keep_srcdir
691 keep_destdir=keep_destdir
694 Then from another recipe you would proceed to copy the necessary files that
695 will compose the meta package, from the main function you must deactivate
696 the variables at the end:
699 unset -v keep_srcdir keep_destdir
702 This will leave the 'keep_srcdir' and 'keep_destdir' variables blank to
703 continue with the rest of the recipes.
705 The special variable @samp{opt_skiprecipe} is available when you need to
706 ignore a recipe cleanly, continuing with the next recipe. May you add a
707 conditional test then set it as @samp{opt_skiprecipe=opt_skiprecipe}.
709 The variable @samp{tarlz_compression_options} can be used to change the
710 default compression options in tarlz(1), default sets to @samp{-9 --solid}.
711 For example if the variable is declared as:
714 tarlz_compression_options="-0 --bsolid"
717 It will change the granularity of tarlz(1) by using the @samp{--bsolid}
718 option @footnote{About the @samp{--bsolid} granularity option of tarlz(1),
719 @url{https://www.nongnu.org/lzip/manual/tarlz_manual.html#g_t_002d_002dbsolid}.},
720 as well as increasing the compression speed by lowering the compression
721 level with @samp{-0}.
723 This is only recommended for recipes where testing, or faster processing is
724 desired to create the packaged file more quickly. It is not recommended for
725 production or general distribution of binary packages.
728 A typical recipe contains the following variables:
731 @item @samp{program}: Software name.
733 It matches the source name. It is also used to compose the name of the
734 package if @samp{$@{pkgname@}} is not specified.
736 @item @samp{version}: Software version.
738 It matches the source name. It is also used to compose the version of the
739 package if @samp{$@{pkgversion@}} is not specified.
741 @item @samp{arch}: Software architecture.
743 It is used to compose the architecture of the package in which it is
746 @item @samp{release}: Release number.
748 This is used to reflect the release number of the package. It is
749 recommended to increase this number after any significant change in
750 the recipe or post-install script.
752 @item @samp{pkgcategory}: Package category.
754 Optional but recommended variable to categorize the package name when it is
759 Obtaining sources over the network must be declared in the recipe using
760 the @samp{fetch} variable.
762 The variables @samp{netget} and @samp{rsync} can be defined in @file{qirc}
763 to establish a network downloader in order to get the sources. If they
764 are not defined, qi uses default values:
766 @samp{netget} is the general network downloader tool, defaults sets to
767 @samp{wget2 -c -w1 -t3 --no-check-certificate}.
769 @samp{rsync} is the network tool for sources containing the prefix for
770 the RSYNC protocol, default sets to
771 @samp{rsync -v -a -L -z -i --progress}.
773 The variable @samp{description} is used to print the package description
774 when a package is installed.
776 A description has two parts: a brief description, and a long description.
777 By convention, the syntax of @samp{description} is:
787 The first line of the value represented is a brief description of the
788 software (called "blurb"). A blank line separates the @emph{brief
789 description} from the @emph{long description}, which should contain a more
790 descriptive description of the software.
793 An example looks like:
797 The GNU core utilities.
799 The GNU core utilities are the basic file, shell and text manipulation
800 utilities of the GNU operating system. These are the core utilities
801 which are expected to exist on every operating system.
805 Please consider a length limit of 78 characters as maximum, because the same
806 one would be used on the meta file creation. See
807 @ref{Recipes, The meta file} section.
809 The @samp{homepage} variable is used to declare the main site or home page:
812 homepage=https://www.gnu.org/software/gcc
815 The variable @samp{license} is used for license information@footnote{
816 The proposal for @samp{license} was made by Richard M. Stallman at
817 @url{https://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html}.}.
818 Some code in the program can be covered by license A, license B, or
819 license C. For "separate licensing" or "heterogeneous licensing", we
820 suggest using @strong{|} for a disjunction, @strong{&} for a conjunction
821 (if that ever happens in a significant way), and comma for heterogeneous
822 licensing. Comma would have lower precedence, plus added special terms.
825 license="LGPL, GPL | Artistic - added permission"
828 @section Writing recipes
829 @cindex writing recipes
831 Originally, Qi was designed for the series of Dragora GNU/Linux-Libre 3;
832 this doesn't mean you can't use it in another distribution, just that if
833 you do, you'll have to try it out for yourself. To help with this, here
834 are some references to well-written recipes:
837 @item @url{https://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes}
838 @item @url{https://notabug.org/dragora/dragora/src/master/recipes}
839 @item @url{https://notabug.org/dragora/dragora-extras/src/master/recipes}
840 @item @url{https://git.savannah.nongnu.org/cgit/dragora/dragora-extras.git/tree/recipes}
843 @section Building packages
844 @cindex package build
846 A recipe is any valid regular file. Qi sets priorities for reading a
847 recipe, the order in which qi looks for a recipe is:
851 Current working directory.
854 If the specified path name does not contain "recipe" as the last
855 component. Qi will complete it by adding "recipe" to the path name.
858 If the recipe is not in the current working directory, it will be
859 searched under @samp{$@{worktree@}/recipes}. The last component will be
860 completed adding "recipe" to the specified path name.
864 To build a single package, type:
867 qi build x-apps/xterm
871 Multiple jobs can be passed to the compiler to speed up the build process:
874 qi build --jobs 3 x-apps/xterm
878 Update or install the produced package (if not already installed) when the
882 qi build -j3 --upgrade x-apps/xterm
886 Only process a recipe but do not create the binary package:
889 qi build --no-package dict/aspell
892 The options --install or --upgrade have no effect when --no-package
896 This is useful to inspect the build process of the above recipe:
898 qi build --keep --no-package dict/aspell 2>&1 | tee aspell-log.txt
900 The --keep option could preserve the source directory and the destination
901 directory for later inspection. A log file of the build process will be
902 created redirecting both, standard error and standard output to tee(1).
904 @section Variables from the environment
905 @cindex environment variables
907 Qi has environment variables which can be used at build time:
909 The variable @env{TMPDIR} sets the temporary directory for sources, which is
910 used for package extractions (see @ref{Examining packages}) and is
911 prepended to the value of @samp{$@{srcdir@}} and @samp{$@{destdir@}} in
912 build command. By convention its default value is equal to
913 @samp{/usr/src/qi/build}.
915 The variables @env{QICFLAGS}, @env{QICXXFLAGS}, @env{QILDFLAGS}, and
916 @env{QICPPFLAGS} have no effect by default. The environment variables
917 such as @env{CFLAGS}, @env{CXXFLAGS}, @env{LDFLAGS}, and @env{CPPFLAGS}
918 are unset at compile time:
921 Recommended practice is to set variables in the command line of
922 @samp{configure} or @emph{make(1)} instead of exporting to the
923 environment. As follows:
925 @url{https://www.gnu.org/software/make/manual/html_node/Environment.html}
927 It is not wise for makefiles to depend for their functioning on environment
928 variables set up outside their control, since this would cause different
929 users to get different results from the same makefile. This is against the
930 whole purpose of most makefiles.
933 Setting environment variables for configure is deprecated because running
934 configure in varying environments can be dangerous.
936 @url{https://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html}
938 Variables not defined in a site shell script can be set in the environment
939 passed to configure. However, some packages may run configure again
940 during the build, and the customized values of these variables may be
941 lost. In order to avoid this problem, you should set them in the
942 configure command line, using @samp{VAR=value}. For example:
944 @code{./configure CC=/usr/local2/bin/gcc}
947 @url{https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html}
949 If for instance the user runs @samp{CC=bizarre-cc ./configure}, then the cache,
950 config.h, and many other output files depend upon bizarre-cc being the C
951 compiler. If for some reason the user runs ./configure again, or if it is
952 run via @samp{./config.status --recheck}, (See Automatic Remaking, and see
953 config.status Invocation), then the configuration can be inconsistent,
954 composed of results depending upon two different compilers.
956 Indeed, while configure can notice the definition of CC in @samp{./configure
957 CC=bizarre-cc}, it is impossible to notice it in @samp{CC=bizarre-cc
958 ./configure}, which, unfortunately, is what most users do.
960 configure: error: changes in the environment can compromise the build.
963 If the @env{SOURCE_DATE_EPOCH} environment variable is set to a UNIX timestamp
964 (defined as the number of seconds, excluding leap seconds, since 01 Jan 1970
965 00:00:00 UTC.); then the given timestamp will be used to overwrite any newer
966 timestamps on the package contents (when it is created). More information
967 about this can be found at
968 @uref{https://reproducible-builds.org/specs/source-date-epoch/}.
970 @section The meta file
971 @cindex the meta file
973 The "meta file" is a regular file created during the build process, 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).
1005 full_pkgname=gawk_5.0.1_amd64-1@@tools
1006 blurb="Pattern scanning and processing language."
1007 homepage="https://www.gnu.org/software/gawk"
1009 fetch="https://ftp.gnu.org/gnu/gawk/gawk-5.0.1.tar.lz"
1013 A package descriptions is extracted from the variable @samp{description}
1014 where each line is interpreted literally and pre-formatted to fit in
1015 (exactly) @strong{80 columns}, plus the character @samp{#} and a blank
1016 space is prefixed to every line (shell comments).
1019 In addition to the Special variables, there are implicit variables such as
1022 The @samp{blurb} variable is related to the special variable
1023 @samp{description}. Its value is made from the first (substantial)
1024 line of @samp{description}, mentioned as the "brief description".
1026 The build flags such as @samp{QICFLAGS}, @samp{QICXXFLAGS},
1027 @samp{QILDFLAGS}, and @samp{QICPPFLAGS} are only added to the meta file
1028 if the declared variable @samp{arch} is not equal to the "noarch" value.
1031 @chapter Order files
1032 @cindex handling build order
1034 The order command has the purpose of resolving the build order through
1035 .order files. An order file contains a list of recipe names, by default
1036 does not perform any action other than to print a resolved list in
1037 descending order. For example, if @strong{a} depends on @strong{b} and
1038 @strong{c}, and @strong{c} depends on @strong{b} as well, the file might
1047 Each letter represents a recipe name, complete dependencies for
1048 the first recipe name are listed in descending order, which is
1049 printed from right to left, and removed from left to right:
1059 Blank lines, colons and parentheses are simply ignored. Comment lines
1060 beginning with @samp{#} are allowed.
1063 An order file could be used to build a series of packages, for example,
1067 # Image handling libraries
1069 libs/libjpeg-turbo: devel/nasm
1070 x-libs/jasper: libs/libjpeg-turbo
1071 libs/tiff: libs/libjpeg-turbo
1074 To proceed with each recipe, we can type:
1077 qi order imglibs.order | qi build --install -
1080 The output of @samp{qi order imglibs.order} tells to qi in which order it
1081 should build the recipes:
1091 @node Creating packages
1092 @chapter Creating packages
1093 @cindex package creation
1095 The creation command is an internal function of qi to make new Qi
1096 compatible packages. A package is produced using the contents of
1097 the Current Working Directory and the package file is written out.
1100 Usage: qi create [@var{Output/PackageName.tlz}]...
1103 The argument for the file name to be written must contain a fully
1104 qualified named directory as the output directory where the package
1105 produced will be written. The file name should be composed using the
1106 full name: name-version-architecture-release[@@pkgcategory].tlz
1112 cd claws-mail_3.17.1_amd64-1@@x-apps
1113 qi create /var/cache/qi/packages/claws-mail_3.17.1_amd64-1@@x-apps
1116 In this case, the package "claws-mail_3.17.1_amd64-1@@x-apps" will be
1117 written into @samp{/var/cache/qi/packages/}.
1120 All packages produced are complemented by a checksum file (.sha256).
1123 @node Examining packages
1124 @chapter Examining packages
1125 @cindex package examination
1127 The extraction command serves to examine binary packages for debugging
1128 purposes. It decompresses a package into a single directory, verifying
1129 its integrity and preserving all of its properties (owner and permissions).
1132 Usage: qi extract [@var{packagename.tlz}]...
1138 qi extract mksh_R56c_amd64-1@@shells.tlz
1141 This action will put the content of "mksh_R56c_amd64-1@@shells.tlz" into a
1142 single directory, this is a private directory for the user who requested
1143 the action, creation operation will be equal to @strong{u=rwx,g=,o= (0700)}.
1144 The package content will reside on this location, default mask to deploy
1145 the content will be equal to @strong{u=rwx,g=rwx,o=rwx (0000)}.
1148 Note: the creation of the custom directory is influenced by the value
1149 of the @env{TMPDIR} variable.
1152 @node Qi exit status
1153 @chapter Qi exit status
1156 All the exit codes are described in this chapter.
1160 Successful completion (no errors).
1163 Minor common errors:
1166 @item Help usage on invalid options or required arguments.
1168 @item Program needed by qi (prerequisite) is not available.
1172 Command execution error:
1174 This code is used to return the evaluation of an external command or shell
1175 arguments in case of failure.
1178 Integrity check error for compressed files.
1180 Compressed files means:
1183 @item A tarball file from tar(1), typically handled by the GNU tar implementation.
1184 Supported extensions: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
1185 .tar.xz, .txz, .tar.zst, .tzst
1187 @item A tarball file from tarlz(1).
1188 Supported extensions: .tar.lz, .tlz
1190 @item Zip files from unzip(1).
1191 Supported extensions: .zip, .ZIP
1193 @item Gzip files from gzip(1).
1194 Supported extensions: .gz, .Z
1196 @item Bzip2 files from bzip2(1).
1197 Supported extension: .bz2
1199 @item Lzip files from lzip(1).
1200 Supported extension: .lz
1202 @item Xz files from xz(1).
1203 Supported extension: .xz
1205 @item Zstd files from zstd(1).
1206 Supported extension: .zst
1210 File empty, not regular, or expected.
1212 It's commonly expected:
1215 @item An argument for giving commands.
1217 @item A regular file or readable directory.
1219 @item An expected extension: .tlz, .sha256, .order.
1221 @item A protocol supported by the network downloader tool.
1225 Empty or not defined variable:
1227 This code is used to report empty or undefined variables (usually
1228 variables coming from a recipe or assigned arrays that are tested).
1231 Package already installed:
1233 The package directory for an incoming .tlz package already exists.
1236 Network manager error:
1238 This code is used if the network downloader tool fails for some reason.