Using the command line options

The available options for the current version of the compiler are listed by category. Also, see chapter Alphabetical listing of command line options for a listing as generated by the current compiler.

General options

-h

Print a list of all options and exit.

-?

Same as -h, waiting after each screenfull for the enter key.

-i

Print copyright and other information. You can supply a qualifier, as -ixxx where xxx can be one of the following:

D

: Returns the compiler date.

V

: Returns the short compiler version.

W

: Return full compiler version.

SO

: Returns the compiler OS.

SP

: Returns the compiler processor.

TO

: Returns the target OS.

TP

: Returns the target processor.

a

: Returns a list of supported ABI targets.

c

: Returns a list of supported CPU instruction sets.

f

: Returns a list of supported FPU instruction sets.

i

: Returns a list of supported inline assembler modes.

o

: Returns a list of supported optimizations.

r

: Returns a list of recognized compiler and RTL features.

t

: Returns a list of supported targets.

u

: Returns a list of supported microcontroller types.

w

: Returns a list of supported whole program optimizations.

-l

Print a line stating which program this is and its version.

-n

Ignore the default configuration file. You can still pass a configuration file with the @ option.

-VNNN

Set the version number to NNN (appends -NNN to the binary name).

Options for getting feedback

-vxxx

Be verbose. xxx is a combination of the following :

• e : Show errors. This option is on by default.

• w : Issue warnings.

• n : Issue notes.

• h : Issue hints.

• i : Issue informational messages.

• l : Report number of lines processed (every 100 lines).

• u : Show information on units being loaded.

• t : Show names of files being opened.

• p : Write parse tree (tree.log)

• q : Show message numbers.

• c : Notify on each conditional being processed.

• mxxx : xxx is a comma-separated list of messages numbers which should not be shown. This option can be specified multiple times.

• d : Show additional debugging information.

• 0 : No messages. This is useful for overriding the default setting in the configuration file.

• x : Show information about the executable (Win32 platform only).

• r : Format errors in RHIDE/GCC compatibility mode.

• a : Show all possible information. (this is the same as specifying all options)

• b : Tells the compiler to write filenames using the full path.

• v : Write copious debugging information to file fpcdebug.txt.

• s : Write timestamps. Mainly for the compiler developers.

• z Write compiler messages to standard error instead of standard output.

The difference between an error/fatal error/hint/warning/note is the severity:

Fatal

The compiler encountered an error, and can no longer continue compiling. It will stop at once.

Error

The compiler encountered an error, but can continue to compile (at most till the end of the current unit).

Warning

if there is a warning, it means there is probably an error, i.e. something may be wrong in your code.

Hint

Is issued if the compiler thinks the code could be better, but there is no suspicion of error.

Note

Is some noteworthy information, but again there is no error.

The difference between hints and notes is not really very clear. Both can be ignored without too much risk, but warnings should always be checked.

Options concerning files and directories

-exxx

Specify xxx as the directory containing the executables for the programs as (the assembler) and ld (the linker).

-FaXYZ

load units XYZ after the system unit, but before any other unit is loaded. XYZ is a comma-separated list of unit names. This can only be used for programs, and has the same effect as if XYZ were inserted as the first item in the program’s uses clause.

-FcXXX

Set the input codepage to XXX. Experimental.

-FCxxx

Set the RC compiler (resource compiler) binary name to xxx.

-Fd

Disable the compiler’s internal directory cache. By default, the compiler caches the names of all files in a directory as soon as it looks for a single file in said directory. This ensures that the correct case of all file names is used in the debug information. It also allows to create compiled files with the correct casing when compiling on a case-preserving file systems under an OS that also support case-sensitive file systems. Lastly, it can also increase performance. This feature can however cause severe slowdowns on networked file systems, especially when compiling trivial programs in directories containing many files, and such slowdowns can be addressed by disabling the cache using this switch.

-FD

Same as -e.

-Fexxx

Write errors, etc. to the file named xxx.

-FExxx

Write the executable and units to directory xxx instead of the current directory. If this option contains a path component and is followed by an option ), then the -o path will override the -FE path setting.

-Ffxxx

Add xxx to the framework path (only for Darwin).

-Fg

?

-Fixxx

Add xxx to the include file search path.

-Flxxx

Add xxx to the library search path. (This is also passed to the linker.)

-FLxxx

(Linuxonly) Use xxx as the dynamic linker. The default is /lib/ld-linux.so.2, or /lib/ld-linux.so.1, depending on which one is found first.

-Fmxxx

Load the unicode conversion table from file x.txt in the directory where the compiler is located. Only used when -Fc is also in effect.

-FMxxx

Set the directory where to search for unicode binary files to xxx.

-Foxxx

Add xxx to the object file search path. This path is used when looking for files that need to be linked in.

-Frxxx

Specify xxx as the file which contain the compiler messages. This will override the compiler’s built-in default messages, which are in English.

-FRxxx

set the resource (.res) linker to xxx.

-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. The xxx path can contain a single wildcard (*) which will be expanded to all possible directory names found at that location. Note that the location itself is not included in the list. See section Compiler usage for more information about this option.

-FUxxx

Write units to 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.

-FWxxx

store generated Whole Program Optimization information in file xxx.

-Fwxxx

Read Whole Program Optimization information (as saved using -FWxxx) from file xxx.

Options controlling the kind of output.

For more information on these options, see Programmer’s Guide.

-a

Do not delete the assembler files (not applicable when using the internal assembler). This also applies to the (possibly) generated batch script.

-al

Include the source code lines in the assembler file as comments.

-an

Write node information in the assembler file (nodes are the way the compiler represents statements or parts thereof internally). This is primarily intended for debugging the code generated by the compiler.

-ap

Use pipes instead of creating temporary assembler files. This may speed up the compiler on OS/2and Linux. Only with assemblers (such as GNU if the internal assembler is used.

-ar

List register allocation and release info in the assembler file. This is primarily intended for debugging the code generated by the compiler.

-at

List information about temporary allocations and deallocations in the assembler file.

-Axxx

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

default

Use the built-in default.

as

Assemble using GNUas.

gas

Assemble using GNUgas.

gas-darwin

Assemble using GNUgas for darwin Mach-O64.

nasmcoff

Coff (Go32v2) file using Nasm.

nasmelf

Elf32 (Linux) file using Nasm.

nasmwin32

Windows32-bit file using Nasm.

nasmwin64

Windows64-bit file using Nasm.

nasmwdosx

Windows32-bit/DOSX file using Nasm.

nasmdarwin

Object file using Nasm.darwin Mach-O64 using GNU GAS

macho

Mach-O (Darwin, Intel 32 bit) using internal writer.

masm

Object file using Masm (Microsoft).

tasm

Object file using Tasm (Borland).

elf

Elf32 (Linux) using internal writer.

coff

Coff object file (Go32v2) using the internal binary object writer.

pecoff

PECoff object file (Win32) using the internal binary object writer.

wasm

Object file using wasm (Watcom).

yasm

Object file using yasm (experimental).

-B

Re-compile all used units, even if the unit sources didn’t change since the last compilation.

-b

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

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

-C3

Turn on (or off) IEEE error checking for constants.

-Caxxx

Set the ABI (Application Binary Interface) to xxx. The -i option gives the possible values for xxx.

-Cb

Generate big-endian code.

-Cc

Set the default calling convention used by the compiler.

-CD

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

-Ce

Emulate floating point operations.

-Cfxxx

Set the used floating point processor to xxx. fpc -i lists all possible values.

-CFNN

Set the minimal floating point precision to NN. Possible values are 32 and 64.

-Cg

Enable generation of PIC code. This should only be necessary when generating libraries on Linuxor other Unices.

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

-CN

Generate nil-pointer checks (AIX-only).

-Co

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

-CO

Check for possible overflow of integer operations.

-CpXXX

Set the processor type to XXX.

-CPX=N

Set the packing for X to N. X can be PACKSET, PACKENUM or PACKRECORDS, and N can be a value of 1,2,4,8 or one of the keywords DEFAULT (0) or NORMAL. PACKRECORDS supports also values 16 and 32. (see the Programmer’s Guidefor more info).

-Cr

Generate Range checking code. If your program accesses an array element with an invalid index, or if it increases an enumerated type beyond its 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. It will also insert an type check in case of typecasts.

-Csxxx

Set stack size to xxx.

-Ct

Generate stack checking code. If your program performs a faulty stack operation, a run-rime error will be generated.

-CTNNN

Target specific code generation options:

cld

Emit a CLD instruction before using the x86 string instructions

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

-D

Generate a DEF file (for OS/2).

-Dd

Set the description of the executable/library (Windows).

-Dv

Set the version of the executable/library (Windows).

-Dw

PM application (for OS/2)

-E

Same as -Cn.

-fPIC

same as -Cg.

-g

Generate debugging information for debugging with gdb.

-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. (note that you cannot use this for externally obtained pointers).

-gg

Same as -g.

-gh

Use the heaptrc unit (see Unit Reference). (Produces a report about heap usage after the program exits)

-gl

Use the lineinfo unit (see Unit Reference). (Produces file name/line number information if the program exits due to an error.)

-goXXX

Set debug information options. One of the options is dwarfsets: It enables dwarf set debug information (this does not work with gdb versions prior to 6.5. stabsabsincludes tells the compiler to store absolute/full include file paths in stabs. dwarfmethodclassprefix tells the compiler to prefix method names in DWARF with class name. item [-gp] Preserve case in stabs symbol names. Default is to uppercase all names.

-gs

Write stabs debug information.

-gt

Trash local variables. This writes a random value to local variables at procedure start. This can be used to detect uninitialized variables. The t can be specified multiple times

-gv

Emit info for Valgrind. Note: this will include the cmem unit in your executable, replacing the default memory manager with the C memory manager.

-gw

Emit dwarf debugging info (version 2).

-gw2

Emit dwarf debugging info (version 2).

-gw3

Emit dwarf debugging info (version 3).

-gw4

Emit dwarf debugging info (version 4, experimental).

-kxxx

Pass xxx to the linker.

-Oxxx

Optimize the compiler’s output; xxx can have one of the following values :

aPARAM=VALUE

Specify alignment of structures and code. PARAM determines what should be aligned; VALUE specifies the alignment boundary. See the Programmer’s Guidefor a description of the possible values.

1

Level 1 optimizations (quick and debugger-friendly optimizations).

2

Level 2 optimizations (-O1 plus quick optimizations).

3

Level 3 optimizations (-O2 plus slower optimizations).

4

Level 4 optimizations (-O3 plus optimizations that might have side effects).

oNNN

Specify individual optimizations: NNN can be one of

REGVAR

Use register variables

UNCERTAIN

Uncertain optimizations (use with care)

STACKFRAME

Skip stack frames

PEEPHOLE

Peephole optimizations

ASMCSE

Common subexpression elimination at the assembler level (i386-only, deprecated)

LOOPUNROLL

Unroll (small) loops

TAILREC

Change tail recursion to non-recursive loop

CSE

Common subexpression elimination

DFA

Enable Data Flow Analysis

USEEBP

Use the EBP/RBP register to hold variables (x86-only)

ORDERFIELDS

Reorder class instance fields if this results in better alignment

FASTMATH

Fast math operations (may reduce floating point precision)

REMOVEEMPTYPROCS

Remove calls to empty procedures.

CONSTPROP

Constant propagation (experimental, requires -Oodfa)

pxxx

Select processor xxx to optimize for. fpc -i lists all available processor instruction sets.

Wxxx

Generate Whole-Program-Optimization information for feature xxx. fpc -i will generate a list of possible values.

wxxx

Perform Whole-Program-Optimization information for feature xxx. fpc -i will generate a list of possible values.

s

Optimize for size rather than speed.

The exact effect of some of these optimizations can be found in the Programmer’s Guide.

-oxxx

Use xxx as the name of the output file (executable). For use only with programs. The output filename can contain a path, and if it does, it will override any previous -FE setting. If the output filename does not contain a path, the -FE setting is observed.

-pg

Generate profiler code for gprof. This will define the symbol FPC_PROFILE, which can be used in conditional defines.

-PB

Show default Target CPU compiler binary.

-PP

Show default target CPU.

-Pxxx

Set target CPU (arm,avr,i386,jvm,m68k,mips,mipsel,powerpc,powerpc64,sparc,x86_64).

-s

Do not 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. This option can take an extra parameter, mainly used for cross-compilation. It can have one of the following values:

h

Generate script to link on host. The generated script can be run on the compilation platform (host platform).

t

Generate script to link on target platform. The generated script can be run on the target platform. (where the binary is intended to be run)

r

Skip register allocation phase (optimizations will be disabled).

-Txxx

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

• darwin : Darwin Mac OS X.

• emx : OS/2 via EMX (and DOS via EMX extender).

• freebsd : FreeBSD.

• go32v2 : DOSand version 2 of the DJ DELORIE extender.

• iphonesim : iPhone simulator.

• linux : Linux.

• netbsd : NetBSD.

• netware : Novell Netware Module (clib).

• netwlibc : Novell Netware Module (libc).

• openbsd : OpenBSD.

• os2 : OS/2 (2.x) using the EMX extender.

• sunos : SunOS/Solaris.

• watcom : Watcom compatible DOS extender

• wdosx : WDOSX extender.

• win32 : Windows32 bit.

• win64 : Windows64 bit.

• wince : Windowsfor handhelds (ARM processor).

The available list of targets depends on the actual compiler binary. Use fpc -i to get a list of targets supported by the compiler binary.

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

-W

Set some Windowsor OS/2attributes of the generated binary. It can be one or more of the following

A

Specify native type application (Windows)

b

Create a bundle instead of a library (Darwin)

B

Create arelocatable image (Windows)

Bhhh

Set preferred base address to hhh (a hexadecimal address)

C

Generate a console application (+) or a gui application (-).

D

Force use of Def file for exports.

e

Use external resources (Darwin)

F

Generate a FS application (+) or a console application (-).

G

Generate a GUI application (+) or a console application (-). For Windows-like operating systems a graphical application does not have stdin/stdout/stderror file descriptors. If you create a console application, then these file descriptors are opened when the program is started. Note that in a console application you can still create windows as in a graphical application.

i

Use internal (FPC) resources (Darwin)

I

Turn on/off the usage of import sections (Windows)

Mnnn

Minimum Mac OS X deployment version: nnn equals 10.4, 10.5.1, ... (Darwin)

N

Do not generate a relocation section.

PXXX

Minimum iOS deployment version needed (iphonesim) XXX is one of 8.0, 8.0.2, etc.

R

Generate a relocation section.

T

Generate a TOOL application (+) or a console application (-).

X

Enable use of an executable stack (Linux)

-Xx

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

• c : (Linuxonly) Link with the C library. You should only use this when you start to port Free Pascalto another operating system.

• d Do not use the standard library path. This is needed for cross-compilation, to avoid linking with the host platform’s libraries.

• D : Link with dynamic libraries (defines the FPC_LINK_DYNAMIC symbol)

• e Use external (GNU) linker.

• f Substitute pthread library name for linking (BSD).

• g Create debug information in a separate file and add a debuglink section to executable.

• i Use internal linker.

• LA Define library name substitutions for the linking stage.

• LO Define the order of library linking.

• LD Exclude default order of standard libraries.

• MXXX : Set the name of the program entry routine. The default is ’main’.

• m : Generate linker map file.

• n : Use target system native linker instead of GNU ld (Solaris, AIX)

• pXXX : First search for the compiler binary in the directory XXX. (fpc command only).

• PXXX : Prepend binutils names with XXX for cross-compiling.

• rXXX : Set library path to XXX.

• Rxxx Prepend xxx to all linker search paths. (used for cross compiling).

• s : Strip the symbols from the executable.

• S : Link with static units (defines the FPC_LINK_STATIC symbol).

• t : Link static (passes the -static option to the linker).

• v : Generate table for Virtual Entry calls.

• X : Link with smartlinked units (defines the FPC_LINK_SMART symbol).

Options concerning the sources (language options)

For more information on these options, see Programmer’s Guide

-Mmode

Set language mode to mode, which can be one of the following:

delphi

Try to be Delphi compatible. This is more strict than the objfpc mode, since some Free Pascalextensions are switched off.

fpc

Free Pascal dialect (default).

macpas

Try to be compatible with Macintosh Pascal dialects.

objfpc

Switch on some Delphi extensions. This is different from Delphi mode, because some Free Pascalconstructs are still available.

tp

Try to be TP/BP 7.0 compatible. This means no function overloading etc.

ISO

In this mode, the compiler complies with the requirements of level 0 of ISO/IEC 7185.

-Mfeature

Select language feature feature. As of FPC version 2.3.1, the -M command line switch can be used to select individual language features. In that case, feature is one of the following keywords:

CLASS

Use object pascal classes.

OBJPAS

Automatically include the ObjPas unit.

RESULT

Enable the Result identifier for function results.

PCHARTOSTRING

Allow automatic conversion of null-terminated strings to strings,

CVAR

Allow the use of the CVAR keyword.

NESTEDCOMMENTS

Allow use of nested comments.

CLASSICPROCVARS

Use classical procedural variables.

MACPROCVARS

Use mac-style procedural variables.

REPEATFORWARD

Implementation and Forward declaration must match completely.

POINTERTOPROCVAR

Allow silent conversion of pointers to procedural variables.

AUTODEREF

Automatic (silent) dereferencing of typed pointers.

INITFINAL

Allow use of Initialization and Finalization

ANSISTRINGS

Allow use of ansistrings.

OUT

Allow use of the out parameter type.

DEFAULTPARAMETERS

Allow use of default parameter values.

HINTDIRECTIVE

Support the hint directives (deprecated, platform etc.)

DUPLICATELOCALS

Allow method arguments with the same name as properties in classes.

PROPERTIES

Allow use of global properties.

ALLOWINLINE

Allow inline procedures.

EXCEPTIONS

Allow the use of exceptions.

OBJECTIVEC1

Allow the use of objective C version 1.

OBJECTIVEC2

Allow the use of objective C version 2.

NESTEDPROCVARS

Allow assigning local procedures to nested procedural variables and defining inline procedural variable types, which can always accept local procedures, in parameter declarations.

NONLOCALGOTO

Allow a GOTO statement to jump outside the local scope (as ISO Pascal).

ADVANCEDRECORDS

Allow the use of advanced records (records with methods/properties)

ISOUNARYMINUS

Treat unary minus like in ISO Pascal: same precedence level as binary minus/plus.

The keyword can be followed by a plus or minus sign to enable or disable the feature. Note that the order of mode and feature switches is important, a mode switch resets the feature list to the default features for that mode.

-Rxxx

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

default

Use the default assembler for the specified target.

-S2

Switch on Delphi 2 extensions (objfpc mode). Deprecated, use -Mobjfpc instead.

-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

Try to be Delphi compatible. Deprecated, use -Mdelphi instead.

-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). Instead of a number, one of n, h or w can also be specified. In that case the compiler will consider notes, hints or warnings as errors and stop when one is encountered.

-Sf

Enable certain features in compiler and RTL. This allows for finer control over available language features than the mode switch. Possible values are:

HEAP

Allow heap memory.

INITFINAL

Initialization/finalization.

RTTI

Allow use of RTTI.

CLASSES

Allow use of classes.

EXCEPTIONS

Allow use of exceptions.

EXITCODE

Allow use of exit code for applications.

ANSISTRINGS

Allow use of ansistrings.

WIDESTRINGS

Allow use of widestrings.

TEXTIO

Allow use of standard Pascal text file I/O.

CONSOLEIO

Allow use of standard Pascal console I/O (text file).

FILEIO

Allow use of standard Pascal binary file I/O.

RANDOM

Allow use of Random() function.

VARIANTS

Allow use of variants.

OBJECTS

Allow use of TP-style objects.

DYNARRAYS

Allow use of dynamic arrays.

THREADING

Allow use of threading.

COMMANDARGS

Allow use of command-line arguments.

PROCESSES

Allow use of processes.

STACKCHECK

Enable stack checking.

DYNLIBS

Allow use of dynamically loadable libraries in the system unit.

SOFTFPU

Allow (enable) the use of software floating point operations.

OBJECTIVEC1

Allow use of Objective C support routines.

RESOURCES

Allow use of resources.

UNICODESTRING

Allow use of unicode strings.

-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 assembler)

-Sh

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

-Si

Support C++ style INLINE.

-SIXXX

Set interfaces style to XXX. Here XXX is one of

COM

COM compatible interfaces (reference counted, descend from IUnknown).

CORBA

Not reference counted interfaces.

-Sk

Load the Kylix compatibility unit (fpcylix).

-Sm

Support C-style macros.

-So

Try to be Borland TP 7.0 compatible. Deprecated, use -Mtp instead.

-Ss

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

-St

Allow the static keyword in objects. This flag is obsolete since Free Pascal2.6.0.

-Sv

Support vector processing (uses CPU vector extensions if available)

-Sx

Enable exception keywords (default in Delphi/Objfpc mode). This will mark all exception related keywords as keywords, also in Turbo Pascalor FPC mode. This can be used to check for code which should be mode-neutral as much as possible.

-Sy

@pointer returns a typed pointer, this is the same as the $T+ option.

-Un

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

-Us

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