When you compile a unit or program that needs other units, the compiler will look for compiled versions of these units in the following way:
You can add a directory to the unit search path with the (-Fu (see page 107)) option. Every occurrence of one of these options will insert a directory to the unit search path. i.e. the last path on the command line will be searched first.
The compiler adds several paths to the unit search path:
whichever is found first.
This is assuming the compiler was installed in the directory
After this directory is determined, the following paths are added to the search path:
Here target must be replaced by the name of the target you are compiling for: this is a combination of CPU and OS, so for instance
or, when cross-compiling
The -Fu option accepts a single * wildcard, which will be replaced by all directories found on that location, but not the location itself. For example, given the directories
will have the same effect as
since both the rtl and fcl directories contain further units/i386-linux subdirectories. The packages directory will not be added, since it doesn’t contain a units/i386-linux subdirectory.
The following command
will match any directory below the units/i386-linux directory, but will not match the units/i386-linux directory itself, so you should add it manually if you want the compiler to look for files in this directory as well:
Note that (for optimization) the compiler will drop any non-existing paths from the search path, i.e. the existence of the path (after wildcard and environment variable expansion) will be tested.
You can see what paths the compiler will search by giving the compiler the -vu option.
Note that unit file paths specified in a config file will be added at the end, while paths specified on the command-line are added at the beginning.
Imagine the following command-line:
Where the file cfg has the following contents:
This will result in the following search path
Reverting the order of the files on the command-line :
Moving the position of @cfg will not change the path:
On systems where filenames are case sensitive (such as unix and linux), the compiler will :
This is necessary, since Pascal is case-independent, and the statements Uses Unit1; or uses unit1; should have the same effect.
It will do this first with the extension .ppu (the compiled unit), .pp and then with the extension .pas.
For instance, suppose that the file foo.pp needs the unit bar. Then the command
will tell the compiler to look for the unit bar in the following places:
Also, unit names that are longer than 8 characters will first be looked for with their full length. If the unit is not found with this name, the name will be truncated to 8 characters, and the compiler will look again in the same directories, but with the truncated name.
If the compiler finds the unit it needs, it will look for the source file of this unit in the same directory where it found the unit. If it finds the source of the unit, then it will compare the file times. If the source file was modified more recent than the unit file, the compiler will attempt to recompile the unit with this source file.
If the compiler doesn’t find a compiled version of the unit, or when the -B option is specified, then the compiler will look in the same manner for the unit source file, and attempt to recompile it.
It is recommended to set the unit search path in the configuration file fpc.cfg. If you do this, you don’t need to specify the unit search path on the command line every time you want to compile something.