This is gpc.info, produced by makeinfo version 4.0 from gpc.texi.

INFO-DIR-SECTION GNU programming tools
START-INFO-DIR-ENTRY
* GPC: (gpc).                   The GNU Pascal Compiler.
END-INFO-DIR-ENTRY
INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* GPC: (gpc)Invoking GPC.       The GNU Pascal Compiler.
END-INFO-DIR-ENTRY

   This file documents the GNU Pascal Compiler.

   Copyright (C) 1988, 1996-2000 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License", "The GNU
Project", "The GNU Manifesto" and "Funding for Free Software" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License", "The GNU Project", "The GNU Manifesto" and "Funding for Free
Software" and this permission notice, may be included in translations
approved by the Free Software Foundation instead of in the original
English.


File: gpc.info,  Node: Built-in Procedures and Functions,  Next: Special Parameters,  Prev: Built-in Operators in BP and GPC,  Up: Borland Pascal

Built-in Procedures and Functions
=================================

   * `GetMem' and `FreeMem' are supported like in BP.  `GetMem' can
     also act as a function in GNU Pascal:

          program GetMemFunctionDemo;
          var p : Pointer;
          begin
            p := GetMem (1024)
          end.

     The second parameter to `FreeMem' is ignored by GNU Pascal and may
     be omitted. Memory blocks are always freed with the same size they
     were allocated with.

     Remark: Extended Pascal Schema types provide a cleaner approach to
     most of the applications of `GetMem' and `FreeMem'.

   * `Min' and `Max': GNU Pascal has built-in `Min' and `Max' functions
     (two arguments) which work for all ordinal types (`Integer',
     `Char', ...) plus `Real'.

   * `UpCase', `High', `Low' and similar functions are built-in. In
     contrast to Borland Pascal, GNU Pascal's `UpCase' function is
     aware of non-ASCII characters of certain languages (e.g., accented
     letters and "umlauts"), but for compatibility this feature is
     disables in `--borland-pascal' mode. There is also a `LoCase'
     function.

   * `Lo', `Hi', `Swap' functions: not built-in, but available in the
     `System' unit.


File: gpc.info,  Node: Special Parameters,  Next: Miscellaneous,  Prev: Built-in Procedures and Functions,  Up: Borland Pascal

Special Parameters
==================

   * Untyped reference parameters can be denoted by

          procedure Foo (var x);

     like in Borland Pascal. In GNU Pascal, you can also use

          procedure Foo (var x : Void);

   * GNU Pascal defines "ellipsis" parameters for variable argument
     lists:

          procedure Foo (a : Integer; ...);

     However, GPC does not (yet) provide a portable mechanism to access
     the additional arguments.

   * Structured function return values: According to Extended Pascal,
     GNU Pascal allows functions to return records and arrays.

   * BP style "open array parameters"
          procedure Foo (a : array of Integer);
     are implemented. However, Standard Pascal `conformant array
     parameters' are usually a cleaner mechanism to pass arrays of
     variable size.

   * Besides BP compatible procedural types, GNU Pascal supports
     Standard Pascal's procedural parameters:

          procedure DrawGraph (function f (x : Real) : Real);


File: gpc.info,  Node: Miscellaneous,  Next: BP and Extended Pascal,  Prev: Special Parameters,  Up: Borland Pascal

Miscellaneous
=============

   * Headlines: According to Extended Pascal, a program headline must
     contain the program's parameters:

          program Foo (Input, Output);
          begin
          end.

     In GNU Pascal, headline parameters are optional. If the headline is
     omitted entirely, a warning is given unless you have specified
     `--borland-pascal' in the command line.

   * `case' statements: In a `case' statement, GNU Pascal allows
     `otherwise' (according to Extended Pascal) as an alternative to
     `else':

          program CaseOtherwiseDemo;
          var x : Integer;
          begin
            ReadLn (x);
            case x of
              1 : WriteLn ('one');
              2 : WriteLn ('two');
              otherwise
                WriteLn ('many')
            end
          end.

     Note: In the absence of a `case' or `otherwise' branch, missing
     cases labels cause an error in Extended Pascal (which goes
     unnoticed in Borland Pascal). GPC does not give this error, but a
     warning if the `-Wswitch' option is given, however only for
     enumeration types.

   * Character constants: BP compatible character constants like `^M'
     as well as `#13' are implemented into GNU Pascal.

   * Sets: GNU Pascal has a `Card' function for sets which counts their
     elements. Unlike Borland Pascal, GNU Pascal does not limit sets to
     the range 0 .. 255.

   * Inline: GNU Pascal allows "inline" Pascal procedures and
     functions, while Borland Pascal only allows machine code to be
     inlined:

     Borland Pascal:

          function Max (x, y : Integer) : Integer;
            inline ($58 / $59 / $3b / $c1 / $7f / $01 / $91);

     GNU Pascal:

          program InlineDemo;
          
          inline function Max (x, y : Integer) : Integer;
          begin
            if x > y then
              Max := x
            else
              Max := y
          end;
          
          begin
            WriteLn (Max (42, 17), ' ', Max (-4, -2))
          end.

     (Actually, a more general `Max' function is already built-in.)

     This feature is not so important as it might seem because in
     optimization level 3 or higher (*note GPC Options::), GNU Pascal
     automatically inlines short procedures and functions.


File: gpc.info,  Node: BP and Extended Pascal,  Next: Portability hints,  Prev: Miscellaneous,  Up: Borland Pascal

BP and Extended Pascal
======================

   Pascal is a well-known programming language and hardly needs to be
described here. Note, however, that there is a large difference between
the language used by the BP compiler and the Pascal Standards.

   Extended Pascal is a standardized language based on the original
Standard Pascal, but with significant extensions. Unfortunately,
Borland Pascal does not conform to any of the Pascal standards.
Writing a program that both complies to Extended Pascal (or even
Standard Pascal) and compiles with BP is almost impossible for any
non-trivial task.

   On the other hand, BP has some nice features that make it very
powerful in the environments in which it runs. However, some of those
features are of little use on non-Dos systems and would not be good
candidates for standardization.

   There are also several BP features which are semantically similar to
features in Standard Pascal or Extended Pascal, but syntactically
different.

   Therefore, in order to be useful to users coming from either side,
GPC supports both the standards and the BP dialect as good as possible.
By default, GPC allows features from any dialect it knows.  By giving a
dialect option such as `--borland-pascal' or `--extended-pascal', you
can tell GPC to disable the features not found in that dialect, and to
adjust its warning behaviour to the dialect.

   The different sets of reserved words are a little problem, but GPC
solves it by making the words in question only "conditionally reserved"
which works transparently without problems in most cases. Still, giving
a dialect option will disable all keywords not part of this dialect.

   Apart from this, there are surprisingly few real conflicts between
the dialects. Therefore, you can usually compile your BP code without
the `--borland-pascal' option and make use of all of GPC's features.
You might be surprised, though, when GPC accepts things you didn't know
were allowed. :-)

   Finally, if you want to make use of some of GPC's extensions
(compared to BP) and still keep the code compileable with BP without
using `ifdef's all over the place, we suggest you look at the unit
`gpc-bp.pas', shipped with GPC, which contains BP versions of some of
GPC's features. Please read the comments at the beginning of the unit
to find out more about it.


File: gpc.info,  Node: Portability hints,  Prev: BP and Extended Pascal,  Up: Borland Pascal

Portability hints
=================

   GPC offers you the possibility to make your code fully portable to
each of the many platforms supported by GPC. It would be a pity not to
make use of this.

   This section lists some known pitfalls that often hinder otherwise
well-written programs to take full advantage of GPC. If you have never
used any compiler but Borland Pascal and similar compilers, some of the
advices might look strange to you. But this is just the same level of
strangeness that your old programs will have for you once you have
understood the principles of cross-platform portability. Remember that
many tricks you have always been applying almost automatically in
Borland Pascal were necessary to overcome certain limitations of the
Dos platform and to compensate for the compiler's missing optimization.
Programming with an optimizing compiler like GPC for platforms without
a 64 kB limit is a completely new experience - and perhaps it is among
the reasons why you are now working with GPC in the first place?

Portability - why?
------------------

   _Okay - but why should I bother and make my program portable?  I
know that all who want to use my program are running WXYZ-OS anyway._

   Yes, but that's the result of a self-fulfilling prophecy. It depends
on *you* whether it will always remain like this or not.  Consider a
program ABC written for a single platform, WXYZ-OS.  Naturally, only
WXYZ-OS-users get interested in ABC. The author gets feedback only from
WXYZ-OS users and does not see any reason to make the program
cross-platform. Then people realize that if they want to run ABC they
must move to WXYZ-OS. The author concludes that people only want
WXYZ-OS programs, and so on.

   To break out, just create a portable version of your program *now*.
Then all OSes have equal chances to show their abilities when running
your program, and your customers can choose their OS. Then, maybe, they
decide to use your program just for the reason that they can be sure
that it will run on all present and future platforms and not only on a
specific one - who knows?

   _My program is a tool specifically designed to make the best of the
STUV feature of WXYZ-OS. There is no point in making it portable._

   How much do you know about non-WXYZ-OSes? Just ask an expert how the
STUV feature is named elsewhere. Be sure, if it is of value, it exists
almost everywhere.

Low-level features
==================

   _I am using a lot of low-level stuff in my programs, so they cannot
be portable._

   You do not use those low-level routines directly in your high-level
routines, do you? There should always be a layer "in-between" that
encapsulates the low-level routines and present an API to your program
that exactly reflects the needs of your application.  This "API in
between" is the point where you can exchange the low-level routines by
portable calls to GPC's Run Time System.

   If you do not have such a layer in-between, then the API of the
low-level routines you call are your first approximation for such a
layer.  If you have ever thought "it would be great if that API
function had that additional parameter", then your own extended version
of that API function that *has* that parameter can become part of your
"API in between".  But then don't stop here: Certainly the API of the
OS is *not* ideal for your program's needs. Just create more routines
that encapsulate all OS-specific stuff ...

   When the low-level stuff in question consists of interrupts,
assembler and similar things, then the first thing you need is a
portable replacement of the functionality. Fortunately, GPC covers many
things already in Pascal that require assembler in Borland Pascal:

   * GPC's libraries come with source. You do not need to learn
     assembler and to write a complete replacement for the CRT unit if
     you only want to adapt some tiny detail in the behavior of CRT to
     your personal needs.

   * GPC's Run Time System is fairly complete. For example, to extract
     the assigned name of a `File' variable, you do not need to mess
     around with the internal representation of those variables, but you
     can type `uses GPC' and then use the `FileName' function.  In the
     same unit, you will find a `FileExists' function and much more.

   * Manually "constructing" an object is covered by the `SetType'
     procedure in GPC. This is where Turbo Vision uses assembler to load
     an object from a stream.

   * Calling local procedures and functions via pointers simply works in
     GPC. This is another place where, for instance, Turbo Vision's
     `ForEach' method uses assembler, while GPC lets you do the same
     thing in Pascal.

   * Interfacing with the OS can be done through library calls. GPC's
     built-in functions and the GPC unit offer a rather complete set of
     routines. And again: You have the source of all this.

   * Using `FillChar' and `Move' does not necessarily speed up your
     programs. Using them to circumvent restrictions of the language
     (e.g. for direct assignments between variables of object or file
     type) is asking for trouble. `FillChar' was created in UCSD Pascal
     to set consecutive chars in a string to the same value, and `Move'
     was created to move the chars within the same string.  Better do
     not use them for other purposes.



File: gpc.info,  Node: Invoking GPC,  Next: Programming,  Prev: Borland Pascal,  Up: Top

Command Line Options supported by GNU Pascal.
*********************************************

   GPC is a command-line compiler, i.e., to compile a program you have
to invoke `gpc' passing it the name of the file you want to compile,
plus options.

   GPC supports all command-line options that GCC knows. For a complete
reference and descriptions of all options, see *Note GCC Command
Options: (gcc)Invoking GCC.  Below, you will find a list of the
additional options that GPC supports, and a list of GPC's most
important options (including some of those supported by GCC as well).

   You can mix options and file names on the command line. For the most
part, the order doesn't matter. Order does matter, e.g., when you use
several options of the same kind; for example, if you specify `-L' more
than once, the directories are searched in the order specified. _Note:_
Since many options have multiletter names; multiple single-letter
options may _not_ be grouped as is possible with many other programs:
`-dr' is very different from `-d -r'.

   Many options have long names starting with `--' or, completely
equivalent `-f'. E.g., `--mixed-comments' is the same as
`-fmixed-comments'. Some options tell GPC when to give warnings, i.e.
diagnostic messages that report constructs which are not inherently
erroneous but which are risky or suggest there may have been an error.
Those options start with `-W'.

   Most GPC specific options can also be changed during one compilation
by using compiler directives in the source, e.g. `{$X+}' or
`{$extended-syntax}' for `--extended-syntax' (*note Compiler
Directives::).

   GPC understands the same environment variables GCC does (*note
Environment Variables Affecting GCC: (gcc)Environment Variables.).  In
addition, GPC recognizes `GPC_EXEC_PREFIX' with the same meaning that
`GCC_EXEC_PREFIX' has to GCC. GPC also recognizes `GCC_EXEC_PREFIX',
but `GPC_EXEC_PREFIX' takes precedence.

* Menu:

* GPC Command Line Options::  GPC options besides those of GCC.
* GPC Options::               The most commonly used options to GPC.


File: gpc.info,  Node: GPC Command Line Options,  Next: GPC Options,  Up: Invoking GPC

GPC options besides those of GCC.
=================================

   The following table lists the command line options GPC understands
in addition to those understood by GCC.

`--standard-pascal-level-0'
     Reject conformant arrays and anything besides ISO-7185 Standard
     Pascal.

`--standard-pascal'
     Reject anything besides ISO-7185 Standard Pascal.

`--extended-pascal'
     Reject anything besides ISO-10206 Extended Pascal.

`--object-pascal'
     Reject anything besides (the implemented parts of) ANSI draft
     Object Pascal.

`--borland-pascal'
     Try to emulate Borland Pascal, version 7.0.

`--delphi'
     Try to emulate Borland Pascal, version 7.0, with some Delphi
     extensions.

`--pascal-sc'
     Be strict about the implemented Pascal-SC extensions.

`--gnu-pascal'
     Undo the effect of a previous `--foo-pascal', `--delphi' or
     `--pascal-sc' switch.

`--lines'
     (Unimplemented switch for debugging).

`--debug-tree'
     (Internal directive for debugging the compiler).

`--debug-gpi'
     (Internal directive for debugging the compiler).

`--debug-source'
     (Internal directive for debugging the compiler).

`--progress-messages'
     Output source file names and line numbers while compiling.

`--progress-bar'
     Output number of processed lines while compiling.

`--autolink'
     Automatically link object files provided by units/modules or `{$L
     ...}' (default).

`--no-autolink'
     Do not automatically link object files provided by
     units/modules/`{$L ...}'.

`--automake'
     Automatically compile changed units/modules/`{$L ...}' files and
     link the object files provided.

`--no-automake'
     Same as `--no-autolink'.

`--autobuild'
     Automatically compile all units/modules/`{$L ...}' files and link
     the object files provided.

`--no-autobuild'
     Same as `--no-autolink'.

`--amtmpfile'
     (Internal switch used for AutoMake).

`--extended-syntax'
     Enable certain `dangerous' features such as ignoring function
     results, pointer arithmetic or using `CString's as strings (same
     as `{$X+}').

`--no-extended-syntax'
     Disable the dangerous features enabled by `--extended-syntax'
     (default; same as `{$X-}').

`--signed-char'
     Let `Char' be a signed type.

`--no-signed-char'
     Let `Char' be an unsigned type.

`--unsigned-char'
     Let `Char' be an unsigned type.

`--no-unsigned-char'
     Let `Char' be a signed type.

`--short-circuit'
     Guarantee short-circuit Boolean evaluation (default; same as
     `{$B-}').

`--no-short-circuit'
     Do not guarantee short-circuit Boolean evaluation (same as
     `{$B+}').

`--mixed-comments'
     Allow comments like `{ ... *)' as required in ISO Pascal (default
     in Standard Pascal mode).

`--no-mixed-comments'
     Ignore `{' and `}' within `(* ... *)' comments and vice versa
     (default).

`--nested-comments'
     Allow nested comments like `{ { } }' and `(* (* *) *)'.

`--no-nested-comments'
     Do not allow nested comments (default).

`--delphi-comments'
     Allow Delphi style `//' comments (default).

`--no-delphi-comments'
     Do not allow Delphi style `//' comments.

`--macros'
     Expand macros (default).

`--no-macros'
     Do not expand macros (default with `--borland-pascal' or
     `--delphi').

`--ignore-function-results'
     Do not complain when a function is called like a procedure.

`--no-ignore-function-results'
     Complain when a function is called like a procedure (default).

`--borland-char-constants'
     Allow for Borland-style character constants like `#27' or `^L'
     (default).

`--no-borland-char-constants'
     Reject Borland-style character constants like `#27' or `^L'
     (default in Standard Pascal mode).

`--truncate-strings'
     Truncate strings being assigned to other strings of too short
     capacity..

`--no-truncate-strings'
     Treat string assignments to other strings of too short capacity as
     errors..

`--exact-compare-strings'
     Do not blank-pad strings for comparisons.

`--no-exact-compare-strings'
     Blank-pad strings for comparisons.

`--io-checking'
     Do automatic run-time checks after I/O operations (same as
     `{$I+}').

`--no-io-checking'
     Do not check I/O operations automatically (same as `{$I-}').

`--write-clip-strings'
     In write statements, truncate strings exceeding their field width
     (`Write (SomeLongString : 3)').

`--no-write-clip-strings'
     Do not truncate strings exceeding their field width.

`--write-real-blank'
     Output a blank in front of positive reals in exponential form
     (default).

`--no-write-real-blank'
     Do not output a blank in front of positive reals in exponential
     form.

`--write-capital-exponent'
     Write real exponents with a capital `E'.

`--no-write-capital-exponent'
     Write real exponents with a lowercase `e'.

`--transparent-file-names'
     Derive external file names from variable names.

`--no-transparent-file-names'
     Do not derive external file names from variable names (default).

`--field-widths'
     Comma-separated list of default field widths for Integer, Real,
     Boolean, LongInt, LongReal.

`--no-field-widths'
     Reset the default field widths.

`--pedantic'
     Warn about everything rejected in some dialect, e.g. redefinition
     of its keywords.

`--no-pedantic'
     Don't give pedantic warnings.

`--stack-checking'
     Enable stack checking (same as `{$S+}').

`--no-stack-checking'
     Disable stack checking (same as `{$S-}').

`--typed-address'
     Make the result of the address operator typed (same as `{$T+}',
     default).

`--no-typed-address'
     Make the result of the address operator an untyped pointer (same
     as `{$T-}').

`--setlimit'
     Define the range for `set of Integer' etc..

`--gpc-main'
     External name for the program's entry point (default: `main').

`--interface-only'
     Compile only the interface part of a unit/module and exit.

`--implementation-only'
     Do not produce a GPI file; only compile the implementation part.

`--executable-file-name'
     Name for the output file, if specified; otherwise derive from main
     source file name.

`--unit-path'
     Directories where to look for unit/module sources.

`--no-unit-path'
     Forget about directories where to look for unit/module sources.

`--object-path'
     Directories where to look for additional object (and source) files.

`--no-object-path'
     Forget about directories where to look for additional object (and
     source) files.

`--executable-path'
     Path where to create the executable file.

`--no-executable-path'
     Create the executable file in the directory where the main source
     is (default).

`--unit-destination-path'
     Path where to create object and GPI files.

`--no-unit-destination-path'
     Create object and GPI files in the current directory (default).

`--object-destination-path'
     Path where to create additional object files.

`--no-object-destination-path'
     Create additional object files in the current directory (default).

`--no-default-paths'
     Do not add a default path to the unit and object path.

`--gpi-destination-path'
     (Internal switch used for AutoMake).

`--uses'
     Add an implicit `uses' clause.

`--cidefine'
     Define a case-insensitive macro.

`--csdefine'
     Define a case-sensitive macro.

`-Wwarnings'
     Enable warnings (same as `{$W+}').

`-Wno-warnings'
     Disable warnings (same as `{$W-}').

`-Wfield-name-problem'
     Warn about ignored field names in initializers (default).

`-Wno-field-name-problem'
     Do not warn about ignored field names in initializers.

`-Wtyped-const'
     Warn about misuse of typed constants as initialized variables
     (default).

`-Wno-typed-const'
     Do not warn about misuse of typed constants as initialized
     variables.

`-Wnear-far'
     Warn about use of useless `near' or `far' directives (default).

`-Wno-near-far'
     Do not warn about use of useless `near' or `far' directives.

`-Wunderscore'
     Warn about double/leading/trailing underscores in identifiers.

`-Wno-underscore'
     Do not warn about double/leading/trailing underscores in
     identifiers.

`-Wmixed-comments'
     Warn about mixed comments like `{ ... *)'.

`-Wno-mixed-comments'
     Do not warn about mixed comments.

`-Wnested-comments'
     Warn about nested comments like `{ { } }'.

`-Wno-nested-comments'
     Do not warn about nested comments.


File: gpc.info,  Node: GPC Options,  Prev: GPC Command Line Options,  Up: Invoking GPC

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
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 units compiled into the directory DIR. The default is the
     current directory.

`--object-destination-path=DIR'
     Place object files compiled 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 (*note Options to Request or
     Suppress Warnings: (gcc)Warning Options.), while `-Wall' only
     warns about such constructs that should be easy to avoid in
     programs. Therefore, we suggest using `-Wall' on most sources.

`-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[=DEFN]'
     Define the macro and conditional MACRO as DEFN (or as `1' if DEFN
     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.

`--standard-pascal-level-0'
`--standard-pascal'
`--extended-pascal'
`--object-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 constructs which would be legal in the specified
     dialect (e.g. assignment to a typed constant with
     `--borland-pascal') are suppressed.

     By default, GNU Pascal allows redefinition of keywords. Each of
     these switches causes GNU Pascal to forbid the redefinition of
     keywords of the specified standard.

     Valid ISO Standard Pascal programs should compile properly with or
     without `--standard-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.


File: gpc.info,  Node: Programming,  Next: Reference,  Prev: Invoking GPC,  Up: Top

The Programmer's Guide to GPC
*****************************

   *This chapter is still under development.*

   This chapter tells you how the source of a valid GNU Pascal program
should look like.  You can use it as tutorial about the GNU Pascal
language, but since the main goal is to document all special GPC
features, implementation-dependent stuff, etc., expect a steep learning
curve.

   This chapter does _not_ cover how to compile your programs and to
produce an executable - this is discussed above in *Note Invoking GPC::.

* Menu:

* Source Structures::            Programs, Units and Modules.
* Data Types::                   Standard and non-standard data types.
* Operators::                    Built-in and user-definable operators.
* Parameters::                   Procedure And Function Parameters
* Pointer Arithmetics::          How pointer arithmetics works in Pascal.
* Type Casts::                   Explicit and emulated type casting in GPC.
* OOP::                          How object-orientated programming is implemented.
* Compiler Directives::          Compiler Directives And The Preprocessor
* Library Routines::             Routines Built-in or in the Run Time System
* Other Languages::              How to share libraries with other languages.
* Notes for Debugging::          Problems and caveats when debugging GPC programs.
* Run Time System::              Pascal declarations for GPC's Run Time System library.
* GPC Units::                    Units included with GPC


File: gpc.info,  Node: Source Structures,  Next: Data Types,  Up: Programming

Source Structures
=================

   A source file accepted by GNU Pascal may contain up to one program,
zero or more ISO-style modules, and/or zero or more UCSD-style units.
Units and modules can be mixed in one project.

* Menu:

* The Program::                 The Source Structure of Programs
* Label Declaration::
* Constant Declaration::
* Type Declaration::
* Variable Declaration::
* Subroutine Declaration::      Procedures, Functions and Operators
* Statements::                  Loops and Conditional Statements
* Modules and Units::           Import Part and Module/Unit Concept

   One trivial example for a valid GPC source file follows. Note that
the code below may either be in one source file, or else the unit and
the program may be in separate source files.

     unit DemoUnit;
     
     interface
     
     procedure Hello;
     
     implementation
     
     procedure Hello;
     begin
       WriteLn ('Hello, world!')
     end;
     
     end.
     
     program UnitDemo;
     
     uses
       DemoUnit;
     
     begin
       Hello
     end.


File: gpc.info,  Node: The Program,  Next: Label Declaration,  Up: Source Structures

The Source Structure of Programs
--------------------------------

   A generic GNU Pascal program looks like the following:

     program NAME (Input, Output);
     
     IMPORT PART
     
     DECLARATION PART
     
     begin
       STATEMENT PART
     end.

   The `program' headline may be omitted in GPC, but a warning will be
given except in `--borland-pascal' mode.

   While the program parameters (usually `Input, Output') are
obligatory in ISO Pascal if you want to use `ReadLn' and `WriteLn',
they are optional in GNU Pascal. GPC will warn about such missing
parameters in `--extended-pascal' mode. However if you give parameters
to the program headline, they work like ISO requires.

   The IMPORT PART consists either of an ISO-style `import'
specification or a UCSD/Borland-style `uses' clause. While `import' is
intended to be used with interfaces exported by ISO-10206 Extended
Pascal modules, and `uses' is intended to be used with units, this is
not enforced. (See also *Note uses::, *Note import::.)

   The DECLARATION PART consists of label, constant, type, variable or
subroutine declarations in free order. However, every identifier must
be declared before it is used. The only exception are type identifiers
pointing to another type identifier which may be declared below.

   The STATEMENT PART consists of a sequence of statements.

   As an extension, GPC supports a "declaring statement" which can be
used in the statement part to declare variables (see *Note var::).


File: gpc.info,  Node: Label Declaration,  Next: Constant Declaration,  Prev: The Program,  Up: Source Structures

Label Declaration
-----------------

   A label declaration has the following look:

     label
       LABEL NAME, ..., LABEL;

   A label declaration part starts with the reserved word `label',
which contains a list of labels.


   *See also* *Note label::, *Note goto::


File: gpc.info,  Node: Constant Declaration,  Next: Type Declaration,  Prev: Label Declaration,  Up: Source Structures

Constant Declaration
--------------------

   A constant declaration has the following look:

     const
       CONSTANT IDENTIFIER = CONSTANT EXPRESSION;
       ...
       CONSTANT IDENTIFIER = CONSTANT EXPRESSION;

   A constant declaration part starts with the reserved word `const'.
It declares a CONSTANT IDENTIFIER which is defined by CONSTANT
EXPRESSION. This expression has to be evaluatable during compilation
time, i.e. it can include numbers, parentheses, predefined operators,
sets and type casts (the last, however, is a Borland extension).  In
ISO-7185 Pascal, CONSTANT EXPRESSION must be a constant or a set. All
Pascal Dialects but ISO-Pascal allow the use of these intrinsic
functions in CONSTANT EXPRESSION:


   *Note Abs::, *Note Round::, *Note Trunc::,


   *Note Chr::, *Note Ord::,


   *Note Length::, *Note Pred::, *Note Succ::,


   *Note SizeOf::, *Note Odd::.


   In Borland Pascal, in the constant declaration part variables can be
declared as well, which are given an initial value. These variables are
called "typed constants". It is good style to avoid this use,
especially since Extended Pascal and GNU Pascal allow to initialize a
variable in variable declaration part or give a type a preset value on
declaration.

     const
       FiveFoo      = 5;
       StringFoo    = 'string constant';
       AlphabetSize = Ord ('Z') - Ord ('A') + 1;
     
     type
       PInteger     = ^Integer;     { Define a pointer to an Integer }
     
     const
       { Constant which holds a pointer to an Integer at address 1234 }
       AddressFoo   = PInteger (1234);

   * BP does not know initialized variables, only typed constants. Even
     worse, it allows them to be misused as variables, without even
     warning. GPC supports this (unwillingly ;-), and warns unless in
     `--borland-pascal' mode.

     An example of a typed constant:

          const
            i : Integer = 0;

     If you want to use it as a constant only, that's perfectly fine.
     However, if you modify `i', we suggest to translate the
     declaration to an initialized variable. The EP syntax is:

          var
            i : Integer value 0;

     GPC supports this as well as the following mixtureof dialects:

          var
            i : Integer = 0;

     Furthermore, you can also assign initialization values to types:

          program InitTypeDemo;
          
          type
            MyInteger = Integer value 42;
          
          var
            i : MyInteger;
          
          begin
            WriteLn (i)
          end.

     Here, all variables of type MyInteger are automatically initialized
     to 0 when created.

   * Arrays initializers look like this in BP:

          program BPArrayInitDemo;
          
          const
            MyStringsCount = 5;
          
          type
            Ident = String [20];
          
          const
            MyStrings : array [1 .. MyStringsCount] of Ident =
              ('export', 'implementation', 'import',
               'interface', 'module');
          
          begin
          end.

     And the following way in EP:

          program EPArrayInitDemo;
          
          {$W no-field-name-problem} { avoid a warning by GPC }
          
          const
            MyStringsCount = 5;
          
          type
            Ident = String (20);
          
          var
            MyStrings : array [1 .. MyStringsCount] of Ident value
              [1 : 'export'; 2 : 'implementation'; 3 : 'import';
               4 : 'interface'; 5 : 'module'];
          
          begin
          end.

     There seem to be pros and cons to each style. GPC supports both as
     well as just about any thinkable mixture of them.

     Some folks don't like having to specify an index since it requires
     renumbering if you want to add a new item to the middle. However,
     if you index by an enumerated type, you might be able to avoid
     major renumbering by hand.


   *See also* *Note Subroutine Parameter List Declaration::


File: gpc.info,  Node: Type Declaration,  Next: Variable Declaration,  Prev: Constant Declaration,  Up: Source Structures

Type Declaration
----------------

   A type declaration looks like this:

     type
       TYPE IDENTIFIER = TYPE DEFINITION;
       ...
       TYPE IDENTIFIER = TYPE DEFINITION;
   or, with preset content:
     type
       TYPE IDENTIFIER = TYPE DEFINITION value CONSTANT EXPRESSION;
       ...
       TYPE IDENTIFIER = TYPE DEFINITION value CONSTANT EXPRESSION;

   A type declaration part begins with the reserved word `type'.  It
declares a TYPE IDENTIFIER which is defined by TYPE DEFINITION.  A type
definition either can be an array, a record, a schema, a set, an
object, a subrange, an enumerated type, a pointer to another type
identifier or simply another type identifier which is to alias.  If a
schema type is to be declared, TYPE IDENTIFIER is followed by a
discriminant enclosed in parentheses:

     TYPE IDENTIFIER (DISCRIMINANT) = SCHEMA TYPE DEFINITION;

   If `value' is specified, followed by a constant satisfying the type
definition, every variable of this type is initialized with CONSTANT
EXPRESSION, unless it is initialized by `value' itself.  The reserved
word `value' can be replaced by `=', however `value' is not allowed in
ISO-Pascal and Borland Pascal, and the replacement by `=' is not
allowed in Extended Pascal.


   Type declaration example:

     type
       { This side is the }     { That side is the }
       { type declaration }     { type definition  }
     
       arrayfoo            = array [0..9] of Integer;  { array definition }
       recordfoo           = record                    { record definition }
                               bar : Integer;
                             end;
     
            { schema def with discriminant ``x,y : Integer'' }
       schemafoo (x,y : Integer) = array [x..y] of Integer;
       charsetfoo          = set of Char;              { Def of a set }
       objectfoo           = object                    { Def of an object }
                               procedure DoAction;
                               constructor Init;
                               destructor Done;
                             end;
       subrangefoo         = -123..456;                { subrange def }
     
       enumeratedfoo       = (Pope,John,the,Second);   { enum type def }
            { Def of a pointer to another type identifier }
       pinteger            = ^arrayfoo;
            { Def of an alias name for another type identifier }
       identityfoo         = Integer;
            { Def of an integer which was initialized by 123 }
       initializedfoo      = Integer value 123;


   *See also*  *Note Type Definition::, *Note Data Types::, *Note
Variable Declaration::


File: gpc.info,  Node: Variable Declaration,  Next: Subroutine Declaration,  Prev: Type Declaration,  Up: Source Structures

Variable Declaration
--------------------

   A variable declaration looks like this:

     var
       VARIABLE IDENTIFIER: TYPE IDENTIFIER;
       ...
       VARIABLE IDENTIFIER: TYPE IDENTIFIER;
   or
     var
       VARIABLE IDENTIFIER: TYPE DEFINITION;
       ...
       VARIABLE IDENTIFIER: TYPE DEFINITION;
   and with initializing value:
     var
       VARIABLE IDENTIFIER: TYPE IDENTIFIER value CONSTANT EXPRESSION;
       ...
       VARIABLE IDENTIFIER: TYPE IDENTIFIER value CONSTANT EXPRESSION;
   or
     var
       VARIABLE IDENTIFIER: TYPE DEFINITION value CONSTANT EXPRESSION;
       ...
       VARIABLE IDENTIFIER: TYPE DEFINITION value CONSTANT EXPRESSION;

   A variable declaration part begins with the reserved word `var'.  It
declares a VARIABLE IDENTIFIER whose type either can be specified by a
type identifier, or by a type definion which either can be an array, a
record, a set, a subrange, an enumerated type or a pointer to an type
identifier.  If `value' is specified followed by a constant expression
satisfying the specified type, the variable declared is initialized with
CONSTANT EXPRESSION.  The reserved word `value' can be replaced by `=',
however `value' is not allowed in ISO-Pascal and Borland Pascal, and the
replacement by `=' is not allowed in Extended Pascal.


   *See also* *Note Type Definition::, *Note Type Declaration::, *Note
Data Types::, *Note The Declaring Statement::, *Note Subroutine
Parameter List Declaration::


File: gpc.info,  Node: Subroutine Declaration,  Next: Statements,  Prev: Variable Declaration,  Up: Source Structures

Subroutine Declaration
----------------------

* Menu:

* The Procedure::
* The Function::
* The Operator::
* Subroutine Parameter List Declaration::


File: gpc.info,  Node: The Procedure,  Next: The Function,  Up: Subroutine Declaration

The Procedure
.............

     procedure PROCEDURE IDENTIFIER;
     DECLARATION PART
     begin
       STATEMENT PART
     end;
   or with a parameter list:
     procedure PROCEDURE IDENTIFIER (PARAMETER LIST);
     DECLARATION PART
     begin
       STATEMENT PART
     end;

   A procedure is quite like a sub-program: The DECLARATION PART
consists of label, constant, type, variable or subroutine declarations
in free order. The STATEMENT PART consists of a sequence of statements.
If PARAMETER LIST is specified, parameters can be passed to the
procedure and can be used in STATEMENT PART. A recursive procedure call
is allowed.


   *See also* *Note The Function::, *Note Subroutine Parameter List
Declaration::


File: gpc.info,  Node: The Function,  Next: The Operator,  Prev: The Procedure,  Up: Subroutine Declaration

The Function
............

     function FUNCTION IDENTIFIER: FUNCTION RESULT TYPE;
     DECLARATION PART
     begin
       STATEMENT PART
     end;
   or with a parameter list:
     function FUNCTION IDENTIFIER (PARAMETER LIST): FUNCION RESULT TYPE;
     DECLARATION PART
     begin
       STATEMENT PART
     end;

   A function is a subroutine which has a return value of type FUNCTION
RESULT TYPE. It is structured like the program: the DECLARATION PART
consists of label, constant, type, variable or subroutine declarations
in free order. The STATEMENT PART consists of a sequence of statements.
If PARAMETER LIST is specified, parameters can be passed to the
function and can be used in STATEMENT PART. The return value is set via
an assignment:
     FUNCTION IDENTIFIER := EXPRESSION
   Recursive function calls are allowed. Concerning the result type,
ISO-7185 Pascal and Borland Pascal only allow the intrinsic types,
subranges, enumerated types and pointer types to be returned. In
Extended Pascal, FUNCTION RESULT TYPE can be every assignable type.  Of
course, there are no type restrictions in GNU Pascal as well.  If
extended syntax is switched on, functions can be called like procedures
via procedure call statement.


   *See also* *Note The Procedure::, *Note Subroutine Parameter List
Declaration::, *Note Data Types::


File: gpc.info,  Node: The Operator,  Next: Subroutine Parameter List Declaration,  Prev: The Function,  Up: Subroutine Declaration

The Operator
............

   GNU Pascal allows to define operators which can be used the infix
style in expressions. For a more detailed description, see *Note
Operators::

