Scotch 5.0 installation instructions
====================================


1) Mandatory tools
------------------

In order for you to compile Scotch and/or PT-Scotch, you must have GNU
Make, Lex and Yacc installed on your system, as well as an
implementation of the MPI message-passing library in the case of
PT-Scotch. There is a possibility to install Scotch without having Lex
or Yacc, but it may require the tuning of sample Flex and Bison (i.e.,
the GNU equivalents of Lex and Yacc) outputs created on a Linux
system, which may need some tricky work to compile on other systems,
because of different C library implementations.

To check if GNU Make is installed and is found first, please
type :

%prompt% make --version

It should read:
% GNU Make x.xx
% Copyright (C) 20xx  Free Software Foundation, Inc.
etc, etc.

Alternatively, if GNU Make is installed but its directory does
not appear first in the PATH variable that is searched for
executables, you can try to locate it using the which command :

%prompt% which make

If several occurences of make are found, one might be GNU Make,
so try to figure out which of them.

To see if lex and yacc are present, type
%prompt% which lex
%prompt% which yacc    (or "bison", the GNU flavor of yacc)

If some of these are missing, please :
- check your path variable (just in case they are located in
  some unusual place, such as /usr/local/bin, /opt/bin,
  /opt/local/bin/, /opt/gnu/bin, etc). Tools such as "which",
  "locate" or "find" may help you find them;
- ask your system administrator (highly recommended);
- install a copy of GNU Make of your own (less recommended,
  please ask your system administrator first). GNU Make is
  available from the FSF website, at :
  http://www.gnu.org/software/make/ and
  http://ftp.gnu.org/pub/gnu/make/ .
  A GNU version of lex and yacc is also available from the
  very same FSF website, at :
  http://www.gnu.org/software/flex/
  http://ftp.gnu.org/non-gnu/flex/
  http://www.gnu.org/software/bison/
  http://ftp.gnu.org/pub/gnu/bison/ ;
- use the "last resort" files placed in a directory judiciously
  called "last_resort", located in subdirectory "src/libscotch".
  These files are :
  . parser_ll.c
  . parser_ly.h
  . parser_yy.c .
  They should be copied in the directory where object files are
  created, and "touch"ed so that their modification date is more
  recent than the ones of the corresponding "parser_ll.l" and
  "parser_yy.y" files. Then cross your fingers and hope it
  compiles properly on your system. Else, you will have to dig in
  their code to have them compile properly...
  The Makefile of the libScotch library has been designed so as
  to copy the last_resort/* files automatically when the lex or
  yacc tools are not found.


2) Configuration
----------------

Go to the "src/" directory.

Look in the "Make.inc/" subdirectory for a configuration
file which matches your system configuration. If there
is none, build a proper one in the "Make.inc/" subdirectory,
basing on the structure of existing ones.

Create a symbolic link from the configuration file to the
current "src/" working directory, renaming it as "Makefile.inc":

%prompt% ln -s Make.inc/Makefile.inc.xxxx_xxx_xxx Makefile.inc

If symbolic links are not available on your system, make a
plain copy of the file to a file named "Makefile.inc" in the
current "src/" working directory:

%prompt% cp Make.inc/Makefile.inc.xxxx_xxx_xxx Makefile.inc

Some additional scripts, designed to ease the installation of Scotch
on specific platforms, are also present in subdirectories of the
Make.inc directory. This is for instance the case for the mingw32
platform.


By default, all integers used in Scotch and PT-Scotch are based on
the "int" C type, corresponding to the "INTEGER" type in Fortran. To
coerce the length of the integer type to 32 or 64 bits, add the
INTSIZE32 or INTSIZE64 flags, respectively, to the C compiler flags in
the Makefile.inc configuration file. If you do so, make sure to use
integer types of equivalent length to declare variables passed to Scotch
routines from caller C and Fortran procedures. It is usually safer and
cleaner to tune your C and Fortran compilers to make them interpret
"int" and "INTEGER" types as 32 or 64 bit values than to use the
aforementioned flags and hard-code type lengths in your own code.


The binaries of the Scotch distribution can handle compressed
graphs in input or output. Three compressed graph formats are
currently supported: bzip2, gzip and lzma. In order for them to be
actually activated, the proper libraries must be available on your
system. On a Linux platform, they are called "zlib" for the gzip
format, "libbz2" for the bzip2 format, and "liblzma" for the lzma
format. Note that it is the "development" version (also called
"devel", for short, within package names) of each of these libraries
which is required for the compilation to succeed.
According to the libraries installed on your system, you may set
flags COMMON_FILE_COMPRESS_BZ2, COMMON_FILE_COMPRESS_GZ and/or
COMMON_FILE_COMPRESS_LZMA in the CFLAGS variable of your Makefile.inc
configuration file, to have these formats and their respective
extensions ".bz2", ".gz" and ".lzma", recognized and handled by
Scotch.


Scotch can also take advantage of Posix threads when they are
available. They are used in two places:

- to compress and uncompress file data. This can be done either
  by launching a service thread, or else by creating a separate
  process by means of a Posix fork() system call. This choice is
  controlled by the -DCOMMON_PTHREAD flag : if it is set, threads
  will be used, else fork() calls will be performed. For systems
  which do not support the fork() system call, such as the MinGW32
  platform, one can set the -DCOMMON_STUB_FORK flag, which creates
  a stub fork() routine which always return an error. Therefore,
  without both fork() and threads, one must set the COMMON_STUB_FORK
  flag without setting COMMON_PTHREAD, so that compilation will
  successfully complete; however, in this case, compressed graphs
  shall not be handled in practice.

- to create distributed graphs in parallel. Since this taks involves
  concurrent MPI communications, the MPI library must support the
  MPI_THREAD_MULTIPLE level. The use of threads within Scotch itself
  is controlled by the SCOTCH_PTHREAD flag, which is completely
  independent from the COMMON_PTHREAD flag. Any of them can be set
  without setting the other. If you have doubts on the stability
  of your MPI implementation, it is better not to set -DSCOTCH_PTHREAD.
  For instance, on Linux platforms, concurrency problems have been
  experienced with MPICH2 versions prior to 1.0.7 using TCP;
  consequently, if the MPI implementation on your platform is based on
  an older MPICH2 version, do not set the SCOTCH_PTHREAD flag.


Then, compile the Scotch distribution by typing "make scotch", or
just "make", in the current "src/" working directory. To compile
the PT-Scotch distribution, type "make ptscotch" in the same "src/"
directory. This can be done in any order.

If no error occurs, all of the relevant header, library and executable
files will be created and copied to the "../include/", "../lib/" and
"../bin/" directories, relatively to your current "src/" working
directory. Since headers, libraries and binaries of Scotch and
PT-Scotch can coexist in these directories, you can compile both in
sequence, in any order.

Further typing "make install" will perform a GNU-like installation,
with header, library, binary and man files copied to the "include",
"lib", "bin" and "man" subdirectories of the path specified in the
"prefix" variable, which is set by default to "/usr/local".


3) Documentation and use
------------------------

The Scotch and PT-Scotch user's manuals are available in the "doc/"
directory. They describe how to use the libscotch and ptlibscotch
libraries, as well as the standalone programs of the Scotch and
PT-Scotch distributions.
