[[tags: manual]]
[[toc:]]


== Declarations


=== declare

<macro>(declare DECLSPEC ...)</macro>

Process declaration specifiers. Declarations always override
any command-line settings.  Declarations are valid for the whole
compilation-unit (source file), the position of the declaration in
the source file can be arbitrary. Declarations are ignored in the interpreter
but not in code evaluated at compile-time (by {{eval-when}} or in
syntax extensions loaded via {{require-extension}}).
{{DECLSPEC}} may be any of the following:


=== always-bound

 [declaration specifier] (always-bound SYMBOL ...)

Declares that the given variables are always bound and
accesses to those have not to be checked.


=== block

 [declaration specifier] (block)

Assume global variables are never redefined. This is the same as
specifying the {{-block}} option.


=== block-global
=== hide

 [declaration specifier] (block-global SYMBOL ...)
 [declaration specifier] (hide SYMBOL ...)

Declares that the toplevel bindings for {{SYMBOL ...}}
should not be accessible from code in other compilation units or by
{{eval}}. Access to toplevel bindings declared as block global is
also more efficient. {{(declare (hide))}} is equivalent to {{(declare (block))}}.


=== bound-to-procedure

 [declaration specifier] (bound-to-procedure SYMBOL ...)

Declares that the given identifiers are always bound to procedure values.


=== check-c-syntax

 [declaration specifier] (check-c-syntax)
 [declaration specifier] (not check-c-syntax)

Enables or disables syntax-checking of embedded C/C++ code fragments. Checking C syntax is the default.


=== constant

 [declaration specifier] (constant SYMBOL ...)

Declares the procedures with the names {{SYMBOL ...}} as constant, that is, as not having any
side effects. This can help the compiler to remove non-side-effecting expressions.


=== export

 [declaration specifier] (export SYMBOL ...)

The opposite of {{hide}}. All given identifiers will be exported and all toplevel variables
not listed will be hidden and not be accessible outside of this compilation unit.


=== emit-external-prototypes-first

 [declaration specifier] (emit-external-prototypes-first)

Emit prototypes for callbacks defined with {{define-external}} before any
other foreign declarations. Equivalent to giving the {{-emit-external-prototypes-first}}
option to the compiler.


=== disable-interrupts

 [declaration specifier] (disable-interrupts)
 [declaration specifier] (not interrupts-enabled)

Disable timer-interrupts checks in the compiled program. Threads can
not be preempted in main- or library-units that contain this declaration.


=== emit-import-library

 [declaration specifier] (emit-import-library MODULENAME | (MODULENAME FILENAME) ...)

Declares that any following definition of a module named {{MODULENAME}} should be written to
an external file (either a specified one or a file named {{"MODULENAME.import.scm"}}).
The compiler option {{-emit-import-library}} may also be used instead.

Note that the import library is only generated if it cannot be found in the current
directory, or if it exists but is not equal to the one that would be generated.


=== inline

 [declaration specifier] (inline)
 [declaration specifier] (not inline)
 [declaration specifier] (inline IDENTIFIER ...)
 [declaration specifier] (not inline IDENTIFIER ...)

If given without an identifier-list, inlining of known procedures is enabled (this is equivalent to the {{-inline}}
compiler option). When an identifier-list is given, then inlining is enabled only for the specified global procedures.
The negated forms {{(not inline)}} and {{(not inline IDENTIFIER)}} disable global inlining, or inlining for
the given global procedures only, respectively.


=== inline-global

  [declaration specifier] (inline-global)
  [declaration specifier] (not inline-global)
  [declaration specifier] (inline-global IDENTIFIER ...)
  [declaration specifier] (not inline-global IDENTIFIER ...)

Declare that then given toplevel procedures (or all) are subject to
cross-module inlining. Potentially inlinable procedures in the current
compilation unit will be written to an external
{{<source-filename>.inline}} file in the current directory. Globally
inlinable procedures from other compilation units referred to via
{{(declare (uses ...))}} or {{require-extension}} are loaded from
{{.inline}} files (if available in the current include path) and inlined
in the current compilation unit.

Enabling global inlining implies {{(declare (inline))}}.


=== inline-limit

 [declaration specifier] (inline-limit THRESHOLD)

Sets the maximum size of procedures which may potentially be inlined. The default threshold is {{20}}.


=== interrupts-enabled

 [declaration specifier] (interrupts-enabled)

Enable timer-interrupts checks in the compiled program (the default).


=== keep-shadowed-macros

 [declaration specifier] (keep-shadowed-macros)

Normally, when a toplevel variable is assigned or defined that has the same name as a macro, the macro-definition
will be removed (in addition to showing a warning). This declaration will disable the removal of the macro.


=== lambda-lift

 [declaration specifier] (lambda-lift)

Enables lambda-lifting (equivalent to the {{-lambda-lift}} option).


=== local

 [declaration specifier] (local)
 [declaration specifier] (local SYMBOL ...)

Declares that the listed (or all) toplevel variables defined in the
current compilation unit are not modified from code outside of this
compilation unit.


=== no-argc-checks

 [declaration specifier] (no-argc-checks)

Disables argument count checking.


=== no-bound-checks

 [declaration specifier] (no-bound-checks)

Disables the bound-checking of toplevel bindings.


=== no-procedure-checks

 [declaration specifier] (no-procedure-checks)

Disables checking of values in operator position for being of procedure type.


=== no-procedure-checks-for-usual-bindings

 [declaration specifier] (no-procedure-checks-for-usual-bindings)

Disables checking of procedures for the default standard- and extended toplevel bindings.


=== no-procedure-checks-for-toplevel-bindings

 [declaration specifier] (no-procedure-checks-for-toplevel-bindings)

Disables checking of procedures for calls to procedures referenced via a toplevel variable
(calls to explicitly named procedures).


=== post-process

 [declaration specifier] (post-process STRING ...)

Arranges for the shell commands {{STRING ...}} to be invoked after the current
file has been translated to C. Any occurrences of the substring {{$@@}} in the
strings given for this declaration will be replaced by the pathname of the currently
compiled file, without the file-extension.
This declaration will only work if the source file is compiled
with the {{csc}} compiler driver.


=== profile

 [declaration specifier] (profile IDENTIFIER ...)

Enable profiling exclusively for given identifiers. Normally the compiler
enables profiling decorations for all globally defined procedures. With
this declaration, profiling can be enabled for selected procedures.


=== number-type
=== fixnum-arithmetic

 [declaration specifier] ([number-type] TYPE)
 [declaration specifier] (fixnum-arithmetic)

Declares that only numbers of the given type are used. {{TYPE}}
may be {{fixnum}} or {{generic}} (which is
the default).


=== compile-syntax

 [declaration specifier] (compile-syntax)

Equivalent to the compiler option of the same name - macros defined in the compiled code are also made available at
runtime.


=== safe-globals

 [declaration specifier] (safe-globals)

Assumes variables assigned in the current compilation unit are always bound and
that any calls to these variables can always be assumed to be calls to proper
procedures.


=== scrutinize

 [declaration specifier] (scrutinize)

Enables scrutiny. This is equivalent to passing the {{-scrutinize}} option to the compiler.


=== standard-bindings

 [declaration specifier] (standard-bindings SYMBOL ...)
 [declaration specifier] (not standard-bindings SYMBOL ...)

Declares that all given standard procedures (or all if no symbols are
specified) are never globally redefined.  If {{not}} is specified,
then all but the given standard bindings are assumed to be never
redefined.


=== type

  [declaration specifier] (type (SYMBOL TYPESPEC) ...)

Declares toplevel procedures to have a specific type for scrutiny. {{SYMBOL}} should name
a toplevel variable and {{TYPESPEC}} should be a type specification, following the syntax
given here:

  TYPESPEC --> *
            |  ( VAL1 ... )
  
  VAL --> (or VAL1 ...)
       |  (struct NAME)
       |  (procedure [NAME] (VAL1 ... [#!optional VALOPT1 ...] [#!rest [VAL]]) . RESULTS)
       |  BASIC
       |  deprecated
  
  BASIC --> * 
         |  string 
         |  symbol 
         |  char 
         |  number 
         |  boolean 
         |  list 
         |  pair 
         |  procedure 
         |  vector 
         |  null 
         |  eof 
         |  port
         |  blob 
         |  pointer
         |  locative
         |  fixnum
         |  float
  
  RESULTS --> * 
           |  (RVAL1 ...)
  
  RVAL --> undefined
        |  noreturn

A type-declaration overrides any previous declaration for the same identifier.


=== extended-bindings

 [declaration specifier] (extended-bindings SYMBOL ...)
 [declaration specifier] (not extended-bindings SYMBOL ...)

Declares that all given non-standard and CHICKEN-specific procedures (or all if no symbols are specified) are never globally redefined.
If {{not}} is specified, then all but the given extended bindings
are assumed to be never redefined.


=== usual-integrations

 [declaration specifier] (usual-integrations SYMBOL ...)
 [declaration specifier] (not usual-integrations SYMBOL ...)

Declares that all given standard and extended bindings (or all if no
symbols are specified) are never globally redefined.  If {{not}}
is specified, then all but the given standard and extended bindings are
assumed to be never redefined. Note that this is the default behaviour,
unless the {{-no-usual-integrations}} option has been given.


=== unit

 [declaration specifier] (unit SYMBOL)

Specify compilation unit-name (if this is a library)


=== unsafe

 [declaration specifier] (unsafe)
 [declaration specifier] (not safe)

Do not generate safety-checks. This is the same as specifying the
{{-unsafe}} option.  Also implies


 (declare (no-bound-checks) (no-procedure-checks) (no-argc-checks))


=== unused

 [declaration specifier] (unused SYMBOL ...)

Disables any warnings when the global variable {{SYMBOL}} is not defined but used, 
or defined but never used and not exported.


=== uses

 [declaration specifier] (uses SYMBOL ...)

Gives a list of used library-units. Before the toplevel-expressions
of the main-module are executed, all used units evaluate their
toplevel-expressions in the order in which they appear in this
declaration. If a library unit A uses another unit B, then B's toplevel
expressions are evaluated before A's.  Furthermore, the used symbols
are registered as features during compile-time, so {{cond-expand}}
knows about them.

---
Previous: [[Modules]]

Next: [[Parameters]]
