From 45f185916e7b914c88555a1af3d868cff50319f9 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Mat=C3=ADas=20Fonzo?=
Date: Wed, 27 Mar 2019 22:39:46 -0300
Subject: [PATCH] qi: doc: added 'Order files' section to the manual
---
qi/doc/qi.html | 97 +++++++++++++++++++++++++++++++++++++++++++++++++---------
qi/doc/qi.info | 97 +++++++++++++++++++++++++++++++++++++++++++++-------------
qi/doc/qi.texi | 77 ++++++++++++++++++++++++++++++++++++++++------
3 files changed, 225 insertions(+), 46 deletions(-)
diff --git a/qi/doc/qi.html b/qi/doc/qi.html
index a2914535..8e0d98f1 100644
--- a/qi/doc/qi.html
+++ b/qi/doc/qi.html
@@ -82,6 +82,7 @@ ul.no-bullet {list-style: none}
5.4 Variables from the environment
5.5 The meta file
+ 6 Order files
Appendix A GNU Free Documentation License
Index
@@ -107,9 +108,11 @@ Next: Introduction, Up:
• Recipes | | Building packages
|
-• License | | GNU Free Documentation License
+ |
• Order files | | Handling build order
|
-• Index | |
+ |
• License | | GNU Free Documentation License
+ |
+• Index | |
|
@@ -513,7 +516,7 @@ installation, e.g:
Delete mode will match the package name using ‘${packagedir}’ as
prefix. For example, if the value of ‘${packagedir}’ is set to
/usr/local/pkgs, this will be equal to:
-
+
qi -d /usr/local/pkgs/xz-5.2.4-i586+1
@@ -535,7 +538,7 @@ changed if the -k option is passed:
This means that the links to the package can be reactivated, later:
-
+
cd /usr/local/pkgs && graft -i lzip-1.21-i586+1
@@ -625,7 +628,7 @@ newer than the package directory in order to perform an update.
5 Recipes
@@ -803,9 +806,9 @@ which are expected to exist on every operating system.
Please consider a length limit of 78 characters as maximum, because the same
one would be used on the meta file creation. See
-The meta file.
+The meta file section.
-The ‘homepage’ variable is used to declare the main site or home:
+
The ‘homepage’ variable is used to declare the main site or home page:
homepage=http://www.gnu.org/software/gcc
@@ -874,7 +877,7 @@ created redirecting both, standard error and standard output to tee(1).
The variable TMPDIR
sets the temporary directory for sources, by
default, this is used to prepend ‘${srcdir}’ and
-‘${destdir}’. By convention, its value is ‘/tmp’.
+‘${destdir}’. By convention its value is ‘/tmp’.
The variables QICFLAGS
, QICXXFLAGS
, and QILDFLAGS
have
no effect by default. The environment variables such as CFLAGS
,
@@ -955,25 +958,84 @@ fetch="ftp://ftp.gnu.org/gnu/bash/bash-5.0.tar.gz"
replace=""
-The package description is extracted from the declared variable
-‘description’, each line will be interpreted literally and
-pre-formatted to fit in (exactly) 80 columns, plus the character
-‘# ’ will be prefixed to each line in the description.
+
A package description is extracted from the variable ‘description’,
+each line will be interpreted literally and pre-formatted to fit in
+(exactly) 80 columns, plus the character ‘# ’ will be prefixed to
+each line in the description.
In addition to the special variables, there are implicit variables such as
‘blurb’:
The ‘blurb’ variable is related to the special variable
‘description’. Its value is composed using the first (substantial)
-line of ‘description’ (know as the "brief description").
+line of ‘description’ (mentioned as the "brief description").
+
+
+
+
+6 Order files
+
+
+The order mode has the purpose to resolve the build order through
+.order files. A .order file contains a list of recipe names, by default
+does not perform any action other than to print a resolved list in descending
+order. For example, if a depends on b and c,
+and c depends on b as well, the file might look like:
+
+
+
+Each letter represents a recipe name, complete dependencies for
+the first recipe name are listed in descending order, which is
+printed from right to left, and removed from left to right:
+
+OUTPUT
+
+
+
+Declaration of blank lines, colons, parentheses, and end of line are
+ignored. Comments are allowed for lines that begin with ‘#’.
+
+An order file could be used to build a serie of packages, for example, if
+the content is:
+
+
# Image handling libraries
+libs/libjpeg-turbo: devel/nasm
+x-libs/jasper: libs/libjpeg-turbo
+libs/tiff: libs/libjpeg-turbo
+
+To proceed with each recipe, we can type:
+
+
+
qi -o imglibs.order | qi -b -i -
+
+The output of ‘qi -o imglibs.order’ will tell to qi in which order it
+should build the recipes/packages:
+
+
+
devel/nasm
+libs/libjpeg-turbo
+x-libs/jasper
+libs/tiff
+
Appendix A GNU Free Documentation License
@@ -1457,6 +1519,8 @@ Previous: License, Up: E
+H
+
I
M
@@ -1481,6 +1545,9 @@ Previous: License, Up: E | |
| environment variables: | | Recipes |
|
+H | | |
+ | handling build order: | | Order files |
+
|
I | | |
| introduction: | | Introduction |
| invocation: | | Invoking qi |
@@ -1513,6 +1580,8 @@ Previous: License, Up: E
+H
+
I
M
diff --git a/qi/doc/qi.info b/qi/doc/qi.info
index ed315645..d1579b50 100644
--- a/qi/doc/qi.info
+++ b/qi/doc/qi.info
@@ -31,6 +31,7 @@ This user guide is for Qi (version 1.0-rc59, 27 March 2019).
* The qirc file:: Configuration file
* Packages:: Managing packages
* Recipes:: Building packages
+* Order files:: Handling build order
* License:: GNU Free Documentation License
* Index::
@@ -458,7 +459,7 @@ update.
.
-File: qi.info, Node: Recipes, Next: License, Prev: Packages, Up: Top
+File: qi.info, Node: Recipes, Next: Order files, Prev: Packages, Up: Top
5 Recipes
*********
@@ -623,9 +624,10 @@ An example looks like:
Please consider a length limit of 78 characters as maximum, because
the same one would be used on the meta file creation. See *note The
-meta file: Recipes.
+meta file: Recipes. section.
- The 'homepage' variable is used to declare the main site or home:
+ The 'homepage' variable is used to declare the main site or home
+page:
homepage=http://www.gnu.org/software/gcc
@@ -683,7 +685,7 @@ Qi has environment variables which can be used at build time:
The variable 'TMPDIR' sets the temporary directory for sources, by
default, this is used to prepend '${srcdir}' and '${destdir}'. By
-convention, its value is '/tmp'.
+convention its value is '/tmp'.
The variables 'QICFLAGS', 'QICXXFLAGS', and 'QILDFLAGS' have no
effect by default. The environment variables such as 'CFLAGS',
@@ -758,17 +760,17 @@ content.
fetch="ftp://ftp.gnu.org/gnu/bash/bash-5.0.tar.gz"
replace=""
- The package description is extracted from the declared variable
-'description', each line will be interpreted literally and pre-formatted
-to fit in (exactly) 80 columns, plus the character '# ' will be prefixed
-to each line in the description.
+ A package description is extracted from the variable 'description',
+each line will be interpreted literally and pre-formatted to fit in
+(exactly) 80 columns, plus the character '# ' will be prefixed to each
+line in the description.
In addition to the special variables, there are implicit variables
such as 'blurb':
The 'blurb' variable is related to the special variable
'description'. Its value is composed using the first (substantial) line
-of 'description' (know as the "brief description").
+of 'description' (mentioned as the "brief description").
---------- Footnotes ----------
@@ -776,7 +778,56 @@ of 'description' (know as the "brief description").
.
-File: qi.info, Node: License, Next: Index, Prev: Recipes, Up: Top
+File: qi.info, Node: Order files, Next: License, Prev: Recipes, Up: Top
+
+6 Order files
+*************
+
+The order mode has the purpose to resolve the build order through .order
+files. A .order file contains a list of recipe names, by default does
+not perform any action other than to print a resolved list in descending
+order. For example, if *a* depends on *b* and *c*, and *c* depends on
+*b* as well, the file might look like:
+
+ a: c b
+ b:
+ c: b
+
+ Each letter represents a recipe name, complete dependencies for the
+first recipe name are listed in descending order, which is printed from
+right to left, and removed from left to right:
+
+ OUTPUT
+
+ b
+ c
+ a
+
+ Declaration of blank lines, colons, parentheses, and end of line are
+ignored. Comments are allowed for lines that begin with '#'.
+
+An order file could be used to build a serie of packages, for example,
+if the content is:
+
+ # Image handling libraries
+ libs/libjpeg-turbo: devel/nasm
+ x-libs/jasper: libs/libjpeg-turbo
+ libs/tiff: libs/libjpeg-turbo
+
+ To proceed with each recipe, we can type:
+
+ qi -o imglibs.order | qi -b -i -
+
+ The output of 'qi -o imglibs.order' will tell to qi in which order it
+should build the recipes/packages:
+
+ devel/nasm
+ libs/libjpeg-turbo
+ x-libs/jasper
+ libs/tiff
+
+
+File: qi.info, Node: License, Next: Index, Prev: Order files, Up: Top
Appendix A GNU Free Documentation License
*****************************************
@@ -1267,34 +1318,36 @@ Index
* Menu:
* configuration file: The qirc file. (line 6)
-* environment variables: Recipes. (line 222)
+* environment variables: Recipes. (line 223)
+* handling build order: Order files. (line 6)
* introduction: Introduction. (line 6)
* invocation: Invoking qi. (line 6)
* managing packages: Packages. (line 6)
* package blacklist: Packages. (line 172)
-* package build: Recipes. (line 184)
+* package build: Recipes. (line 185)
* package conflicts: Packages. (line 30)
* package de-installation: Packages. (line 104)
* package installation: Packages. (line 55)
* package upgrade: Packages. (line 143)
* recipes: Recipes. (line 6)
* special variables: Recipes. (line 58)
-* the meta file: Recipes. (line 268)
+* the meta file: Recipes. (line 269)
* variables: Recipes. (line 29)
Tag Table:
Node: Top807
-Node: Introduction1460
-Node: Invoking qi2600
-Node: The qirc file5962
-Node: Packages7040
-Ref: Packages-Footnote-114013
-Node: Recipes14126
-Ref: Recipes-Footnote-126072
-Node: License26217
-Node: Index51329
+Node: Introduction1511
+Node: Invoking qi2651
+Node: The qirc file6013
+Node: Packages7091
+Ref: Packages-Footnote-114064
+Node: Recipes14177
+Ref: Recipes-Footnote-126134
+Node: Order files26279
+Node: License27608
+Node: Index52724
End Tag Table
diff --git a/qi/doc/qi.texi b/qi/doc/qi.texi
index 17f5fa0c..e2d320d5 100644
--- a/qi/doc/qi.texi
+++ b/qi/doc/qi.texi
@@ -59,6 +59,7 @@ This user guide is for Qi (version @value{VERSION},
* The qirc file:: Configuration file
* Packages:: Managing packages
* Recipes:: Building packages
+* Order files:: Handling build order
* License:: GNU Free Documentation License
* Index::
@end menu
@@ -445,7 +446,7 @@ qi -d xz-5.2.4-i586+1.tlz
Delete mode will match the package name using @samp{$@{packagedir@}} as
prefix. For example, if the value of @samp{$@{packagedir@}} is set to
/usr/local/pkgs, this will be equal to:
-@sp 1
+
@example
qi -d /usr/local/pkgs/xz-5.2.4-i586+1
@end example
@@ -469,7 +470,7 @@ qi -d -k /usr/local/pkgs/lzip-1.21-i586+1
@end example
This means that the links to the package can be reactivated, later:
-@sp 1
+
@example
cd /usr/local/pkgs && graft -i lzip-1.21-i586+1
@end example
@@ -745,9 +746,9 @@ which are expected to exist on every operating system.
Please consider a length limit of 78 characters as maximum, because the same
one would be used on the meta file creation. See
-@ref{Recipes, The meta file}.
+@ref{Recipes, The meta file} section.
-The @samp{homepage} variable is used to declare the main site or home:
+The @samp{homepage} variable is used to declare the main site or home page:
@example
homepage=http://www.gnu.org/software/gcc
@@ -823,7 +824,7 @@ Qi has environment variables which can be used at build time:
The variable @env{TMPDIR} sets the temporary directory for sources, by
default, this is used to prepend @samp{$@{srcdir@}} and
-@samp{$@{destdir@}}. By convention, its value is @samp{/tmp}.
+@samp{$@{destdir@}}. By convention its value is @samp{/tmp}.
The variables @env{QICFLAGS}, @env{QICXXFLAGS}, and @env{QILDFLAGS} have
no effect by default. The environment variables such as @env{CFLAGS},
@@ -905,20 +906,76 @@ fetch="ftp://ftp.gnu.org/gnu/bash/bash-5.0.tar.gz"
replace=""
@end example
-The package description is extracted from the declared variable
-@samp{description}, each line will be interpreted literally and
-pre-formatted to fit in (exactly) 80 columns, plus the character
-@samp{# } will be prefixed to each line in the description.
+A package description is extracted from the variable @samp{description},
+each line will be interpreted literally and pre-formatted to fit in
+(exactly) 80 columns, plus the character @samp{# } will be prefixed to
+each line in the description.
In addition to the special variables, there are implicit variables such as
@samp{blurb}:
The @samp{blurb} variable is related to the special variable
@samp{description}. Its value is composed using the first (substantial)
-line of @samp{description} (know as the "brief description").
+line of @samp{description} (mentioned as the "brief description").
+
+
+@node Order files
+@chapter Order files
+@cindex handling build order
+
+The order mode has the purpose to resolve the build order through
+.order files. A .order file contains a list of recipe names, by default
+does not perform any action other than to print a resolved list in descending
+order. For example, if @strong{a} depends on @strong{b} and @strong{c},
+and @strong{c} depends on @strong{b} as well, the file might look like:
+
+@example
+a: c b
+b:
+c: b
+@end example
+
+Each letter represents a recipe name, complete dependencies for
+the first recipe name are listed in descending order, which is
+printed from right to left, and removed from left to right:
+
+@sc{Output}
+
+@example
+b
+c
+a
+@end example
+Declaration of blank lines, colons, parentheses, and end of line are
+ignored. Comments are allowed for lines that begin with @samp{#}.
+
+@noindent
+An order file could be used to build a serie of packages, for example, if
+the content is:
+
+@example
+# Image handling libraries
+libs/libjpeg-turbo: devel/nasm
+x-libs/jasper: libs/libjpeg-turbo
+libs/tiff: libs/libjpeg-turbo
+@end example
+To proceed with each recipe, we can type:
+@example
+qi -o imglibs.order | qi -b -i -
+@end example
+
+The output of @samp{qi -o imglibs.order} will tell to qi in which order it
+should build the recipes/packages:
+
+@example
+devel/nasm
+libs/libjpeg-turbo
+x-libs/jasper
+libs/tiff
+@end example
@node License
@appendix GNU Free Documentation License
--
2.11.4.GIT