2
The package provides thirteen commands to control the details of
3
compilation and linking, enabling [file .critcl] files to provide
4
custom information about their environment and dependencies.
6
[para] In important thing to note about all these commands is that the
7
package manages their information on a per-file basis.
9
I.e. information provided by and in a file [file FOO.tcl] is kept
10
separate from the information provided by and in a file
11
[file BAR.tcl], preventing them from interfering with each other.
16
[list_begin definitions]
17
[comment ---------------------------------------------------------------------]
18
[call [cmd ::critcl::cheaders] [opt [arg arg]...]]
20
This command provides the compile step with additional header files
23
[para] All arguments matching the glob pattern [const -*] are
24
forwarded to the compiler's command line when it is invoked for the
25
current [file .critcl] file.
27
[para] All other arguments are interpreted as glob pattern and the
28
matching files are made available to the compiler when it is invoked
29
for the current [file .critcl] file. Patterns matching no file or
30
non-existing files cause the command to throw an error.
32
[para] [emph Note] that patterns which are not beginning with an
33
absolute path are interpreted relative to the directory containing the
34
current [file .critcl] file.
36
[para] [emph Note] further that this declaration does not cause the
37
specified header files to be [const {#include}]'d automatically. This
38
still has to be done via [cmd critcl::ccode] where necessary.
40
It does simply ensure that the compiler will be able to find these
41
files when invoked, by providing the necessary command line flags
42
extending the compiler's search paths.
44
[para] Multiple invocations of this command accumulate their
47
[comment ---------------------------------------------------------------------]
48
[call [cmd ::critcl::csources] [opt [arg pattern]...]]
50
This command provides the compile step with additional C source files.
52
[para] All arguments are intepreted as glob patterns. Patterns
53
matching no file or non-existing files cause the command to throw an
54
error. The files matching the patterns are made available to the
55
compiler when it is invoked for the current [file .critcl] file. This
56
means that the files in question are compiled together with the
57
[file .c] file backing the [file .critcl] file into a single object.
59
[para] [emph Note] that patterns which are not beginning with an
60
absolute path are interpreted relative to the directory containing the
61
current [file .critcl] file.
63
[para] Multiple invocations of this command accumulate their
66
[comment ---------------------------------------------------------------------]
67
[call [cmd ::critcl::clibraries] [opt [arg arg]...]]
69
This command provides the link step with additional libraries to link
70
and library locations.
72
[para] All arguments matching the glob pattern [const -*] are
73
forwarded to the linkers's command line when it is invoked for the
74
current [file .critcl] file.
76
[para] All other arguments are interpreted glob patterns. Patterns
77
matching no file or non-existing files cause the command to throw an
78
error. The files matching the patterns are made available to the
79
linker when it is invoked for the current [file .critcl] file. This
80
means that the files in question are linked together with the object
81
file backing the [file .critcl] file into a single shared library.
83
[para] [emph Note] that patterns which are not beginning with an
84
absolute path are interpreted relative to the directory containing the
85
current [file .critcl] file.
87
[para] Multiple invocations of this command accumulate their
90
[comment ---------------------------------------------------------------------]
91
[call [cmd ::critcl::source] [arg path]]
93
This command evaluates the critcl commands in the file specified by
94
[arg path] in the context of the current [file .critcl] file.
96
[para] The argument is actually considered as glob pattern and all
97
matching files are evaluated. A pattern matching no file or
98
non-existing files cause the command to throw an error.
100
[para] [emph Note] that a pattern not beginning with an absolute path
101
is interpreted relative to the directory containing the current
104
[comment ---------------------------------------------------------------------]
105
[call [cmd ::critcl::tsources] [arg pattern]...]
107
This command provides the critcl package with information about
108
additional Tcl script files to source when the shared library is
111
[para] All arguments are considered as glob patterns and the matching
112
files are made available to generated shared library when it is loaded
113
for the current [file .critcl] file. Patterns matching no file or
114
non-existing files cause the command to throw an error.
116
[para] [emph Note] that patterns which are not beginning with an
117
absolute path are interpreted relative to the directory containing the
118
current [file .critcl] file.
120
[para] Multiple invocations of this command accumulate their
123
[para] The declared files are sourced after the shared library has
124
been loaded, in the same order they were provided to [cmd critcl::tsources].
126
[comment ---------------------------------------------------------------------]
127
[call [cmd ::critcl::owns] [arg pattern]...]
129
This command is ignored by the regular build modes, i.e. both "compile
130
and run", and "generate package". It is present to support the static
131
code scanner of critcl v3's new mode to "generate TEA" packages.
133
[para] In that situation it provides the critcl package with
134
information about any files which have to be wrapped and could not be
135
figured out from the previous commands (i.e. [cmd critcl::csources],
136
[cmd critcl::tsources]) because of getting specified dynamically, or
137
getting directly sourced and this not visible to critcl in any other
141
[comment ---------------------------------------------------------------------]
142
[call [cmd ::critcl::cflags] [opt [arg arg]...]]
144
This command provides the compile step with additional compiler flags.
146
[para] All arguments are forwarded to the compiler's command line when
147
it is invoked for the current [file .critcl] file.
149
[para] Multiple invocations of this command accumulate their
152
[comment ---------------------------------------------------------------------]
153
[call [cmd ::critcl::ldflags] [opt [arg arg]...]]
155
This command provides the link step with additional linker flags.
157
[para] All arguments are forwarded to the linkers's command line when
158
it is invoked for the current [file .critcl] file.
160
[para] Multiple invocations of this command accumulate their
163
[comment ---------------------------------------------------------------------]
164
[call [cmd ::critcl::framework] [opt [arg arg]...]]
166
This command provides the link step with the names of additional
167
frameworks to link on MacOS X. The command is ignored if we are not
168
building for OS X. This means that it is possible to declare the OS X
169
specific frameworks unconditionally. The package itself takes care to
170
not use them when building for non-OS X platforms.
172
[para] All arguments are forwarded to the linkers's command line when
173
it is invoked for the current [file .critcl] file.
175
[para] Multiple invocations of this command accumulate their
178
[comment ---------------------------------------------------------------------]
179
[call [cmd ::critcl::tcl] [arg version]]
181
This command tells critcl for what minimum version of the Tcl runtime
182
to compile and link the package for. If not specified critcl falls
183
back to the default of [const 8.4].
185
[comment ---------------------------------------------------------------------]
186
[call [cmd ::critcl::tk]]
188
This command informs critcl that the package in question is based on
189
Tk, and therefore needs the Tk headers for compilation, and the Tk
192
[comment ---------------------------------------------------------------------]
193
[call [cmd ::critcl::preload] [arg lib]...]
195
This command arranges that the named dependent external shared library is loaded
196
before the generated package's shared library.
198
[para] Multiple invocations of this command accumulate their
201
[para][include preload_search.inc]
204
XXX preload - compile & run - will it work ?
207
If you are a developer wishing to understand or modify the internals
208
of the [package critcl] package then you possibly should read the
209
section explaining how the [sectref {Preloading functionality}] is
212
[comment ---------------------------------------------------------------------]
213
[call [cmd ::critcl::debug] [arg area]...]
215
This tells critcl if the package is to be compiled for debugging, and
216
which areas to activate. Internally each area is translated into
217
area-specific flags for the compiler which are then handed over to
218
[cmd critcl::cflags].
220
[list_begin definitions]
223
Specification of this area activates Tcl memory debugging
224
for the package code.
226
[def [const symbols]]
228
Specification of this area activates compilation and linking with
229
debugging symbols, for use by a debugger or other tool.
233
Specification of this area translates ino the activation of all other
added
removed
doc/include/api_control.inc
