qi: Bump to version 1.5 (Release Candidate 1)
[dragora.git] / qi / doc / qi.info
blob1f6f81bafd3fbc7dec361b408b8d833d2772ba1c
1 This is qi.info, produced by makeinfo version 6.5 from qi.texi.
3 This user guide is for Qi (version 1.5rc1, 24 Apr 2020), which is a
4 simple but well-integrated package manager.
6    Copyright © 2019-2020 Matias Andres Fonzo, Santiago del Estero,
7 Argentina.
9      Permission is granted to copy, distribute and/or modify this
10      document under the terms of the GNU Free Documentation License,
11      Version 1.3 or any later version published by the Free Software
12      Foundation; with no Invariant Sections, with no Front-Cover Texts,
13      and with no Back-Cover Texts.  A copy of the license is included in
14      the section entitled "GNU Free Documentation License".
15 INFO-DIR-SECTION Package management
16 START-INFO-DIR-ENTRY
17 * Qi: (qi).                   A user-friendly package manager.
18 END-INFO-DIR-ENTRY
20 \x1f
21 File: qi.info,  Node: Top,  Next: Introduction,  Up: (dir)
23 Qi user guide
24 *************
26 This user guide is for Qi (version 1.5rc1, 24 Apr 2020).
28 * Menu:
30 * Introduction::              Description and features of qi
31 * Invoking qi::               Command-line options
32 * The qirc file::             Configuration file
33 * Packages::                  Managing packages
34 * Recipes::                   Building packages
35 * Order files::               Handling build order
36 * Creating packages::         Making Qi packages
37 * Examining packages::        Debugging purposes
38 * Exit status::               Exit codes
39 * Index::
42    Copyright (C) 2019-2020 Matias Fonzo.
44    Qi's home page can be found at <https://www.dragora.org>.
45 Send bug reports or suggestions to <dragora-users@nongnu.org>.
47 \x1f
48 File: qi.info,  Node: Introduction,  Next: Invoking qi,  Prev: Top,  Up: Top
50 1 Introduction
51 **************
53 Qi is a simple but well-integrated package manager.  It can create,
54 install, remove, and upgrade software packages.  Qi produces binary
55 packages using recipes, which are files containing specific instructions
56 to build each package from source.  Qi can manage multiple packages
57 under a single directory hierarchy.  This method allows to maintain a
58 set of packages and multiple versions of them.  This means that Qi could
59 be used as the main package manager or complement the existing one.
61    Qi offers a friendly command line interface, a global configuration
62 file, a simple recipe layout to deploy software packages; also works
63 with binary packages in parallel, speeding up installations and packages
64 in production.  The format used for packages is a simplified but safe
65 POSIX pax archive compressed with lzip.
67    Qi is a modern (POSIX-compliant) shell script released under the
68 terms of the GNU General Public License.  There are only two major
69 dependencies for the magic: graft(1) and tarlz(1), the rest is expected
70 to be found in any Unix-like system.
72 \x1f
73 File: qi.info,  Node: Invoking qi,  Next: The qirc file,  Prev: Introduction,  Up: Top
75 2 Invoking qi
76 *************
78 This chapter describes the synopsis and command line options for invoke
79 Qi.
81      Usage: qi [OPTION]... [FILE]...
83 One mandatory option specifies the operation that 'qi' should perform,
84 other options are meant to detail how this operation should be
85 performed.
87 qi supports the following options to operate:
89 '-b'
90      Build package using recipe names.
92 '-c'
93      Create .tlz package from directory.
95 '-d'
96      Delete packages.
98 '-i'
99      Install packages.
101 '-o'
102      Resolve build order through .order files.
104 '-u'
105      Upgrade packages (implies -i, -d and -p options).
107 '-w'
108      Warn about files that will be linked.
110 '-x'
111      Extract a package for debugging purposes.
113 There are common options between modes:
115 '-N'
116      Do not read the configuration file.
118      This will ignore any value in the qirc file.
120 '-P <DIR>'
121      Package directory for installations.
123      This option sets '${packagedir}'.
125      Only valid for -i, -d, or -u options.
127 '-f'
128      Force option.
130      This option can force the build of a recipe, or force the upgrade
131      of a pre-existing package.
133      Only valid for -b, -u options.
135 '-t <DIR>'
136      Target directory for symbolic links.
138      This option sets '${targetdir}'.
140      Only valid for -i, -d, or -u options.
142 '-k'
143      Keep (don't delete) '${srcdir}' or '${destdir}' in build mode, keep
144      (don't delete) package directory in delete mode.
146      Only valid for -b, -d or -u options.
148 '-p'
149      Prune conflicts on package installations.
151      This option may proceed with the package installation if one or
152      more conflicts occur.
154 '-r /rootdir'
155      Use the fully qualified named directory as the root directory for
156      all qi operations.  The target directory and package directory will
157      be relative to the specified directory, including the log file for
158      graft.
160 '-v'
161      Be verbose (a 2nd -v gives more).
163 Options for build mode (-b):
165 '-O <DIR>'
166      Where the packages produced are written.
168      This option sets '${outdir}'.
170 '-W <DIR>'
171      Where archives, patches, and recipes are expected.
173      This option sets '${worktree}'.
175 '-Z <DIR>'
176      Where (compressed) sources will be found.
178      This option sets '${tardir}'.
180 '-a'
181      Architecture to use.
183      Default value is obtained via uname(1) as 'uname -m'.
185 '-j'
186      Parallel jobs for the compiler.
188      If not specified, default sets to 1.
190 '-1'
191      Increment release number ('${release}' + 1).
193      It will be omitted if the -n option is being used.
195 '-n'
196      Don't create a .tlz package.
198 '-S'
199      Selects the option to skip completed recipes.
201      This means, in interactive mode, when the dialog to summarize
202      recipes is shown.
204 Informative options:
206 '-L'
207      Print default directory locations.
209      This will print the target directory, package directory, working
210      tree, the directory for tarballs, and the output directory for the
211      packages produced.
213 '-h'
214      Display the help describing the options and then exit.
216 '-V'
217      Print the version number and license information.  The version
218      number should be included in all bug reports.
220 Expected non-option arguments are package directories and regular files:
221 recipes or files ending in .tlz, .order.
223    When FILE is -, qi can read from the standard input.  See examples at
224 *note Packages::.
226 \x1f
227 File: qi.info,  Node: The qirc file,  Next: Packages,  Prev: Invoking qi,  Up: Top
229 3 The qirc file
230 ***************
232 The global 'qirc' file offers a way to define variables and tools (such
233 as a download manager) for default use.  This file is used by qi at
234 runtime, e.g., to build, install, remove or upgrade packages.
236    Variables and their possible values must be declared as any other
237 variable in the shell.
239 The command line options related to the package directory and target
240 directory and some of the command line options used for the build mode,
241 have the power to override the values declared on 'qirc'.  See *note
242 Invoking qi::.
244 The order in which qi looks for this file is:
246   1. '${HOME}/.qirc' Effective user.
248   2. '${sysconfdir}/qirc' System-wide.
250    If you intend to run qi as effective user, the file
251 '${sysconfdir}/qirc' could be copied to '${HOME}/.qirc' setting the
252 paths for '${packagedir}' and '${targetdir}' according to the '$HOME'.
254 \x1f
255 File: qi.info,  Node: Packages,  Next: Recipes,  Prev: The qirc file,  Up: Top
257 4 Packages
258 **********
260 A package is a suite of programs usually distributed in binary form
261 which may also contain manual pages, documentation, or any other file
262 associated to a specific software.
264    The package format used by qi is a simplified POSIX pax archive
265 compressed with lzip(1).  The file extension for packages ends in
266 '.tlz'.
268 Both package installation and package de-installation are managed using
269 two important (internal) variables: '${packagedir}' and '${targetdir}',
270 these values can be changed in the configuration file or via options.
272    '${packagedir}' is a common directory tree where the package contents
273 will be decompressed (will reside).
275    '${targetdir}' is a target directory where the links will be made by
276 graft(1) taking '${packagedir}/package_name' into account.
278 Packages are installed in self-contained directory trees and symbolic
279 links from a common area are made to the package files.  This allows
280 multiple versions of the same package to coexist on the same system.
282 4.1 Package conflicts
283 =====================
285 All the links to install or remove a package are handled by graft(1).
286 Since multiple packages can be installed or removed at the same time,
287 certain conflicts may arise between the packages.
289 graft(2) defines a CONFLICT as one of the following conditions:
291    * If the package object is a directory and the target object exists
292      but is not a directory.
294    * If the package object is not a directory and the target object
295      exists and is not a symbolic link.
297    * If the package object is not a directory and the target object
298      exists and is a symbolic link to something other than the package
299      object.
301 The default behavior of qi for an incoming package is to ABORT if a
302 conflict arises.  When a package is going to be deleted, qi tells to
303 graft(1) to remove those parts that are not in conflict, leaving the
304 links to the belonging package.  This behavior can be forced if the -p
305 option is given.
307 4.2 Installing packages
308 =======================
310 To install a single package, simply type:
312      qi -i coreutils-8.30-i586+1.tlz
314 To install multiple packages at once, type:
316      qi -i gcc-8.3.0-i586+1.tlz rafaela-2.2-i586+1.tlz ...
318 Warn about the files that will be linked:
320      qi -w bash-5.0-i586+1.tlz
322    This is to verify the content of a package before installing it.
324 See the process of an installation (very verbose):
326      qi -i -v mariana-3.0-i586+1.tlz
328    A second -v gives more.
330 Installing package in a different location:
332      qi -r /media/floppy -i lzip-1.21-i586+1.tlz
334    Important: the -r option assumes '${targetdir}' and '${packagedir}'.
335 See the following example.
337      qi -r /home/selk -i lzip-1.21-i586+1.tlz
339    In this case the content of "lzip-1.21-i586+1.tlz" will be
340 decompressed into '/home/selk/pkgs/lzip-1.21-i586+1'.  Assuming that the
341 main binary for lzip is under
342 '/home/selk/pkgs/lzip-1.21-i586+1/usr/bin/' the target for "usr/bin"
343 will be created at '/home/selk'.  Considering that you have exported the
344 'PATH' as '${HOME}/usr/bin', now the system is able to see the recent
345 lzip.
347 Installing from a list of packages using standard input:
349      qi -i - < PACKAGELIST.txt
351    Or in combination with another tool:
352      sort -u PACKAGELIST.txt | qi -i -
354    The list of packages must contain full path names to be passed in the
355 installation, e.g.:
356      /var/cache/qi/packages/tcl-8.6.9-x86_64+1.tlz
357      /var/cache/qi/packages/tk-8.6.9.1-x86_64+1.tlz
358      /var/cache/qi/packages/vala-0.42.3-x86_64+1.tlz
360 4.3 Removing packages
361 =====================
363 To remove a package, simply type:
365      qi -d xz-5.2.4-i586+1.tlz
367 Delete mode will match the package name using '${packagedir}' as prefix.
368 For example, if the value of '${packagedir}' is set to /usr/pkg, this
369 will be equal to:
371      qi -d /usr/pkg/xz-5.2.4-i586+1
373 Detailed output (very verbose):
375      qi -d -v /usr/pkg/xz-5.2.4-i586+1
377    A second -v gives more.
379 By default the delete mode does not preserve a package directory after
380 removing its links from '${targetdir}', but this behavior can be changed
381 if the -k option is passed:
383      qi -d -k /usr/pkg/lzip-1.21-i586+1
385    This means that the links to the package can be reactivated, later:
387      cd /usr/pkg && graft -i lzip-1.21-i586+1
389 Removing package from a different location:
391      qi -r /home/cthulhu -d xz-5.2.4-i586+1
393 Removing a package using standard input:
395      echo "vala-0.42.3-x86_64+1" | qi -d -
397    This will match with the package directory.
399 4.4 Upgrading packages
400 ======================
402 The upgrade mode inherits the properties of the installation and removal
403 process.  To make sure that a package is updated, the package is
404 installed in a temporary directory taking '${packagedir}' into account.
405 Once the incoming package is pre-installed, qi can proceed to search and
406 delete packages that have the same name (considered as previous ones).
407 Finally, the package is re-installed at its final location and the
408 temporary directory is removed.
410 To upgrade a package, just type:
412      qi -u gcc-9.0.1-i586+1.tlz
414    This will proceed to upgrade "gcc-9.0.1-i586+1" removing any other
415 version of "gcc" (if any).
417 If you want to keep the package directories of versions found during the
418 upgrade process, just pass:
420      qi -u -k gcc-9.0.1-i586+1.tlz
422 To see the upgrade process (very verbose):
424      qi -u -v gcc-9.0.1-i586+1.tlz
426    A second -v gives more.
428 To force the upgrade of an existing package:
430      qi -u -f gcc-9.0.1-i586+1.tlz
432 4.4.1 Package blacklist
433 -----------------------
435 To implement general package facilities, either to install, remove or
436 maintain the hierarchy of packages in a clean manner, qi makes use of
437 the pruning operation via graft(1) by default:
439    There is a risk if those are crucial packages for the proper
440 functioning of the system, because it implies the deactivation of
441 symbolic from the target directory, _especially_ when transitioning an
442 incoming package into its final location during upgrade.
444 A blacklist of package names has been devised for the case where a user
445 decides to upgrade all packages in the system, or just the crucial ones,
446 such as the C library.
448    The blacklist is related to the upgrade mode only, consists in
449 installing a package instead of updating it or removing previous
450 versions of it; the content of the package will be updated over the
451 existing content at '${packagedir}', while the existing links from
452 '${targetdir}' will be preserved.  A pruning of links will be carried
453 out in order to re-link possible differences with the recent content,
454 this helps to avoid leaving dead links in the target directory.
456 The package names for the blacklist to be declared must be set from the
457 configuration file.
459    ---------- Footnotes ----------
461    (1) For more details about the lzip format, visit
462 <https://www.nongnu.org/lzip/>.
464    (2) The official guide for Graft can be found at
465 <http://peters.gormand.com.au/Home/tools/graft/graft.html>.
467 \x1f
468 File: qi.info,  Node: Recipes,  Next: Order files,  Prev: Packages,  Up: Top
470 5 Recipes
471 *********
473 A recipe is a file telling qi what to do.  Most often, the recipe tells
474 qi how to build a binary package from a source tarball.
476    A recipe has two parts: a list of variable definitions and a list of
477 sections.  By convention, the syntax of a section is:
479      section_name()
480      {
481          section lines
482      }
484    The section name is followed by parentheses, one newline and an
485 opening brace.  The line finishing the section contains just a closing
486 brace.  The section names or the function names currently recognized are
487 'build'.
489    The 'build' section is an augmented shell script.  This is the main
490 section (or *shell function*) which contains the instructions to build
491 and produce a package.
493 5.1 Variables
494 =============
496 A "variable" is a *shell variable* defined either in 'qirc' or in a
497 recipe to represent a string of text, called the variable's "value".
498 These values are substituted by explicit request in the definitions of
499 other variables or in calls to external commands.
501    Variables can represent lists of file names, options to pass to
502 compilers, programs to run, directories to look in for source files,
503 directories to write output to, or anything else you can imagine.
505    Definitions of variables in qi have four levels of precedence.
506 Options which define variables from the command-line override those
507 specified in the 'qirc' file, while variables defined in the recipe
508 override those specified in 'qirc', taking priority over those variables
509 set by command-line options.  Finally, the variables have default values
510 if they are not defined anywhere.
512    Options that set variables through the command-line can only
513 reference variables defined in 'qirc' and variables with default values.
515    Definitions of variables in 'qirc' can only reference variables
516 previously defined in 'qirc' and variables with default values.
518    Definitions of variables in the recipe can only reference variables
519 set by the command-line, variables previously defined in the recipe,
520 variables defined in 'qirc', and variables with default values.
522 5.2 Special variables
523 =====================
525 There are variables which can only be set using the command line options
526 or via 'qirc', there are other special variables which can be defined or
527 redefined in a recipe.  See the following definitions:
529    'outdir' is the directory where the packages produced are written.
530 This variable can be redefined per-recipe.  Default sets to
531 '/var/cache/qi/packages'.
533    'worktree' is the working tree where archives, patches, and recipes
534 are expected.  This variable can not be redefined in the recipe.
535 Default sets to '/usr/src/qi'.
537    'tardir' is defined in the recipe to the directory where the tarball
538 containing the source can be found.  The full name of the tarball is
539 composed as '${tardir}/$tarname'.  Its value is available in the recipe
540 as '${tardir}'; a value of .  for 'tardir' sets it to the value of CWD
541 (Current Working Directory), this is where the recipe lives.
543    'arch' is the architecture to compose the package name.  Its value is
544 available in the recipe as '${arch}'.  Default value is the output of
545 'uname -m'.
547    'jobs' is the number of parallel jobs to pass to the compiler.  Its
548 value is available in the recipe as '${jobs}'.  The default value is 1.
550    The two variables '${srcdir}' and '${destdir}' can be set in the
551 recipe, as any other variable, but if they are not, qi uses default
552 values for them when building a package.
554    'srcdir' contains the source code to be compiled, and defaults to
555 '${program}-${version}'.  'destdir' is the place where the built package
556 will be installed, and defaults to '${TMPDIR}/package-${program}'.
558    If 'pkgname' is left undefined, the special variable 'program' is
559 assigned by default.  If 'pkgversion' is left undefined, the special
560 variable 'version' is assigned by default.
562    'pkgname' and 'pkgversion' along with: 'version', 'arch', 'release',
563 and (optionally) 'pkgcategory' are used to produce the package name in
564 the form:
565 '${pkgname}-${pkgversion}-${arch}+${release}[@${pkgcategory}].tlz'
567    'pkgcategory' is an optional special variable that can be defined on
568 the recipe to categorize the package name.  If it is defined, then the
569 package output will be composed as
570 '${pkgname}-${pkgversion}-${arch}+${release}@${pkgcategory}.tlz'.
571 Automatically, the value of 'pkgcategory' will be prefixed using the '@'
572 character.
574    A special variable called 'replace' can be used to declare package
575 names that will be replaced at installation time.
577 A typical recipe contains the following variables:
579    * 'program': Software name.
581      It matches the source name.  It is also used to compose the name of
582      the package if '${pkgname}' is not specified.
584    * 'version': Software version.
586      It matches the source name.  It is also used to compose the version
587      of the package if '${pkgversion}' is not specified.
589    * 'arch': Software architecture.
591      It is used to compose the architecture of the package in which it
592      is build.
594    * 'release': Release number.
596      This is used to reflect the release number of the package.  It is
597      recommended to increase this number after any significant change in
598      the recipe or post-install script.
600    * 'pkgcategory': Package category.
602      Optional but recommended variable to categorize the package name
603      when it is created.
605 Obtaining sources over the network must be declared in the recipe using
606 the 'fetch' variable.
608    The variables 'netget' and 'rsync' can be defined in 'qirc' to
609 establish a network downloader in order to get the sources.  If they are
610 not defined, qi uses default values:
612    'netget' is the general network downloader tool, defaults sets to
613 'wget -c -w1 -t3 --no-check-certificate'.
615    'rsync' is the network tool for sources containing the prefix for the
616 RSYNC protocol, default sets to 'rsync -v -a -L -z -i --progress'.
618    The variable 'description' is used to print the package description
619 when a package is installed.
621    A description has two parts: a brief description, and a long
622 description.  By convention, the syntax of 'description' is:
624      description="
625      Brief description.
627      Long description.
628      "
630    The first line of the value represented is a brief description of the
631 software (called "blurb").  A blank line separates the _brief
632 description_ from the _long description_, which should contain a more
633 descriptive description of the software.
635 An example looks like:
637      description="
638      The GNU core utilities.
640      The GNU core utilities are the basic file, shell and text manipulation
641      utilities of the GNU operating system.  These are the core utilities
642      which are expected to exist on every operating system.
643      "
645    Please consider a length limit of 78 characters as maximum, because
646 the same one would be used on the meta file creation.  See *note The
647 meta file: Recipes. section.
649    The 'homepage' variable is used to declare the main site or home
650 page:
652      homepage=http://www.gnu.org/software/gcc
654    The variable 'license' is used for license information(1).  Some code
655 in the program can be covered by license A, license B, or license C. For
656 "separate licensing" or "heterogeneous licensing", we suggest using *|*
657 for a disjunction, *&* for a conjunction (if that ever happens in a
658 significant way), and comma for heterogeneous licensing.  Comma would
659 have lower precedence, plus added special terms.
661      license="LGPL, GPL | Artistic + added permission"
663 5.3 Writing recipes
664 ===================
666 Originally, Qi was designed for the version 3 of Dragora GNU/Linux; this
667 doesn't mean you can't use it in another distribution, just that if you
668 do, you'll have to try it out for yourself.  To help with this, here are
669 some references to well-written recipes:
671    * <http://git.savannah.nongnu.org/cgit/dragora.git/tree/recipes>
672    * <http://notabug.org/dragora/dragora/src/master/recipes>
674 5.4 Building packages
675 =====================
677 A recipe is any valid regular file.  Qi sets priorities for reading a
678 recipe, the order in which qi looks for a recipe is:
680   1. Current working directory.
682   2. If the specified path name does not contain "recipe" as the last
683      component.  Qi will complete it by adding "recipe" to the path
684      name.
686   3. If the recipe is not in the current working directory, it will be
687      searched under '${worktree}/recipes'.  The last component will be
688      completed adding "recipe" to the specified path name.
690 To build a single package, type:
692      qi -b x-apps/xterm
694 Multiple jobs can be passed to the compiler to speed up the build
695 process:
697      qi -b -j3 x-apps/xterm
699 Update or install the package produced (if it is not already installed)
700 when finish:
702      qi -b -j3 -u x-apps/xterm
704 Only process a recipe but do not create the binary package:
706      qi -b -n dict/aspell
708    The options -i or -u have no effect when -n is given.
710 This can be useful to inspect the build process of recipe:
712    qi -b -k -n dict/aspell 2>&1 | tee aspell-buildlog.txt
714    The -k option could preserve the source directory and the destination
715 directory for later inspection.  A log file of the build process will be
716 created redirecting both, standard error and standard output to tee(1).
718 5.5 Variables from the environment
719 ==================================
721 Qi has environment variables which can be used at build time:
723    The variable 'TMPDIR' sets the temporary directory for sources, which
724 is used for package extractions (see *note Examining packages::) and is
725 prepended to the value of '${srcdir}' and '${destdir}' in build mode.
726 By convention its default value is equal to '/usr/src/qi/build'.
728    The variables 'QICFLAGS', 'QICXXFLAGS', and 'QILDFLAGS' have no
729 effect by default.  The environment variables such as 'CFLAGS',
730 'CXXFLAGS', and 'LDFLAGS' are unset at compile time:
732 Recommended practice is to set variables in the command line of
733 'configure' or _make(1)_ instead of exporting to the environment.  As
734 follows:
736    <http://www.gnu.org/software/make/manual/html_node/Environment.html>
737      It is not wise for makefiles to depend for their functioning on
738      environment variables set up outside their control, since this
739      would cause different users to get different results from the same
740      makefile.  This is against the whole purpose of most makefiles.
742    Setting environment variables for configure is deprecated because
743 running configure in varying environments can be dangerous.
745    <http://gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Variables.html>
746      Variables not defined in a site shell script can be set in the
747      environment passed to configure.  However, some packages may run
748      configure again during the build, and the customized values of
749      these variables may be lost.  In order to avoid this problem, you
750      should set them in the configure command line, using 'VAR=value'.
751      For example:
753      './configure CC=/usr/local2/bin/gcc'
755    <http://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Setting-Output-Variables.html>
756      If for instance the user runs 'CC=bizarre-cc ./configure', then the
757      cache, config.h, and many other output files depend upon bizarre-cc
758      being the C compiler.  If for some reason the user runs ./configure
759      again, or if it is run via './config.status --recheck', (See
760      Automatic Remaking, and see config.status Invocation), then the
761      configuration can be inconsistent, composed of results depending
762      upon two different compilers.  [...]  Indeed, while configure can
763      notice the definition of CC in './configure CC=bizarre-cc', it is
764      impossible to notice it in 'CC=bizarre-cc ./configure', which,
765      unfortunately, is what most users do.  [...]  configure: error:
766      changes in the environment can compromise the build.
768 5.6 The meta file
769 =================
771 The "meta file" is a regular file created during the build mode, it
772 contains information about the package such as package name, package
773 version, architecture, release, fetch address, description, and other
774 minor data extracted from processed recipes.  The name of the file is
775 generated as '${full_pkgname}.tlz.txt', and its purpose is to reflect
776 essential information to the user without having to look inside the
777 package content.  The file format is also intended to be used by other
778 scripts or by common Unix tools.
780    The content of a meta file looks like:
782      #
783      # Pattern scanning and processing language.
784      #
785      # The awk utility interprets a special-purpose programming language
786      # that makes it possible to handle simple data-reformatting jobs
787      # with just a few lines of code.  It is a free version of 'awk'.
788      #
789      # GNU awk implements the AWK utility which is part of
790      # IEEE Std 1003.1 Shell and Utilities (XCU).
791      #
793      QICFLAGS="-g0 -Os"
794      QICXXFLAGS="-g0 -Os"
795      QILDFLAGS="-s"
796      pkgname=gawk
797      pkgversion=5.0.1
798      arch=x86_64
799      release=1
800      pkgcategory=@tools
801      full_pkgname=gawk-5.0.1-x86_64+1@tools
802      blurb="Pattern scanning and processing language."
803      homepage="http://www.gnu.org/software/gawk"
804      license="GPLv3+"
805      fetch="http://ftp.gnu.org/gnu/gawk/gawk-5.0.1.tar.lz"
806      replace=""
808    Package descriptions are extracted from the variable 'description'
809 where each line is interpreted literally and pre-formatted to fit in
810 (exactly) *80 columns*, plus the character '#' and a blank space is
811 prefixed to every line (shell comments).
813 In addition to the Special variables, there are implicit variables such
814 as 'blurb':
816    The 'blurb' variable is related to the special variable
817 'description'.  Its value is made from the first (substantial) line of
818 'description', mentioned as the "brief description".
820    ---------- Footnotes ----------
822    (1) The proposal for 'license' was made by Richard M. Stallman at
823 <http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html>.
825 \x1f
826 File: qi.info,  Node: Order files,  Next: Creating packages,  Prev: Recipes,  Up: Top
828 6 Order files
829 *************
831 The order mode has the purpose of resolving the build order through
832 .order files.  An order file contains a list of recipe names, by default
833 does not perform any action other than to print a resolved list in
834 descending order.  For example, if *a* depends on *b* and *c*, and *c*
835 depends on *b* as well, the file might look like:
837      a: c b
838      b:
839      c: b
841    Each letter represents a recipe name, complete dependencies for the
842 first recipe name are listed in descending order, which is printed from
843 right to left, and removed from left to right:
845    OUTPUT
847      b
848      c
849      a
851    Blank lines, colons and parentheses are simply ignored.  Comment
852 lines beginning with '#' are allowed.
854 An order file could be used to build a series of packages, for example,
855 if the content is:
857      # Image handling libraries
859      libs/libjpeg-turbo: devel/nasm
860      x-libs/jasper: libs/libjpeg-turbo
861      libs/tiff: libs/libjpeg-turbo
863    To proceed with each recipe, we can type:
865      qi -o imglibs.order | qi -b -i -
867    The output of 'qi -o imglibs.order' tells to qi in which order it
868 should build the recipes:
870      devel/nasm
871      libs/libjpeg-turbo
872      x-libs/jasper
873      libs/tiff
875 \x1f
876 File: qi.info,  Node: Creating packages,  Next: Examining packages,  Prev: Order files,  Up: Top
878 7 Creating packages
879 *******************
881 The "creation mode" is an internal function of qi to make new Qi
882 compatible compatible packages, the creation mode is selected by the -c
883 option.  A package is produced using the contents of the Current
884 Directory, and the package file is written out.
886      Usage: qi -c [OUTPUT/PACKAGENAME.TLZ]...
888    The argument for the file name to be written must contain a fully
889 qualified named directory as the output directory where the package
890 produced will be written.  The file name should be composed using the
891 full name: name-version-architecture+release.tlz
893    EXAMPLE
895      cd /usr/pkg
896      cd claws-mail-3.17.1-x86_64+1
897      qi -c /var/cache/qi/packages/claws-mail-3.17.1-x86_64+1.tlz
899    In this case, the package "claws-mail-3.17.1-x86_64+1.tlz" will be
900 written into '/var/cache/qi/packages/'.
902 All packages produced are complemented by a checksum file (.sha256).
904 \x1f
905 File: qi.info,  Node: Examining packages,  Next: Exit status,  Prev: Creating packages,  Up: Top
907 8 Examining packages
908 ********************
910 The "extraction mode" serves to examine binary packages for debugging
911 purposes.  The extraction mode is selected by the -x option.  It
912 decompresses a package into a single directory, verifying its integrity
913 and preserving its properties.
915      Usage: qi -x [PACKAGENAME.TLZ]...
917    EXAMPLE
919      qi -x mksh-R56c-x86_64+1.tlz
921    This action will put the content of "mksh-R56c-x86_64+1.tlz" into a
922 single directory, this will be a private directory for the user who
924    requested the action, creation mode will be equal to *u=rwx,g=,o=
925 (0700)*.  The package content will reside on this location, default mask
926 to deploy the content will be equal to *u=rwx,g=rwx,o=rwx (0000)*.
928 The creation of the custom directory is influenced by the value of the
929 'TMPDIR' variable.
931 \x1f
932 File: qi.info,  Node: Exit status,  Next: Index,  Prev: Examining packages,  Up: Top
934 9 Exit status
935 *************
937 All the exit codes are described in this chapter.
940      Successful completion (no errors).
943      Minor common errors:
945         * Help usage on illegal options or required arguments.
947         * Program needed by qi (prerequisite) is not available.
950      Command execution error:
952      This code is used to return the evaluation of external commands and
953      shell arguments in case of error.
956      Integrity check error for compressed files.
958      Compressed files means:
960         * Tarball files from tar(1).  Supported extensions: .tar,
961           .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz, .tar.xz, .txz
963         * Tarball files from tarlz(1).  Supported extensions: .tar.lz,
964           .tlz
966         * Zip files from unzip(1).  Supported extensions: .zip, .ZIP
968         * Gzip files from gzip(1).  Supported extensions: .gz, .Z
970         * Bzip2 files from bzip2(1).  Supported extension: .bz2
972         * Lzip files from lzip(1).  Supported extension: .lz
974         * Xz files from xz(1).  Supported extension: .xz
977      File empty, not regular, or expected.
979      Commonly, it is expected:
981         * An argument for the mode of operation.
983         * A readable file or directory.
985         * A binary package (.tlz).
987         * A valid recipe.
989         * An order file (.order).
991         * A protocol supported by the network downloader tool.
993         * A checksum file (.sha256).
996      Empty or not defined variable:
998      This code is used to report empty or undefined variables; usually,
999      variables coming from a recipe or assigned arrays that are tested.
1002      Package already installed:
1004      The package directory for an incoming .tlz package already exists.
1006 '10'
1007      Network manager error:
1009      This code is used if the network downloader tool fails for some
1010      reason.
1012 \x1f
1013 File: qi.info,  Node: Index,  Prev: Exit status,  Up: Top
1015 Index
1016 *****
1018 \0\b[index\0\b]
1019 * Menu:
1021 * configuration file:                    The qirc file.       (line   6)
1022 * environment variables:                 Recipes.             (line 254)
1023 * exit codes:                            Exit status.         (line   6)
1024 * handling build order:                  Order files.         (line   6)
1025 * introduction:                          Introduction.        (line   6)
1026 * invocation:                            Invoking qi.         (line   6)
1027 * managing packages:                     Packages.            (line   6)
1028 * package blacklist:                     Packages.            (line 181)
1029 * package build:                         Recipes.             (line 210)
1030 * package conflicts:                     Packages.            (line  31)
1031 * package creation:                      Creating packages.   (line   6)
1032 * package de-installation:               Packages.            (line 109)
1033 * package examination:                   Examining packages.  (line   6)
1034 * package installation:                  Packages.            (line  56)
1035 * package upgrade:                       Packages.            (line 148)
1036 * recipes:                               Recipes.             (line   6)
1037 * special variables:                     Recipes.             (line  58)
1038 * the meta file:                         Recipes.             (line 304)
1039 * variables:                             Recipes.             (line  29)
1040 * writing recipes:                       Recipes.             (line 199)
1043 \x1f
1044 Tag Table:
1045 Node: Top\x7f806
1046 Node: Introduction\x7f1590
1047 Node: Invoking qi\x7f2759
1048 Node: The qirc file\x7f6182
1049 Node: Packages\x7f7143
1050 Ref: Packages-Footnote-1\x7f13960
1051 Ref: Packages-Footnote-2\x7f14046
1052 Node: Recipes\x7f14159
1053 Ref: Recipes-Footnote-1\x7f28078
1054 Node: Order files\x7f28223
1055 Node: Creating packages\x7f29525
1056 Node: Examining packages\x7f30532
1057 Node: Exit status\x7f31442
1058 Node: Index\x7f33377
1059 \x1f
1060 End Tag Table
1062 \x1f
1063 Local Variables:
1064 coding: iso-8859-1
1065 End: