This is ../p/doc/info/gpc.info, produced by makeinfo version 4.6 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.

   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.

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

   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: Trunc,  Next: Truncate,  Prev: True,  Up: Reference

Trunc
=====

Synopsis
--------

     function Trunc (x: Real): Integer;

Description
-----------

`Trunc' returns the integer part of a floating point number as an
integer. Use `Int' to get the integer part as a floating point number.

Conforming to
-------------

`Trunc' is defined in ISO 7185 Pascal and supported by all known Pascal
variants.

Example
-------

     program TruncDemo;
     
     begin
       WriteLn (Frac (12.345) : 1 : 5);  { 0.34500 }
       WriteLn (Int (12.345) : 1 : 5);  { 12.00000 }
       WriteLn (Round (12.345) : 1);  { 12 }
       WriteLn (Trunc (12.345) : 1);  { 12 }
     
       WriteLn (Frac (-12.345) : 1 : 5);  { -0.34500 }
       WriteLn (Int (-12.345) : 1 : 5);  { -12.00000 }
       WriteLn (Round (-12.345) : 1);  { -12 }
       WriteLn (Trunc (-12.345) : 1);  { -12 }
     
       WriteLn (Frac (12.543) : 1 : 5);  { 0.54300 }
       WriteLn (Int (12.543) : 1 : 5);  { 12.00000 }
       WriteLn (Round (12.543) : 1);  { 13 }
       WriteLn (Trunc (12.543) : 1);  { 12 }
     
       WriteLn (Frac (-12.543) : 1 : 5);  { -0.54300 }
       WriteLn (Int (-12.543) : 1 : 5);  { -12.00000 }
       WriteLn (Round (-12.543) : 1);  { -13 }
       WriteLn (Trunc (-12.543) : 1);  { -12 }
     end.

See also
--------

*Note Real Types::, *Note Real::, *Note Int::, *Note Frac::, *Note
Round::.


File: gpc.info,  Node: Truncate,  Next: type,  Prev: Trunc,  Up: Reference

Truncate
========

(Under construction.)

Synopsis
--------

     procedure Truncate (var F: ANY_FILE);

Description
-----------

Conforming to
-------------

`Truncate' is a Borland Pascal extension.

Example
-------

See also
--------


File: gpc.info,  Node: type,  Next: type of,  Prev: Truncate,  Up: Reference

type
====

Synopsis
--------

As a type declaration:
     type
       TYPE_INDENTIFIER = TYPE_DEFINITION;
   or with initialization:
     type
       TYPE_INDENTIFIER = TYPE_DEFINITION value CONSTANT_EXPRESSION;

Description
-----------

The reserved word `type' starts the declaration of a TYPE IDENTIFIER
which is defined by TYPE_DEFINITION. For further description see *Note
Type Declaration::, *Note Type Declaration::, *Note Type Definition::,
*Note Data Types::.

Conforming to
-------------

`type' is defined in ISO 7185 Pascal and supported by all known Pascal
variants. Initializers are an ISO 10206 Extended Pascal extension.

Example
-------

     program TypeDemo;
     type
       { This side is the }    { That side is the }
       { type declaration }    { type definition  }
     
       { array type }
       ArrayType                  = array [0 .. 9] of Integer;
     
       { record type }
       RecordType                 = record
                                      Bar: Integer
                                    end;
     
       { subrange type }
       SubrangeType               = -123 .. 456;
     
       { enumeration type }
       EnumeratedType             = (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
     
       { set type }
       CharSetType                = set of Char;
     
       { object type }
       ObjectType                 = object
                                      constructor Init;
                                      procedure Method;
                                      destructor Done
                                    end;
     
       { pointer type to another type identifier }
       PArrayType                 = ^ArrayType;
     
       { an alias name for another type identifier }
       IntegerType                = Integer;
     
       { an integer which is initialized by 123 }
       InitializedInt             = Integer value 123;
     
       { a schema with discriminants x and y of type Integer }
       SchemaType (x, y: Integer) = array [x .. y] of Integer;
     
     { Dummy methods of the object type }
     constructor ObjectType.Init;
     begin
     end;
     
     procedure ObjectType.Method;
     begin
     end;
     
     destructor ObjectType.Done;
     begin
     end;
     
     begin
     end.

See also
--------

*Note Keywords::, *Note Type Declaration::, *Note Type Definition::,
*Note Data Types::, *Note Variable Declaration::, *Note array::, *Note
record::, *Note object::, *Note set::, *Note Pointer::, *Note value::.


File: gpc.info,  Node: type of,  Next: TypeOf,  Prev: type,  Up: Reference

type of
=======

(Under construction.)

Synopsis
--------

Description
-----------

Conforming to
-------------

Example
-------

See also
--------

*Note Keywords::.


File: gpc.info,  Node: TypeOf,  Next: Unbind,  Prev: type of,  Up: Reference

TypeOf
======

Synopsis
--------

     function TypeOf (var x): PObjectType;

Description
-----------

Returns a pointer to the VMT of an _object_ type or variable.  This
pointer can be used to identify the type of an object.

   `TypeOf' can be applied to expressions of object type and to object
type names. In the former case, the actual type of polymorphic objects
is returned.

Conforming to
-------------

`TypeOf' is a Borland Pascal extension.

Example
-------

     program TypeOfDemo;
     type
       FooPtr = ^Foo;
       BarPtr = ^Bar;
     
       Foo = object         { Has a VMT, though it doesn't }
         x: Integer;        { contain virtual methods.     }
         constructor Init;
       end;
     
       Bar = object (Foo)
         y: Integer;
       end;
     
     constructor Foo.Init;
     begin
     end;
     
     var
       MyFoo: FooPtr;
     
     begin
       MyFoo := New (BarPtr, Init);
       if TypeOf (MyFoo^) = TypeOf (Bar) then  { True }
         WriteLn ('OK')
     end.

See also
--------

*Note BitSizeOf::, *Note AlignOf::, *Note PObjectType::, *Note
SetType::, *Note SizeOf::, *Note OOP::.


File: gpc.info,  Node: Unbind,  Next: unit,  Prev: TypeOf,  Up: Reference

Unbind
======

(Under construction.)

Synopsis
--------

     procedure Unbind (var F: ANY_FILE);

Description
-----------

Conforming to
-------------

`Unbind' is an ISO 10206 Extended Pascal extension.

Example
-------

See also
--------

*Note Bind::, *Note Binding::, *Note BindingType::, *Note bindable::.


File: gpc.info,  Node: unit,  Next: Unpack,  Prev: Unbind,  Up: Reference

unit
====

(Under construction.)

Synopsis
--------

Description
-----------

UCSD and BP style unit declaration.

Conforming to
-------------

`unit' is a UCSD Pascal extension.

Example
-------

See also
--------

*Note Keywords::.


File: gpc.info,  Node: Unpack,  Next: until,  Prev: unit,  Up: Reference

Unpack
======

(Under construction.)

Synopsis
--------

     procedure Unpack (Source: PACKED_ARRAY;
                       var Dest: UNPACKED_ARRAY;
                       FirstElement: INDEX_TYPE);

Description
-----------

Conforming to
-------------

`Unpack' is defined in ISO 7185 Pascal and supported by all known
Pascal variants except UCSD/Borland Pascal and its variants.

Example
-------

See also
--------


File: gpc.info,  Node: until,  Next: UpCase,  Prev: Unpack,  Up: Reference

until
=====

(Under construction.)

Synopsis
--------

Description
-----------

`until' is part of the `repeat ... until' loop statement.

Conforming to
-------------

`until' is defined in ISO 7185 Pascal and supported by all known Pascal
variants.

Example
-------

See also
--------

*Note Keywords::, *Note repeat::, *Note while::, *Note for::.


File: gpc.info,  Node: UpCase,  Next: Update,  Prev: until,  Up: Reference

UpCase
======

(Under construction.)

Synopsis
--------

     function UpCase (Ch: Char): Char;

Description
-----------

Conforming to
-------------

`UpCase' is a Borland Pascal extension.

Example
-------

See also
--------


File: gpc.info,  Node: Update,  Next: uses,  Prev: UpCase,  Up: Reference

Update
======

(Under construction.)

Synopsis
--------

     procedure Update (var F: ANY_FILE);

Description
-----------

Conforming to
-------------

`Update' is an ISO 10206 Extended Pascal extension.

Example
-------

See also
--------


File: gpc.info,  Node: uses,  Next: Val,  Prev: Update,  Up: Reference

uses
====

Synopsis
--------

In a program:

     program @@fragment foo;
     
     uses
       bar1,
       bar2 in 'baz.pas',
       bar3;
     
     [...]

   In a unit:

     unit @@fragment Bar3;
     
     interface
     
     uses
       bar1,
       bar2 in 'baz.pas';
     
     [...]
     
     implementation
     
     uses
       bar3,
       bar4 in 'qux.pas';
     
     [...]

Description
-----------

The reserved word `uses' in the _import part_ of a program or unit
makes the program or unit import an interface.

   The keyword `in' tells GPC to look for the `unit' in the specified
file; otherwise the file name is derived from the name of the
interface, coverted to lower-case, by adding first `.p', then `.pas'.

   There must be at most one import part in a program.

   In a unit, there can be one import part in the interface part and
one in the implementation part.

   The imported interface needn't be a UCSD/Borland Pascal unit, it may
be an interface exported by an Extended Pascal module as well.

Conforming to
-------------

ISO Pascal does not define `uses' and units at all. UCSD and Borland
Pascal do, but without the `in' extension. Delphi supports `uses' like
described above.

Example
-------

See also
--------

*Note Keywords::, *Note unit::, *Note module::, *Note import::.


File: gpc.info,  Node: Val,  Next: value,  Prev: uses,  Up: Reference

Val
===

(Under construction.)

Synopsis
--------

     procedure Val (const Source: String; var x: INTEGER_OR_REAL;
                    var ErrorPosition: Integer);

Description
-----------

`Val' converts the integer or real number that is represented by the
characters in the string `Source' and places it into `x'.

   The `Source' string can have a base prefix (`$' for hexadecimal or
`Base#'). The optional `ErrorCode' will be set to the position of the
first invalid character, or to a 0 if the entire string represents a
valid number. In case an invalid character occurrs in `Source', `x'
will be undefined.

Conforming to
-------------

`Val' is a Borland Pascal extension.

Example
-------

     program ValDemo;
     var
       x, ec: Integer;
       l: LongInt;
       r: Real;
     begin
       Val ('123', x, ec);                { x :=            123; ec := 0; }
       Val ('-123', x, ec);               { x :=           -123; ec := 0; }
       Val ('123.456', r, ec);            { r :=        123.456; ec := 0; }
       Val ('$ffff', x, ec);              { x :=          65535; ec := 0; }
       Val ('$F000', x, ec);              { x :=          61440; ec := 0; }
       Val ('-$ffff', x, ec);             { x :=         -65535; ec := 0; }
       Val ('12#100', x, ec);             { x :=            144; ec := 0; }
       Val ('-2#11111111', x, ec);        { x :=           -255; ec := 0; }
       { here we have the invalid character 'X' for base 16 }
       Val ('$fffeX', x, ec);             { x :=    <undefined>; ec := 6; }
       Val ('12#100invalid', x, ec);      { x :=    <undefined>; ec := 7; }
       Val ('36#Jerusalem', l, ec);       { l := 54758821170910; ec := 0; }
     end.

See also
--------

*Note ReadLn::, *Note ReadStr::, *Note WriteLn::, *Note WriteStr::,
*Note Str::.


File: gpc.info,  Node: value,  Next: var,  Prev: Val,  Up: Reference

value
=====

Synopsis
--------

Description
-----------

The reserved word `value' is part of a type or var declaration.  It can
be replaced by `:=' or `='.

Conforming to
-------------

`value' is an ISO 10206 Extended Pascal extension. `:=' in this context
is a VAX Pascal extension, and `=' is a Borland Delphi extension.

Example
-------

See also
--------

*Note Keywords::, *Note var::, *Note type::, *Note Variable
Declaration::, *Note Type Declaration::.


File: gpc.info,  Node: var,  Next: view,  Prev: value,  Up: Reference

var
===

Synopsis
--------

As part of a variable declaration part or in a statement block:
     var VARIABLE_IDENTIFIER: TYPE_IDENTIFIER;
   or
     var VARIABLE_IDENTIFIER: TYPE_DEFINITION;
   and with initializing value:
     var VARIABLE_IDENTIFIER: TYPE_IDENTIFIER value CONSTANT_EXPRESSION;
   or
     var VARIABLE_IDENTIFIER: TYPE_DEFINITION value CONSTANT_EXPRESSION;

As part of a parameter list (passing by reference):
     var VAR_PARAMETER: TYPE_IDENTIFIER;
   or without type declaration
     var VAR_PARAMETER;

or protected (i.e., the called routine can't modify the parameter):
     protected var VAR_PARAMETER: TYPE_IDENTIFIER;
   or without type declaration
     protected var VAR_PARAMETER;

Description
-----------

In a declaration part: The reserved word `var' declares a
VARIABLE_IDENTIFIER whose type is of TYPE_IDENTIFIER or which is
defined by TYPE_DEFINITION. For further description see *Note Variable
Declaration::, *Note Type Declaration::, *Note Type Definition::, *Note
Data Types::.

   In a parameter list: see *Note Subroutine Parameter List
Declaration::.

Conforming to
-------------

`var' is defined in ISO 7185 Pascal and supported by all known Pascal
variants. Untyped `var' parameters in parameter lists are a UCSD Pascal
extension. The ability to do `var' declarations in a statement block is
a GNU Pascal extension.

Example
-------

     program VarDemo;
     
     type
       FooType = Integer;
     
     var
       Bar: FooType;
       ArrayFoo: array [0 .. 9] of Integer;   { array var definition }
       FecordFoo: record                      { record var definition }
                    Bar: Integer
                  end;
       CharsetFoo: set of Char;               { set var }
       SubrangeFoo: -123 .. 456;              { subrange var }
       EnumeratedFoo: (Mon, Tue, Wed, Thu, Fri, Sat, Sun);  {enumerated var }
       PointerBar: ^FooType;                  { pointer var }
     
     procedure ReadFoo (var Foo: FooType);
     begin
       ReadLn (Foo)
     end;
     
     begin
       var Bar: Integer;  { GNU Pascal extension }
       Bar := 42
     end.

See also
--------

*Note Keywords::, *Note type::, *Note array::, *Note record::, *Note
set::, *Note Subrange Types::, *Note Pointer::, *Note protected::.


File: gpc.info,  Node: view,  Next: virtual,  Prev: var,  Up: Reference

view
====

Not yet implemented.

Synopsis
--------

Description
-----------

Object class view.

Conforming to
-------------

`view' is an Object Pascal extension.

Example
-------

See also
--------

*Note Keywords::.


File: gpc.info,  Node: virtual,  Next: Void,  Prev: view,  Up: Reference

virtual
=======

(Under construction.)

Synopsis
--------

Description
-----------

Virtual object method declaration.

Conforming to
-------------

`virtual' is an Object Pascal and a Borland Pascal extension.

Example
-------

See also
--------

*Note Keywords::.


File: gpc.info,  Node: Void,  Next: while,  Prev: virtual,  Up: Reference

Void
====

(Under construction.)

Synopsis
--------

     type
       Void  { built-in type }

Description
-----------

Conforming to
-------------

`Void' is a GNU Pascal extension.

Example
-------

     program VoidDemo;
     
     procedure p (var x: Void);
     begin
     end;
     
     var
       i: Integer;
       s: String (42);
     
     begin
       p (i);
       p (s)
     end.

See also
--------


File: gpc.info,  Node: while,  Next: with,  Prev: Void,  Up: Reference

while
=====

Synopsis
--------

     while BOOLEAN_EXPRESSION do
       STATEMENT

Description
-----------

The `while' statement declares a loop. For further description see
*Note while Statement::.

Conforming to
-------------

`while' is defined in ISO 7185 Pascal and supported by all known Pascal
variants.

Example
-------

     program WhileDemo;
     var
       Foo, Bar: Integer;
     begin
       WriteLn ('Enter an descending series of integer numbers.');
       WriteLn ('Terminate by breaking this rule.');
       WriteLn ('Enter start number: ');
       Bar := MaxInt;
       ReadLn (Foo);
       while Foo < Bar do
         begin
           Bar := Foo;
           ReadLn (Foo)
         end;
       WriteLn ('The last number of your series was: ', Bar)
     end.

See also
--------

*Note Keywords::, *Note repeat Statement::, *Note for Statement::.


File: gpc.info,  Node: with,  Next: Word,  Prev: while,  Up: Reference

with
====

(Under construction.)

Synopsis
--------

Description
-----------

Automatic `record' or object field access.

Conforming to
-------------

`with' is defined in ISO 7185 Pascal and supported by all known Pascal
variants.

Example
-------

...

   { Note bar is shadowed by foo.bar }  ...

See also
--------

*Note Keywords::.


File: gpc.info,  Node: Word,  Next: WordBool,  Prev: with,  Up: Reference

Word
====

Synopsis
--------

     type
       Word = Cardinal;

Description
-----------

`Word' is the "natural" unsigned integer type in GNU Pascal.  On some
platforms it is 32 bits wide and thus has a range of `0 .. 4294967295'.
It is the same as *Note Cardinal::, introduced for compatibility with
other Pascal compilers.

   There are lots of other integer types in GPC, see *Note Integer
Types::.

Conforming to
-------------

`Word' is defined in Borland Pascal and Borland Delphi, where it is a
16-bit unsigned integer type.

Example
-------

     program WordDemo;
     var
       a: Word;
     begin
       a := 42;
       WriteLn (a)
     end.

See also
--------

*Note Cardinal::, *Note Integer Types::, *Note Subrange Types::.


File: gpc.info,  Node: WordBool,  Next: Write,  Prev: Word,  Up: Reference

WordBool
========

Synopsis
--------

     type
       WordBool = Boolean attribute (Size = BitSizeOf (Word));

Description
-----------

The intrinsic `WordBool' represents boolean values, but occupies the
same memory space as a `Word'.  It is used when you need to define a
parameter or record that conforms to some external library or system
specification.

Conforming to
-------------

`WordBool' is a Borland Pascal extension.

Example
-------

     program WordBoolDemo;
     var
       a: WordBool;
     begin
       Word (a) := 1;
       if a then WriteLn ('Ord (True) = 1')
     end.

See also
--------

*Note Boolean (Intrinsic)::, *Note Boolean::, *Note True::, *Note
False::, *Note CBoolean::, *Note ByteBool::, *Note ShortBool::, *Note
MedBool::, *Note LongBool::, *Note LongestBool::.


File: gpc.info,  Node: Write,  Next: WriteLn,  Prev: WordBool,  Up: Reference

Write
=====

(Under construction.)

Synopsis
--------

     procedure Write (var F: TYPED_FILE; VARIABLE);
or
     procedure Write (var F: Text; VALUES_AND_FORMAT_SPECIFICATIONS);
   or
     procedure Write (VALUES_AND_FORMAT_SPECIFICATIONS);

Description
-----------

Conforming to
-------------

`Write' is defined in ISO 7185 Pascal and supported by all known Pascal
variants.

Example
-------

See also
--------


File: gpc.info,  Node: WriteLn,  Next: WriteStr,  Prev: Write,  Up: Reference

WriteLn
=======

(Under construction.)

Synopsis
--------

     procedure WriteLn (var F: Text; VALUES_AND_FORMAT_SPECIFICATIONS);
or
     procedure WriteLn (VALUES_AND_FORMAT_SPECIFICATIONS);

Description
-----------

Conforming to
-------------

`WriteLn' is defined in ISO 7185 Pascal and supported by all known
Pascal variants.

Example
-------

See also
--------


File: gpc.info,  Node: WriteStr,  Next: xor,  Prev: WriteLn,  Up: Reference

WriteStr
========

(Under construction.)

Synopsis
--------

     procedure WriteStr (var Dest: String; VALUES_AND_FORMAT_SPECIFICATIONS);

Description
-----------

Conforming to
-------------

`WriteStr' is an ISO 10206 Extended Pascal extension.

Example
-------

See also
--------


File: gpc.info,  Node: xor,  Prev: WriteStr,  Up: Reference

xor
===

Synopsis
--------

     operator xor (operand1, operand2: Boolean) = Result: Boolean;
or
     operator xor (operand1, operand2: INTEGER_TYPE) = Result: INTEGER_TYPE;
   or
     procedure xor (var operand1: INTEGER_TYPE; operand2: INTEGER_TYPE);

Description
-----------

In GNU Pascal, `xor' has three built-in meanings:

  1. Logical "exclusive or" between two `Boolean'-type expressions. The
     result of the operation is of `Boolean' type.  (Logical `foo xor
     bar' in fact has the same effect as `foo <> bar'.)

  2. Bitwise "exclusive or" between two integer-type expressions.  The
     result is of the common integer type of both expressions.

  3. Use as a "procedure": `operand1' is "xor"ed bitwise with
     `operand2'; the result is stored in `operand1'.


Conforming to
-------------

ISO Pascal does not define the `xor' operator; Borland Pascal and
Delphi do.

   Use of `xor' as a "procedure" is a GNU Pascal extension.

Example
-------

     program XorDemo;
     var
       a, b, c: Integer;
     begin
       if (a = 0) xor (b = 0) then
         c := 1  { happens if either `a' or `b' is zero,    }
                 { but not if both are zero or both nonzero }
       else if (a xor b) = 0 then  { bitwise xor }
         c := 2  { happens if a = b }
       else
         xor (c, a)  { same as `c := c xor a' }
     end.

See also
--------

*Note Keywords::, *Note and::, *Note or::, *Note Operators::.


File: gpc.info,  Node: Keywords,  Next: Support,  Prev: Reference,  Up: Top

Pascal keywords and operators supported by GNU Pascal.
******************************************************

This chapter lists all keywords understood by GNU Pascal. The keywords
are taken from the following standards and dialects:

   * ISO 7185 Pascal (CP)

   * ISO 10206 Extended Pascal (EP)

   * ANSI draft Object Pascal (OP)

   * UCSD Pascal (UCSD)

   * Borland Pascal 7.0 (BP)

   * Borland Delphi (BD)

   * Pascal-SC (PXSC, Pascal eXtensions for Scientific Calculations)

   * VAX Pascal (VP)

   * Sun Pascal (SP)

   * Traditional Macintosh Pascal (MP)

   * GNU Pascal extensions (GPC)

   The table below lists all known keywords with short descriptions.
The links point to the longer descriptions in the reference.

   By default (using GPC extensions) all keywords are enabled. Only
those are marked `GPC' in the table below that are valid _only_ in the
GPC extensions.

   All keywords that are specific to some dialects (i.e., not marked
"any") can also be used as identifiers (with a few exceptions, see
below). Then, however, they generally cannot be used as keywords
anymore. So you can compile code from dialects that use them as
keywords and code that uses them as identifiers, i.e., you do not have
to modify your correct ISO 7185 programs in order to compile them with
GPC without any dialect option. Some words can even be used as keywords
and identifiers in parallel, including `forward' (according to ISO 7185
Pascal), and `near' and `far' (according to Borland Pascal).

   The exceptions are:

   * `Operator' can't be used as a type, untyped constant or exported
     interface, i.e. when it would be followed by `=' (unless it's
     disabled as a keyword explicitly or by dialect options, see
     below). This is because of a conflict with a definition of the
     operator `='. (It can be used as a typed constant, but it might be
     confusing if you later decide to make it untyped, so use with
     care.)

   * The first statement after `initialization' (Delphi specific unit
     initialization) must not start with `('.  (Statements starting
     with `(' are uncommon, anyway, but not impossible.) This does not
     restrict the usage of `Initialization' as an identifier.

   * The following keywords can't be used _immediately_ after an
     `import' part: `uses', `implementation', `operator',
     `constructor', `destructor'. Using `uses' instead of `import', or
     putting some other declaration between `import' and the
     problematic keyword helps.

   A dialect option turns off all keywords that do not belong to this
dialect. Besides, any keyword can be enabled and disabled with the
compiler options `{$enable-keyword}' and `{$disable-keyword}'.

absolute (BP, BD) (*note absolute::)
     overloaded variable declaration

abstract (OP) (*note abstract::)
     abstract object type or method declaration

all (all) (*note all::)
     `export' (*note export::) extension (`export foo = all')

and (any) (*note and::)
     Boolean or bitwise `and' operator or part of the `and then' (*note
     and then::) operator

and_then (EP, OP) (*note and_then::)
     short-circuit Boolean `and' (*note and::) operator

array (any) (*note array::)
     array type declaration

as (OP, BD) (*note as::)
     object type membership test and conversion

asm (BP, BD) (*note asm::)
     GNU style inline assembler code

asmname (GPC) (*note asmname::)
     DEPRECATED! linker name of routines and variables

attribute (GPC) (*note attribute::)
     attributes of routines and variables

begin (any) (*note begin::)
     begin of a code block, part of a `to begin do' (*note to begin
     do::) module constructor

bindable (EP, OP) (*note bindable::)
     external bindability of files

c (GPC) (*note c::)
     DEPRECATED! declaration of external routine

case (any) (*note case::)
     multi-branch conditional statement or variant `record' (*note
     record::) type

c_language (GPC) (*note c_language::)
     DEPRECATED! declaration of external routine

class (OP, BD) (*note class::)
     OOE/Delphi style object class (not yet implemented)

const (any) (*note const::)
     constant declaration or constant parameter declaration

constructor (OP, BP, BD) (*note constructor::)
     object constructor

destructor (OP, BP, BD) (*note destructor::)
     object destructor

div (any) (*note div::)
     integer division operator

do (any) (*note do::)
     part of a `while' (*note while::) or `for' (*note for::) loop, a
     `with' (*note with::) statement, or a `to begin do' (*note to
     begin do::) or `to end do' (*note to end do::) module constructor
     or destructor

downto (any) (*note downto::)
     part of a `for' (*note for::) loop counting downwards

else (any) (*note else::)
     alternative part of an `if' (*note if::) statement, default `case'
     (*note case::) branch, part of the `or else' (*note or else::)
     operator

end (any) (*note end::)
     end of a code block, end of a `case' (*note case::) statement, end
     of a `record' (*note record::) or `object' (*note object::)
     declaration, part of a `to end do' (*note to end do::) module
     destructor

export (export) (*note export::)
     module interface export

exports (BP, BD) (*note exports::)
     library export (not yet implemented)

external (UCSD, BP, BD, MP) (*note external::)
     declaration of an external object

far (BP, BD) (*note far::)
     BP directive (ignored)

file (any) (*note file::)
     non-text file type declaration

finalization (BD) (*note finalization::)
     unit finalization

for (any) (*note for::)
     loop statement where the number of loops is known in advance

forward (any) (*note forward::)
     declaration of a routine whose definition follows below

function (any) (*note function::)
     function declaration

goto (any) (*note goto::)
     statement to jump to a `label' (*note label::)

if (any) (*note if::)
     conditional statement

implementation (all except CP) (*note implementation::)
     module or unit implementation part

import (EP, OP) (*note import::)
     module interface import

in (any) (*note in::)
     set membership test or part of a `for' (*note for::) loop
     iterating through sets

inherited (OP, BP, BD, MP) (*note inherited::)
     reference to methods of ancestor object types

initialization (BD) (*note initialization::)
     unit initialization

interface (interface) (*note interface::)
     module or unit interface part

interrupt (BP, BD) (*note interrupt::)
     interrupt handler declaration (not yet implemented)

is (OP, BD) (*note is::)
     object type membership test

label (any) (*note label::)
     label declaration for a `goto' (*note goto::) statement

library (BP, BD) (*note library::)
     library declaration (not yet implemented)

mod (any) (*note mod::)
     integer remainder operator

module (module) (*note module::)
     EP style or PXSC style module

name (name) (*note name::)
     linker name

near (BP, BD) (*note near::)
     BP directive (ignored)

nil (any) (*note nil::)
     reserved value for unassigned pointers

not (any) (*note not::)
     Boolean or bitwise negation operator

object (BP, BD, MP) (*note object::)
     BP style object declaration

of (any) (*note of::)
     part of an `array' (*note array::), `set' (*note set::) or typed
     `file' (*note file::) type declaration, a `case' (*note case::)
     statement, a variant `record' (*note record::) type or a `type of'
     (*note type of::) type inquiry

only (EP, OP) (*note only::)
     import specification

operator (PXSC) (*note operator::)
     operator declaration

or (any) (*note or::)
     Boolean or bitwise `or' operator or part of the `or else' (*note
     or else::) operator

or_else (EP, OP) (*note or_else::)
     short-circuit Boolean `or' (*note or::) operator

otherwise (EP, OP, MP) (*note otherwise::)
     default `case' (*note case::) branch, default value in a
     structured value of `array' (*note array::) type

packed (any) (*note packed::)
     declaration of packed structured types (`record' (*note record::),
     `array' (*note array::), `set' (*note set::), `file' (*note
     file::)), also packed ordinal subranges

pow (EP, OP) (*note pow::)
     exponentiation operator with integer exponent

private (private) (*note private::)
     private object fields

procedure (any) (*note procedure::)
     procedure declaration

program (any) (*note program::)
     start of a Pascal program

property (OP, BD) (*note property::)
     object properties (not yet implemented)

protected (protected) (*note protected::)
     read-only formal parameters or module export and protected object
     fields

public (public) (*note public::)
     public object fields

published (published) (*note published::)
     published object fields

qualified (qualified) (*note qualified::)
     import specification

record (any) (*note record::)
     record type declaration

repeat (any) (*note repeat::)
     loop statement

resident (BP, BD) (*note resident::)
     library export specification (not yet implemented)

restricted (EP, OP) (*note restricted::)
     restricted type specification

segment (UCSD) (*note segment::)
     segment specification (not yet implemented)

set (any) (*note set::)
     set type declaration

shl (BP, BD, MP) (*note shl::)
     bitwise left shift operator

shr (BP, BD, MP) (*note shr::)
     bitwise right shift operator

then (any) (*note then::)
     part of an `if' (*note if::) statement or part of the `and then'
     (*note and then::) operator

to (any) (*note to::)
     part of a `for' (*note for::) loop counting upwards or a `to begin
     do' (*note to begin do::) or `to end do' (*note to end do::)
     module constructor or destructor

type (any) (*note type::)
     type declaration or part of a `type of' (*note type of::) type
     inquiry

unit (UCSD, BP, BD, MP) (*note unit::)
     UCSD and BP style unit declaration

until (any) (*note until::)
     end of a `repeat' (*note repeat::) statement

uses (UCSD, BP, BD, MP) (*note uses::)
     unit import

value (EP, OP) (*note value::)
     variable/type initializer

var (any) (*note var::)
     variable declaration or reference parameter declaration

view (OP) (*note view::)
     object class view (not yet implemented)

virtual (OP, BP, BD, MP) (*note virtual::)
     virtual object method declaration

while (any) (*note while::)
     loop statement

with (any) (*note with::)
     automatic `record' (*note record::) or object field access

xor (BP, BD, MP) (*note xor::)
     Boolean or bitwise `exclusive or' operator


File: gpc.info,  Node: Support,  Next: To Do,  Prev: Keywords,  Up: Top

Where to get support for GNU Pascal; how to report bugs.
********************************************************

   Here you can find information on where to find the most up-to-date
information about GPC, how you can get support (professional or
voluntary), how to use GPC's Test Suite, and how to report new bugs you
might encounter.

   If you have problems with GNU Pascal, please read the relevant
sections of the GPC Manual. The most current version of the manual is
available at `http://www.gnu-pascal.de/gpc/index.html' for online
browsing.  You can also download the complete manual in HTML format
(tar.bz2) (`gpc-html.tar.bz2' on GPC's WWW home page).  The manual is
also available in DVI format (compressed with bzip2) (`gpc.dvi.bz2' on
GPC's WWW home page) and PostScript format (compressed with bzip2)
(`gpc.ps.bz2' on GPC's WWW home page) for printing.

   If the manual doesn't help you, here is what we recommend you to do:

*Note FAQ::                Check the GPC FAQ

* Menu:

* Mailing List::           Join the GPC Mailing List
* Mailing List Archives::  Look in the Mailing List Archives
* Newsgroups::             Ask in a newsgroup
* Professional Support::   Get individual support for GPC
* Compiler Crashes::       If the compiler crashes ...
* Reporting Bugs::         Find out how to report GPC bugs
* Testing::                If you have GPC sources, learn how to run
                           the Test Suite to test your bugs reported


File: gpc.info,  Node: Mailing List,  Next: Mailing List Archives,  Up: Support

The GPC Mailing List
====================

There is a mailing list devoted to GNU Pascal. You can write to the
mailing list, e.g. if you have problems installing GPC or if you found
a problem with GPC (please see *Note Reporting Bugs::). You can also
use it to discuss suggestions for improving GPC and, most welcome, to
offer your help or contribute code, documentation or other work. Mails
to the list should be in English.

   To subscribe to the mailing list, send the command
     subscribe gpc your@email.address
   in the body of a mail to <majordomo@gnu.de> (*not* to
`gpc@gnu.de'!). The subject is ignored. (Please replace
`your@email.address' with your real email address.) For more info, send
a line `help' to <majordomo@gnu.de>.

   After subscribing, you can send a message to the mailing list by
sending email to the list address <gpc@gnu.de> as if it were a person.

   To leave the mailing list, send the command
     unsubscribe gpc your@email.address
   to <majordomo@gnu.de>.

   You can reach a human moderator at _gpc-owner@gnu.de_.

   There is a separate mailing list for discussions about GPC
documentation, <gpc-doc@gnu.de>. To subscribe, send the command
     subscribe gpc-doc your@email.address
   to <majordomo@gnu.de>.

   There is also a (low-traffic) announce list, <gpc-announce@gnu.de>
that you can subscribe to stay up-to-date. To subscribe to the list,
write an email with
     subscribe gpc-announce your@email.address
   in the body to <majordomo@gnu.de>. If you like to announce a
contribution, a service or an event related to GPC, you are invited to
post to this list rather than `gpc@gnu.de', but please don't use the
announce list for questions or discussions. Please note that all mail
sent to the announce list is forwarded to the regular list, so you
won't have to subscribe to both lists if you don't want to miss
anything. For the same reason, please don't cross-post to both lists.

   There is also a German speaking mailing list, <gpc-de@gnu.de>. To
subscribe send the command
     subscribe gpc-de your@email.address
   in the body of a mail to <majordomo@gnu.de> (note the hints above).


File: gpc.info,  Node: Mailing List Archives,  Next: Newsgroups,  Prev: Mailing List,  Up: Support

The GPC Mailing List Archives
=============================

Perhaps your problem was already discussed on the list. There is a
searchable archive of the mailing list on the WWW. It can be browsed or
searched at
     `http://www.gnu-pascal.de/crystal/gpc/en/'

   The archive of the documentation list is at
     `http://www.gnu-pascal.de/crystal/gpc-doc/en/'

   The archive of the announce list is at
     `http://www.gnu-pascal.de/crystal/gpc-announce/en/'

   The archive of the German GPC list is at
     `http://www.gnu-pascal.de/crystal/gpc-de/de/'


File: gpc.info,  Node: Newsgroups,  Next: Professional Support,  Prev: Mailing List Archives,  Up: Support

Newsgroups relevant to GPC
==========================

To get support, you can also ask the Usenet newsgroups for help.  There
are several Pascal related newsgroups, but none is dedicated just to
GNU Pascal, so use the one which is most appropriate for your problem.
For general Pascal questions, we recommend the following one:

`news://comp.lang.pascal.misc'       Pascal in general and ungrouped
                                     Pascals.

   Pascal syntax related questions may be appropriate in:

`news://comp.lang.pascal.ansi-iso'   Pascal according to ANSI and ISO
                                     standards.

   The next newsgroup is a haven for beginners, answering questions
that would apply to almost any Pascal. However, if you have a
GPC-specific question don't post there - use the GPC mailing list.  And
when in doubt use the GPC mailing list.

`news://comp.lang.pascal.borland'    Borland Pascal questions.

   Don't forget to give back what you have obtained. None of us is
getting money for answering your questions (unless you pay us by
yourself). Please do your part by answering the questions of others
instead.


File: gpc.info,  Node: Professional Support,  Next: Compiler Crashes,  Prev: Newsgroups,  Up: Support

Where to get individual support for GPC
=======================================

GPC is free software and comes *without any warranty*.

   If you want to get professional support, you can hire an individual
or a company for providing such a service.

   G-N-U GmbH (http://www.g-n-u.de) is doing large parts of the
development of GNU Pascal. This company offers special support for GPC
and can be contacted at <info@g-n-u.de>.

   More generally, to find a company or an individual who offers
support and other consulting services for free software, look into the
GNU Service Directory (http://www.gnu.org/prep/service.html).


File: gpc.info,  Node: Compiler Crashes,  Next: Reporting Bugs,  Prev: Professional Support,  Up: Support

If the compiler crashes ...
===========================

If the compiler crashes, you have discovered a bug. A reliable compiler
never crashes. To help the maintainers fix this bug, it is important
that you send us a problem report.

   If you're on Unix, you can find out where the compiler crashed if
you enable coredumps, then load the compiler (`gpc1') plus the core
file in the debugger (`gdb /your_path_here/gpc1 core'), then type
`backtrace' to get a stacktrace. Include this stacktrace in your bug
report.


File: gpc.info,  Node: Reporting Bugs,  Next: Testing,  Prev: Compiler Crashes,  Up: Support

How to report GPC bugs
======================

If you encounter a bug with GPC, please check whether it is one of the
known bugs (*note Known Bugs::). If not, please report it to the GNU
Pascal mailing list (*note Mailing List::). That way, they always reach
the maintainers. Please note the following points.

   * Please send a description of the problem. Try to give as much
     information as possible, with the full text of any error messages
     encountered, or a description of how some output varies from the
     expected output. Always specify the operating system type with
     version and the machine type (try `uname -a' if unsure) as well as
     the version of GPC which you get by typing `gpc -v'.

   * A good article on submitting bug reports can be found at either
     `http://www.chiark.greenend.org.uk/~sgtatham/bugs.html' or
     `http://freshmeat.net/news/2000/02/26/951627540.html'

     Another good article "How To Ask Questions The Smart Way" is
     available as `http://www.catb.org/~esr/faqs/smart-questions.html'

     *Please note that the authors of these articles have no relation
     to GPC and will not help you with your problems! The articles
     contain general hints about how to report problems well.*


   If the problem is with the compiler itself, not an installation
problem or something like this, please provide a test program to
reproduce the problem, and note the following hints. You can also
contribute test programs for features that are working in GPC to ensure
they will not break in future releases.

   * The test program should be as short as possible, but *by all
     means*, please send a *complete* program and *make sure* that it
     still reproduces the problem before you send it. Too often, users
     have sent code which contained obvious syntax errors far before
     the actual problem, or just code fragments that we could only make
     wild guesses about. This is unproductive for us and doesn't help
     you get your problem solved.


   The preferred form for test programs is the form that the automated
GPC Test Suite understands. Please, if at all possible, send your test
programs in this form which should be easy to do, so we won't have to
waste our time to bring them into this form, and can concentrate on
fixing the problem.

   * The file containing the main program _must_ have a name ending
     with `.pas' and contain the keyword `program' (case-insensitively)
     and a `;' in the same line to be recognized by the Test Suite at
     all. Other files whose name ends in `.pas' (e.g., units or modules
     needed by the program), must not contain this.

   * Since the Test Suite must run under very ... nah ... strange
     operating systems, too, file names must be distinguished in their
     first eight characters (case-insensitively) and should not contain
     anything but letters, numbers, hyphens, underscores and a single
     dot. Furthermore, any ancillary files (units, modules, includes,
     data files) should not be longer than "8+3" characters; the same
     applies to the names of unit/module interfaces (because GPC will
     create `.gpi' file names based on those). It is often a good idea
     to use your name, nickname or initials followed by a number as the
     file name.

   * If your test program needs any units or modules, don't give them
     (or their interfaces in case of modules) common names like `Test',
     `Foo' or `MyUnit', unless you have very special reasons to,
     because there might be subtle problems if several test programs
     use the same name. Instead, it is recommended to prefix the
     unit/module/interface names with the name of the main test program
     or an abbreviation of it (if necessary because of the file name
     restrictions). Furthermore, please avoid the use of units and
     modules at all if the bug is not specific to them, in order to keep
     the test as simple as possible.

   * The test program, when run, should produce a line of output
     consisting of the string `OK' (followed by a newline) if
     everything went as expected, and something else (e.g. `failed',
     possibly followed by the reason of failure) if something went
     wrong.  In the latter case you might want to output additional
     information such as the values of important variables or an
     indication in which place the program failed if there are several
     possible places.

   * However, if the program is intended to check whether GPC catches an
     (intentional) compile-time error in the program, place the string
     `WRONG' somewhere in the test program, preferably in a comment in
     the line that contains the intentional error. `WRONG' tests will
     be run with the option `-w' to suppress all warnings, so only real
     errors will be detected.

     *Please note:* While it is possible to combine several `OK' tests
     in a single test program (if you make sure that it outputs `OK'
     only if all tests pass), you cannot put several `WRONG' tests into
     one test program. This is because the compiler will fail (and the
     test therefore be regarded as successful) already if _one_ error
     occurs. So, for `WRONG' tests, do only one check per test program.
     Also, try to keep such a test program as small and simple as
     possible, to avoid the risk that it will fail because of other
     problems (and therefore the test be mistakenly considered
     successful).

   * If the test should merely provoke a GPC warning, use `WARN'
     instead of `WRONG'. This will run the test without `-w', but with
     `-Werror'. However, such tests will also appear to succeed if they
     produce a compiler error, not only a warning.  Therefore, when
     checking for a warning, it is often a good idea to provide a
     complementary test (with expected success) and with `-w' in `FLAG'
     or a compiler directive `{$W-}' to make sure that it's really just
     a warning, not an error.

   * Runtime errors must be detected by the test itself. One way to do
     so is to insert code like the following into your test program:

          uses GPC;
          
          procedure ExpectError;
          begin
            if ExitCode = 0 then
              WriteLn ('failed')
            else
              begin
                WriteLn ('OK');
                Halt (0)
              end
          end;
          
          begin
            AtExit (ExpectError);
            { Your code which should provoke a runtime error }
          end.

   * For a test that reproduces an existing problem (which is not
     expected to be fixed soon), please put a comment at the top that
     describes the problem in a few words, and start it with `BUG'.
     This is not required by the test scripts, it's just to make it
     easier for those who will try to fix the problem to see immediately
     what the test is about. Tests for new (planned) features should not
     say `BUG'.


   The following special features of the Test Suite may be helpful for
constructing slightly unusual tests:

   * If the expected output is something else than `OK', place it in a
     file `<basename>.out' (where `<basename>' is the name of the test
     program without the `.pas' extension).

   * If the test program expects some input, place it in a file
     `<basename>.in'. It will automatically be redirected to the
     program's standard input.

   * If the test needs some special flags to be given to the GPC command
     line, place them in a comment preceded by `FLAG', e.g.:

          { FLAG --extended-pascal -Werror }

   * If the test program creates a file, use `.dat' as a file name
     suffix and no directory (the Makefiles will remove such files in
     the `mostlyclean' etc. targets) and do not assume that this file
     exists, does not exist, or anything else about it when the test
     starts. If possible, use an internal (unnamed) file, so these
     issues will not apply.

   * The source file name of the test program will be passed as the
     first command-line argument to the test program run.

   * If a test needs to be run in a special way, you can accompany the
     program with a script `<basename>.run' that will do the actual
     test after the test program was compiled. This script will be run
     by `sh' (regardless of its first line). In order to be portable,
     it should only use standard tools and features present in all `sh'
     compatible shells (e.g., `ash', `bash', but not necessarily
     `csh'). The source file name of the test program will be passed as
     the first command-line argument to the run script in this case.
     The compiled file is called `./a.out' on most systems, but, e.g.,
     `./a.exe' on Cygwin. The environment variable `A_OUT' contains the
     base name (i.e., `a.out' or `a.exe', so you can always invoke the
     program as `./"$A_OUT"').

   * If a test needs to be compiled in a special way (e.g., to decide
     whether to skip the test), place the commands in a script
     (preferably called `<basename>.cmp'), and put the file name of the
     script (without directory) in a comment preceded by `COMPILE-CMD:'
     into the source of the test program. The compile script will be
     run *instead* of the compiler and any other action otherwise done
     for this test program, so it gives you maximum flexibility to do
     whatever you need to do. This script will be run by `sh'
     (regardless of its first line). In order to be portable, it should
     only use standard tools and features present in all `sh'
     compatible shells (see above). The first command-line argument to
     the compile script will be the compiler to use, including all
     options. The second argument will be the source file name of the
     test program. For some typical tests, there are standard compile
     scripts, e.g. `asmtest.cmp' which will skip the test unless run on
     a platform supported by the few tests that contain `asm'
     statements. Of course, it's generally better not to have to use
     such scripts when possible.

   * In some cases you may want to write _randomized_ tests. This is
     not usually recommended since it makes problems found harder to
     reproduce, but sometimes it might be useful (e.g., if you want to
     cover a large parameter space). In such a case, the following
     strategy can be used:

          ...
          
          uses GPC;
          
          var
            RandomSeed: Integer;
          
          begin
            RandomSeed := Random (MaxInt);
            SeedRandom (RandomSeed);
          
            ... { do your normal tests }
          
            { when printing an error message: }
            if ... then
              begin
                WriteLn ('failed (', RandomSeed, ') ',
                         ... { possibly additional information } );
                Halt
              end
          end.

     This is a little unnatural since a random number is used to
     (re-)seed the random number generator, but there's currently no way
     to retrieve the internal state of the random number generator (and
     in fact, it's not represented by a single number, but by a large
     array).

     Given the value of `RandomSeed' in an error message, it should
     then be possible to reproduce the problem by inserting this value
     in place of the `Random (MaxInt)'. Just be sure to print this
     value in *every* message of failure the program may produce.



File: gpc.info,  Node: Testing,  Prev: Reporting Bugs,  Up: Support

Running the GPC Test Suite
==========================

_Note:_ If you have installed a GPC binary distribution, you usually
don't have the Test Suite installed (you can download the GPC source
distribution to get it, however), so this section does not apply to
you. Still, you can find in the section `Contributing Tests to the Test
Suite' how to report GPC bugs in the form of new test programs so we
can fix them as fast as possible.

   The files in the test directory and subdirectories are for testing
GPC only and should not be of any other use.

   Note: A few of the tests do not make sense on all systems. They are
equipped with checks and will be skipped if they find the system not
suitable. Skipped tests do *not* indicate a GPC bug, unless you have a
reason to be sure that the particular test should make sense on your
system.

   * To run the whole Test Suite, type `make' in the test directory (or
     `make check' in the `p' object directory after building GPC).

   * The output will show all errors encountered (hopefully none) and
     tests skipped, and finally display a summary giving the number of
     successful, failed and skipped tests. Any failed test indicates a
     bug in GPC which should be reported to the GPC mailing list,
     <gpc@gnu.de>. Don't forget to mention the operating system you ran
     the test on and any other relevant information about what you did.

   * You can also type `make pascal.check-long' to get a long output
     which is a sequence of file names followed by `OK' for successful
     tests, `SKIPPED' for skipped tests (both in capital letters), and
     anything else for failed tests.

   * To run only some of the tests, you can type something like `make
     MASK="foo[1-7]*.pas"' or `make MASK="foo42.pas" pascal.check-long'.

   * To clean up after running the tests, type `make clean'.



File: gpc.info,  Node: To Do,  Next: Internals,  Prev: Support,  Up: Top

The GNU Pascal To-Do List.
**************************

This is the To-Do list for the GNU Pascal Compiler.

   The GNU Pascal development team is constantly working on making GNU
Pascal more reliable and more comfortable. However, there are some
known bugs which will take some time to be fixed (any help welcome!),
and we do not want to hide them from you. You might also be interested
to know what features are planned to be implemented in the future. This
list is meant to keep track of the known bugs and wanted features of
GPC.

   If you want to report a new bug or suggest a new feature, the best
way to do it is in the mailing list. This way, other GPC users can
provide additional ideas, perhaps work-arounds for bugs, and the GPC
maintainers can sooner start to think about how to solve the problem.
The GPC mailing list is <gpc@gnu.de>. To subscribe, send the command
`subscribe gpc your@email.address' in the body of a mail to
<majordomo@gnu.de> (the subject is ignored). An archive of the mailing
list can be found at `http://www.gnu-pascal.de/crystal/gpc/en/'.

   The list changes regularly. The present version refers to the
current GPC snapshot, 20041218.

   This list is part of the GNU Pascal Manual, included in GPC
distributions and snapshots. You can always browse the most current
version of the list on GPC's WWW page. If you check the To-Do list
regularly you can decide if and when to try a new snapshort.

* Menu:

* Known Bugs::        Known bugs in GPC
* Planned Features::  Features planned for GPC
* Fixed Bugs::        Fixed bugs


File: gpc.info,  Node: Known Bugs,  Next: Planned Features,  Up: To Do

Known bugs in GPC
=================

In this section, you can find information about GPC bugs that are known
to the developers.

   If you encounter a bug with GPC, please check whether it is one of
the known bugs. If not, report it to the GNU Pascal mailing list.  (But
always report if you solve the problem! :-)

   Solved problems are moved to "Fixed Bugs" (*note Fixed Bugs::), and
implemented features to the "News" chapter (*note News::).

   A message ID (like `<42@foo.bar>') refers to a message in the GPC
mailing list or a newsgroup where the topic was discussed (often a bug
report). A note of the form `(xy20001231)' refers to an internal
message of the GPC developers. A file name like `(foo42.pas)' refers to
the according program in the GPC test suite included in the GPC source
distribution.

   * `setlimit' is applied when it shouldn't be ((a) variable/constant
     declarations, (b) `set of ShortCard', (c) constant sets)

   * problem with string operations and `goto' (contourbug.pas,
     martin1.pas, berend3.pas)

   * global variables of dynamic size don't work (john1.pas)

   * declaring a procedure in the implementation with the same name as
     an imported procedure doesn't work (chief18.pas), detect name
     collisions between imported EP modules (mod9.pas)

   * dynamic sets don't work

   * there are some bugs with mathematical functions; GPC fails, for
     example, the Paranoia test

   * check `goto' targets more strictly
     <261020020000077022%gpaeper@empirenet.com>,
     <Pine.LNX.4.44.0210281004000.31943-100000@duch.mimuw.edu.pl>
     (fjf701*.pas)


File: gpc.info,  Node: Planned Features,  Next: Fixed Bugs,  Prev: Known Bugs,  Up: To Do

Features planned for GPC
========================

In the following sections, you can find informations about features
which have been suggested and/or discussed for inclusion into GPC,
usually in the GPC mailing list. The division into the sections and the
names of the sections may change when this seems useful. The entries
within each section are in no particular order.

   Some of the entries may be a bit difficult to read. Double question
marks (`??') within the entries mean that it's not yet clear how to do
the thing. Triple question marks (`???') mean that it's not clear
whether to do it at all. ;-)

* Menu:

* Planned - Strings::            String types
* Planned - Records/arrays::     Record and array types
* Planned - Other types::        Other types
* Planned - OOP::                Object oriented programming extensions
* Planned - Misc::               Miscellaneous GPC topics
* Planned - Utilities::          Useful utilities for GPC


File: gpc.info,  Node: Planned - Strings,  Next: Planned - Records/arrays,  Up: Planned Features

Planned features: Strings
-------------------------

   * const/var `AnyString' parameters and pointers (records internally,
     cf. gpc.pas) (GetCapacity; only for var parameters)

   * `SetLength' for non-Pascal string types; use truncate-flag

   * make work on all string types: string functions from
     `rts/string*.pas', `Concat'/`+' (function with conformant array;
     Optimize `s := s + ch') (fh19971105)

   * option `--arrays-of-char-as-cstrings={none,zero-based,all}' to
     allow assigning [zero-based] arrays of char to cstring variables
     (warning otherwise) (cstrini2.pas); make padding of those arrays
     in initialized variables and in assignments dependent on this
     switch (fh19970921) (fjf57.pas, ok) and if the length matches
     exactly, give a warning (fh19971013) (cstrassign.pas); pass those
     arrays as cstrings in read*, write*, str (P_*STRING; current
     length=-1 in two places); compile time warning (and treatment as
     non-zero-based) if it's not clear at compile time if a conformant
     array or schema is zero-based or not, and an operation depends on
     this in the zero-based state

   * Short strings (Length, Capacity) and switches
     (tc19980326.2,tc19980327); allow `type x=string' (undiscriminated)
     when switch is set so that strings don't default to length 255
     (fh19971113) (fjf97.pas, ok); don't add a #0 terminator when
     passing as a CString parameter (automatically use String2CString)

   * automatically convert CStrings to Strings?

   * general switch `--bp-strings'

   * "wide" characters

   * open array/string parameters (`$P', `$V' in BP; undocumented
     `OpenString' identifier in BP)

   * variables of type undiscriminated schema/strings -> remove
     pointers to string constants; functions returning undiscriminated
     schemata (pg19980813.3)


File: gpc.info,  Node: Planned - Records/arrays,  Next: Planned - Other types,  Prev: Planned - Strings,  Up: Planned Features

Planned features: Records/arrays
--------------------------------

   * variant records: EP: check that all values of tag-type have
     exactly one matching variant

   * initialized types in records/arrays (inirec[24].pas)

   * when applying `New' to a variant record type with a selector
     given, only allocate the space necessary for the selected variant
     (varrec2.pas) ???

   * Oregon and Vax Pascal structured constants
     <80256540.005E7D08.00@buffer1.quantel.com> ???

   * automatically detected upper array bounds in structured
     constants/intialized variables (-> PXSC)


File: gpc.info,  Node: Planned - Other types,  Next: Planned - OOP,  Prev: Planned - Records/arrays,  Up: Planned Features

Planned features: Other types
-----------------------------

   * UCSD Pascal's `Integer[n]' ??? BCD?

   * enum/record type extensions (syntax??)

   * general subtypes ???

   * type-cast operators ???

   * read/write operators ???

   * make `SizeOf' work on specially declared untyped var and const
     parameters (`AnyType'?)

   * sparse sets; sets of arbitrary types ?? ???

   * initalization and finalization code for arbitrary types (e.g. GMP
     types)

   * `SELECTED_REAL_KIND' for real types (cf. Fortran, drf) ?? ???

   * resize schemata (cf. `SetLength' in Delphi)

   * `ShortComplex', `LongComplex'
     <Pine.GSO.4.44.0207151258290.5058-100000@bonsai.fernuni-hagen.de>

   * keep files in FDRList while they live, not only while they're
     open, so `DoneFDR' can be applied to all of them

   * improve TFDDs


File: gpc.info,  Node: Planned - OOP,  Next: Planned - Misc,  Prev: Planned - Other types,  Up: Planned Features

Planned features: OOP
---------------------

   * `ProcVar := Obj.Method' {$X+}; method pointers
     (`procedure/function of object') (-> Delphi) ???

   * destructor: reset VMT link to 0 ???

   * checks: `@Obj <> nil', `TypeOf (Obj) <> nil', `TypeOf (Obj)^.Size
     = -TypeOf (Obj)^.NegatedSize'; separate switches; function
     initialized (that does these 3 tests) ???

   * `CLASS is CLASS' (implemented in Pascal with `Parent')

   * BP compatible dynamic method dispatcher ?? ???

   * `class' (reference to an object type); allow classes and object
     types to inherit from each other; OOE;
     <01BD7A3A.6B187A20.prucha@helicon.co.at>; obpascal.zip

   * `New': Delphi syntax; Dispose?? (automatically?; set references
     automatically to nil) (-> FPC)

   * `--base-class=foo', `--base-object=bar' ???

   * properties <01BD7A3A.6B187A20.prucha@helicon.co.at>,
     <16131.199805071354@potter.cc.keele.ac.uk>

   * VMTs (also for local classes (EP modules???)!) in GPI files,
     written to assembler file by main program; `--cfiles=foo': .s file
     with VMTs for C/assembler??? (also .h???)

   * method overloading ??? ??

   * interfaces (cf. OOE, Java); `OBJ is INTERFACE' (not so easy?) ???;
     variables of type pointer to more than one interface [and class]
     (also possible!); VMT problem with interfaces (my solution??? also
     with dynamic linking???)

   * virtual constructors; in interfaces (load)???

   * VMT: ClassID (64/128 bits?) default 0, error when duplicated,
     warning when 0 and inherited from class with <>0 ?, not allowed
     for abstract classes!; ClassName (also for abstract classes?); [];
     ProgrammerID, BaseClassID at beginning of unit (redeclarable?) ???

   * VMT: Children: list of pVMT

   * find class by ClassID/ClassName (implementable in Pascal with
     `Child')

   * object constants, class variables (-> other name for `VMT');
     virtual/static

   * store in GPI: whether ClassID used, ClassName used, which classes
     are instantiated


File: gpc.info,  Node: Planned - Misc,  Next: Planned - Utilities,  Prev: Planned - OOP,  Up: Planned Features

Planned features: Misc
----------------------

   * qualified identifiers <34508F33.4F685BD1@keele.ac.uk> (also
     `program_name.identifier'?) (problem module.id vs. record.field);
     also for operators; `gpc' for built-in identifiers; duplicate
     identifiers in different units (fjf260[ab].pas); don't capitalize
     variable names in error messages and file name queries (store the
     casing of the first occurrence of an identifier) -> remove
     `{$no-debug-info}'; `name' for units/modules; qualified import
     (mod10.pas)

   * check for using, incrementing, ... unused variables
     <199711270257.VAA06393@mint.mint.net> (kevin2.pas), especially for
     strings, also for `for'-loop counters after the loop (EP 6.8.1)

   * transpose arrays (Fortran)? <918557$mke$1@nnrp1.deja.com>

   * inline functions in GPI files

   * unit inheritance (of a complete interface with one statement or
     selectively)
     <Pine.HPP.3.96.971105161603.28577A-100000@tea.geophysik.tu-freiberg.de>,
     <199711061008.LAA25341@agnes.dida.physik.uni-essen.de> ??; virtual
     procedures ??? (-> EP import/export features good enough?)

   * read Booleans and enum types from files, write enum types to files
     ???

   * options to warn about everything that could cause portability
     problems

   * libraries (static/shared; DLL)
     <Pine.HPP.3.96.971110183550.7996B-100000@tea.geophysik.tu-freiberg.de>

   * smart linking (split `foo.s', as `foo*.s', ar `foo*.o' or split
     `foo.o')

   * overflow (right operand of mod <=0 is an error), nil pointer,
     string length, variant, object VMT (pointer, negative size field),
     etc. checking <199911040915.KAA11168@humulus.daimi.au.dk>; check
     that strings converted to CStrings don't contain #0 characters;
     initialize strings (length field), pointers, ordinal values and
     reals(?) with invalid values if checking is on

   * overloading of unary operators (`+', `-', `not')

   * intel assembler syntax; BP BASM ???

   * function overloading (in units and static methods?? - with
     different parameters, override or overload?); linker name??
     (perhaps: first occurrence of a procedure with normal name (=> all
     non-overloaded procedures get normal names)?); cf. Delphi methods
     without `override'

   * `for var: type = foo to bar do' ???

   * error/exception handling (Java,Delphi?)
     <01BD7A3A.6B187A20.prucha@helicon.co.at> (tc20000623)

   * RTS checking (libgpc_g), switch?

   * simplify implementation of some mathametical functions
     <199708091006.MAA26576@agnes.dida.physik.uni-essen.de>

   * variable number of arguments <32F9CFE7.5CB@lmemw.ericsson.se> ??
     ???

   * multithreading support ?? ???

   * `--wirth-pascal' :-)

   * PXSC standard ... (`pxsc.zip', `contrib/peter/pxsc') (??)

   * Object Oriented Extensions (Technical Report) (??)

   * generic types (cf. OOE section C.1) (gentypes.pas) ???

   * default parameters (cf. OOE section C.4; Delphi 4?)
     (iniparm[12].pas) <E183vio-000IyH-00@f12.mail.ru>

   * Pascal++ standard ... (??) ???

   * Delphi features: CompToCurrency, CurrencyToComp, Slice, TypeInfo
     ???, dynamic arrays (tc19991012)

   * output column numbers in error messages ??

   * debug info: `with' statements


File: gpc.info,  Node: Planned - Utilities,  Prev: Planned - Misc,  Up: Planned Features

Planned features: Utilities
---------------------------

   * `gp' make utility to replace automake; compile and link programs,
     but compile units without linking and without a warning that there
     is nothing to link; store GPC version numbers, platform and
     options in GPD files and re-compile automatically in `--automake'
     mode when they don't match; `external LIB' like `$L' (-> BP,
     Delphi) ?? (fh19990325.2)

   * `pas2texi' <200301290441.FAA30843@goedel.fjf.gnu.de>

   * C header to Pascal translator

   * gdb: Pascal types (sets, files, subranges, schemata, ...)

   * `indent'-like source code formatter for Pascal

   * AT&T <-> Intel assembler syntax converter ???


File: gpc.info,  Node: Fixed Bugs,  Prev: Planned Features,  Up: To Do

Problems that have been solved
==============================

This section lists the bugs fixed since the last (non alpha/beta) GPC
release, together with the date (YYYYMMDD) on which they were fixed, so
you can check if some problem has already been solved in a recent
release or developer version. For new features, see *Note News::.

   * 20041203: accessing components of a constant (EP) constructor
     (indexed by a constant for arrays) must yield a constant again
     (dave3*.pas)

   * 20041202: GPC crashes when using two variables with
     identically-named fields in a single `with' statement (withbug.pas)

   * 20041125: GPC doesn't accept `case' statements without
     case-list-elements (fjf982*.pas)

   * 20041125: gcc-3.x: options are wrongly reordered (so, e.g.,
     `--gnu-pascal -Wno-underscore' doesn't work as expected) (avo7.pas)

   * 20041124: applying `not' to a function result in parentheses
     doesn't work (avo6.pas)

   * 20041123: packed array indices containing `mod' don't work
     (avo4.pas)

   * 20041120: GPC sometimes prints `???' instead of the actual file
     name in messages

   * 20041028: function results (of record type) must not be allowed as
     `with' elements (only a warning in `--delphi' and `--mac-pascal'
     modes for compatibility); fields of non-lvalue `with' elements
     must not be lvalues either (fjf493*.pas)

   * 20041022: value parameters of type `String' (undiscriminated) must
     take the capacity of the actual parameter, according to EP
     (waldek11*.pas)

   * 20041021: initialized types in arrays (fjf233.pas, fjf974*.pas)

   * 20041020: initializers are ignored in `New' and `Initialize'
     (fjf967[j-l].pas)

   * 20041020: the address of global routines is not allowed in
     initializers (avo2*.pas)

   * 20041015: `Index' and `Pos' cannot be used in constant expressions
     (fjf970*.pas)

   * 20041012: initializers of variant records don't work (fjf259.pas),
     (peter6.pas) <C1256791.0021F002.00@synln01.synstar.de>

   * 20041012: initializers of packed arrays don't work (emil5.pas)

   * 20041007: the `__FILE__' and `__BASE_FILE__' macros should return
     full paths

   * 20041006: `Sqr' sometimes evaluates its argument twice (fjf963.pas)

   * 20041004: memory leak in routines with a local variable of file
     type that are left via `Exit' or `Return' (fjf962.pas)

   * 20040916: using a Boolean function as a condition in a `repeat'
     loop doesn't work correctly (artur1*.pas)

   * 20040913: overstrict type-checking in comparisons involving
     procedural types (fjf960*.pas)

   * 20040908: `Read', `Write' etc. evaluate its arguments in the wrong
     order (az43*.pas)

   * 20040908: `Read' etc. evaluate references to string parameters
     twice (fjf958.pas)

   * 20040907: on targets with 16 bit `Integer' type, the `MicroSecond'
     field of `TimeStamp' causes a compilation error

   * 20040907: character arrays indexed by non-integer ordinal types
     treated as strings cause internal compiler errors (fjf957*.pas)

   * 20040906: `-W[no-]cast-align' does not work (fjf956*.pas)

   * 20040903: in `FormatTime' `%Z' and `%z' unless provided by system
     library ignore DST

   * 20040710: powerpc: `--strength-reduce' doesn't work with `for'
     loops (was kludged before, fixed in gcc-3.3.3)

   * 20040710: AIX: `ReturnAddress' doesn't work after use of dynmamic
     variables (backend bug, fixed in gcc-3.3.3)

   * 20040622: functions returning sets are called twice if
     range-checking is on (inga1*.pas)

   * 20040512: `pow' and `**' are really EP conformant now (in
     particular `x pow y' and `x ** y' are an error if x = 0 and y <=
     0) (emil27*.pas)

   * 20040511: bug with `absolute' variables in strange situations
     (waldek8.pas)

   * 20040511: `protected var' parameters must only accept references
     (unlike `const' parameters) (gale5*.pas)

   * 20040507: `pack' must not pack the component type of arrays
     (fjf940[b-e].pas)

   * 20040507: in some circumstances packed fields are allowed as `var'
     parameters (fjf940a.pas)

   * 20040427: parameters of procedural types don't support Standard
     Pascal procedural parameters, conformant/open arrays and `type of'
     inquiries (fjf939*.pas)

   * 20040422: bugs with nonlocal gotos out of routines declaring file
     variables (nonloc*.pas) (fix involved a change in the internal
     representation of file variables)

   * 20040331: `'foo'#42' is rejected in `--borland-pascal'
     (chief53.pas)

   * 20040330: records/objects with many fields are handled slowly

   * 20040328: `--implementation-only' doesn't work correctly
     (bo4-19.pas)

   * 20040325: messages referring to object methods point to the end of
     the object type rather than the method declaration

   * 20040325: bug when slice-accessing a function result of type
     `Pointer' type-casted to `PString' (bo4-18.pas)

   * 20040210: incorrect errors with packed arrays and records
     (fb[12].pas, gale[34].pas)

   * 20040204: GPC crashes on `else' after a missing semicolon in some
     circumstances (fjf926.pas)

   * 20031007: spurious errors about `result types in forward declared
     functions' in `--extended-pascal' etc. (dave2.pas)

   * 20031004: do not allow disposing of `nil' pointers in standard
     Pascal modes (fjf917*.pas)

   * 20031001: arithmetic expressions don't work as lower
     array/subrange bounds (fjf248.pas, fjf293.pas, fjf336.pas,
     fjf346a.pas, fjf622.pas)

   * 20030925: initializers for types containing nested schemata don't
     work (fjf914*.pas)

   * 20030830: open internal files with `O_EXCL' on `Rewrite' (as a
     protection against symlink attacks)

   * 20030819: GPC accepts, but ignores, options with invalid suffixes
     (e.g. `--delphi-pascal')

   * 20030729: `pow' and `**' are EP conformant now (in particular `x
     pow y = (1 div x) pow (­y)' if `y' is negative and `x <> 0')
     (fjf908.pas)

   * 20030714: `--enable-keyword'/`--disable-keyword' on the
     command-line makes GPC crash (david5.pas)

   * 20030704: wrong type-error when applying `Inc' to a type-casted
     pointer (peter3.pas)

   * 20030702: with range checking enabled, check dynamic
     subrange/array size (fjf222*.pas, fjf813*.pas, fjf900*.pas)

   * 20030701: GPC allows modification of conformant array bounds,
     result of `High'/`Low' etc. (fjf897*.pas)

   * 20030626: don't allow linker names starting with a digit
     (fjf894.pas)

   * 20030625: `SubStr' with constant arguments doesn't work in
     constants (gale1.pas)

   * 20030617: handle `BitSizeOf' correctly for packed array fields,
     don't allow `SizeOf' on them (fjf891*.pas)

   * 20030612: System: `BPReal' must be a packed record
     <3EE8A26D.C919BE7D@flexim.de>

   * 20030610: schema types with initializers (drf1.pas, fjf886*.pas)

   * 20030610: `Return' doesn't work for sets (fjf885.pas)

   * 20030609: bug with arrays as fields of `packed' records
     (waldek6.pas)

   * 20030607: don't allow duplicate imports in a module interface and
     implementation (nick1b.pas)

   * 20030604: compensate for parser read-ahead in the lexer, so
     compiler directives don't become effective too early and error
     messages refer more closely to the correct source position

   * 20030603: bug when dividing two integers with `/' (fjf481.pas)

   * 20030509: don't allow `absolute' in type definitions

   * 20030502: subranges with variable limits (couper[23].pas)

   * 20030502: Sparc with gcc-2.95.x: `goto' jumping out of two
     procedure nesting levels doesn't work (GCC bug; fixed in gcc-3)
     <200111170922.KAA09125@goedel.fjf.gnu.de> (fjf558[op].pas) (fixed
     with gcc-3 or when using `--longjmp-all-nonlocal-labels')

   * 20030502: the parser does not always recover well after a parse
     error <199911040915.KAA11168@humulus.daimi.au.dk> (fixed the case
     given in this report; if there are other cases, please report)

   * 20030501: detect conflicts between object fields and local
     variables in methods

   * 20030430: packed array/record fields don't work in `Read' etc.
     (tom5.pas)

   * 20030430: file parameters must not automatically be bindable in
     `--extended-pascal' (fjf193[c-e].pas)

   * 20030423: give an error rather than a warning when casting between
     types of different size in `{$X-}'

   * 20030423: simplify code generated to compute size of dynamical
     variables if no bitfields are involved (ok with gcc-3)

   * 20030422: initialized object variables don't work (fjf445*.pas)

   * 20030422: declarations of a module interface are not visible in
     the implementation (kevin13.pas, mod12.pas)
     <Pine.BSI.3.96.971110210330.7570A-100000@malasada.lava.net>

   * 20030422: detect invalid array slice access with constant indices
     at compile-time (peter2*.pas)

   * 20030421: automatically close dynamically allocated files on
     `Dispose' and files declared in a statement block at the end of
     the statement block <6r9ir5$7v5$1@nntpd.lkg.dec.com>
     (fjf219[a-d].pas, fjf502.pas)

   * 20030421: initialize local static variables in the main
     constructor, not in each routine call (fjf458*.pas)

   * 20030421: check parameter and result variable names in repeated
     forward etc. declarations <20010321204051.A611@plato> (fjf284.pas,
     markus8.pas, fjf850*.pas)

   * 20030417: modifying `for'-loop counters within the loop or in a
     subroutine is not allowed <200005240807.EAA05355@mail.bcpl.net>,
     <Pine.LNX.4.44.0210281004000.31943-100000@duch.mimuw.edu.pl>
     (az47.pas, fjf837*.pas)

   * 20030417: possible stack overflow when using string concatenation
     in a loop (fjf419*.pas, fjf345e.pas, fjf460b.pas) - breaks
     berend3.pas (less important because strange test case, and just
     another instance of existing contourbug.pas)

   * 20030416: some functions in boolean shortcuts are always called
     (fjf226*.pas)

   * 20030414: label declarations must not be allowed in unit/module
     interfaces and module implementations (but in unit
     implementations, BP compatible, though we don't allow nonlocal
     `goto's into the constructor) (fjf835*.pas)

   * 20030321: variables declared in interfaces of modules are not
     initialized (capacity of strings etc.) (daj3.pas, sven14c.pas,
     nick1.pas)

   * 20030321: subranges whose size is exactly one or two bytes are not
     packed in packed arrays (daj14a.pas)

   * 20030321: `prior parameter's size depends on `Foo'' with `const'
     string parameters in module interfaces (fjf667.pas)

   * 20030313: operators don't always work across units (fjf803.pas)

   * 20030312: overloading `<=', `>=', `<>' and some certain words
     doesn't work (fjf789.pas, fjf794*.pas, fjf800.pas, fjf802.pas,
     fjf804.pas)

   * 20030311: when passing a schema variable as an untyped argument,
     the whole schema, including the discriminants is passed
     (fjf798.pas)

   * 20030302: discriminant identifiers as variant record selectors

   * 20030227: GPC crashes when taking the address of local variables
     in an initializer (nicola4*.pas)

   * 20030225: the warnings about uninitialized/unused variables don't
     work for strings, objects, etc. (fjf779*.pas)

   * 20030221: gcc-2.95.x: `configure --silent' doesn't work (passes
     wrong options to sub-configures, so the subsequent make fails)
     (GCC bug; fixed in 3.x)

   * 20030215: forward referencing pointers generate debug info that
     appears as generic pointers

   * 20030202: count of parameters in error messages should not include
     `Self' in methods or internal parameters for conformant or open
     arrays

   * 20030129: check for unresolved `forward', interface and method
     declarations (az32.pas, fjf758*.pas)

   * 20030129: several standard conformance bugs
     (az{1..24,26..42,44..46}*.pas, emil23*.pas)

   * 20030126: some bugs with complicated schema usage (emil22*.pas,
     fjf750*.pas)

   * 20030122: subtraction of unsigned types with a negative result
     doesn't work (ml4.pas)

   * 20021229: declaring huge enum types and exporting subranges of
     them is very slow (quadratic time behaviour); some bugs regarding
     exporting of subranges (fjf736*.pas)

   * 20021213: Linux: `crtscreen' should react to `SIGWINCH'

   * 20021120: `Card' doesn't work with set constructors; `Include' and
     `Exclude' should not accept set constructors (eike3*.pas)

   * 20021105: type initializers are not type-checked until a variable
     of the type is declared (fjf704.pas); with gcc-2.x: bug when
     variables of a type with initializer are declared locally in more
     than one routine (couper13.pas)

   * 20021105: `packed object' should not be allowed (fjf703.pas)

   * 20021101: bug when replacing a non-virtual method by a virtual one
     in a descendant object type (fjf702.pas)

   * 20021027: classic Pascal does not know the empty string
     <Pine.LNX.4.44.0210181332470.29475-100000@duch.mimuw.edu.pl>
     (fjf693*.pas)

   * 20021027: relational and exponentiation operators have no
     associativity
     <Pine.LNX.4.44.0210210807410.18095-100000@duch.mimuw.edu.pl>
     (fjf692.pas, fjf566[k-m].pas)

   * 20021002: `gpc -BDIR' requires a trailing dir separator

   * 20021001: constructors are accepted as the argument to `Dispose'
     (fjf674.pas)

   * 20021001: align file fields in packed records on machines with
     strict alignment requirements (chief38*.pas)

   * 20021001: bug on machines with strict alignment requirements
     <199906021618.MAA06228@sten27.software.mitel.com> (richard1.pas)

   * 20020930: duplicate variable declarations are allowed

   * 20020929: `attribute's of variables are ignored (fjf673.pas)

   * 20020929: `volatile' for `external' variables without `asmname' is
     ignored (fjf672.pas)

   * 20020926: numbers with base specifiers are allowed as labels
     (fjf417*.pas)

   * 20020923: System: `MemAvail'/`MaxAvail' can go into an endless loop

   * 20020920: the number of times the preprocessor is invoked by the
     automake mechanism might grow exponentially with the number of
     units involved <02091610572303.14626@dutw54.wbmt.tudelft.nl>

   * 20020918: importing `StandardOutput' etc. in the interface of a
     module doesn't work (sietse2*.pas)

   * 20020904: comparisons between signed and unsigned integers
     sometimes give wrong results (eike2.pas, fjf664.pas, martin5.pas)

   * 20020903: `IOSelect' fails with file handles >= 8 on some systems
     (e.g., Solaris) (fjf663.pas)

   * 20020831: GPC creates wrong debug info for many built-in types
     <200208280012.g7S0CWj07637@mail.bcpl.net>

   * 20020827: comparisons of `packed' subrange variables don't work
     right (martin4[ab].pas)

   * 20020824: operators defined in units don't always work (maur11.pas)

   * 20020824: object methods that contain an ISO style procedural
     parameter forget the implicit `with Self do' (fjf662a.pas)

   * 20020615: `if Pass[i] in 'A' .. 'Z'' makes GPC crash (miklos6.pas)

   * 20020603: compiling a program (not a unit or module) with
     `--interface-only' or `--syntax-only' segfaults (waldek1.pas)

   * 20020603: `--nested-comments' fails without `-Wall' (waldek2.pas)

   * 20020514: powerpc: `--strength-reduce' doesn't work with `for'
     loops [kludged now]

   * 20020514: guarantee complete evaluation in `{$B+}' mode
     (fjf552*.pas)

   * 20020514: spurious warning with `for' loops using a `ByteCard'
     counter (toby1.pas)


File: gpc.info,  Node: Internals,  Next: Copying,  Prev: To Do,  Up: Top

The GPC Source Reference
************************

     "The Source will be with you. Always."

   This chapter describes internals of GPC. It is meant for GPC
developers and those who want to become developers, or just want to
know more about how the compiler works. It does not contain information
needed to just use GPC to compile programs.

   This chapter tells you how to look up additional information about
the GNU Pascal compiler from its source code.

   *Please note:* If you intend to modify GPC's source, please check
the top of each file you're going to modify. A number of files are
generated automatically by various tools. The top of these files will
tell you by which tool and from what file they were generated.
Modifying a generated file is pointless, since it will be overwritten
the next time the tool is run. Instead, modify the original source
(which will usually be easier in fact, e.g. a bison input file vs. the
generated C code). This also holds for various documentation and other
files.

   Proprietary compilers often come with a lot of technical information
about the internals of the compiler. This is necessary because their
vendors want to avoid to distribute the source of the compiler - which
is always the most definitive source of this technical information.

   With GNU compilers, on the other hand, you are free to get the
source code, look how your compiler works internally, customize it for
your own needs, and to re-distribute it in modified or unmodified form.
You may even take money for this redistribution.  (For details, see the
GNU General Public License, *Note Copying::.)

   The following subsections are your guide to the GNU Pascal source
code. If you have further questions, be welcome to ask them at the GNU
Pascal mailing list (see *Note Support::).

   All file paths mentioned in this chapter are relative to the GNU
Pascal source directory, a subdirectory `gcc/p' below the top-level GCC
source directory.

   The following sections roughly coincide with the order of the steps
a Pascal source passes through during compilation (omitting the code
generation which is the job of the GCC backend, and the assembler and
linker steps at the end which are done by the programs `as' and `ld' of
binutils and possibly other utilities like `collect2'). Also missing
here is the compiler driver `gpc' which behaves very similarly to `gcc'
and whose main job is to invoke the other parts in the right order,
with the right arguments etc.

   Note, this chapter docuemnts only selected parts of the compiler.
Many things are missing because nobody has yet had the time to write
something about them. In any case, for real understanding of the inner
workings, you should always refer to the source code.

* Menu:

* Preprocessor::         `gpcpp.c' -- The Pascal preprocessor
* Lexical analyzer::     `gpc-lex.c' -- How GPC reads your source.
* Language definition::  `parse.y' -- ``Syntax diagrams'' as ``Bison'' source.
* Tree nodes::           `../tree.*' -- How GPC stores your program internally.
* Parameter passing::    `typecheck.c' -- How GPC passes parameters.
* GPI files::            `module.c' -- How GPC's precompiled module/unit interfaces work.
* Automake::             `module.c' -- How GPC automatically ``makes'' a large project.
* File Layout::          Files that make up GPC
* Planned::              Planned features

   For more information, see the manual of GCC internals, *Note Top:
(gccint)Top.


File: gpc.info,  Node: Preprocessor,  Next: Lexical analyzer,  Up: Internals

The Pascal preprocessor
=======================

`gpcpp' is based on the C preprocessor, so it does everything `cpp'
does (see the cpp manual) and some more.  In particular:

   * Comments like `cpp' does, but within `{ ... }' and `(* ... *)',
     also after `//' if `delphi-comments' is active, never within `/*
     ... */'.  Also mixed comments (`{ ... *)', `(* ... }') if enabled
     (`mixed-comments') and nested comments (e.g.  `{ ... { ... } ...
     }') if enabled (`nested-comments')

   * Macros and conditionals like `cpp' does, but both case sensitive
     and insensitive ones; `no-macros' to turn macro expansion off
     (e.g., for BP compatibility)

   * `ifopt' for short and long options

   * Include files like `cpp' does, but also with `{$I ...}' (BP
     style), which allows the file name extension to be omitted

   * Recognize Pascal strings (to avoid looking for comments and
     directives within strings) enclosed in single (like Standard
     Pascal) or double quotes (like C).

   * Option handling, sharing tables in `gpc-options.h' with the
     compiler:
        - Default option settings

        - Options can imply other options (e.g., `borland-pascal' ->
          `no-macros' etc.)

        - Short compiler directives

        - Short directive `W' (warnings) is disabled in
          `borland-pascal' and `delphi' because it has another meaning
          there

   * Compiler directives (`{$...}' or `(*$...*)'):
        - pass them through, so the compiler can handle them

        - keep track of them for `ifopt'

        - handle those that affect the preprocessor (e.g., about
          comments)

        - allow comments within compiler directives if nested comments
          are enabled

        - local directives

        - case insensitive

   * Slightly Pascal-like syntax for conditional compilation (`not' ->
     `!', `and' -> `&&', `or' -> `||', `xor' -> `!=', `shl' -> `<<',
     `shr' -> `>>', `False' -> `0', `True' -> `1', `<>' -> `!=', `=' ->
     `==')

   * Line directives like `cpp' does, but recognize BP style (`#42' or
     `#$f0') character constants and don't confuse them with line
     directives (the latter seem to always have a space after the `#')



File: gpc.info,  Node: Lexical analyzer,  Next: Language definition,  Prev: Preprocessor,  Up: Internals

GPC's Lexical Analyzer
======================

The source files `gpc-lex.c' and `pascal-lex.c' contain the so-called
_lexical analyzer_ of the GNU Pascal compiler.  The latter file was
created using `flex' from `pascal-lex.l'. This very first stage of the
compiler (after the preprocessor which is a separate executable) is
responsible for reading what you have written and dividing it into
_tokens_, the "atoms" of each computer language. The main entry point
is the function, `yylex' which calls the flex-generated function
`lexscan' which does the main work of token separation.

   Here is, for example, where the real number `3.14' and the subrange
of integers `3..14' are distinguished, and where strings constants,
symbols etc. are recognized.

* Menu:

* Lexer problems::
* BP character constants::
* Compiler directives internally::


File: gpc.info,  Node: Lexer problems,  Next: BP character constants,  Up: Lexical analyzer

Lexer problems
--------------

Pascal is a language that's easy to lex and parse. Then came Borland ...

   A number of their ad-hoc syntax extensions cause lexing or parsing
problems, and even ambiguities. This lexer tries to solve them as well
as possible, sometimes with clever rules, other times with gross hacks
and with help from the parser. (And, BTW, it handles regular Pascal as
well. ;-)

   Some of the problems are:

   * Real constants with a trailing `.'. Problem: They make the
     character sequence `2.)' ambiguous. It could be interpreted as
     `2.0', followed by `)' or as `2' and `.)' (which is an alternative
     for `]'). This lexer chooses the latter interpretation, like BP
     does, and the standard requires. It would be possible to handle
     both, by keeping a stack of the currently open parentheses and
     brackets and chosing the matching closing one, but since BP does
     not do this, either, it doesn't seem worth the trouble. (Or maybe
     later ... ;-)

   * They also cause a little problem in the sequence `2..' (the start
     of an integer subrange), but this is easily solved by normal lexer
     look-ahead since a real constant can't be followed by a `.' in any
     Pascal dialect we know of.

   * Missing token separators bwtween integer or real constants and a
     following keyword (e.g. `42to'). It gets worse with hex numbers
     (`$abcduntil'), but it's not really difficult to lex. However, we
     don't allow this with Extended Pascal non-decimal integer
     constants, e.g. `16#abcduntil' where it would be a little more
     difficult (because it would depend on the basis whether or not `u'
     is a digit). Since BP does not even support EP non-decimal
     constants, there's no point in going to such troubles.

   * Initializers for variables (or "typed constants", as BP likes to
     call initialized variables even though they are not constant) with
     `=' rather than `value'. Problem: It makes initialized Boolean
     subrange variable declarations like `Foo: False .. True = False =
     False' ambiguous. They could be interpreted as `Foo: False ..
     (True = False) = False' or `Foo: False .. True = (False = False)'.
     This lexer, like BP, chooses the latter interpretation. To avoid
     conflicts in the parser, this is done with the `LEX_CONST_EQUAL'
     hack, counting parentheses and brackets so that in `Foo: False ..
     (True = False) = True' the *second* `=' will become the
     LEX_CONST_EQUAL token.

   * Array initializers in `(', `)'. When they consist of a single
     entry (without an index as required in EP), they conflict with
     expressions in parentheses. This is resolved in the parser and the
     later processing of initializers.

   * Delphi's `external [<libname>] [name <name>]' construct where
     `<libname>' and `<name>' can be string expressions. Since `name'
     is not a reserved word, but an identifier, `external name name
     name' can be valid which is difficult to parse. It could be solved
     by the parser, by making `name' a special identifier whose special
     meaning is recognized after `external' only.

   * Character constants with `#'. They conflict with the Extended
     Pascal non-decimal integer number notation. `#13#10' could mean
     `Chr (13) + Chr (10)' or `Chr (13#10)'. This lexer chooses the
     former interpretation, since the latter one would be a mix of BP
     and Extended Pascal features.

   * Last (but not least - no, certainly worst): Character constants
     with `^' (was this "feature" meant as an AFJ or something???). GPC
     tries to make the best out of a stupid situation, see the next
     section (*note BP character constants::) for details.  It should
     be noted that BP itself fails in a number of situations involving
     such character constants, probably the clearest sign for a design
     bug.

   * That said, to be honest, BP is not the only dialect to introduce
     lexing or parsing problems. Extended Pascal (but also BP) allow the
     lower bound of a subrange declaration to be an arbitrary expression
     (Standard Pascal allows only a plain constant). This makes things
     like `var Foo: (Bar ...' hard to parse, since `Bar' could be part
     of an expression in parentheses as the lower bound of a subrange,
     or the beginning of an enumeration type declaration. BP can't
     handle this situation. This will be solved with a GLR parser.

   * GPC's extension `...' for variadic external function declarations
     causes a problem in the sequence `(...)' which could mean `(',
     `...', `)', i.e., a parameter list with only variadic arguments,
     or `(.', `.', `.)'.  Since the latter token sequence is
     meaningless in any Pascal dialect we know of, this lexer chooses
     the former one which is easily accomplished with normal look-ahead.


File: gpc.info,  Node: BP character constants,  Next: Compiler directives internally,  Prev: Lexer problems,  Up: Lexical analyzer

BP character constants
----------------------

Borland-style character constants of the form `^M' need special care.
For example look at the following type declaration:

     type
       X = Integer;
       Y = ^X;        { pointer type }
       Z = ^X .. ^Y;  { subrange type }

   One way to resolve this is to try to let the parser tell the lexer
(via a global flag) whether a character constant or the symbol `^' (to
create pointer types or to dereference pointer expressions) is suitable
in the current context. This was done in previous versions, but it had
a number of disadvantages: First, any dependency of the lexer on the
parser (*note Lexical Tie-Ins: (bison)Lexical Tie-Ins.) is problematic
by itself since it must be taken care of manually in each relevant
parser rule. Furthermore, the parser read-ahead must be taken into
account, so the flag must usually be changed apparently one token too
early. Using a more powerful parsing algorithm such as GLR (*note GLR
Parsers: (bison)GLR Parsers.) adds to this problem since it may read
many tokens while the parser is split before it can perform any
semantic action (which is where the flag could be modified). Secondly,
as the example above shows, there are contexts in which both meanings
are acceptable. So further look-ahead (within the lexer) was needed to
resolve the problem.

   Therefore, the current version of GPC uses another approach. When
seeing `^X', the lexer returns two tokens, a regular `^' and a special
token `LEX_CARET_LETTER' with semantic value `X'. The parser then
accepts `LEX_CARET_LETTER' wherever an identifier is accepted (and
turns it into the identifier `X' via the nonterminal `caret_letter').
Furthermore, it accepts the sequence `^', `LEX_CARET_LETTER' as a
string constant (whose value is a one-character string). Since
`LEX_CARET_LETTER' is only produced by the lexer immediately after `^'
(no white-space in between), this works (whereas otherwise, pasting
tokens in the parser is not reliable due to white-space, e.g. the token
sequence `:' and `=' could stand for `:=' (if `:=' weren't a token by
itself), but also for `: =' with a space in between). With this trick,
we can handle `^' followed by a single letter or underscore. The fact
that this doesn't cause any conflicts in the bison parser tell us that
this method works.

   However, BP even allows any other character after `^' as a char
constant. E.g., `^)' could be a pointer dereference after an expression
and followed by a closing parenthesis, or the character `i' (sic!).

   Some characters are unproblematic because they can never occur after
a `^' in its regular meaning, so the sequence can be lexed as a char
constant directly. These are all characters that are not part of any
Pascal tokens at all (which includes all control characters except
white-space, all non-ASCII characters and the characters `!', `&', `%',
`?', `\', ``', `|', `~' and `}' - the last one occurs at the end of
comments, but within a comment this issue doesn't occur, anyway) and
those characters that can only start constants because a constant can
never follow a `^' in Pascal (which are `#', `$', `'', `"' and the
digits).

   For `^' followed by whitespace, we return the token
`LEX_CARET_WHITE' which the parser accepts as either a string constant
or equivalent to `^' (because in the regular meaning, the white-space
is meaningless).

   If `^' is followed by one of the tokens `,', `.', `:', `;', `(',
`)', `[', `]', `+', `-', `*', `/', `<', `=', `>', `@', `^', the lexer
just returns the tokens regularly, and the parser accepts these
sequences as a char constant (besides the normal meaning of the
tokens). (Again, since white-space after `^' is already dealt with,
this token pasting works here.)

   But `^' can also be followed by a multi-character alphanumeric
sequence such as `^cto' which might be read as `^ cto' or `^c to'
(since BP also allows omitting white-space after constants), or by a
multi-character token such as `^<=' which could be `^ <=' or `^< ='.
Both could be solved with extra tokens, e.g. lexing `^<=' as `^',
`LEX_CARET_LESS', `=' and accepting `^', `LEX_CARET_LESS' in the parser
as a string constant and `LEX_CARET_LESS', `=' as equivalent to `<='
(relying on the fact that the lexer doesn't produce `LEX_CARET_LESS' if
there's white-space after the `<' because then the simple `^', `<' will
work, so justifying the token-pasting once again). This has not been
done yet (in the alphanumeric case, this might add a lot of special
tokens because of keywords etc., and it's doubtful whether that's worth
it).

   Finally, we have `^{' and `^(*'. This is so incredibly stupid (e.g.,
think of the construct `type c = Integer; foo = ^{ .. ^|; bar = {} c;'
which would become ambiguous then), that perhaps we should not attempt
to handle this ...

   (As a side-note, BP itself doesn't handle `^' character constants in
many situations, including many that GPC does handle with the
mechanisms described above, probably the clearest sign for a design
bug. But if we support them at all, we might just as well do it better
than BP ... :-)


File: gpc.info,  Node: Compiler directives internally,  Prev: BP character constants,  Up: Lexical analyzer

Compiler directives internally
------------------------------

Compiler directives are mostly handled in `options.c', mostly in common
with command-line options, using the definitions in `lang-options.h'
and the tables in `gpc-options.h'.

   A special problem is that the parser sometimes has to read tokens
before they're used to decide what to do next. This is generally
harmless, but if there is a compiler directive before such a look-ahead
token, it would be handled apparently too early. This looks strange
from the programmer's point of view - even more so since the programmer
cannot easily predict when the parser needs to read ahead and when not,
and therefore cannot be sure where exactly to place the directive
(especially for local directives that are meant to have a scope as
small as possible).

   To solve this problem (and in turn give the parser more freedom for
further look ahead which is useful, e.g., for a GLR parser), GPC keeps
the options that can be changed by directives in a `struct options'.
There are several pointers to such a structure:

   `lexer_options' are the options current to the lexer. These are
always the ones read most recently. Compiler directives are applied
here when read. Each directive creates a new `struct options' which is
chained in a linked list to the previous ones.

   `compiler_options' points to the options current for the compiler,
i.e. seen before the last token handled in a parser rule.  To
facilitate this, we abuse Bison's location tracking feature (*note
Locations: (bison)Locations.) and refer to the options seen before a
token in the token's location (`yylloc'). Before each grammar rule is
handled, the compiler options are updated to those of the last token
involved in the rules handled so far, using Bison's `YYLLOC_DEFAULT'
feature. Actual locations, used for error messages etc., are handled
the same way (according to the real purpose of Bison's location
tracking), also distinct for the lexer and compiler.

   Note: Tokens are not always handled in order. E.g., in `2 + 3 * 4',
first `3 * 4' is evaluated, then `2 + 12', i.e., the tokens `2' and `+'
are handled after the following tokens.  To avoid jumping back in the
options, we store a counter, rather than a pointer, in `yyloc', so we
can compare it to the current counter. This also allows us to free any
`struct options' that `compiler_options' has advanced beyond because it
can never go back.

   Finally, the pointer `co' points to the current options which is
`lexer_options' when we're in the lexer and `compiler_options'
otherwise. All routines that use or set options refer to `co', so there
is no problem when they may be called both from the lexer and from
other parts of the compiler (e.g., `lookup_name').

   Note: Some of the options are flags declared in the backend. Since
we can't keep them in `struct option' directly, we have to copy them
back and forth in `activate_options'. This is a little annoyance, but
no real problem.


File: gpc.info,  Node: Language definition,  Next: Tree nodes,  Prev: Lexical analyzer,  Up: Internals

Language Definition: GPC's Parser
=================================

The file `parse.y' contains the "bison" source code of GNU Pascal's
parser. This stage of the compilation analyzes and checks the syntax of
your Pascal program, and it generates an intermediate,
language-independent code which is then passed to the GNU back-end.

   The _bison_ language essentially is a machine-readable form of the
Backus-Naur Form, the symbolic notation of grammars of computer
languages. "Syntax diagrams" are a graphical variant of the Backus-Naur
Form.

   For details about the "bison" language, see the Bison manual. A
short overview how to pick up some information you might need for
programming follows.

   Suppose you have forgotten how a variable is declared in Pascal.
After some searching in `parse.y' you have found the following:

     simple_decl_1:
         ...
       | p_var variable_declaration_list
           { [...] }
       ;
     
     variable_declaration_list:
         variable_declaration { }
       | variable_declaration_list variable_declaration
       ;

   Translated into English, this means: "A declaration can (amoung
other things like types and constants, omitted here) consist of the
keyword (lexical token) `var' followed by a `variable declaration
list'. A `variable declaration list' in turn consists of one or more
`variable declarations'." (The latter explanation requires that you
understand the recursive nature of the definition of
`variable_declaration_list'.)

   Now we can go on and search for `variable_declaration'.

     variable_declaration:
         id_list_limited ':' type_denoter_with_attributes
           { [...] }
         absolute_or_value_specification optional_variable_directive_list ';'
           { [...] }
       ;

   The `[...]' are placeholders for some C statements, the "semantic
actions" which (for the most part) aren't important for understanding
GPC's grammar.

   From this you can look up that a variable declaration in GNU Pascal
consists of an identifier list, followed by a colon, "type denoter with
attributes", an "absolute or value specification" and an "optional
variable directive list", terminated by a semicolon.  Some of these
parts are easy to understand, the others you can look up from
`parse.y'. Remember that the reserved word `var' precedes all this.

   Now you know how to get the exact grammar of the GNU Pascal language
from the source.

   The semantic actions, not shown above, are in some sense the most
important part of the bison source, because they are responsible for
the generation of the intermediate code of the GNU Pascal front-end,
the so-called _tree nodes_ (which are used to represent most things in
the compiler). For instance, the C code in "type denoter" returns
(assigns to `$$') information about the type in a variable of type
`tree'.

   The "variable declaration" gets this and other information in the
numbered arguments (`$1' etc.) and passes it to some C functions
declared in the other source files. Generally, those functions do the
real work, while the main job of the C statements in the parser is to
call them with the right arguments.

   This, the parser, is the place where it becomes Pascal.

* Menu:

* Parsing keywords::   So many keywords, so many problems ...
* Parsing subranges::  Expressions as lower bounds of subranges


File: gpc.info,  Node: Parsing keywords,  Next: Parsing subranges,  Up: Language definition

So many keywords, so many problems ...
--------------------------------------

Keywords can be potential problems since they are (generally) not
available for use as identifiers. Only those keywords that are defined
in ISO 7185 Pascal are unproblematic because no valid program should
ever use them as identifiers.

   To cope with this problem, GPC does several things:

   * If a dialect option is set, only keywords of the specified dialect
     are enabled. All possible keywords, together with their dialects,
     are defined in `predef.h'. However, compiling with dialect options
     is usually not recommended, so this is no good general solution.

   * The user can turn off individual keywords using the compiler
     directive `{$disable-keyword}'. This makes sure that every
     conflict with a user's identifier _can_ be avoided, but with extra
     work on part of the user.

   * The parser used to enable and disable keywords in certain syntactic
     contexts. However, this was rather fragile since it interacts with
     the parser's read-ahead, and it requires attention on every related
     change in the parser. Therefore, this mechanism was removed.

   * Many of the problematic keywords are now treated as "weak". This
     means, they are only recognized as keywords if no current
     declaration of this name exists. However, so that this can work, it
     must be possible to create new declarations of this name in the
     first place - at this point, no declaration exists yet, so the name
     is recognized as a keyword.

     This is solved by listing these keywords in the `new_identifier'
     rule of the parser. This means, first the lexer recognizes them as
     keywords, then the parser "turns them back" into identifiers. The
     advantage, compared to explicit enabling and disabling of
     keywords, is that bison automatically finds the places in which to
     apply the `new_identifier' rule, i.e. treat them as plain
     identifiers.

     Of course, there is a catch. Since the keyword tokens are listed in
     `new_identifier', they can conflict with occurrences of the actual
     keywords (bison will find such cases as S/R or R/R conflicts).
     Such conflicts have to be sorted out carefully.  Fortunately, for
     many keywords, this turned out quite easy - in some cases no
     conflicts at all arose. One especially complicated example is
     explained below in detail. If it is not possible to solve the
     conflicts for a particular keyword, this keyword cannot be handled
     this way.

   The following sections describe the most problematic keywords:

* Menu:

* attribute as a weak keyword::
* external as a weak keyword::
* forward near far::
* implementation constructor destructor operator uses import initialization::

   These descriptions should make it clear that we're walking on the
bleeding edge of what's possible with LALR(1) and lexer tricks.  Trying
much more will probably increase the complexity to the unmanageable.


File: gpc.info,  Node: attribute as a weak keyword,  Next: external as a weak keyword,  Up: Parsing keywords

`attribute' as a weak keyword
.............................

Note that in the following we use the spelling `attribute' when
referring to the directive and `Attribute' for an identifier.  This is
according to the GPCS and might make the following text clearer.
However, it cannot be a criterion for resolving the conflict since the
compiler must treat both spellings equally. The same applies, of
course, to the line-breaks and white-space used here for readability.

   Making `attribute' a weak keyword leads to a S/R conflict in
variable declarations (whereas routine declarations go without
conflicts). Consider this case:

     var
       a: Integer; attribute (...)

   vs.

     var
       a: Integer;
       Attribute: ...

   After reading the `;', the parser must decide whether to shift it,
or to reduce to a variable declaration. But the next token `attribute'
doesn't decide it, and bison can only look ahead one token.

   The following token would resolve the problem, since the directive
`attribute' is always followed by `(' whereas an identifier in a
variable declaration can be followed by `,' or `:', but never `('.

   More generally, an identifier in an `id_list' in the parser can
never be followed by `(' (while identifiers in other contexts can be,
e.g. in function calls). This must be carefully checked manually
through the whole grammar!

   Thus, the solution consists of two steps. Firstly, the _lexer_ does
the additional look-ahead that bison can't do. When it reads the word
`attribute' (and it is not disabled by dialect options or by the user
or shadowed by some declaration), then if the next token is not `(', it
can only be an identifier, so the lexer returns `LEX_ID'. If the next
token is `(', the lexer returns `p_attribute'.

   Lexer look-ahead is not really nice, either, e.g. because it
increases the "shift" of compiler directives. At least, we only have to
read ahead two characters plus preceding white-space (two because of
`(.'), and not an actual token - the latter would add additiional
complications of saving and restoring lexer semantic values and the
state of lexer/parser interrelation variables such as
`lex_const_equal', and then either lex the token again later or handle
the cases where the parser modifies these variables in between. This
would get really messy.

   Secondly, the parser accepts `p_attribute' as an identifier _except_
in an `id_list'. To achieve this, the nonterminal
`new_identifier_limited' is used within `id_list'.

   _Note:_ Using `new_identifier_limited' does _not_ mean that
`Attribute' can't be used as an identifier in this place. Instead, this
nonterminal can never be followed by `(', so the lexer will have turned
`Attribute' into a `LEX_ID' token already.

   Actually, that's not all: In a `constant_definition', the conflict
is not against `id_list', but against a simple `new_identifier'. But we
can just use `new_identifier_limited' instead in the
`constant_definition' rule.

   This finally solves all conflicts with `attribute'.  `fjf792*.pas'
are test programs for these cases.


File: gpc.info,  Node: external as a weak keyword,  Next: forward near far,  Prev: attribute as a weak keyword,  Up: Parsing keywords

`external' as a weak keyword
............................

The situation about `external' is similar to `attribute'.  However, on
the positive side, we don't have to worry about constants which cannot
be external - by definition, since initialization and external
declaration contradict each other.

   The new problems are that an `external' directive can be followed by
`;', `name' and by many more tokens if GPC will support a BP compatible
`external LIBNAME' where LIBNAME can be a string constant expression.

   So we have to consider the problem from the other side. In an
`id_list' of a variable declaration (which is the only conflict, given
the notes about attribute, *Note attribute as a weak keyword::.), an
identifier can be followed only by `,' and `:'. These two tokens cannot
follow an `external' directive (not even in `external LIBNAME').

   However, in other contexts, identifiers can be followed by other
tokens (even in an `id_list', e.g. `procedure Foo (var External; i:
Integer);'), so we accept `p_external' as a `new_identifier' everywhere
except in variable declarations (`new_identifier_limited'
`id_list_limited').

   `fjf793*.pas' are test programs for `external'.

   (Basically the same applies to the deprecated `asmname'.)


File: gpc.info,  Node: forward near far,  Next: implementation constructor destructor operator uses import initialization,  Prev: external as a weak keyword,  Up: Parsing keywords

`forward', `near' and `far' as weak keywords
............................................

`forward' is a little special in ISO 7185 in that it is no keyword, so
it may be used as an identifier and a directive at the same time.
That's more than what our weak keywords allow.

   This problem would be easy to solve if we just parsed it as a plain
identifier (`LEX_ID') and then check that it was in fact `forward'.

   However, the same applies to the BP directives `near' and `far'. (At
least so it seems - the BP documentation claims they're reserved words,
but the compiler seems to think otherwise.)

   Parsing all the three together as an identifier and then checking
which one it was fails because `forward' is a remote directive, i.e. a
routine declared so has no body, while `near' and `far' are not. So it
makes a syntactical difference for what follows.

   So we need a new trick: We lex the three like regular (non-weak)
keywords, but throw their tokens together with `LEX_ID' very early in
the parser, in the `id' rule which is used everywhere an existing
identifier is expected. But in the context of these three directives,
no identifier is allowed, so the three tokens can be used without
conflicts between each other or with `id'.


File: gpc.info,  Node: implementation constructor destructor operator uses import initialization,  Prev: forward near far,  Up: Parsing keywords

`implementation', `constructor', `destructor', `operator', `uses', `import' and `initialization' as weak keywords
.................................................................................................................

In ISO 7185 Pascal, each section of the source code is uniquely
introduced by a keyword (`program', `const', `type', `var', `label',
`procedure', `function', `begin'). However, the ending of some of these
sections (in particular `const', `type' and `var') is not intrinsically
defined, but only by the context (the next of these "critical"
keywords). E.g., `var Foo: Integer;' can be a complete variable
declaration part (if one of those keywords follows), or only a part of
one, as in `var Foo: Integer; Bar: Integer;'. (For the other keywords,
the ending is intrinsically defined - the `program' heading and `label'
declarations end with the next `;'. For `procedure' and `function' it's
a little more complicated, due to `forward' declarations, but still
well-defined, and `begin' ends with the matching `end'). The same
applies to sections within one routine, except that `program' cannot
occur there.

   Extended Pascal adds `to' (in `to begin do' and `to end do') and
`end' (in interface modules and implementation modules without
initializer and finalizer) to those "critical" keywords.

   But it also adds two keywords which are not defined in classic
Pascal, namely `export' and `import'. But they can only occur at the
beginning of the source or of a module implementation so they have
fewer chances to conflict with those other keywords.  The same applies
to UCSD/Borland Pascal's `uses' for units.  (`uses' terminates at the
first `;', `export' and `import' do not necessarily, like `var' etc.)

   The problem gets bigger with UCSD/Borland Pascal's `implementation'
in units. It can occur after the interface part, so it might follow,
e.g., a variable declaration part. And it is not an ISO 7185 Pascal
keyword.

   If we want to treat `implementation' as a weak keyword, it must not
conflict with _new_ identifiers anywhere in the grammar.

   However, variable declaration parts are not self-contained in the
sense described above, so after a variable declaration part it is not
immediately clear if the part is finished or will continue. So this is
a place where a new identifier is acceptable. E.g.:

     interface
     
     var
       Bar: Integer;
       Implementation: Integer;

   vs.

     interface
     
     var
       Bar: Integer;
     
     implementation

   The same applies to `implementation' after `const', `type', `export'
and `import' parts.

   The same problem also occurs with the Borland Pascal and Object
Pascal keywords `constructor' and `destructor', the Borland Delphi
keyword `initialization', and the PXSC keyword `operator' since the
respective declarations can follow variable declaration blocks etc. It
also happens with `import' (but it is only possible after an `export'
part) and with `uses' if we allow it after other declarations (GPC
extension).

   Again, we play some lexer tricks. We observe that the new identifier
in `export', `var', `const' and `type' is always followed by either
`,', `:' or `=' while none of the keywords `implementation',
`constructor', `destructor', `operator', `import' and `uses' is ever
followed by one of these symbols ... with two exceptions: `operator ='
is valid, overloading the `=' operator.  Consider:

     type
       Foo = record end;
       Operator = (a, b);  { enum type }

   vs.

     type
       Foo = record end;
     
     operator = (a, b: Foo) c: Foo;

   To decide whether `operator' is a keyword, we would have to look
ahead _six tokens_! Anyway, that seems to be a new record (where
"record" in this sentence can be read either as a Pascal keyword or in
at least one of the usual English meanings ;-).

   The other exception is that `initialization' can, in principle, be
followed by `(', as in:

     implementation
     
     type
       Foo = Integer;
       Initialization (Obj: Integer)

   vs.

     implementation
     
     type
       Foo = Integer;
     
     Initialization
       (Obj as SubObj).Method;

   This would require 3 tokens look-ahead. However, a `(' at the
beginning of a statement is quite uncommon, so we just disallow that,
so the use of `Initialization' as an identifier is not restricted.

   Doing so much look-ahead would be a huge effort and cause some
complications as noted above. This seems inappropriate for such an
academic example. So, until someone comes up with a clever trick to
cope with this case, we give up here and let `operator' before `=' be a
keyword, so overloading `=' is possible. This means that `operator'
cannot be used as an `export' interface, a type or an (untyped)
constant, unless the keyword is disabled explicitly or by dialect
options. (Enabling and disabling the keyword by the parser would also
have been no option here, since the parser would need the 6-token
look-ahead just as well, which it cannot do.)

   You may have noticed that we "forgot" `import' (in the list of
possibly unfinished sections; not in the list of critical following
keywords where it was alright; it actually plays both roles in this
discussion).

   This is because the identifier at the beginning of an import
specification can be followed by `qualified', `only', `in', `(' or `;'
- the former two of which are non-standard keywords as well and would
therefore conflict with a new identifier after, e.g., `uses' and
`operator'.

   This means that there's no simple general solution. So let's
consider the problematic keywords after an `import' part in detail:

   * `import'. Can't happen since EP only allows only `import' part
     (possibly containing multiple import specifications). So this one
     doesn't cause a S/R conflict, unlike the following ones.

   * `uses'. Combining module-style `import' with unit-style `uses' is
     a direct mix of different standards.  According to the discussion
     above, it would lead to the following ambiguity:

          import Foo; Uses only (a);  { import only `a' from `Uses' }

     vs.

          import Foo;
          
          uses Only (a);  { import `a' from `Only' }

     Though `uses' with an import-list is another "cross-standard"
     extension, disallowing it would only reduce the issue from an
     ambiguity to a two-token look-ahead conflict and not really help
     much - whereas it would devalue the usefulness of `uses' which
     otherwise can always serve as a substitute for `import', e.g.  to
     avoid all the conflicts discussed here (because `uses' is
     terminated by the first `;').

   * `operator'.

          import Foo; Operator only (a, b);

     (i.e., import only `a' and `b' from an interface called
     `Operator'), vs.

          import Foo;
          
          operator Only (a, b: Integer) c: Integer;

     As in the case of `operator =', we would need 6 tokens of
     look-ahead. We have to give up.

   * `implementation'. This does not happen for module implementations
     since their syntax is different (`module Foo implementation;'),
     but for unit implementations. Combining these with module-style
     `import' is therefore "cross-standard" already. In addition, it
     would imply an empty interface part (apart from the imports) which
     is rather pointless in units (whereas it might be useful in
     modules, containing only re-exports, but as noted, module
     implementations are unproblematic here).

   * `constructor' and `destructor'. In an interface, these actually do
     not make sense immediately after `import' since their purpose is
     to implement constructors and destructors of object types that
     must have been declared before (not imported). But it could happen
     in an implementation.


   We forbid all of these keywords immediately after an `import' part.
This is achieved using parser precedence rules.


File: gpc.info,  Node: Parsing subranges,  Prev: Parsing keywords,  Up: Language definition

Expressions as lower bounds of subranges
----------------------------------------

Extended Pascal allows arbitrary expressions as the lower bounds of
subrange types. This leads to some following parsing difficulties:

     type
       a = (expr1) .. expr2;

   (if `expr1' starts with an identifier) vs.

     type
       a = (enum1, enum2);

   If the enum type contains at least two items, we get no real
conflicts, but what the bison manual calls "mystery conflicts", i.e.
our grammer is LR(1), but not LALR(1) which bison requires, *Note
Mystery Conflicts: (bison)Mystery Conflicts.

   Our solution is the one suggested in the bison manual, to add a
bogus rule. For that we add a new terminal `BOGUS' which is never used
and a new nonterminal `conflict_id' which contains the identifiers that
are responsible for the six conflicts.

   It gets more difficult if the enum type has only one item, i.e.:

     type
       a = (enum1);

   If further `expr1' consists of a single identifier, the conflict
cannot be resolved without reading the token following the right
parenthesis. (This is inherent in the EP language.)

   But already after reading the identifier (`expr1' or `enum1'), our
parser has to decide whether to reduce it to an expression or to keep
it as an identifier. (The alternative would be to define an expression
which is anything but a single identifier, and parse `(IDENTIFIER)' as
a distinct thing, but this would get quite hairy.)

   We resolve it with a lexer hack. The lexer turns a right parenthesis
which is followed by `..' into the new token `LEX_RPAR'.  Most places
in the parser treat `LEX_RPAR' and `)' as equivalent (nonterminal
`rpar'). However, enum types allow only `)' (they can never be followed
by `..'), and the lower bound of a subrange allows only `LEX_RPAR' (it
is always followed by `..'). This resolves the conflict.

   But there are more conflicts if the lower bound is not enclosed in
parentheses:

     type
       a = Foo (42) .. expr2;

   (where `Foo' can be one of certain built-in functions such as `Sqr',
or a type name for a type-cast) vs.

     type
       a = Bar (42);

   (where `Bar' is an undiscriminated schema type).

   To resolve this, we let the lexer return a special token
`LEX_SCHEMA' for identifiers which correspond to undiscriminated schema
types. The parser accepts this token in `new_identifier' (so schema
identifiers can be redefined) and `typename' (e.g. for parameters), but
not in `id' (which appears in expressions) where undiscriminated schema
types are invalid.

   The last conflict:

     type
       a = @Foo = (EXPR) .. expr2;

   (where `@' is the BP address operator - the `= (EXPR)' is there to
create an ordinal (namely, Boolean) expression that starts with the
address operator) vs.

     type
       a = @Bar = (EXPR);

   (where `@' is a lexical alternative for `^', according to the
standards).

   The conflict arises already with the `@' token. The `=' (as a
comparison operator in the first case, and for a type initializer - EP
extension, combined with a BP extension of using `=' instead of
`value') just adds to the problem. Since EXPR can be arbitrary long,
the conflict is in fact not solvable with any fixed number of lookup
tokens.

   This conflict is decided using parser precedence rules, in favour of
the latter interpretation. (BP itself can't parse the supposedly BP
compatible former syntax.)

   Another parsing problem is the innocent-looking (BP compatible)
`New' call for objects with constructors:
     New (ObjectPointer, ConstructorCall (Arguments))

   This conflicts with:
     New (SchemaPointer, FunctionCall (Arguments))

   The same goes for `Dispose' with destructors. Since the constructor
name is used without naming the object type, it needs special handling.
Trying to solve it using `pascal_shadow_record_fields' (which is used
to handle `with' statements and the implicit `Self' parameter in object
methods), fails for two reasons: First, only constructors (or
destructors, respectively), no other methods, must be recognized.  This
could be solved with a special flag to `pascal_shadow_record_fields'.

   But secondly, the constructor must be recognized only in the first
position of the second argument (see `fjf915[ab].pas' for some evil
examples). This means the same identifier (here: `Init') can have a
different meaning in different positions of the same statement. This is
completely contrary to the usual Pascal scoping rules, but actually
BP's behaviour.

   Since the two forms of `New' shown above look completely the same
syntactically (the difference is given by the type, i.e. the semantic
value, of the first argument of `New'), we can't distinguish them
during parsing without further tricks.

   Using a GLR parser, the `%merge' feature looked promising, but it
also does not help here since it first evaluates both alternatives and
then merges them (in a user-defined way, which would be fine since it
could look at the type). But trying to evaluate the respective wrong
alternative would already produce error messages which can't be undone
later.

   So we resort to a lexical tie-in. After parsing the first argument
(`start_of_new'), we store it in the global variable
`current_structor_object_type' which the lexer recognizes and returns
the special token `LEX_STRUCTOR' for the _first_ following occurrence
of an identifier that denotes a constructor/destructor of this object
type. This token is then required in the syntax rules for an object
`New' call with a constructor (whereas an object `New' call without
constructor is parsed the same way as a non-object `New' call).

   To avoid mis-parsing, we accept `LEX_STRUCTOR' nowhere else in the
grammar, and in the rule for `New' call with further arguments which
are not a constructor, we verify that the first argument is no object
(otherwise something like `New (ObjectPointer, SomeFunction)' could be
accepted syntactially and cause havoc in the further stages).

   This method has all the usual drawbacks of lexer tie-ins, in
particular it would break if the parser had already read ahead too far
when the first argument of `New' is handled (which is in principle not
impossible with GLR). On the other hand, that's the same when the lexer
looks at declarations, which include identifiers made available by
`with', so this new kludge is at least no worse than a `with' based
alternative (if the latter would work at all).


File: gpc.info,  Node: Tree nodes,  Next: Parameter passing,  Prev: Language definition,  Up: Internals

Tree Nodes
==========

If you want really to understand how the GNU Pascal language front-end
works internally and perhaps want to improve the compiler, it is
important that you understand GPC's internal data structures.

   The data structure used by the language front-end to hold all
information about your Pascal program are the so-called "tree nodes".
(Well, it needn't be Pascal source - tree nodes are language
independent.) The tree nodes are kind of objects, connected to each
other via pointers. Since the GNU compiler is written in C and was
created at a time where nobody really thought about object-oriented
programming languages yet, a lot of effort has been taken to create
these "objects" in C.

   Here is an extract from the "object hierarchy". Omissions are marked
with "..."; nodes in parentheses are "abstract": They are never
instantiated and aren't really defined. They only appear here to
clarify the structure of the tree node hierarchy. The complete list is
in `../tree.def'; additional information can be found in `../tree.h'.

     (tree_node)
     |
     |--- ERROR_MARK  { enables GPC to continue after an error }
     |
     |--- (identifier)
     |    |
     |    |--- IDENTIFIER_NODE
     |    |
     |    \--- OP_IDENTIFIER
     |
     |--- TREE_LIST  { a list of nodes, also used as a
     |                  general-purpose "container object" }
     |
     |--- TREE_VEC
     |
     |--- BLOCK
     |
     |--- (type)  { information about types }
     |    |
     |    |--- VOID_TYPE
     |    |
     |    |--- INTEGER_TYPE
     |   ...
     |    |
     |    |--- RECORD_TYPE
     |    |
     |    |--- FUNCTION_TYPE
     |    |
     |    \--- LANG_TYPE  { for language-specific extensions }
     |
     |--- INTEGER_CST  { an integer constant }
     |
     |--- REAL_CST
     |
     |--- STRING_CST
     |
     |--- COMPLEX_CST
     |
     |--- (declaration)
     |    |
     |    |--- FUNCTION_DECL
     |   ...
     |    |
     |    |--- TYPE_DECL
     |    |
     |    \--- VAR_DECL
     |
     |--- (reference)
     |    |
     |    |--- COMPONENT_REF
     |   ...
     |    |
     |    \--- ARRAY_REF
     |
     |--- CONSTRUCTOR
     |
     \--- (expression)
          |
          |--- MODIFY_EXPR  { assignment }
          |
          |--- PLUS_EXPR  { addition }
         ...
          |
          |--- CALL_EXPR  { procedure/function call }
          |
          |--- GOTO_EXPR
          |
          \--- LOOP_EXPR  { for all loops }

   Most of these tree nodes - struct variables in fact - contain
pointers to other tree nodes. A `TREE_LIST' for instance has a
`TREE_VALUE' and a `TREE_PURPOSE' slot which can contain arbitrary
data; a third pointer `TREE_CHAIN' points to the next `TREE_LIST' node
and thus allows us to create linked lists of tree nodes.

   One example: When GPC reads the list of identifiers in a variable
declaration

     var
       Foo, Bar, Baz: Integer;

   the parser creates a chain of `TREE_LIST's whose `TREE_VALUE's hold
`IDENTIFIER_NODE's for the identifiers `Foo', `Bar', and `Baz'. The
function `declare_variables()' (declared in `declarations.c') gets this
tree list as a parameter, does some magic, and finally passes a chain
of `VAR_DECL' nodes to the back-end.

   The `VAR_DECL' nodes in turn have a pointer `TREE_TYPE' which holds
a `_TYPE' node - an `INTEGER_TYPE' node in the example above. Having
this, GPC can do type-checking when a variable is referenced.

   For another example, let's look at the following statement:

     Baz := Foo + Bar;

   Here the parser creates a `MODIFY_EXPR' tree node. This node has two
pointers, `TREE_OPERAND[0]' which holds a representation of `Baz', a
`VAR_DECL' node, and `TREE_OPERAND[1]' which holds a representation of
the sum `Foo + Bar'. The sum in turn is represented as a `PLUS_EXPR'
tree node whose `TREE_OPERAND[0]' is the `VAR_DECL' node `Foo', and
whose `TREE_OPERAND[1]' is the `VAR_DECL' node `Bar'. Passing this (the
`MODIFY_EXPR' node) to the back-end results in assembler code for the
assignment.

   If you want to have a closer look at these tree nodes, write a line
`{$debug-tree FooBar}' into your program with `FooBar' being some
identifier in your program. This tells GPC to output the contents of
the `IDENTIFIER_NODE' to the standard error file handle in
human-readable form.

   While hacking and debugging GPC, you will also wish to have a look
at these tree nodes in other cases. Use the `debug_tree()' function to
do so. (In fact `{$debug-tree FooBar}' does nothing else than to
`debug_tree()' the `IDENTIFIER_NODE' of the `Foobar' identifier node -
note the capitalization of the first character in the internal
representation.)


File: gpc.info,  Node: Parameter passing,  Next: GPI files,  Prev: Tree nodes,  Up: Internals

Parameter Passing
=================

GPC supports a lot of funny things in parameter lists: value and
reference, `protected' and `const' parameters, strings and other
schemata with specified or unspecified discriminants, conformant and
open arrays, objects, procedural parameters, untyped reference
parameters, etc. All this requires sophisticated type-checking; the
responsible function is `convert_arguments()' in the source file
`typecheck.c'.  Every detail can be looked up from there.

   Some short notes about the most interesting cases follow.

*Conformant arrays:*
     First, the array bounds are passed (an even number of parameters of
     an ordinal type), then the address(es) of the array(s) themselves.

*Procedural parameters:*
     These need special care because a function passed as a parameter
     can be confused with a call to the function whose result is then
     passed as a parameter. See also the functions
     `maybe_call_function()' and `probably_call_function()' in
     `expressions.c'.

*Chars:*
     According to ISO 10206 Extended Pascal, formal char parameters
     accept string values. GPC does the necessary conversion implicitly.
     The empty string produces a space.

*Strings and schemata:*
     Value parameter strings and schemata of known size are really
     passed by value. Value parameter strings and schemata of unknown
     size are passed by reference, and GPC creates temporary variable
     to hold a copy of the string.

*`CString' parameters:*
     GPC implicitly converts any string value such that the address of
     the actual string data is passed and appends a `Chr (0)'
     terminator when necessary.

*`const' parameters:*
     If a constant value is passed to a `const' parameter, GPC assigns
     the value to a temporary variable whose address is passed.
     Exception: Small types (whose size is known and not bigger than
     that of a pointer) as well as all integer, real and complex types
     are passed by value.

*Untyped parameters:*
     These are denoted by `var foo' or `var foo: Void' and are
     compatible to C's `void *' parameters; the size of such entities
     is _not_ passed. Maybe we will change this in the future and pass
     the size for `var foo' parameters whereas `var foo: Void' will
     remain compatible to C. (Same with `const' instead of `var'.)



File: gpc.info,  Node: GPI files,  Next: Automake,  Prev: Parameter passing,  Up: Internals

GPI files - GNU Pascal Interfaces
=================================

This section documents the mechanism how GPC transfers information from
the exporting modules and units to the program, module or unit which
imports (uses) the information.

   A GPI file contains a precompiled GNU Pascal interface.
"Precompiled" means in this context that the interface already has been
parsed (i.e. the front-end has done its work), but that no assembler
output has been produced yet.

   The GPI file format is an implementation-dependent (but not _too_
implementation-dependent ;-) file format for storing GNU Pascal
interfaces to be exported - Extended Pascal and PXSC module interfaces
as well as interface parts of UCSD/Borland Pascal units compiled with
GNU Pascal.

   To see what information is stored in or loaded from a GPI file, run
GPC with an additional command-line option `--debug-gpi'. Then, GPC
will write a human-readable version of what is being stored/loaded to
the standard error file handle. (See also: *Note Tree nodes::.) *Please
note:* This will usually produce _huge_ amounts of output!

   While parsing an interface, GPC stores the names of exported objects
in tree lists - look for `handle_autoexport' in the GPC source files.
At the end of the interface, everything is stored in one or more GPI
files. This is done in `module.c'. There you can find the source of
`create_gpi_files()' which documents the file format:

   First, a header of 33 bytes containing the string `GNU Pascal
unit/module interface' plus a newline.

   This is followed by an integer containing the "magic" value 12345678
(hexadecimal) to carry information about the endianness.  Note that,
though a single GPI file is always specific to a particular target
architecture, the host architecture (i.e., the system on which GPC
runs) can be different (cross-compilers).  Currently, GPC is not able
to convert endianness in GPI files "on the fly", but at least it will
detect and reject GPI files with the "wrong" endianness. When writing
GPI files, always the host's endianness is used (this seems to be a
good idea even when converting on the fly will be supported in the
future, since most often, GPI files created by a cross-compiler will be
read again by the same cross-compiler). "Integer" here and in the
following paragraphs means a `gpi_int' (which is currently defined as
`HOST_WIDE_INT').

   The rest of the GPI file consists of chunks. Each chunk starts with
a one-byte code that describes the type of the chunk. It is followed by
an integer that specifies the size of the chunk (excluding this chunk
header). The further contents depend on the type, as listed below.

   For the numeric values of the chunk type codes, please refer to
`GPI_CHUNKS' in `module.c'. Chunk types denoted with `(*)' must occur
exactly once in a GPI file. Other types may occur any number of times
(including zero times). The order of chunks is arbitrary. "String" here
simply means a character sequence whose length is the chunk's length
(so no terminator is needed).

`GPI_CHUNK_VERSION' (String) (*)
     The version of the GPI file which is the same as the GPC version.
     If `USE_GPI_DEBUG_KEY' is used (which will insert a "magic" value
     at the beginning of each node in the node table, see below, so
     errors in GPI files will be detected more reliably), ` D' is
     appended to this version string. (Currently, `USE_GPI_DEBUG_KEY'
     is used by default.) Furthermore, the GCC backend version is
     appended, since it also influences GPI files.

`GPI_CHUNK_TARGET' (String) (*)
     The target system the GPI file was compiled for.

`GPI_CHUNK_MODULE_NAME' (String) (*)
     The name of the unit/module.

`GPI_CHUNK_SRCFILE' (String) (*)
     The name of the primary source file of the unit/module.

`GPI_CHUNK_IMPORT'
     The name of an interface imported by the current interface. This
     chunk consists of a string followed by the checksum of the imported
     interface's nodes, so the chunk length is the length of the string
     plus the size of an integer. Again, no terminator of the string is
     needed.

     The checksum is currently a simple function of the contents of the
     `GPI_CHUNK_NODES' chunk's contents (see below). This might be
     replaced in the future by a MD5 hash or something else more
     elaborate.

`GPI_CHUNK_LINK' (String)
     The name of a file to link.

`GPI_CHUNK_LIB' (String)
     The name of a library to link (prefixed with `-l').

`GPI_CHUNK_INITIALIZER' (String)
     The name of a module initializer. For technical reasons, any such
     chunk must come _after_ the `GPI_CHUNK_MODULE_NAME' chunk.

`GPI_CHUNK_GPC_MAIN_NAME' (String)
     A `gpc-main' option given in this interface. (More than one
     occurrence is pointless.)

`GPI_CHUNK_NODES' (*)
     The exported names and the objects (i.e., constants, data types,
     variables and routines) they refer to are internally represented as
     so-called _tree nodes_ as defined in the files `../tree.h' and
     `../tree.def' from the GNU compiler back-end. (See also: *Note
     Tree nodes::.)

     The main problem when storing tree nodes is that they form a
     complicated structure in memory with a lot of circular references
     (actually, not a tree, but a directed graph in the usual
     terminology, so the name "tree nodes" is actually a misnomer), so
     the storing mechanism must make sure that nothing is stored
     multiple times.

     The functions `load_node()' and `store_node_fields()' do the main
     work of loading/storing the contents of a tree node with
     references to all its contained pointers in a GPI file. Each tree
     node has a `TREE_CODE' indicating what kind of information it
     contains. Each kind of tree nodes must be stored in a different way
     which is not described here. See the source of these functions for
     details.

     As most tree nodes contain pointers to other tree nodes,
     `load_node()' is an (indirectly) recursive function. Since this
     recursion can be circular (think of a record containing a pointer
     to a record of the same type), we must resolve references to tree
     nodes which already have been loaded. For this reason, all tree
     nodes being loaded are kept in a table (`rb.nodes'). They are
     entered there _before_ all their fields have been loaded (because
     loading them is what causes the recursion). So the table contains
     some incomplete nodes during loading, but at the end of loading a
     GPI file, they have all been completed.

     On the other hand, for `store_node_fields()' the (seeming)
     recursion must be resolved to an iterative process so that the
     single tree nodes are stored one after another in the file, and not
     mixed together. This is the job of `store_tree()'. It uses a hash
     table (see `get_node_id()') for efficiency.

     When re-exporting (directly or indirectly) a node that was imported
     from another interface, and a later compiler run imports both
     interfaces, it must merge the corresponding nodes loaded from both
     interfaces. Otherwise it would get only similar, but not identical
     items. However, we cannot simply omit the re-exported nodes from
     the new interface in case a later compiler run imports only one of
     them.  The same problem occurs when a module exports several
     interfaces. In this case, a program that imports more than one of
     them must recognize their contents as identical where they overlap.

     Therefore, each node in a GPI file is prefixed (immediately before
     its tree code) with information about the interface it was
     originally imported from or stored in first. This information is
     represented as a reference to an `INTERFACE_NAME_NODE' followed by
     the id (as an integer) of the node in that interface. If the node
     is imported again and re-re-exported, this information is copied
     unchanged, so it will always refer to the interface the node was
     originally contained it. For nodes that appear in an interface for
     the first time (the normal case), a single 0 integer is stored
     instead of interface `INTERFACE_NAME_NODE' and id (for shortness,
     since this information is implicit).

     This mechanism is not applied to `INTERFACE_NAME_NODE's since
     there would be a problem when the identifier they represent is the
     name of the interface they come from; neither to
     `IDENTIFIER_NODE's because they are handled somewhat specially by
     the backend (e.g., they contain fields like `IDENTIFIER_VALUE'
     which depend on the currently active declarations, so storing and
     loading them in GPI files would be wrong) because there is only
     one `IDENTIFIER_NODE' ever made for any particular name. But for
     the same reason, it is no problem that the mechanism can't be
     applied to them.

     `INTERFACE_NAME_NODE's are a special kind of tree nodes, only used
     for this purpose. They contain the name of the interface, the name
     of the module (to detect the unlikely case that different modules
     have interfaces of the same name which otherwise might confuse
     GPC), and the checksum of that interface. The latter may seem
     redundant with the checksum stored in the `GPI_CHUNK_IMPORT'
     chunk, but in fact it is not. On the one hand, `GPI_CHUNK_IMPORT'
     chunks occur only for interfaces imported directly, while the
     `INTERFACE_NAME_NODE' mechanism might also refer to interfaces
     imported indirectly. On the other hand, storing the checksum in
     the `GPI_CHUNK_IMPORT' chunks allows the automake mechanism to
     detect discrepancies and force recompilation of the imported
     module, whereas during the handling of the `GPI_CHUNK_NODES'
     chunk, the imported modules must already have been loaded. (It
     would be possible to scan the `GPI_CHUNK_NODES' chunk while
     deciding whether to recompile, but that would be a lot of extra
     effort, compared to storing the checksum in the `GPI_CHUNK_IMPORT'
     chunks.)

     Finally, at the end of the `GPI_CHUNK_NODES' chunk, a checksum of
     its own contents (excluding the checksum itself, of course) is
     appended. This is to detect corrupted GPI files and is independent
     of the other uses of checksums.

`GPI_CHUNK_OFFSETS' (*)
     An offset table for the tree nodes. Each node in a GPI file is
     assigned a unique id (which is stored as an integer wherever nodes
     refer to other nodes). There are some special tree nodes (e.g.,
     `integer_type_node' or `NULL_TREE') which are used very often and
     have fixed meanings. They have been assigned predefined ids, so
     they don't have to be stored in the GPI file at all. Their number
     and values are fixed (but may change between different GPC
     versions), see `SPECIAL_NODES' in `module.c'.

     For the remaining nodes, the `GPI_CHUNK_OFFSETS' table contains
     the file offsets as integers where they are stored within the
     (only) `GPI_CHUNK_NODES' chunk. The offsets are relative to the
     start of that chunk, i.e. after the chunk header. After the table
     (but still in this chunk) the id of the main node which contains
     the list of all exported names is stored as an integer.
     (Currently, this is always the last node, but for the file format
     definition, this is not guaranteed.)

`GPI_CHUNK_IMPLEMENTATION'
     This chunk contains no data (i.e., its size must be 0). Its only
     purpose is to signal that the module implementation or the
     implementation part of the unit has been compiled. (Stored, but not
     used currently.)

   That's it. Now you should be able to "read" GPI files using GPC's
`--debug-gpi' option. There is also a utility `gpidump' (built and
installed with GPC, source code in the `utils' directory) to decode and
show the contents of GPI files. It does also some amount of integrity
checking (a little more than GPC does while loading GPI files), so if
you suspect a problem with GPI files, you might want to run `gpidump'
on them, discarding its standard output (it writes all error reports to
standard error, of course).

   If you encounter a case where the loaded information differs too
much from the stored information, you have found a bug -
congratulations! What "too much" means, depends on the object being
stored in or loaded from the GPI file. Remember that the order things
are loaded from a GPI file is the _reversed_ order things are stored
when considering _different_ recursion levels, but the _same_ order
when considering the _same_ recursion level. (This is important when
using `--debug-gpi'; with `gpidump' you can read the file in any order
you like.)


File: gpc.info,  Node: Automake,  Next: File Layout,  Prev: GPI files,  Up: Internals

GPC's Automake Mechanism - How it Works
=======================================

When a program/module/unit imports (uses) an interface, GPC searches
for the GPI file (see *Note GPI files::) derived from the name of the
interface.

   Case 1: A GPI file was found.

   Each GPI file contains the name of the primary source file (normally
a `.pas' or `.p' file) of the module/unit, and the names of all
interfaces imported. GPC reads this information and invokes itself with
a command like

     gpc foo.pas -M -o foo.d

   This means: preprocess the file, and write down the name of the
object file and those of all its source files in `foo.d'. GPC reads
`foo.d' and looks if the object file exists and if the source was
modified since the creation of the object file and the gpi file. If so,
GPC calls itself again to compile the primary source file. When
everything is done, the `.d' file is removed.  If there was no need to
recompile, all interfaces imported by the module/unit are processed in
the same way as this one.

   Case 2: No GPI file was found.

   In this case, GPC derives the name of the source file from that of
the interface by trying first `interface.p', then `interface.pas'. This
will almost always work with UCSD/Borland Pascal units, but not always
with Extended Pascal modules. The programmer can override this
assumption using `uses ... in' or `import ... in'.

   All this is done by the function `gpi_open()' which uses some
auxiliary functions such as `module_must_be_recompiled()' and
`compile_module()'.

   Each time an object file is compiled or recognized as being
up-to-date, its name is stored in a temporary file with the same base
name as all the other temporary files used by GPC but the extension
`.gpc'. When the top-level `gpc' is invoked (which calls `gpc1' later
on), it passes the name of this temporary file as an additional command
line parameter to `gpc1'. After compilation has been completed, the
top-level `gpc' reads the temporary file and adds the new object files
to the arguments passed to the linker.

   The additional command `--amtmpfile' (not to be specified by the
user!) is passed to child GPC processes, so all compiles use the same
temporary file.

   The source for this is merely in `module.c', but there are also some
hacks in `gpc.c', additional command line options in `lang-options.h'
and `options.c', and `gpc.h' contains declarations for the functions
and global variables.


File: gpc.info,  Node: File Layout,  Next: Planned,  Prev: Automake,  Up: Internals

Files that make up GPC
======================

The GNU back end (gbe) is used to convert RTL into assembler code.  It
is supposed to be language independent. Files are in the `..' directory
(i.e., the directory called `gcc'). It also uses files in the
`../config' subdirectories etc.

   Unfortunately, some of them are not completely language independent
and need patching for GPC. These patches (against all supported GCC
versions) are in the `diffs' subdirectory.

   The Pascal language implementation files are in the directory called
`p'. Some of them were written from scratch. Others are hacked from GCC
sources. Their roots, if any, are mentioned in the comment at their top.


File: gpc.info,  Node: Planned,  Prev: File Layout,  Up: Internals

Planned features
================

AnyStrings
----------

     GetCapacity (s):
       LongString            : s.Capacity
       UndiscriminatedString : MaxInt
       ShortString           : High (s)
       FixedString           : High (s) - Low (s) + 1
       CString (Array)       : High (s) - Low (s)
       CString (Zeiger)      : strlen (s)
       ObjectString          : s.GetCapacity
     
     GetLength (s):
       LongString            : s.Length
       UndiscriminatedString : s.Length
       ShortString           : Ord (s[0])
       FixedString           : c := High (s);
                               while (c >= Low (s)) and (s[c] = ' ') do
                                 Dec (c);
                               c - Low (s) + 1
       CString               : strlen (s)
       ObjectString          : s.GetLength
     
     SetLength (s,n):
       if n > GetCapacity (s) then
         if TruncateFlag then
           n := GetCapacity (s)
         else
           Error;
       LongString            : s.Length := n
       UndiscriminatedString : if n > s.Capacity then
                                 begin
                                   tmp := @s;
                                   { possibly round n up to m * 2^k
                                     to avoid frequent reallocations }
                                   New (@s, n);
                                   Move (tmp^[1], s[1], Length (tmp^);
                                   Dispose (tmp)
                                 end;
                               s.Length := n
       ShortString           : s[0] := Chr (n)
       FixedString           : FillChar (s[Low (s) + n],
                                 GetCapacity (s) - n, ' ')
       CString               : s[n] := #0
       ObjectString          : s.SetLength (n)
     
     GetFirstChar (s):
       LongString            : @s[1]
       UndiscriminatedString : @s[1]
       ShortString           : @s[1]
       FixedString           : @s[Low (s)]
       CString               : s
       ObjectString          : s.GetFirstChar

   Anything else can be reduced to these, e.g. string assignment:

     SetLength (Dest, GetLength (Src));
     Move (GetFirstChar (Src) ^, GetFirstChar (Dest) ^, GetLength (Dest));
                                                                   ^^^^
                                                    (because of truncate!)

   Note pointer CStrings because assignments to them (from long,
undiscriminated (with appending #0) or CStrings, not from short, fixed
or object strings) should set the pointer, not overwrite the memory
pointed to.

Fully automatic C header translator
-----------------------------------

   * C operators like `+=' (increment a variable and return the new
     value), or `/' (integer or real division, depending on the
     arguments). They could be emulated by special built-in functions
     in GPC which do the same ...

   * Types! C doesn't distinguish between pointers and arrays - and
     various other "jokes". E.g., a `CString' and a pointer to an array
     of bytes can both be `char *' in C. Solutions could be to
     introduce "special types" in GPC which behave like the C types
     (not so nice ...)-:, or to let the translator choose one possible
     matching GPC type (by some heuristics perhaps), and leave it up to
     the user to type-cast when necessary (also not nice)-: ...

   * Name clashes. How to map `foo', `FOO', `struct foo', `union foo'
     etc. (which can potentially be totally different things in C) to
     Pascal identifiers in a reasonable way.  Also, how to introduce
     identifiers for types when needed (e.g., typed used in parameter
     lists). Of course, that's solvable ...

   * Macros. Since GPC has a preprocessor, we can translate most of
     them, but some particularly strange ones are virtually impossible
     to translate. But there's hope that such strange macros are not
     being used in the libraries' headers ...

   * ...



File: gpc.info,  Node: Copying,  Next: Library Copying,  Prev: Internals,  Up: Top

GNU GENERAL PUBLIC LICENSE
**************************

                         Version 2, June 1991
     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

GPL Preamble
============

The licenses for most software are designed to take away your freedom
to share and change it.  By contrast, the GNU General Public License is
intended to guarantee your freedom to share and change free software -
to make sure the software is free for all its users.  This General
Public License applies to most of the Free Software Foundation's
software and to any other program whose authors commit to using it.
(Some other Free Software Foundation software is covered by the GNU
Lesser General Public License instead.)  You can apply it to your
programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
modification follow.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  0. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  2. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  5. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  7. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

  9. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 10. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY

 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs
=============================================

If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
     Copyright (C) YEAR  NAME OF AUTHOR
     
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

   Also add information on how to contact you by electronic and paper
mail.

   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items - whatever suits your
program.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright interest in the program
     `Gnomovision' (which makes passes at compilers) written by James Hacker.
     
     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Lesser General Public License instead of this License.


File: gpc.info,  Node: Library Copying,  Next: Demo Copying,  Prev: Copying,  Up: Top

GNU LESSER GENERAL PUBLIC LICENSE
*********************************

                      Version 2.1, February 1999
     Copyright (C) 1991, 1999 Free Software Foundation, Inc.
     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.
     
     [This is the first released version of the Lesser GPL.  It also counts
     as the successor of the GNU Library Public License, version 2, hence the
     version number 2.1.]

LGPL Preamble
=============

The licenses for most software are designed to take away your freedom
to share and change it.  By contrast, the GNU General Public Licenses
are intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.

   This license, the Lesser General Public License, applies to some
specially designated software--typically libraries--of the Free
Software Foundation and other authors who decide to use it.  You can use
it too, but we suggest you first think carefully about whether this
license or the ordinary General Public License is the better strategy to
use in any particular case, based on the explanations below.

   When we speak of free software, we are referring to freedom of use,
not price.  Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of it
in new free programs; and that you are informed that you can do these
things.

   To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights.  These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.

   For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you.  You must make sure that they, too, receive or can get the source
code.  If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it.  And you must show them these terms so they know their rights.

   We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.

   To protect each distributor, we want to make it very clear that
there is no warranty for the free library.  Also, if the library is
modified by someone else and passed on, the recipients should know that
what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.

   Finally, software patents pose a constant threat to the existence of
any free program.  We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder.  Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.

   Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License.  This license, the GNU Lesser
General Public License, applies to certain designated libraries, and is
quite different from the ordinary General Public License.  We use this
license for certain libraries in order to permit linking those
libraries into non-free programs.

   When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library.  The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom.  The Lesser General
Public License permits more lax criteria for linking other code with
the library.

   We call this license the "Lesser" General Public License because it
does _Less_ to protect the user's freedom than the ordinary General
Public License.  It also provides other free software developers Less
of an advantage over competing non-free programs.  These disadvantages
are the reason we use the ordinary General Public License for many
libraries.  However, the Lesser license provides advantages in certain
special circumstances.

   For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it
becomes a de-facto standard.  To achieve this, non-free programs must be
allowed to use the library.  A more frequent case is that a free
library does the same job as widely used non-free libraries.  In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.

   In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of free
software.  For example, permission to use the GNU C Library in non-free
programs enables many more people to use the whole GNU operating
system, as well as its variant, the GNU/Linux operating system.

   Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run that
program using a modified version of the Library.

   The precise terms and conditions for copying, distribution and
modification follow.  Pay close attention to the difference between a
"work based on the library" and a "work that uses the library".  The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.

                   GNU LESSER GENERAL PUBLIC LICENSE
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  0. This License Agreement applies to any software library or other
     program which contains a notice placed by the copyright holder or
     other authorized party saying it may be distributed under the
     terms of this Lesser General Public License (also called "this
     License").  Each licensee is addressed as "you".

     A "library" means a collection of software functions and/or data
     prepared so as to be conveniently linked with application programs
     (which use some of those functions and data) to form executables.

     The "Library", below, refers to any such software library or work
     which has been distributed under these terms.  A "work based on the
     Library" means either the Library or any derivative work under
     copyright law: that is to say, a work containing the Library or a
     portion of it, either verbatim or with modifications and/or
     translated straightforwardly into another language.  (Hereinafter,
     translation is included without limitation in the term
     "modification".)

     "Source code" for a work means the preferred form of the work for
     making modifications to it.  For a library, complete source code
     means all the source code for all modules it contains, plus any
     associated interface definition files, plus the scripts used to
     control compilation and installation of the library.

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running a program using the Library is not restricted, and
     output from such a program is covered only if its contents
     constitute a work based on the Library (independent of the use of
     the Library in a tool for writing it).  Whether that is true
     depends on what the Library does and what the program that uses
     the Library does.

  1. You may copy and distribute verbatim copies of the Library's
     complete source code as you receive it, in any medium, provided
     that you conspicuously and appropriately publish on each copy an
     appropriate copyright notice and disclaimer of warranty; keep
     intact all the notices that refer to this License and to the
     absence of any warranty; and distribute a copy of this License
     along with the Library.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  2. You may modify your copy or copies of the Library or any portion
     of it, thus forming a work based on the Library, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. The modified work must itself be a software library.

       b. You must cause the files modified to carry prominent notices
          stating that you changed the files and the date of any change.

       c. You must cause the whole of the work to be licensed at no
          charge to all third parties under the terms of this License.

       d. If a facility in the modified Library refers to a function or
          a table of data to be supplied by an application program that
          uses the facility, other than as an argument passed when the
          facility is invoked, then you must make a good faith effort
          to ensure that, in the event an application does not supply
          such function or table, the facility still operates, and
          performs whatever part of its purpose remains meaningful.

          (For example, a function in a library to compute square roots
          has a purpose that is entirely well-defined independent of the
          application.  Therefore, Subsection 2d requires that any
          application-supplied function or table used by this function
          must be optional: if the application does not supply it, the
          square root function must still compute square roots.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Library, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Library, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Library.

     In addition, mere aggregation of another work not based on the
     Library with the Library (or with a work based on the Library) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  3. You may opt to apply the terms of the ordinary GNU General Public
     License instead of this License to a given copy of the Library.
     To do this, you must alter all the notices that refer to this
     License, so that they refer to the ordinary GNU General Public
     License, version 2, instead of to this License.  (If a newer
     version than version 2 of the ordinary GNU General Public License
     has appeared, then you can specify that version instead if you
     wish.)  Do not make any other change in these notices.

     Once this change is made in a given copy, it is irreversible for
     that copy, so the ordinary GNU General Public License applies to
     all subsequent copies and derivative works made from that copy.

     This option is useful when you wish to copy part of the code of
     the Library into a program that is not a library.

  4. You may copy and distribute the Library (or a portion or
     derivative of it, under Section 2) in object code or executable
     form under the terms of Sections 1 and 2 above provided that you
     accompany it with the complete corresponding machine-readable
     source code, which must be distributed under the terms of Sections
     1 and 2 above on a medium customarily used for software
     interchange.

     If distribution of object code is made by offering access to copy
     from a designated place, then offering equivalent access to copy
     the source code from the same place satisfies the requirement to
     distribute the source code, even though third parties are not
     compelled to copy the source along with the object code.

  5. A program that contains no derivative of any portion of the
     Library, but is designed to work with the Library by being
     compiled or linked with it, is called a "work that uses the
     Library".  Such a work, in isolation, is not a derivative work of
     the Library, and therefore falls outside the scope of this License.

     However, linking a "work that uses the Library" with the Library
     creates an executable that is a derivative of the Library (because
     it contains portions of the Library), rather than a "work that
     uses the library".  The executable is therefore covered by this
     License.  Section 6 states terms for distribution of such
     executables.

     When a "work that uses the Library" uses material from a header
     file that is part of the Library, the object code for the work may
     be a derivative work of the Library even though the source code is
     not.  Whether this is true is especially significant if the work
     can be linked without the Library, or if the work is itself a
     library.  The threshold for this to be true is not precisely
     defined by law.

     If such an object file uses only numerical parameters, data
     structure layouts and accessors, and small macros and small inline
     functions (ten lines or less in length), then the use of the object
     file is unrestricted, regardless of whether it is legally a
     derivative work.  (Executables containing this object code plus
     portions of the Library will still fall under Section 6.)

     Otherwise, if the work is a derivative of the Library, you may
     distribute the object code for the work under the terms of Section
     6.  Any executables containing that work also fall under Section 6,
     whether or not they are linked directly with the Library itself.

  6. As an exception to the Sections above, you may also combine or
     link a "work that uses the Library" with the Library to produce a
     work containing portions of the Library, and distribute that work
     under terms of your choice, provided that the terms permit
     modification of the work for the customer's own use and reverse
     engineering for debugging such modifications.

     You must give prominent notice with each copy of the work that the
     Library is used in it and that the Library and its use are covered
     by this License.  You must supply a copy of this License.  If the
     work during execution displays copyright notices, you must include
     the copyright notice for the Library among them, as well as a
     reference directing the user to the copy of this License.  Also,
     you must do one of these things:

       a. Accompany the work with the complete corresponding
          machine-readable source code for the Library including
          whatever changes were used in the work (which must be
          distributed under Sections 1 and 2 above); and, if the work
          is an executable linked with the Library, with the complete
          machine-readable "work that uses the Library", as object code
          and/or source code, so that the user can modify the Library
          and then relink to produce a modified executable containing
          the modified Library.  (It is understood that the user who
          changes the contents of definitions files in the Library will
          not necessarily be able to recompile the application to use
          the modified definitions.)

       b. Use a suitable shared library mechanism for linking with the
          Library.  A suitable mechanism is one that (1) uses at run
          time a copy of the library already present on the user's
          computer system, rather than copying library functions into
          the executable, and (2) will operate properly with a modified
          version of the library, if the user installs one, as long as
          the modified version is interface-compatible with the version
          that the work was made with.

       c. Accompany the work with a written offer, valid for at least
          three years, to give the same user the materials specified in
          Subsection 6a, above, for a charge no more than the cost of
          performing this distribution.

       d. If distribution of the work is made by offering access to copy
          from a designated place, offer equivalent access to copy the
          above specified materials from the same place.

       e. Verify that the user has already received a copy of these
          materials or that you have already sent this user a copy.

     For an executable, the required form of the "work that uses the
     Library" must include any data and utility programs needed for
     reproducing the executable from it.  However, as a special
     exception, the materials to be distributed need not include
     anything that is normally distributed (in either source or binary
     form) with the major components (compiler, kernel, and so on) of
     the operating system on which the executable runs, unless that
     component itself accompanies the executable.

     It may happen that this requirement contradicts the license
     restrictions of other proprietary libraries that do not normally
     accompany the operating system.  Such a contradiction means you
     cannot use both them and the Library together in an executable
     that you distribute.

  7. You may place library facilities that are a work based on the
     Library side-by-side in a single library together with other
     library facilities not covered by this License, and distribute
     such a combined library, provided that the separate distribution
     of the work based on the Library and of the other library
     facilities is otherwise permitted, and provided that you do these
     two things:

       a. Accompany the combined library with a copy of the same work
          based on the Library, uncombined with any other library
          facilities.  This must be distributed under the terms of the
          Sections above.

       b. Give prominent notice with the combined library of the fact
          that part of it is a work based on the Library, and explaining
          where to find the accompanying uncombined form of the same
          work.

  8. You may not copy, modify, sublicense, link with, or distribute the
     Library except as expressly provided under this License.  Any
     attempt otherwise to copy, modify, sublicense, link with, or
     distribute the Library is void, and will automatically terminate
     your rights under this License.  However, parties who have
     received copies, or rights, from you under this License will not
     have their licenses terminated so long as such parties remain in
     full compliance.

  9. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Library or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Library (or any work
     based on the Library), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Library or works based on it.

 10. Each time you redistribute the Library (or any work based on the
     Library), the recipient automatically receives a license from the
     original licensor to copy, distribute, link with or modify the
     Library subject to these terms and conditions.  You may not impose
     any further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties with this License.

 11. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Library at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Library by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Library.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply, and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

 12. If the distribution and/or use of the Library is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Library under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

 13. The Free Software Foundation may publish revised and/or new
     versions of the Lesser General Public License from time to time.
     Such new versions will be similar in spirit to the present version,
     but may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Library specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Library
     does not specify a license version number, you may choose any
     version ever published by the Free Software Foundation.

 14. If you wish to incorporate parts of the Library into other free
     programs whose distribution conditions are incompatible with these,
     write to the author to ask for permission.  For software which is
     copyrighted by the Free Software Foundation, write to the Free
     Software Foundation; we sometimes make exceptions for this.  Our
     decision will be guided by the two goals of preserving the free
     status of all derivatives of our free software and of promoting
     the sharing and reuse of software generally.

                                NO WARRANTY

 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU.  SHOULD THE
     LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY
     OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Libraries
==============================================

If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change.  You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of
the ordinary General Public License).

   To apply these terms, attach the following notices to the library.
It is safest to attach them to the start of each source file to most
effectively convey the exclusion of warranty; and each file should have
at least the "copyright" line and a pointer to where the full notice is
found.

     ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES.
     Copyright (C) YEAR  NAME OF AUTHOR
     
     This library is free software; you can redistribute it and/or modify it
     under the terms of the GNU Lesser General Public License as published by
     the Free Software Foundation; either version 2.1 of the License, or (at
     your option) any later version.
     
     This library is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Lesser General Public License for more details.
     
     You should have received a copy of the GNU Lesser General Public
     License along with this library; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
     USA.

   Also add information on how to contact you by electronic and paper
mail.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the library,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright interest in the library
     `Frob' (a library for tweaking knobs) written by James Random Hacker.
     
     SIGNATURE OF TY COON, 1 April 1990
     Ty Coon, President of Vice

   That's all there is to it!


File: gpc.info,  Node: Demo Copying,  Next: Acknowledgments,  Prev: Library Copying,  Up: Top

DEMO COPYING
************

   This is the common copying notice for all files found in `demos/'
and `docdemos/' (unless stated otherwise in the file itself). They are
distributed under the GNU General Public License with a notable
exception:

   Copyright (C) 1997-2004 Free Software Foundation, Inc.

   Authors: See notice in the demo program. If not listed there, these
are the authors of the GNU Pascal Compiler.

   This demo program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2, or (at
your option) any later version.

   This demo program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

   You should have received a copy of the GNU General Public License
along with this demo program; see the file COPYING. If not, write to
the Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.  *Note Top: Copying.

   As a special exception, if you incorporate even large parts of the
code of this demo program into another program with substantially
different functionality, this does not cause the other program to be
covered by the GNU General Public License. This exception does not
however invalidate any other reasons why it might be covered by the GNU
General Public License.


File: gpc.info,  Node: Acknowledgments,  Next: Resources,  Prev: Demo Copying,  Up: Top

Contributors to GNU Pascal.
***************************

Jukka Virtanen
     invented GNU Pascal in March 1988, implemented the ISO 7185 and
     most of the ISO 10206 standard, etc.

Dr. Peter Gerwinski (http://www.gerwinski.de/~peter/)
     added Borland Pascal related and other extensions to GNU Pascal in
     summer 1995, ported GPC to EMX, did most of the development of the
     compiler from 1996 to 2001, created the WWW home page, etc.

Jan-Jaap van der Heijden
     ported GPC to DJGPP and to Microsoft Windows 95/NT, added ELF
     support in spring 1996, solved a lot of configuration and
     compatibility problems, created the GPC FAQ, etc.

Frank Heckenbach (http://fjf.gnu.de)
     rewrote and maintains the Run Time System since July 1997, does
     most of the development of the compiler since July 2001, wrote
     most of the units, demo programs, scripts and utilities
     distributed with GPC, wrote many test programs, maintains the GPC
     To-Do list (*note To Do::) and the WWW home page, etc.

Waldek Hebisch
     made GPC compatible with gcc-3.1.1 and later backend versions,
     fixed backend problems on various targets and improved the
     frontend in the areas of structured initializers, qualified
     identifiers, etc.

Prof. Abimbola A. Olowofoyeku ("The African Chief") (http://www.bigfoot.com/~african_chief/)
     created the original versions of many BP compatibility units in May
     1997, contributed code to other units and the Run Time System,
     helped porting GPC and the units to Cygwin, mingw and MSYS, wrote a
     number of test programs, contributed a Borland Delphi-compatible
     `SysUtils' unit (http://www.gnu-pascal.de/contrib/chief/), etc.

Nicholas Burrett
     fixed some bugs and cleaned up GPC in May 1998, etc.

Dominik Freche
     improved and extended the GPC manual in August - September 1999 and
     wrote conversion routines for Borland compatible 6 Byte floating
     point numbers in December 1999.

Alexey Volokhov
     improved the performance of GPC's module/unit support in June 1997.

Bill Currie
     implemented more Borland extensions into GPC in July 1997.

Nicola Girardi
     wrote the GNU Pascal Coding Standards in November 2001, contributed
     a GPC unit (http://www.gnu-pascal.de/contrib/nicola/) for the
     `svgalib' graphics library for some platforms in February 2000,
     provided some portability enhancements to the RTS.

Eike Lange
     wrote an internationalization unit, translated the GNU Pascal
     Coding Standards into German and worked on the documentation.

Mirsad Todorovac
     translated the GPC documentation into Croatian and contributed code
     to the run time system.

Francisco Javier Fernandez Serrador
     translated the GPC documentation into Spanish.

Maurice Lombardi
     maintains the DJGPP port of GPC, improved the numerical routines
     for real and complex numbers and improved and extended the GMP real
     routines.

Emil Jerabek
     improved the numerical routines for real and complex numbers.

Neil Santos

Russell Whitaker
     updated and maintains the GNU Pascal FAQ.  (*note FAQ::)

Matthias Klose
     integrated GPC into EGCS and Debian GNU/Linux in May 1998, improved
     the installation process, etc.

Peter N Lewis
     added support for Mac Pascal dialect specific features and improved
     the documentation.

Orlando Llanes
     provided some contributions to the manual in May 1998.


The development of GNU Pascal profits a lot from independent
contributions:

Anja Gerwinski
     maintains the GPC mailing list, since September 1999.

Berend de Boer
     wrote a lot of useful documentation about Extended Pascal in 1995.

Markus Gerwinski (http://www.gerwinski.de/~markus/)
     created the drawing showing a Gnu with Blaise Pascal and helped to
     design the WWW home page in October 1996.

Eike Lange
     is writing a book (http://www.gnu-pascal.org/~eike/) about GPC in
     German since March 2003.

Eike Lange
     wrote units (http://www.gnu-pascal.de/contrib/eike/) to access
     MySQL, GNU DBM and PostgreSQL databases in August 2000, and a unit
     (now part of GPC) and tools for internationalization in October -
     December 2001.

Eike Lange and Nicola Girardi
     together contributed a set of GTK units
     (http://www.gnu-pascal.de/contrib/nicola/) in February - May 2001.

Nicola Girardi
     wrote the GNU Pascal Coding Standards in English. Eike Lange
     translated them to German.

Prof. Phil Nelson
     created a bug reporting system for GPC in October 1996.

Robert Höhne
     wrote RHIDE (http://www.rhide.com), an integrated development
     environment for GNU compilers running under Dos (DJGPP) and Linux,
     and added support for GNU Pascal in autumn 1996.

Sven Hilscher
     wrote a mostly BP compatible `Graph' unit for several platforms in
     December 1996, now part of the GRX library
     (http://www.gnu.de/software/grx/).

Dario Anzani ("Predator Zeta") (http://www.geocities.com/SiliconValley/Vista/6573)
     contributed documentation about the use of assembler in GNU Pascal
     in May 1997.  (*note Assembler::)

Dieter Schmitz
     set up a German mailing list for GPC, *Note Mailing List::, in
     March 2001.

Adriaan van Os
     helped with the port of GPC to Mac OS X and set up a web site
     (http://www.microbizz.nl/gpc.html) with sources, binaries, patches
     and building instructions for this platform in January 2003.

`(-:---------:-)'
     This space is reserved for _your_ name. ;-) Please contact us at
     the GPC mailing list, *Note Mailing List::, if you have something
     interesting for us.


We thank everybody who supports us by reporting bugs, providing
feedback, contributing knowledge and good ideas, donating development
tools, and giving us the opportunity to test GPC on a large variety of
systems. We are particularly indebted (in alphabetical order,
individuals first) to

Sietse Achterop, Jawaad Ahmad, Montaz Ali, Jamie Allan, Strobe Anarkhos,
John P. R. Archer, Phil Armsdon, Geoffrey Arnold, Artur Bac, Steven J.
Backus, Geoff Bagley, Andy Ball, Uwe Bauermann, Silvio a Beccara,
Michael Behm, Ariel Bendersky, Pablo Bendersky, John Blakeney, Nicolas
Bley, Philip Blundell, Preben Mikael Bohn, Ernst-Ludwig Bohnen, Nils
Bokermann, Francesco Bonomi, J. Booij, Patrice Bouchand, Jim Brander,
Frank Thomas Braun, Matthias Braun, Marcus Brinkmann, Steve Brooker,
Doug Brookmann, J. David Bryan, Kev Buckley, Jason Burgon, Ricky W.
Butler, Dr. E. Buxbaum, Andrew Cagney, Loris Caren, Theo Carr-Brion,
Fernando Carrilho, Larry Carter, Fabio Casamatta, Janet Casey, Romain
Chantereau, Emmanuel Chaput, Jean-Pierre Chevillard, Carl Eric Codere,
Jean-Philippe Combe, Paolo Cortelli, F. Couperin, Nicolas Courtel,
Miklos Cserzo, Tim Currie, Serafim Dahl, Paul Davidson, Martin G. C.
Davies, Stefan A. Deutscher, Jerry van Dijk, Thomas Dunbar, Andreas
Eckleder, Stephan Eickschen, Frank D. Engel Jr., Sven Engelhardt, Klaus
Espenlaub, Toby Ewing, Chuck B. Falconer, Joachim Falk, Irfan Fazel,
Carel Fellinger, Francisco Javier Fernandez, Christopher Ferrall, David
Fiddes, Alfredo Cesar Fontana, Kevin A. Foss, B. Gayathri, Marius
Gedminas, Philip George, Nicholas Geovanis, Jose Oliver Gil, Thorsten
Glaser, Jing Gloria, Roland Goretzki, Morten Gulbrandsen, Gerrit P.
Haase, Kocherlakota Harikrishna, Joe Hartley, Hans Hauska, Jakob
Heinemann, Boris Herman, Arvid Herzenberg, Thorsten Hindermann, Honda
Hirotaka, Stephen Hurd, Nick Ioffe, Mason Ip, Fredrik Ismyren, Richard
D. Jackson, Daniel Jacobowitz, Grant Jacobs, Andreas Jaeger, Frank
Jahnke, David James, Nathalie Jarosz, Sven Jauring, Niels Kristian Bech
Jensen, Johanna Johnston, Achim Kalwa, Christine Karow, Tim Kaulmann,
Thomas Keller, Clark Kent, Victor Khimenko, Russell King, Niels Ole
Staub Kirkeby, Prof. Donald E. Knuth, Michael Kochiashvili, Tomasz
Kowaltowski, David Kredba, Peter Ulrich Kruppa, Jochen Kuepper, Casper
ter Kuile, Oliver Kullmann, Krzysztof Kwapien, Randy Latimer, Bernard
Leak, Olivier Lecarme, Wren Lee, Martin Liddle, Kennith Linder, Stephen
Lindholm, Orlando Llanes, Miguel Lobo, Benedict Lofstedt, Steve Loft,
John Logsdon, Dominique Louis, Dmitry S. Luhtionov, Jesper Lund, Martin
Maechler, Muhammad Umer Mansoor, Claude Marinier, Ingvar Marny, Antony
Matranga, Michael McCarthy, Michael Meeks, Clyde Meli, Axel Mellinger,
Bryan Meredith, Jeff Miller, John Miller, Russell Minnich, Rudy
Moddemeijer, Jason Moore, Scott A. Moore, Jeffrey Moskot, Pierre Muller,
Adam Naumowicz, Nathanael Nerode, Andreas Neumann, Christian Neumann,
Peter Norton, Adam Oldham, Gerhard Olejniczak, Alexandre Oliva, John G.
Ollason, Marius Onica, Ole Osterby, Klaus Friis Ostergaard, Jean-Marc
Ottorini, Michael Paap, Gale Paeper, Matija Papec, Miguel A. Alonso
Pardo, Laurent Parise, Andris Pavenis, Robert R. Payne, Opie Pecheux,
Jose M. Perez, Ronald Perrella, Bjorn Persson, Per Persson, Michael
Pfeiffer, Pierre Phaneuf, Pascal Pignard, Tam Pikey, Nuno Pinhao,
Philip Plant, Larry Poorman, Stuart Pope, Yuri Prokushev, Huge
Rademaker, Shafiek Rasdien, Mike Reid, Leon Renkema, John L. Ries, Phil
Robertson, Clive Rodgers, Jim Roland, Guillaume Rousse, Daniel Rudy,
Marten Jan de Ruiter, Martin Rusko, Sven Sahle, Neil Santos, Carl-Johan
Schenstrom, Robert B. Scher, Hartmut Schmider, Thomas D. Schneider,
Dominique Schuppli, Egbert Seibertz, George Shapovalov, Richard Sharman,
Patrick Sharp, Joe da Silva, Arcadio Alivio Sincero, Ian Sinclair,
Kasper Souren, Tomas Srb, Anuradha Srinivasan, David Starner, Andrew
Stribblehill, Alan Sun, Veli Suorsa, Matthew Swift, Mark Taylor, Paul
Tedaldi, Robin S. Thompson, Ian Thurlbeck, Gerhard Tonn, Ivan Torshin,
Bernhard Tschirren, Josef Urban, Luiz Vaz, Tom Verhoeff, Kresimir
Veselic, Jean-Pierre Vial, Alejandro Villarroel, Bohdan Vlasyuk, Marco
van de Voort, Raymond Wang, Nic Webb, Peter Weber, Francisco Stefano
Wechsler, Christian Wendt, Benedikt Wildenhain, Gareth Wilson, Marc van
Woerkom, David Wood, Michael Worsley, Takashi Yamanoue, George L. Yang,
Salaam Yitbarek, Dafi Yondra, Eli Zaretskii, Artur Zaroda, Gerhard
Zintel, Mariusz Zynel, the `BIP' at the `University of Birmingham', UK,
the `Institut fuer Festkoerperforschung (IFF)' at the
`Forschungszentrum Juelich', Germany, CARNet (Croatian Academic and
Research NETwork), the Academy of Fine Arts and the Faculty of Graphic
Arts at the University of Zagreb, Croatia,

and everybody we might have forgotten to mention here.  Thanks to all
of you!

GNU Pascal is based on GNU CC by Richard Stallman. Several people have
contributed to GNU CC:

   * The idea of using RTL and some of the optimization ideas came from
     the program PO written at the University of Arizona by Jack
     Davidson and Christopher Fraser.  See "Register Allocation and
     Exhaustive Peephole Optimization", Software Practice and
     Experience 14 (9), Sept. 1984, 857-866.

   * Paul Rubin wrote most of the preprocessor.

   * Leonard Tower wrote parts of the parser, RTL generator, and RTL
     definitions, and of the Vax machine description.

   * Ted Lemon wrote parts of the RTL reader and printer.

   * Jim Wilson implemented loop strength reduction and some other loop
     optimizations.

   * Nobuyuki Hikichi of Software Research Associates, Tokyo,
     contributed the support for the Sony NEWS machine.

   * Charles LaBrec contributed the support for the Integrated Solutions
     68020 system.

   * Michael Tiemann of Cygnus Support wrote the support for inline
     functions and instruction scheduling.  Also the descriptions of the
     National Semiconductor 32000 series cpu, the SPARC cpu and part of
     the Motorola 88000 cpu.

   * Jan Stein of the Chalmers Computer Society provided support for
     Genix, as well as part of the 32000 machine description.

   * Randy Smith finished the Sun FPA support.

   * Robert Brown implemented the support for Encore 32000 systems.

   * David Kashtan of SRI adapted GNU CC to VMS.

   * Alex Crain provided changes for the 3b1.

   * Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX
     for the 9000 series 300.

   * William Schelter did most of the work on the Intel 80386 support.

   * Christopher Smith did the port for Convex machines.

   * Paul Petersen wrote the machine description for the Alliant FX/8.

   * Dario Dariol contributed the four varieties of sample programs that
     print a copy of their source.

   * Alain Lichnewsky ported GNU CC to the Mips cpu.

   * Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the
     Tahoe.

   * Jonathan Stone wrote the machine description for the Pyramid
     computer.

   * Gary Miller ported GNU CC to Charles River Data Systems machines.

   * Richard Kenner of the New York University Ultracomputer Research
     Laboratory wrote the machine descriptions for the AMD 29000, the
     DEC Alpha, the IBM RT PC, and the IBM RS/6000 as well as the
     support for instruction attributes.  He also made changes to
     better support RISC processors including changes to common
     subexpression elimination, strength reduction, function calling
     sequence handling, and condition code support, in addition to
     generalizing the code for frame pointer elimination.

   * Richard Kenner and Michael Tiemann jointly developed reorg.c, the
     delay slot scheduler.

   * Mike Meissner and Tom Wood of Data General finished the port to the
     Motorola 88000.

   * Masanobu Yuhara of Fujitsu Laboratories implemented the machine
     description for the Tron architecture (specifically, the Gmicro).

   * James van Artsdalen wrote the code that makes efficient use of the
     Intel 80387 register stack.

   * Mike Meissner at the Open Software Foundation finished the port to
     the MIPS cpu, including adding ECOFF debug support, and worked on
     the Intel port for the Intel 80386 cpu.

   * Ron Guilmette implemented the `protoize' and `unprotoize' tools,
     the support for Dwarf symbolic debugging information, and much of
     the support for System V Release 4.  He has also worked heavily on
     the Intel 386 and 860 support.

   * Torbjorn Granlund implemented multiply- and divide-by-constant
     optimization, improved long long support, and improved leaf
     function register allocation.

   * Mike Stump implemented the support for Elxsi 64 bit CPU.

   * John Wehle added the machine description for the Western Electric
     32000 processor used in several 3b series machines (no relation to
     the National Semiconductor 32000 processor).



File: gpc.info,  Node: Resources,  Next: GNU,  Prev: Acknowledgments,  Up: Top

Resources For Use With GPC.
***************************

Many of the programs mentioned here, plus some more, can be found at
     `http://www.gnu-pascal.de/contrib/'

GNU Pascal Drawing
------------------

On the web you can find our GNU Pascal drawing as a small (1 KB)
(`images/GnuPascal-small.png' on GPC's WWW home page) and a large PNG
image (10 KB) (`images/GnuPascal.png' on GPC's WWW home page), as an
EPS file (45 KB) (`images/GnuPascal.eps' on GPC's WWW home page), and
as a PDF file (18 KB) (`images/GnuPascal.pdf' on GPC's WWW home page).

Due to patent problems (http://www.gnu.org/philosophy/gif.html) we do
not use GIF files. Fortunately the PNG format (http://www.libpng.org),
the successor of GIF, does not have this problem - and introduces
better compression and more advanced features anyway.

   By the way, the color gradient (`images/gradient.png' on GPC's WWW
home page) that makes our page background is a PNG file of only 632
bytes. It was generated by a Pascal program compiled with GPC and
`pnmtopng'.  [Example (gradient.pas)]

PENG
----

PENG is an integrated development environment (IDE) for GNU Compilers
and other purposes on any platform supported by GPC, written by Frank
Heckenbach. The home page of PENG is
     `http://fjf.gnu.de/peng/'.

RHIDE
-----

RHIDE is an integrated development environment (IDE) for GNU Compilers
on DOS (DJGPP) or Linux, written by Robert Höhne. The home page of
RHIDE is
     `http://www.rhide.com'.

DevPascal
---------

DevPascal is an integrated development environment (IDE) for GNU Pascal
on mingw32. The home page of DevPascal is
     `http://www.bloodshed.net/devpascal.html'.

GRX
---

GRX is a graphics library for C and GNU Pascal, including a mostly BP
compatible `Graph' unit. It is available from
     `http://www.gnu.de/software/grx/'

   Although GRX originated on DJGPP, a DOS programming platform, it is
portable to Linux with SVGAlib, to all Unix-like systems running the
X11 window system, and to MS-Windows 9x/NT.

Internationalization
--------------------

Units and tools for internationalization are available in
     `http://www.gnu-pascal.de/contrib/eike/'

Database units
--------------

GNU Pascal units to access MySQL, GNU DBM and PostgreSQL databases are
available in
     `http://www.gnu-pascal.de/contrib/eike/'

GTK units
---------

GNU Pascal units for the GTK+ and GTK+ GL libraries are available in
     `http://www.gnu-pascal.de/contrib/nicola/'

Documentation
-------------

A book about GPC manual in German written by Eike Lange can be found in
     `http://www.gnu-pascal.org/~eike/'

SysUtils unit
-------------

Prof. Abimbola A. Olowofoyeku ("The African Chief") wrote a
Delphi-compatible (though a few routines are still missing) `SysUtils'
unit. It has been tested under Cygwin, mingw, Linux (Mandrake 7.0), and
Solaris 7. It can be downloaded from
`http://www.gnu-pascal.de/contrib/chief/'.

Crystal, a mailing list archive program
---------------------------------------

Crystal is a web based mailing list archive, written for GNU Pascal and
used for the archives of GPC's mailing lists (*note Mailing List
Archives::). The source code can be found at
`http://fjf.gnu.de/crystal/'.

ISO standards
-------------

The Pascal standard specifications are available in PostScript format at
     `http://ftp.digital.com/pub/Digital/Pascal/'

   Alternative addresses are
     `ftp://ftp.europe.digital.com/pub/DEC/Pascal/'

     `ftp://ftp.digital.com/pub/DEC/Pascal/'

   There are also copies at
     `http://www.moorecad.com/standardpascal/iso7185.ps'
     (ISO 7185 Pascal)

     `http://www.moorecad.com/standardpascal/iso10206.ps'
     (ISO 10206 Extended Pascal)

   Note: These documents are a bit hard to navigate (e.g., in
ghostview) because they are missing the so called "document structuring
comments" (DSC). The GPC source distribution contains a little script
`ps2dsc' to add the DSC again and make the documents easier to
navigate. Note that for reasons of copyright, you are probably only
allowed to do this for your own use and not to distribute the modified
files.

   You can find an easy-to-read introduction to Extended Pascal by
Prospero Software at
     `http://www.prosperosoftware.com/epintro.html'

   Please note that Standard Pascal is *not* the same as Borland Pascal
nor a subset of it. See *Note Highlights:: for examples of Standard
Pascal features that are missing in Borland Pascal.

   Scott A. Moore's ANSI-ISO Pascal FAQ (132 KB)
(http://www.moorecad.com/standardpascal/ansiiso.faq) discusses the
differences between both dialects in detail.

   The draft standard "Object-Oriented Extensions to Pascal" can be
found at
     `http://pascal-central.com/OOE-stds.html'

Software Patents Kill Innovation
--------------------------------

Programming activities of small companies and individuals are
threatened by software patents. If you are a programmer, you are in
danger, too! Your employer or yourself might be sued by a large company
holding a patent on some _ideas_ you are using in your programs. (You
need not use foreign code in order to become vulnerable.)

   For more information look at
     `http://swpat.ffii.org' (Europe)
     `http://lpf.ai.mit.edu' (USA)


File: gpc.info,  Node: GNU,  Next: Index-GPC,  Prev: Resources,  Up: Top

The GNU Project.
****************

GNU Pascal is part of the GNU project which was founded by Richard
Stallman in 1984. The aim of the GNU project is to provide a complete
operating system with editors, compilers etc. as "Free Software".

   People often confuse _Free Software_ with _public domain software_
or have other wrong information about the GNU project. If you want to
know it definitely, please read the *GNU General Public License*
(http://www.gnu.org/copyleft/gpl.html).

   For even more information, please consult the official *GNU home
page* of the _Free Software Foundation (FSF)_, `http://www.gnu.org/' or
one of its mirror sites.

   Some small notes about common misunderstandings follow.

   * It is legal to compile commercial, including non-free, programs
     written in Pascal with GNU Pascal. They do _not_ automatically
     become Free Software themselves.

   * "Free" is opposed to "proprietary", but _not_ opposed to
     "commercial". Free Softare can be - and is in fact - distributed
     commercially for a real price. In contrast, most non-commercial
     software does _not_ meet the open source criteria
     (http://www.opensource.org/osd.html) and thus does _not_ qualify
     as Free Software.

   * When you modify a free program released under the *GNU General
     Public License* (http://www.gnu.org/copyleft/gpl.html), e.g. the
     GNU Pascal compiler itself:
        - You can released and license your own modifications (as a
          separate entity) any way you like.

        - If you distribute or publish the whole work with your
          modifications, including or derived from GPL licensed parts,
          the whole work (including your modifications) must be
          licensed under the terms of the GPL. (Note: This does not
          contradict the previous point since you can license your work
          in several ways.)

        - You do not have to distribute or publish the whole work at
          all. In this case the question of license of the whole work
          does not arise.
     *Please note:* These are informal explanations which should not be
     construed as legal advice. The legally binding text is only the
     text contained in the license statement.

   * When using libraries for writing proprietary programs, check the
     libraries' licenses carefully. The _GNU Lesser General Public
     License_ (http://www.gnu.org/copyleft/lesser.html) allows linking
     a library to non-free software under certain conditions, the
     ordinary _GNU General Public License_ does not.

   * It is legal to charge a fee for distributing Free Software. If
     somebody sold you a copy of GNU Pascal you could have got without
     paying for it as well, that's in agreement with the _GNU General
     Public License_.

   * However if somebody wants you to sign an agreement that you won't
     re-distribute the Free Software you have got, it would be illegal.
     That person would lose the right to use and distribute that Free
     Software.

   * The preferred form to distribute Free Software is in source code.
     This ensures that everybody has the freedom to customize the
     software or to fix bugs by themselves. When we also distribute GNU
     Pascal binaries we do it only to simplify installation and to
     encourage its use.

* Menu:

* Manifesto::  The GNU Manifesto
* Funding::    How to help assure funding for Free Software


File: gpc.info,  Node: Manifesto,  Next: Funding,  Up: GNU

The GNU Manifesto
=================

     The GNU Manifesto which appears below was written by Richard
     Stallman at the beginning of the GNU project, to ask for
     participation and support.  For the first few years, it was
     updated in minor ways to account for developments, but now it
     seems best to leave it unchanged as most people have seen it.

     Since that time, we have learned about certain common
     misunderstandings that different wording could help avoid.
     Footnotes added in 1993 help clarify these points.

     For up-to-date information about the available GNU software,
     please see the latest issue of the GNU's Bulletin.  The list is
     much too long to include here.

* Menu:

* Gnu is Not Unix::           What's GNU?  Gnu's Not Unix!
* Why GNU::                   Why I Must Write GNU
* GNU Unix Compatibility::    Why GNU Will Be Compatible with Unix
* GNU Availability::          How GNU Will Be Available
* Why Help GNU::              Why Many Other Programmers Want to Help
* How To Contribute to GNU::  How You Can Contribute
* GNU Benefits::              Why All Computer Users Will Benefit
* Objections to GNU::         Some Easily Rebutted Objections to GNU's Goals


File: gpc.info,  Node: Gnu is Not Unix,  Next: Why GNU,  Up: Manifesto

What's GNU?  Gnu's Not Unix!
----------------------------

GNU, which stands for Gnu's Not Unix, is the name for the complete
Unix-compatible software system which I am writing so that I can give it
away free to everyone who can use it.(1) Several other volunteers are
helping me.  Contributions of time, money, programs and equipment are
greatly needed.

   So far we have an Emacs text editor with Lisp for writing editor
commands, a source level debugger, a yacc-compatible parser generator,
a linker, and around 35 utilities.  A shell (command interpreter) is
nearly completed.  A new portable optimizing C compiler has compiled
itself and may be released this year.  An initial kernel exists but
many more features are needed to emulate Unix.  When the kernel and
compiler are finished, it will be possible to distribute a GNU system
suitable for program development.  We will use TeX as our text
formatter, but an nroff is being worked on.  We will use the free,
portable X window system as well.  After this we will add a portable
Common Lisp, an Empire game, a spreadsheet, and hundreds of other
things, plus on-line documentation.  We hope to supply, eventually,
everything useful that normally comes with a Unix system, and more.

   GNU will be able to run Unix programs, but will not be identical to
Unix.  We will make all improvements that are convenient, based on our
experience with other operating systems.  In particular, we plan to
have longer file names, file version numbers, a crashproof file system,
file name completion perhaps, terminal-independent display support, and
perhaps eventually a Lisp-based window system through which several
Lisp programs and ordinary Unix programs can share a screen.  Both C
and Lisp will be available as system programming languages.  We will
try to support UUCP, MIT Chaosnet, and Internet protocols for
communication.

   GNU is aimed initially at machines in the 68000/16000 class with
virtual memory, because they are the easiest machines to make it run
on.  The extra effort to make it run on smaller machines will be left
to someone who wants to use it on them.

   To avoid horrible confusion, please pronounce the `G' in the word
`GNU' when it is the name of this project.

   ---------- Footnotes ----------

   (1) The wording here was careless.  The intention was that nobody
would have to pay for _permission_ to use the GNU system.  But the
words don't make this clear, and people often interpret them as saying
that copies of GNU should always be distributed at little or no charge.
That was never the intent; later on, the manifesto mentions the
possibility of companies providing the service of distribution for a
profit.  Subsequently I have learned to distinguish carefully between
"free" in the sense of freedom and "free" in the sense of price.  Free
software is software that users have the freedom to distribute and
change.  Some users may obtain copies at no charge, while others pay to
obtain copies - and if the funds help support improving the software,
so much the better.  The important thing is that everyone who has a
copy has the freedom to cooperate with others in using it.


File: gpc.info,  Node: Why GNU,  Next: GNU Unix Compatibility,  Prev: Gnu is Not Unix,  Up: Manifesto

Why I Must Write GNU
--------------------

I consider that the golden rule requires that if I like a program I must
share it with other people who like it.  Software sellers want to divide
the users and conquer them, making each user agree not to share with
others.  I refuse to break solidarity with other users in this way.  I
cannot in good conscience sign a nondisclosure agreement or a software
license agreement.  For years I worked within the Artificial
Intelligence Lab to resist such tendencies and other inhospitalities,
but eventually they had gone too far: I could not remain in an
institution where such things are done for me against my will.

   So that I can continue to use computers without dishonor, I have
decided to put together a sufficient body of free software so that I
will be able to get along without any software that is not free.  I
have resigned from the AI lab to deny MIT any legal excuse to prevent
me from giving GNU away.


File: gpc.info,  Node: GNU Unix Compatibility,  Next: GNU Availability,  Prev: Why GNU,  Up: Manifesto

Why GNU Will Be Compatible with Unix
------------------------------------

Unix is not my ideal system, but it is not too bad.  The essential
features of Unix seem to be good ones, and I think I can fill in what
Unix lacks without spoiling them.  And a system compatible with Unix
would be convenient for many other people to adopt.


File: gpc.info,  Node: GNU Availability,  Next: Why Help GNU,  Prev: GNU Unix Compatibility,  Up: Manifesto

How GNU Will Be Available
-------------------------

GNU is not in the public domain.  Everyone will be permitted to modify
and redistribute GNU, but no distributor will be allowed to restrict its
further redistribution.  That is to say, proprietary modifications will
not be allowed.  I want to make sure that all versions of GNU remain
free.


File: gpc.info,  Node: Why Help GNU,  Next: How To Contribute to GNU,  Prev: GNU Availability,  Up: Manifesto

Why Many Other Programmers Want to Help
---------------------------------------

I have found many other programmers who are excited about GNU and want
to help.

   Many programmers are unhappy about the commercialization of system
software.  It may enable them to make more money, but it requires them
to feel in conflict with other programmers in general rather than feel
as comrades.  The fundamental act of friendship among programmers is the
sharing of programs; marketing arrangements now typically used
essentially forbid programmers to treat others as friends.  The
purchaser of software must choose between friendship and obeying the
law.  Naturally, many decide that friendship is more important.  But
those who believe in law often do not feel at ease with either choice.
They become cynical and think that programming is just a way of making
money.

   By working on and using GNU rather than proprietary programs, we can
be hospitable to everyone and obey the law.  In addition, GNU serves as
an example to inspire and a banner to rally others to join us in
sharing.  This can give us a feeling of harmony which is impossible if
we use software that is not free.  For about half the programmers I
talk to, this is an important happiness that money cannot replace.


File: gpc.info,  Node: How To Contribute to GNU,  Next: GNU Benefits,  Prev: Why Help GNU,  Up: Manifesto

How You Can Contribute
----------------------

I am asking computer manufacturers for donations of machines and money.
I'm asking individuals for donations of programs and work.

   One consequence you can expect if you donate machines is that GNU
will run on them at an early date.  The machines should be complete,
ready to use systems, approved for use in a residential area, and not
in need of sophisticated cooling or power.

   I have found very many programmers eager to contribute part-time
work for GNU.  For most projects, such part-time distributed work would
be very hard to coordinate; the independently-written parts would not
work together.  But for the particular task of replacing Unix, this
problem is absent.  A complete Unix system contains hundreds of utility
programs, each of which is documented separately.  Most interface
specifications are fixed by Unix compatibility.  If each contributor
can write a compatible replacement for a single Unix utility, and make
it work properly in place of the original on a Unix system, then these
utilities will work right when put together.  Even allowing for Murphy
to create a few unexpected problems, assembling these components will
be a feasible task.  (The kernel will require closer communication and
will be worked on by a small, tight group.)

   If I get donations of money, I may be able to hire a few people full
or part time.  The salary won't be high by programmers' standards, but
I'm looking for people for whom building community spirit is as
important as making money.  I view this as a way of enabling dedicated
people to devote their full energies to working on GNU by sparing them
the need to make a living in another way.


File: gpc.info,  Node: GNU Benefits,  Next: Objections to GNU,  Prev: How To Contribute to GNU,  Up: Manifesto

Why All Computer Users Will Benefit
-----------------------------------

Once GNU is written, everyone will be able to obtain good system
software free, just like air.(1)

   This means much more than just saving everyone the price of a Unix
license.  It means that much wasteful duplication of system programming
effort will be avoided.  This effort can go instead into advancing the
state of the art.

   Complete system sources will be available to everyone.  As a result,
a user who needs changes in the system will always be free to make them
himself, or hire any available programmer or company to make them for
him.  Users will no longer be at the mercy of one programmer or company
which owns the sources and is in sole position to make changes.

   Schools will be able to provide a much more educational environment
by encouraging all students to study and improve the system code.
Harvard's computer lab used to have the policy that no program could be
installed on the system if its sources were not on public display, and
upheld it by actually refusing to install certain programs.  I was very
much inspired by this.

   Finally, the overhead of considering who owns the system software
and what one is or is not entitled to do with it will be lifted.

   Arrangements to make people pay for using a program, including
licensing of copies, always incur a tremendous cost to society through
the cumbersome mechanisms necessary to figure out how much (that is,
which programs) a person must pay for.  And only a police state can
force everyone to obey them.  Consider a space station where air must
be manufactured at great cost: charging each breather per liter of air
may be fair, but wearing the metered gas mask all day and all night is
intolerable even if everyone can afford to pay the air bill.  And the
TV cameras everywhere to see if you ever take the mask off are
outrageous.  It's better to support the air plant with a head tax and
chuck the masks.

   Copying all or parts of a program is as natural to a programmer as
breathing, and as productive.  It ought to be as free.

   ---------- Footnotes ----------

   (1) This is another place I failed to distinguish carefully between
the two different meanings of "free".  The statement as it stands is
not false - you can get copies of GNU software at no charge, from your
friends or over the net.  But it does suggest the wrong idea.


File: gpc.info,  Node: Objections to GNU,  Prev: GNU Benefits,  Up: Manifesto

Some Easily Rebutted Objections to GNU's Goals
----------------------------------------------

     "Nobody will use it if it is free, because that means they can't
     rely on any support."

     "You have to charge for the program to pay for providing the
     support."

   If people would rather pay for GNU plus service than get GNU free
without service, a company to provide just service to people who have
obtained GNU free ought to be profitable.(1)

   We must distinguish between support in the form of real programming
work and mere handholding.  The former is something one cannot rely on
from a software vendor.  If your problem is not shared by enough
people, the vendor will tell you to get lost.

   If your business needs to be able to rely on support, the only way
is to have all the necessary sources and tools.  Then you can hire any
available person to fix your problem; you are not at the mercy of any
individual.  With Unix, the price of sources puts this out of
consideration for most businesses.  With GNU this will be easy.  It is
still possible for there to be no available competent person, but this
problem cannot be blamed on distribution arrangements.  GNU does not
eliminate all the world's problems, only some of them.

   Meanwhile, the users who know nothing about computers need
handholding: doing things for them which they could easily do
themselves but don't know how.

   Such services could be provided by companies that sell just
hand-holding and repair service.  If it is true that users would rather
spend money and get a product with service, they will also be willing
to buy the service having got the product free.  The service companies
will compete in quality and price; users will not be tied to any
particular one.  Meanwhile, those of us who don't need the service
should be able to use the program without paying for the service.

     "You cannot reach many people without advertising, and you must
     charge for the program to support that."

     "It's no use advertising a program people can get free."

   There are various forms of free or very cheap publicity that can be
used to inform numbers of computer users about something like GNU.  But
it may be true that one can reach more microcomputer users with
advertising.  If this is really so, a business which advertises the
service of copying and mailing GNU for a fee ought to be successful
enough to pay for its advertising and more.  This way, only the users
who benefit from the advertising pay for it.

   On the other hand, if many people get GNU from their friends, and
such companies don't succeed, this will show that advertising was not
really necessary to spread GNU.  Why is it that free market advocates
don't want to let the free market decide this?(2)

     "My company needs a proprietary operating system to get a
     competitive edge."

   GNU will remove operating system software from the realm of
competition.  You will not be able to get an edge in this area, but
neither will your competitors be able to get an edge over you.  You and
they will compete in other areas, while benefiting mutually in this
one.  If your business is selling an operating system, you will not
like GNU, but that's tough on you.  If your business is something else,
GNU can save you from being pushed into the expensive business of
selling operating systems.

   I would like to see GNU development supported by gifts from many
manufacturers and users, reducing the cost to each.(3)

     "Don't programmers deserve a reward for their creativity?"

   If anything deserves a reward, it is social contribution.
Creativity can be a social contribution, but only in so far as society
is free to use the results.  If programmers deserve to be rewarded for
creating innovative programs, by the same token they deserve to be
punished if they restrict the use of these programs.

     "Shouldn't a programmer be able to ask for a reward for his
     creativity?"

   There is nothing wrong with wanting pay for work, or seeking to
maximize one's income, as long as one does not use means that are
destructive.  But the means customary in the field of software today
are based on destruction.

   Extracting money from users of a program by restricting their use of
it is destructive because the restrictions reduce the amount and the
ways that the program can be used.  This reduces the amount of wealth
that humanity derives from the program.  When there is a deliberate
choice to restrict, the harmful consequences are deliberate destruction.

   The reason a good citizen does not use such destructive means to
become wealthier is that, if everyone did so, we would all become
poorer from the mutual destructiveness.  This is Kantian ethics; or,
the Golden Rule.  Since I do not like the consequences that result if
everyone hoards information, I am required to consider it wrong for one
to do so.  Specifically, the desire to be rewarded for one's creativity
does not justify depriving the world in general of all or part of that
creativity.

     "Won't programmers starve?"

   I could answer that nobody is forced to be a programmer.  Most of us
cannot manage to get any money for standing on the street and making
faces.  But we are not, as a result, condemned to spend our lives
standing on the street making faces, and starving.  We do something
else.

   But that is the wrong answer because it accepts the questioner's
implicit assumption: that without ownership of software, programmers
cannot possibly be paid a cent.  Supposedly it is all or nothing.

   The real reason programmers will not starve is that it will still be
possible for them to get paid for programming; just not paid as much as
now.

   Restricting copying is not the only basis for business in software.
It is the most common basis because it brings in the most money.  If it
were prohibited, or rejected by the customer, software business would
move to other bases of organization which are now used less often.
There are always numerous ways to organize any kind of business.

   Probably programming will not be as lucrative on the new basis as it
is now.  But that is not an argument against the change.  It is not
considered an injustice that sales clerks make the salaries that they
now do.  If programmers made the same, that would not be an injustice
either.  (In practice they would still make considerably more than
that.)

     "Don't people have a right to control how their creativity is
     used?"

   "Control over the use of one's ideas" really constitutes control over
other people's lives; and it is usually used to make their lives more
difficult.

   People who have studied the issue of intellectual property rights
carefully (such as lawyers) say that there is no intrinsic right to
intellectual property.  The kinds of supposed intellectual property
rights that the government recognizes were created by specific acts of
legislation for specific purposes.

   For example, the patent system was established to encourage
inventors to disclose the details of their inventions.  Its purpose was
to help society rather than to help inventors.  At the time, the life
span of 17 years for a patent was short compared with the rate of
advance of the state of the art.  Since patents are an issue only among
manufacturers, for whom the cost and effort of a license agreement are
small compared with setting up production, the patents often do not do
much harm.  They do not obstruct most individuals who use patented
products.

   The idea of copyright did not exist in ancient times, when authors
frequently copied other authors at length in works of non-fiction.  This
practice was useful, and is the only way many authors' works have
survived even in part.  The copyright system was created expressly for
the purpose of encouraging authorship.  In the domain for which it was
invented - books, which could be copied economically only on a printing
press - it did little harm, and did not obstruct most of the individuals
who read the books.

   All intellectual property rights are just licenses granted by society
because it was thought, rightly or wrongly, that society as a whole
would benefit by granting them.  But in any particular situation, we
have to ask: are we really better off granting such license?  What kind
of act are we licensing a person to do?

   The case of programs today is very different from that of books a
hundred years ago.  The fact that the easiest way to copy a program is
from one neighbor to another, the fact that a program has both source
code and object code which are distinct, and the fact that a program is
used rather than read and enjoyed, combine to create a situation in
which a person who enforces a copyright is harming society as a whole
both materially and spiritually; in which a person should not do so
regardless of whether the law enables him to.

     "Competition makes things get done better."

   The paradigm of competition is a race: by rewarding the winner, we
encourage everyone to run faster.  When capitalism really works this
way, it does a good job; but its defenders are wrong in assuming it
always works this way.  If the runners forget why the reward is offered
and become intent on winning, no matter how, they may find other
strategies - such as, attacking other runners.  If the runners get into
a fist fight, they will all finish late.

   Proprietary and secret software is the moral equivalent of runners
in a fist fight.  Sad to say, the only referee we've got does not seem
to object to fights; he just regulates them ("For every ten yards you
run, you can fire one shot").  He really ought to break them up, and
penalize runners for even trying to fight.

     "Won't everyone stop programming without a monetary incentive?"

   Actually, many people will program with absolutely no monetary
incentive.  Programming has an irresistible fascination for some
people, usually the people who are best at it.  There is no shortage of
professional musicians who keep at it even though they have no hope of
making a living that way.

   But really this question, though commonly asked, is not appropriate
to the situation.  Pay for programmers will not disappear, only become
less.  So the right question is, will anyone program with a reduced
monetary incentive?  My experience shows that they will.

   For more than ten years, many of the world's best programmers worked
at the Artificial Intelligence Lab for far less money than they could
have had anywhere else.  They got many kinds of non-monetary rewards:
fame and appreciation, for example.  And creativity is also fun, a
reward in itself.

   Then most of them left when offered a chance to do the same
interesting work for a lot of money.

   What the facts show is that people will program for reasons other
than riches; but if given a chance to make a lot of money as well, they
will come to expect and demand it.  Low-paying organizations do poorly
in competition with high-paying ones, but they do not have to do badly
if the high-paying ones are banned.

     "We need the programmers desperately.  If they demand that we stop
     helping our neighbors, we have to obey."

   You're never so desperate that you have to obey this sort of demand.
Remember: millions for defense, but not a cent for tribute!

     "Programmers need to make a living somehow."

   In the short run, this is true.  However, there are plenty of ways
that programmers could make a living without selling the right to use a
program.  This way is customary now because it brings programmers and
businessmen the most money, not because it is the only way to make a
living.  It is easy to find other ways if you want to find them.  Here
are a number of examples.

   A manufacturer introducing a new computer will pay for the porting of
operating systems onto the new hardware.

   The sale of teaching, hand-holding and maintenance services could
also employ programmers.

   People with new ideas could distribute programs as freeware, asking
for donations from satisfied users, or selling hand-holding services.
I have met people who are already working this way successfully.

   Users with related needs can form users' groups, and pay dues.  A
group would contract with programming companies to write programs that
the group's members would like to use.

   All sorts of development can be funded with a Software Tax:

     Suppose everyone who buys a computer has to pay x percent of the
     price as a software tax.  The government gives this to an agency
     like the NSF to spend on software development.

     But if the computer buyer makes a donation to software development
     himself, he can take a credit against the tax.  He can donate to
     the project of his own choosing - often, chosen because he hopes to
     use the results when it is done.  He can take a credit for any
     amount of donation up to the total tax he had to pay.

     The total tax rate could be decided by a vote of the payers of the
     tax, weighted according to the amount they will be taxed on.

     The consequences:

        * The computer-using community supports software development.

        * This community decides what level of support is needed.

        * Users who care which projects their share is spent on can
          choose this for themselves.

   In the long run, making programs free is a step toward the
post-scarcity world, where nobody will have to work very hard just to
make a living.  People will be free to devote themselves to activities
that are fun, such as programming, after spending the necessary ten
hours a week on required tasks such as legislation, family counseling,
robot repair and asteroid prospecting.  There will be no need to be
able to make a living from programming.

   We have already greatly reduced the amount of work that the whole
society must do for its actual productivity, but only a little of this
has translated itself into leisure for workers because much
nonproductive activity is required to accompany productive activity.
The main causes of this are bureaucracy and isometric struggles against
competition.  Free software will greatly reduce these drains in the
area of software production.  We must do this, in order for technical
gains in productivity to translate into less work for us.

   ---------- Footnotes ----------

   (1) Several such companies now exist.

   (2) The Free Software Foundation raises most of its funds from a
distribution service, although it is a charity rather than a company.
If _no one_ chooses to obtain copies by ordering from the FSF, it will
be unable to do its work.  But this does not mean that proprietary
restrictions are justified to force every user to pay.  If a small
fraction of all the users order copies from the FSF, that is sufficient
to keep the FSF afloat.  So we ask users to choose to support us in
this way.  Have you done your part?

   (3) A group of computer companies recently pooled funds to support
maintenance of the GNU C Compiler.


File: gpc.info,  Node: Funding,  Prev: Manifesto,  Up: GNU

Funding Free Software
=====================

If you want to have more free software a few years from now, it makes
sense for you to help encourage people to contribute funds for its
development.  The most effective approach known is to encourage
commercial redistributors to donate.

   Users of free software systems can boost the pace of development by
encouraging for-a-fee distributors to donate part of their selling price
to free software developers - the Free Software Foundation, and others.

   The way to convince distributors to do this is to demand it and
expect it from them.  So when you compare distributors, judge them
partly by how much they give to free software development.  Show
distributors they must compete to be the one who gives the most.

   To make this approach work, you must insist on numbers that you can
compare, such as, "We will donate ten dollars to the Frobnitz project
for each disk sold."  Don't be satisfied with a vague promise, such as
"A portion of the profits are donated," since it doesn't give a basis
for comparison.

   Even a precise fraction "of the profits from this disk" is not very
meaningful, since creative accounting and unrelated business decisions
can greatly alter what fraction of the sales price counts as profit.
If the price you pay is $50, ten percent of the profit is probably less
than a dollar; it might be a few cents, or nothing at all.

   Some redistributors do development work themselves.  This is useful
too; but to keep everyone honest, you need to inquire how much they do,
and what kind.  Some kinds of development make much more long-term
difference than others.  For example, maintaining a separate version of
a program contributes very little; maintaining the standard version of a
program for the whole community contributes much.  Easy new ports
contribute little, since someone else would surely do them; difficult
ports such as adding a new CPU to the GNU C compiler contribute more;
major new features or packages contribute the most.

   By establishing the idea that supporting further development is "the
proper thing to do" when distributing free software for a fee, we can
assure a steady flow of resources into making more free software.

     Copyright (C) 1994 Free Software Foundation, Inc.
     Verbatim copying and redistribution of this section is permitted
     without royalty; alteration is not permitted.

