~ chicken-core (chicken-5) /manual/Declarations
Trap1[[tags: manual]]2[[toc:]]345== Declarations678Declarations can be used to control compiler settings directly inside9the compiled code and are always global in scope. In many (but not10all) cases an associated command-line option exists. When in conflict,11declarations override command-line options. When multiple declarations12conflict, the one appearing textually last overrides any previous one.1314Declarations can be used to improve performance and to give entities15like procedures and variables special properties that can result in16better performing code. Most of these declarations subtly change the17semantics of standard Scheme code with respect to the declared18entities, so care must be taken when using them.1920Declarations are always ignored in {{csi}} (the interpreter) or in evaluated code.212223=== declare2425<macro>(declare DECLSPEC ...)</macro>2627Process declaration specifiers. Declarations always override28any command-line settings. Declarations are valid for the whole29compilation-unit (source file), the position of the declaration in30the source file can be arbitrary. Declarations are ignored in the interpreter31but not in code evaluated at compile-time (by {{eval-when}} or in32syntax extensions loaded via {{require-extension}}).33{{DECLSPEC}} may be any of the following:343536=== always-bound3738 [declaration specifier] (always-bound IDENTIFIER ...)3940Declares that the given variables are always bound and41accesses to those have not to be checked.424344=== block4546 [declaration specifier] (block)4748Assume global variables are never redefined. This is the same as49specifying the {{-block}} option.505152=== block-global53=== hide5455 [declaration specifier] (block-global IDENTIFIER ...)56 [declaration specifier] (hide IDENTIFIER ...)5758Declares that the toplevel bindings for {{IDENTIFIER ...}}59should not be accessible from code in other compilation units or by60{{eval}}. Access to toplevel bindings declared as block global is61also more efficient. {{(declare (hide))}} is equivalent to {{(declare (block))}}.626364=== bound-to-procedure6566 [declaration specifier] (bound-to-procedure IDENTIFIER ...)6768Declares that the given identifiers are always bound to procedure values.697071=== enforce-argument-types7273 [declaration-specifier] (enforce-argument-types IDENTIFIER ...)7475Declares that the toplevel procedures listed check the type of their arguments76(either explicitly or by calling other enforcing procedures) and so a successfull77invocation will indicate the arguments are of the types declared.787980=== export8182 [declaration specifier] (export IDENTIFIER ...)8384The opposite of {{hide}}. All given identifiers will be exported and all toplevel variables85not listed will be hidden and not be accessible outside of this compilation unit.868788=== emit-external-prototypes-first8990 [declaration specifier] (emit-external-prototypes-first)9192Emit prototypes for callbacks defined with {{define-external}} before any93other foreign declarations. Equivalent to giving the {{-emit-external-prototypes-first}}94option to the compiler.959697=== disable-interrupts9899 [declaration specifier] (disable-interrupts)100101Disable timer-interrupts checks in the compiled program. Threads can102not be preempted in main- or library-units that contain this declaration.103104105=== emit-import-library106107 [declaration specifier] (emit-import-library MODULENAME | (MODULENAME FILENAME) ...)108109Declares that any following definition of a module named {{MODULENAME}} should be written to110an external file (either a specified one or a file named {{"MODULENAME.import.scm"}}).111The compiler option {{-emit-import-library}} may also be used instead.112113Note that the import library is only generated if it cannot be found in the current114directory, or if it exists but is not equal to the one that would be generated.115116117=== emit-types-file118119 [declaration specifier] (emit-types-file [FILENAME])120121Enables generation of a types file for the current compilation unit, which will122be written to the specified {{FILENAME}} or to {{<source-filename>.types}} in the123current directory. This filename can be overridden with the {{-emit-types-file}}124command line flag, which takes precedence over this declaration.125126127=== inline128129 [declaration specifier] (inline)130 [declaration specifier] (not inline)131 [declaration specifier] (inline IDENTIFIER ...)132 [declaration specifier] (not inline IDENTIFIER ...)133134If given without an identifier-list, inlining of known procedures is enabled (this is equivalent to the {{-inline}}135compiler option). When an identifier-list is given, then inlining is enabled only for the specified global procedures.136The negated forms {{(not inline)}} and {{(not inline IDENTIFIER)}} disable global inlining, or inlining for137the given global procedures only, respectively.138139140=== inline-global141142 [declaration specifier] (inline-global)143 [declaration specifier] (not inline-global)144 [declaration specifier] (inline-global IDENTIFIER ...)145 [declaration specifier] (not inline-global IDENTIFIER ...)146147Declare that then given toplevel procedures (or all) are subject to148cross-module inlining. Potentially inlinable procedures in the current149compilation unit will be written to an external150{{<source-filename>.inline}} file in the current directory. Globally151inlinable procedures from other compilation units referred to via152{{(declare (uses ...))}} or {{require-extension}} are loaded from153{{.inline}} files (if available in the current include path) and inlined154in the current compilation unit.155156Enabling global inlining implies {{(declare (inline))}}.157158159=== inline-limit160161 [declaration specifier] (inline-limit THRESHOLD)162163Sets the maximum size of procedures which may potentially be inlined. The default threshold is {{20}}.164165166=== unroll-limit167168 [declaration specifier] (unroll-limit LIMIT)169170Sets the maximum number of times a self-recursive call is inlined and171so effectively "unrolled". The default limit is 1.172173174=== keep-shadowed-macros175176 [declaration specifier] (keep-shadowed-macros)177178Normally, when a toplevel variable is assigned or defined that has the same name as a macro, the macro-definition179will be removed (in addition to showing a warning). This declaration will disable the removal of the macro.180181182=== local183184 [declaration specifier] (local)185 [declaration specifier] (local IDENTIFIER ...)186187Declares that the listed (or all) toplevel variables defined in the188current compilation unit are not modified from code outside of this189compilation unit. See also the documentation for the {{-local}}190compiler option about the implications of this.191192193=== no-argc-checks194195 [declaration specifier] (no-argc-checks)196197Disables argument count checking.198199200=== no-bound-checks201202 [declaration specifier] (no-bound-checks)203204Disables the bound-checking of toplevel bindings.205206207=== no-procedure-checks208209 [declaration specifier] (no-procedure-checks)210211Disables checking of values in operator position for being of procedure type.212213214=== no-procedure-checks-for-usual-bindings215216 [declaration specifier] (no-procedure-checks-for-usual-bindings)217218Disables checking of procedures for the default standard- and extended toplevel bindings.219220221=== no-procedure-checks-for-toplevel-bindings222223 [declaration specifier] (no-procedure-checks-for-toplevel-bindings)224225Disables checking of procedures for calls to procedures referenced via a toplevel variable226(calls to explicitly named procedures).227228229=== predicate230231 [declaration specifier] (predicate (IDENTIFIER TYPE) ...)232233Marks the global procedure {{IDENTIFIER}} as a predicate on {{TYPE}}.234235236=== profile237238 [declaration specifier] (profile IDENTIFIER ...)239240Enable profiling exclusively for given identifiers. Normally the compiler241enables profiling decorations for all globally defined procedures. With242this declaration, profiling can be enabled for selected procedures.243244245=== pure246247 [declaration specifier] (pure IDENTIFIER ...)248249Declares the procedures with the names {{IDENTIFIER ...}} as250referentially transparent, that is, as not having any side251effects. This can help the compiler to remove non-side-effecting252expressions.253254255=== number-type256=== fixnum-arithmetic257258 [declaration specifier] ([number-type] TYPE)259 [declaration specifier] (fixnum-arithmetic)260261Declares that only numbers of the given type are used. {{TYPE}}262may be {{fixnum}} or {{generic}} (which is263the default).264265266=== compile-syntax267268 [declaration specifier] (compile-syntax)269270Equivalent to the compiler option of the same name - macros defined in the compiled code are also made available at271runtime.272273274=== safe-globals275276 [declaration specifier] (safe-globals)277278Assumes variables assigned in the current compilation unit are always bound and279that any calls to these variables can always be assumed to be calls to proper280procedures.281282283=== specialize284285 [declaration specifier] (specialize)286287Enables specialization. This is equivalent to passing the {{-specialize}} option to the compiler.288289290=== standard-bindings291292 [declaration specifier] (standard-bindings IDENTIFIER ...)293 [declaration specifier] (not standard-bindings IDENTIFIER ...)294295Declares that all given standard procedures (or all if no symbols are296specified) are never globally redefined. If {{not}} is specified,297then all but the given standard bindings are assumed to be never298redefined.299300301=== strict-types302303 [declaration specifier] (strict-types)304305Declares that the type of variables is not changed by assignment. Equivalent to giving the {{-strict-types}} compiler option.306307308=== type309310 [declaration specifier] (type (IDENTIFIER TYPE) ...)311312Declares toplevel procedures to have a specific type for313scrutiny. {{IDENTIFIER}} should name a toplevel variable and {{TYPE}}314should be a type specification. A type-declaration overrides any315previous declaration for the same identifier. See also [[Types]] for316more information about using types, the syntax of type-specifiers and317a more convenient type-declaration syntax ({{:}}).318319320=== extended-bindings321322 [declaration specifier] (extended-bindings IDENTIFIER ...)323 [declaration specifier] (not extended-bindings IDENTIFIER ...)324325Declares that all given non-standard and CHICKEN-specific procedures (or all if no symbols are specified) are never globally redefined.326If {{not}} is specified, then all but the given extended bindings327are assumed to be never redefined.328329330=== usual-integrations331332 [declaration specifier] (usual-integrations IDENTIFIER ...)333 [declaration specifier] (not usual-integrations IDENTIFIER ...)334335Declares that all given standard and extended bindings (or all if no336symbols are specified) are never globally redefined. If {{not}}337is specified, then all but the given standard and extended bindings are338assumed to be never redefined. Note that this is the default behaviour,339unless the {{-no-usual-integrations}} option has been given.340341342=== unit343344 [declaration specifier] (unit IDENTIFIER)345346Specify compilation unit-name (if this is a library)347348349=== unsafe350351 [declaration specifier] (unsafe)352 [declaration specifier] (not safe)353354Do not generate safety-checks. This is the same as specifying the355{{-unsafe}} option. Also implies356357358 (declare (no-bound-checks) (no-procedure-checks) (no-argc-checks))359360361=== unused362363 [declaration specifier] (unused IDENTIFIER ...)364365Disables any warnings when the global variable {{IDENTIFIER}} is not defined but used,366or defined but never used and not exported.367368369=== uses370371 [declaration specifier] (uses IDENTIFIER ...)372373Gives a list of used library-units. Before the toplevel-expressions374of the main-module are executed, all used units evaluate their375toplevel-expressions in the order in which they appear in this376declaration. If a library unit A uses another unit B, then B's toplevel377expressions are evaluated before A's. Furthermore, the used symbols378are registered as features during compile-time, so {{cond-expand}}379knows about them.380381382---383Previous: [[Types]]384385Next: [[Extensions]]