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

   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:: how
to install a binary distribution.

   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. Because GNU Pascal
shares its backend with GNU CC, it should run on any system supported by
GNU CC. A full list of platforms supported by GNU CC can be found in
*Note the GCC installation instructions: (gcc)Installation.

   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 certain platforms.

  1. Unpack the source distributions.

     From a directory of your choice (e.g. `/usr/local/src'), unpack
     the GNU CC and GNU Pascal source distributions.  This will create
     separate subdirectories for GCC and GPC.

     `cd' to the GPC directory (`/usr/local/src/gpc' in the example
     above) and move the contents (a subdirectory `p') to the GCC
     directory (for instance `usr/local/src/gcc-2.8.1').

     Next, go to the GCC source directory and apply the GCC patch
     required by GNU Pascal:

          % patch -s -p1 < p/diffs/gcc-2.8.1.diff

     Note 1: If you omit this step, `configure' (see below) will prompt
     you for doing this automatically.

     Note 2: In the example above, GCC version 2.8.1 is assumed.  If
     your version of GCC is other than 2.8.1, you have to get and apply
     the appropriate patch.  If you run the patch automatically from
     `configure', it will detect and work with some versions of EGCS.

     Note 3: 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.

     It is possible, though not required, to build the compiler in a
     directory other than the one containing the sources.  (If you do
     that, you do not need to write into the GCC source directory and
     can build GPC for more than one platform from the same source
     tree.)  In that case, you need a `make' that understands the VPATH
     variable.  GNU make does, although at least GNU make version 3.71
     has a bug in the way it treats VPATH.  GNU make version 3.75 is
     known to work.

     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. Configuring and building GNU CC GNU Pascal is automatically
     configured with GNU CC.  Configuration of GNU CC is treated in
     depth in *Note the GCC installation instructions:
     (gcc)Installation.

     Chdir to the GCC object directory.  (This can be a directory of
     your choice, including the GCC source directory.)  From there, run
     the `configure' script in the GCC source directory.  If both
     directories are the same, the command

          % ./configure

     is sufficient to configure GCC in most cases.  If they are
     different, something like

          % ../gcc-2.8.1/configure

     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', `cexp.c', and
     `p/parse.y' are more recent than `c-parse.y', `cexp.y',
     `p/parse.c', and `p/parse.h' 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. Once you are satisfied with the configuration as determined by
     `configure', you can build the Pascal compiler:

          % make LANGUAGES=pascal

     (Just `make' would also build the C++ and Objective C compilers).
     Notice that this procedure will build the C compiler 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'

  8. When everything compiles, you can verify what the `make -n
     pascal.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. This installation process does *not* overwrite
     existing copies of `libgcc.a' or `specs', should they exist.

     You can also install GPC as part of the complete GNU compiler
     suite using "make install" as described in the GCC installation
     docs.


Configuration dependent compilation notes
=========================================

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>)

   We 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

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

   You cannot build GNU CC (or GNU Pascal) by itself on MS-DOS or a
compatible system; 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 has mirrors all over the world.
The `configure' script is replaced by an MS-DOS batch file called
`configure.bat' wich does essentially the same. Detailed instructions
are in the file `config/msdos/README.dj' of the GNU Pascal source
distribution.

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.  You can find
it, for example, via anonymous `ftp' on the server
`ftp.uni-stuttgart.de' in the directory `pub/systems/os2/emx*'.

   Due to the limitation of the command line to 128 characters we don't
know a way to compile GPC for EMX under DOS; you need OS/2 instead.  If
you succeed to compile GPC for EMX on a DOS system, please let us know.
(However you can compile GPC for DJGPP on a DOS system.)

  1. Unzip the source for GCC from the root directory, and rename the
     resulting directory `gcc-2.7' to `gpc'.
            cd \
            unzip c:\gccsrc1
            unzip c:\gccsrc2
            unzip c:\gccsrc3
            ren \emx\gnu\gcc-2.7 gpc

  2. Unzip the source for GPC from the `emx\gnu' directory, so it will
     go into the gpc subdirectory.  Unlike other EMX sources, the GPC
     source must *not* be extracted from the root directory.
            cd \emx\gnu
            unzip c:\gpc-21s.zip

  3. If you are working on a drive different from `c:' and/or if you
     want to compile the compiler with optimization and/or without
     debugging information (recommended), edit
     `\emx\gnu\gpc\dostage1.cmd' to refer to your drive and to have the
     `CFLAGS' you want, e.g.  `CFLAGS=-O2' instead of `CFLAGS=-g'.

  4. You will also want to apply the patches for gcc.  To do this you
     will need GNU Patch (also known as Larry Wall's Patch), which
     should be available from the normal OS/2 `ftp' archives, e.g.
     `hobbes.nmsu.edu' in the `/pub/os2/unix/dev' directory.  Make sure
     you rename `patch.exe' to a filename that won't conflict with the
     built in OS/2 patch command.  EM recommends using `lwpatch.exe' in
     his `\emx\doc\build.doc' file.

     Apply the diff:
            cd \emx\gnu\gpc
            set emxopt=-t
            lwpatch -p1 --prefix=~ < p\diffs\gcc-2.8.1.diff

  5. Compile GPC using the `compile.cmd' script.
            cd \emx\gnu\gpc\p
            compile

  6. To install, move the GPC files into place.
            cd \emx\gnu\gpc
            copy gpc*.exe \emx\bin
            copy libgpc.a \emx\lib\gpc.a


   Note:  The EMX C compiler has not yet been upgraded to GCC 2.8.1.
If you want to compile GPC for EMX, some porting will be necessary to
make GPC compile with GCC 2.7.2--or to make GCC 2.8.1 run on EMX.

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--i.e. Microsoft
Windows 95 and Windows NT. Currently, cygwin32 is in beta stage; it is
available from `ftp://ftp.cygnus.com/pub/gnu-win32/' Don't use gcc
sources from the cygwin32 distribution. These are not just modified from
FSF `gcc-2.8.1' to support the Windows 95/NT target, they are the
"current development release", and too different from FSF GCC to be
compatible with GNU Pascal, which is based on FSF sources.

   Currently, cygwin32 is not self-hosting: the preferred way to build
the cygwin32-gpc binary is to use a UNIX system with a cygwin32
targeting cross-compiler. *Note Crossbuilding::

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
cross-compiler. 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 FreeBSD system
and want a cross-compiler that produces code that runs on MS-DOS:

     % ../gcc-2.8.1/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.

   Sample output for a FreeBSD->msdos cross configuration:

     --------------------------------------------------------------------------
     Configuration summary:
       Building a i386-go32 cross-compiler hosted by i386-unknown-freebsd2.1.0
     
       GPC sources in:         ../gpc-2.0
       GCC sources in:         ../gcc-2.8.1
       GCC object code in:     ../gcc
       GCC version:            2.8.1
     
       Compiler for GPC:       gcc
       Compiler for libgpc.a:  i386-go32-gcc
       Compiler flags:         -g -O
     
       Cross-ar utility:       i386-go32-ar
       Cross-ranlib utility:   i386-go32-ranlib
     
       Installation path:      /usr/bin, /usr/lib/gcc-lib/i386-go32/2.8.1
     --------------------------------------------------------------------------
     
     Now, type `make' to build the compiler and runtime system.

   Building a cross-compiler requires cross-binutils for your target,
i386-go32 in this examples. If `configure' is not able to find
`i386-go32-ar' and/or `i386-go32-ranlib', you may have to run it again
with again with `--with-ar=YOUR-CROSS-AR' or
`--with-ranlib=YOUR-CROSS-RANLIB' switches.

   Then, `make' and `make install' the cross-compiler like you would
for a native configuration.

Crossbuilding a compiler.
-------------------------

   Yet another possibility is CROSSBUILDING : Using a cross-compiler to
build GNU Pascal results in a compiler binary that runs on the
cross-target platform. A possible reason why anybody would want to do
this, is when the platform on which you want to run the GNU Pascal
compiler, is not self-hosting. An example is cygwin32.

   To crossbuild GNU Pascal, you have to install a cross-compiler for
your target first. This is covered in chapter 4 of "Using and Porting
GNU CC".  Assuming you want to build a native cygwin32 Pascal compiler
on a FreeBSD system, configure GCC:

     % ../gcc-2.8.1/configure --prefix=/usr --build=i386-freebsd \
     	--host=i386-cygwin32 --target=i386-cygwin32

   Build it:

     % make CFLAGS=-O2 LANGUAGES=c

   Now, configure and build GPC. The output of `configure' should look
like:

     --------------------------------------------------------------------------
     Configuration summary:
       Building a i386-cygwin32 cross-compiler hosted by i386-cygwin32
     
       GPC sources in:         ../gpc-2.0
       GCC sources in:         ../gcc-2.8.1
       GCC object code in:     ../gcc
       GCC version:            2.8.1
     
       Compiler for GPC:       i386-cygwin32-gcc
       Compiler for libgpc.a:  i386-cygwin32-gcc
       Compiler flags:         -g -O
     
       Cross-ar utility:       i386-cygwin32-ar
       Cross-ranlib utility:   i386-cygwin32-ranlib
     
       Installation path:      /usr/bin, /usr/lib/gcc-lib/i386-cygwin32/2.8.1
     --------------------------------------------------------------------------
     
     Now, type `make' to build the compiler and runtime system.

   Again, `configure' should be able to detect and configure this setup
without additional flags. If not, specify `--with-ar', `--with-ranlib',
`--with-gcc' and/or `--with-rtsgcc' as appropriate.

   A cross-built compiler must be installed by hand.

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

   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, `cd' the the
appropriate directory (usually `\' for EMX, `\DJGPP' for DJGPP), then
type

       C:\> pkunzip -d ARCHIVE

   where ARCHIVE is the name of the distribution file.  To install a
`.tar.gz' archive under a UNIX compatible system, become root, then
extract the archive from the root of the filesystem:

       # 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 two steps:

       # gzip -d ARCHIVE.tar.gz
       # tar xf ARCHIVE.tar

   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.

