See file INSTALL for the list of software requirements and
installation instructions.  See file PROBLEMS if installation turns
out to be difficult.

oo2c translates Oberon-2 source code into a variant of C supported by
the gcc family of compilers.  It uses a variant of SSA for its
intermediate representation, and performs common optimizations like
common subexpression elimination, invariant code motion, constant
propagation, algebraic transformations, and dead code removal.  The
compiler relies on Boehm's gc for garbage collection.  A summary of
the user visible changes from oo2c-1.5.9 to oo2c-2.0.x can be found in
directory doc/from-v1-to-v2/.

Operating system, architecture, and gcc combinations that are known to
work:

  Linux 2.4.19/i386/gcc 2.95.4 & 3.2.1
  Linux 2.6.7/x86 and x86-64/gcc 3.4.1
  SunOS 5.6/sparc/gcc 2.95.2 (32 bit)
  SunOS 5.8/sparcv9/gcc 3.2.1 (64 bit)
  Mac OS X/G3/gcc 2.95.2
  Windows 2000/i386/cygwin gcc 2.95.3-5

Starting with oo2c-2.0.11, there is an interface for POSIX threads.
For this to work, both the garbage collector and oo2c must be build
with `--enable-threads=pthreads'.  You can check that threading works
by running the program src/TestThread.Mod.  If it completes without
crashing or failed assertions you can be fairly sure that
synchronization, exceptions, and heap management work as expected.
See lib/src/liboo2c.Mod for some caveats regarding threading and other
library modules.  Threads have been tested with Debian 3.0 (Linux 2.4,
glibc 2.3.1, gc6.0+ and gc6.2) and Solaris 2.6 (gc6.2).



Typical installation is quite simple:

  tar xfvj oo2c_32-2.0.0.tar.bz2
  cd oo2c_32-2.0.0
  ./configure --prefix ~/mydir
  make install

For a fast and small installation, you can do

  env OFLAGS="--no-rtc" CFLAGS="-O2 -pipe" ./configure  --prefix ~/mydir
  make install-strip

More information is available in INSTALL.


Building programs is simple as well:

  mkdir /tmp/test
  cd /tmp/test
  mkdir src
  cat >src/T.Mod
    MODULE T;
    IMPORT Out;
    BEGIN
    Out.String("Hello");Out.Ln;
    END T.
  ~/mydir/bin/oo2c --make T

And then `bin/T' should say `Hello'.  For more information, please
refer to the man page of oo2c.

Please use Sourceforge

  https://sourceforge.net/tracker/?atid=103539&group_id=3539

to report bugs and include the version you are using in the summary
line.  This ensures that bug reports are not lost, and provides a
convenient central location to collect information about bugs.

For miscompiled code, that is, correct input code that produces a
broken binary, please try to create a small program that will
reproduce the error.  Ideally this program is a single module with
just enough lines of code to trigger the bug.  Send me this module,
together with the information on how the bug manifests itself, how to
trigger the bug, and the version of oo2c you are using.

For input modules that hang or crash the compiler, please send me the
module or modules that trigger the problem.  This does not need to be
small.  Don't send me module fragments!  Getting fragments into shape
for the compiler to compile takes time that I would rather spend on
debugging.

Reporting about bugs can be a surprisingly difficult excercise in
communication.  There is a very nice essay "How to Report Bugs
Effectively" at http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
It should be recommended reading for everyone who will ever write --
or read -- a bug report.


Build and Install Using a CVS Working Copy
==========================================

To install a compiler from the bleeding edge CVS sources, you need to
have the latest file release compiler installed.  Then, using this
baseline compiler, create a bootstrap compiler from the CVS sources.
Finally, run "make install" with the bootstrap compiler.

Here are the recommended steps in detail.  First, the usual setup:

  ~/sf-ooc/ooc2$ make cvsclean
  ~/sf-ooc/ooc2$ cvs update -d
  ~/sf-ooc/ooc2$ ./configure --prefix /tmp/test

Then create a compiler binary bin/oo2c from the current sources
(~/local-ooc2/bin/oo2c is the local installation of the latest file
release in this example):

  ~/sf-ooc/ooc2$ . ENV
  ~/sf-ooc/ooc2$ make $OOC_DEV_ROOT/oo2crc-install.xml
  ~/sf-ooc/ooc2$ ~/local-ooc2/bin/oo2c -M --config oo2crc-install.xml oo2c

Use bin/oo2c to do "make install":

  ~/sf-ooc/ooc2$ make install BOOTSTRAP_COMPILER=bin/oo2c

This installs the compiler's data under the configured prefix,
`/tmp/test' from the call to ./configure above.


How to Create a Patch
=====================

To create a patch file relative to the current state of the CVS, first
eliminate all derived files in the local working copy:

  make cvsclean

Update the working copy to the current head of the CVS:

  cvs update -dP

Resolve conflicts caused by the update (if any) and run the diff
command:

  cvs diff -u >../mypatch

If "diff -u" does not work use "diff -c" as fallback.  The resulting
file can be applied with "patch -p0 <file".


-- Michael van Acken <mva@users.sf.net>

Using OOC under Mac OS
======================

This document describes options for using OOC on Apple Macintosh operating
systems.

OOC works under Darwin, Apple's open-source operating system based on 4.4BSD.
OOC also works under OS X, which is based on Darwin. Earlier versions of Mac OS
are not supported.

OOC requires the GNU C compiler (gcc) which is available as part of the
"Developer Tools" package available from Apple.

Issues:
======

1) Apple's distribution of gcc defaults to ANSI with precompiled headers. OOC
requires GNU extensions. Precompiled headers often go wrong. The
"-no-cpp-precomp" option must be specified to gcc.  This seems to fix both
problems.

2) OOC requires Hans Boehm's conservative garbage collector. Until version 6.2,
there were issues with dynamic loading and thread safety under Darwin. Also,
earlier versions of the GC would only work reliably on specific versions of OS
X. Users should install version 6.2 or later. If using threads, the argument
"-DGC_DARWIN_THREADS" must be specified, both to build the GC and to build any
clients of the GC library.

3) Apple supplies a version of libtool which is incompatible with the standard
GNU libtool. OOC may detect this version, but it will not work. For dynamic
library support, users should install GNU libtool. This is available as part of
the "Fink" project (fink.sf.net). Alternatively, dynamic linking can be
disabled by specifying "--disable-libs" during configuration.

Installation:
============

- Install the developer tools from developer.apple.com. Download is free for
  ADC (Apple Developer Connection) members. Free membership of ADC is
  available. Developer tools are also available on CD.

- Install version 6.2 (or later) of the GC. Specify "-DGC_DARWIN_THREADS" if
  using threads.

- If dynamic library support is required, install glibtool.

- Follow the regular instructions. Common configurations are outlined below.

  For static linking:
    env "CFLAGS=-O2" "CPPFLAGS=-no-cpp-precomp" ./configure --disable-libs

  For dynamic linking:
    env "CFLAGS=-O2" "CPPFLAGS=-no-cpp-precomp" ./configure

  For dynamic linking with threads:
    env "CFLAGS=-O2" "CPPFLAGS=-no-cpp-precomp -DGC_DARWIN_THREADS" \
      ./configure --enable-threads=pthreads

Problems?
========

1) While linking, the compiler complains about undefined GC_pthread_sigmask?
   Make sure that you specify "-DGC_DARWIN_THREADS" in CPPFLAGS when
   configuring OOC.

2) You installed programs or libraries with "Fink", but OOC cannot find them?
   Fink does not install its components in the regular places (eg. /usr/local)
   so the default searches will not work. As documented by Fink, you should
   set the symbols CFLAGS, CXXFLAGS, CPPFLAGS and LDFLAGS to point to your
   Fink installation. Normally, this is done in .cshrc using:
     setenv CFLAGS -I/sw/include
     setenv LDFLAGS -L/sw/lib
     setenv CXXFLAGS $CFLAGS
     setenv CPPFLAGS $CXXFLAGS
     source /sw/bin/init.csh

-- Stewart Greenhill <sgreenhill@users.sf.net>

Using OOC under Win32
=====================

This document describes options for using OOC on Windows systems.

Currently, OOC requires the GNU C compiler (gcc). There are a couple of
implementations of gcc under Windows:

1) Mingw32  (www.mingw.org)
2) Cygwin   (www.cygwin.com)

Mingw32 is a "minimalist" implementation of gcc for Win32 systems. Mingw32
applications link to Microsoft's own C run-time library (MSVCRTL.DLL),
which is installed as part of every Windows system. Some features of
Mingw32:
- Mingw32 environment is compact.
- Mingw32 applications are compact.
- Run-time library functions have "Windows" semantics.
- Some "Unix" functionality is not available.

Cygwin is an implementation of the Unix API for Windows. Cygwin
applications use GCC's run-time library as well as additional "emulation"
functions in a separate library (CYGWIN.DLL). Some features of Cygwin:
- Cygwin environment is very large.
- Cygwin applications require an additional large DLL.
- Run-time library functions have "Unix" semantics.
- Cygwin is only free for GPL code. Use with non-GPL code requires a
  special contract with the vendors.

In many cases, Unix source code can run unmodified under Cygwin. Cygwin is
typically distributed with a large collection of Unix utilities, including:
- C compiler
- Bash shell
- ssh and cvs
- XWindows client libraries
- XWindows server
- inetd and friends (supporting ftp and telnet into Windows systems).

In addition, Cygwin supports the generation of Mingw applications via the
"-mno-cygwin" option.

OOC supports the following options:

- Cygwin
- Mingw stand-alone  (with MSYS)
- Mingw under Cygwin

Note: Some of these configurations have not been extensively tested. Please
report any problems.

Path virtualisation
===================

The C compiler and associated utilities are Unix applications that have
been ported to run under Windows. Unix applications cannot be allowed to
see DOS file names, or they would fail to handle files properly. Each
application has its own file management procedures that assume Unix syntax.
To port such applications to Windows, the run-time environment MUST map all
DOS file paths to Unix syntax.

Applications compiled with Cygwin will see Unix-style paths. Applications
compiled with Mingw (or -mno-cygwin under Cygwin) will see Windows paths.

OOC will see different styles of paths according to which environment is
has been compiled under. However, the C compiler always sees virtual Unix
paths. For OOC and gcc to play nicely together:

  It is ESSENTIAL that OOC and gcc SEE THE SAME PATHS TO SOURCE FILES.

Keep this in mind when installing the system.

Note that OOC does not quote file names that are passed as arguments to the
C compiler, so:

  PATHS TO SOURCE FILES MAY NOT INCLUDE WHITESPACE.

This may be an issue on Windows systems, in which the user's default working
directory is called something like "Documents and Settings/myname". To use OOC
under Windows, you will need a working directory that does not have spaces in
its name (eg. C:/users/myname").

Note that OOC uses an absolute path to name the "install" program. This means
that the path detected by "configure" may not be usable by the generated
compiler under mingw. To remedy this problem, specify the absolute path using
the INSTALL environment variable.

Installing the GC
=================

To do any serious work with OOC, you will need to install a garbage collector.
This is a separate library used by the compiler and OOC applications for
memory management. OOC uses Hans Boehm's GC, available here:
  http://www.hpl.hp.com/personal/Hans_Boehm/gc/

Follow the installation instructions for the GC. The following discussion
applies for modern releases. It is recommended to use at least version
6.3alpha2.

1) Build the GC library.

  ./configure
  make

2) Ensure that the GC is working correctly.

  Under Cygwin:
    make gctest
    ./gctest

  Under MingW32, the test application is a Win32 application and writes its
  output to a file "gc.log" rather than standard output.
    make gctest.exe
    ./gctest
    cat gc.log

3) Install the GC library

  make install

4) Review possible configuration settings for OOC

Path issues:

  Unless you specify another location to "configure" via the --prefix option,
  the libraries will be installed in /usr/local/{lib,include}. Depending on
  your local settings, this may not be the C compiler's search path. To ensure
  that OOC finds the GC, you may need to use these settings:
    CPPFLAGS=-I/usr/local/include
    LDFLAGS=-L/usr/local/lib
  It appears that these are necessary for MingW32/MSYS.

Threading issues:

  Versions of the GC differ in how threads are handled under Win32.

  For modern releases of the GC, "configure" builds a threaded GC under
  MingW32. This requires locks to be statically allocated by the GC. Under
  Win32, this only works correctly if client code defines the symbol:
    GC_WIN32_THREADS

In summary, for MingW32/MSYS the following options are likely to be required
by the GC in order to build OOC:
	"CPPFLAGS=-I/usr/local/include -DGC_WIN32_THREADS" \
	LDFLAGS=-L/usr/local/lib

Installation
============

1) Make a directory `c:\usr\local\src', and extract the oo2c files here.

2) Under MSYS or Cygwin, ensure that `c:\usr\local' is mapped to the
   logical path `/usr/local'. Normally, one would do:

     mount c:/usr/local /usr/local

   If you encounter problems with the "mount" tool, see additional comments
   below.

3) `cd' to the directory containing the compiler source code.

4) Configure the package.

    For Cygwin:

      env CFLAGS=-O2 ./configure --disable-libs


    For stand-alone Mingw32 (adjust path to "install.exe"):

	  env \
	    "INSTALL=c:/msys/1.0/bin/install.exe" \
	    LDFLAGS=-L/usr/local/lib \
	    CFLAGS=-O2 \
		"CPPFLAGS=-I/usr/local/include -DGC_WIN32_THREADS" \
        ./configure --disable-libs

    For Mingw32 under Cygwin:

	  env CPPFLAGS=-mno-cygwin CFLAGS=-O2 LDFLAGS=-mno-cygwin \
	    ./configure --disable-libs

      (depending on path settings, INSTALL path may be required as above)

5) Type `make' to compile the package.

6) Type `make install' to install the programs and any data files and
   documentation.  `make install-strip' will additionally remove any
   debug information from the installed executables.

7) You can remove the program binaries and object files from the
   source code directory by typing `make clean'.  To also remove the
   files that `configure' created (so you can compile the package for
   a different kind of computer), type `make distclean'.

Problems?
=========

1) In at least one version of MSYS it looks like the "mount" tool is
   broken.  If you keep getting "Function not implemented", you may need to
   manually edit the MSYS fstab file (eg. C:\MSYS\1.0\etc\fstab). It should
   look something like this:

     c:/MinGW /mingw
     c:/usr/local /usr/local

   Note that MSYS must be restarted for any changes to take effect.

2) OOC couldn't find "install" during "make install"? Depending on path
   settings, the detected path to "install" may not be valid for mingw
   executables. See the explanation in "Path Virtualisation" and try setting
   the INSTALL path before running "configure". For a quick fix, manually
   adjust the "install" entries in the generated "rsrc/OOC/oo2crc.xml" and
   re-run "make install".

3) While building OOC under MingW32, stage0/oo2c crashes abruptly? Most likely
   you have a threaded GC, and have not defined "-DGC_WIN32_THREADS" during
   configure. The crash is due to an uninitialised mutex in the GC. See
   the section "Installing the GC".

4) You installed the GC under MingW32, but OOC did not find it? By default
   mingw32/MSYS does not search in /usr/local/{lib,include} where the GC is
   normally installed. You will need to explicitly specify these locations
   to the compiler via the LDPATH and CPPFLAGS environment variables. See
   the section "Installing the GC".

5) You have installed both cygwin and mingw32 toolchains, and the C compiler
   is behaving strangely? Take care that you have the correct search paths
   configured. As a general rule, you should not allow the MSYS shell to see
   the cygwin compiler, and vice versa. The object files generated by the two
   compilers are similar, but depend on different run-time libraries. If the
   compiler sees the wrong object files at link-time you can expect to see
   many undefined symbols.

Platform-specific issues
========================

This section discusses features of OOC relevant to the Win32 platform.

- Alignment. Many Win32 structure specify particular alignments. OOC
  provides the following record flags to control the alignment of fields
  within a record: ALIGN1 ALIGN2 ALIGN4 ALIGN8

  Example:

    tagMCI_WAVE_OPEN_PARMSA_struct* = RECORD [ALIGN1]
      dwCallback* : DWORD;
      wDeviceID* : MCIDEVICEID;
      lpstrDeviceType* : LPCSTR;
      lpstrElementName* : LPCSTR;
      lpstrAlias* : LPCSTR;
      dwBufferSeconds* : DWORD
    END;

- Calling Conventions. Most functions in the Win32 API are declared to use
  "Pascal" (or "stdcall") calling convention. For Pascal calls, the callee
  removes any parameters from the stack before returning from the
  procedure.  In "C" calling convention (or "cdecl"), the caller removes
  the parameters which permits the use of variable argument lists.

  The "fastcall" calling convention is implemented by Microsoft's C compiler as
  well as recent versions of GCC. Specifying "Fastcall" causes arguments to
  functions to be passed in registers "where possible". For the x86, the first
  two LONGINT or smaller arguments are passed (left to right) in the ECX and
  EDX registers; all other arguments are passed right to left on the stack. The
  callee removes arguments from the stack. On modern machines, the speed
  benefits of fastcall are probably negligible, but it is occasionally used in
  third-party application binary interfaces (ABIs) so it is included here for
  compatibility with these libraries.

  OOC allows calling convention to be specified in both Module declarations
  and procedure declarations. For example, an interface module for a Win32
  library is usually declared "Pascal":

    MODULE WinApi [ INTERFACE "Pascal";
      LINK LIB "kernel32"; LIB "user32"; LIB "gdi32" END];

  Procedures or procedure types declared within the interface module will
  inherit the specified calling convention.

    WNDPROC* = PROCEDURE (p0 : HWND;
	   p1 : UINT; p2 : WPARAM; p3 : LPARAM) : LRESULT;

  In the above example, WinApi.WNDPROC inherits the "Pascal" convention
  declared in the module header.  Exceptions from the module convention may
  be declared per procedure. For example:

    PROCEDURE wsprintfA* [ "C" ] (p0 : LPSTR; p1 : LPCSTR; ...) : LONGINT;

  Regular Oberon-2 modules use the default calling convention, which is
  compatible with "C". Oberon-2 functions to be used as Win32 call-backs
  must therefore be explicitly declared "Pascal". For example:

    IMPORT W := WinApi;

    PROCEDURE MessageHandler ["Pascal"] (wnd : W.HWND;
      msg : W.UINT; wParam : W.WPARAM; lParam : W.LPARAM) : W.LRESULT;

- C string assignment. Libraries written for the "C" language generally
  represent text strings using the "char *" data type. The Oberon-2
  equivalent is "POINTER TO ARRAY OF CHAR", which is not normally
  compatible with Oberon strings types. The CSTRING pointer flag specifies
  that "C"-style string assignments should be permitted. The following are
  fragments from the Win32 API.

    PCHAR* = POINTER [ CSTRING ] TO ARRAY OF CHAR;
	...
    LPCSTR* = PCHAR;
	...
    PROCEDURE MessageBoxA* (hWnd : HWND;
	  lpText : LPCSTR; lpCaption : LPCSTR; uType : UINT) : LONGINT;

  The declaration of WinApi.MessageBoxA allows strings or character arrays
  to be passed as the second and third parameters. For example:

    IMPORT W := WinApi;

    PROCEDURE TestMessage;
    VAR result : LONGINT;
    BEGIN
      result := W.MessageBoxA(0, "Hello!", "This is a test Message", 0);
    END TestMessage;

    PROCEDURE MessageBox(title, message : ARRAY OF CHAR);
	VAR result : LONGINT;
	BEGIN
	  result := W.MessageBoxA(0, title, message, 0);
	END;

Implementation Issues
=====================

1) File rename.

Windows file semantics do not allow open files to be renamed, or files to
be renamed over existing files. Cygwin emulates Unix behaviour, but not on
Win9X platforms.

- Files.File.Register uses unlink/rename/re-open

- IO:FileChannel uses the Win32 kernel function MoveFileEx to guarantee an
  atomic rename operation. It is not clear which versions of Windows
  support MoveFileEx.

2) ftruncate()

The ftruncate function is unavailable under Windows. This means that
PosixFileDescr.Truncate will always return an error.

3) Windows networking.

Windows networking functions are in a separate library, WSOCK32.DLL, which
is included if the relevant IO modules are used.  The networking library is
configured as part of the initialisation for module IO:Socket. Note that
Windows sockets are not file descriptors and require a separate set of
functions to operate. For portable code, IO:SocketChannel should always be
used for sockets.

4) system()

There are many issues associated with the system() run-time function.
Under Unix, system() calls the Unix shell as its command interpreter.
Under windows, system() calls the Windows command interpreter. These
interpreters differ in their syntax and semantics. In addition, the
Microsoft C start-up code has its own rules for interpreting the command
line.

There appear to be some limitations in the Windows command interpreter that
prevent OOC passing long command lines to the C compiler (eg. as are
required for static linking). Therefore, OS:ProcessManagement.system does
not use the run-time library system() command. Instead, the command-line is
passed directly to the command using the Win32 kernel CreateProcess
function. This means that it is not possible to:
- use piping redirection with a system command
- specify substitutions using environment variables

An option exists to use an external shell `/bin/sh' for the system command.
This can be enabled by defining USE_SHELL in lib/src/OS/ProcessManagement.c.
With an external shell, such as `bash' installed in `C:\bin', system()
behaves the same as the Unix system() call. This configuration is necessary
to use the test framework from the OOC CVS repository.

-- Stewart Greenhill <sgreenhill@users.sf.net>