The {$I filename} or {$INCLUDE filename} directive tells the compiler to read further statements from the file filename. The statements read there will be inserted as if they occurred in the current file.
If the file with the given filename exists, it will be included. If no extension is given, the compiler will append the .pp extension to the file and try with that filename. No other extensions are tried.
The filename can be placed between single quotes, they will not be regarded as part of the file’s name. Indeed, if the filename contains a space, then it must be surrounded by single quotes:
{$I 'my file name'}
will try to include the file my file name or my file name.pp.
{$I my file name}
will try to include the file my or my.pp.
If the filename is an asterisk (*) then the compiler will use the unit or program name as filename and try to include that. The following code
unit testi;
interface
{$I *}
implementation
end.
will include the file testi or testi.pp if they exist.
Care should be taken with this mechanism, because the unit name should already match the unit filename, meaning most likely the unit will include itself recursively.
Include files can be nested, but not infinitely deep. The number of files is restricted to the number of file descriptors available to the Free Pascal compiler.
Contrary to Turbo Pascal, include files can cross blocks. I.e. a block can start in one file (with a Begin keyword) and can end in another (with a End keyword). The smallest entity in an include file must be a token, i.e. an identifier, keyword or operator.
The compiler will look for the file to include in the following locations:
It will look in the path specified in the include file name.
It will look in the directory where the current source file is.
it will look in all directories specified in the include file search path.
Directories can be added to the include file search path with the -Fi command line option.