5 .\" Manual page for `sw-env' files
10 .\"----- Licensing notice ---------------------------------------------------
12 .\" This file is part of sw-tools.
14 .\" sw-tools is free software; you can redistribute it and/or modify
15 .\" it under the terms of the GNU General Public License as published by
16 .\" the Free Software Foundation; either version 2 of the License, or
17 .\" (at your option) any later version.
19 .\" sw-tools is distributed in the hope that it will be useful,
20 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
21 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 .\" GNU General Public License for more details.
24 .\" You should have received a copy of the GNU General Public License
25 .\" along with sw-tools; if not, write to the Free Software Foundation,
26 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
28 .\" --- Useful macro definitions ---
30 .de VS \" Start a sort-of verbatim block
36 .de VE \" Stop a sort-of verbatim block
42 .de hP \" Start an indented paragraph with a bold right-aligned label
44 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
47 .\" --- Style hacking ---
51 . ds mw \fR[\f(BImdw\fR]
53 .el .ds mw \fR[\fBmdw\fR]
59 .\"----- Main manual text ---------------------------------------------------
61 .TH sw-env 5 "25 May 1999" sw-tools
64 .\"--------------------------------------------------------------------------
68 sw\-env \- environment variable assignment files for \*(sw.
70 .\"--------------------------------------------------------------------------
74 A \*(se file is a sequence of statements. The following statements are
104 Whitespace serves to separate tokens but is otherwise ignored except
105 when it occurs quoted within a
107 The file may also contain comments, which begin with a
109 character and extend to the end of the line. The start of a comment
110 must appear where a new statement is expected. Apart from its behaviour
111 of terminating comments, newlines behave the same way as other
112 whitespace characters. Keywords are not reserved words.
116 is a sequence of digits, letters and underscores which does not start
121 may contain any non-null character, although some characters are special
122 and must be quoted. The syntax of
124 is loosely based on the Bourne
125 shell, although there are differences and irregularities due to the
126 quick and dirty nature of the parser. The various quoting and
127 substitution operations are described below.
131 The statements behave as follows:
136 is read and discarded. This is not useless: reading a
138 may cause variables to be assigned as a result of
140 .BI ${ name = value }\c
146 is read, and further assignments are read from the file so named, if it
147 exists. Conventionally, the last statement in the global \*(se file is
151 to read in package-specific settings.
156 is read. If it matches the name of the host's architecture, then the
157 brace-enclosed statements are executed; otherwise they're ignored. It's
158 possible, though not useful, to nest
167 are read, optionally separated by an
169 character. The variable named is assigned the value, replacing any
170 previously assigned value, if any. The
172 keyword is optional. It's only useful so that you can assign values to
173 variables whose names are also statement keywords.
178 is read. Any value assigned to the variable named is discarded, and the
179 variable is forgotten.
183 The parser usually reads a
185 a character by character, until it finds a delimiter. Delimiter
193 whitespace also acts as a delimiter. Delimiter characters can only
194 appear in a value if quoted.
196 There are three types of quoting understood by the value reader. A
199 character causes the following character to be stripped of its special
202 inserts a literal backslash. Text between single quotes
205 entirely as-is, including all whitespace, newlines, backslashes,
206 everything. To include a single quote in a piece of single-quoted text,
209 as in the shell. (This drops out of single-quoting, inserts an escaped
210 single quote, and resumes quoting.) Text between double quotes
212 is partially quoted: delimiters and whitespace are read as normal
213 characters, but substitutions using the
217 characters are still made, and the backslash retains its behaviour of
218 escaping the following character.
220 Two sorts of substitutions are available in values:
221 .I "variable substitution"
222 examines a variable and substitutes some text based on its value, and
223 .I "command substitution"
224 runs a command and substitutes its output.
226 The simplest variable substitution takes the form
229 this is replaced by the value of the variable called
231 or the empty string if there is no such variable defined. The name may
232 be enclosed in braces should it be necessary to clearly disambiguate the
235 More complex variable substitutions are permitted:
237 .BI ${ name \- text }
238 Expands to the value of the variable called
247 if there is a variable called
252 If there is no variable called
254 then create one with the value
256 then expands to the variable's value.
258 In each of the above, prefixing the operator character
265 changes the variable existence test, such that it will believe that a
266 variable whose value is the empty string is not defined. Each
268 part in the above forms is syntactically a
270 and may itself contain quoting and substitutions. It may also contain
271 unescaped whitespace.
273 There are two forms for command substitution: the backtick form, where a
274 command is enclosed in backquotes
276 and the parenthesized form
278 The only difference between these two forms is syntactic: it's easy to
279 make the parenthesized version nest, although that's not actually very
280 useful. The text between the backquotes or parentheses is broken into
281 words and executed as a command. It is not passed through the shell:
282 the author suspects that this would be too confusing. The standard
283 output of the command, with trailing newlines (but not internal or
284 leading newlines) removed, is the result of the substitution.
286 .\"--------------------------------------------------------------------------
290 The \*(sw program, and this manual, are \*(mw productions, in association
291 with the European Bioinformatics Institute. They were written by Mark
292 Wooding <mdw@nsict.org>. Go and ask him if you have problems.
294 .\"----- That's all, folks --------------------------------------------------