3.1 File searching

Before you start compiling a program or a series of units, it is important to know where the compiler looks for its source files and other files. In this section we discuss this, and we indicate how to influence this.

Remark: The use of slashes (/) and backslashes (\) as directory separators is irrelevant, the compiler will convert to whatever character is used on the current operating system. Examples will be given using slashes, since this avoids problems on UNIX systems (such as LINUX).

Command line files

 fpc foo.pp

 fpc subdir/foo.pp

Under case sensitive file systems (such as LINUX and UNIX), the name of this file is case sensitive, under other operating systems (such as DOS, WINDOWS NT, OS/2) this is not the case.

Unit files

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:

1. It will look in the current directory.
2. It will look in the directory where the source file is being compiled.
3. It will look in the directory where the compiler binary is.
4. It will look in all the directories specified in the unit search path.

You can add a directory to the unit search path with the (-Fu, (see page 5.1)) option. Every occurrence of one of this 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:

1. The contents of the environment variable XXUNITS, where XX must be replaced with one of the supported targets: GO32V2, LINUX,WIN32, OS2, BEOS, FREEBSD, NETBSD.
2. The standard unit directory. This directory is determined from the FPCDIR environment variable. If this variable is not set, then it is defaulted to the following:
   • On LINUX:

     /usr/local/lib/fpc/VERSION  or    /usr/lib/fpc/VERSION

     whichever is found first.
   • On other OSes: the compiler binary directory, with ’../’ appended to it, if it exists.

   After this directory is determined , the following paths are added to the search path:

   1. FPCDIR/units/TARGET
   2. FPCDIR/units/TARGET/rtl

   Here target must be replaced by the name of the target you are compiling for.

You can see what paths the compiler will search by giving the compiler the -vu option.

On systems where filenames to lower-case (such as UNIX and LINUX), the compiler will first convert the filename of a unit to all-lowercase. This is necessary, since Pascal is case-independent, and the statements Uses Unit1; or uses unit1; should have the same effect.

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.

For instance, suppose that the file foo.pp needs the unit bar. Then the command

 fpc -Fu.. -Fuunits foo.pp

1. In the current directory.
2. In the directory where the compile binary is (not under LINUX).
3. In the parent directory of the current directory.
4. In the subdirectory units of the current directory
5. In the standard unit directory.

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.

Include files

1. It will look in the path specified in the include file name.
2. It will look in the directory where the current source file is.
3. it will look in all directories specified in the include file search path.

You can add files to the include file search path with the -I, (see page 5.1) or -Fi, (see page 5.1) options.

As an example, consider the following include statement in a file units/foo.pp:

 
 {$i ../bar.inc}
 

 fpc -Iincfiles units/foo.pp

1. the parent directory of the current directory
2. the units subdirectory of the current directory
3. the incfiles directory of the current directory.

Object files

1. It will look in the path specified in the object file name.
2. It will look in the directory where the current source file is.
3. it will look in all directories specified in the object file search path.

You can add files to the object file search path with the -Fo, (see page 5.1) option.

Configuration file

Starting from version 1.0.6 of the compiler, usage of the file ppc386.cfg is considered deprecated. The file should now be called fpc.cfg and will work for all processor targets. For compatibility, fpc.cfg will be searched first, and if not found, the file ppc386.cfg will be used.

Unless you specify the -n, (see page 5.1) option, the compiler will look for a configuration file fpc.cfg in the following places:

• Under UNIX (such as LINUX)
  1. The current directory.
  2. In your home directory, it looks for .fpc.cfg.
  3. The directory specified in the environment variable PPC_CONFIG_PATH, and if it’s not set under /etc.
• Under all other OSes:
  1. The current directory.
  2. If it is set, the directory specified in the environment variable. PPC_CONFIG_PATH.
  3. The directory where the compiler is.

About long filenames

If no support for long filenames is present, it will truncate unit names to 8 characters.

It is not recommended to put units in directories that contain spaces in their names, since the linker doesn’t understand such filenames.