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: , 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.

    -Next: , Previous: , Up: Top   [Contents][Index]

    +Next: , Previous: , Up: Top   [Contents][Index]

    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"). +

    + +
    +
    +

    +Next: , Previous: , Up: Top   [Contents][Index]

    +
    +

    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
+

    -Next: , Previous: , Up: Top   [Contents][Index]

    +Next: , Previous: , Up: Top   [Contents][Index]

    Appendix A GNU Free Documentation License

    @@ -1457,6 +1519,8 @@ Previous: , Up: E   +H +   I   M @@ -1481,6 +1545,9 @@ Previous: , Up: E environment variables: Recipes
    +H +handling build order: Order files +
    I introduction: Introduction invocation: Invoking qi @@ -1513,6 +1580,8 @@ Previous: , 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