$include: what changed
Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | 1 | The [[Compiler directive|compiler directive]] `{$include}` is used to: | |
| 2 | 2 | ||
| 3 | 3 | - read and parse a file, virtually inserting its contents at the location the directive was encountered, | |
| 4 | 4 | - insert compiler information, or | |
| 5 | 5 | - insert the value of an environment variable. | |
| 6 | 6 | ||
| 7 | 7 | The `{$I}` directive, case-*sensitive*, is shorthand for the same directive. | |
| 8 | 8 | ||
| 9 | 9 | ## Sourcing files | |
| 10 | 10 | ||
| 11 | 11 | 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}`. | |
| 12 | 12 | ||
| 13 | 13 | Files are searched for in the following order: | |
| 14 | 14 | ||
| 15 | 15 | 1. at the path specified; | |
| 16 | 16 | 2. in the directory containing the current source file; | |
| 17 | 17 | 3. in all include file paths. (`-Fi` or `-I` compiler parameters.) | |
| 18 | 18 | ||
| 19 | 19 | When specifying a file name, a file type hint suffix can be omitted. If you omit a suffix, the following suffixes are tried out: | |
| 20 | 20 | ||
| 21 | 21 | 1. *none*, meaning the exact name as specified (*without* any suffix) | |
| 22 | 22 | 2. `.inc` | |
| 23 | 23 | 3. `.pp` | |
| 24 | 24 | 4. `.pas` | |
| 25 | 25 | 5. (trailing dot stripped) | |
| 26 | 26 | ||
| 27 | 27 | This strategy applies to every directory in the search path as described above, and the first match is taken. | |
| 28 | 28 | ||
| 29 | 29 | For Delphi compatibility, the special file name [[Asterisk|*]] will attempt to include a file of the current file’s base name. The suffix is supplemented as described above. You can, however, specify a (different) suffix too: `{$include *.dat}` will look for a file bearing same name as the source file, but the suffix (if applicable) will be replaced by (or augmented with) `.dat`. The suffix is the *last* component of a file name separated by a [[period|. (dot)]] (thus `{$I *.foo.bar.dat}` is effectively the same as `{$I *.dat}`). Note, if you are reading a file via a symbolic link, the supplied *unresolved* name is the source code file’s name, *not* the target file name. | |
| 30 | 30 | ||
| 31 | 31 | If a file name contains blank characters, the file name needs to be surrounded by [[&|' (typewriter quotes)]]. If a file name starts with a percent sign or asterisk, you must either use straight quotes as in the case of blanks, or specify an absolute or relative path like `{$I ./%wage.pas}` (on UNIX-like platforms `./` denotes the “current directory”). | |
| 32 | 32 | ||
| 33 | 33 | Not finding a specified file constitutes a [[compile-time error|fatal error]]. | |
| 34 | 34 | ||
| 35 | 35 | ## Insertion of certain information | |
| 36 | 36 | ||
| 37 | 37 | The compiler can be instructed to insert certain information at a specific spot. For that, a word is surrounded by [[Percent sign|%]] like in `{$include %internalVariable%}`. | |
| 38 | 38 | ||
| 39 | 39 | This directive always inserts [[String|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. | |
| 40 | 40 | ||
| 41 | 41 | The set of predefined variables are (case-insensitive): | |
| 42 | 42 | ||
| 43 | 43 | - location information | |
| 44 | 44 | - `{$include %currentRoutine%}` expands to the current routine’s name. (available since FPC trunk revision 30873; FPC 3.2.0) | |
| 45 | 45 | - `{$include %file%}` expands to the file’s name the directive is found in. | |
| 46 | 46 | - `{$include %line%}` expands to the line number (starting at 1) where the directive is found at. | |
| 47 | 47 | - `{$include %lineNum%}` is the same as `{$I %line%}` but of an integer type. | |
| 48 | 48 | - [[Free Pascal supported targets|target]] information | |
| 49 | 49 | - `{$include %FPCTargetCPU%}` expands to the target’s CPU name, e. g. `'x86_64'`. | |
| 50 | 50 | - `{$include %FPCTargetOS%}` expands to the target’s [[Operating System|OS]] name, e. g. [[Linux|'Linux']]. | |
| 51 | 51 | - compiler information | |
| 52 | 52 | - `{$include %FPCVersion%}` expands to the version number of the used [[FPC]], e. g. `'3.0.4'`. | |
| 53 | 53 | - regarding time/date of processing the directive | |
| 54 | - | ||
| 55 | - | ||
| 56 | - | ||
| 57 | - | ||
| 58 | - | ||
| 59 | - | ||
| 54 | + | - `{$include %date%}` expands to a string of the form `'YYYY/mm/dd'`, e. g. `'//'`. | |
| 55 | + | - `{$include %dateYear%}` expands to `''`. (Available since FPC trunk revision 38329) | |
| 56 | + | - `{$include %dateMonth%}` expands to `''`. (Available since FPC trunk revision 38329) | |
| 57 | + | - `{$include %dateDay%}` expands to `''`. (Available since FPC trunk revision 38329) | |
| 58 | + | - `{$include %time%}` expands to a string of the form `'HH:MM:SS'`, e. g. `':42'`. | |
| 59 | + | - `{$include %timeHour%}` expands to `''`. (Available since FPC trunk revision 38329) | |
| 60 | 60 | - `{$include %timeMinute%}` expands to the minute part of `{$I %time%}`. (Available since FPC trunk revision 38329) | |
| 61 | 61 | - `{$include %timeSecond%}` expands to the seconds part of `{$I %time%}`. (Available since FPC trunk revision 38329) | |
| 62 | 62 | ||
| 63 | 63 | Historical remark: Previously *some* information like `{$include %FPCVersion%}` and `{$include %date%}` could be included with the long deprecated utility [`fpcsubst`](https://gitlab.com/freepascal.org/fpc/source/-/tree/3.3.1/utils/fpcsubst.pp), a macro preprocessor program. | |
| 64 | 64 | ||
| 65 | 65 | ## See also | |
| 66 | 66 | ||
| 67 | 67 | - [§ “include file”](https://www.freepascal.org/docs-html/prog/progsu40.html) and [§ “include compiler info”](https://www.freepascal.org/docs-html/prog/progsu41.html) in the *Free Pascal programmer’s guide* | |
| 68 | 68 | ||
| 69 | 69 | --- | |
| 70 | 70 | *From the Free Pascal wiki, page "$include", as it stood on 2022-10-04 after a change by Kai Burghardt, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* |