-
Notifications
You must be signed in to change notification settings - Fork 13
/
autobuild.txt
189 lines (141 loc) · 16.2 KB
/
autobuild.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
Autorun.pl:
===========
Option
-c Parse and Check each command but don't execute any. Causes autorun.pl to perform stages 1, 2 and 3 but not 4 (see below).
-cvs_tag <tag>
This sets the autobuild variable "cvs_tag" to the value given with the attribute. Checkout operations can use this variable instead of "HEAD" which is the default value if this attribute if not given.
-d Any use of Deprecated Prism Tech features issues a warning message and an equivalent format using the new features of "BetterParser".
-k Keep going if any errors are encountered. Similar to make -k, this attribute causes command errors during execution to be ignored so that all commands in the controlling xml file will be attempted if possible. Commands that fail the requirements checking step will be ignored during the execution phase.
-p Parse only, don't check or execute commands. Causes autorun.pl to perform stage 1 only. Stage 2, 3 and 4 are not undertaken (see below).
-v0 Verbose Mode (level 0) i.e. OFF. Does not output any trace messages during execution. This does not stop warning and error messages being displayed.
-v1 Verbose Mode (level 1) Displays a small amount of detail as to what operation autobuild.pl is currently performing.
-v2 Verbose Mode (level 2) This displays more information detail.
-v Verbose mode (increase) Used without a number to increment the verbose level each time it is seen.
-xml Dumps to a new file (with _dump appended to the filename) the combined variables, environment, and command settings that the parsed input file created. This removes the need for any of the included files that the original input file requires.
---------------------
Autorun.pl performs its operations during 4 distinct stages on each input file (one file at a time from the list provided) being processed:
Stage 1 "Parsing"
=================
This uses betterparser.pm. During the parsing stage, all variable definitions
in the input file are acted upon immediately and stored in the autobuild
variables list. This DOES NOT happen with Environment variables, where only a
list of actions to perform later in stage 2 are stored. Any use of an
environment variables in setting the value of an autobuild variable using the
various variable tags will see the ORIGINAL environment value as when the
program started until stage 2 has completed. If you want an autobuild variable
to reflect the current environment variable value after stage 2 processing,
you can place the ${environment_name} or %environment_name% strings anywhere
inside the value of the autobuild variable, and these will be substituted
with the current value of the environment variable at the time the
autobuild variable is used (i.e. not when the autobuild variable is created).
Command are also parsed and stored for later use.
Stage 2 "Environment Variables"
===============================
Assuming no parsing errors, the change actions stored in stage 1 are acted upon.
Now the environment variables will be set to the values actually desired.
NOTE that Environment Variables are formed into collections called
"Environment_Groups". (Any number of different groups can be created and the
environment changes can be applied globally or restricted to certain groups only
, see the description of "BetterParser" below.)
Stage 3 "Command Requirements Checking"
=======================================
Before every command is checked, the default "root" / directory will be
changed (if required for that command only) and the correct environment group
will be selected before the Check_Requirements function of the command is
called. If the command tag has an associated IF attribute, it will be ignored
during the check requirements stage, command tag IF attributes are only valid
during stage 4.
Stage 4 "Command Execution"
===========================
Each command that has passed its Requirement checks will be executed in turn.
Again for each command the correct environment group will be selected (and a
different root / current directory) if required for that individual command.
--------------------
BetterParser:
=============
This is an improvement on the "SimpleParser" and it allows more freedom. It IGNORES all text outside of <tags> but you should note however that "for correctness" and to avoid unintentional problems any windows directory paths given inside tags should be fully escaped, as the \ character inside double quotes acts as an escape character. (There are slightly more escape sequences from previous parsers, it understands \" \' \n \\ \t \b \r \x## \0x## and \0###.)
<!-- comments --> and <? Comment ?> Tags are also allowed anywhere to denote comments. The contents of these tags are ignored and can not be nested.
Only the <relative_env /> and <relative_var /> tags are "rigidly" defined (and are only supported for backward compatibility as they can now be performed better with <variable /> and <environment /> tags). All other tags can have any order of their attributes.
<relative_var name="variable" base_var="variable" suffix_var="variable" join="text" />
This command splices together two other named variables and stores the resultant string in variable being created. The join attribute is optional (defaulting to a null string) and if given its text will be spliced between the two other variable's text to form the result). All attributes must be in the order given above.
<relative_env name="environment" base_var="variable" suffix_var="variable" join="text" type="" />
All attributes must be in the order given above although both join and type are optional. This command splices together two other named autobuild variables and stores the resultant string in environment variable being created. The join attribute is optional (defaulting to a null string) and if given its text will be spliced between the two other variable's text to form the result). If the type is given it works just as for the environment tag above.
The <include name="filename" if="test" /> tag can now have an optional if attribute that will be evaluated immediately during the parse stage.
This can sit anywhere in the input file and causes the named file to be opened and parsed at the current point. This file must have it's own <autobuild> and optional <configuration> sections to be processed and any variables, environment and commands will be added to the current file's already processed tags.
<autobuild> .. <autobuild/>
This surrounds all of the command tags and any configuration section(s) that the parser understands.
<configuration> .. <configuration/>
This section (if it exists) must sit within the <autobuild> section and contains the variable and environment definition tags.
Both of the start section tags <autobuild if=""> and <configuration if=""> can have the optional if attribute. The text of this is substituted with autobuild variable and evaluated by the perl eval command to determine if the whole section will be acted on (the sections will always be parsed and errors reported even if not being acted on, <include /> tags will not work inside a dead section). For example multiple <autobuild> sections can be given, each controlled by the new built in autobuild variables isWin, isUnix etc.
The <configuration>..</configuration> section records the definition of autobuild and environment variables.
The "original" forms of the variable tag are:
<variable name="variable" value="text" />
<variable name="variable" default="text" />
<variable name="variable" environment="env" />
<variable name="variable" relative_value="text" eval="text" />
Each of the above forms of the variable tag set the named variable to the text specified.
* Using "value" means the autobuild variable will always be set or changed to
the text given.
* Using "default" means the autobuild variable will only set the variable if it
has not already been defined a value.
* Using "environment" means setting the autobuild variable to the value of the
"original" environment variable's value. Since this is looked up at the point
the autobuild variable is being parsed, it will ALWAYS be the original value,
if any. (If you want the current value AFTER any environment variable changes
have been actions, use the ${environment_name} or %environment_name% strings
within a normal value="" form.)
* Using "relative_value" means that the text will be scanned for other variable
names (enclosed in <>) and the current value of such variables will be
substituted into the text before the variable is stored. The eval attribute is
optional (defaulting to false) but if given as eval="true" will cause the
relative_value text to be evaluated by perl's eval statement after substitution
and this result will be stored in the named variable. This form of the variable
command allows complex expressions to be formed and evaluated for later use
with command IF attributes, but note that the evaluation is performed BEFORE any
commands are executed and is static after stage 1.
The original form of the environment tag is:
<environment name="env_name" value="text" type="type") />
The attribute type is optional. This simply RECORDS the change of value to the
named environment variable (that will be acted upon in stage 2). The type
attribute is optional (defaulting to "replace").
The <variable /> and <environment /> tags have been enhanced with betterparser, all of the attributes are optional as long as the variable has been named. The default value defaults to a null string, and multiple values can be specified and they will be spliced together to form the actual value. Both tags understand the following attributes:
If="text" defaults to true, but otherwise the text given will have autobuild variables substituted into the string and then perl eval to determine IF the variable or environment variable instruction will be acted upon. This is tested immediately during the parse stage.
name="name" This simply names the variable being defined.
value="text" This gives a textual value to the variable being defined. Multiple values will be spliced together in the order specified.
default="text" If default is given (with or without ="text" anywhere in the tag, it makes the type of the variable default, and the value will then only be set if it has not already been defined.)
variable="variable" The current autobuild variable's text value will be substituted into this variable at the point this attribute is seen.
environment="env" The current original environment variables text value will be substituted into this variable at the point this attribute is seen.
relative_value="text" The text will first have any autobuild variable denoted by <name> substituted into the text and then this will be used to form part of the current value being defined.
Substitute_variables="text" If the text is not given or is given as "true" will force the whole resultant value to have any <var> strings substituted for the current value of the autobuild variable and the resultant string stored. If the text is given, only the given text will have it's <vars> substituted (not the whole value of the resultant variable).
eval="text" If "text" is not given or is given as "true", means that the whole resultant value once complete will be passed to the perl eval command and the result will be stored.
type="text" If the type is not given it is assumed to be "replace" unless the
"default" attribute is seen. It can take any of "replace", "set", "unset",
"delete", "remove", "ifundefined", "default", "prefix", "suffix", "postfix".
The various types can also appear as attributes (which mean the same thing as
type="text") with any value given being used to created the value of the
resultant variable. Autobuild variables can have a type as well as environment
variables, however prefix, suffix and postfix variable types do not have any
joining characters between the original value and the newly defined value;
environment variables do still get treated to the platform's path separating
character.
replace/set which simply resets or creates the environment variable with the value given,
prefix which appends the original value of the environment variable to the end of the string, joined with a "path" separating character as defined by the platform autobuild.pl is running on,
suffix/postfix which appends the value given to the end of the current value of the environment variable again separated by a "path" character or
ifundefined/default which will only create a new environment variable with the given value if it does not already exist.
unset/delete/remove which will remove the variable.
groups="group1,group2,group3" This is only valid inside <environment /> tags, if not specified, ALL groups will have the environment modifications applied. If given, only each of the groups named in the groups=list will have the environment modifications applied. (This allows different paths or other environment variables to be setup only for certain commands). Simply adding a group name to the <environment /> tag creates that group if it doesn't already exist, each group gets a copy of the original environment before any environment variables have been modified.
Join="" This changes the default joining string of a single space to the text specified, with two "special" values of "path" and "directory" that represent the platform's path and directory separating characters. Join takes effect in the position it is currently and can be specified / changed multiple times during the tags parsing allowing multiple values to be joined together in different ways.
For example:
<variable name="jim" value="hello" value="this is" join=dir value="simon" variable="fred" />
Would result in the variable simon being set to the string "hello this is/simon/fredvalue" with fredvalue being the actual value of the "fred" variable. Note you can use join="" to join multiple values without any joining characters.
The <command /> tag also has been enhanced in a similar way to the <variable /> and <environment /> tags, so it will allow it's attributes in any order.
This tag can only exist with an <autobuild> section outside of a <configuration> section. It details one of the registered commands, via the name attribute, that will be executed in stage 4. All of the other attributes are optional. The options if given will be passed to the command when it is executed as the arguments to that command; its format is dependant upon the individual command itself. The directory attribute specifies which directory the "root" autobuild variable will be changed to for this command (if this attribute is missing, the default "root" directory will be selected). The optional if attribute details a test that must be "true" for the command to actually execute at stage 4. The string provided will have autobuild variables substituted for any <variable> string given and the whole expression will be passed to the perl eval command for evaluation to determine the "true or false" outcome. (If the IF attribute is missing, the command will always be executed, unless it failed it's requirement checks at stage 3.) It allows the following attributes:
Name="name" Must be a registered command.
Options="text" the optional, defaulting to a null string, parameters given to the command during execution. May be given more than once, all option strings will be spliced together using the join string specified.
unche
Join="text" the optional, defaulting to a single space, used to modify (possibly many times) the joining characters between multiple option strings. Join understands the two special "dir" and "path" names which indicate platform specified directory and path separating characters.
Root="dir" or directory="dir" optionally specify that this command should have a different root to that defined globally.
Substitute_variables or SubsVars, optionally used to over-ride the default for the individual command, indicating that the resultant options string should have any <Var> variables substituted prior to use.
NoSubstitute_variables or NoSubsVars, optionally used to over-ride the default for the individual command, indicating that the resultant options string should NOT have any <Var> variables substituted.
group="group" optionally states that the command should be using the named environment group, it defaults to "default" which is always created.
If="test" when given it will only be processed immediately prior to the command's execution, and controls if this is actually performed. It will have any <var> strings substituted and will be passed to the perl eval function. Obviously it defaults to true.