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

Last change on this file since 23717 was 23717, checked in by Ivan Raikov, 10 years ago

Chicken manual: merging changes from the core repository

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