source: project/chicken/trunk/manual/Declarations @ 14828

Last change on this file since 14828 was 14828, checked in by felix winkelmann, 10 years ago

merged scrutiny branch

File size: 10.3 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4
5== Declarations
6
7
8=== declare
9
10 [syntax] (declare DECLSPEC ...)
11
12Process declaration specifiers. Declarations always override
13any command-line settings.  Declarations are valid for the whole
14compilation-unit (source file), the position of the declaration in
15the source file can be arbitrary. Declarations are ignored in the interpreter
16but not in code evaluated at compile-time (by {{eval-when}} or in
17syntax extensions loaded via {{require-extension}}).
18{{DECLSPEC}} may be any of the following:
19
20
21=== always-bound
22
23 [declaration specifier] (always-bound SYMBOL ...)
24
25Declares that the given variables are always bound and
26accesses to those have not to be checked.
27
28
29=== block
30
31 [declaration specifier] (block)
32
33Assume global variables are never redefined. This is the same as
34specifying the {{-block}} option.
35
36
37=== block-global
38=== hide
39
40 [declaration specifier] (block-global SYMBOL ...)
41 [declaration specifier] (hide SYMBOL ...)
42
43Declares that the toplevel bindings for {{SYMBOL ...}}
44should not be accessible from code in other compilation units or by
45{{eval}}. Access to toplevel bindings declared as block global is
46also more efficient. {{(declare (hide))}} is equivalent to {{(declare (block))}}.
47
48
49=== bound-to-procedure
50
51 [declaration specifier] (bound-to-procedure SYMBOL ...)
52
53Declares that the given identifiers are always bound to procedure values.
54
55
56=== check-c-syntax
57
58 [declaration specifier] (check-c-syntax)
59 [declaration specifier] (not check-c-syntax)
60
61Enables or disables syntax-checking of embedded C/C++ code fragments. Checking C syntax is the default.
62
63
64=== constant
65
66 [declaration specifier] (constant SYMBOL ...)
67
68Declares the procedures with the names {{SYMBOL ...}} as constant, that is, as not having any
69side effects. This can help the compiler to remove non-side-effecting expressions.
70
71
72=== export
73
74 [declaration specifier] (export SYMBOL ...)
75
76The opposite of {{hide}}. All given identifiers will be exported and all toplevel variables
77not listed will be hidden and not be accessible outside of this compilation unit.
78
79
80=== emit-exports
81
82 [declaration specifier] (emit-exports STRING)
83
84Write exported toplevel variables to file with name {{STRING}}.
85
86
87=== emit-external-prototypes-first
88
89 [declaration specifier] (emit-external-prototypes-first)
90
91Emit prototypes for callbacks defined with {{define-external}} before any
92other foreign declarations. Equivalent to giving the {{-emit-external-prototypes-first}}
93option to the compiler.
94
95
96=== disable-interrupts
97
98 [declaration specifier] (disable-interrupts)
99 [declaration specifier] (not interrupts-enabled)
100
101Disable timer-interrupts checks in the compiled program. Threads can
102not be preempted in main- or library-units that contain this declaration.
103
104
105=== disable-warning
106
107 [declaration specifier] (disable-warning CLASS ...)
108
109Disable warnings of type {{CLASS ...}} (equivalent to the {{-disable-warning CLASS}}
110compiler option).
111
112
113=== emit-import-library
114
115 [declaration specifier] (emit-import-library MODULENAME | (MODULENAME FILENAME) ...)
116
117Declares that any following definition of a module named {{MODULENAME}} should be written to
118an external file (either a specified one or a file named {{"MODULENAME.import.scm"}}).
119The compiler option {{-emit-import-library}} may also be used.
120
121
122=== inline
123
124 [declaration specifier] (inline)
125 [declaration specifier] (not inline)
126 [declaration specifier] (inline IDENTIFIER ...)
127 [declaration specifier] (not inline IDENTIFIER ...)
128
129If given without an identifier-list, inlining of known procedures is enabled (this is equivalent to the {{-inline}}
130compiler option). When an identifier-list is given, then inlining is enabled only for the specified global procedures.
131The negated forms {{(not inline)}} and {{(not inline IDENTIFIER)}} disable global inlining, or inlining for
132the given global procedures only, respectively.
133
134
135=== inline-global
136
137  [declaration specifier] (inline-global)
138  [declaration specifier] (not inline-global)
139  [declaration specifier] (inline-global IDENTIFIER ...)
140  [declaration specifier] (not inline-global IDENTIFIER ...)
141
142Declare that then given toplevel procedures (or all) are subject to
143cross-module inlining. Potentially inlinable procedures in the current
144compilation unit will be written to an external
145{{<source-filename>.inline}} file in the current directory. Globally
146inlinable procedures from other compilation units referred to via
147{{(declare (uses ...))}} or {{require-extension}} are loaded from
148{{.inline}} files (if available in the current include path) and inlined
149in the current compilation unit.
150
151Enabling global inlining implies {{(declare (inline))}}.
152
153
154=== inline-limit
155
156 [declaration specifier] (inline-limit THRESHOLD)
157
158Sets the maximum size of procedures which may potentially be inlined. The default threshold is {{20}}.
159
160
161=== interrupts-enabled
162
163 [declaration specifier] (interrupts-enabled)
164
165Enable timer-interrupts checks in the compiled program (the default).
166
167
168=== keep-shadowed-macros
169
170 [declaration specifier] (keep-shadowed-macros)
171
172Normally, when a toplevel variable is assigned or defined that has the same name as a macro, the macro-definition
173will be removed (in addition to showing a warning). This declaration will disable the removal of the macro.
174
175
176=== lambda-lift
177
178 [declaration specifier] (lambda-lift)
179
180Enables lambda-lifting (equivalent to the {{-lambda-lift}} option).
181
182
183=== local
184
185 [declaration specifier] (local)
186 [declaration specifier] (local SYMBOL ...)
187
188Declares that the listed (or all) toplevel variables defined in the
189current compilation unit are not modified from code outside of this
190compilation unit.
191
192
193=== no-argc-checks
194
195 [declaration specifier] (no-argc-checks)
196
197Disables argument count checking.
198
199
200=== no-bound-checks
201
202 [declaration specifier] (no-bound-checks)
203
204Disables the bound-checking of toplevel bindings.
205
206
207=== no-procedure-checks
208
209 [declaration specifier] (no-procedure-checks)
210
211Disables checking of values in operator position for being of procedure type.
212
213
214=== post-process
215
216 [declaration specifier] (post-process STRING ...)
217
218Arranges for the shell commands {{STRING ...}} to be invoked after the current
219file has been translated to C. Any occurrences of the substring {{$@@}} in the
220strings given for this declaration will be replaced by the pathname of the currently
221compiled file, without the file-extension.
222This declaration will only work if the source file is compiled
223with the {{csc}} compiler driver.
224
225
226=== profile
227
228 [declaration specifier] (profile IDENTIFIER ...)
229
230Enable profiling exclusively for given identifiers. Normally the compiler
231enables profiling decorations for all globally defined procedures. With
232this declaration, profiling can be enabled for selected procedures.
233
234
235=== number-type
236=== fixnum-arithmetic
237
238 [declaration specifier] ([number-type] TYPE)
239 [declaration specifier] (fixnum-arithmetic)
240
241Declares that only numbers of the given type are used. {{TYPE}}
242may be {{fixnum}} or {{generic}} (which is
243the default).
244
245
246=== compile-syntax
247
248 [declaration specifier] (compile-syntax)
249
250Equivalent to the compiler option of the same name - macros defined in the compiled code are also made available at
251runtime.
252
253
254=== scrutinize
255
256 [declaration specifier] (scrutinize)
257
258Enables scrutiny. This is equivalent to passing the {{-scrutinize}} option to the compiler.
259
260
261=== standard-bindings
262
263 [declaration specifier] (standard-bindings SYMBOL ...)
264 [declaration specifier] (not standard-bindings SYMBOL ...)
265
266Declares that all given standard procedures (or all if no symbols are
267specified) are never globally redefined.  If {{not}} is specified,
268then all but the given standard bindings are assumed to be never
269redefined.
270
271
272=== type
273
274  [declaration specifier] (type (SYMBOL TYPESPEC) ...)
275
276Declares toplevel procedures to have a specific type for scrutiny. {{SYMBOL}} should name
277a toplevel variable and {{TYPESPEC}} should be a type specification, following the syntax
278given here:
279
280  TYPESPEC --> *
281            |  ( VAL1 ... )
282 
283  VAL --> (or VAL1 ...)
284       |  (struct NAME)
285       |  (procedure (VAL1 ... [#!optional VALOPT1 ...] [#!rest [VAL]]) . RESULTS)
286       |  BASIC
287       |  deprecated
288 
289  BASIC --> *
290         |  string
291         |  symbol
292         |  char
293         |  number
294         |  boolean
295         |  list
296         |  pair
297         |  procedure
298         |  vector
299         |  null
300         |  eof
301         |  port
302         |  blob
303         |  pointer
304         |  locative
305         |  fixnum
306         |  float
307 
308  RESULTS --> *
309           |  (RVAL1 ...)
310
311  RVAL --> undefined
312        |  noreturn
313
314A type-declaration overrides any previous declaration for the same identifier.
315
316
317=== extended-bindings
318
319 [declaration specifier] (extended-bindings SYMBOL ...)
320 [declaration specifier] (not extended-bindings SYMBOL ...)
321
322Declares that all given non-standard and CHICKEN-specific procedures (or all if no symbols are specified) are never globally redefined.
323If {{not}} is specified, then all but the given extended bindings
324are assumed to be never redefined.
325
326
327=== usual-integrations
328
329 [declaration specifier] (usual-integrations SYMBOL ...)
330 [declaration specifier] (not usual-integrations SYMBOL ...)
331
332Declares that all given standard and extended bindings (or all if no
333symbols are specified) are never globally redefined.  If {{not}}
334is specified, then all but the given standard and extended bindings are
335assumed to be never redefined. Note that this is the default behaviour,
336unless the {{-no-usual-integrations}} option has been given.
337
338
339=== unit
340
341 [declaration specifier] (unit SYMBOL)
342
343Specify compilation unit-name (if this is a library)
344
345
346=== unsafe
347
348 [declaration specifier] (unsafe)
349 [declaration specifier] (not safe)
350
351Do not generate safety-checks. This is the same as specifying the
352{{-unsafe}} option.  Also implies
353
354
355 (declare (no-bound-checks) (no-procedure-checks) (no-argc-checks))
356
357
358=== unused
359
360 [declaration specifier] (unused SYMBOL ...)
361
362Disables any warnings when the global variable {{SYMBOL}} is not defined but used,
363or defined but never used and not exported.
364
365
366=== uses
367
368 [declaration specifier] (uses SYMBOL ...)
369
370Gives a list of used library-units. Before the toplevel-expressions
371of the main-module are executed, all used units evaluate their
372toplevel-expressions in the order in which they appear in this
373declaration. If a library unit A uses another unit B, then B's toplevel
374expressions are evaluated before A's.  Furthermore, the used symbols
375are registered as features during compile-time, so {{cond-expand}}
376knows about them.
377
378---
379Previous: [[Modules and macros]]
380
381Next: [[Parameters]]
Note: See TracBrowser for help on using the repository browser.