3
It explains the syntax of configuration files and the configuration
4
keys used by [package critcl] to configure its build backend, i.e. how
5
this part of the system accesses compiler, linker, etc.
9
It is recommended to open the file containing the standard
10
configurations ([file path/to/critcl/Config]) in the editor of your
11
choice when reading this section of the documentation, using it as an
12
extended set of examples going beyond the simple defaults shown here.
16
First, the keys and the meaning of their values, plus examples drawn
17
from the standard configurations distributed with the package.
19
Note that when writing a custom configuration it is not necessary to
20
specify all the keys listed below, but only those whose default values
21
are wrong or insufficient for the platform in question.
23
[list_begin definitions]
24
[comment {============================================================}]
26
The command to print the compiler version number.
27
Defaults to [example { gcc -v }]
29
[comment {============================================================}]
31
The command to compile a single C source file to an object file.
32
Defaults to [example { gcc -c -fPIC }]
34
[comment {============================================================}]
36
The list of flags for the compiler to enable memory debugging in
38
Defaults to [example { -DTCL_MEM_DEBUG }]
40
[comment {============================================================}]
42
The list of flags for the compiler to add symbols to the object files
43
and the resulting library.
44
Defaults to [example { -g }]
46
[comment {============================================================}]
48
The compiler flag to add an include directory.
49
Defaults to [example { -I }]
51
[comment {============================================================}]
53
The compiler flag to set USE_TCL_STUBS.
54
Defaults to [example { -DUSE_TCL_STUBS }]
56
[comment {============================================================}]
58
The compiler flag to set USE_TK_STUBS.
59
Defaults to [example { -DUSE_TK_STUBS }]
61
[comment {============================================================}]
63
The list of compiler flags to enable a threaded build.
64
Defaults to [example {
65
-DUSE_THREAD_ALLOC=1 -D_REENTRANT=1 -D_THREAD_SAFE=1
66
-DHAVE_PTHREAD_ATTR_SETSTACKSIZE=1 -DHAVE_READDIR_R=1
70
[comment {============================================================}]
72
The compiler flag to turn off assertions in Tcl code.
73
Defaults to [example { -DNDEBUG }]
75
[comment {============================================================}]
77
The compiler flag to specify optimization level.
78
Defaults to [example { -O2 }]
80
[comment {============================================================}]
82
The compiler flags to set the output file of a compilation.
83
Defaults to [example { -o [list $outfile] }]
85
[para] [emph NOTE] the use of Tcl commands and variables here. At the
86
time [package critcl] uses the value of this key the value of the
87
referenced variable is substituted into it. The named variable is the
88
only variable whose value is defined for this substitution.
90
[comment {============================================================}]
92
The file extension for object files on the platform.
93
Defaults to [example { .o }]
95
[comment {============================================================}]
97
The command to preprocess a C source file without compiling it, but
98
leaving #define's in the output. Defaults to [example { gcc -E -dM }]
100
[comment {============================================================}]
102
See [const preproc_define], except that #define's are not left in the
103
output. Defaults to [example { gcc -E }]
105
[comment {============================================================}]
107
The command to link one or more object files and create a shared
108
library. Defaults to [example { gcc -shared }]
110
[comment {============================================================}]
112
The list of linker flags to use when dependent libraries are
113
pre-loaded. Defaults to
114
[example { --unresolved-symbols=ignore-in-shared-libs }]
116
[comment {============================================================}]
118
The flag to tell the linker to strip symbols from the shared library.
119
Defaults to [example { -Wl,-s }]
122
[comment {============================================================}]
124
Like [const output], but for the linker.
125
Defaults to the value of [const output].
127
[comment {============================================================}]
129
The list of linker flags needed to build a shared library with
130
symbols. Defaults to the empty string.
132
One platform requiring this are all variants of Windows, which uses
133
[example { -debug:full -debugtype:cv }]
135
[comment {============================================================}]
137
The list of linker flags needed to build a shared library without
138
symbols, i.e. a regular build. Defaults to the empty string.
140
One platform requiring this are all variants of Windows, which uses
141
[example { -release -opt:ref -opt:icf,3 -ws:aggressive }]
143
[comment {============================================================}]
145
The file extension for shared library files on the platform.
146
Defaults to [example { [info sharedlibextension] }]
148
[comment {============================================================}]
150
The identifier of the platform used in generated packages.
151
Defaults to [example { [platform::generic] }]
153
[comment {============================================================}]
155
The presence of this key marks the configuration as a
156
cross-compilation target and the value is the actual platform
157
identifier of the target. No default.
162
The syntax expected from configuration files is governed by the rules below.
164
Again, it is recommended to open the file containing the standard
165
configurations ([file path/to/critcl/Config]) in the editor of your
166
choice when reading this section of the documentation, using it as an
167
extended set of examples for the syntax>
169
[list_begin enumerated]
170
[comment {============================================================}]
171
[enum] Each logical line of the configuration file consists of one or
172
more physical lines. In case of the latter the physical lines have to
173
follow each other and all but the first must be marked by a trailing
174
backslash. This is the same marker for [term {continuation lines}] as
177
[comment {============================================================}]
178
[enum] A (logical) line starting with the character "#" (modulo
179
whitespace) is a comment which runs until the end of the line, and is
182
[comment {============================================================}]
183
[enum] A (logical) line starting with the word "if" (modulo
184
whitespace) is interpreted as Tcl's [cmd if] command and executed as
185
such. I.e. this command has to follow Tcl's syntax for the command,
186
which may stretch across multiple logical lines. The command will be
187
run in a save interpreter.
189
[comment {============================================================}]
190
[enum] A (logical) line starting with the word "set" (modulo
191
whitespace) is interpreted as Tcl's [cmd set] command and executed as
192
such. I.e. this command has to follow Tcl's syntax for the command,
193
which may stretch across multiple logical lines. The command will be
194
run in a save interpreter.
196
[comment {============================================================}]
197
[enum] A line of the form "[arg platform] [var variable] [arg value]"
198
defines a platform specific configuration variable and value.
200
The [var variable] has to be the name of one of the configuration keys
201
listed earlier in this section, and the [arg platform] string
202
identifies the platform the setting is for. All settings with the same
203
identification string form the [term {configuration block}] for this
206
[comment {============================================================}]
207
[enum] A line of the special form
208
"[arg platform] [const when] [arg expression]"
209
marks the [arg platform] and all the settings in its
210
[term {configuration block}] as conditional on the [arg expression].
214
If the build platform is not a prefix of [arg platform],
215
nor vice versa the whole block is ignored.
217
Otherwise the [arg expression] is evaluated via [cmd expr], in the
218
same safe interpreter used to run any [cmd set] and [cmd if] commands
219
found in the configuration file (see above).
223
If the expression evaluates to [const true] this configuration block
224
is considered to be the build platform fo the host and chosen as the
225
default configuration.
227
An large example of of this feature is the handling of OS X found in
228
the standard configuration file, where it selects the architectures to
229
build based on the version of the operating system, the available SDK,
230
etc. I.e. it chooses whether the output is universal or not, and
231
whether it is old-style (ix86 + ppc) versus new-style (ix86 32+64) of
234
[comment {============================================================}]
235
[enum] A line of the special form
236
"[arg platform] [const copy] [arg sourceplatform]"
237
copies the configuration variables and values currently defined in the
238
[term {configuration block}] for [arg sourceplatform] to that of
239
[arg platform], overwriting existing values, and creating missing
240
ones. Variables of [arg platform] not defined by by [arg sourceplatform]
243
[para] The copied values can be overridden later in the configuration
244
file. Multiple [const copy] lines may exist for a platform and be
245
intermixed with normal configuration definitions. If a variable is
246
defined multiple times, the last definition will be used.
248
[comment {============================================================}]
249
[enum] At last, a line of the form "[var variable] [arg value]"
250
defines a default configuration variable and value.
added
removed
doc/include/iconfig.inc
