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.

-Ldir

Search the directory dir for libraries. Can be given multiple times.

-Idir

Search the directory dir for include files. Can be given multiple times.

-llibrary

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.

-Dmacro[=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.)