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 27 March 2019
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 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 * License:: GNU Free Documentation License
68 Copyright (C) 2019 Matias Fonzo.
70 Qi's home page can be found at @uref{http://www.dragora.org}.
71 @w{Send bug reports or suggestions to @email{dragora-users@@nongnu.org}.}
77 Qi is a simple but well-integrated package manager. It can creates,
78 install, remove, and upgrade software packages. Qi produces binary
79 packages using recipe names, these are files containing specific
80 instructions to build every source. Qi can manage multiple packages
81 under a single directory hierarchy, this method allows to maintain a set
82 of packages and multiple versions of them. This means that Qi could be
83 used as the main package manager or as complementary.
85 Qi offers a friendly command line interface, a global configuration
86 file, a simple recipe layout to deploy software packages; it can also
87 work with binary packages in parallel, speeding up installations and
88 produced packages. The used format for packages is a simplified but
89 safe POSIX pax archive compressed with lzip.
91 Qi is a POSIX-compliant shell script released under the terms of the
92 GNU General Public License. It has only two major dependencies for the
93 magic: graft(1) and tarlz(1), the rest is expected to be found in any
100 This chapter describes the synopsis and command line options for
104 Usage: qi [@var{OPTION}]... [@var{FILE}]...
108 One mandatory option specifies the operation that @samp{qi} should
109 perform, other options are meant to detail how this operation should be
113 qi supports the following options to operate:
117 Build package using recipe names.
120 Create .tlz package from directory.
129 Resolve build order through .order files.
132 Update packages (implies -i, -d and -p options).
135 Warn about files that will be linked.
138 Extract a package for debugging purposes.
142 There are common options between modes:
146 Do not read the configuration file.
148 This will omit any value on the qirc file.
151 Package directory for installations.
153 This option sets @samp{$@{packagedir@}}.
155 Only valid for -i, -d, or -u options.
160 This can force the build of a recipe, or update a pre-existing package.
162 Only valid for -b, -u options.
165 Target directory for symbolic links.
167 This option sets @samp{$@{targetdir@}}.
169 Only valid for -i, -d, or -u options.
172 Keep (don't delete) @samp{$@{srcdir@}} or @samp{$@{destdir@}} on build
175 Keep (don't delete) package directory on delete mode.
177 Only valid for -b, -d or -u options.
180 Prune conflicts on package installations.
182 This option may proceed with the package installation if one or
183 more conflicts occur.
186 Use the fully qualified named directory as the root directory for all
187 qi operations. The target directory and package directory will
188 be relative to the specified directory.
191 Be verbose (a 2nd -v gives more).
195 Options for build mode (-b):
199 Where the produced packages are written.
201 This option sets @samp{$@{outdir@}}.
204 Where archives, patches, and recipes are expected.
206 This option sets @samp{$@{worktree@}}.
209 Where (compressed) sources will be found.
211 This option sets @samp{$@{tardir@}}.
216 Default value is obtained via uname(1) as @samp{uname -m}.
219 Parallel jobs for the compiler.
221 If not specified, default sets to 1.
224 Increment release number (@samp{$@{release@}} + 1).
226 It will be omitted if the -n option is being used.
229 Don't create a .tlz package.
232 Selects the option to skip completed recipes.
234 This means, in interactive mode, when the dialog
235 to summarize recipes is showed.
243 Print default directory locations.
245 This will print the target directory, package directory, working tree,
246 the directory for tarballs, and the output directory for produced
250 Display the help describing the options and then exit.
253 Print the version number and license information.
254 The version number should be included in all bug reports.
258 Expected arguments beyond of options are package directories and regular
259 files: recipes or files ending in .tlz, .order. When FILE is -, qi can
260 read from the standard input. See examples in @ref{Packages}.
264 @chapter The qirc file
265 @cindex configuration file
267 The global @file{qirc} file offers a way to define variables and tools
268 (such as a download manager) for default use. This file is used by qi
269 at runtime for e.g to build, install, remove or upgrade packages.
272 It has the following rules:
275 @item Variables must be declared as @samp{name=value}.
277 @item Declaration of values should only take one line, no line break.
279 @item For security reasons, assignments like @samp{name=$var} are only
280 interpreted as literal.
284 The command line options related to the package directory and target
285 directory plus some of the options used for the build mode can override
286 some values in @file{qirc}. See @ref{Invoking qi}.
289 The order in which qi looks for this file is:
293 @env{$@{HOME@}/.qirc}
297 @samp{$@{sysconfdir@}/qirc}
301 If you intend to run qi as effective user, the file
302 @samp{$@{sysconfdir@}/qirc} could be copied to @env{$@{HOME@}/.qirc}
303 setting the paths for @samp{$@{packagedir@}} and @samp{$@{targetdir@}}
304 according to the @env{$HOME}.
309 @cindex managing packages
311 A package is a suite of programs usually distributed in binary form
312 which may also contain manual pages, documentation, or any other file
313 associated to a specific software.
315 The package format used by qi is a simplified POSIX pax archive
316 compressed with lzip. The file extension for packages ends in .tlz
319 Both package installation and package de-installation are managed using
320 two important (internal) variables: @samp{$@{packagedir@}} and
321 @samp{$@{targetdir@}}, these values can be changed in the
322 configuration file or via options.
324 @samp{$@{packagedir@}} is a common directory tree where the package
325 contents will be decompressed (will reside).
327 @samp{$@{targetdir@}} is a target directory where the links will be
328 made by graft(1) taking @samp{$@{packagedir@}/package_name} into account.
331 Packages are installed in self-contained directory trees and symbolic
332 links from a common area are made to the package files. This allows
333 multiple versions of the same package to co-exist on the one system.
335 @section Package conflicts
336 @cindex package conflicts
338 All the links to install or remove a package are handled by graft(1).
339 Since multiple packages can be installed or removed at the same time,
340 certain conflicts may arise between the packages.
343 graft@footnote{The official guide for Graft can be found at
344 @url{http://peters.gormand.com.au/Home/tools/graft/graft.html}.}
345 defines a CONFLICT as one of the following conditions:
349 If the package object is a directory and the target object exists but is
353 If the package object is not a directory and the target object exists
354 and is not a symbolic link.
357 If the package object is not a directory and the target object exists
358 and is a symbolic link to something other than the package object.
362 The default behavior of qi for an incoming package is to ABORT if a
363 conflict arises. When a package is going to be deleted, qi tells to
364 graft(1) to remove those parts that are not in conflict, leaving the
365 links to the belonging package. This behavior can be forced if the
368 @section Installing packages
369 @cindex package installation
371 To install a single package, simply type:
374 qi -i coreutils-8.30-i586+1.tlz
378 To install multiple packages at once, type:
381 qi -i gcc-8.3.0-i586+1.tlz rafaela-2.2-i586+1.tlz ...
385 Warn about the files that will be linked:
388 qi -w bash-5.0-i586+1.tlz
391 This is to verify the content of a package before installing it.
394 See the process of an installation (very verbose):
397 qi -i -v mariana-3.0-i586+1.tlz
400 A second -v gives more.
403 Installing package in a different location:
406 qi -r /media/floppy -i lzip-1.21-i586+1.tlz
409 The -r option assumes @samp{$@{targetdir@}} and @samp{$@{packagedir@}}.
413 qi -r /home/selk -P /pkgs -t / -i lzip-1.21-i586+1.tlz
416 In this case the content of "lzip-1.21-i586+1.tlz" will be decompressed
417 into @samp{/home/selk/pkgs/lzip-1.21-i586+1}. Assuming that the main
418 binary for lzip is under @samp{/home/selk/pkgs/lzip-1.21-i586+1/usr/bin/}
419 the target for "usr/bin" will be created at @samp{/home/selk}. Considering
420 that you have exported the @env{PATH} as @samp{$@{HOME@}/usr/bin}, now the
421 system is able to see the recent lzip.
424 Installing from a list of packages using standard input:
427 cat FILELIST.txt | qi -i -
430 The list of packages must contain full path names to be passed in the
432 /var/cache/qi/packages/x86_64/devel/tcl-8.6.9-x86_64+1.tlz
433 /var/cache/qi/packages/x86_64/devel/tk-8.6.9.1-x86_64+1.tlz
434 /var/cache/qi/packages/x86_64/devel/vala-0.42.3-x86_64+1.tlz
436 @section Removing packages
437 @cindex package de-installation
439 To remove a package, simply type:
442 qi -d xz-5.2.4-i586+1.tlz
446 Delete mode will match the package name using @samp{$@{packagedir@}} as
447 prefix. For example, if the value of @samp{$@{packagedir@}} is set to
448 /usr/local/pkgs, this will be equal to:
451 qi -d /usr/local/pkgs/xz-5.2.4-i586+1
455 Detailed output (very verbose):
458 qi -d -v /usr/local/pkgs/xz-5.2.4-i586+1
461 A second -v gives more.
464 By default the delete mode does not preserve a package directory after
465 removing its links from @samp{$@{targetdir@}}, but this behavior can be
466 changed if the -k option is passed:
469 qi -d -k /usr/local/pkgs/lzip-1.21-i586+1
472 This means that the links to the package can be reactivated, later:
475 cd /usr/local/pkgs && graft -i lzip-1.21-i586+1
479 Removing package from a different location:
482 qi -r /home/cthulhu -P /pkgs -t / -d xz-5.2.4-i586+1
486 Removing a package using standard input:
489 echo "vala-0.42.3-x86_64+1" | qi -d -
492 This will match with the package directory.
494 @section Upgrading packages
495 @cindex package upgrade
497 The upgrade mode inherits the properties of the installation and removal
498 process. To make sure that a package is updated, the package is installed
499 in a temporary directory taking @samp{$@{packagedir@}} into account. Once
500 the incoming package is pre-installed, qi can proceed to search and delete
501 packages that have the same name (considered as previous ones). Finally,
502 the package is re-installed at its final location and the temporary
503 directory is removed.
506 To upgrade a package, just type:
509 qi -u gcc-9.0.1-i586+1.tlz
512 This will proceed to update "gcc-9.0.1-i586+1" removing other versions
516 If you want to keep the package directory of found versions during the
517 upgrade process, just pass:
520 qi -u -k gcc-9.0.1-i586+1.tlz
524 To see the upgrade process (very verbose):
527 qi -u -v gcc-9.0.1-i586+1.tlz
530 A second -v gives more.
532 @subsection Package blacklist
533 @cindex package blacklist
535 To enforce general package facilities, either to install, remove or
536 maintain the hierarchy of packages in a clean manner, qi makes use of the
537 pruning operation via graft(1):
539 There is a risk if those are crucial packages for the proper functioning
540 of the system, because it implies to deactivate symbolic links from the
541 target directory, @emph{especially} when transitioning an incoming package
542 into its final location during upgrade.
545 A blacklist for declare package names has been devised for this cases,
546 in case that a user decides to upgrade all packages in the system or,
547 just the crucial ones, such as the C library.
549 The blacklist is related to the upgrade mode only, consists in installing
550 a package instead of updating it or removing previous versions of it;
551 the content of the package will be updated over the existing content at
552 @samp{$@{packagedir@}}, while the existing links from
553 @samp{$@{targetdir@}} will be preserved. A pruning of links will carried
554 out in order to re-link possible differences with the recent content, this
555 helps to avoid having dead links in the target directory.
558 Since the upgrade mode is also used to install a new package, the mechanism
559 for blacklist is to install a declared package if it does not already
560 exist, if it already exists, it is verified that the binary package is
561 newer than the package directory in order to perform an update.
563 The names of packages for the blacklist can be configured from the
571 A recipe is a file telling qi what to do. Most often, the recipe tells to
572 qi how to build a binary package from a source tarball.
574 A recipe has two parts: a list of variable definitions and a list of
575 sections. By convention, the syntax of a section is:
584 The section name is followed by parentheses, one newline and an opening
585 brace. The line finishing the section contains just a closing brace.
586 The section names or the function names currently recognized are
589 The @samp{build} section is an augmented shell script. This is the main
590 section (or @strong{shell function}) which contains the instructions to
591 build and produce a package.
596 A "variable" is a @strong{shell variable} defined either in @file{qirc}
597 or in a recipe to represent a string of text, called the variable's
598 "value". These values are substituted by explicit request in the
599 definitions of other variables or in calls to external commands.
601 Variables can represent lists of file names, options to pass to
602 compilers, programs to run, directories to look in for source files,
603 directories to write output in, or anything else you can imagine.
605 Definitions of variables in qi have four levels of precedence.
606 Options which define variables from the command-line override those
607 specified in the @file{qirc} file, while variables defined in the recipe
608 override those specified in @file{qirc}, taking priority over those
609 variables settled by options via command-line. Finally, the variables
610 have default values if they are not defined anywhere.
612 Options that set variables through the command-line can only reference
613 variables defined in @file{qirc} and variables with default values.
615 Definitions of variables in @file{qirc} can only reference variables
616 previously defined in @file{qirc} and variables with default values.
618 Definitions of variables in the recipe can only reference variables
619 settled by command-line, variables previously defined in the recipe,
620 variables defined in @file{qirc}, and variables with default values.
622 @section Special variables
623 @cindex special variables
625 There are variables which can only be set using the command line options or
626 via @file{qirc}, there are other special variables which can be defined or
627 redefined in a recipe. See the following definitions:
629 @samp{outdir} is the directory where the produced packages are written.
630 This variable can not be redefined in the recipe. Default sets to
631 @samp{/var/cache/qi/packages}.
633 @samp{worktree} is the working tree where archives, patches, and recipes
634 are expected. This variable can not be redefined in the recipe. Default
635 sets to @samp{/usr/src/qi}.
637 @samp{tardir} is defined in the recipe to the directory where the tarball
638 containing the source can be found. The full name of the tarball is
639 composed as @samp{$@{tardir@}/$tarname}. Its value is available in the
640 recipe as @samp{$@{tardir@}}; a value of . for @samp{tardir} sets it to
641 the value of CWD (Current Working Directory), this is where the recipe
644 @samp{arch} is the architecture to compose the package name. Its value is
645 available in the recipe as @samp{$@{arch@}}. Default value is the output
648 @samp{jobs} is the number of parallel jobs to pass to the compiler. Its
649 value is available in the recipe as @samp{$@{jobs@}}. Default sets to
652 The two variables @samp{$@{srcdir@}} and @samp{$@{destdir@}} can be
653 set in the recipe, as any other variable, but if they are not, qi uses
654 default values for them when building a package.
656 @samp{srcdir} contains the source code to be compiled, and defaults to
657 @samp{$@{program@}-$@{version@}}. @samp{destdir} is the place where the
658 built package will be installed, and defaults to
659 @samp{$@{TMPDIR@}/package-$@{program@}}.
661 If @samp{pkgname} is left undefined, the special variable @samp{program}
662 is assigned by default. If @samp{pkgversion} is left undefined, the
663 special variable @samp{version} is assigned by default.
665 @samp{pkgname} and @samp{pkgversion} along with: @samp{version}, @samp{arch},
666 and @samp{release} are used to produce the name of the package in the form:
667 @samp{$@{pkgname@}-$@{pkgversion@}-$@{arch@}+$@{release@}.tlz}
670 A typical recipe contains:
673 @item @samp{program}: software name.
675 It matches the source name. It is also used to compose the name of the
676 package if @samp{$@{pkgname@}} is not specified.
678 @item @samp{version}: software version.
680 It matches the source name. It is also used to compose the version of the
681 package if @samp{$@{pkgversion@}} is not specified.
683 @item @samp{arch}: software architecture.
685 It is used to compose the architecture of the package in which it is
688 @item @samp{release}: release number.
690 This is used to reflect the release number of the package. It is
691 recommended to increase this number after any significant change in
692 the recipe or post-install script.
696 Obtaining sources over the network must be declared in the recipe using
697 the @samp{fetch} variable. Use double quotes for separated values.
699 The variables @samp{netget} and @samp{rsync} can be defined in @file{qirc}
700 to establish a network downloader in order to get the sources. If they
701 are not defined, qi uses default values:
703 @samp{netget} is the general network downloader tool, defaults sets to
704 @samp{wget -c -w1 -t3 --no-check-certificate}.
706 @samp{rsync} is the network tool for sources containing the prefix for
707 the RSYNC protocol, default sets to
708 @samp{rsync -v -a -L -z -i --progress}.
711 There are three important variables to produce meta information of the
712 package from a recipe: @samp{description}, @samp{homepage}, and
715 The variable @samp{description} is used to print the package description
716 when a package is installed.
719 A description has two parts: a brief description, and a long description.
720 By convention, the syntax of @samp{description} is:
730 The first (substantial) line of the value is a brief description of the
731 software (called "blurb"). A newline follows to separate the @emph{brief
732 description} from the @emph{long description}.
735 An example looks like:
739 The GNU core utilities.
741 The GNU core utilities are the basic file, shell and text manipulation
742 utilities of the GNU operating system. These are the core utilities
743 which are expected to exist on every operating system.
747 Please consider a length limit of 78 characters as maximum, because the same
748 one would be used on the meta file creation. See
749 @ref{Recipes, The meta file} section.
751 The @samp{homepage} variable is used to declare the main site or home page:
754 homepage=http://www.gnu.org/software/gcc
757 The variable @samp{license} is used for license information@footnote{
758 The proposal for @samp{license} was made by Richard M. Stallman at
759 @url{http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html}.}.
760 Some code in the program can be covered by license A, license B, or
761 license C. For "separate licensing" or "heterogeneous licensing", we
762 suggest using @strong{|} for a disjunction, @strong{&} for a conjunction
763 (if that ever happens in a significant way), and comma for heterogeneous
764 licensing. Comma would have lower precedence, plus added special terms.
767 license="LGPL, GPL | Artistic + added permission"
770 @section Building packages
771 @cindex package build
773 A recipe is any valid regular file, qi sets priorities to read a recipe,
774 for example, the Current Working Directory has priority over the working
775 tree (or where the recipes reside); the @samp{$@{worktree@}/recipes} is
776 the second place where to find a recipe, we complete the possibility of
777 using the directory name to invoke a recipe if it contains "recipe" inside
778 as a valid file name.
781 To build a single package, type:
788 Multiple jobs can be passed to the compiler for speed up the build process:
791 qi -b -j3 x-apps/xterm
795 Update or install the produced package (if it is not already installed)
799 qi -b -j3 -u x-apps/xterm
803 Only process a recipe but do not create the binary package:
809 The options -i or -u have no effect when -n is given.
812 This can be useful to inspect the build process of recipe:
814 qi -b -k -n dict/aspell 2>&1 | tee aspell-buildlog.txt
816 The -k option could preserve the source directory and the destination
817 directory for later inspection. A log file of the build process will be
818 created redirecting both, standard error and standard output to tee(1).
820 @section Variables from the environment
821 @cindex environment variables
823 Qi has environment variables which can be used at build time:
825 The variable @env{TMPDIR} sets the temporary directory for sources, by
826 default, this is used to prepend @samp{$@{srcdir@}} and
827 @samp{$@{destdir@}}. By convention its value is @samp{/tmp}.
829 The variables @env{QICFLAGS}, @env{QICXXFLAGS}, and @env{QILDFLAGS} have
830 no effect by default. The environment variables such as @env{CFLAGS},
831 @env{CXXFLAGS}, and @env{LDFLAGS} are unset at compile time:
834 Recommended practices is to set variables in front of @samp{configure}
835 or in front of @emph{make(1)} instead of exporting to the environment.
839 Variables not defined in a site shell script can be set in the environment
840 passed to configure. However, some packages may run configure again
841 during the build, and the customized values of these variables may be
842 lost. In order to avoid this problem, you should set them in the
843 configure command line, using @samp{VAR=value}. For example:
845 @code{./configure CC=/usr/local2/bin/gcc}
847 @url{http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html}
851 Indeed, while configure can notice the definition of CC in
852 @samp{./configure CC=bizarre-cc}, it is impossible to notice it in
853 @samp{CC=bizarre-cc ./configure}, which, unfortunately, is what most
858 configure: error: changes in the environment can compromise the build.
860 @url{http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html}
864 It is not wise for makefiles to depend for their functioning on
865 environment variables set up outside their control, since this would cause
866 different users to get different results from the same makefile. This is
867 against the whole purpose of most makefiles.
869 @url{http://gnu.org/software/make/manual/make.html#Environment}
872 @section The meta file
873 @cindex the meta file
875 The "meta file" is a regular file created during the build mode, it
876 contains information about the package such as program name, program
877 version, release, fetch address, description, and other minor data
878 extracted from the processed recipe. The name of the file is generated as
879 @samp{$@{full_pkgname@}.tlz.txt}, it has the purpose to reflect essential
880 information to the user without having to look inside the package content.
882 The content of a meta file looks like:
886 # The Bourne Again SHell.
888 # Bash is an sh-compatible shell that incorporates useful features from
889 # the Korn shell (ksh) and C shell (csh). It is intended to conform to
890 # the IEEE POSIX P1003.2/ISO 9945.2 shell and tools standard.
892 # It offers functional improvements over sh for both programming and
896 QICFLAGS="-g0 -Os -mtune=generic -pipe"
897 QICXXFLAGS="-g0 -Os -mtune=generic -pipe"
902 blurb="The Bourne Again SHell."
903 homepage="http://www.gnu.org/software/bash"
905 fetch="ftp://ftp.gnu.org/gnu/bash/bash-5.0.tar.gz"
909 A package description is extracted from the variable @samp{description},
910 each line will be interpreted literally and pre-formatted to fit in
911 (exactly) 80 columns, plus the character @samp{# } will be prefixed to
912 each line in the description.
914 In addition to the special variables, there are implicit variables such as
917 The @samp{blurb} variable is related to the special variable
918 @samp{description}. Its value is composed using the first (substantial)
919 line of @samp{description} (mentioned as the "brief description").
924 @cindex handling build order
926 The order mode has the purpose to resolve the build order through
927 .order files. A .order file contains a list of recipe names, by default
928 does not perform any action other than to print a resolved list in descending
929 order. For example, if @strong{a} depends on @strong{b} and @strong{c},
930 and @strong{c} depends on @strong{b} as well, the file might look like:
938 Each letter represents a recipe name, complete dependencies for
939 the first recipe name are listed in descending order, which is
940 printed from right to left, and removed from left to right:
950 Declaration of blank lines, colons, parentheses, and end of line are
951 ignored. Comments are allowed for lines that begin with @samp{#}.
954 An order file could be used to build a serie of packages, for example, if
958 # Image handling libraries
959 libs/libjpeg-turbo: devel/nasm
960 x-libs/jasper: libs/libjpeg-turbo
961 libs/tiff: libs/libjpeg-turbo
964 To proceed with each recipe, we can type:
967 qi -o imglibs.order | qi -b -i -
970 The output of @samp{qi -o imglibs.order} will tell to qi in which order it
971 should build the recipes/packages:
981 @appendix GNU Free Documentation License