This is ../p/doc/info/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-2002 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: Strings in BP and GPC,  Next: Typed Constants,  Prev: Objects,  Up: Borland Pascal

Strings in BP and GPC
=====================

   Strings are "Schema types" in GNU Pascal which is something more
advanced than Borland-style strings. For variables, you cannot specify
just `String' as a type like in Borland Pascal; for parameters and
pointer types you can. There is no 255 characters length limit.
According to Extended Pascal, the maximum string length must be in
(parentheses); GNU Pascal accepts [brackets], too, however, like BP.

   For more about strings and schema types see *Note Schema Types::.

   GPC supports Borland Pascal's string handling functions and some
more (see *Note String Operations::):

Borland Pascal           GNU Pascal
Length                   Length
Pos                      Pos, Index (1)
Str                      Str, WriteStr (1) (2)
Val                      Val, ReadStr (2)
Copy                     Copy, SubStr, MyStr[2 .. 7] (3)
Insert                   Insert
Delete                   Delete
MyStr[0] := #7           SetLength (MyStr, 7)
=, <>, <, <=, >, >=      =, <>, <, <=, >, >= (4)
                         EQ, NE, LT, LE, GT, GE
n/a                      Trim

   Notes:

   (1) The order of parameters of the Extended Pascal routines
(`Index', `WriteStr') is different from the Borland Pascal routines.

   (2) `ReadStr' and `WriteStr' allow an arbitrary number of arguments,
and the arguments are not limited to numbers.  `WriteStr' also allows
comfortable formatting like `WriteLn' does, e.g.  `WriteStr (Dest, Foo
: 20, Bar, 1/3 : 10 : 2)'.

   (3) `SubStr' reports a runtime error if the requested substring does
not fit in the given string, `Copy' does not (like in BP).

   (4) By default, the string operators behave like in BP. However, if
you use the option `--no-exact-compare-strings' or `--extended-pascal',
they ignore differences of trailing blanks, so, e.g., `'foo'' and `'foo
 '' are considered equal. The corresponding functions (`EQ', ...)
always do exact comparisons.


File: gpc.info,  Node: Typed Constants,  Next: Bit; Byte and Memory Manipulation,  Prev: Strings in BP and GPC,  Up: Borland Pascal

Typed Constants
===============

   GNU Pascal supports Borland Pascal's "typed constants" but also
Extended Pascal's initialized variables:

     var
       x: Integer value 7;

   or

     var
       x: Integer = 7;

   When a typed constant is misused as an initialized variable, a
warning is given unless you specify `--borland-pascal'.

   When you want a local variable to preserve its value, define it as
`static' instead of using a typed constant. Typed constants also become
static automatically for Borland Pascal compatibility, but it's better
not to rely on this "feature" in new programs.  Initialized variables
do not become static automatically.

     program StaticDemo;
     
     procedure Foo;
     { x keeps its value between two calls to this procedure }
     var
       x: static Integer = 0;
     begin
       WriteLn (x);
       Inc (x)
     end;
     
     begin
       Foo;
       Foo;
       Foo;
     end.

   For records and arrays, GPC supports both BP style and Extended
Pascal style initializers. When you initialize a record, you may omit
the field names. When you initialize an array, you may provide indices
with a `:'. However, this additional information is ignored completely,
so perhaps it's best for the moment to only provide the values ...

     program BPInitVarDemo;
     {$W no-field-name-problem}  { avoid a warning by GPC }
     const
       A: Integer = 7;
       B: array [1 .. 3] of Char = ('F', 'o', 'o');
       C: array [1 .. 3] of Char = 'Bar';
       Foo: record
         x, y: Integer;
       end = (x: 3; y: 4);
     begin
     end.


File: gpc.info,  Node: Bit; Byte and Memory Manipulation,  Next: User-defined Operators in GPC,  Prev: Typed Constants,  Up: Borland Pascal

Bit, Byte and Memory Manipulation
=================================

   The bitwise operators `shl', `shr', `and', `or', `xor' and `not'
work in GNU Pascal like in Borland Pascal.  As an extension, you can
use them as procedures, for example

     program AndProcedureDemo;
     var x: Integer;
     begin
       and (x, $0000ffff);
     end.

   as an alternative to

     program AndOperatorDemo;
     var x: Integer;
     begin
       x := x and $0000ffff;
     end.

   GPC accepts the BP style notation `$abcd' for hexadecimal numbers,
but you also can use Extended Pascal notation:

     program EPBaseDemo;
     const
       Binary =  2#11111111;
       Octal  =  8#177;
       Hex    = 16#ff;
     begin
     end.

   and so on up to a basis of 36. Of course, you can mix the notations
as you like, e.g.:

     program BPEPBaseDemo;
     begin
       WriteLn ($cafe = 2#1100101011111110)
     end.

   `Inc' and `Dec' are implemented like in Borland Pascal.  `Pred' and
`Succ' are generalized according to Extended Pascal and can have a
second (optional) parameter:

     procedure SuccDemo;
     var a: Integer = 42;
     begin
       a := Succ (a, 5);
       WriteLn (a) { 47 }
     end.

   BP style `absolute' variables work in the context of overloading
other variables as well as in the context of specifying an absolute
address, but the latter is highly unportable and not very useful even
in Dos protected mode.

     program BPAbsoluteDemo;
     
     type
       TString = String (80);
       TTypeChoice = (t_Integer, t_Char, t_String);
     
     { @@ WARNING: BAD STYLE! }
     procedure ReadVar (var x: Void; TypeChoice: TTypeChoice);
     var
       xInt: Integer absolute x;
       xChar: Char absolute x;
       xStr: TString absolute x;
     begin
       case TypeChoice of
         t_Integer: ReadLn (xInt);
         t_Char   : ReadLn (xChar);
         t_String : ReadLn (xStr);
       end
     end;
     
     var
       i: Integer;
       c: Char;
       s: TString;
     
     begin
       ReadVar (i, t_Integer);
       ReadVar (c, t_Char);
       ReadVar (s, t_String);
       WriteLn (i, ' ', c, ' ', s)
     end.

   GNU Pascal knows Borland Pascal's procedures `FillChar' and `Move'.
However, their use can be dangerous because it often makes implicit
unportable assumptions about type sizes, endianness, internal
structures or similar things. Therefore, avoid them whenever possible.
E.g., if you want to clear an array of strings, don't `FillChar' the
whole array with zeros (this would overwrite the Schema discriminants,
see *Note Strings::), but rather use a `for' loop to assign the empty
string to each string. In fact, this is also more efficient than
`FillChar', since it only has to set the length field of each string to
zero.


File: gpc.info,  Node: User-defined Operators in GPC,  Next: Data Types in BP and GPC,  Prev: Bit; Byte and Memory Manipulation,  Up: Borland Pascal

User-defined Operators in GPC
=============================

   GNU Pascal allows the user to define operators according to the
Pascal-SC syntax:

     program PXSCOperatorDemo;
     
     type
       Point = record
         x, y: Real;
       end;
     
     operator + (a, b: Point) c: Point;
     begin
       c.x := a.x + b.x;
       c.y := a.y + b.y;
     end;
     
     var
       a, b, c: Point = (42, 0.5);
     
     begin
       c := a + b
     end.

   The Pascal-SC operators `+>', `+<', etc. for exact numerical
calculations are not implemented, but you can define them.


File: gpc.info,  Node: Data Types in BP and GPC,  Next: BP Procedural Types,  Prev: User-defined Operators in GPC,  Up: Borland Pascal

Data Types in BP and GPC
========================

   * Integer types have different sizes in Borland and GNU Pascal:

     Borland Pascal      GNU Pascal         Bits (1)     Signed
     ShortInt            ByteInt             8           yes
     Integer             ShortInt           16           yes
     LongInt             Integer            32           yes
     Comp                LongInt, Comp      64           yes
     Byte                Byte                8           no
     Word                ShortWord          16           no
     n/a                 Word               32           no
     n/a                 LongWord           64           no

     (1) The size of the GNU Pascal types may depend on the platform.
     The sizes above apply to 32 bit platforms, including the IA32.

     If you care for types with exactly the same size as in Borland
     Pascal, take a look at the `System' unit and read its comments.

     You can get the size of a type with `SizeOf' in bytes (like in
     Borland Pascal) and with `BitSizeOf' in bits, and you can declare
     types with a specific size (given in bits), e.g.:

          program IntegerSizeDemo;
          type
            MyInt  = Integer (42);  { 42 bits, signed }
            MyWord = Word (2);      { 2 bits, unsigned, i.e., 0 .. 3 }
            MyCard = Cardinal (2);  { the same }
          
            HalfInt = Integer (BitSizeOf (Integer) div 2);
              { A signed integer type which is half as big as the normal
                `Integer' type, regardless of how big `Integer' is
                on any platform the program is compiled on. }
          
          begin
          end.

   * Borland's real (floating point) types are supported except for the
     6-byte software Real type (but the `System' unit provides
     conversion routines for it). GNU Pascals's `Real' type has 8 bytes
     on the IA32 and is the same as `Double'. In addition there are
     alternative names for real types:

     Borland Pascal      GNU Pascal
     Single              Single, ShortReal
     Real                n/a (1)
     Double              Double, Real
     Extended            Extended, LongReal
     Comp                LongInt, Comp (see above)

     (1) But see `BPReal', `RealToBPReal' and `BPRealToReal' in GPC's
     `System' unit.

   * Complex numbers: According to Extended Pascal, GNU Pascal has
     built-in complex numbers and supports a number of mathematical
     functions on them, e.g. `Abs', `Sqr', `SqRt', `Exp', `Ln', `Sin',
     `Cos', `ArcTan'.

   * Record types: GNU Pascal by default aligns 32-bit fields on 4-byte
     addresses because this improves performance. So, e.g., the record
          type
            MyRec = record
              f, o, oo: Boolean;
              Bar: Integer
            end;
     has 8 bytes, not 7. Use the `--pack-struct' option or declare the
     record as `packed' to force GPC to pack it to 7 bytes.  However,
     note that this produces somewhat less efficient code on the IA32
     and far less efficient code on certain other processors.  Packing
     records and arrays is mostly useful only when using large
     structures where memory usage is a real concern, or when reading or
     writing them from/to binary files where the exact layout matters.



File: gpc.info,  Node: BP Procedural Types,  Next: Files,  Prev: Data Types in BP and GPC,  Up: Borland Pascal

BP Procedural Types
===================

   In addition to BP's procedural types, GNU Pascal has pointers to
procedures:

     type
       FuncPtr = ^function (Real): Real;

   The differences between procedure pointers and procedural types are
only syntactical:

   * In the first case, one can pass/assign a procedure/function with
     `@myproc', in the latter case just with `myproc' (which can lead
     to confusion in the case of functions - though GPC should always
     recognize the situation and not try to call the function).

   * In the first case, one can call the routine via `myprocptr^', in
     the latter case just with `myprocvar'.

   * To retrieve the address of a procedure stored in a variable, one
     can use `myprocptr' in the first case and `@myprocvar' in the
     latter.

   * If, for some reason, one needs the address of the variable itself,
     in the first case, that's obtained with `@myprocptr', in the
     second case with `@@myprocvar'!

   * Bottom line: BP style procedural types are simpler to use in normal
     cases, but somewhat strange in the last example.

   One can use both kinds in the same program, of course, though it is
recommended to stick to one kind throughout to avoid maximum confusion.

   GNU Pascal also supports Standard Pascal's procedural parameters
(*note Special Parameters::).

   Furthermore, GNU Pascal allows you to call even local procedures
through procedural pointers, variables or parameters without reverting
to any dirty tricks (like assembler, which is necessary in BP).

   The differences between the various kinds of procedural types,
pointers and parameters are demonstrated in the demo program
`procvardemo.pas'. An example for calling local routines through
procedural parameters can be found in the demo program
`iteratordemo.pas'.


File: gpc.info,  Node: Files,  Next: Built-in Constants,  Prev: BP Procedural Types,  Up: Borland Pascal

Files
=====

   * GPC supports files like in Borland Pascal, including untyped files,
     `BlockRead', `BlockWrite' and `Assign'. Instead of `Assign', you
     can also use the `Bind' mechanism of Extended Pascal.

     Besides the routines supproted by BP, there are many more routines
     available that deal with files, file names and similar things in a
     portable way. In contrast to Borland Pascal, you don't have to use
     any platform-specific units to do these kinds of things, though
     portable emulations of those units (e.g., of the `Dos' and
     `WinDos' units) are also available for compatibility.



File: gpc.info,  Node: Built-in Constants,  Next: Built-in Operators in BP and GPC,  Prev: Files,  Up: Borland Pascal

Built-in Constants
==================

   * The `MaxInt', `MaxLongInt', `Pi' constants are supported like in
     BP.

   * Other built-in constants: GNU Pascal has `MaxChar', `MaxReal',
     `MinReal', `EpsReal' and a number of other useful constants.


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

Built-in Operators in BP and GPC
================================

   Besides the operators found in Borland Pascal, GNU Pascal supports
the following operators:

   * Exponentiation: According to Extended Pascal, GNU Pascal supports
     the exponentiation operators `pow' and `**' which do not exist in
     Borland Pascal. You can use `x pow y' for integer and `x ** y' for
     real or complex exponents. The basis may be integer, real or
     complex in both cases.

   * GNU Pascal has a symmetric set difference operator `set1 >< set2'.
     For more about this, see *Note Set Operations::.


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 and procedure pointers
     (*note BP 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.

   Some of the long options (e.g., `--unit-path') take an argument.
This argument is separated with a `=' sign, e.g.:

     --unit-path=/home/foo/units

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

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

`--classic-pascal'
     Reject anything besides ISO-7185 Pascal.

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

`--standard-pascal'
     Reject anything besides ISO-7185 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.

`--debug-tree'
     (For GPC developers.) Show the internal representation of a given
     tree node (name or address).

`--debug-gpi'
     (For GPC developers.) Show what is written to and read from GPI
     files (huge output!).

`--debug-automake'
     (For GPC developers.) Give additional information about the
     actions of automake.

`--debug-source'
     Output the source while it is processed.

`--no-debug-info'
     Inhibit `-g' options (temporary work-around, this option may
     disappear in the future).

`--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 ISO 7185/10206 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 ISO 7185/10206 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.

`--double-quoted-strings'
     Allow strings enclosed in "\"..

`--no-double-quoted-strings'
     Do not allow strings enclosed in "\"..

`--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-}').

`--read-base-specifier'
     In read statements, allow non-decimal input with `n#' (default).

`--no-read-base-specifier'
     In read statements, do not allow non-decimal input with `n#'
     (default in ISO-7185 Pascal).

`--read-hex'
     In read statements, allow hexadecimal input with `$' (default).

`--no-read-hex'
     In read statements, do not allow hexadecimal input with `$'
     (default in ISO-7185 Pascal).

`--read-white-space'
     In read statements, require whitespace after numbers.

`--no-read-white-space'
     In read statements, do not require whitespace after numbers
     (default).

`--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'
     Reject everything not allowed 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 of Pascal units.

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

`--object-destination-path'
     Path where to create additional object files (e.g. of C files, not
     Pascal units).

`--no-object-destination-path'
     Create additional object files (e.g. of C files, not Pascal units)
     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.

`--init-modules'
     Initialize the named modules in addition to those imported
     regularly; kind of a kludge.

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

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

`--big-endian'
     Tell GPC that the system is big-endian (for those targets where it
     can very).

`--little-endian'
     Tell GPC that the system is little-endian (for those targets where
     it can very).

`--print-needed-options'
     Print the needed options.

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

`-Wobject-directives'
     Warn about unimplemented `private', `protected' and `public'
     directives (default).

`-Wno-object-directives'
     Do not warn about unimplemented `private', `protected' and
     `public' directives.

`-Wimplicit-abstract'
     Warn if an object type not declared `abstract' contains an
     abstract method (default).

`-Wno-implicit-abstract'
     Do not warn if an object type not `declared' abstract contains an
     abstract method.

`-Winherited-abstract'
     Warn if an abstract object type inherits from a non-abstract one
     (default).

`-Wno-inherited-abstract'
     Do not warn warn if an abstract object type inherits from a
     non-abstract one.

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

`-Wsemicolon'
     Warn about a semicolon after @samp{then}, @samp{else} or @samp{do}
     (default).

`-Wno-semicolon'
     Do not warn about a semicolon after @samp{then}, @samp{else} or
     @samp{do}.

