Subsections

- 1 Using the command-line options
  - 1 General options
  - 2 Options for getting feedback
  - 3 Options concerning files and directories
  - 4 Options controlling the kind of output.
  - 5 Options concerning the sources (language options)
- 2 Using the configuration file
  - 1 #IFDEF
  - 2 #IFNDEF
  - 3 #ELSE
  - 4 #ENDIF
  - 5 #DEFINE
  - 6 #UNDEF
  - 7 #WRITE
  - 8 #INCLUDE
  - 9 #SECTION
- 3 Variable substitution in paths

#
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: fpc.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.

# 1 Using the command-line options

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

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

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

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

##
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 by the 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.
-CR
  Generate checks when calling methods to verify if the virtual method table for that object is valid.
-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. This must be used with the `-gh` command-line option. When this options is enabled, it will verify that all pointer accesses are within the heap.
-kxxx
  pass `xxx` to the linker.
-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. This will define the symbol `FPC_PROFILE`, which can be used in conditional defines.
-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.
  - SUNOS : SunOS/Solaris.
  - BEOS : BeOS.
-uxxx
  Undefine the symbol `xxx`. This is the opposite of the `-d` option.
-Ur
  Generate release unit files. These files will not be recompiled, even when the sources are available. This is useful when making release distributions. This also overrides the `-B` option for release mode units.
-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 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 (`objfpc` mode). This is different from `-Sd` (Delphi mode) because some Free Pascal constructs are still available.
-Sa
  Include assert statements in compiled code. Omitting this option will cause assert statements to be ignored.
-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.

#
2 Using the configuration file

Using the configuration file fpc.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. All the default defines used to compile source code are also defined while processing the configuration file. For example, if the target compiler is an intel 80x86 compatile linux platform, both `cpu86` and `linux` will be defined while interpreting the configuration file. For the possible default defines when compiling, consult Appendix G of the Programmers' guide.

What follows is a description of the different directives.

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

## 2 #IFNDEF

Syntax:

    #IFNDEF name

Lines following `#IFNDEF` 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.

## 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` or `#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.5/linuxunits
    #ELSE
    -Fu/usr/lib/fpc/0.99.6/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.

## 4 #ENDIF

Syntax:

    #ENDIF

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

## 5 #DEFINE

Syntax:

    #DEFINE name

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

## 6 #UNDEF

Syntax:

    #UNDEF name

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

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

## 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/fpc.cfg
    #ELSE
      #IFDEF GO32V2
        #INCLUDE c:\pp\bin\fpc.cfg
      #ENDIF
    #ENDIF

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

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

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