Subsections


5. Compiler configuration

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

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 :

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:
-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:


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