*************************************************************************
*                                                                       *
*  mpC Programming Environment                                          *
*  ===========================                                          *
*                                                                       *
*                                                                       *
*  Copyright (c) 1996,97,98,99 Institute for System Programming,        *
*                              Russian Academy of Sciences.             *
*                                                                       *
*  All rights reserved. We assume no responsibility for the use         *
*  or reliability of our software.                                      *
*                                                                       *
*************************************************************************


Direct requests, comments, questions, and error reports to:

   Alexey L. Lastovetsky
   Institute for System Programming, Russian Academy of Sciences,
   25, Bolshaya Kommunisticheskaya str., Moscow 109004, Russia
   Phone: 7(095) 912-0754
   Fax  : 7(095) 912-1524
   Email: lastov@ispras.ru

or to mpC Group:

   Email: mpc@ispras.ru


The mpC software is available from:

http://www.ispras.ru/~mpc


The file tree is compressed: tar and gzip are used (suffix: .tar.gz)

To uncompress the file tree use:

   gzip -d mpcc-X.Y.Z.tar.gz
   tar xvf mpcc-X.Y.Z.tar

where X.Y.Z stands for the installed version of the mpC system
(say 1.2.3, 2.0.2 or 2.0.3)

The directory 'mpcc-X.Y.Z' will be created; execute

   cd mpcc-X.Y.Z

The subdirectories of mpcc-X.Y.Z and their contents are as follows:

directory       contents
------------------------------------------------------------------------
README          this file
install_mpc     installation script
Troubles	description of the installation problems
doc             documentation in postscript format
man             manual pages
front           front-end of the compiler
back            back-end of the compiler
reuse           reusable modules (needed for front-end)
rts             run-time system
env             environment sources (.c-files and shell scripts)
h               header files
tests		mpC source files, subdirectories and makefiles for
		testing mpC compiler and environment 

Machine Dependencies:
---------------------

Most machine dependent code is isolated in the file System.c. This file
is a part of Karlsruhe Toolbox for Compiler Construction ("Cocktail") used
when constructing the compiler. This file is written in C and is located
in the directory 'reuse'.


Platforms:
----------

The mpC programming environment has been installed on SPARCstations
running Solaris 2.3/2.4/2.5 and SunOS 4.1.3, on HP9000 running
HP-UX 9.07, on PC running Linux (Red Hat Linux 4.0) or FreeBSD 3.0,
and on DEC Alpha running OSF1 V3.2.

If you got problems during installation on another platform, please,
send your comments to mpC Group.


Before Installation:
--------------------

MPI should be installed before the installation of the mpC environment.

NOTE: this version of the mpC programming environment works correctly for
      two implementations of MPI - LAM and MPICH. The mpC programming
      environment was implemented using LAM MPI version 6.0 and
      tested using LAM 6.0/6.1 and MPICH 1.0.13. If you have another MPI
      implementation or another version of LAM or MPICH, the installation
      and usage of mpC programming environment may cause problems.
      All MPI dependent code is isolated in subdirectories 'env' and 'rts'.

Make sure that your C compiler compiles ANSI C; some commercial compilers
need options to specify ANSI C conformance. So, you may use
SPARCworks(TM) Professional C to compile the mpC software, but you should 
specify one of the options -Xc or -Xa.

All files in subdirectories 'env' and 'rts' are compiled by MPI C compiler;
make sure that the directory, where this compiler is placed (that is,
$MPIDIR/bin), is in PATH.

The mpC compiler uses standard preprocessor cpp. You should specify the
directory where cpp is placed when editing Makefile. We recommend to use
GNU cpp. Environmental variable MPCPREPDIR also may be determined before
or after installation; in this case the mpC compiler will use
$MPCPREPDIR/cpp instead of previously specified cpp.

The full installation procedure consists of 4 steps, one of which
(run_test) tests the mpC programming environment installed by means of
creating a simple virtual parallel machine and executing a few mpC
programs. To succeed this step, the user should determine environmental
variables WHICHMPI, MPCHOME, MPCTOPO and MPCLOAD (See 'The Environmental
Variables' below). In addition, it is necessary to add $MPIDIR/bin,
$MPIDIR/lib, $MPCHOME/bin and $MPCLOAD to PATH and $MPIDIR/lib, 
$MPCHOME/lib to LD_LIBRARY_PATH (or to LPATH on HP and so on).


Installation:
-------------

To compile all the programs execute:

shell$ ./install_mpc

To clean up:

shell$ make clean

to remove object files and executables from source directories.

To uninstall mpC

shell$ ./uninstall

To check the integrity of the compiler (mpcc) execute:

   make test

This command will compile test programs in subdirectory 'tests',
recompile the mpC compiler with itself and produce 'mpcc1', recompile test
programs with 'mpcc1', and compare codes produced by 'mpcc' and 'mpcc1'.
No error mesages must be produced during recompilation, but some
warnings are possible; 'mpcc' and 'mpcc1' must produce identical code.

To install the programs execute:

   make install

NOTE: You may install 'mpcc1' instead of 'mpcc' (if you want); to do it,
      copy mpcc1 to the mpC source directory by command
      'cp tests/selftest/mpcc1 ./mpcc', and then type 'make install'.

After the installation completes, execute

   make run_test

to create a simple virtual parallel machine ('test_machine') and
execute several mpC programs on 'test_machine'.

NOTE: in this version you may execute this step ONLY if you use LAM MPI
      because these test programs are developed for LAM, and MPICH can't
      support such a large computing space on a single workstation needed
      for most of the tests.

Type

   make clean

to remove object files and executables from source directories.


Troubles During Installation:
-----------------------------

Ignore any warnings appearing during compilation, they are normal.
Any other compilation errors may be because of either bugs in your
C compiler or its incompatibility with ANSI C. Some compilers fail to
compile the mpC software because of specific limitations. We recommend
GNU C compiler.

Error diagnostics produced by the mpC compiler at step 'test' may appear
because of incompatibility of your C compiler and/or preprocessor with the
mpC compiler; errors in system headers are also possible.

For more details, read file 'Troubles'.


How to use the mpC programming environment:
-------------------------------------------

The mpC programming environment is developed to execute mpC programs on
disributed memory machines (DMM). Currently, DMM is a local network of
workstations (including PCs running LINUX and/or FreeBSD); to execute an mpC 
program on more than one workstations, the user should:
a) be an authorized user with the same name on each of workstations
   constituting user's DMM;
b) be able to execute rsh on each workstation (make sure that file
   .rhosts is placed in his home directory on each workstation
   and contains the names of all the workstations constituting the DMM);
c) have the mpC programming environment installed in directory $MPCHOME
   (this directory may be shared by different users and may be mounted);
   if his local network is heterogeneous, the user should have a separate
   copy of the mpC programming environment installed on each platform;
d) determine environmental variables WHICHMPI, MPIDIR, MPCHOME, MPCTOPO
   and MPCLOAD of his shell on each of workstations constituting the DMM
   (by editing files like .cshrc, .bashrc and so on in his home directory
   on each workstation); in addition, environmental variable MPCPREPDIR
   may be determined on each workstation used for compilation of mpC
   programs;
e) create YOUR OWN (!) directories $MPCLOAD, $MPCTOPO and $MPCTOPO/log
   on each workstation; you should have write access to these directories;
f) add directories $MPIDIR/bin, $MPIDIR/lib, $MPCHOME/bin and $MPCLOAD
   to PATH, and $MPIDIR/LIB, $MPCHOME/lib to LD_LIBRARY_PATH (or to LPATH 
   on HP, ...) on each workstation. 


Environmental Variables:
-----------------------

Environmental variables WHICHMPI, MPIDIR, MPCHOME, MPCTOPO and MPCLOAD
should be determined before the usage of the mpC environment for correct
compilation and execution of mpC programs.

Environmental variable WHICHMPI should be
a) LAM, id you use a LAM implementation of MPI;
b) MPICH_P4, if you use a MPICH implementation of MPI configured with the
   ch_p4 communication device;
c) MPICH, if you use a MPICH implementation of MPI configured with any
   valid communication device not having to be ch_p4.

$MPIDIR is the directory, where MPI is placed. When using LAM, it may be
needed to determine environmental variable TROLLIUSHOME setting it to
the same value as MPIDIR.

$MPCHOME is a directory where the mpC programming environment was installed.

$MPCTOPO is a directory where files describing virtual parallel machines
(VPMs) must be placed; each user should have his own $MPCTOPO directory. 

$MPCLOAD is a directory for user's applications; each user should have his
own $MPCLOAD directory.

See mpC User's Guide for more details.
