INSTALL

Compilation:

The core parts  of the package consist  of a single C  source file which
can be compiled either for dynamic linkage  or to be compiled into a new
Tcl  interpreter with  the TclMPI  package included  and two  Tcl script
files tclmpi.tcl and  pkgIndex.tcl, that interface the  compiled code to
the Tcl  interpreter.  In addition a  folder with examples and  a folder
with unittests and a custom test harness are provided.

The TclMPI package  uses CMake for building,  installation, testing, and
packaging.  This requires  a somewhat modern CMake  version (3.16).  You
need  to run  CMake the  usual way  `cmake -B  build-folder .`  and then
`cmake   --build    build-folder`,   followed   by    `cmake   --install
build-folder`. Tcl version 8.5 or later and MPI-2 or later with  support
for development are required.

The following settings are supported by the CMake build environment
- BUILD_TCLMPI_SHELL   Build a `tclmpish` executable as extended Tcl shell   (default: on)
- ENABLE_TCL_STUBS     Use the Tcl stubs mechanism   (default: on, requires Tcl 8.6 or later)
- CMAKE_INSTALL_PREFIX Path to installation location prefix (default: (platform specific))
- BUILD_TESTING        Enable unit testing   (default: on)
- DOWNLOAD_MPICH4WIN   Download MPICH2-1.4.1 headers and link library (default: off, for cross-compiling to Windows only)

Documentation in HTML and PDF format is generated from doxygen and
pdflatex, if available, with `cmake --build build-folder --target html`
and `cmake --build build-folder --target pdf`, respectively.

Installation:

To    install   you    choose    a   suitable    prefix   folder    with
`-DCMAKE_INSTALL_PREFIX` when  configuring with  CMake and then  can use
`cmake  --install <builddir>`  e.g.  /usr/local.  The files  _tclmpi.so,
tclmpi.tcl   and    pkgIndex.tcl   would   then   be    installed   into
/usr/local/lib64/tcl8.6/tclmpi1.1.  To enable  loading  the plugin  'set
auto_path [concat /usr/local/lib64/tcl8.6  $auto_path]' in your .tclshrc
or set the environment variable  TCLLIBPATH to include that folder.  One
can  load the  tclmpi wrappers  on demand  simply by  using the  command
'package require tclmpi'.

Testing and packaging:

The included unit tests can be run (in serial and parallel) using the `ctest`
command, and the `cpack` command can be used to produce binary packages.
Testing with CTest is currently not supported on Windows.