5. Compiler configuration

The output of the compiler can be controlled in many ways. This can be done essentially in two distinct ways:

Using command-line options.
Using the configuration file: ppc386.cfg.

The compiler first reads the configuration file. Only then the command line options are checked. This creates the possibility to set some basic options in the configuration file, and at the same time you can still set some specific options when compiling some unit or program. First we list the command line options, and then we explain how to specify the command line options in the configuration file. When reading this, keep in mind that the options are case sensitive. While this is customary for LINUX, it isn't under DOS.

5.1 Using the command-line options

The available options for version 0.99.10 of the compiler are listed by category (see appendix A for a listing as generated by the compiler):

5.1.1 General options

-h

if you specify this option, the compiler outputs a list of all options, and exits after that.

-?

idem as -h, waiting after every screenfull for the enter key.

-i

This option tells the compiler to print the copyright information. You can give it an option, as -ixxx where xxx can be one of the following:

D: : Returns the compiler date.
V: : Returns the compiler version.
SO: : Returns the compiler OS.
SP: : Returns the compiler processor.
TO: : Returns the target OS.
TP: : Returns the target Processor.

-l

This option tells the compiler to print the Free Pascal logo on standard output. It also gives you the Free Pascal version number.

-n

Tells the compiler not to read default the configuration file. You can still pass a configuration file with the @ option.

5.1.2 Options for getting feedback

-vxxx

Be verbose. xxx is a combination of the following :

e : Tells the compiler to show only errors. This option is on by default.
i : Tells the compiler to show some general information.
w : Tells the compiler to issue warnings.
n : Tells the compiler to issue notes.
h : Tells the compiler to issue hints.
l : Tells the compiler to show the line numbers as it processes a file. Numbers are shown per 100.
u : Tells the compiler to print information on the units it loads.
t : Tells the compiler to print the names of the files it tries to open.
p : Tells the compiler to print the names of procedures and functions as it is processing them.
c : Tells the compiler to warn you when it processes a conditional.
m : Tells the compiler to write which macros are defined.
d : Tells the compiler to write other debugging info.
a : Tells the compiler to write all possible info. (this is the same as specifying all options)
0 : Tells the compiler to write no messages. This is useful when you want to override the default setting in the configuration file.
b : Tells the compiler to show all procedure declarations if an overloaded function error occurs.
x : Tells the compiler to output some executable info (for Win32 platform only).
r : Rhide/GCC compatibility mode: formats the errors differently, so they are understood by RHIDE.

5.1.3 Options concerning files and directories

-exxx: xxx specifies the directory where the compiler can find the executables as (the assembler) and ld (the linker).
-FD: same as -e.
-Fexxx: This option tells the compiler to write errors, etc. to the file named xxx.
-FExxx: tells the compiler to write the executable and units in directory xxx instead of th current directory.
-Fixxx: Adds xxx to the include file search path.
-Flxxx: Adds xxx to the library searching path, and is passed to the linker.
-FLxxx: (LINUX only) Tells the compiler to use xxx as the dynamic linker. Default this is /lib/ld-linux.so.2, or /Hlib/ld-linux.so.1, depending on which one is found first.
-Foxxx: Adds xxx to the object file search path. This path is used when looking for files that need to be linked in.
-Frxxx: xxx specifies the file which contain the compiler messages. Default the compiler has built-in messages. Specifying this option will override the default messages.
-Fuxxx: Add xxx to the unit search path. Units are first searched in the current directory. If they are not found there then the compiler searches them in the unit path. You must always supply the path to the system unit.
-FUxxx: Tells the compiler to write units in directory xxx instead of the current directory. It overrides the -FE option.
-Ixxx: Add xxx to the include file search path. This option has the same effect as -Fi.
-P: uses pipes instead of files when assembling. This may speed up the compiler on OS/2 and LINUX. Only with assemblers (such as GNU as) that support piping...

5.1.4 Options controlling the kind of output.

for more information on these options, see also Programmers' guide

-a

Tells the compiler not to delete the assembler files it generates (not when using the internal assembler). This also counts for the (possibly) generated batch script.

-al

Tells the compiler to include the sourcecode lines in the assembler file as comments.

-ar

tells the compiler to list register allocation and release info in the assembler file. This is primarily intended for debugging the code generated bythe compiler.

-at

tells the compiler to list information about temporary allocations and deallocations in the assembler file.

-Axxx

specifies what kind of assembler should be generated . Here xxx is one of the following :

as: assemble using GNU as.
asaout: assemble using GNU as for aout (Go32v1).
nasmcoff: coff (Go32v2) file using Nasm.
nasmelf: elf32 (Linux) file using Nasm.
nasmobj: object file using Nasm.
masm: object file using Masm (Microsoft).
tasm: object file using Tasm (Borland).
coff: coff object file (Go32v2) using the internal binary object writer.
pecoff: pecoff object file (Win32) using the internal binary object writer.

-B

tells the compiler to re-compile all used units, even if the unit sources didn't change since the last compilation.

-b

tells the compiler to generate browser info. This information can be used by an Integrated Development Environment (IDE) to provide information on classes, objects, procedures, types and variables in a unit.

-bl

is the same as -b but also generates information about local variables, types and procedures.

-CD

Create a dynamic library. This is used to transform units into dynamically linkable libraries on LINUX.

-Chxxx

Reserves xxx bytes heap. xxx should be between 1024 and 67107840.

-Ci

Generate Input/Output checking code. In case some input/output code of your program returns an error status, the program will exit with a run-time error. Which error is generated depends on the I/O error.

-Cn

Omit the linking stage.

-Co

Generate Integer overflow checking code. In case of integer errors, a run-time error will be generated by your program.

-Cr

Generate Range checking code. In case your program acesses an array element with an invalid index, or if it increases an enumerated type beyond it's scope, a run-time error will be generated.

-Csxxx

Set stack size to xxx.

-Ct

generate stack checking code. In case your program performs a faulty stack operation, a run-rime error will be generated.

-CX

Create a smartlinked unit when writing a unit. smartlinking will only link in the code parts that are actually needed by the program. All unused code is left out. This can lead to substantially smaller binaries.

-dxxx

Define the symbol name xxx. This can be used to conditionally compile parts of your code.

-E Same as -Cn.

-g

Generate debugging information for debugging with gdb

-gg

idem as -g.

-gd

generate debugging info for dbx.

-gh

use the heaptrc unit (see Unit reference).

-gc

generate checks for pointers.

-Oxxx

optimize the compiler's output; xxx can have one of the following values :

g

optimize for size, try to generate smaller code.

G

optimize for time, try to generate faster code (default).

r

keep certain variables in registers (experimental, use with caution).

u

Uncertain optimizations

1

Level 1 optimizations (quick optimizations).

2

Level 2 optimizations (-O1 plus some slower optimizations).

3

Level 3 optimizations (-O2 plus -Ou).

Pn

(Intel only) Specify processor: n can be one of

1: optimize for 386/486
2: optimize for Pentium/PentiumMMX (tm)
3: optimizations for PentiumPro/PII/Cyrix 6x86/K6 (tm)

The exact effect of these effects can be found in the Programmers' guide.

-oxxx

Tells the compiler to use xxx as the name of the output file (executable). Only with programs.

-pg

Generate profiler code for gprof.

-s

Tells the compiler not to call the assembler and linker. Instead, the compiler writes a script, PPAS.BAT under DOS, or ppas.sh under LINUX, which can then be executed to produce an executable. This can be used to speed up the compiling process or to debug the compiler's output.

-Txxx

Specifies the target operating system. xxx can be one of the following:

GO32V1 : DOS and version 1 of the DJ DELORIE extender (no longer maintained).
GO32V2 : DOS and version 2 of the DJ DELORIE extender.
LINUX : LINUX.
OS2 : OS/2 (2.x) using the EMX extender.
WIN32 : WINDOWS 32 bit.

-uxxx

undefine the symbol xxx. This is the opposite of the -d option.

-uxxx

Undefine symbol xxx.

-Xx

executable options. This tells the compiler what kind of executable should be generated. the parameter x can be one of the following:

c : (LINUX only) Link with the C library. You should only use this when you start to port Free Pascal to another operating system.
D : Link with dynamic libraries (defines the FPC_LINK_DYNAMIC symbol)
s : Strip the symbols from the executable.
S : Link with static units (defines the FPC_LINK_STATIC symbol)
X : Link with smartlinked units (defines the FPC_LINK_SMART symbol)

5.1.5 Options concerning the sources (language options)

for more information on these options, see also Programmers' guide

-Rxxx

Specifies what kind of assembler you use in your asm assembler code blocks. Here xxx is one of the following:

att: asm blocks contain AT&T-style assembler. This is the default style.
intel: asm blocks contain Intel-style assembler.
direct: asm blocks should be copied as-is in the assembler, only replacing certain variables. file.

-S2

Switch on Delphi 2 extensions. This is different from -Sd because some Free Pascal constructs are still available to you.

-Sc

Support C-style operators, i.e. *=, +=, /= and -=.

-Sd

Tells the compiler to be Delphi compatible. This is more strict than the -S2 option, since some fpc extensions are switched off.

-SeN

The compiler stops after the N-th error. Normally, the compiler tries to continue compiling after an error, until 50 errors are reached, or a fatal error is reached, and then it stops. With this switch, the compiler will stop after the N-th error (if N is omitted, a default of 1 is assumed).

-Sg

Support the label and goto commands. By default these are not supported. You must also specify this option if you use labels in assembler statements. (if you use the AT&T style assember)

-Sh

Use ansistrings by default for strings. If this keyword is specified, the compiler will interpret the string keyword as a ansistring. Otherwise it is supposed to be a short strings (TP style).

-Si

Support C++ style INLINE.

-Sm

Support C-style macros.

-So

Try to be Borland TP 7.0 compatible (no function overloading etc.).

-Sp

Try to be gpc (GNU pascal compiler) compatible.

-Ss

The name of constructors must be init, and the name of destructors should be done.

-St

Allow the static keyword in objects.

-Un

Do not check the unit name. Normally, the unit name is the same as the filename. This option allows both to be different.

-Us

Compile a system unit. This option causes the compiler to define only some very basic types.

5.2 Using the configuration file

Using the configuration file ppc386.cfg is an alternative to command line options. When a configuration file is found, it is read, and the lines in it are treated like you typed them on the command line. They are treated before the options that you type on the command line.

You can specify comments in the configuration file with the # sign. Everything from the # on will be ignored.

The algorithm to determine which file is used as a configuration file is decribed in on page .

When the compiler has finished reading the configuration file, it continues to treat the command line options.

One of the command-line options allows you to specify a second configuration file: Specifying @foo on the command line will open file foo, and read further options from there. When the compiler has finished reading this file, it continues to process the command line.

The configuration file allows some kind of preprocessing. It understands the following directives, which you should place on the first column of a line :

#IFDEF
#IFNDEF
#ELSE
#ENDIF
#DEFINE
#UNDEF
#WRITE
#INCLUDE
#SECTION

They work the same way as their {$...} counterparts in Pascal.

What follows is a description of the different directives.

5.2.1 #IFDEF

Syntax:

#IFDEF name

Lines following #IFDEF are skipped read if the keyword name following it is not defined.

They are read until the keywords #ELSE or #ENDIF are encountered, after which normal processing is resumed.

Example :

#IFDEF VER0_99_5
-Fu/usr/lib/fpc/0.99.5/linuxunits
#ENDIF

In the above example, /usr/lib/fpc/0.99.5/linuxunits will be added to the path if you're compiling with version 0.99.5 of the compiler.

5.2.2 #IFNDEF

Syntax:

#IFNDEF name

Lines following #IFDEF are skipped read if the keyword name following it is defined.

They are read until the keywords #ELSE or #ENDIF are encountered, after which normal processing is resumed.

Example :

#IFNDEF VER0_99_5
-Fu/usr/lib/fpc/0.99.6/linuxunits
#ENDIF

In the above example, /usr/lib/fpc/0.99.6/linuxunits will be added to the path if you're NOT compiling with version 0.99.5 of the compiler.

5.2.3 #ELSE

Syntax:

#ELSE

#ELSE can be specified after a #IFDEF or #IFNDEF directive as an alternative. Lines following #ELSE are skipped read if the preceding #IFDEF #IFNDEF was accepted.

They are skipped until the keyword #ENDIF is encountered, after which normal processing is resumed.

Example :

#IFDEF VER0_99_5
-Fu/usr/lib/fpc/0.99.6/linuxunits
#ELSE
-Fu/usr/lib/fpc/0.99.5/linuxunits
#ENDIF

In the above example, /usr/lib/fpc/0.99.5/linuxunits will be added to the path if you're compiling with version 0.99.5 of the compiler, otherwise /usr/lib/fpc/0.99.6/linuxunits will be added to the path.

5.2.4 #ENDIF

Syntax:

#ENDIF

#ENDIF marks the end of a block that started with #IF(N)DEF, possibly with an #ELSE between it.

5.2.5 #DEFINE

Syntax:

#DEFINE name

#DEFINE defines a new keyword. This has the same effect as a -dname command-line option.

5.2.6 #UNDEF

Syntax:

#UNDEF name

#UNDEF un-defines a keyword if it existed. This has the same effect as a -uname command-line option.

5.2.7 #WRITE

Syntax:

#WRITE Message Text

#WRITE writes Message Text to the screen. This can be useful to display warnings if certain options are set.

Example:

#IFDEF DEBUG
#WRITE Setting debugging ON...
-g
#ENDIF

if DEBUG is defined, this will produce a line

Setting debugging ON...

and will then switch on debugging information in the compiler.

5.2.8 #INCLUDE

Syntax:

#INCLUDE filename

#INCLUDE instructs the compiler to read the contents of filename before continuing to process options in the current file.

This can be useful if you want to have a particular configuration file for a project (or, under LINUX, in your home directory), but still want to have the global options that are set in a global configuration file.

Example:

#IFDEF LINUX
  #INCLUDE /etc/ppc386.cfg
#ELSE
  #IFDEF GO32V2
    #INCLUDE c:\pp\bin\ppc386.cfg
  #ENDIF
#ENDIF

This will include /etc/ppc386.cfg if you're on a linux machine, and will include c:\pp\bin\ppc386.cfg on a dos machine.

5.2.9 #SECTION

Syntax:

#SECTION name

The #SECTION directive acts as a #IFDEF directive, only it doesn't require an #ENDIF directive. the special name COMMON always exists, i.e. lines following #SECTION COMMON are always read.

5.3 Variable substitution in paths

To avoid having to edit your configuration files too often, the compiler allows you to specify the following variables in the paths that you feed to the compiler:

FPCVER: is replaced by the compiler's full version string.
FPCDATE: is replaced by the compiler's date.
FPCTARGET: is replaced by the compiler's target CPU (deprecated).
FPCCPU: is also replaced by the compiler's target CPU.
TARGET: is replaced by the compiler's target OS.(deprecated)
FPCOS: is replaced by the compiler's target OS.

To have these variables subsituted, just insert them with a $ prepended, as follows:

-Fu/usr/lib/fpc/$FPCVER/rtl/$FPCOS

This is equivalent to

-Fu/usr/lib/fpc/0.99.12a/rtl/linux

If the compiler version is 0.99.12a and the target os is linux.

These replacemens are valid on the command-line and also in the configuration file.

On the linux command-line, you must be careful to escape the $ since otherwise the shell will expand the variable for you, which may have undesired effects.

root
2000-12-20