Installing GNU Pascal
*********************

   The preferred way to distribute GNU software is distribution of the
source code.  However it is nontrivial to compile GNU Pascal on non-UNIX
systems, so we also provide ready-to-run binaries for the following
platforms:

   * DJGPP for DOS (you need the DJGPP/GO32 extender),

   * EMX for DOS and OS/2 (you need the EMX extender),

   * CygWin32 for Windows 95/NT (you need the CygWin32 extender),

   * Linux.

   To install a binary distribution, cd to the main directory and
unpack the archive while preserving the stored directory structure.  In
concrete, to install a ZIP archive under DOS with PKunzip, type

       C:\> pkunzip -d ARCHIVE

   where ARCHIVE is the name of the distribution file.  To install a
TGZ archive under Linux, type

       # tar xzf ARCHIVE.tgz

   Compilation instructions for the different platforms and more about
the extenders mentioned above follow.

Installation on a UNIX system
=============================

   GPC is based on GNU CC; you will need the GCC sources to build it.
It must be the same version as the one GPC is implemented with.
Although you need GCC to build the GNU Pascal compiler, you don't need
GCC to compile Pascal programs once GNU Pascal is installed.

   Here is the generic procedure for installing GNU Pascal on a Unix
system.  See *Note System V:: for System V compatible unices (e.g.
Linux), *Note Alpha OSF/1:: for Alpha OSF/1 systems.

  1. Unpack source distributions.

     Please note that it is *not possible* to compile gpc if you do not
     have separate object and source directories. (i.e. you can not
     configure gpc so that the compiled object files are generated to
     the same directory where the sources are) This means that you'll
     need a make that understands the VPATH variable. GNU Make does.

     A sample directory structure (for a Linux configuration) might be:

          /home/joe/src/gnu/gcc               <- GCC sources
                           /gcc-i486-linux    <- GCC objects
                           /gpc               <- GPC sources
                           /gpc-i486-linux    <- GPC objects

     If you have built GNU Pascal previously in the same directory 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.

  2. Chdir to the GCC object directory and configure GCC. Configuration
     of GNU CC is treated in depth in Chapter 4 of "Using and Porting
     GNU CC" Usually,

          % ../gcc/configure --prefix=/usr

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

  3. The standard directory for installing GNU CC and GNU Pascal is
     `/usr/local/lib'. If you want to install its files somewhere else,
     specify `--prefix=DIR' when you run `configure'.  Here DIR is a
     directory name to use instead of `/usr/local' for all purposes
     with one exception: the directory `/usr/local/include' is searched
     for header files no matter where you install the compiler.  To
     override this name, use the `--local-prefix' option below.

  4. Specify `--local-prefix=DIR' if you want the compiler to search
     directory `DIR/include' for locally installed header files
     *instead* of `/usr/local/include'.

     You should specify `--local-prefix' *only* if your site has a
     different convention (not `/usr/local') for where to put
     site-specific files.

     *Do not* specify `/usr' as the `--local-prefix'!  The directory
     you use for `--local-prefix' *must not* contain any of the
     system's standard header files.  If it did contain them, certain
     programs would be miscompiled (including GNU Emacs, on certain
     targets), because this would override and nullify the header file
     corrections made by the `fixincludes' script.

  5. Make sure the Bison parser generator is installed.  (This is
     unnecessary if the Bison output files `c-parse.c' and `cexp.c' are
     more recent than `c-parse.y' and `cexp.y' and you do not plan to
     change the `.y' files.)

     Bison versions older than Sept 8, 1988 will produce incorrect
     output for `c-parse.c'.

  6. If you have chosen a configuration for GNU Pascal which requires
     other GNU tools (such as GAS or the GNU linker) instead of the
     standard system tools, install the required tools in the 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'.

     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.

  7. Build the C compiler:

          % make LANGUAGES=c

     (Just `make' would also build the C++ and Objective C compilers).
     Leave the objects in place, since GPC will directly load most of
     the GCC object files.

  8. Install the GNU C compiler. At least install it so that the `xgcc'
     program will be able to locate the `libgcc.a' file with `xgcc
     --print-libgcc-file-name' command. This is to find out where gpc
     Makefile should put `libgpc.a' and `gpc1'.

     If you do not install the C compiler, you may be able to configure
     gpc anyway, if you give both gpc- and gcc `configure' scripts
     identical `--prefix=/some/path' options

  9. Chdir to the GPC object directory and configure GPC.  Note that
     the gpc configure script does not want to have the usual
     host-vendor-system spec, since GPC is compiled for the same system
     than GCC was compiled for. All you have to do is give the
     locations of GCC sources, GCC object code and the GPC sources.
     Assuming the directory structure given before,

          % ../gpc/configure --srcdir=../gpc --gccdir=../gcc-i486-linux \
                  --gccsrc=../gcc

     will do it all.

     If you do not use `--prefix', gpc will install itself to the same
     directory where gcc has been installed before (i.e. the gpc
     compiler driver looks for the `gpc-cpp' preprocessor, the `gpc1'
     compiler and the `libgpc.a' library from the same directory where
     the `libgcc.a' library is found. This is determined automatically
     by GPC configure script; and to do that the GCC needs to be
     installed).

 10. Say "make -n" to see if everything is ok.

 11. After it is, you just say "make" to make the compiler and run time
     system.

 12. When everything compiles, you can verify what the  `make -n
     install' command does, and if you are satisfied run it without the
     `-n' option to install the compiler (gpc1), front end (gpc), run
     time system (libgpc.a) to the same place where gcc was installed.

     It is sort of stupid to have a separate incarnation of `gcc.c'; the
     difference now is that "gpc" also searches from library `libgpc.a'
     and `-lm'. In addition `gcc.c' specifies the interface to the
     Pascal compiler (gpc1). This command will vanish when "gcc" knows
     how to compile Pascal programs.


   Configuration dependent notes:

System V compatible unices (e.g. Linux)
---------------------------------------

   Compiling the Runtime System (RTS) on a System V compatible unix
requires "-DSYSV" to be set in CFLAGS. `configure' recognizes a number
of System V compatible unices, but not all.

   If you see:
     ../srcdir/rts/rts-rt0.c: In function `_p_initialize':
     ../srcdir/rts/rts-rt0.c:286: `SIGEMT' undeclared (first use this function)
     ../srcdir/rts/rts-rt0.c:290: `SIGSYS' undeclared (first use this function)
   while building `libgpc.a', you have to add "-DSYSV" to your
MY_CFLAGS.

   Example:
     % make MY_CFLAGS=-DSYSV other-make-flags-you-want-to-use

   Please send a report, with the canonical name of the system to
`gpc@kampi.hut.fi'

Alpha OSF/1
-----------

   For alpha OSF/1 v3.2 (GCC 2.6.3): If your linker starts to output
error messages like:

     Warning: Linking some objects which contain exception information sections
         and some which do not. This may cause fatal runtime exception handling
         problems (last obj encountered without exceptions was <OBJ/LIB>)

   I do not know why these started to appear, but you can get rid of
these if you do as follows in the GPC object directory.

   You need to trigger the Makefile dependencies, e.g. by doing the
touch command below. What happens is that it re-generates the version.c
and rts/version.c files, which need to be recompiled with `ALPHA_BUG'
defined.

   Example:
     % touch Makefile
     % make MY_CFLAGS=-DALPHA_BUG other-make-flags-you-want-to-use

GNU Pascal for MS-DOS with DJGPP
================================

   You cannot build GNU CC (or GNU Pascal) by itself on MS-DOS; it will
not compile under any MS-DOS compiler except itself. The official
MS-DOS port of GCC is called djgpp, and it is available from
`simtel.coast.net' and it's mirrors all over the world. The `configure'
script is replaced by an MS-DOS batch file called `configure.bat' wich
does essentially the same. A pre-configured source distribution should
be available from the same site where you got djgpp.

GNU Pascal for MS-DOS or OS/2 with EMX
======================================

   EMX is a FreeWare 32-bit DOS extender which adds some properties of
UNIX to the DOS and OS/2 operating systems written by Eberhard Mattes.
You can find it, for example, via anonymous `ftp' on the server
`ftp.uni-stuttgart.de' in the directory `pub/systems/os2/emx*'.

   The EMX extender for DOS and OS/2 makes it relatively easy to port
GNU tools--such as the GNU Pascal Compiler--to these platforms.
However, it is not straightforward to compile it.  There is no bash.
No symbolic links.  8.3 file names.  Etc.  It took me about two
complete days to find out what to do--not much when facing the about 15
MegaBytes of sources, but enough.  The method I finally did it through
might be not the best one but it works, and I document it here.  If
somebody finds a cleaner way how to compile GNU Pascal for EMX, please
let me know!  `<peter.gerwinski@uni-essen.de>'.

  0. I assume you have the EMX package installed with GNU development
     tools and the `nmake' make utility.

     If you are using a DOS system, you are in trouble now, because the
     required utility `nmake' is an OS/2 program.  I was not able to
     replace it with, for example, Borland `make'; if you are, please
     inform me.

  1. Get the patched source code GCCSRC1.ZIP, GCCSRC2.ZIP, GCCSRC3.ZIP
     for GCC version 2.7.2.  (The correct version is important.)  Get
     the original source ZIP archive for GNU Pascal (GPC) 2.7.2 from
     `kampi.hut.fi'.

  2. Unzip the source for GCC.  E.g. with PKUNZIP, when the ZIP files
     are in the `C:\' directory:

            pkunzip -d c:\gccsrc? \

  3. Unzip the source for GPC in the `emx\gnu' directory.

            cd \emx\gnu
            pkunzip -d c:\gpc-272

  4. Rename the GCC subdirectory in `\emx\gnu' to make things more
     symmetric. (-: Don't omit this because the Makefile I created
     relies on this naming.)

            rendir gcc-2.7 gcc-272

     (with OS/2: `ren')

  5. Cd to the EMX subdirectory and run the nmake utility telling it
     whether you are using a FAT or a HPFS partition.  Use UPPERCASE
     here--nmake is case-sensitive.

            cd gpc-272\emx
            nmake FS=FAT

     Be patient - this will take a while to complete.

  6. That's it.  Hope that not too much went wrong.  Write some tiny
     test programs.  Write useful larger programs with GPC ...

GNU Pascal for Windows NT and Windows 95 with CygWin32
======================================================

   CygWin32 is a project to make it easy to port Unix applications to
machines which run an OS which supports the Win32 API - ie Windows 95
and Windows NT.  Windows NT runs on more than just the 386 too.
Currently, cygwin32 is in beta stage; it is available from
`ftp://ftp.cygnus.com/pub/gnu-win32/' This (beta) GCC is incompatible
with GNU Pascal, but neither gcc-2.6.3 nor gcc-2.7.2 does support the
cygwin32 platform. To patch cygwin32 support into a regular GNU CC
distribution, you need a special patch, available from the site where
you got the GNU Pascal sources. Because of the unix-ish environment
provided by cygwin32, configuring and building GNU Pascal is
essentially the same as a unix configuration.

   Currently, GNU Pascal does not support the stack calling convention
of the Win32 API, thus making it impossible to access system DLL's.

Building and Installing a Cross-Compiler
========================================

   GNU Pascal can function as a cross-compiler for many machines, but
not all.  Also, only a few combinations have been tested. If you need
information about GNU tools in a cross-configuration,
`ftp://ftp.cygnus.com/pub/embedded/crossgcc/' is the place to be.

   * Cross-compilers for the Mips as target using the Mips assembler
     currently do not work, because the auxiliary programs
     `mips-tdump.c' and `mips-tfile.c' can't be compiled on anything
     but a Mips.  It does work to cross compile for a Mips if you use
     the GNU assembler and linker.

   * Cross-compilers between machines with different floating point
     formats have not all been made to work.  GNU C now has a floating
     point emulator with which these can work, but each target machine
     description needs to be updated to take advantage of it.

   * Cross-compilation between machines of different word sizes is
     somewhat problematic and sometimes does not work.

   Since GNU Pascal generates assembler code, you probably need a
cross-assembler that GNU Pascal can run, in order to produce object
files.  If you want to link on other than the target machine, you need a
cross-linker as well.  You also need header files and libraries suitable
for the target machine that you can install on the host machine.

Steps of Cross-Compilation
--------------------------

   To compile and run a program using a cross-compiler involves several
steps:

   * Run the cross-compiler on the host machine to produce assembler
     files for the target machine.  This requires header files for the
     target machine.

   * Assemble the files produced by the cross-compiler.  You can do this
     either with an assembler on the target machine, or with a
     cross-assembler on the host machine.

   * Link those files to make an executable.  You can do this either
     with a linker on the target machine, or with a cross-linker on the
     host machine.  Whichever machine you use, you need libraries and
     certain startup files (typically `crt....o') for the target
     machine.

   It is most convenient to do all of these steps on the same host
machine, since then you can do it all with a single invocation of GNU
Pascal.  This requires a suitable cross-assembler and cross-linker.
For some targets, the GNU assembler and linker are available.

Configuring GNU CC as a Cross-Compiler
--------------------------------------

   No special actions have to be taken to configure GNU Pascal as a
crosscompiler. Cross-compiler specific configuration is done only for
GCC.  Section 4.2 of "Using and Porting GNU CC" deals with
cross-configurations in great detail. Once cross-binutils and a C
library for the target machine are in place, GCC can be configured
(from the GCC object directory).  Suppose we are on a Linux system and
want a cross-compiler that produces code that runs on MS-DOS:

     % ../gcc/configure --prefix=/usr --target=i386-go32

   This creates all the necessary config files, links and Makefile in
the GCC object directory. Now, proceed with the compilation and
installation process like in the case of the native configuration
described before. Do not remove files from the GCC object directory;
the cross-compiler is used to compile the GNU Pascal runtime system
(RTS) for the target system.

Building the Pascal Cross-Compiler
----------------------------------

   Once you have verified the C cross-compiler, the Pascal
cross-compiler can be configured and built. Note that the `configure'
script does not require any cross-compiler related switches because GPC
inherits all of this from GNU CC.  Assuming GCC object code is in
`../gcc-i386-go32/',

     % ../gpc/configure --srcdir=../gpc --gccdir=../gcc-i386-go32 --gccsrc=../gcc
     % make

   Then, "make install" the cross-compiler.

