1 This is qi.info, produced by makeinfo version 6.5 from qi-header.texi.
3 INFO-DIR-SECTION Package management
5 * Qi: (qi). A user-friendly package manager.
9 File: qi.info, Node: Top, Next: Introduction to Qi, Up: (dir)
14 This user guide is for Qi (version 2.9-rc1, 16 May 2022).
18 * Introduction to Qi:: Description and features of qi
19 * Invoking qi:: Command-line options
20 * The qirc file:: Configuration file
21 * Packages:: Managing packages
22 * Recipes:: Building packages
23 * Order files:: Handling build order
24 * Creating packages:: Making Qi packages
25 * Examining packages:: Debugging purposes
26 * Qi exit status:: Exit codes
30 Copyright © 2019-2022 Matias Andres Fonzo, Santiago del Estero,
33 Permission is granted to copy, distribute and/or modify this document
34 under the terms of the GNU Free Documentation License, Version 1.3 or
35 any later version published by the Free Software Foundation; with no
36 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
39 File: qi.info, Node: Introduction to Qi, Next: Invoking qi, Prev: Top, Up: Top
44 Qi is a simple but well-integrated package manager. It can create,
45 install, remove, and upgrade software packages. Qi produces binary
46 packages using recipes, which are files containing specific instructions
47 to build each package from source. Qi can manage multiple packages
48 under a single directory hierarchy. This method allows to maintain a
49 set of packages and multiple versions of them. This means that Qi could
50 be used as the main package manager or complement the existing one.
52 Qi offers a friendly command line interface, a global configuration
53 file, a simple recipe layout to deploy software packages; also works
54 with binary packages in parallel, speeding up installations and packages
55 in production. The format used for packages is a simplified and safer
56 variant of POSIX pax archive compressed in lzip format.
58 Qi is a modern (POSIX-compliant) shell script released under the
59 terms of the GNU General Public License. There are only two major
60 dependencies for the magic: graft(1) and tarlz(1), the rest is expected
61 to be found in any Unix-like system.
64 File: qi.info, Node: Invoking qi, Next: The qirc file, Prev: Introduction to Qi, Up: Top
69 This chapter describes the synopsis for invoking Qi.
71 Usage: qi COMMAND [OPTION...] [FILE]...
73 One mandatory command specifies the operation that 'qi' should perform,
74 options are meant to detail how this operation should be performed
75 during or after the process.
77 Qi supports the following commands:
80 Warn about files that will be installed.
92 Extract packages for debugging purposes.
95 Create a .tlz package from directory.
98 Build packages using recipe names.
101 Resolve build order through .order files
103 Options when installing, removing, or upgrading software packages:
107 Force upgrade of pre-existing packages.
111 Keep directories when build/remove/upgrade.
113 Keep (don't delete) the package directory when using remove/upgrade
116 This will also try to preserve the directories '${srcdir}' and
117 '${destdir}' when using build command. Its effect is available in
118 recipes as '${keep_srcdir}' and '${keep_destdir}'. See *note
119 Special variables: Recipes. for details.
127 Set directory for package installations.
131 Set target directory for symbolic links.
135 Use the fully qualified named directory as the root directory for
138 Note: the target directory and the package directory will be
139 relative to the specified directory, excepting the graft log file.
141 Options when building software packages using recipes:
145 Set architecture name for the package.
149 Parallel jobs for the compiler.
151 This option sets the variable '${jobs}'. If not specified, default
156 Skip questions on completed recipes.
160 Increment release number ('${release}' + 1).
162 The effect of this option will be omitted if -no-package is being
167 Do not create a .tlz package.
171 Install package after the build.
175 Upgrade package after the build.
179 Where the packages produced will be written.
181 This option sets the variable '${outdir}'.
185 Where archives, patches, recipes are expected.
187 This option sets the variable '${worktree}'.
191 Where compressed sources will be found.
193 This option sets the variable '${tardir}'.
199 Be verbose (an extra -v gives more).
201 It sets the verbosity level, default sets to 0.
203 The value 1 is used for more verbosity while the value 2 is too
204 detailed. Although at the moment it is limited to graft(1)
209 Do not read the configuration file.
211 This will ignore reading the qirc file.
215 Print default directory locations and exit.
217 This will print the target directory, package directory, working
218 tree, the directory for sources, and the output directory for the
223 Display the usage and exit.
228 This will print the (short) version information and then exit.
230 The same can be achieved if Qi is invoked as 'qi version'.
232 When FILE is -, qi can read from the standard input. See examples
233 from the *note Packages:: section.
235 Exit status: 0 for a normal exit, 1 for minor common errors (help
236 usage, support not available, etc), 2 to indicate a command execution
237 error; 3 for integrity check error on compressed files, 4 for empty, not
238 regular, or expected files, 5 for empty or not defined variables, 6 when
239 a package already exist, 10 for network manager errors. For more
240 details, see the *note Qi exit status:: section.
243 File: qi.info, Node: The qirc file, Next: Packages, Prev: Invoking qi, Up: Top
248 The global 'qirc' file offers a way to define variables and tools (such
249 as a download manager) for default use. This file is used by qi at
250 runtime, e.g., to build, install, remove or upgrade packages.
252 Variables and their possible values must be declared as any other
253 variable in the shell.
255 The command line options related to the package directory and target
256 directory and some of the command line options used for the build
257 command, have the power to override the values declared on 'qirc'. See
260 The order in which qi looks for this file is:
262 1. '${HOME}/.qirc' Effective user.
264 2. '${sysconfdir}/qirc' System-wide.
266 If you intend to run qi as effective user, the file
267 '${sysconfdir}/qirc' could be copied to '${HOME}/.qirc' setting the
268 paths for '${packagedir}' and '${targetdir}' according to the '$HOME'.
271 File: qi.info, Node: Packages, Next: Recipes, Prev: The qirc file, Up: Top
276 A package is a suite of programs usually distributed in binary form
277 which may also contain manual pages, documentation, or any other file
278 associated to a specific software.
280 The package format used by qi is a simplified POSIX pax archive
281 compressed using lzip(1). The file extension for packages ends in
284 Both package installation and package de-installation are managed using
285 two important (internal) variables: '${packagedir}' and '${targetdir}',
286 these values can be changed in the configuration file or via options.
288 '${packagedir}' is a common directory tree where the package contents
289 will be decompressed (will reside).
291 '${targetdir}' is a target directory where the links will be made by
292 graft(1) taking '${packagedir}/package_name' into account.
294 Packages are installed in self-contained directory trees and symbolic
295 links from a common area are made to the package files. This allows
296 multiple versions of the same package to coexist on the same system.
298 4.1 Package conflicts
299 =====================
301 All the links to install or remove a package are handled by graft(1).
302 Since multiple packages can be installed or removed at the same time,
303 certain conflicts may arise between the packages.
305 graft(2) defines a CONFLICT as one of the following conditions:
307 * If the package object is a directory and the target object exists
308 but is not a directory.
310 * If the package object is not a directory and the target object
311 exists and is not a symbolic link.
313 * If the package object is not a directory and the target object
314 exists and is a symbolic link to something other than the package
317 The default behavior of qi for an incoming package is to ABORT if a
318 conflict arises. When a package is going to be deleted, qi tells to
319 graft(1) to remove those parts that are not in conflict, leaving the
320 links to the belonging package. This behavior can be forced if the
321 -prune option is given.
323 4.2 Installing packages
324 =======================
326 To install a single package, simply type:
328 qi install coreutils_8.30_i586-1@tools.tlz
330 To install multiple packages at once, type:
332 qi install gcc_8.3.0_i586-1@devel.tlz rafaela_2.2_i586-1@legacy.tlz ...
334 Warn about the files that will be linked:
336 qi warn bash_5.0_i586-1@shells.tlz
338 This is to verify the content of a package before installing it.
340 See the process of an installation:
342 qi install --verbose mariana_3.0_i586-1@woman.tlz
344 A second -verbose or -v option gives more (very verbose).
346 Installing package in a different location:
348 qi install --rootdir=/media/floppy lzip_1.21_i586-1@compressors.tlz
350 Important: the -rootdir option assumes '${targetdir}' and
351 '${packagedir}'. See the following example:
353 qi install --rootdir=/home/selk lzip_1.21_i586-1@compressors.tlz
355 The content of "lzip_1.21_i586-1@compressors.tlz" will be
356 decompressed into '/home/selk/pkgs/lzip_1.21_i586-1@compressors'.
357 Assuming that the main binary for lzip is under
358 '/home/selk/pkgs/lzip_1.21_i586-1@compressors/usr/bin/' the target for
359 "usr/bin" will be created at '/home/selk'. Considering that you have
360 exported the 'PATH' as '${HOME}/usr/bin', now the system is able to see
361 the recent lzip command.
363 Installing from a list of packages using standard input:
365 qi install - < PACKAGELIST.txt
367 Or in combination with another tool:
368 sort -u PACKAGELIST.txt | qi install -
370 The sort command will read and sorts the list of declared packages,
371 while trying to have unique entries for each statement. The output
372 produced is captured by Qi to install each package.
374 An example of a list containing package names is:
375 /var/cache/qi/packages/amd64/tcl_8.6.9_amd64-1@devel.tlz
376 /var/cache/qi/packages/amd64/tk_8.6.9.1_amd64-1@devel.tlz
377 /var/cache/qi/packages/amd64/vala_0.42.3_amd64-1@devel.tlz
379 4.3 Removing packages
380 =====================
382 To remove a package, simply type:
384 qi remove xz_5.2.4_i586-1@compressors.tlz
386 Remove command will match the package name using '${packagedir}' as
387 prefix. For example, if the value of '${packagedir}' has been set to
388 /usr/pkg, this will be equal to:
390 qi remove /usr/pkg/xz_5.2.4_i586-1@compressors
394 qi remove --verbose /usr/pkg/xz_5.2.4_i586-1@compressors
396 A second -verbose or -v option gives more (very verbose).
398 By default the remove command does not preserve a package directory
399 after removing its links from '${targetdir}', but this behavior can be
400 changed if the -keep option is passed:
402 qi remove --keep /usr/pkg/lzip_1.21_i586-1@compressors
404 This means that the links to the package can be reactivated, later:
406 cd /usr/pkg && graft -i lzip_1.21_i586-1@compressors
408 Removing package from a different location:
410 qi remove --rootdir=/home/cthulhu xz_5.2.4_i586-1@compressors
412 Removing a package using standard input:
414 echo vala_0.42.3_amd64-1@devel | qi remove -
416 This will match with the package directory.
418 4.4 Upgrading packages
419 ======================
421 The upgrade command inherits the properties of the installation and
422 removal process. To make sure that a package is updated, the package is
423 installed in a temporary directory taking '${packagedir}' into account.
424 Once the incoming package is pre-installed, qi can proceed to search and
425 delete packages that have the same name (considered as previous ones).
426 Finally, the package is re-installed at its final location and the
427 temporary directory is removed.
429 Since updating a package can be crucial and so to perform a
430 successful upgrade, from start to finish, you will want to ignore some
431 important system signals during the upgrade process, those signals are
432 SIGHUP, SIGINT, SIGQUIT, SIGABRT, and SIGTERM.
434 To upgrade a package, just type:
436 qi upgrade gcc_9.0.1_i586-1@devel.tlz
438 This will proceed to upgrade "gcc_9.0.1_i586-1@devel" removing any
439 other version of "gcc" (if any).
441 If you want to keep the package directories of versions found during the
442 upgrade process, just pass:
444 qi upgrade --keep gcc_9.0.1_i586-1@devel.tlz
446 To see the upgrade process:
448 qi upgrade --verbose gcc_9.0.1_i586-1@devel.tlz
450 A second -verbose or -v option gives more (very verbose).
452 To force the upgrade of an existing package:
454 qi upgrade --force gcc_9.0.1_i586-1@devel.tlz
456 4.4.1 Package blacklist
457 -----------------------
459 To implement general package facilities, either to install, remove or
460 maintain the hierarchy of packages in a clean manner, qi makes use of
461 the pruning operation via graft(1) by default:
463 There is a risk if those are crucial packages for the proper
464 functioning of the system, because it implies the deactivation of
465 symbolic from the target directory, _especially_ when transitioning an
466 incoming package into its final location during an upgrade.
468 A blacklist of package names has been devised for the case where a user
469 decides to upgrade all the packages in the system, or just the crucial
470 ones, such as the C library.
472 The blacklist is related to the upgrade command only, consists in
473 installing a package instead of updating it or removing previous
474 versions of it; the content of the package will be updated over the
475 existing content at '${packagedir}', while the existing links from
476 '${targetdir}' will be preserved. A pruning of links will be carried
477 out in order to re-link possible differences with the recent content,
478 this helps to avoid leaving dead links in the target directory.
480 Package names for the blacklist to be declared must be set from the
481 configuration file. By default, it is declared using the package name,
482 which is more than enough for critical system packages, but if you want
483 to be more specific, you can declare a package using:
484 '${pkgname}_${pkgversion}_${arch}-${release}' where the package category
485 is avoided for common matching. See *note Special variables: Recipes.
486 for a description of these variables.
488 ---------- Footnotes ----------
490 (1) For more details about tarlz and the lzip format, visit
491 <https://lzip.nongnu.org/tarlz.html>.
493 (2) The official guide for Graft can be found at
494 <https://peters.gormand.com.au/Home/tools/graft/graft.html>.
497 File: qi.info, Node: Recipes, Next: Order files, Prev: Packages, Up: Top
502 A recipe is a file telling qi what to do. Most often, the recipe tells
503 qi how to build a binary package from a source tarball.
505 A recipe has two parts: a list of variable definitions and a list of
506 sections. By convention, the syntax of a section is:
513 The section name is followed by parentheses, one newline and an
514 opening brace. The line finishing the section contains just a closing
515 brace. The section names or the function names currently recognized are
518 The 'build' section (or *shell function*) is an augmented shell
519 script that contains the main instructions to build software from
522 If there are other functions defined by the packager, Qi detects them
528 A "variable" is a *shell variable* defined either in 'qirc' or in a
529 recipe to represent a string of text, called the variable's "value".
530 These values are substituted by explicit request in the definitions of
531 other variables or in calls to external commands.
533 Variables can represent lists of file names, options to pass to
534 compilers, programs to run, directories to look in for source files,
535 directories to write output to, or anything else you can imagine.
537 Definitions of variables in qi have four levels of precedence.
538 Options which define variables from the command-line override those
539 specified in the 'qirc' file, while variables defined in the recipe
540 override those specified in 'qirc', taking priority over those variables
541 set by command-line options. Finally, the variables have default values
542 if they are not defined anywhere.
544 Options that set variables through the command-line can only
545 reference variables defined in 'qirc' and variables with default values.
547 Definitions of variables in 'qirc' can only reference variables
548 previously defined in 'qirc' and variables with default values.
550 Definitions of variables in the recipe can only reference variables
551 set by the command-line, variables previously defined in the recipe,
552 variables defined in 'qirc', and variables with default values.
554 5.2 Special variables
555 =====================
557 There are variables which can only be set using the command line options
558 or via 'qirc', there are other special variables which can be defined or
559 redefined in a recipe. See the following definitions:
561 'outdir' is the directory where the packages produced are written.
562 This variable can be redefined per-recipe. Default sets to
563 '/var/cache/qi/packages'.
565 'worktree' is the working tree where archives, patches, and recipes
566 are expected. This variable can not be redefined in the recipe.
567 Default sets to '/usr/src/qi'.
569 'tardir' is defined in the recipe to the directory where the tarball
570 containing the source can be found. The full name of the tarball is
571 composed as '${tardir}/$tarname'. Its value is available in the recipe
572 as '${tardir}'; a value of . for 'tardir' sets it to the value of CWD
573 (Current Working Directory), this is where the recipe lives.
575 'arch' is the architecture to compose the package name. Its value is
576 available in the recipe as '${arch}'. Default value is the one that was
577 set in the Qi configuration.
579 'jobs' is the number of parallel jobs to pass to the compiler. Its
580 value is available in the recipe as '${jobs}'. The default value is 1.
582 The two variables '${srcdir}' and '${destdir}' can be set in the
583 recipe, as any other variable, but if they are not, qi uses default
584 values for them when building a package.
586 'srcdir' contains the source code to be compiled, and defaults to
587 '${program}-${version}'. 'destdir' is the place where the built package
588 will be installed, and defaults to '${TMPDIR}/package-${program}'.
590 If 'pkgname' is left undefined, the special variable 'program' is
591 assigned by default. If 'pkgversion' is left undefined, the special
592 variable 'version' is assigned by default.
594 'pkgname' and 'pkgversion' along with: 'version', 'arch', 'release',
595 and (optionally) 'pkgcategory' are used to produce the package name in
597 '${pkgname}_${pkgversion}_${arch}-${release}[@${pkgcategory}].tlz'
599 'pkgcategory' is an optional special variable that can be defined on
600 the recipe to categorize the package name. If it is defined, then the
601 package output will be composed as
602 '${pkgname}_${pkgversion}_${arch}-${release}[@${pkgcategory}.tlz'.
603 Automatically, the value of 'pkgcategory' will be prefixed using the '@'
604 (at) symbol which will be added to the last part of the package name.
606 A special variable called 'replace' can be used to declare package
607 names that will be replaced at installation time.
609 The special variables 'keep_srcdir' and 'keep_destdir' are provided
610 in order to preserve the directories '${srcdir}' or '${destdir}', if
611 those exists as such. Note: The declaration of these variables are
612 subject to manual deactivation; its purpose in recipes is to preserve
613 the directories that relate to the package's build (source) and
614 destination directory, that is so that another recipe can get a new
615 package (or meta package) from there. For example, the declarations can
618 keep_srcdir=keep_srcdir
619 keep_destdir=keep_destdir
621 Then from another recipe you would proceed to copy the necessary
622 files that will compose the meta package, from the main function you
623 must deactivate the variables at the end:
625 unset -v keep_srcdir keep_destdir
627 This will leave the 'keep_srcdir' and 'keep_destdir' variables blank
628 to continue with the rest of the recipes.
630 A typical recipe contains the following variables:
632 * 'program': Software name.
634 It matches the source name. It is also used to compose the name of
635 the package if '${pkgname}' is not specified.
637 * 'version': Software version.
639 It matches the source name. It is also used to compose the version
640 of the package if '${pkgversion}' is not specified.
642 * 'arch': Software architecture.
644 It is used to compose the architecture of the package in which it
647 * 'release': Release number.
649 This is used to reflect the release number of the package. It is
650 recommended to increase this number after any significant change in
651 the recipe or post-install script.
653 * 'pkgcategory': Package category.
655 Optional but recommended variable to categorize the package name
658 Obtaining sources over the network must be declared in the recipe using
659 the 'fetch' variable.
661 The variables 'netget' and 'rsync' can be defined in 'qirc' to
662 establish a network downloader in order to get the sources. If they are
663 not defined, qi uses default values:
665 'netget' is the general network downloader tool, defaults sets to
666 'wget2 -c -w1 -t3 --no-check-certificate'.
668 'rsync' is the network tool for sources containing the prefix for the
669 RSYNC protocol, default sets to 'rsync -v -a -L -z -i --progress'.
671 The variable 'description' is used to print the package description
672 when a package is installed.
674 A description has two parts: a brief description, and a long
675 description. By convention, the syntax of 'description' is:
683 The first line of the value represented is a brief description of the
684 software (called "blurb"). A blank line separates the _brief
685 description_ from the _long description_, which should contain a more
686 descriptive description of the software.
688 An example looks like:
691 The GNU core utilities.
693 The GNU core utilities are the basic file, shell and text manipulation
694 utilities of the GNU operating system. These are the core utilities
695 which are expected to exist on every operating system.
698 Please consider a length limit of 78 characters as maximum, because
699 the same one would be used on the meta file creation. See *note The
700 meta file: Recipes. section.
702 The 'homepage' variable is used to declare the main site or home
705 homepage=https://www.gnu.org/software/gcc
707 The variable 'license' is used for license information(1). Some code
708 in the program can be covered by license A, license B, or license C. For
709 "separate licensing" or "heterogeneous licensing", we suggest using *|*
710 for a disjunction, *&* for a conjunction (if that ever happens in a
711 significant way), and comma for heterogeneous licensing. Comma would
712 have lower precedence, plus added special terms.
714 license="LGPL, GPL | Artistic - added permission"
719 Originally, Qi was designed for the series of Dragora GNU/Linux-Libre 3;
720 this doesn't mean you can't use it in another distribution, just that if
721 you do, you'll have to try it out for yourself. To help with this, here
722 are some references to well-written recipes:
724 * <https://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes>
725 * <https://notabug.org/dragora/dragora/src/master/recipes>
726 * <https://notabug.org/dragora/dragora-extras/src/master/recipes>
728 <https://git.savannah.nongnu.org/cgit/dragora/dragora-extras.git/tree/recipes>
730 5.4 Building packages
731 =====================
733 A recipe is any valid regular file. Qi sets priorities for reading a
734 recipe, the order in which qi looks for a recipe is:
736 1. Current working directory.
738 2. If the specified path name does not contain "recipe" as the last
739 component. Qi will complete it by adding "recipe" to the path
742 3. If the recipe is not in the current working directory, it will be
743 searched under '${worktree}/recipes'. The last component will be
744 completed adding "recipe" to the specified path name.
746 To build a single package, type:
748 qi build x-apps/xterm
750 Multiple jobs can be passed to the compiler to speed up the build
753 qi build --jobs 3 x-apps/xterm
755 Update or install the produced package (if not already installed) when
756 the build command ends:
758 qi build -j3 --upgrade x-apps/xterm
760 Only process a recipe but do not create the binary package:
762 qi build --no-package dict/aspell
764 The options -install or -upgrade have no effect when -no-package is
767 This is useful to inspect the build process of the above recipe:
769 qi build -keep -no-package dict/aspell 2>&1 | tee aspell-log.txt
771 The -keep option could preserve the source directory and the
772 destination directory for later inspection. A log file of the build
773 process will be created redirecting both, standard error and standard
776 5.5 Variables from the environment
777 ==================================
779 Qi has environment variables which can be used at build time:
781 The variable 'TMPDIR' sets the temporary directory for sources, which
782 is used for package extractions (see *note Examining packages::) and is
783 prepended to the value of '${srcdir}' and '${destdir}' in build command.
784 By convention its default value is equal to '/usr/src/qi/build'.
786 The variables 'QICFLAGS', 'QICXXFLAGS', 'QILDFLAGS', and 'QICPPFLAGS'
787 have no effect by default. The environment variables such as 'CFLAGS',
788 'CXXFLAGS', 'LDFLAGS', and 'CPPFLAGS' are unset at compile time:
790 Recommended practice is to set variables in the command line of
791 'configure' or _make(1)_ instead of exporting to the environment. As
794 <https://www.gnu.org/software/make/manual/html_node/Environment.html>
795 It is not wise for makefiles to depend for their functioning on
796 environment variables set up outside their control, since this
797 would cause different users to get different results from the same
798 makefile. This is against the whole purpose of most makefiles.
800 Setting environment variables for configure is deprecated because
801 running configure in varying environments can be dangerous.
803 <https://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html>
804 Variables not defined in a site shell script can be set in the
805 environment passed to configure. However, some packages may run
806 configure again during the build, and the customized values of
807 these variables may be lost. In order to avoid this problem, you
808 should set them in the configure command line, using 'VAR=value'.
811 './configure CC=/usr/local2/bin/gcc'
813 <https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html>
814 If for instance the user runs 'CC=bizarre-cc ./configure', then the
815 cache, config.h, and many other output files depend upon bizarre-cc
816 being the C compiler. If for some reason the user runs ./configure
817 again, or if it is run via './config.status --recheck', (See
818 Automatic Remaking, and see config.status Invocation), then the
819 configuration can be inconsistent, composed of results depending
820 upon two different compilers. [...] Indeed, while configure can
821 notice the definition of CC in './configure CC=bizarre-cc', it is
822 impossible to notice it in 'CC=bizarre-cc ./configure', which,
823 unfortunately, is what most users do. [...] configure: error:
824 changes in the environment can compromise the build.
826 If the 'SOURCE_DATE_EPOCH' environment variable is set to a UNIX
827 timestamp (defined as the number of seconds, excluding leap seconds,
828 since 01 Jan 1970 00:00:00 UTC.); then the given timestamp will be used
829 to overwrite any newer timestamps on the package contents (when it is
830 created). More information about this can be found at
831 <https://reproducible-builds.org/specs/source-date-epoch/>.
836 The "meta file" is a regular file created during the build process, it
837 contains information about the package such as package name, package
838 version, architecture, release, fetch address, description, and other
839 minor data extracted from processed recipes. The name of the file is
840 generated as '${full_pkgname}.tlz.txt', and its purpose is to reflect
841 essential information to the user without having to look inside the
842 package content. The file format is also intended to be used by other
843 scripts or by common Unix tools.
845 The content of a meta file looks like:
848 # Pattern scanning and processing language.
850 # The awk utility interprets a special-purpose programming language
851 # that makes it possible to handle simple data-reformatting jobs
852 # with just a few lines of code. It is a free version of 'awk'.
854 # GNU awk implements the AWK utility which is part of
855 # IEEE Std 1003.1 Shell and Utilities (XCU).
867 full_pkgname=gawk_5.0.1_amd64-1@tools
868 blurb="Pattern scanning and processing language."
869 homepage="https://www.gnu.org/software/gawk"
871 fetch="https://ftp.gnu.org/gnu/gawk/gawk-5.0.1.tar.lz"
874 A package descriptions is extracted from the variable 'description'
875 where each line is interpreted literally and pre-formatted to fit in
876 (exactly) *80 columns*, plus the character '#' and a blank space is
877 prefixed to every line (shell comments).
879 In addition to the Special variables, there are implicit variables such
882 The 'blurb' variable is related to the special variable
883 'description'. Its value is made from the first (substantial) line of
884 'description', mentioned as the "brief description".
886 The build flags such as 'QICFLAGS', 'QICXXFLAGS', 'QILDFLAGS', and
887 'QICPPFLAGS' are only added to the meta file if the declared variable
888 'arch' is not equal to the "noarch" value.
890 ---------- Footnotes ----------
892 (1) The proposal for 'license' was made by Richard M. Stallman at
893 <https://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html>.
896 File: qi.info, Node: Order files, Next: Creating packages, Prev: Recipes, Up: Top
901 The order command has the purpose of resolving the build order through
902 .order files. An order file contains a list of recipe names, by default
903 does not perform any action other than to print a resolved list in
904 descending order. For example, if *a* depends on *b* and *c*, and *c*
905 depends on *b* as well, the file might look like:
911 Each letter represents a recipe name, complete dependencies for the
912 first recipe name are listed in descending order, which is printed from
913 right to left, and removed from left to right:
921 Blank lines, colons and parentheses are simply ignored. Comment
922 lines beginning with '#' are allowed.
924 An order file could be used to build a series of packages, for example,
927 # Image handling libraries
929 libs/libjpeg-turbo: devel/nasm
930 x-libs/jasper: libs/libjpeg-turbo
931 libs/tiff: libs/libjpeg-turbo
933 To proceed with each recipe, we can type:
935 qi order imglibs.order | qi build --install -
937 The output of 'qi order imglibs.order' tells to qi in which order it
938 should build the recipes:
946 File: qi.info, Node: Creating packages, Next: Examining packages, Prev: Order files, Up: Top
951 The creation command is an internal function of qi to make new Qi
952 compatible packages. A package is produced using the contents of the
953 Current Working Directory and the package file is written out.
955 Usage: qi create [OUTPUT/PACKAGENAME.TLZ]...
957 The argument for the file name to be written must contain a fully
958 qualified named directory as the output directory where the package
959 produced will be written. The file name should be composed using the
960 full name: name-version-architecture-release[@pkgcategory].tlz
965 cd claws-mail_3.17.1_amd64-1@x-apps
966 qi create /var/cache/qi/packages/claws-mail_3.17.1_amd64-1@x-apps
968 In this case, the package "claws-mail_3.17.1_amd64-1@x-apps" will be
969 written into '/var/cache/qi/packages/'.
971 All packages produced are complemented by a checksum file (.sha256).
974 File: qi.info, Node: Examining packages, Next: Qi exit status, Prev: Creating packages, Up: Top
979 The extraction command serves to examine binary packages for debugging
980 purposes. It decompresses a package into a single directory, verifying
981 its integrity and preserving all of its properties (owner and
984 Usage: qi extract [PACKAGENAME.TLZ]...
988 qi extract mksh_R56c_amd64-1@shells.tlz
990 This action will put the content of "mksh_R56c_amd64-1@shells.tlz"
991 into a single directory, this is a private directory for the user who
992 requested the action, creation operation will be equal to *u=rwx,g=,o=
993 (0700)*. The package content will reside on this location, default mask
994 to deploy the content will be equal to *u=rwx,g=rwx,o=rwx (0000)*.
996 Note: the creation of the custom directory is influenced by the value of
997 the 'TMPDIR' variable.
1000 File: qi.info, Node: Qi exit status, Next: Index, Prev: Examining packages, Up: Top
1005 All the exit codes are described in this chapter.
1008 Successful completion (no errors).
1011 Minor common errors:
1013 * Help usage on invalid options or required arguments.
1015 * Program needed by qi (prerequisite) is not available.
1018 Command execution error:
1020 This code is used to return the evaluation of an external command
1021 or shell arguments in case of failure.
1024 Integrity check error for compressed files.
1026 Compressed files means:
1028 * A tarball file from tar(1). Supported extensions: .tar,
1029 .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz, .tar.xz, .txz
1031 * A tarball file from tarlz(1). Supported extensions: .tar.lz,
1034 * Zip files from unzip(1). Supported extensions: .zip, .ZIP
1036 * Gzip files from gzip(1). Supported extensions: .gz, .Z
1038 * Bzip2 files from bzip2(1). Supported extension: .bz2
1040 * Lzip files from lzip(1). Supported extension: .lz
1042 * Xz files from xz(1). Supported extension: .xz
1045 File empty, not regular, or expected.
1047 It's commonly expected:
1049 * An argument for giving commands.
1051 * A regular file or readable directory.
1053 * An expected extension: .tlz, .sha256, .order.
1055 * A protocol supported by the network downloader tool.
1058 Empty or not defined variable:
1060 This code is used to report empty or undefined variables (usually
1061 variables coming from a recipe or assigned arrays that are tested).
1064 Package already installed:
1066 The package directory for an incoming .tlz package already exists.
1069 Network manager error:
1071 This code is used if the network downloader tool fails for some
1075 File: qi.info, Node: Index, Prev: Qi exit status, Up: Top
1083 * configuration file: The qirc file. (line 6)
1084 * environment variables: Recipes. (line 283)
1085 * exit codes: Qi exit status. (line 6)
1086 * handling build order: Order files. (line 6)
1087 * introduction to qi: Introduction to Qi. (line 6)
1088 * invocation: Invoking qi. (line 6)
1089 * managing packages: Packages. (line 6)
1090 * package blacklist: Packages. (line 189)
1091 * package build: Recipes. (line 237)
1092 * package conflicts: Packages. (line 31)
1093 * package creation: Creating packages. (line 6)
1094 * package de-installation: Packages. (line 112)
1095 * package examination: Examining packages. (line 6)
1096 * package installation: Packages. (line 56)
1097 * package upgrade: Packages. (line 151)
1098 * recipes: Recipes. (line 6)
1099 * special variables: Recipes. (line 61)
1100 * the meta file: Recipes. (line 340)
1101 * variables: Recipes. (line 32)
1102 * writing recipes: Recipes. (line 223)
1108 Node: Introduction to Qi
\x7f1195
1109 Node: Invoking qi
\x7f2399
1110 Node: The qirc file
\x7f6527
1111 Node: Packages
\x7f7491
1112 Ref: Packages-Footnote-1
\x7f15527
1113 Ref: Packages-Footnote-2
\x7f15629
1114 Node: Recipes
\x7f15743
1115 Ref: Recipes-Footnote-1
\x7f31582
1116 Node: Order files
\x7f31728
1117 Node: Creating packages
\x7f33049
1118 Node: Examining packages
\x7f34037
1119 Node: Qi exit status
\x7f34955
1120 Node: Index
\x7f36825