@c Copyright (C) 1988, 1996 Free Software Foundation, Inc.
@c This is part of the GPC manual.
@c For copying conditions, see the file gpc.texi.
@c
@c Written by J.J. van der Heijden <j.j.vanderheijden@student.utwente.nl>
@c Last modified: 24 Jun 1997 19:53 (PG)
@c
@c Adapted to comply FSF naming conventions on Thu 26 Dec 1996
@c by Peter Gerwinski <peter@gerwinski.de>
@c
@c The text of this file appears in the file INSTALL
@c in the GPC distribution, as well as in the GPC manual.

@ifclear INSTALLONLY
@node Installation
@chapter Installing GNU Pascal
@cindex installing GNU Pascal
@end ifclear

@ifset INSTALLONLY
@settitle GNU Pascal Installation Guide
@node Top
@chapter Installing GNU Pascal
@end ifset

@iftex
This chapter covers:
@itemize @bullet
@item Compilation of the source distribution on a UNIX system
@item Configuration dependent compilation notes
@item Building and installing a cross-compiler
@item Installation instructions for a GPC binary distribution
@end itemize
@end iftex

@menu
* compilation notes::     Configuration dependent compilation notes.
* cross-compilers::       Building and Installing a cross-compiler.
* binary distributions::  How to install a binary distribution.
@end menu

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 @ref{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
@ref{Installation, the GCC installation instructions, Installation, gcc,
``Using and Porting GNU CC''}.

Here is the generic procedure for installing GNU Pascal on a UNIX
system.  See @ref{compilation notes} for extra information needed to
install GPC on certain platforms.

@enumerate
@item Unpack the source distributions.

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

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

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

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

Note 1: If you omit this step, @samp{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
@samp{configure}, it will detect and work with some versions of EGCS.

Note 3: All changes to GCC are surrounded by @samp{#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 @file{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 @samp{make distclean} to delete all files
that might be invalid.  One of the files this deletes is
@file{Makefile}; if @samp{make distclean} complains that @file{Makefile}
does not exist, it probably means that the directory is already suitably
clean.

@item Configuring and building GNU CC
GNU Pascal is automatically configured with GNU CC.  Configuration of
GNU CC is treated in depth in @ref{Installation, the GCC installation
instructions, Chapter 4, gcc, ``Using and Porting GNU CC''}.

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

@smallexample
% ./configure
@end smallexample

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

@smallexample
% ../gcc-2.8.1/configure
@end smallexample

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

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

@item
Specify @samp{--local-prefix=@var{dir}} if you want the compiler to
search directory @file{@var{dir}/include} for locally installed header
files @emph{instead} of @file{/usr/local/include}.

You should specify @samp{--local-prefix} @strong{only} if your site has
a different convention (not @file{/usr/local}) for where to put
site-specific files.

@strong{Do not} specify @file{/usr} as the @samp{--local-prefix}!  The
directory you use for @samp{--local-prefix} @strong{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 @code{fixincludes} script.

@cindex Bison parser generator
@cindex parser generator, Bison
@item
Make sure the Bison parser generator is installed.  (This is unnecessary
if the Bison output files @file{c-parse.c}, @file{cexp.c}, and
@file{p/parse.y} are more recent than @file{c-parse.y}, @file{cexp.y},
@file{p/parse.c}, and @file{p/parse.h} and you do not plan to change the
@file{.y} files.)

Bison versions older than Sept 8, 1988 will produce incorrect output for
@file{c-parse.c}.

@item
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
@file{as}, @file{ld} or whatever is appropriate.  This will enable the
compiler to find the proper tools for compilation of the program
@file{enquire}.

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

@item
Once you are satisfied with the configuration as determined
by @file{configure}, you can build the Pascal compiler:

@smallexample
% make LANGUAGES=pascal
@end smallexample

(Just @samp{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.:
@samp{make CFLAGS="-O2" RTSFLAGS=-Wall}

@item
When everything compiles, you can verify what the
@samp{make -n pascal.install} command does, and if you are satisfied run
it without the @samp{-n} option to install the compiler @file{gpc1}, front
end @file{gpc}, run time system @file{libgpc.a} to the same place where
@file{gcc} was installed. This installation process does @strong{not}
overwrite existing copies of @file{libgcc.a} or @file{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.

@end enumerate


@c -------------------------------------------------------------------------


@node compilation notes
@section Configuration dependent compilation notes
@cindex configuration dependent compilation notes
@menu
* Alpha OSF/1::      Installation on an Alpha OSF/1 system.
* MS-DOS: DJGPP.     The DJGPP port of GNU compilers to MS-DOS.
* MS-DOS, OS/2: EMX. The EMX port of GNU compilers to MS-DOS and OS/2.
* Windows 95/NT::    Installation on a Windows 95/NT system.
@end menu


@c -------------------------------------------------------------------------


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

@smallexample
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>)
@end smallexample

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 @file{version.c}
and @file{rts/version.c} files, which need to be recompiled with
@samp{ALPHA_BUG} defined.

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


@c -------------------------------------------------------------------------


@node DJGPP
@subsection MS-DOS with DJGPP
@cindex djgpp
@cindex DOS, MS-
@cindex MS-DOS

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 @samp{simtel.coast.net} and it has mirrors all over the world.
The @samp{configure} script is replaced by an MS-DOS batch file called
@samp{configure.bat} wich does essentially the same. Detailed instructions
are in the file @file{config/msdos/README.dj} of the GNU Pascal source
distribution.


@c -------------------------------------------------------------------------


@node EMX
@subsection MS-DOS or OS/2 with EMX
@cindex EMX
@cindex DOS, MS-
@cindex MS-DOS
@cindex OS/2

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 @samp{ftp} on the server
@samp{ftp.uni-stuttgart.de} in the directory @samp{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.)

@enumerate 1

@item 
Unzip the source for GCC from the root directory, and rename the
resulting directory @samp{gcc-2.7} to @samp{gpc}.
@smallexample
  cd \
  unzip c:\gccsrc1
  unzip c:\gccsrc2
  unzip c:\gccsrc3
  ren \emx\gnu\gcc-2.7 gpc
@end smallexample

@item 
Unzip the source for GPC from the @samp{emx\gnu} directory, so it will
go into the gpc subdirectory.  Unlike other EMX sources, the
GPC source must @strong{not} be extracted from the root directory.
@smallexample
  cd \emx\gnu
  unzip c:\gpc-21s.zip
@end smallexample

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

@item
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 @samp{ftp} archives, e.g.@:
@samp{hobbes.nmsu.edu} in the @samp{/pub/os2/unix/dev} directory.
Make sure you rename @samp{patch.exe} to a filename that won't 
conflict with the built in OS/2 patch command.  EM recommends using
@samp{lwpatch.exe} in his @samp{\emx\doc\build.doc} file.

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

@item
Compile GPC using the @samp{compile.cmd} script.
@smallexample
  cd \emx\gnu\gpc\p
  compile
@end smallexample

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

@end enumerate

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.


@c -------------------------------------------------------------------------


@node Windows 95/NT
@subsection Windows NT and Windows 95 with cygwin32
@cindex Windows NT
@cindex Windows 95

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 @file{ftp://ftp.cygnus.com/pub/gnu-win32/} Don't use gcc
sources from the cygwin32 distribution. These are not just modified from
FSF @file{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.

@ignore

This is no longer true.  Someone interested to take over the CygWin
part of the project? -- PG

Instead, apply @file{config/cygwin32/gcc-2.7.2.1.cygwin32-beta17.diff}
to FSF @file{gcc-2.7.2.1} to add cygwin32 platform support to GCC.
The GNU pascal sources already have the cygwin32 support, so no further
patching of gpc is needed

@end ignore

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. @xref{Crossbuilding}


@c -------------------------------------------------------------------------

@node cross-compilers
@section Building and Installing a cross-compiler
@cindex cross-compilers

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, 
@samp{ftp://ftp.cygnus.com/pub/embedded/crossgcc/} is the place to be.

@itemize @bullet
@item
Cross-compilers for the Mips as target using the Mips assembler
currently do not work, because the auxiliary programs
@file{mips-tdump.c} and @file{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.

@item
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.

@item 
Cross-compilation between machines of different word sizes is
somewhat problematic and sometimes does not work.
@end itemize

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.

@menu
* Steps of Cross::      Using a cross-compiler involves several steps
                        that may be carried out on different machines.
* Configure Cross::     Configuring a cross-compiler.
* Build Cross::         Actually building a Pascal cross-compiler.
* Crossbuilding::	Crossbuilding a Pascal compiler.
@end menu

@c -------------------------------------------------------------------------

@node Steps of Cross
@subsection Steps of Cross-Compilation

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

@itemize @bullet
@item
Run the cross-compiler on the host machine to produce assembler files
for the target machine.  This requires header files for the target
machine.

@item
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.

@item
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 @file{crt@dots{}.o}) for the target machine.
@end itemize

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.

@c -------------------------------------------------------------------------

@node Configure Cross
@subsection 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:

@smallexample
% ../gcc-2.8.1/configure --prefix=/usr --target=i386-go32
@end smallexample

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.

@c -------------------------------------------------------------------------

@node Build Cross
@subsection 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 @samp{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:

@example
--------------------------------------------------------------------------
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 @samp{make} to build the compiler and runtime system.
@end example

Building a cross-compiler requires cross-binutils for your target,
i386-go32 in this examples. If @file{configure} is not able to find
@file{i386-go32-ar} and/or @file{i386-go32-ranlib}, you may have to run it
again with again with @code{--with-ar=@var{your-cross-ar}} or
@code{--with-ranlib=@var{your-cross-ranlib}} switches.

Then, @samp{make} and @samp{make install} the cross-compiler like you would
for a native configuration.

@c -------------------------------------------------------------------------

@node Crossbuilding
@subsection Crossbuilding a compiler.

Yet another possibility is @var{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:

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

Build it:

@smallexample
% make CFLAGS=-O2 LANGUAGES=c
@end smallexample

Now, configure and build GPC. The output of @file{configure} should look
like:

@example
--------------------------------------------------------------------------
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 @samp{make} to build the compiler and runtime system.
@end example

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

A cross-built compiler must be installed by hand.


@c -------------------------------------------------------------------------


@node binary distributions
@section Installation instructions for a GPC binary distribution
@cindex binary distributions, installing
@cindex installing binary distributions

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, @samp{cd}
the the appropriate directory (usually @samp{\} for EMX, @samp{\DJGPP}
for DJGPP), then type

@smallexample
  C:\> pkunzip -d @var{archive}
@end smallexample

where @var{archive} is the name of the distribution file.  To install a
@file{.tar.gz} archive under a UNIX compatible system, become root, then
extract the archive from the root of the filesystem:

@smallexample
  # tar xzf @var{archive}.tar.gz
@end smallexample

If you are using a @samp{tar} utility other than GNU tar, it might be
necessary to do the above in two steps:

@smallexample
  # gzip -d @var{archive}.tar.gz
  # tar xf @var{archive}.tar
@end smallexample

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

