5.2 The most commonly used options to GPC
As the most simple example, calling
gpc foo.pas
tells GPC to compile the source file foo.pas and to produce
an executable of the default name which is foo.exe on EMX,
a.exe on Cygwin, both a.out and a.exe on DJGPP,
and a.out on most other platforms.
Users familiar with BP, please note that you have to give the file
name extension .pas: GPC is a common interface for a Pascal
compiler, a C, ObjC and C++ compiler, an assembler, a linker, and
perhaps an Ada and a FORTRAN compiler. From the extension of your
source file GPC figures out which compiler to run. GPC recognizes
Pascal sources by the extension .pas, .p, .pp
or .dpr. GPC also accepts source files in other languages
(e.g., .c for C) and calls the appropriate compilers for
them. Files with the extension .o or without any special
recognized extension are considered to be object files or libraries
to be linked.
Another example:
gpc -O2 -Wall --executable-file-name --automake --unit-path=units foo.pas
This will compile the source file foo.pas to an executable
named foo (--executable-file-name) with fairly good
optimization (-O2), warning about possible problems
(-Wall). If the program uses units or imports modules, they
will be searched for in a directory called units
(--unit-path) and automatically compiled and linked
(--automake).
The following table lists the most commonly used options to GPC.
--automake
- Check whether modules/units used must be recompiled and do the
recompilation when necessary.
--unit-path=
dir[:
dir...]
- Search the given directories for units and object files.
--object-path=
dir[:
dir...]
- Search the given directories for object files.
--unit-destination-path=
dir- Place compiled units (GPI and object files) into the directory
dir. The default is the current directory.
--object-destination-path=
dir- Place compiled object files (e.g., from C files, but not from Pascal
units) into the directory dir. The default is the directory
given with --unit-destination-path.
--executable-path=
dir- Place the executable compiled into the directory dir. The
default is the main source file's directory.
-o
file- Place output in file file. This applies regardless to whatever
sort of output is being produced, whether it be an executable file,
an object file, an assembler file, etc.
Since only one output file can be specified, it does not make sense
to use -o when compiling more than one input file, unless you
are producing an executable file as output.
--executable-file-name[=
name]
- Derive the executable file name from the source file name, or use
name as the executable file name. The difference to the
-o option is that --executable-file-name considers the
--executable-path, while -o does not and accepts a
file name with directory. Furthermore, --executable-file-name
only applies to executables, not to other output formats selected.
-L
dir- Search the directory dir for libraries. Can be given multiple
times.
-I
dir- Search the directory dir for include files. Can be given
multiple times.
-l
library- Search the library named library when linking. This option
must be placed on the command line after all source or object
files or other libraries that reference the library.
-O[
n]
- Select the optimization level. Without optimization (or -O0
which is the default), the compiler's goal is to reduce the
compilation time and to make debugging produce the expected results.
Statements are independent: if you stop the program with a
breakpoint between statements, you can then assign a new value to
any variable or change the program counter to any other statement in
the same routine and get exactly the results you would expect from
the source code.
With optimization, the compiler tries to reduce code size and
execution time. The higher the value of n, the more
optimizations will be done, but the longer the compilation will
take.
If you use multiple -O options, with or without n, the
last such option is the one that is effective.
-g
- Produce debugging information suitable for gdb. Unlike some
other compilers, GNU Pascal allows you to use -g with
-O. The shortcuts taken by optimized code may occasionally
produce surprising results: some variables you declared may not
exist at all; flow of control may briefly move where you did not
expect it; some statements may not be executed because they compute
constant results or their values were already at hand; some
statements may execute in different places because they were moved
out of loops. Nevertheless it proves possible to debug optimized
output. This makes it reasonable to use the optimizer for programs
still in the testing phase.
-s
- Remove all symbol table and relocation information from the
executable. Note: this has no influence on the performance of the
compiled executable.
-Wall
- Give warnings for a number of constructs which are not inherently
erroneous but which are risky or suggest there may have been an
error. There are additional warning options not implied by
-Wall, see the GCC warning options
(see Options to Request or Suppress Warnings (the GCC manual)),
while -Wall only warns about such constructs that should be
easy to avoid in programs. Therefore, we suggest using -Wall
on most sources.
Note that some warnings (e.g., those about using uninitialized
variables) are never given unless you compile with optimization (see
above), because otherwise the compiler doesn't analyze the usage
patterns of variables.
-Werror
- Turn all warnings into errors.
-S
- Stop after the stage of compilation proper; do not assemble. The
output is in the form of an assembler code file for each source
file. By default, the assembler file name for a source file is made
by replacing the extension with .s.
-c
- Compile and assemble the source files, but do not link. The output
is in the form of an object file for each source file. By default,
the object file name for a source file is made by replacing the
extension with .o.
-static
- On systems that support dynamic linking, this prevents linking with
the shared libraries, i.e. forces static linking. On other systems,
this option has no effect.
-D
macro[=
def]
- Define the macro and conditional symbol macro as def (or
as 1 if def is omitted).
-b
machine- The argument machine specifies the target machine for
compilation. This is useful when you have installed GNU Pascal as a
cross-compiler.
-v
- Print (on standard error) the commands executed to run the stages of
compilation. Also print the version number of the compiler driver
program and of the preprocessor and the compiler proper.
--classic-pascal-level-0
--classic-pascal
--extended-pascal
--object-pascal
--ucsd-pascal
--borland-pascal
--pascal-sc
- GNU Pascal supports the features of several different Pascal
standards and dialects. By default, they are all enabled. These
switches tell GPC to restrict itself to the features of the
specified standard. It does not enable any additional features.
Warnings about certain dangerous constructs which would be valid in
the specified dialect (e.g., assignment to a typed constant with
--borland-pascal) are suppressed.
By default, GNU Pascal allows the redefinition of some keywords.
Each of these switches causes GNU Pascal to forbid the redefinition
of keywords of the specified standard.
Valid ISO 7185 Pascal programs should compile properly with or
without --classic-pascal. However, without this option,
certain GNU extensions and Pascal features from other dialects are
supported as well. With this option, they are rejected.
These options are not intended to be useful; they exist only to
satisfy pedants who would otherwise claim that GNU Pascal fails to
support the ISO Standard or is not really compatible to Borland
Pascal, or whatever. We recommend, rather, that users take advantage
of the extensions of GNU Pascal and disregard the limitations of
other compilers.
-pedantic-errors
- Produce errors rather than warnings for portability violations.
Unlike in C, this does not imply the -pedantic option,
so you can, for instance, use -pedantic-errors without
-pedantic, but with --extended-pascal.
--gpc-main=
name- Name the entry point of the main program name instead
of main on the linker level. This is useful, e.g., when
working with some C libraries which define their own main
function and require the program's main entry point to be named
differently. (This option should preferably be used as a compiler
directive in the unit or module which links to that strange C
library, rather than be given on the command-line.)