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

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

   This file documents the GNU Pascal Compiler.

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

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

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

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


File: gpc.info,  Node: Supported platforms,  Prev: Turbo Pascal compatibility,  Up: GNU Pascal

Which platforms are supported by GNU Pascal?
--------------------------------------------

   GPC uses the GCC backend, so it should run on any system that is
supported by GNU CC. This includes a large variety of Unix systems,
MS-DOS, OS/2 and Win32. A full list of platforms supported by GCC can
be found in the file `INSTALL' of the GCC distribution. Not all of
these have actually been tested, but it is known to run on these
platforms:

ix86-linux                    (Linux 2.x, ELF)
i486-linuxaout                
i486-linuxoldld               
i386-freebsd1.2.0             
AIX 4.2.1                     
AIX 4.3                       
DJGPP V2                      (Dos)
EMX 0.9B                      (OS/2, Dos)
Cygwin32 beta20 and higher    (MS-Windows95/98, MS-Windows NT)
Mingw32                       (MS-Windows95/98, MS-Windows NT)
mips-sgi-irix5.3              
sun-sparc-sunos4.1.4          
sparc-sun-solaris2.x          
sun-sparc-solaris 2.5.1       
sun-sparc-solaris 2.6         
sun-sparc-solaris 7           
alpha-unknown-linux           
alphaev56-dec-osf4.0d         

   *OK people - send us your success stories, with canonical machine
name!*


File: gpc.info,  Node: Installing GPC,  Next: GPC on DJGPP,  Prev: GNU Pascal,  Up: FAQ

Installing GPC
==============

   You find the most up-to-date installation instructions in the GPC
Manual or the file `INSTALL' in source distributions, or on the GPC web
site.  (*note Installation::)

   The following sections describe things you might need or want to
install besides GPC itself.

* Menu:

* Documentation files::  What to read next
* Components::           Which components do I need to compile Pascal code?
* Debugger::             How do I debug my Pascal programs?
* Libraries::            What additional libraries should I have?
* Contributed units::    Contributed units
* IDE::                  Can you recommend an IDE?


File: gpc.info,  Node: Documentation files,  Next: Components,  Up: Installing GPC

What to read next
-----------------

   After installing GPC, please check the files in the directory
`/usr/local/doc/gpc':

`README'       General Information about GPC
`FAQ'          This FAQ :-)
`NEWS'         Changes since the last release
`LIBS'         Libraries used by some GPC units
`BUGS'         How to report bugs, about the Test Suite
`AUTHORS'      List of GPC authors
`COPYING'      The GNU General Public License


File: gpc.info,  Node: Components,  Next: Debugger,  Prev: Documentation files,  Up: Installing GPC

Which components do I need to compile Pascal code?
--------------------------------------------------

   A complete Pascal compiler system should at least have:

  1. The actual compiler, GPC.

  2. An editor, assembler, linker, librarian and friends.

  3. A C library. If you have a working C compiler, you already have
     this.

  4. A debugger, if you want to debug your programs.

   For most people, the GNU binutils and GNU debugger (`gdb') are a
good choice, although some may prefer to use vendor specific tools.


File: gpc.info,  Node: Debugger,  Next: Libraries,  Prev: Components,  Up: Installing GPC

How do I debug my Pascal programs?
----------------------------------

   To debug your programs, (a) GNU Pascal must be able to generate
executables with debug info for your platform, and (b) you must have a
debugger which understands this.

   * If `gpc -g -o hello hello.p' says:
          gpc: -g not supported for this platform
     then GPC is unable to generate debugging info. Usually, installing
     `gas' (part of GNU binutils) instead of your system's assembler
     can overcome this. When you configure the GCC used for GPC, specify
     `--with-gnu-as', and possibly `--with-gnu-ld' and/or
     `--with-stabs'. More information can be found in the `INSTALL'
     file in the GNU CC source directory.

   * Your system's debugger may not understand the debug info generated
     by GNU tools. In this case, installing `gdb' may help.

   The bottom line: if you can debug GCC compiled programs, you should
be able to do this with GPC too.

   The GNU debugger (`gdb') currently does not have a "Pascal" mode, so
it is unable to display certain Pascal structures etc. When debugging,
please note that the Initial Letter In Each Identifier Is In Upper Case
And The Rest Are In Lower Case. If you want to display variable `foo'
in the debugger, type `show Foo' or `display Foo' instead.

   Although `gdb' is an excellent debugger, it's user interface is not
everybody's preference. If you like to debug under X11, please refer to
the comp.windows.x FAQ: "Where can I get an X-based debugger?" at:
`http://www.cis.ohio-state.edu/hypertext/faq/usenet/x-faq/part6/faq-doc-2.html'

   Some useful frontends include: XXGDB, tGDB and XWPE. See:
`http://www.ee.ryerson.ca:8080/~elf/xapps/Q-IV.html'

   Very nice, but resource consuming is the Motif based DDD:
`http://sol.ibr.cs.tu-bs.de/softech/ddd/'

   Furthermore, RHIDE (*note IDE::) contains built-in debugging suport,
similar to the IDE of BP.


File: gpc.info,  Node: Libraries,  Next: Contributed units,  Prev: Debugger,  Up: Installing GPC

What additional libraries should I have?
----------------------------------------

   You will need certain additional libraries when you compile some of
the units. These can be found in the directory
`ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/libs/'.

   Currently, there are the following libraries:

gmp
     Arithmetic for integers, rationals and real numbers with arbitrary
     size and precision. Used by the GMP unit.

rx
     Regular expression matching and substitution. Used by the RegEx
     unit.

ncurses
PDCurses
     Screen handling. Used by the CRT unit. Depending on your system,
     you have the following choices:

     Unix: You can compile terminal applications with ncurses and
     applications that run in an X11 window with PDCurses (though
     terminal applications can, of course, also run in an xterm under
     X11). ncurses is used by default. If you want to use PDCurses
     (a.k.a. XCurses), give the option `-DX11' when compiling CRT.

     Dos with DJGPP and MS-Windows with mingw: Only PDCurses is
     available and will be used by default.

     MS-Windows with Cygwin: PDCurses and ncurses are available.
     PDCurses is used by default. If you want to use ncurses, give the
     option `-DUSE_NCURSES' when compiling CRT.

     Other systems: Please see the `README's and installation
     instructions of PDCurses and ncurses to find out which one(s) can
     be built on your system. See the conditionals at the end of
     crt.inc and crtc.h (and change them if necessary) on which library
     is used by default.

ElectricFence
     This library is not used by any GPC unit. It is a debugging tool to
     assist you in finding memory allocation bugs. To use it, just link
     it to your program, either on the command line (`-lefence') or in
     the source code (`{$L efence}') which you might want to put into
     an `{$ifdef DEBUG}' or similar since using libefence is only
     recommended for debugging.

   The source code of the libraries is available in the main `libs'
directory. Most libraries come with one or several patches which should
be applied before compiling them.

   Binaries for some platforms are available in the `binary/PLATFORM'
subdirectories. If you compile the libraries for other platforms, be
invited to make the binaries available to us for distribution on the
FTP site.

   There are also the following files:

`terminfo-linux.tar.gz'
     This is a patch to enable ncurses programs to make use of the
     ability of Linux 2.2 and newer kernels to produce a block cursor
     when needed. The present patch can be installed without recompiling
     anything, just by copying some files into place. More details can
     be found in the `README' file included in this archive. The patch
     will not do any harm on older kernels. Please note that *not* only
     on Linux machines it is useful to install the patch. Installing
     them on any other machine will allow users who telnet in from a
     Linux console to profit from the block cursor capability. Besides,
     some Unix systems have installed older Linux terminfo entries or
     none at all, so it's a good thing, anyway, to give them a current
     version. The patch is included in the terminfo database of ncurses
     5.0, so if you install ncurses 5.0 (source or binary), you don't
     need to get the patch separately. But you can install it on a
     system with an older ncurses version if you don't feel like
     upgrading ncurses altogether.

`tsort-2.9i.zip'
     A little utility (extracted from util-linux-2.9i, but not Linux
     specific), needed for the configuration of the rx library. You
     need it only if you compile rx yourself (and if it's not already
     present on your system), not when using a rx binary.


File: gpc.info,  Node: Contributed units,  Next: IDE,  Prev: Libraries,  Up: Installing GPC

Contributed units
-----------------

   Several people have contributed units for GPC. They are usually
announced on the mailing list, *Note Mailing List::. Here's a selection:

   * Nicola Girardi wrote a unit which you can use to interface Svgalib.
     You can read a mini-FAQ about it at
     `http://ages.dida.physik.uni-essen.de/~nicola/', complete with
     links to download the unit via http or ftp. If you want to download
     the unit directly, get `svgalib-gpc-20000216.tar.gz' from
     `ftp://agnes.dida.physik.uni-essen.de/home/nicola/'.

   * 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
     `ftp://agnes.dida.physik.uni-essen.de/home/chief/sysutils-20000725.zip'.

   * Eike Lange wrote units to access MySql, GNU DBM and PostgreSQL data
     bases. As of this writing (Aug 2000), they are in Alpha stage. They
     can be downloaded from
     `ftp://agnes.dida.physik.uni-essen.de/home/lange/'.


File: gpc.info,  Node: IDE,  Prev: Contributed units,  Up: Installing GPC

Can you recommend an IDE?
-------------------------

   Users of Borland Pascal may wonder if there's a replacement for the
IDE (Integrated Development Environment). Here's a few suggestions:

   * (X)Emacs. Some people think it's the answer to the question of
     Life, the Universe and Everything, others decide it's uGNUsable.
     Available from your friendly GNU mirror and most distributions.

   * RHIDE. DJGPP users might want to try RHIDE. The latest (beta)
     release is compatible with GNU Pascal and allows stepping, tracing
     and watching like Borland's IDE. It can be downloaded from
     `http://www.tu-chemnitz.de/~sho/rho/rhide/rhide.html'.

   * PENG. It's not free software, but it was written with GPC.  It's
     very similar to Borland's IDE, but with many extensions.  Binaries
     for DJGPP, Linux and Solaris can be downloaded from
     `http://fjf.gnu.de/peng.html'.

   * XWPE is another imitation of the Borland IDE, so users of Borland
     Pascal may find it a good alternative.


File: gpc.info,  Node: GPC on DJGPP,  Next: Strings in GPC,  Prev: Installing GPC,  Up: FAQ

GNU Pascal on the DJGPP (MS-DOS) platform
=========================================

   This chapter discusses some potential problems with GNU Pascal on
MS-DOS, using DJGPP.

* Menu:

* What is DJGPP::            What is DJGPP?
* DJGPP FAQ::                If you need more information
* DJGPP download::           What do I download?
* Installing GPC on DJGPP::  How do I install the compiler?
* DJGPP Info reader::        I cannot read the Info documentation!
* DJGPP DPMI server::        GPC says: no DPMI
* Assembler syntax::         I have troubles with assembly code
* DJGPP specific code::      Tell me how to do DPMI, BIOS and
                             other DOS related things.
* DJGPP stack size::         I got an exception when accessing an
                             `array [1 .. 4000000] of Byte'.


File: gpc.info,  Node: What is DJGPP,  Next: DJGPP FAQ,  Up: GPC on DJGPP

What is DJGPP?
--------------

   The following paragraph is from the site
`http://www.delorie.com/djgpp/':

   DJGPP is a complete 32-bit C/C++ development system for Intel 80386
(and higher) PCs running DOS. It includes ports of many GNU development
utilities. The development tools require a 80386 or newer computer to
run, as do the programs they produce. In most cases, the programs it
produces can be sold commercially without license or royalties.


File: gpc.info,  Node: DJGPP FAQ,  Next: DJGPP download,  Prev: What is DJGPP,  Up: GPC on DJGPP

If you need more information
----------------------------

   GPC/DJGPP is a DJGPP V2 application, and most of the DJGPP
documentation applies for GPC too. A great source of information is the
DJGPP FAQ: `http://www.delorie.com/djgpp/v2faq/230b.zip'

   Another place to look for DJGPP documentation is the DJGPP Knowledge
Base, at this URL: `http://www.delorie.com/djgpp/doc/kb/'


File: gpc.info,  Node: DJGPP download,  Next: Installing GPC on DJGPP,  Prev: DJGPP FAQ,  Up: GPC on DJGPP

What do I download?
-------------------

   As discussed in *Note Components::, other than GPC itself, you need
an assembler, linker and friends, a C library and possibly a debugger.
The site `http://www.delorie.com/djgpp/' recommended the following
files and they will help you find a mirror:

`v2/djdev203.zip'       (C library)
`v2gnu/bnu2951b.zip'    (assembler, ....)
`v2gnu/gcc2952b.zip'    (gcc)
`v2gnu/gdb418b.zip'     (debugger)
`v2gnu/mak379b.zip'     (make)
`v2gnu/txi40b.zip'      (texi)

   This list is about 10 MB not counting GPC. You can use a binary
version of GPC from agnes.


File: gpc.info,  Node: Installing GPC on DJGPP,  Next: DJGPP Info reader,  Prev: DJGPP download,  Up: GPC on DJGPP

How do I install the compiler?
------------------------------

   If you don't have DJGPP installed on your harddisk, create a
directory for GNU Pascal (`c:\gpc'), and unzip the archives.  Make sure
you preserve the directory structure (use `pkunzip -d'). Now, add the
directory where `gpc.exe' lives (`c:\gpc\bin') to your path and set the
DJGPP environment variable to point to your `djgpp.env' file:

     set DJGPP=c:\gpc\djgpp.env

   Then, add this to your `djgpp.env' file:

     ---------------------------------------------------------
     [gpcpp]
     C_INCLUDE_PATH=%/>;C_INCLUDE_PATH%%DJDIR%/lang/pascal;%DJDIR%/include
     
     [gpc]
     COMPILER_PATH=%/>;COMPILER_PATH%%DJDIR%/bin
     LIBRARY_PATH=%/>;LIBRARY_PATH%%DJDIR%/lib;%DJDIR%/contrib/grx20/lib
     ---------------------------------------------------------

   The binary distribution should come with a `djgpp.env' which is
already modified, so you may not have to do this.

   The GPC online documentation is in GNU info format; you need the
Info reader (`txi390b.zip') to read it, or use the built-in Info reader
of the RHIDE or PENG IDE. To add the GPC documentation to the info
directory file, edit the `c:\gpc\info\dir' file, and locate this
section:

     ---------------------------------------------------------
     * GCC: (gcc.inf).
     The GNU C, C++, and Objective-C Compiler
     
     * GDB: (gdb.inf).
     The GNU Debugger (gdb and gdb-dpmi).
     
     ---------------------------------------------------------

   To add GPC, change it to look like this:

     ---------------------------------------------------------
     * GCC: (gcc.inf).
     The GNU C, C++, and Objective-C Compiler
     
     * GPC: (gpc.inf).
     The GNU Pascal Compiler
     
     * GDB: (gdb.inf).
     The GNU Debugger (gdb and gdb-dpmi).
     
     ---------------------------------------------------------

   Specific information for low-memory conditions and more can be found
in the DJGPP FAQ and documentation.


File: gpc.info,  Node: DJGPP Info reader,  Next: DJGPP DPMI server,  Prev: Installing GPC on DJGPP,  Up: GPC on DJGPP

I cannot read the Info documentation!
-------------------------------------

   To read the Info documentation, you need the `info' program from
`txi390b.zip' or an IDE like RHIDE or PENG.


File: gpc.info,  Node: DJGPP DPMI server,  Next: Assembler syntax,  Prev: DJGPP Info reader,  Up: GPC on DJGPP

GPC says: no DPMI
-----------------

   You don't have a DPMI server installed, and DJGPP v2 requires it to
run. You can either use one of the commercial DPMI servers (e.g., run
`gpc' in a DOS box under MS-Windows) or download and install CWSDPMI
(`csdpmi3b.zip') which is a free DPMI server written for DJGPP.


File: gpc.info,  Node: Assembler syntax,  Next: DJGPP specific code,  Prev: DJGPP DPMI server,  Up: GPC on DJGPP

I have troubles with assembly code
----------------------------------

   The GNU Assembler (`as.exe'), or `gas', called by GCC accepts "AT&T"
syntax which is different from "Intel" syntax.  Differences are
discussed in section 17.1 of the DJGPP FAQ.

   A guide is available which was written by Brennan Mr. Wacko
Underwood <brennan@mack.rt66.com> and describes how to use inline
assembly programming with DJGPP, at this URL:
`http://www.rt66.com/~brennan/djgpp/djgpp_asm.html'

   There's also a GPC assembler tutorial at
`ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/contrib/gpcasm.zip'

   Section 17.3 of the DJGPP FAQ discusses some methods to convert
"Intel" syntax to "AT&T" syntax.


File: gpc.info,  Node: DJGPP specific code,  Next: DJGPP stack size,  Prev: Assembler syntax,  Up: GPC on DJGPP

Tell me how to do DPMI, BIOS and other DOS related things.
----------------------------------------------------------

   DPMI, BIOS and other functions are no different than other system
functions. Refer to the GPC Manual on how to access your system's
C-library. This small example shows how to use DPMI, copying some
structures and function prototypes of `<dpmi.h>':

     program DPMIDemo;
     
     { Only for DJGPP }
     
     {$X+}
     
     { `Byte' is `unsigned char' in C,
       `ShortCard' is `unsigned short' in C,
       `MedCard' is `unsigned long' in C,
       `Word' is `unsigned' in C,
       etc. (all these types are built-in). }
     
     type
       TDpmiVersionRet = record
         Major      : Byte;
         Minor      : Byte;
         Flags      : ShortCard;
         CPU        : Byte;
         Master_PIC : Byte;
         Slave_PIC  : Byte;
       end;
     
     type
       TDpmiFreeMemInfo = record
         Largest_Available_Free_Block_In_Bytes,
         Maximum_Unlocked_Page_Allocation_In_Pages,
         Maximum_Locked_Page_Allocation_In_Pages,
         Linear_Address_Space_Size_In_Pages,
         Total_Number_Of_Unlocked_Pages,
         Total_Number_Of_Free_Pages,
         Total_Number_Of_Physical_Pages,
         Free_Linear_Address_Space_In_Pages,
         Size_Of_Paging_File_Partition_In_Pages,
         Reserved1,
         Reserved2,
         Reserved3 : MedCard;
       end;
     
     function DpmiGetVersion (var Version: TDpmiVersionRet): Integer;
              asmname '__dpmi_get_version';
     
     function DpmiGetFreeMemoryInformation
              (var MemInfo: TDpmiFreeMemInfo): Integer;
              asmname '__dpmi_get_free_memory_information';
     
     var
       Version: TDpmiVersionRet;
       MemInfo: TDpmiFreeMemInfo;
     
     begin
       if DpmiGetVersion (Version) = 0 then
         begin
           WriteLn ('CPU type :       ', Version.cpu, '86');
           WriteLn ('DPMI major :       ', Version.Major);
           WriteLn ('DPMI minor :       ', Version.Minor);
         end
       else
         WriteLn ('Error in DpmiGetVersion');
       if DpmiGetFreeMemoryInformation (MemInfo) = 0 then
         WriteLn ('Free DPMI memory : ',
                  MemInfo.Total_Number_Of_Free_Pages, ' pages.')
       else
         WriteLn ('Error in DpmiGetMemoryInformation');
     end.


File: gpc.info,  Node: DJGPP stack size,  Prev: DJGPP specific code,  Up: GPC on DJGPP

I got an exception when accessing an `array [1 .. 4000000] of Byte'.
--------------------------------------------------------------------

   Per default, the maximum stack size of a DJGPP application is 256K.
If you need more, you have to adjust it with the stubedit program, i.e.:

     stubedit your_app.exe minstack=5000K

   Another way is to add the following code to your program to define a
minimum stack size (here: 2 MB). This value will be honored even if a
user sets a lower value by using stubedit, so this method might be a
little safer.

   Note: The syntax given here is valid for GPC releases of May 2000
and newer.

     {$ifdef DJGPP}
     const
       MinStackSize : Cardinal = $200000; asmname '_stklen';
     {$endif}

   Still, it might be a good idea to use pointers for large structures,
and allocate the memory at runtime.


File: gpc.info,  Node: Strings in GPC,  Next: Getting Help,  Prev: GPC on DJGPP,  Up: FAQ

Strings
=======

* Menu:

* String schema::               What's this confusion about strings?
* Strings in variant records::  Overlaying strings in variant records
* Length byte::                 Why does `s[0]' not contain the length?
* Short strings::               Support for BP compatible short strings
* C strings::                   What about C strings?


File: gpc.info,  Node: String schema,  Next: Strings in variant records,  Up: Strings in GPC

What's this confusion about strings?
------------------------------------

   Turbo Pascal strings have a length byte in front. Since a byte has
the range 0 .. 255, this limits a string to 255 characters. However,
the Pascal string schema, as defined in section 6.4.3.3.3 of the
ISO-10206: 1990 Extended Pascal standard, is a schema record:

     type
       String (Capacity : Integer) = record
         Length : 0 .. Capacity;
         String : packed array [1 .. Capacity + 1] of Char
       end;

   The `+ 1' is a GPC extension to make it feasible to automatically
add the `#0' terminator when passing or assigning them to CStrings.
Thus at the expense of a little added complexity (must declare
capacity, don't use `GetMem' without explicit initialization of the
`Capacity' field, and the additional space requirement) you can now
have very long strings.


File: gpc.info,  Node: Strings in variant records,  Next: Length byte,  Prev: String schema,  Up: Strings in GPC

Overlaying strings in variant records
-------------------------------------

   Q: Should the different variants in a variant record overlay in the
same memory? Previous Pascals I have used have guaranteed this, and
I've got low-level code that relies on this. The variants are not the
same length, and they are intended not to be.

   A: No, this is intentional so that the discriminants are not
overwritten, and they can be properly initialized in the first place.
Consider:

     record
     case Boolean of
       False: (s1 : String (42));
       True:  (s2 : String (99));
     end;

   If the strings would overlay, in particular their discriminants
would occupy the same place in memory. How should it be initialized?
Either way, it would be wrong for at least one of the variants...

   So, after a discussion in comp.lang.pascal.ansi-iso where this topic
came up concerning file variables (which also require some automatic
initialization and finalization), we decided to do this in GPC for all
types with automatic initialization and finalization (currently files
and schemata, in the future this might also be Delphi compatible
classes and user-defined initialized and finalized types), since the
standard does not guarantee variants to overlay, anyway...

   There are two ways in GPC to get guaranteed overlaying (both
non-standard, of course, since the standard does not assume anything
about internal representations; both BP compatible), `absolute'
declarations and variable type casts. E.g., in order to overlay a byte
array `b' to a variable `v':

     var
       b: array [1 .. SizeOf (v)] of Byte absolute v;

   Or you can use type-casting:

     type
       t = array [1 .. SizeOf (v)] of Byte;

   then `t (v)' can be used as a byte array overlayed to `v'.


File: gpc.info,  Node: Length byte,  Next: Short strings,  Prev: Strings in variant records,  Up: Strings in GPC

Why does `s[0]' not contain the length?
---------------------------------------

   Q: In standard Pascal you expect `s[1]' to align with the first
character position of `s' and thus one character to the left is the
length of `s'. Thus `s[0]' is the length of `s'.  True?

   A: This holds for UCSD/BP strings (which GPC does not yet implement,
but that's planned). The only strings Standard Pascal knows are arrays
of char without any length value.

   GPC also supports Extended Pascal string schemata (*note String
schema::), but they also don't have a length byte at "position 0", but
rather a `Length' field (which is larger than one byte).


File: gpc.info,  Node: Short strings,  Next: C strings,  Prev: Length byte,  Up: Strings in GPC

Support for BP compatible short strings
---------------------------------------

   Q: Two different kinds of strings with the same name - `String' -
does make a bit of confusion. Perhaps the oldstyle strings could be
renamed `short string' ?

   A: When we implement the short strings, we'll have to do such a
distinction. Our current planning goes like this:

   `String (N)': string schema (EP compatible)

   `String [N]': short string (UCSD/BP compatible, where N must be <=
255)

   `String': dependent on flags, by default undiscriminated schema, but
in BP mode (or with a special switch) short string of capacity 255
(UCSD/BP compatible).

   Q: So when will these short strings be available?

   A: It's been planned for over a year. The delay has been caused by
more pressing problems.


File: gpc.info,  Node: C strings,  Prev: Short strings,  Up: Strings in GPC

What about C strings?
---------------------

   A C string (`char *') is an array of char, terminated with a `#0'
char.

   C library functions require C, not Pascal style string arguments.
However, Pascal style strings are automatically converted to C style
strings when passed to a routine that expects C style strings. This
works only if the routine reads from the string, not if it modifies it.

   E.g., this is how you could access the `system()' call in your C
library (which is not necessary anymore, since `Execute' is already
built-in):

     program SysCall;
     
     function System (Name : CString): Integer; asmname 'system';
     
     var
       Result : Integer;
     
     begin
       Result := System ('ls -l');
       WriteLn ('system() call returned : ', Result)
     end.

   You could use the type `PChar' instead of `CString'. Both `CString'
and `PChar' are predefined as `^Char' - though we recommend `CString'
because it makes it clearer that we're talking about some kind of
string rather than a single character.

   A lot of library routines in Pascal for many applications exist in
the GPC unit and some other units. Where available, they should be
preferred (e.g. `Execute' rather than `system()', and then you won't
have to worry about `CString's.)

   Do *not* pass a C style string as a `const' or `var' argument if the
C prototype says `const char *' or you will probably get a segfault.


File: gpc.info,  Node: Getting Help,  Next: Miscellaneous FAQ,  Prev: Strings in GPC,  Up: FAQ

Getting Help
============

   Please read the GPC Manual (info files or other formats) as well as
the `README' and `BUGS' files that come with GPC (usually installed in
directory `/usr/local/doc/gpc'), plus other docs that might help (the
DJGPP FAQ if you use DJGPP, etc.) before you send email to the
maintainers or mailing list.

   In particular, the `BUGS' file contains information on how to submit
bug reports in the most efficient way.

   The `Support' chapter of the GPC Manual tells you where to find more
information about GPC and how to contact the GPC developers.  (*note
Support::)


File: gpc.info,  Node: Miscellaneous FAQ,  Prev: Getting Help,  Up: FAQ

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

* Menu:

* Contributing::           I want to contribute; where do I start?
* GPC FTP and WWW sites::  Where is the GNU Pascal FTP site? WWW?
* About the FAQ::          About this FAQ


File: gpc.info,  Node: Contributing,  Next: GPC FTP and WWW sites,  Up: Miscellaneous FAQ

I want to contribute; where do I start?
---------------------------------------

   If you want to contribute, please write to the mailing list, *Note
Mailing List::.


File: gpc.info,  Node: GPC FTP and WWW sites,  Next: About the FAQ,  Prev: Contributing,  Up: Miscellaneous FAQ

Where is the GNU Pascal FTP site? WWW?
--------------------------------------

   The GPC homepage on the web is
`http://home.pages.de/~GNU-Pascal/'.

   For now, this same page appears at
`http://agnes.dida.physik.uni-essen.de/~gnu-pascal/'.

   The master FTP site for GNU Pascal is
`agnes.dida.physik.uni-essen.de'.

   GNU Pascal related files can be found in
`ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/'.

   GPC To-Do list, latest features, fixed bugs:
`http://agnes.dida.physik.uni-essen.de/~gnu-pascal/todo.html'


File: gpc.info,  Node: About the FAQ,  Prev: GPC FTP and WWW sites,  Up: Miscellaneous FAQ

About this FAQ
--------------

   Current Maintainer: Russ Whitaker <russ@ashlandhome.net>

   This is the second incarnation of the GNU Pascal FAQ list. Comments
about, suggestions for, or corrections to this FAQ list are welcome.

   This FAQ is based on GNU Pascal Frequently-Asked Questions List,
Edition 0.4, for GPC version 2.0, November 1996 by J.J. van der Heijden
<j.j.vanderheijden@student.utwente.nl>.

   Please make sure to include in your mail the version number of the
document to which your comments apply (you can find the version at the
beginning of this FAQ list).

   Many people have contributed to this FAQ, only some of them are
acknowledged above. Much of the info in, and inspiration for this FAQ
list was taken from the GPC mailing list traffic, so you may have
(unbeknownst to you) contributed to this list.


File: gpc.info,  Node: Installation,  Next: Borland Pascal,  Prev: FAQ,  Up: Top

How to download, compile and install GNU Pascal.
************************************************

* Menu:

* Download::              Where and what to download
* Binary Distributions::  How to install a binary distribution
* Compiling GPC::         How to compile GPC
* Compilation Notes::     Compilation notes for specific platforms
* Cross-Compilers::       Building and Installing a cross-compiler
* Crossbuilding::         Crossbuilding a compiler


File: gpc.info,  Node: Download,  Next: Binary Distributions,  Up: Installation

Where and what to download
==========================

   The master server for GNU Pascal is
`agnes.dida.physik.uni-essen.de'. Official and beta releases of the
compiler with sources and binaries for many platforms as well as other
GNU Pascal related files can be found in

     `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/'

   You can find binary distributions for many platforms in the
subdirectory `binary'. The archive files are named
`gpc-VERSION.PLATFORM.EXTENSION' - for example
`gpc-2.1.alpha-unknown-linux-gnu.tar.gz' for GPC version 2.1 on an
Alpha workstation running the Linux kernel with GNU C Library, or
`gpc-20000616.i586-pc-djgppv201.zip' for GPC version 20000616 on an
i586 PC running DOS with DJGPP version 2.01.

   After you have downloaded the correct archive file for your
platform, please read the installation notes on how to install such a
binary distribution.

   If you are running Dos or MS Windows, you will need additional tools
- see "What else to download and where" below.

Current snapshots
-----------------

   GNU Pascal is subject to steady development. You can download the
current snapshot (source only, use at your own risk) via anonymous FTP
from:

     `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/alpha/'

or via anonymous CVS from:

     CVS root:
       :pserver:anonymous@agnes.dida.physik.uni-essen.de:/usr/local/cvsroot
     Password:
       anonymous
     Command:
       checkout gpc

   Please read the installation notes on how to compile the source from
a distribution or a CVS checkout.

What else to download and where
-------------------------------

   When you are using GNU Pascal on a DOS system, you will need either
the DJGPP or the EMX development environment (see below). On an OS/2
system, you will need EMX. On an MS Windows 95/98/NT system you will
need either the CygWin or the mingw32 environment.

   GNU Pascal uses the compiler back-end from the GNU Compiler
Collection, GNU CC or GCC. If you want to compile GPC, you will need
the source of GCC as well as the source of GPC itself. For the current
version, please download `version 2.95.x' from a GNU FTP mirror (see
the list on the GNU home page, `http://www.gnu.org/gnu/order/ftp.html',
for the site closest to you).

Libraries
---------

   For some of GPC's units, you will need some standard libraries. In
particular:

Unit             Platform              Library
CRT              Unix/terminal         ncurses >= 5.0 (1), (2)
CRT              Unix/X11              PDCurses (2)
CRT              Dos, MS-Windows       PDCurses (3)
GMP              any                   gmp
RegEx            any                   rx
(debugging)      Unix, MS-Windows      ElectricFence (4)

   Notes:

   (1) ncurses version 5.0 or newer is strongly recommended because
older versions contain a bug that severely affects CRT programs.

   (2) You can install both ncurses and PDCurses on a Unix system, and
choose at compile time whether to generate a terminal or X11 version of
your program.

   (3) ncurses also runs under MS-Windows with CygWin (not mingw32,
however), but doesn't appear to behave much differently from PDCurses
on that platform.

   (4) ElectricFence is not used by any unit, but can be used for
debugging memory allocation bugs by simply linking it (see the
accompanying documentation).

   You can find those libraries on many places on the Net. Also, many
GNU/Linux distributions, DJGPP mirrors and other OS distributions
already contain some of the libraries. In any case, you can find the
sources of the libraries (sometimes together with patches that you
should apply before building if you choose to build from the sources)
and binaries for some platforms in

     `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/libs/'

DJGPP
-----

   DJGPP (http://www.delorie.com/djgpp/) is available from any SimTel
mirror in the `gnu/djgpp' subdirectory; for FTP addresses look into the
DJGPP FAQ (http://www.delorie.com/djgpp/v2faq/). For using GNU Pascal
you need at least

   - the C library, `v2/djdev201.zip', and

   - `binutils' (assembler, etc.), `v2gnu/bnu270b.zip'.

   We also recommend you to get:

   - the `make' utility, `v2gnu/mak375b.zip'

   - the GNU debugger, `v2gnu/gdb416b.zip'

   - the DJGPP FAQ, `v2faq/faq211b.zip'

   - the GRX graphics library, `http://www.gnu.de/software/GRX/'

   - PENG, `http://fjf.gnu.de/peng.html', an integrated development
     environment, similar to BP's one, written in GNU Pascal, or

   - RHIDE, `v2app/rhide.zip', another integrated development
     environment.

EMX
---

   EMX is an environment for creating 32-bit applications for DOS and
OS/2.  It is available from:

     `http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html'

   To develop EMX programs with GNU Pascal you need at least

   - the EMX runtime package, `emxrt.zip',

   - the EMX development system, `emxdev*.zip', and

   - the GNU development tools, `gnudev*.zip'.

   If your DOS box has DPMI (it does if you are using MS Windows or
OS/2) you will also need RSX, available from the same sites as EMX in
the subdirectory `rsxnt'.

   The GNU development tools contain the GNU C compiler which is in fact
not needed to use GNU Pascal. However, the C library _is_ needed.

CygWin
------

   CygWin is an environment which implements a POSIX layer under MS
Windows, giving it large parts of the functionality of Unix. CygWin
contains development tools such as an assembler, a linker, etc. GPC
needs for operation. More information about CygWin can be found at:

     `http://www.cygnus.com/cygwin/'

mingw32
-------

   The Minimalists' GNU Win32 environment, mingw32, allows a large
number of Unix programs - including GPC and GCC - to run under MS
Windows 95/98/NT using native MS libraries. mingw32 ressources can be
found at:

     `http://agnes.dida.physik.uni-essen.de/~janjaap/mingw32/'
     `http://www.xraylith.wisc.edu/~khan/software/gnu-win32/'


File: gpc.info,  Node: Binary Distributions,  Next: Compiling GPC,  Prev: Download,  Up: Installation

Installation instructions for a GPC binary distribution
=======================================================

   To install a binary distribution, `cd' to the root directory and
unpack the archive while preserving the stored directory structure.
Under a Unix compatible system with GNU `tar' installed, the following
(performed as `root') will do the job:

     # cd /
     # tar xzf ARCHIVE.tar.gz

   If you are using a `tar' utility other than GNU `tar', it might be
necessary to do the above in an explicit pipe:

     # cd /
     # gzip -c -d ARCHIVE.tar.gz | tar xf -

   If you want to install a GPC binary distribution in another directory
than it was prepared for (for example, if you do not have root access
to the computer and want to install GPC somewhere under your home
directory), you can do the following:

   - Unpack the archive file in a directory of your choice (see above).

   - `cd' to the "prefix" directory of the distribution (for instance
     `usr/local').

   - Run the script `install-gpc-binary', available from
     `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/current/binary/'.

   - Follow the instructions in the script.

   To install a ZIP archive under DOS with `PKunzip', `cd' the the
appropriate directory (usually `\' for EMX, `\DJGPP' for DJGPP), then
call `PKunzip' with the `-d' option:

     C:\> cd djgpp
     C:\DJGPP> pkunzip -d ARCHIVE.zip

   where `ARCHIVE.zip' is the name of the distribution file.

   For DJGPP you must edit your `djgpp.env' in the `DJGPP' directory to
complete the installation: Please copy the entries from `[gcc]' to
create a new `[gpc]' section. The result may look as follows:

     [gcc]
     COMPILER_PATH=%/>;COMPILER_PATH%%DJDIR%/bin
     LIBRARY_PATH=%/>;LIBRARY_PATH%%DJDIR%/lib
     
     [gpc]
     COMPILER_PATH=%/>;COMPILER_PATH%%DJDIR%/bin
     LIBRARY_PATH=%/>;LIBRARY_PATH%%DJDIR%/lib

   If you are using the DJGPP version of GPC but do not have a `DJGPP'
directory, please download and install DJGPP (*note Download::).

   Binary distributions include `libgcc.a' and `specs', files that are
normally part of GCC. If you have GCC installed, they will be replaced
unless you manually install the archive.


File: gpc.info,  Node: Compiling GPC,  Next: Compilation Notes,  Prev: Binary Distributions,  Up: Installation

Compiling GPC
=============

   The preferred way to distribute GNU software is distribution of the
source code. However, it can be a non-trivial exercise to build GNU
Pascal on some non-Unix systems, so we also provide ready-to-run
binaries for a number of platforms. (See *Note Binary Distributions::
for how to install a binary distribution.)

   GPC is based on the GNU Compiler Collection, GNU CC or GCC. You will
need the GCC sources to build it. It must be the same version as the
one GPC is implemented with - `version 2.95.x' as of this writing.
Although you need GCC to build the GNU Pascal compiler, you don't need
GCC to compile Pascal programs once GNU Pascal is installed. (However,
using certain libraries will require compiling C wrappers, so it is a
good idea to install the C compiler as well.)

   Because GNU Pascal shares its back-end with GCC, it should run on any
system supported by GCC. A full list of platforms supported by GCC can
be found in *Note the GCC installation instructions: (gcc)Installation.

   The GCC source can be obtained from any mirror of the GNU FTP site,
`ftp://ftp.gnu.org/gnu/gcc/'. The "core" distribution is sufficient for
GPC.

   Here is the generic procedure for installing GNU Pascal on a Unix
system. See *Note Compilation Notes:: for extra information needed to
install GPC on DOS-like platforms.

  1. Checking the prerequisites

     Make sure that GNU make is installed. (In the following, we will
     simply speak of `make' when invoking GNU make; you might need to
     call `gmake' instead.)

     For extracting the example programs from the documentation to the
     `doc/docdemos' directory a non-crippled `sed' is needed.  GNU sed
     is known to work.

     If you have checked out the GPC source from CVS, you will have to
     rebuild most derived files, so you will need additional tools:
     `bison', `flex', `makeinfo', `gperf', and `autoconf'. Make sure
     that these are installed.

     If you want to build the GPC WWW pages you will also need:
     `texi2html' version 1.61 (older versions are missing some needed
     features; newer versions suffer from a bug), `texi2dvi', TeX,
     `gzip', `dvips', `dviselect', and `dviconcat'.

     If you run into trouble during the installation process, please
     check whether you are using outdated versions of the required
     utilities and upgrade if necessary.

     The GNU versions of the packages above are available from the GNU
     FTP server (ftp://ftp.gnu.org) or any of its mirrors.  Package
     PACKAGE is usually located in the directory `gnu/PACKAGE'.

  2. Unpacking the source

     From a directory of your choice (e.g. `/home/fred'), unpack the
     GCC and GNU Pascal source distributions. This will create separate
     subdirectories for GCC and GPC. Let us assume `gcc-2.95.1' and
     `gpc-20000535' in this example.
          % cd /home/fred
          % gzip -c -d gcc-core-2.95.1.tar.gz | tar xf -
          % gzip -c -d gpc-20000535.tar.gz | tar xf -

     `cd' to the GPC directory and move the contents (a subdirectory
     `p') to the subdirectory `gcc' of the GCC directory:

          % cd /home/fred/gpc-20000535
          % mv p /home/fred/gcc-2.95.1/gcc/

     It is recommended, though not required, to use a separate
     directory for building the compiler, rather than compiling in the
     source directory. In this example, let us create
     `/home/fred/gpc-build' for this purpose:

          % mkdir /home/fred/gpc-build

     If you use a separate directory, you do not need to write into the
     GCC source directory once you have patched the GCC source (see
     below), and can build GPC for more than one platform from the same
     source tree.

     In case you are re-using a directory where you have already built
     GCC and/or GPC for a different target machine, do `make distclean'
     to delete all files that might be invalid. One of the files this
     deletes is `Makefile'; if `make distclean' complains that
     `Makefile' does not exist, it probably means that the directory is
     already suitably clean.

  3. Configuring and building GCC

     GNU Pascal is automatically configured with GCC. Configuration of
     GCC is treated in depth in *Note the GCC installation
     instructions: (gcc)Installation. The normal procedure is as
     follows:

     `cd' to the GPC build directory. From there, run the `configure'
     script in the GCC source directory:

          % cd /home/fred/gpc-build
          % /home/fred/gcc-2.95.1/configure --enable-languages=pascal

     This creates all the necessary config files, links and Makefile in
     the GCC object directory.

     Note 1: The configuration will prompt you for patching the GCC
     source for GPC support, so you need write access to that
     directory. All changes to GCC are surrounded by `#ifdef GPC ...
     #endif', so they should not interfere when you build a C compiler
     from this source tree.

     Note 2: The `--enable-languages=pascal' option means that we only
     want to build the Pascal compiler and not, for instance, the C++
     compiler.

     Note 3: The standard base directory for installing GCC and GPC is
     `/usr/local'. If you want to install files to an alternate
     directory DIR, specify `--prefix=DIR' when you run `configure'.

  4. Putting other GNU tools in place

     Some environments require other GNU tools (such as the GNU
     assembler or linker) instead of the standard system tools for GCC
     to work. (See the GCC installation instructions for details.) If
     this is the case for your system, install the required tools in
     the GPC build directory under the names `as', `ld', or whatever is
     appropriate. This will enable the compiler to find the proper
     tools for compilation of the program `enquire' (a part of GCC) and
     to install the GNU tools to a place where they are found by GCC
     but do not interfere with the standard system tools.

     Alternatively, you can do subsequent compilation using a value of
     the `PATH' environment variable such that the necessary GNU tools
     come before the standard system tools.

  5. Compiling GPC

     Once you are satisfied with the configuration as determined by
     `configure', you can build the compiler:

          % make

     Notice that this procedure will build the C compiler (and maybe
     some other compilers) too, because that is used to compile the GPC
     runtime library.

     Optionally, you may supply CFLAGS, LDFLAGS or RTSFLAGS. CFLAGS is
     used for compiler and RTS, RTSFLAGS are for RTS only, i.e.: `make
     CFLAGS="-O2" RTSFLAGS=-Wall'

  6. Completing the installation

     When everything has been compiled, you can check the installation
     process with:

          % make -n install

     To complete the installation, run the command `make install'. You
     need write access to the target directories (`/usr/local/bin',
     `/usr/local/lib', `/usr/local/info', `/usr/local/doc', and
     `/usr/local/man' in this example), so this is usually done as
     `root':

          % su -c "make install"

     If you want to install _only_ the Pascal compiler (for example if
     you already have the correct version of GCC installed), `cd' to the
     `gcc' subdirectory of the build directory (e.g.
     `/home/fred/gpc-build/gcc') and run `make pascal.install'. This
     installation process does *not* overwrite existing copies of
     `libgcc.a' or `specs', should they exist.

     Also from the `gcc' subdirectory you can do some more "exotic"
     builds. For instance, you can build the GPC WWW pages by typing
     `make pascal.html' or a binary distribution by typing `make
     pascal.bindist'. See the `Makefile' in that directory for more
     examples.


File: gpc.info,  Node: Compilation Notes,  Next: Cross-Compilers,  Prev: Compiling GPC,  Up: Installation

Compilation notes for specific platforms
========================================

* Menu:

* MS-DOS with DJGPP::        The DJGPP port of GNU compilers to MS-DOS.
* MS-DOS or OS/2 with EMX::  The EMX port of GNU compilers to MS-DOS and OS/2.
* MS Windows 95/98/NT::      Installation on a Windows 95/98/NT system.


File: gpc.info,  Node: MS-DOS with DJGPP,  Next: MS-DOS or OS/2 with EMX,  Up: Compilation Notes

MS-DOS with DJGPP
-----------------

   The only compiler that is capable of compiling the GNU Compiler
Collection (GNU CC or GCC) under MS-DOS is GCC itself. In order to
compile GPC or GCC for MS-DOS with DJGPP you will therefore need either
a working copy of DJGPP installed, or you will have to cross-build from
a non-MS-DOS system.

   Building GPC under MS-DOS with DJGPP follows the same scheme as
building GPC under a Unix-like system: Place the `p' subdirectory in the
`gcc' directory and follow the instructions for compiling GCC. This
requires `bash' and many other tools installed, and you must be very
careful at many places to circumvent the limitations of the DOS
platform.

   Our preferred way to build GPC for DJGPP is to cross-build it from a
Unix-like platform - which is much easier. For instructions, see *Note
Cross-Compilers:: and *Note Crossbuilding::.


File: gpc.info,  Node: MS-DOS or OS/2 with EMX,  Next: MS Windows 95/98/NT,  Prev: MS-DOS with DJGPP,  Up: Compilation Notes

MS-DOS or OS/2 with EMX
-----------------------

   EMX is a free 32-bit DOS extender which adds some properties of Unix
to MS-compatible DOS and IBM's OS/2 operating systems.

   As of this writing, we are not aware of current versions of GCC for
EMX, and EMX support in GPC has not been maintained. Please contact us
if you know about recent development in EMX and are interested in
continuing EMX support in GPC.


File: gpc.info,  Node: MS Windows 95/98/NT,  Prev: MS-DOS or OS/2 with EMX,  Up: Compilation Notes

MS Windows 95/98/NT
-------------------

   There are two ports of the GNU development tools to MS Windows
95/98/NT: CygWin and mingw32.

   The CygWin environment implements a POSIX layer under MS Windows,
giving it large parts of the functionality of Unix. Thus, compiling GCC
and GPC under the CygWin environment can be done following the
instructions for compiling it under a Unix-like system (see *Note
Compiling GPC::).

   The Minimalists' GNU Win32 environment, mingw32, uses the native
`crtdll.dll' library of MS Winodws. It is much smaller than CygWin, but
it is not self-hosting and must be crossbuilt from another system (see
*Note Crossbuilding::).

