MERCURY POSIX
-------------

These are the release notes for Mercury POSIX (as of 11/20/2014).

WHAT IS MERCURY POSIX?

   Mercury POSIX is a lightweight library that allows redirection
   of POSIX I/O calls to a remote server by using the Mercury RPC layer.

   Please see the accompanying COPYING file for license details.

ARCHITECTURES SUPPORTED:

   Mercury POSIX supports 32 and 64-bit Linux platforms. Network transports
   supported by the Mercury RPC layer are supported by Mercury POSIX.
   Please refer to the Mercury documentation for more details.

DOCUMENTATION:

 - Please see the accompanying design implementation documentation for
   additional and useful details.

 - Environment variables:
     MERCURY_PORT_NAME:
     Port name/plugin information (IP/port) used to establish a connection with 
     a remote server -- specific to the network transport chosen.
     E.g. "bmi+tcp://127.0.0.1:22222"

SOFTWARE REQUIREMENTS:

   Compiling and running Mercury POSIX requires up-to-date versions of various
   software packages. Beware that using excessively old versions of these
   packages can cause indirect errors that are very difficult to track down.
   Mercury POSIX requires a _well-configured_ Mercury package (v0.8.2) with
   BOOST_PP option (Boost preprocessor library) turned on.

BUILDING:

 - If you install the full sources, put the tarball in a directory where you
   have permissions (e.g., your home directory) and unpack it:

     gzip -cd mercury_posix-X.tar.gz | tar xvf -

   or

     bzip2 -dc mercury_posix-X.tar.bz2 | tar xvf -

   Replace "X" with the version number of the package.

 - Mercury POSIX makes use of the CMake build-system and requires that you do
   an out-of-source build. In order to do that, you must create a new build
   directory and run the 'ccmake' command from it:

     cd mercury_posix-X
     mkdir build
     cd build
     ccmake .. (where ".." is the relative path to the mercury_posix-X
     directory)

 - Type 'c' multiple times and choose suitable options. Recommended options
   are:

     BUILD_SHARED_LIBS                ON (for dynamic redirection)
     BUILD_TESTING                    ON
     CMAKE_INSTALL_PREFIX             /path/to/install/directory
     MERCURY_POSIX_ENABLE_LARGE_FILE  ON
     MERCURY_POSIX_ENABLE_SERVER_LOG  ON (for printing log messages on server)
     mercury_DIR                      /path/to/mercury/install/share/cmake/mercury

   Setting include directory and library paths may require you to toggle to
   the advanced mode by typing 't'. Once you are done and do not see any
   errors, type 'g' to generate makefiles. Once you exit the CMake
   configuration screen and are ready to build the targets, do:

      make

 - (Optional) Verbose compile/build output:

   This is done by inserting "VERBOSE=1" in the "make" command. E.g.:

     make VERBOSE=1

INSTALLING:

 - Assuming that the CMAKE_INSTALL_PREFIX has been set (see previous step)
   and that you have write permissions to the destination directory, do
   from the build directory:
   
     make install
     
TESTING:

 - Open a terminal, start a server:
     mercury_posix_server(64)
   or:
     mpirun -np 1 mercury_posix_server(64)

 - Open a second terminal, export MERCURY_PORT_NAME:
     export MERCURY_PORT_NAME="bmi+tcp://127.0.0.1:22222"

 - In the same terminal, launch the posix client test:
     ./client_posix
   or:
     mpirun -np 1 ./client_posix