1 | [[tags: manual]] |
---|
2 | [[toc:]] |
---|
3 | |
---|
4 | |
---|
5 | == Declarations |
---|
6 | |
---|
7 | |
---|
8 | Declarations can be used to control compiler settings directly inside |
---|
9 | the compiled code and are always global in scope. In many (but not |
---|
10 | all) cases an associated command-line option exists. When in conflict, |
---|
11 | declarations override command-line options. When multiple declarations |
---|
12 | conflict, the one appearing textually last overrides any previous one. |
---|
13 | |
---|
14 | |
---|
15 | === declare |
---|
16 | |
---|
17 | <macro>(declare DECLSPEC ...)</macro> |
---|
18 | |
---|
19 | Process declaration specifiers. Declarations always override |
---|
20 | any command-line settings. Declarations are valid for the whole |
---|
21 | compilation-unit (source file), the position of the declaration in |
---|
22 | the source file can be arbitrary. Declarations are ignored in the interpreter |
---|
23 | but not in code evaluated at compile-time (by {{eval-when}} or in |
---|
24 | syntax 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 | |
---|
32 | Declares that the given variables are always bound and |
---|
33 | accesses to those have not to be checked. |
---|
34 | |
---|
35 | |
---|
36 | === block |
---|
37 | |
---|
38 | [declaration specifier] (block) |
---|
39 | |
---|
40 | Assume global variables are never redefined. This is the same as |
---|
41 | specifying the {{-block}} option. |
---|
42 | |
---|
43 | |
---|
44 | === block-global |
---|
45 | === hide |
---|
46 | |
---|
47 | [declaration specifier] (block-global IDENTIFIER ...) |
---|
48 | [declaration specifier] (hide IDENTIFIER ...) |
---|
49 | |
---|
50 | Declares that the toplevel bindings for {{IDENTIFIER ...}} |
---|
51 | should not be accessible from code in other compilation units or by |
---|
52 | {{eval}}. Access to toplevel bindings declared as block global is |
---|
53 | also more efficient. {{(declare (hide))}} is equivalent to {{(declare (block))}}. |
---|
54 | |
---|
55 | |
---|
56 | === bound-to-procedure |
---|
57 | |
---|
58 | [declaration specifier] (bound-to-procedure IDENTIFIER ...) |
---|
59 | |
---|
60 | Declares 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 | |
---|
68 | Enables 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 | |
---|
75 | Declares the procedures with the names {{SYMBOL ...}} as constant, that is, as not having any |
---|
76 | side effects. This can help the compiler to remove non-side-effecting expressions. |
---|
77 | |
---|
78 | |
---|
79 | === export |
---|
80 | |
---|
81 | [declaration specifier] (export IDENTIFIER ...) |
---|
82 | |
---|
83 | The opposite of {{hide}}. All given identifiers will be exported and all toplevel variables |
---|
84 | not 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 | |
---|
91 | Emit prototypes for callbacks defined with {{define-external}} before any |
---|
92 | other foreign declarations. Equivalent to giving the {{-emit-external-prototypes-first}} |
---|
93 | option to the compiler. |
---|
94 | |
---|
95 | |
---|
96 | === disable-interrupts |
---|
97 | |
---|
98 | [declaration specifier] (disable-interrupts) |
---|
99 | [declaration specifier] (not interrupts-enabled) |
---|
100 | |
---|
101 | Disable timer-interrupts checks in the compiled program. Threads can |
---|
102 | not 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 | |
---|
109 | Declares that any following definition of a module named {{MODULENAME}} should be written to |
---|
110 | an external file (either a specified one or a file named {{"MODULENAME.import.scm"}}). |
---|
111 | The compiler option {{-emit-import-library}} may also be used instead. |
---|
112 | |
---|
113 | Note that the import library is only generated if it cannot be found in the current |
---|
114 | directory, 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 | |
---|
124 | If given without an identifier-list, inlining of known procedures is enabled (this is equivalent to the {{-inline}} |
---|
125 | compiler option). When an identifier-list is given, then inlining is enabled only for the specified global procedures. |
---|
126 | The negated forms {{(not inline)}} and {{(not inline IDENTIFIER)}} disable global inlining, or inlining for |
---|
127 | the 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 | |
---|
137 | Declare that then given toplevel procedures (or all) are subject to |
---|
138 | cross-module inlining. Potentially inlinable procedures in the current |
---|
139 | compilation unit will be written to an external |
---|
140 | {{<source-filename>.inline}} file in the current directory. Globally |
---|
141 | inlinable 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 |
---|
144 | in the current compilation unit. |
---|
145 | |
---|
146 | Enabling global inlining implies {{(declare (inline))}}. |
---|
147 | |
---|
148 | |
---|
149 | === inline-limit |
---|
150 | |
---|
151 | [declaration specifier] (inline-limit THRESHOLD) |
---|
152 | |
---|
153 | Sets 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 | |
---|
160 | Enable timer-interrupts checks in the compiled program (the default). |
---|
161 | |
---|
162 | |
---|
163 | === keep-shadowed-macros |
---|
164 | |
---|
165 | [declaration specifier] (keep-shadowed-macros) |
---|
166 | |
---|
167 | Normally, when a toplevel variable is assigned or defined that has the same name as a macro, the macro-definition |
---|
168 | will 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 | |
---|
176 | Declares that the listed (or all) toplevel variables defined in the |
---|
177 | current compilation unit are not modified from code outside of this |
---|
178 | compilation unit. See also the documentation for the {{-local}} |
---|
179 | compiler option about the implications of this. |
---|
180 | |
---|
181 | |
---|
182 | === no-argc-checks |
---|
183 | |
---|
184 | [declaration specifier] (no-argc-checks) |
---|
185 | |
---|
186 | Disables argument count checking. |
---|
187 | |
---|
188 | |
---|
189 | === no-bound-checks |
---|
190 | |
---|
191 | [declaration specifier] (no-bound-checks) |
---|
192 | |
---|
193 | Disables the bound-checking of toplevel bindings. |
---|
194 | |
---|
195 | |
---|
196 | === no-procedure-checks |
---|
197 | |
---|
198 | [declaration specifier] (no-procedure-checks) |
---|
199 | |
---|
200 | Disables 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 | |
---|
207 | Disables 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 | |
---|
214 | Disables 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 | |
---|
222 | Arranges for the shell commands {{STRING ...}} to be invoked after the current |
---|
223 | file has been translated to C. Any occurrences of the substring {{$@@}} in the |
---|
224 | strings given for this declaration will be replaced by the pathname of the currently |
---|
225 | compiled file, without the file-extension. |
---|
226 | This declaration will only work if the source file is compiled |
---|
227 | with the {{csc}} compiler driver. |
---|
228 | |
---|
229 | |
---|
230 | === profile |
---|
231 | |
---|
232 | [declaration specifier] (profile IDENTIFIER ...) |
---|
233 | |
---|
234 | Enable profiling exclusively for given identifiers. Normally the compiler |
---|
235 | enables profiling decorations for all globally defined procedures. With |
---|
236 | this 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 | |
---|
245 | Declares that only numbers of the given type are used. {{TYPE}} |
---|
246 | may be {{fixnum}} or {{generic}} (which is |
---|
247 | the default). |
---|
248 | |
---|
249 | |
---|
250 | === compile-syntax |
---|
251 | |
---|
252 | [declaration specifier] (compile-syntax) |
---|
253 | |
---|
254 | Equivalent to the compiler option of the same name - macros defined in the compiled code are also made available at |
---|
255 | runtime. |
---|
256 | |
---|
257 | |
---|
258 | === safe-globals |
---|
259 | |
---|
260 | [declaration specifier] (safe-globals) |
---|
261 | |
---|
262 | Assumes variables assigned in the current compilation unit are always bound and |
---|
263 | that any calls to these variables can always be assumed to be calls to proper |
---|
264 | procedures. |
---|
265 | |
---|
266 | |
---|
267 | === scrutinize |
---|
268 | |
---|
269 | [declaration specifier] (scrutinize) |
---|
270 | |
---|
271 | Enables 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 | |
---|
279 | Declares that all given standard procedures (or all if no symbols are |
---|
280 | specified) are never globally redefined. If {{not}} is specified, |
---|
281 | then all but the given standard bindings are assumed to be never |
---|
282 | redefined. |
---|
283 | |
---|
284 | |
---|
285 | === type |
---|
286 | |
---|
287 | [declaration specifier] (type (SYMBOL TYPESPEC) ...) |
---|
288 | |
---|
289 | Declares toplevel procedures to have a specific type for scrutiny. {{SYMBOL}} should name |
---|
290 | a toplevel variable and {{TYPESPEC}} should be a type specification, following the syntax |
---|
291 | given 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 | |
---|
329 | A 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 | |
---|
337 | Declares that all given non-standard and CHICKEN-specific procedures (or all if no symbols are specified) are never globally redefined. |
---|
338 | If {{not}} is specified, then all but the given extended bindings |
---|
339 | are 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 | |
---|
347 | Declares that all given standard and extended bindings (or all if no |
---|
348 | symbols are specified) are never globally redefined. If {{not}} |
---|
349 | is specified, then all but the given standard and extended bindings are |
---|
350 | assumed to be never redefined. Note that this is the default behaviour, |
---|
351 | unless the {{-no-usual-integrations}} option has been given. |
---|
352 | |
---|
353 | |
---|
354 | === unit |
---|
355 | |
---|
356 | [declaration specifier] (unit IDENTIFIER) |
---|
357 | |
---|
358 | Specify compilation unit-name (if this is a library) |
---|
359 | |
---|
360 | |
---|
361 | === unsafe |
---|
362 | |
---|
363 | [declaration specifier] (unsafe) |
---|
364 | [declaration specifier] (not safe) |
---|
365 | |
---|
366 | Do 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 | |
---|
377 | Disables any warnings when the global variable {{IDENTIFIER}} is not defined but used, |
---|
378 | or defined but never used and not exported. |
---|
379 | |
---|
380 | |
---|
381 | === uses |
---|
382 | |
---|
383 | [declaration specifier] (uses IDENTIFIER ...) |
---|
384 | |
---|
385 | Gives a list of used library-units. Before the toplevel-expressions |
---|
386 | of the main-module are executed, all used units evaluate their |
---|
387 | toplevel-expressions in the order in which they appear in this |
---|
388 | declaration. If a library unit A uses another unit B, then B's toplevel |
---|
389 | expressions are evaluated before A's. Furthermore, the used symbols |
---|
390 | are registered as features during compile-time, so {{cond-expand}} |
---|
391 | knows about them. |
---|
392 | |
---|
393 | |
---|
394 | === unsafe-specialized-arithmetic |
---|
395 | |
---|
396 | [declaration specifier] (unsafe-specialized-arithmetic) |
---|
397 | |
---|
398 | Assume specialized arithmetic operations like {{fp+}}, {{fpsin}}, etc. |
---|
399 | are always called with arguments of correct type and perform |
---|
400 | unboxing of intermediate results if possible and if the {{-unboxing}} |
---|
401 | compiler-option has been enabled (done by default on optimization |
---|
402 | levels 2 and higher). |
---|
403 | |
---|
404 | |
---|
405 | --- |
---|
406 | Previous: [[Modules]] |
---|
407 | |
---|
408 | Next: [[Parameters]] |
---|