3. Compiler usage

Here we describe the essentials to compile a program and a unit. We also describe how to make a stand-alone executable of the compiled program under DOS. For more advanced uses of the compiler, see the section on configuring the compiler, and the Programmers' guide .

The examples in this section suppose that you have a ppc386.cfg which is set up correctly, and which contains at least the path setting for the RTL units. In principle this file is generated by the installation program. You may have to check that it is in the correct place (see section for more information on this).

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 LINUX.

3.1.1 Command line files

The file that you specify on the command line, such as in

ppc386 foo.pp

will be looked for ONLY in the current directory. If you specify a directory in the filename, then the compiler will look in that directory:

ppc386 subdir/foo.pp

will look for foo.pp in the subdirectory subdir of the current directory.

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

3.1.2 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 compiler binary is. (not under LINUX)
3. 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 (See Fu) option. Every occurrence of one of this options will insert a directory to the unit search path. i.e. 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 musrt be replaced with one of the supported targets: GO32V2, LINUX,WIN32, OS2.
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 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

ppc386 -Fu.. -Fuunits foo.pp

will tell the compiler to look for the unit bar in the following places:

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 ppc386.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.

3.1.3 Include files

If you include files in your source with the {$I filename} directive, the compiler will look for it in the following places:

1. It will look in the path specified in the incude 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 See I or See Fi options.

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

{$i ../bar.inc}

Then the following command :

ppc386 -Iincfiles units/foo.pp

will cause the compiler to look in the following directories for bar.inc:

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

3.1.4 Object files

When you link to object files (using the {$L file.o} directive, the compiler will look for this file in the same way as it looks for include 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 See Fo option.

3.1.5 Configuration file

Unless you specify the See n option, the compiler will look for a configuration file ppc386.cfg in the following places:

• Under LINUX
  1. The current directory.
  2. In your home directory, it looks for .ppc386.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.

3.1.6 About long filenames

Free Pascal can handle long filenames under WINDOWS; it will use support for long filenames if it is available.

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.

3.2 Compiling a program

Compiling a program is very simple. Assuming that you have a program source in the file prog.pp, you can compile this with the following command:

  ppc386 [options] prog.pp

The square brackets [ ] indicate that what is between them is optional.

If your program file has the .pp or .pas extension, you can omit this on the command line, e.g. in the previous example you could have typed:

  ppc386 [options] prog

If all went well, the compiler will produce an executable, or, for version 1 of the DOS extender, a file which can be converted to an executable.

Unless you are using DOS and version 1 of the DOS extender, the file you obtained is the executable. You can execute it straight away, you don't need to do anything else. Under version 1 of the DOS extender, additional processing is required. See section on how to create an executable in this case.

You will notice that there is also another file in your directory, with extensions .o. This contains the object file for your program. If you compiled a program, you can delete the object file (.o), but not if you compiled a unit. Then the object file contains the code of the unit, and will be linked in any program that uses the unit you compiled, so you shouldn't remove it.

3.3 Compiling a unit

Compiling a unit is not essentially different from compiling a program. The difference is mainly that the linker isn't called in this case.

To compile a unit in the file foo.pp, just type :

  ppc386  foo

Recall the remark about file extensions in the previous section.

When all went well, you will be left with 2 (two) unit files:

1. foo.ppu This is the file describing the unit you just compiled.
2. foo.o This file contains the actual code of the unit. This file will eventually end up in the executables.

Both files are needed if you plan to use the unit for some programs. So don't delete them. If you want to distribute the unit, you must provide both the .ppu and .o file. One is useless without the other.

Remark: Under LINUX, a unit source file must have a lowercase filename. Since Pascal is case independent, you can specify the names of units in the uses clause in either case. To get a unique filename, the Free Pascal compiler changes the name of the unit to all lowercase when looking for unit files.

The compiler produces lowercase files, so your unit will be found, even if your source file has uppercase letters in it. Only when the compiler tries to recompile the unit, it will not find your source because of the uppercase letters.

3.4 Units, libraries and smartlinking

The Free Pascal compiler supports smartlinking and the creation of libraries. However, the default behaviour is to compile each unit into 1 big object file, which will be linked as a whole into your program.

Not only is it possible to compile a shared library under WINDOWS and LINUX, but also it is possible to take existing units and put them together in 1 static or shared library (using the ppumove tool)

3.5 Creating an executable for GO32V1 and PMODE/DJ targets

The GO32V1 platform is officially no longer supported, so this section is of interest only to people who wish to make go32V1 binaries anyway.

3.5.1 GO32V1

When compiling under DOS, GO32V2 is the default target. However, if you use go32V1 (using the -TGO32V1 switch), the compilation process leaves you with a file which you cannot execute right away. There are 2 things you can do when compiling has finished.

The first thing is to use the DOS extender from D.J. Delorie to execute your program :

  go32 prog

This is fine for testing, but if you want to use a program regularly, it would be easier if you could just type the program name, i.e.

  prog

This can be accomplished by making a DOS executable of your compiled program.

There two ways to create a DOS executable (under DOS only):

1. if the GO32.EXE is already installed on the computers where the program should run, you must only copy a program called STUB.EXE at the begin of the AOUT file. This is accomplished with the AOUT2EXE.EXE program. which comes with the compiler:

   AOUT2EXE PROG
   

   and you get a DOS executable which loads the GO32.EXE automatically. the GO32.EXE executable must be in current directory or be in a directory in the PATH variable.
2. The second way to create a DOS executable is to put GO32.EXE at the beginning of the AOUT file. To do this, at the command prompt, type :

   COPY /B GO32.EXE+PROG PROG.EXE
   

   (assuming Free Pascal created a file called PROG, of course.) This becomes then a stand-alone executable for DOS, which doesn't need the GO32.EXE on the machine where it should run.

3.5.2 PMODE/DJ

You can also use the PMODE/DJ extender to run your Free Pascal applications. To make an executable which works with the PMODE extender, you can simply create an GO32V2 executable (the default), and then convert it to a PMODE executable with the following two extra commands:

1. First, strip the GO32V2 header of the executable:

   EXE2COFF PROG.EXE
   

   (we suppose that PROG.EXE is the program generated by the compilation process.
2. Secondly, add the PMODE stub:

   COPY /B PMODSTUB.EXE+PROG PROG.EXE
   

   If the PMODSTUB.EXE file isn't in your local directory, you need to supply the whole path to it.

That's it. No additional steps are needed to create a PMODE extender executable.

Be aware, though, that the PMODE extender doesn't support virtual memory, so if you're short on memory, you may run unto trouble. Also, officially there is not support for the PMODE/DJ extender. It just happens that the compiler and some of the programs it generates, run under this extender too.

3.6 Reducing the size of your program

When you created your program, it is possible to reduce its size. This is possible, because the compiler leaves a lot of information in the program which, strictly speaking, isn't required for the execution of it. The surplus of information can be removed with a small program called strip. It comes with the GO32 development environment under DOS, and is standard on LINUX machines where you can do development. The usage is simple. Just type

strip prog

On the command line, and the strip program will remove all unnecessary information from your program. This can lead to size reductions of up to 30 %.

Remark: In the WIN32 version, strip is called stripw.

You can use the -Xs switch to let the compiler do this stripping automatically at program compile time (the switch has no effect when compiling units).

Another technique to reduce the size of a program is to use smartlinking. Normally, units (including the system unit) are linked in as a whole. It is however possible to compile units such that the can be smartlinked. This means that only the functions and procedures are linked in your program, leaving out any unnecessary code. This technique is described in full in the programmers guide.