freepascal.compiler/install/man/man1/fpc.1

.TH fpc 1 "22 feb 2002" "Free Pascal" "Free Pascal Compiler"
.SH NAME
fpc \- Free Pascal Compiler (FPC) binary

.SH SYNOPSIS

.B "fpc [options] [sourcefile]"
.BR

.SH DESCRIPTION
This binary is the main binary of the
.I Free Pascal Compiler (FPC)
which is a
.I Turbo Pascal
and
.I Delphi (7.0) 
compatible standalone (non GCC frontend) multitarget Pascal compiler.
.PP
The compiler uses
.BR LD (1)
and can use
.BR AS (1)
(see parameter \-Aas), but also has its own binary object writer.
.PP
The current main targets are
.I Go32V2
(Dos DJGPP extender),
.I Freebsd,
.I Linux,
.I MacOS,
.I MacOSX,
.I MorphOS,
.I Netware,
.I OS/2
and
.I Win32.
The other targets (M68K compilers for Atari and Amiga) are either based on older
versions of the compiler or are still in development.
.PP
This manpage is meant for quick\-reference only. FPC comes with a great (2000+ pages)
manual, which is updated constantly, while this man page can be out of date.

.SH Version number

Starting with release 1.0, a new versioning system has been implemented. 
If the last number is even (1.0, 1.0.2), it is stable, and if the last number is 
odd it is a daily changing development version.(1.0.5, 1.1) just like the linux kernel.
.PP
Version 0.99.5 however is a stable release. It was made before the even/odd version
naming system was introduced.

.SH Usage

The compilation proces is started by typing
.I fpc
followed by a sourcefile name (normally with .pas or .pp extension). Before processing the actual processing of the source file,
.BR fpc.cfg (5)
the configuration file of the compiler is read which contains the location of the
RTL, other packages (FCL, FreeVision), and optionally default values for some
switches. See the separate manpage of
.BR fpc.cfg (5)
for more information.

.SH Options

.PP
General options

.TP
.BI \-h
if you specify this option, the compiler outputs a list of all options,
and exits after that.
.TP
.BI \-?
idem as \-h, but waiting after every screenfull for the enter key.
.TP
.BI \-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:
.RS
.TP
.I D
Returns the compiler date.
.TP
.I V
Returns the compiler version.
.TP
.I SO
Returns the compiler OS.
.TP
.I SP
Returns the compiler processor.
.TP
.I TO
Returns the target OS.
.TP
.I TP
Returns the target Processor.
.RE
.TP
.I -l
This option tells the compiler to print the
.I FPC
logo on standard output. It also gives you the
.I FPC
version number.
.TP
.I -n
Tells the compiler not to read the configuration file
.BR fpc.cfg (5)

.PP
Options for getting feedback
.TP
.BI \-v xxx
Be verbose. "xxx" is a combination of the following:
.RS
.TP
.I e
Tells the compiler to show only errors. This option is on by default.
.TP
.I i
Tells the compiler to show some general information.
.TP
.I w
Tells the compiler to issue warnings.
.TP
.I n
Tells the compiler to issue notes.
.TP
.I h
Tells the compiler to issue hints.
.TP
.I l
Tells the compiler to show the line numbers as it processes a
file. Numbers are shown per 100.
.TP
.I u
Tells the compiler to print the names of the files it opens.
.TP
.I t
Tells the compiler to print the names of the files it tries
to open.
.TP
.I p
Tells the compiler to print the names of procedures and
functions as it is processing them.
.TP
.I c
Tells the compiler to warn you when it processes a
conditional.
.TP
.I m
Tells the compiler to write which macros are defined.
.TP
.I d
Tells the compiler to write other debugging info.
.TP
.I a
Tells the compiler to write all possible info. (this is the
same as specifying all options)
.TP
.I 0
Tells the compiler to write no messages. This is useful when
you want to override the default setting in the configuration file.
.TP
.I b
Tells the compiler to show all procedure declarations if an
overloaded function error occurs.
.TP
.I x
Tells the compiler to output some executable info (for Win32
platform only).
.TP
.I r
Rhide/GCC compatibility mode: formats the error differently, so they
are understood by RHIDE.
.RE
.PP
Options concerning files and directories
.TP
.BI -e xxx
tells the compiler that 
.I xxx
is the directory where it can find the executables as (the assembler) and 
ld (the linker).
.TP
.BI \-FD
same as
.I \-e.
.TP
.BI \-Fe xxx
This option tells the compiler to write errors, etc. to
the file 
.I xxx
.
.TP
.BI \-FE xxx
set the executable/unit output path to
.I xxx
.
.TP
.BI \-Fi xxx
adds 
.I xxx
to the path where the compiler searches for its include files.
.TP
.BI \-Fl xxx
Adds 
.I xxx
to the library searching path, and is passe to the linker.
.TP
.BI \-FL xxx
( Linux only) Tells the compiler to use 
.I xxx
as the dynamic linker. Default this is /lib/ld-linux.so.2, or
lib/ld-linux.so.1, depending on which one is found.
.TP
.BI \-Fo xxx
Adds 
.I xxx
to the object file path. This path is used
when looking for files that need to be linked in.
.TP
.BI \-Fr xxx
tells the compiler that 
.I xxx
contains the compiler messages. Default the compiler has built-in 
messages. Specifying this option will override the default messages.
(useful if you want to use a language other than the default language).
.TP
.BI \-Fu xxx
Adds
.I xxx
to the unit path.
By default, the compiler only searches for units in the current directory
and the directory where the compiler itself resides. This option tells the
compiler also to look in the directory 
.I xxx
.
.TP
.BI \-FU xxx
Tells the compiler to write units in directory 
.I xxx
instead of the current directory.
.TP
.BI \-I xxx
Add 
.I xxx
to the include file search path.
This path is used when looking for include files.

.PP Options controlling the kind of output
for more information on these options, see also the programmers manual.
.TP
.BI \-a
Tells the compiler not to delete the assembler file.
This also counts for the (possibly) generated batch script.
.TP
.BI \-al
Tells the compiler to include the sourcecode lines
in the assembler file as comments. 
.TP
.BI \-an
Tells the compiler to include node information in the generated assembler file.
This is mainly for use by the compiler developers.
.TP
.BI \-ap
Tells the compiler to use pipes to communicate with the assembler.
.TP
.BI \-ar
Tells the compiler to include register allocation/deallocation information.
.TP
.BI \-at
Tells the compiler to include temparary register allocation/deallocation information.
.TP
.BI -A xxx
specifies what kind of assembler should be generated . Here
.I xxx
is one of the following :
.RS
.TP
.I AS
A unix .o (object) file, using
.I GNU AS
.TP
.I coff
coff object file (go32) using internal writer.
.TP
.I default
Use the default writer for the current platform.
.TP
.I elf
elf object file (linux, 32-bit only) using internal writer.
.TP
.I nasmcoff
a coff file using the
.I nasm
assembler.
.TP
.I nasmelf
a ELF32 file (LINUX only) using the
.I nasm
assembler.
.TP
.I nasmobj
a obj file using the
.I nasm
assembler.
.TP
.I masm
An obj file using the Microsoft
.I masm
assembler.
.TP
.I pecoff
pecoff object file (win32) using internal writer.
.TP
.I tasm
An obj file using the Borland
.I tasm
assembler.
.TP
.I wasm
An obj file using the Watcom assembler.
.RE
.TP
.BI \-Ccxxx
set the default calling convention to XXX.
.TP
.BI \-CD
Create dynamic library.
.TP
.TP
.BI \-Ce
Compile using emulated floating point instructions.
.TP
.BI \-Cfxxx
Set the used floating point instruction set to xxx.
.TP
.BI \-Cg
Generate PIC code.
.TP
.BI \-Ch xxx
Reserves 
.I xxx
bytes heap. 
.I xxx
should be between 1024 and 67107840.
.TP
.BI \-Ci
Generate Input/Output checking code.
.TP
.BI \-Cn
Omit the linking stage.
.TP
.BI \-Co
Generate Integer overflow checking code.
.TP
.BI \-CR
Verify object call validity (method calls mustbe valid).
.TP
.BI \-Cr
Generate Range checking code.
.TP
.BI \-Cs xxx
Set stack size to 
.I xxx
bytes.
.TP
.BI \-Ct
generate stack checking code.
.TP
.BI \-CX
Create a smartlinked library.
.TP
.BI \-d xxx
Define the symbol name 
.I xxx
This can be used to conditionally compile parts of your code.

.TP
.BI \-E
Same as -Cn.
.TP
.BI \-g
Generate debugging information for debugging with
.I GDB
.
.TP
.BI \-gg
idem as 
.B -g.
.TP
.BI \-gd
generate debugging info for dbx.
.TP
.BI \-gh
use the heaptrc unit (see the units part of the FPC manual).
.TP
.BI \-gl
use the lineinfo unit for line information (see the units part of the FPC manual).
.TP
.BI \-gv
Generate information for debugging with valgrind.
.TP
.BI \-gw
Generate DWARF debugging information.
.TP
.BI \-O xxx
optimize the compiler's output; 
.I xxx
can have one of the following values :
.RS
.TP
.I g
optimize for size, try to generate smaller code.
.TP
.I G
optimize for time, try to generate faster code (default).
.TP
.I r
keep certain variables in registers (experimental, use with caution).
.TP
.I u
uncertain optimizations
.TP
.I 1
Level 1 optimizations (quick optimizations).
.TP
.I 2
Level 2 optimizations (-O1 plus some slower optimizations).
.TP
.I 3
Level 3 optimizations (-O2 plus -Ou).
.TP
.I pn
Specify processor : n can be one of
.RS
.TP
.I 1
optimize for 386/486
.TP
.I 2
optimize for Pentium/PentiumMMX (tm)
.TP
.I 3
optimizations for PentiumPro / P-II / Cyrix 6x86 / K6 (tm)
.RE

The exact effect of these effects can be found in the programmers part of the manual.
.RE
.TP
.BI \-o xxx
Tells the compiler to use 
.I xxx
as the name of the output file (executable). Only with programs.
.TP
.BI \-pg
Generate profiler code for gprof.
.TP
.BI \-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.
.TP
.BI \-sh
Tells the compiler to generate a script that can be used to assemble 
and link on the host system, not on the target system. Use this when 
cross-compiling.
.TP
.BI \-sr
Skip register allocation stage in compiler (use with -ar) 
.TP
.BI \-st
Tells the compiler to generate a script that can be used to assemble 
and link on the target system, not on the host system. Use this when 
cross-compiling.
.TP
.BI \-T xxx
Specifies the target operating system. 
.I xxx
can be one of the following:
.RS
.TP
.I EMX
OS/2 and DOS via the EMX extender.
.TP
.I FREEBSD
FreeBSD
.TP
.I GO32V2
DOS and version 2 of the DJ DELORIE extender.
.TP
.I LINUX
Linux.
.TP
.I NETBSD
Netbsd.
.TP
.I NETWARE
Novell Netware module (clib)
.TP
.I NETLIBC
Novell Netware module (libc)
.TP
.I OPENBSD
OpenBSD
.TP
.I OS2
OS/2 (native mode)
.TP
.I SunOS
Solaris SunOS
.TP
.I WATCOM
WatCOM dos extender
.TP
.I WDOSX
WDosX Dos extender
.TP
.I WIN32
Windows 32 bit.
.RE
.TP
.BI -u xxx
undefine the symbol 
.I xxx
if it is defined. This is the opposite of the 
.B \-d 
option.
.TP
.BI \-X x
Executable options. These tell the compiler what
kind of executable should be generated. the parameter 
.I x
can be one of the following:
.RS
.TP
.I c
(Linux only, obsolete) Link with the C library. You should only use this when
you start to port Free Pascal to another operating system.
.TP
.I D
Link with dynamic libraries (defines the FPC_LINK_DYNAMIC symbol)
.TP
.I d
Don't use the standard library path. Use this when cross-compiling, to avoid
linking with the host OS libraries.
.TP
.I Pxxx
Prepend the names of binutils (as, ld) with xxx. For use when cross-compiling.
.TP
.I rxxx
Set the library search path to xxx.
.TP
.I s
Strip the symbols from the executable.
.TP
.I S
Link with static libraries (defines the FPC_LINK_STATIC symbol)
.TP
.I t
Link statically (passes -static to the linker)
.TP
.I X
Link smart. Using this option sets the FPC_LINK_SMART symbol.
.RE

.PP
Options concerning the sources (language options)
for more information on these options, see also in the Programmers Manual
.TP
.BI \-M mode
Specify the language mode. 
.I mode
can be one of the following:
.RS
.TP
.I delphi
Delphi-compatibility mode. This loads the objpas unit, and switches on ansistring mode (
.B -Sh
).
.TP
.I fpc
Default mode.
.TP
.I gpc
GNU pascal mode (does nothing at the moment)
.TP
.I macpas
MAC pascal mode. This loads the macpas unit and switches on some Mac extensions
(mainly macros)
.TP
.I objfpc
Object Pascal mode. This loads the objpas unit.
.TP
.I tp
Turbo Pascal mode.
.RE
.TP
.BI \-R xxx
Specifies what assembler you use in your "asm" assembler code
blocks. Here 
.I xxx
is one of the following:
.RS
.TP
.I att
Asm blocks contain AT&T assembler.
.TP
.I intel
Asm blocks contain Intel assembler.
.TP
.I direct
Asm blocks should be copied as-is in the assembler
file.
.RE
.TP
.BI \-S2
Switch on Delphi 2 extensions.
.TP
.BI \-Sa
Generate code for assertions.
.TP
.BI \-Sc
Support C-style operators, i.e. *=, +=, /= and -=.
.TP
.BI \-Sd
Tries to be Delphi compatible
.TP
.BI \-Se
The compiler stops after the first 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 first error.
.TP
.BI \-Sg
Support the label and goto commands.
.TP
.BI \-Sh
use ansistrings by default.
.TP
.BI \-SIxxx
Specify the kind of interfaces. 
.I xxx
can be one of the following:
.RS
.TP
.I COM 
use COM interfaces. (all interfaces descend from IUnknown)
.TP
.I CORBA 
use CORBA interfaces. (no inheritance is supposed)
.RE
.TP
.BI \-Si
Support C++ style INLINE.
.TP
.BI \-Sm
Support C-style macros.
.TP
.BI \-So
Try to be Borland TP 7.0 compatible (no function
overloading etc.).
.TP
.BI \-Sp
Try to be
.I GPC (GNU Pascal Compiler)
compatible.
.TP
.BI \-Ss
The name of constructors must be "init", and the
name of destructors should be "done".
.TP
.BI \-St
Allow the "static" keyword in objects.
.TP
.BI \-Un
Do not check the unit name. Normally, the unit name
is the same as the filename. This option allows both to be different.
.TP
.BI \-Ur
Create a release unit. This sets a special flag in the unit, causing the 
compiler not to look for sources.
.TP
.BI \-Us
Compile a system unit. This option causes the
compiler to define only some very basic types.

.SH SEE ALSO
.BR  fpc.cfg (5)
.BR  ppdep (1)
.BR  ppudump (1)
.BR  ppumove (1)
.BR  ptop (1)
.BR  h2pas (1)
.BR  ld (1)
.BR  as (1)