source: project/wiki/man/4/Declarations @ 25875

Last change on this file since 25875 was 25875, checked in by felix winkelmann, 9 years ago

merged some manual changes from master into wiki

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