qi: make release of qi 1.1
[dragora.git] / qi / doc / qi.texi
1 \input texinfo   @c -*-texinfo-*-
2 @comment $Id@w{$}
3 @comment %**start of header
4 @setfilename qi.info
5 @settitle Qi user guide
6 @documentencoding ISO-8859-1
7 @syncodeindex pg cp
8 @comment %**end of header
10 @set VERSION 1.1
11 @set UPDATED 19 May 2019
13 @copying
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,
18 Argentina.
20 @quotation
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''.
27 @end quotation
28 @end copying
30 @dircategory Package management
31 @direntry
32 * Qi: (qi).                   A user-friendly package manager.
33 @end direntry
35 @titlepage
36 @finalout
37 @title Qi
38 @subtitle for version @value{VERSION}, @value{UPDATED}
39 @author Matias Fonzo (@email{selk@@dragora.org})
41 @page
42 @vskip 0pt plus 1filll
43 @insertcopying
44 @end titlepage
46 @contents
48 @ifnottex
49 @node Top
50 @top
52 This user guide is for Qi (version @value{VERSION},
53 @value{UPDATED}).
54 @end ifnottex
56 @menu
57 * Introduction::              Description and features of qi
58 * Invoking qi::               Command-line options
59 * The qirc file::             Configuration file
60 * Packages::                  Managing packages
61 * Recipes::                   Building packages
62 * Order files::               Handling build order
63 * Creating packages::         Making Qi packages
64 * Examining packages::        Debugging purposes
65 * Exit status::               Exit codes
66 * Index::
67 @end menu
69 @sp 1
70 Copyright (C) 2019 Matias Fonzo.
72 Qi's home page can be found at @uref{http://www.dragora.org}.
73 @w{Send bug reports or suggestions to @email{dragora-users@@nongnu.org}.}
75 @node Introduction
76 @chapter Introduction
77 @cindex introduction
79 Qi is a simple but well-integrated package manager.  It can create,
80 install, remove, and upgrade software packages.  Qi produces binary
81 packages using recipes, which are files containing specific instructions
82 to build each package from source.  Qi can manage multiple packages
83 under a single directory hierarchy.  This method allows to maintain a set
84 of packages and multiple versions of them.  This means that Qi could be
85 used as the main package manager or complement the existing one.
87 Qi offers a friendly command line interface, a global configuration
88 file, a simple recipe layout to deploy software packages; also works
89 with binary packages in parallel, speeding up installations and packages
90 in production.  The format used for packages is a simplified but safe
91 POSIX pax archive compressed with lzip.
93 Qi is a modern (POSIX-compliant) shell script released under the
94 terms of the GNU General Public License.  There are only two major
95 dependencies for the magic: graft(1) and tarlz(1), the rest is expected
96 to be found in any Unix-like system.
98 @node Invoking qi
99 @chapter Invoking qi
100 @cindex invocation
102 This chapter describes the synopsis and command line options for
103 invoke Qi.
105 @example
106 Usage: qi [@var{OPTION}]... [@var{FILE}]...
107 @end example
109 @noindent
110 One mandatory option specifies the operation that @samp{qi} should
111 perform, other options are meant to detail how this operation should be
112 performed.
114 @noindent
115 qi supports the following options to operate:
117 @table @code
118 @item -b
119 Build package using recipe names.
121 @item -c
122 Create .tlz package from directory.
124 @item -d
125 Delete packages.
127 @item -i
128 Install packages.
130 @item -o
131 Resolve build order through .order files.
133 @item -u
134 Update packages (implies -i, -d and -p options).
136 @item -w
137 Warn about files that will be linked.
139 @item -x
140 Extract a package for debugging purposes.
141 @end table
143 @noindent
144 There are common options between modes:
146 @table @code
147 @item -N
148 Do not read the configuration file.
150 This will ignore any value in the qirc file.
152 @item -P <DIR>
153 Package directory for installations.
155 This option sets @samp{$@{packagedir@}}.
157 Only valid for -i, -d, or -u options.
159 @item -f
160 Force option.
162 This option can force the build of a recipe, or force the update of a
163 pre-existing package.
165 Only valid for -b, -u options.
167 @item -t <DIR>
168 Target directory for symbolic links.
170 This option sets @samp{$@{targetdir@}}.
172 Only valid for -i, -d, or -u options.
174 @item -k
175 Keep (don't delete) @samp{$@{srcdir@}} or @samp{$@{destdir@}} in build
176 mode, keep (don't delete) package directory in delete mode.
178 Only valid for -b, -d or -u options.
180 @item -p
181 Prune conflicts on package installations.
183 This option may proceed with the package installation if one or more
184 conflicts occur.
186 @item -r /rootdir
187 Use the fully qualified named directory as the root directory for all qi
188 operations.  The target directory and package directory will be relative
189 to the specified directory, including the log file for graft.
191 @item -v
192 Be verbose (a 2nd -v gives more).
193 @end table
195 @noindent
196 Options for build mode (-b):
198 @table @code
199 @item -O <DIR>
200 Where the packages produced are written.
202 This option sets @samp{$@{outdir@}}.
204 @item -W <DIR>
205 Where archives, patches, and recipes are expected.
207 This option sets @samp{$@{worktree@}}.
209 @item -Z <DIR>
210 Where (compressed) sources will be found.
212 This option sets @samp{$@{tardir@}}.
214 @item -a
215 Architecture to use.
217 Default value is obtained via uname(1) as @samp{uname -m}.
219 @item -j
220 Parallel jobs for the compiler.
222 If not specified, default sets to 1.
224 @item -1
225 Increment release number (@samp{$@{release@}} + 1).
227 It will be omitted if the -n option is being used.
229 @item -n
230 Don't create a .tlz package.
232 @item -S
233 Selects the option to skip completed recipes.
235 This means, in interactive mode, when the dialog
236 to summarize recipes is shown.
237 @end table
239 @noindent
240 Informative options:
242 @table @code
243 @item -L
244 Print default directory locations.
246 This will print the target directory, package directory, working tree,
247 the directory for tarballs, and the output directory for the packages
248 produced.
250 @item -h
251 Display the help describing the options and then exit.
253 @item -V
254 Print the version number and license information.
255 The version number should be included in all bug reports.
256 @end table
258 @noindent
259 Expected non-option arguments are package directories and regular files:
260 recipes or files ending in .tlz, .order.  When FILE is -, qi can read from
261 the standard input.  See examples in @ref{Packages}.
264 @node The qirc file
265 @chapter The qirc file
266 @cindex configuration file
268 The global @file{qirc} file offers a way to define variables and tools
269 (such as a download manager) for default use.  This file is used by qi
270 at runtime, e.g., to build, install, remove or upgrade packages.
272 @noindent
273 It has the following rules:
275 @itemize @bullet
276 @item Variables must be declared as @samp{name=value}.
278 @item Declaration of values should only take one line, no line break.
280 @item For security reasons, assignments like @samp{name=$var} are only
281 interpreted as literal.
282 @end itemize
284 @noindent
285 The command line options related to the package directory and target
286 directory plus some of the options used for the build mode can override
287 some values in @file{qirc}.  See @ref{Invoking qi}.
289 @noindent
290 The order in which qi looks for this file is:
292 @enumerate
293 @item
294 @env{$@{HOME@}/.qirc}
295 @- Effective user.
297 @item
298 @samp{$@{sysconfdir@}/qirc}
299 @- System-wide.
300 @end enumerate
302 If you intend to run qi as effective user, the file
303 @samp{$@{sysconfdir@}/qirc} could be copied to @env{$@{HOME@}/.qirc}
304 setting the paths for @samp{$@{packagedir@}} and @samp{$@{targetdir@}}
305 according to the @env{$HOME}.
308 @node Packages
309 @chapter Packages
310 @cindex managing packages
312 A package is a suite of programs usually distributed in binary form
313 which may also contain manual pages, documentation, or any other file
314 associated to a specific software.
316 The package format used by qi is a simplified POSIX pax archive
317 compressed with lzip.  The file extension for packages is @samp{.tlz}.
319 @noindent
320 Both package installation and package de-installation are managed using
321 two important (internal) variables: @samp{$@{packagedir@}} and
322 @samp{$@{targetdir@}}, these values can be changed in the
323 configuration file or via options.
325 @samp{$@{packagedir@}} is a common directory tree where the package
326 contents will be decompressed (will reside).
328 @samp{$@{targetdir@}} is a target directory where the links will be
329 made by graft(1) taking @samp{$@{packagedir@}/package_name} into account.
331 @noindent
332 Packages are installed in self-contained directory trees and symbolic
333 links from a common area are made to the package files.  This allows
334 multiple versions of the same package to coexist on the same system.
336 @section Package conflicts
337 @cindex package conflicts
339 All the links to install or remove a package are handled by graft(1).
340 Since multiple packages can be installed or removed at the same time,
341 certain conflicts may arise between the packages.
343 @noindent
344 graft@footnote{The official guide for Graft can be found at
345 @url{http://peters.gormand.com.au/Home/tools/graft/graft.html}.}
346 defines a CONFLICT as one of the following conditions:
348 @itemize @bullet
349 @item
350 If the package object is a directory and the target object exists but is
351 not a directory.
353 @item
354 If the package object is not a directory and the target object exists
355 and is not a symbolic link.
357 @item
358 If the package object is not a directory and the target object exists
359 and is a symbolic link to something other than the package object.
360 @end itemize
362 @noindent
363 The default behavior of qi for an incoming package is to ABORT if a
364 conflict arises.  When a package is going to be deleted, qi tells to
365 graft(1) to remove those parts that are not in conflict, leaving the
366 links to the belonging package.  This behavior can be forced if the
367 -p option is given.
369 @section Installing packages
370 @cindex package installation
372 To install a single package, simply type:
374 @example
375 qi -i coreutils-8.30-i586+1.tlz
376 @end example
378 @noindent
379 To install multiple packages at once, type:
381 @example
382 qi -i gcc-8.3.0-i586+1.tlz rafaela-2.2-i586+1.tlz ...
383 @end example
385 @noindent
386 Warn about the files that will be linked:
388 @example
389 qi -w bash-5.0-i586+1.tlz
390 @end example
392 This is to verify the content of a package before installing it.
394 @noindent
395 See the process of an installation (very verbose):
397 @example
398 qi -i -v mariana-3.0-i586+1.tlz
399 @end example
401 A second -v gives more.
403 @noindent
404 Installing package in a different location:
406 @example
407 qi -r /media/floppy -i lzip-1.21-i586+1.tlz
408 @end example
410 The -r option assumes @samp{$@{targetdir@}} and @samp{$@{packagedir@}}.
411 See:
413 @example
414 qi -r /home/selk -P /pkgs -t / -i lzip-1.21-i586+1.tlz
415 @end example
417 In this case the content of "lzip-1.21-i586+1.tlz" will be decompressed
418 into @samp{/home/selk/pkgs/lzip-1.21-i586+1}.  Assuming that the main
419 binary for lzip is under @samp{/home/selk/pkgs/lzip-1.21-i586+1/usr/bin/}
420 the target for "usr/bin" will be created at @samp{/home/selk}.  Considering
421 that you have exported the @env{PATH} as @samp{$@{HOME@}/usr/bin}, now the
422 system is able to see the recent lzip.
424 @noindent
425 Installing from a list of packages using standard input:
427 @example
428 cat FILELIST.txt | qi -i -
429 @end example
431 The list of packages must contain full path names to be passed in the
432 installation, e.g.:
433 /var/cache/qi/packages/x86_64/devel/tcl-8.6.9-x86_64+1.tlz
434 /var/cache/qi/packages/x86_64/devel/tk-
435 /var/cache/qi/packages/x86_64/devel/vala-0.42.3-x86_64+1.tlz
437 @section Removing packages
438 @cindex package de-installation
440 To remove a package, simply type:
442 @example
443 qi -d xz-5.2.4-i586+1.tlz
444 @end example
446 @noindent
447 Delete mode will match the package name using @samp{$@{packagedir@}} as
448 prefix.  For example, if the value of @samp{$@{packagedir@}} is set to
449 /usr/local/pkgs, this will be equal to:
451 @example
452 qi -d /usr/local/pkgs/xz-5.2.4-i586+1
453 @end example
455 @noindent
456 Detailed output (very verbose):
458 @example
459 qi -d -v /usr/local/pkgs/xz-5.2.4-i586+1
460 @end example
462 A second -v gives more.
464 @noindent
465 By default the delete mode does not preserve a package directory after
466 removing its links from @samp{$@{targetdir@}}, but this behavior can be
467 changed if the -k option is passed:
469 @example
470 qi -d -k /usr/local/pkgs/lzip-1.21-i586+1
471 @end example
473 This means that the links to the package can be reactivated, later:
475 @example
476 cd /usr/local/pkgs && graft -i lzip-1.21-i586+1
477 @end example
479 @noindent
480 Removing package from a different location:
482 @example
483 qi -r /home/cthulhu -P /pkgs -t / -d xz-5.2.4-i586+1
484 @end example
486 @noindent
487 Removing a package using standard input:
489 @example
490 echo "vala-0.42.3-x86_64+1" | qi -d -
491 @end example
493 This will match with the package directory.
495 @section Upgrading packages
496 @cindex package upgrade
498 The upgrade mode inherits the properties of the installation and removal
499 process.  To make sure that a package is updated, the package is installed
500 in a temporary directory taking @samp{$@{packagedir@}} into account.  Once
501 the incoming package is pre-installed, qi can proceed to search and delete
502 packages that have the same name (considered as previous ones).  Finally,
503 the package is re-installed at its final location and the temporary
504 directory is removed.
506 @noindent
507 To upgrade a package, just type:
509 @example
510 qi -u gcc-9.0.1-i586+1.tlz
511 @end example
513 This will proceed to update "gcc-9.0.1-i586+1" removing other versions
514 of "gcc" (if any).
516 @noindent
517 If you want to keep the package directories of versions found during the
518 upgrade process, just pass:
520 @example
521 qi -u -k gcc-9.0.1-i586+1.tlz
522 @end example
524 @noindent
525 To see the upgrade process (very verbose):
527 @example
528 qi -u -v gcc-9.0.1-i586+1.tlz
529 @end example
531 A second -v gives more.
533 @noindent
534 To force the upgrade of an existing package:
536 @example
537 qi -u -f gcc-9.0.1-i586+1.tlz
538 @end example
540 @subsection Package blacklist
541 @cindex package blacklist
543 To implement general package facilities, either to install, remove or
544 maintain the hierarchy of packages in a clean manner, qi makes use of the
545 pruning operation via graft(1):
547 There is a risk if those are crucial packages for the proper functioning
548 of the system, because it implies the deactivation of symbolic from the
549 target directory, @emph{especially} when transitioning an incoming package
550 into its final location during upgrade.
552 @noindent
553 A blacklist of package names has been devised for the case where
554 a user decides to upgrade all packages in the system, or
555 just the crucial ones, such as the C library.
557 The blacklist is related to the upgrade mode only, consists in installing
558 a package instead of updating it or removing previous versions of it;
559 the content of the package will be updated over the existing content at
560 @samp{$@{packagedir@}}, while the existing links from
561 @samp{$@{targetdir@}} will be preserved.  A pruning of links will be
562 carried out in order to re-link possible differences with the recent
563 content, this helps to avoid leaving dead links in the target directory.
565 @noindent
566 Since the upgrade mode is also used to install a new package, the mechanism
567 for blacklist is to install a declared package if it does not already
568 exist.  If it already exists, it is verified that the binary package is
569 newer than the package directory in order to perform an update.
571 Package names for the blacklist can be set from the configuration file.
574 @node Recipes
575 @chapter Recipes
576 @cindex recipes
578 A recipe is a file telling qi what to do.  Most often, the recipe tells
579 qi how to build a binary package from a source tarball.
581 A recipe has two parts: a list of variable definitions and a list of
582 sections.  By convention, the syntax of a section is:
584 @example
585 section_name()
587     section lines
589 @end example
591 The section name is followed by parentheses, one newline and an opening
592 brace.  The line finishing the section contains just a closing brace.
593 The section names or the function names currently recognized are
594 @samp{build}.
596 The @samp{build} section is an augmented shell script.  This is the main
597 section (or @strong{shell function}) which contains the instructions to
598 build and produce a package.
600 @section Variables
601 @cindex variables
603 A "variable" is a @strong{shell variable} defined either in @file{qirc}
604 or in a recipe to represent a string of text, called the variable's
605 "value".  These values are substituted by explicit request in the
606 definitions of other variables or in calls to external commands.
608 Variables can represent lists of file names, options to pass to
609 compilers, programs to run, directories to look in for source files,
610 directories to write output to, or anything else you can imagine.
612 Definitions of variables in qi have four levels of precedence.
613 Options which define variables from the command-line override those
614 specified in the @file{qirc} file, while variables defined in the recipe
615 override those specified in @file{qirc}, taking priority over those
616 variables set by command-line options.  Finally, the variables have
617 default values if they are not defined anywhere.
619 Options that set variables through the command-line can only reference
620 variables defined in @file{qirc} and variables with default values.
622 Definitions of variables in @file{qirc} can only reference variables
623 previously defined in @file{qirc} and variables with default values.
625 Definitions of variables in the recipe can only reference variables
626 set by the command-line, variables previously defined in the recipe,
627 variables defined in @file{qirc}, and variables with default values.
629 @section Special variables
630 @cindex special variables
632 There are variables which can only be set using the command line options or
633 via @file{qirc}, there are other special variables which can be defined or
634 redefined in a recipe.  See the following definitions:
636 @samp{outdir} is the directory where the packages produced are written.
637 This variable can not be redefined in the recipe.  Default sets to
638 @samp{/var/cache/qi/packages}.
640 @samp{worktree} is the working tree where archives, patches, and recipes
641 are expected.  This variable can not be redefined in the recipe.  Default
642 sets to @samp{/usr/src/qi}.
644 @samp{tardir} is defined in the recipe to the directory where the tarball
645 containing the source can be found.  The full name of the tarball is
646 composed as @samp{$@{tardir@}/$tarname}.  Its value is available in the
647 recipe as @samp{$@{tardir@}}; a value of . for @samp{tardir} sets it to
648 the value of CWD (Current Working Directory), this is where the recipe
649 lives.
651 @samp{arch} is the architecture to compose the package name.  Its value is
652 available in the recipe as @samp{$@{arch@}}.  Default value is the output
653 of @samp{uname -m}.
655 @samp{jobs} is the number of parallel jobs to pass to the compiler.  Its
656 value is available in the recipe as @samp{$@{jobs@}}.  The default value
657 is 1.
659 The two variables @samp{$@{srcdir@}} and @samp{$@{destdir@}} can be
660 set in the recipe, as any other variable, but if they are not, qi uses
661 default values for them when building a package.
663 @samp{srcdir} contains the source code to be compiled, and defaults to
664 @samp{$@{program@}-$@{version@}}.  @samp{destdir} is the place where the
665 built package will be installed, and defaults to
666 @samp{$@{TMPDIR@}/package-$@{program@}}.
668 If @samp{pkgname} is left undefined, the special variable @samp{program}
669 is assigned by default.  If @samp{pkgversion} is left undefined, the
670 special variable @samp{version} is assigned by default.
672 @samp{pkgname} and @samp{pkgversion} along with: @samp{version}, @samp{arch},
673 and @samp{release} are used to produce the name of the package in the form:
674 @samp{$@{pkgname@}-$@{pkgversion@}-$@{arch@}+$@{release@}.tlz}
676 A special variable called @samp{replace} can be used to declare package
677 names that will be replaced at the time of installation.
679 @noindent
680 A typical recipe contains the following variables:
682 @itemize @bullet
683 @item @samp{program}: software name.
685 It matches the source name.  It is also used to compose the name of the
686 package if @samp{$@{pkgname@}} is not specified.
688 @item @samp{version}: software version.
690 It matches the source name.  It is also used to compose the version of the
691 package if @samp{$@{pkgversion@}} is not specified.
693 @item @samp{arch}: software architecture.
695 It is used to compose the architecture of the package in which it is
696 build.
698 @item @samp{release}: release number.
700 This is used to reflect the release number of the package.  It is
701 recommended to increase this number after any significant change in
702 the recipe or post-install script.
703 @end itemize
705 @noindent
706 Obtaining sources over the network must be declared in the recipe using
707 the @samp{fetch} variable.  Use double quotes for separated values.
709 The variables @samp{netget} and @samp{rsync} can be defined in @file{qirc}
710 to establish a network downloader in order to get the sources.  If they
711 are not defined, qi uses default values:
713 @samp{netget} is the general network downloader tool, defaults sets to
714 @samp{wget -c -w1 -t3 --no-check-certificate}.
716 @samp{rsync} is the network tool for sources containing the prefix for
717 the RSYNC protocol, default sets to
718 @samp{rsync -v -a -L -z -i --progress}.
720 The variable @samp{description} is used to print the package description
721 when a package is installed.
723 A description has two parts: a brief description, and a long description.
724 By convention, the syntax of @samp{description} is:
726 @example
727 description="
728 Brief description.
730 Long description.
732 @end example
734 The first line of the value represented is a brief description of the
735 software (called "blurb").  A blank line separates the @emph{brief
736 description} from the @emph{long description}, which should contain a more
737 descriptive description of the software.
739 @noindent
740 An example looks like:
742 @example
743 description="
744 The GNU core utilities.
746 The GNU core utilities are the basic file, shell and text manipulation
747 utilities of the GNU operating system.  These are the core utilities
748 which are expected to exist on every operating system.
750 @end example
752 Please consider a length limit of 78 characters as maximum, because the same
753 one would be used on the meta file creation.  See
754 @ref{Recipes, The meta file} section.
756 The @samp{homepage} variable is used to declare the main site or home page:
758 @example
759 homepage=http://www.gnu.org/software/gcc
760 @end example
762 The variable @samp{license} is used for license information@footnote{
763 The proposal for @samp{license} was made by Richard M. Stallman at
764 @url{http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html}.}.
765 Some code in the program can be covered by license A, license B, or
766 license C.  For "separate licensing" or "heterogeneous licensing", we
767 suggest using @strong{|} for a disjunction, @strong{&} for a conjunction
768 (if that ever happens in a significant way), and comma for heterogeneous
769 licensing.  Comma would have lower precedence, plus added special terms.
771 @example
772 license="LGPL, GPL | Artistic + added permission"
773 @end example
775 @section Writing recipes
776 @cindex writing recipes
778 Originally, qi was designed for the version 3 of Dragora GNU/Linux (this
779 does not mean that you can't use it in another distribution, just that
780 if you do you will need to test it for your selves).  To aid this here
781 are some references to well written recipes:
783 @noindent
784 @url{http://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes}.
785 @url{http://notabug.org/dragora/dragora/src/master/recipes}.
787 You can also check the "doc" directory in the distribution sources of qi
788 for some examples.
790 @section Building packages
791 @cindex package build
793 A recipe is any valid regular file.  Qi sets priorities for reading a
794 recipe, the order in which qi looks for a recipe is:
796 @enumerate
797 @item
798 Current working directory.
800 @item
801 If the specified path name does not contain "recipe" as the last
802 component.  Qi will complete it by adding "recipe" to the path name.
804 @item
805 If the recipe is not in the current working directory, it will be
806 searched under @samp{$@{worktree@}/recipes}.  The last component will be
807 completed adding "recipe" to the specified path name.
808 @end enumerate
810 @noindent
811 To build a single package, type:
813 @example
814 qi -b x-apps/xterm
815 @end example
817 @noindent
818 Multiple jobs can be passed to the compiler to speed up the build process:
820 @example
821 qi -b -j3 x-apps/xterm
822 @end example
824 @noindent
825 Update or install the package produced (if it is not already installed)
826 when finish:
828 @example
829 qi -b -j3 -u x-apps/xterm
830 @end example
832 @noindent
833 Only process a recipe but do not create the binary package:
835 @example
836 qi -b -n dict/aspell
837 @end example
839 The options -i or -u have no effect when -n is given.
841 @noindent
842 This can be useful to inspect the build process of recipe:
844 qi -b -k -n dict/aspell 2>&1 | tee aspell-buildlog.txt
846 The -k option could preserve the source directory and the destination
847 directory for later inspection.  A log file of the build process will be
848 created redirecting both, standard error and standard output to tee(1).
850 @section Variables from the environment
851 @cindex environment variables
853 Qi has environment variables which can be used at build time:
855 The variable @env{TMPDIR} sets the temporary directory for sources, which is
856 used for package extractions (see @ref{Examining packages}) and is
857 prepended to the value of @samp{$@{srcdir@}} and @samp{$@{destdir@}} in
858 build mode.  By convention its default value is equal to
859 @samp{/usr/src/qi/build}.
861 The variables @env{QICFLAGS}, @env{QICXXFLAGS}, and @env{QILDFLAGS} have
862 no effect by default.  The environment variables such as @env{CFLAGS},
863 @env{CXXFLAGS}, and @env{LDFLAGS} are unset at compile time:
865 @noindent
866 Recommended practice is to set variables in the command line of
867 @samp{configure} or @emph{make(1)} instead of exporting to the
868 environment.  As follows:
870 @quotation
871 Variables not defined in a site shell script can be set in the environment
872 passed to configure.  However, some packages may run configure again
873 during the build, and the customized values of these variables may be
874 lost.  In order to avoid this problem, you should set them in the
875 configure command line, using @samp{VAR=value}.  For example:
877 @code{./configure CC=/usr/local2/bin/gcc}
879 @url{http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html}
880 @end quotation
882 @quotation
883 Indeed, while configure can notice the definition of CC in
884 @samp{./configure CC=bizarre-cc}, it is impossible to notice it in
885 @samp{CC=bizarre-cc ./configure}, which, unfortunately, is what most
886 users do.
888 [...]
890 configure: error: changes in the environment can compromise the build.
892 @url{http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html}
893 @end quotation
895 @quotation
896 It is not wise for makefiles to depend for their functioning on
897 environment variables set up outside their control, since this would cause
898 different users to get different results from the same makefile.  This is
899 against the whole purpose of most makefiles.
901 @url{http://gnu.org/software/make/manual/make.html#Environment}
902 @end quotation
904 @section The meta file
905 @cindex the meta file
907 The "meta file" is a regular file created during the build mode, it
908 contains information about the package such as program name, program
909 version, release, fetch address, description, and other minor data
910 extracted from processed recipes.  The name of the file is generated as
911 @samp{$@{full_pkgname@}.tlz.txt}, and its purpose is to reflect essential
912 information to the user without having to look inside the package content.
914 The content of a meta file looks like:
916 @example
918 # The Bourne Again SHell.
920 # Bash is an sh-compatible shell that incorporates useful features from
921 # the Korn shell (ksh) and C shell (csh).  It is intended to conform to
922 # the IEEE POSIX P1003.2/ISO 9945.2 shell and tools standard.
924 # It offers functional improvements over sh for both programming and
925 # interactive use.
928 QICFLAGS="-g0 -Os -mtune=generic -pipe"
929 QICXXFLAGS="-g0 -Os -mtune=generic -pipe"
930 QILDFLAGS="-s"
931 program=bash
932 version=5.0
933 release=1
934 blurb="The Bourne Again SHell."
935 homepage="http://www.gnu.org/software/bash"
936 license="GPLv3+"
937 fetch="ftp://ftp.gnu.org/gnu/bash/bash-5.0.tar.gz"
938 replace=""
939 @end example
941 Package descriptions are extracted from the variable @samp{description}:
942 each line is interpreted literally and pre-formatted to fit in (exactly)
943 @strong{80 columns}, plus the character @samp{#} and a space is prefixed
944 to every line.
946 @noindent
947 In addition to the Special variables, there are implicit variables such as
948 @samp{blurb}:
950 The @samp{blurb} variable is related to the special variable
951 @samp{description}.  Its value is composed using the first (substantial)
952 line of @samp{description}, mentioned as the "brief description".
955 @node Order files
956 @chapter Order files
957 @cindex handling build order
959 The order mode has the purpose of resolving the build order through
960 .order files.  An order file contains a list of recipe names, by default
961 does not perform any action other than to print a resolved list in
962 descending order.  For example, if @strong{a} depends on @strong{b} and
963 @strong{c}, and @strong{c} depends on @strong{b} as well, the file might
964 look like:
966 @example
967 a: c b
969 c: b
970 @end example
972 Each letter represents a recipe name, complete dependencies for
973 the first recipe name are listed in descending order, which is
974 printed from right to left, and removed from left to right:
976 @sc{Output}
978 @example
982 @end example
984 Blank lines, colons and parentheses are simply ignored.  Comment lines
985 beginning with @samp{#} are allowed.
987 @noindent
988 An order file could be used to build a series of packages, for example,
989 if the content is:
991 @example
992 # Image handling libraries
994 libs/libjpeg-turbo: devel/nasm
995 x-libs/jasper: libs/libjpeg-turbo
996 libs/tiff: libs/libjpeg-turbo
997 @end example
999 To proceed with each recipe, we can type:
1001 @example
1002 qi -o imglibs.order | qi -b -i -
1003 @end example
1005 The output of @samp{qi -o imglibs.order} tells to qi in which order it
1006 should build the recipes:
1008 @example
1009 devel/nasm
1010 libs/libjpeg-turbo
1011 x-libs/jasper
1012 libs/tiff
1013 @end example
1016 @node Creating packages
1017 @chapter Creating packages
1018 @cindex package creation
1020 The "creation mode" is an internal function of qi to make new Qi compatible
1021 compatible packages, the creation mode is selected by the -c option.
1022 A package is produced using the contents of the Current Directory, and
1023 the package file is written out.
1025 @example
1026 Usage: qi -c [@var{OUTPUT/packagename.tlz}]...
1027 @end example
1029 The argument for the file name to be written must contain a fully
1030 qualified named directory as the output directory where the package
1031 produced will be written.  The file name should be composed using the
1032 full name: name-version-architecture+release.tlz
1034 @sc{Example}
1036 @example
1037 cd /usr/local/pkgs
1038 cd claws-mail-3.17.1-x86_64+1
1039 qi -c /var/cache/qi/packages/x86_64/local/claws-mail-3.17.1-x86_64+1.tlz
1040 @end example
1042 In this case, the package "claws-mail-3.17.1-x86_64+1.tlz" will be written
1043 into @samp{/var/cache/qi/packages/x86_64/local/}.
1045 @noindent
1046 All packages produced are complemented by a checksum file (.sha256).
1049 @node Examining packages
1050 @chapter Examining packages
1051 @cindex package examination
1053 The "extraction mode" serves to examine binary packages for debugging
1054 purposes. The extraction mode is selected by the -x option.  It
1055 decompresses a package into a single directory, verifying its integrity
1056 and preserving its properties.
1058 @example
1059 Usage: qi -x [@var{packagename.tlz}]...
1060 @end example
1062 @sc{Example}
1064 @example
1065 qi -x mksh-R56c-x86_64+1.tlz
1066 @end example
1068 This action will put the content of "mksh-R56c-x86_64+1.tlz" into a
1069 single directory, this will be a private directory for the user who
1071 requested the action, creation mode will be equal to @strong{u=rwx,g=,o=
1072 (0700)}.  The package content will reside on this location, default
1073 mask to deploy the content will be equal to
1074 @strong{u=rwx,g=rwx,o=rwx (0000)}.
1076 @noindent
1077 The creation of the custom directory is influenced by the value of the
1078 @env{TMPDIR} variable.
1081 @node Exit status
1082 @chapter Exit status
1083 @cindex exit codes
1085 All the exit codes are described in this chapter.
1087 @table @samp
1088 @item 0
1089 Successful completion (no errors).
1091 @item 1
1092 Minor common errors:
1094 @itemize @minus
1095 @item Help usage on illegal options or required arguments.
1097 @item Program needed by qi (prerequisite) is not available.
1098 @end itemize
1100 @item 2
1101 Command execution error:
1103 This code is used to return the evaluation of external commands and shell
1104 arguments in case of error.
1106 @item 3
1107 Integrity check error for compressed files.
1109 Compressed files means:
1111 @itemize @minus
1112 @item Tarball files from tar(1).
1113 Supported extensions: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
1114 .tar.xz, .txz
1116 @item Tarball files from tarlz(1).
1117 Supported extensions: .tar.lz, .tlz
1119 @item Zip files from unzip(1).
1120 Supported extensions: .zip, .ZIP
1122 @item Gzip files from gzip(1).
1123 Supported extensions: .gz, .Z
1125 @item Bzip2 files from bzip2(1).
1126 Supported extensions: .bz2
1128 @item Lzip files from lzip(1).
1129 Supported extensions: .lz
1131 @item Xz files from xz(1).
1132 Supported extensions: .xz
1133 @end itemize
1135 @item 4
1136 File empty, not regular, or expected.
1138 Commonly, it is expected:
1140 @itemize @minus
1141 @item An argument for the mode of operation.
1143 @item A readable file or directory.
1145 @item A binary package (.tlz).
1147 @item A valid recipe.
1149 @item An order file (.order).
1151 @item A protocol supported by the network downloader tool.
1153 @item A checksum file (.sha256).
1154 @end itemize
1156 @item 5
1157 Empty or not defined variable:
1159 This code is used to report empty or undefined variables; usually,
1160 variables coming from a recipe or assigned arrays that are tested.
1162 @item 6
1163 Package already installed:
1165 The package directory for an incoming .tlz package already exists.
1167 @item 10
1168 Network manager error:
1170 This code is used if the network downloader tool fails for some reason.
1171 @end table
1174 @node Index
1175 @unnumbered Index
1177 @printindex cp
1179 @bye