$include

From Free Pascal wiki

Deutsch (de) English (en)
The compiler directive {$include} is used to:

  • read and parse a file, virtually inserting its contents at the location the directive was encountered,
  • insert compiler information, or
  • insert the value of an environment variable.

The {$I}, case-sensitive, is shorthand for the same directive.

Sourcing files

Further tokens can be read from a file using the {$include} directive to virtually substitute the file’s contents for the directive. A file to be substituted for the directive is specified like this {$include magic.pas}. The suffix .pas or .pp can be omitted.

The special file name * will attempt to include a file of the current module’s name.

Files are searched for in the following order:

  1. at the path specified;
  2. in the directory containing the current source file;
  3. in all include file paths. (-Fi or -I compiler parameters.)

Not finding a specified file constitutes a fatal error.

Insertion of certain information

The compiler can be instructed to insert certain information at a specific spot. For that, a word is surrounded by % like in {$include %internalVariable%}.

This directive always inserts strings (except {$include %lineNum%}). A set of predefined variables are consulted first. If there is no predefined variable of a given name, the value of the environment variable of the given name is tried to be retrieved. If this process fails, an empty string is inserted in order to provide a consistent behavior.

The set of predefined variables are (case-insensitive):

  • location information
    • {$include %currentRoutine%} expands to the current routine’s name. (available since FPC trunk revision 30873; FPC 3.2.0)
    • {$include %file%} expands to the file’s name the directive is found in.
    • {$include %line%} expands to the line number (starting at 1) where the directive is found at.
    • {$include %lineNum%} is the same as {$I %line%} but of an integer type.
  • target information
    • {$include %FPCTargetCPU%} expands to the target’s CPU name, e. g. 'x86_64'.
    • {$include %FPCTargetOS%} expands to the target’s OS name, e. g. 'Linux'.
  • compiler information
    • {$include %FPCVersion%} expands to the version number of the used FPC, e. g. '3.0.4'.
  • regarding date of invocation of the compiler
    • {$include %date%} expands to a string of the form 'YYYY/mm/dd', e. g. '2020/08/24'.
    • {$include %dateYear%} expands to '2020'. (Available since FPC trunk revision 38329)
    • {$include %dateMonth%} expands to '08'. (Available since FPC trunk revision 38329)
    • {$include %dateDay%} expands to '24'. (Available since FPC trunk revision 38329)
    • {$include %time%} expands to a string of the form 'HH:MM:SS', e. g. '11:39:42'.
    • {$include %timeHour%} expands to '11'. (Available since FPC trunk revision 38329)
    • {$include %timeMinute%} expands to the minute part of {$I %time%}. (Available since FPC trunk revision 38329)
    • {$include %timeSecond%} expands to the seconds part of {$I %time%}. (Available since FPC trunk revision 38329)

See also