2
The package provides six commands to control compilation and linking.
5
[list_begin definitions]
6
[comment ---------------------------------------------------------------------]
7
[call [cmd ::critcl::check] [opt [arg label]] [arg text]]
9
This command is useful to test if some functionality is available in
10
the build environment, and then select other C code fragments based on
13
It immediately compiles the C code in [arg text] and returns a boolean
14
value based on the result of the compilation.
16
The command returns [const true] on success, and [const false] otherwise.
18
If specified, the [arg label] is used to uniquely mark the check in the
21
[comment ---------------------------------------------------------------------]
22
[call [cmd ::critcl::checklink] [opt [arg label]] [arg text]]
24
This command is an extenson of [cmd critcl::check] above, useful to
25
test if some functionality is available in the build environment, and
26
then select other C code fragments based on that information.
28
It immediately compiles and links the C code in [arg text] and returns
29
a boolean value based on the result of compilation and linking.
31
The command returns [const true] on success, and [const false] otherwise.
33
If specified, the [arg label] is used to uniquely mark the check in the
36
[comment ---------------------------------------------------------------------]
37
[call [cmd ::critcl::msg] [opt [option -nonewline]] [arg msg]]
39
This command can be used by critc-based code to report results from
40
[cmd critcl::check] and [cmd critcl::checklink]. The default
41
implementation used by mode [term {compile & run}] ignores any calls.
43
[para] Tools like the [manpage {CriTcl Application}] are allowed to
44
redefine this procedure to perform their own way of message
45
reporting. The package [package critcl::app] and the application on
46
top print such messages to [term stdout], for example.
48
[comment ---------------------------------------------------------------------]
49
[call [cmd ::critcl::print] [opt [option -nonewline]] [opt [arg chan]] [arg msg]]
51
This command is used by the critcl internals to report its activity.
52
Its signature is equivalent to the Tcl builtin command [cmd ::puts].
53
The default implementation is effectively [cmd ::puts].
55
[para] Tools directly using either the critcl package, or the critcl
56
application package are allowed to redefine this procedure to perform
57
their own way of printing.
59
[para] An example of this is
60
[uri https://chiselapp.com/user/andreas_kupries/repository/Kettle/index Kettle]
61
where the newest revisions use this to highlight build warnings.
63
[comment ---------------------------------------------------------------------]
64
[call [cmd ::critcl::compiled]]
66
This command returns a boolean value. It returns [const true] if the C
67
code of the current [file .critcl] file is already compiled, and
68
[const false] otherwise.
70
[para] This predicate effectively enables a [file .critcl] file used
71
as its own Tcl companion file (see [cmd critcl::tsources]) to
72
distinguish between sourced by mode "compile & run" for compilation
73
and sourced from either the result of mode "generate package" or during
74
the load phase of "compile & run".
76
In case of the two latter possibilities the result is [const true],
77
and [const false] for the first.
79
[comment ---------------------------------------------------------------------]
80
[call [cmd ::critcl::compiling]]
82
This command returns a boolean value. It returns [const true] if C
83
code can be compiled on this platform in general, i.e. if a C compiler
84
is available, and [const false] otherwise.
86
[comment ---------------------------------------------------------------------]
87
[call [cmd ::critcl::done]]
89
This command returns a boolean value. It returns [const true] when
90
critcl has built the embedded C code, and [const false] otherwise.
92
[para] This enables the Tcl code of a critcl-based package to
93
distinguish between it getting used as a prebuilt package, versus
94
dynamic compile & run, and take action based on that.
96
[para] [emph Note] that this command is only useful from within a
97
[file .critcl] file. The result is managed on a per-file basis, like
98
is done for the commands embedding C code and controlling the
99
behaviour of compiler and linker.
101
[para] See also section [sectref {Modes Of Operation/Use}].
103
[comment ---------------------------------------------------------------------]
104
[call [cmd ::critcl::failed]]
106
This command returns a boolean value. It returns [const true] if
107
critcl has failed to build the package. As part of this it forces the
108
building of the package, but not its loading. Note that it will
109
attempt to build the package only on the first call; future calls for
110
the same package will return a cached result.
112
[para] This enables a critcl-based package to check itself for
113
availability and throw an error if it could not be built.
115
[para] [emph Note] that this command is only useful from within in a
116
[file .critcl] file. The result is managed on a per-file basis, like
117
is done for the commands embedding C code and controlling the
118
behaviour of compiler and linker.
120
[comment ---------------------------------------------------------------------]
121
[call [cmd ::critcl::load]]
123
This command is like [cmd critcl::failed], except that it also forces
124
the loading of the generated shared library, if it was built, and that
125
its result has reversed sense.
127
[para] It returns [const true] if critcl succeeded in building and
130
[para] This enables a critcl-based package to to not only check itself
131
for availability and throw an error if it could not be built, but also
132
force an immediate load, circumventing the default behaviour, which is
133
lazy. See also section [sectref {Runtime Behaviour}].
135
[para] [emph Note] that this command is only useful from within in a
136
[file .critcl] file. The result is managed on a per-file basis, like
137
is done for the commands embedding C code and controlling the
138
behaviour of compiler and linker.
added
removed
doc/include/api_introspection.inc
