Copyright © 1997 Cornell University, Ithaca, NY, USA
All rights reserved.
Last Revised: Tue Apr 29 15:33:48 EDT 1997
Maintainer: Mark Hayden.
Thank you for choosing Ensemble as your message transport system. Its platform independence allows you to interconnect a wide range of computing environments.
The following instructions guide you through the process of installing Ensemble. Click on the hypertext links for the details about each step. The installation instructions are designed to be as simple as possible. However, please read them through carefully before starting and follow them carefully.
These installation instructions are aimed at getting a simple version of Ensemble up and running on your system by using precompiled, platform-independent bytecode libraries. After successfully installing the system, you may wish to compile Ensemble for native instruction set of your computer and to use an optimized C library we provide in order to improve performance. The difference is only significant when Ensemble is used in high-performance settings and many users find the performance of bytecode satisfactory.
If you are upgrading from an older version, due to problems with long environment variable names on certain platforms, we have changed the names for the Ensemble environment variables to use the prefix 'ENS_' instead of 'ENSEMBLE_'. Please update your configuration.
The name of the group membership service has been changed from 'domain' to 'groupd'. The names of the corresponding environment variables have changed from 'ENS_DOMAIN_' to 'ENS_GROUPD_'.
After you have made these changes, to upgrade your system simply install the new version of Ensemble as described below.
To use Ensemble you must agree to the terms of the license. Ensemble is freely available software, but there is a license to which you must agree before you can install it. We ask that you read the licensing agreement before installing Ensemble. The setup process will also require you to agree to the License agreement.
Install Ensemble by following the step-by-step instructions. You need to get the O'Caml compile, extract the Ensemble software, and then compile the portions you wish to use.
In addition, instructions for building Ensemble on multiple platforms.
To compile Ensemble you need Objective Caml version 1.05. Other versions of the compiler will NOT work. This is because the O'Caml bytecode format and libraries are not guaranteed to be compatible across versions.
If you already have O'Caml you can check which version you have by typing:
ocamlc -v
This gives you the version of the compiler in your path (if there is one). The first line of the output should be:
The Objective Caml compiler, version 1.05
If you have some other version then obtain version 1.05 and install it. O'Caml is freely available from http://pauillac.inria.fr/ocaml and is easy to install (precompiled binaries are available for Windows NT). You do not need the native code compiler, although you can compile Ensemble with it.
If you want to compile the white board demo or wish to use the O'Caml Tcl/Tk interface, you will also need the Ocamltk library. This library is entirely optional. It is not available for Windows NT. You can install Ensemble without it and install it later if you change your mind. The library and a necessary bug-patch can be obtained from the O'Caml Web site:
ftp://ftp.inria.fr/lang/caml-light/camltk/ocamltk.tar.gz
ftp://ftp.inria.fr/lang/caml-light/camltk/ocaml-patch1
Download Ensemble from http://www.cs.cornell.edu/Info/Projects/Ensemble/ftp.html. Uncompress and untar the distribution. It will put the sources in a directory called "ensemble". On Windows NT you can use the winzip program. On Unix platforms, do it this way:
# uncompress and untar the distribution
gunzip ensemble-0.40.tar.gz
tar xf ensemble/ensemble.tar
At this point you have untarred the first level of the Ensemble distribution. You need to read and agree to the Ensemble licensing agreement before the distribution can be decrypted. You do this by running the program "setup" like this (you need to have the O'Caml program, ocamlrun, in your path):
# run the setup program
# directory: ensemble/
ocamlrun setup
The setup program does the following:
Uncompress and untar the decrypted version. You should extract the distribution from the parent directory of the main Ensemble directory. On Unix platforms, do it this way:
# uncompress and untar the final distribution
# directory: ensemble/
gunzip ensemble.tar.gz
cd ..
tar xf ensemble/ensemble.tar
The distribution of Ensemble comes with pre-compiled O'Caml bytecode libraries which are interpreted. To use them you simply need to compile your application. Some demonstration applications have been provided which you can use to test the distribution once the first parts are installed.
You can also compile everything to run on the native instruction set of your computer instead of using an interpreter. This will run faster.
In 'ensemble\mk\config.nmk', you may need to edit the following macro definitions (you may wish to try the default settings first). MSDEV and LIBSYS should have appropriate values for your C compiler. Set the CAMLLIB environment variable to be the directory where you installed the O'Caml libraries (this is used to set the OCAML_LIB macro. CAMLLIB should have been set when O'Caml was installed -- see the O'Caml README.win32 file).
Since Ensemble comes with pre-compiled, machine-independent libraries it is possible to use it directly. Some demonstration programs are provided to test that everything is working. Compile the demonstration programs as follows. Note that on Windows NT, you need to use the Makefile.nt versions of the makefiles:
# directory: ensemble\demo
nmake -f Makefile.nt
If all went smoothly, the initial installation is now complete.
You can now refer to the file 'ensemble\doc\tut.ps' for instructions on executing the demo applications. This involves setting a few environment variables and then executing the applications.
You can also compile everything to run on the native instruction set of your computer instead of using an interpreter. This will run faster. We distributed the libraries for Windows NT in binary form (they are in the 'ensemble\lib' directory, so you do not need to compile anything further if you wish to just use the libraries.
To use the native code version of Ensemble, compile it in the directory 'ensemble\opt'. This step compiles all of the Ensemble sources and will take awhile. This is also where you build the native code versions of the HOT tools.
In order to compile the HOT tools, you need a modified version of the O'Caml 1.05 native code compiler for Windows NT. This fixes a bug in the compiler. Later versions of the O'Caml compiler should fix the problem, making this binary unnecessary. You can find the fixed version of the compiler in 'ocamlopt.nt.tar.gz' in the same FTP directory from which you downloaded Ensemble. Uncompress and tar this and copy the binary into the 'ocaml-1.05/bin' directory of your O'Caml distribution (you still need the rest of the distribution). The binary is the same as that distributed by INRIA, except that it has a bug fix for the '-output-obj' command-line option.
# build native code libraries
# directory: ensemble\opt
nmake -f Makefile.nt
# build native code demo programs
# directory: ensemble\demo
nmake -f Makefile.nt socketopt
# build the HOT tools
# directory: ensemble\opt
nmake -f Makefile.nt libhot
(Note: Because of a bug in the Microsoft C++ compiler, the bytecode version of the HOT tools is not available on Windows NT. This is not a problem because you can still compile the native code version, which has better performance anyway.)
You need to have compiled the HOT library before compiling the Maestro C++ interface. This step generates the file 'ensemble\lib\libmae-nt.a' and installs the Maestro header files in 'ensemble\lib'.
# build the Maestro tools
# directory: ensemble\maestro
nmake -f Makefile.nt
You should now have two test programs, 'ensemble\maestro\maestro_test' and 'ensemble\maestro\maestro_test_threads'. In both, several group-member objects are created which then randomly send messages and leave/rejoin the group. To get started with Maestro and Ensemble, we recommend you read the Maestro documentation and start from the test programs (in the corresponding .C files) -- you can modify and experiment with them.
This concludes the instructions for building Ensemble on Windows NT
systems.
Back to installation guide.
The distribution of Ensemble comes with pre-compiled O'Caml libraries which are interpreted. To use them you simply need to compile your application. Some demonstration applications have been provided which you can use to test the distribution once everything is installed.
You can also compile everything to run on the native instruction set of your computer instead of using an interpreter. This will run faster. You can also use a special Socket library to improve the performance of network operations. Details on how to build all of these things are given below.
Since Ensemble comes with pre-compiled, machine-independent libraries it is possible to use it directly. Some demonstration programs are provided to test that everything is working. Compile the demonstration programs as follows:
# make standard demos
# directory: ensemble/demo
make
If all went smoothly, the initial installation is now complete, and you can try out the demo programs following the instructions below.
You can now refer to the tutorial, 'ensemble/doc/tut.ps', for instructions on executing the demo applications. This involves setting a few environment variables and then executing the applications. Come back to here to install additional parts of Ensemble.
If you installed the O'caml Tcl/Tk interface, compile the white board demo and "Game of Life" demo. (Note: In order to use the Tcl/Tk interface you may need to set the TKLIB macro in 'ensemble/mk/config.mk').
# make the white board demo
# directory: ensemble/demo/tk
make
# make the game-of-life demo
# directory: ensemble/demo/life
make
In order to compile platform-dependent parts (the Socket library, the native code, the HOT C interface, and the Maestro C++ interface) some configuration needs to be done.
MACHTYPE=i386
export MACHTYPE
OSTYPE=linux
export OSTYPE
% ocamlc -v
The Objective Caml compiler, version 1.05
Standard library directory: /usr/local/lib/ocaml
The second line printed out by this is the location where O'Caml installed the libraries. In sh, you set the CAMLLIB variable like this:
CAMLLIB=/usr/local/lib/ocaml
export CAMLLIB
We recommend you add these to your '.profile' or equivalent for your shell.
The Socket library supports extensions to the Unix library concerned with communication. It is derived in large part from the O'Caml Unix library. It is not necessary on Unix (the O'Caml Unix library is used by default), but using the Socket library increases Ensemble performance and decreases memory usage. Note that you only need to compile this separately if you are using the bytecode version of Ensemble. The build for the native code system compiles the Socket library by default.
make socket
make clean
make
When you compile other parts of Ensemble in the future, the Socket library will be used in place of the Unix library.
The HOT tools can be compiled from either the bytecode or native code version of Ensemble. Compiling from 'ensemble/def' builds the bytecode version. Compiling from 'ensemble/opt' builds the native version. Either way the C library file that is generated is platform dependent.
This step generates the file 'ensemble/lib/libhot-PLATFORM.a' (where PLATFORM is the name of your platform) and installs the HOT header files into 'ensemble/lib'. This step compiles all of the Ensemble sources and will take awhile.
# build the HOT tools
# directory: ensemble/def (or ensemble/opt)
make libhot
You need to have compiled the HOT library before compiling the Maestro C++ interface. You need a C++ compiler in order to compile Maestro. This step generates the file 'ensemble/lib/libmae-PLATFORM.a' (where platform is the name of your platform) and installs the Maestro header files in the 'ensemble/lib'.
# build the Maestro tools
# directory: ensemble/maestro
make
To use the native code version of Ensemble, compile it in the directory 'ensemble/opt'. This is also where you build the native code versions of the HOT tools. Note that this automatically compiles the native code Socket library for you. This step compiles all of the Ensemble sources (including the demos) and will take awhile.
Note that the native-code version of HOT tools and Maestro do not work on sparc-solaris platforms. Use the bytecode version.
# build native code libraries
# directory: ensemble/opt
make
# build the HOT tools for native code
# directory: ensemble/opt
make libhot
# build the Maestro tools for native code
# directory: ensemble/maestro
make
You should now have two test programs, 'ensemble/maestro/maestro_test' and 'ensemble/maestro/maestro_test_threads'. In both, several group-member objects are created which then randomly send messages and leave/rejoin the group. To get started with Maestro and Ensemble, we recommend you read the Maestro documentation and start from the test programs (in the corresponding .C files) -- you can modify and experiment with them.
This concludes the instructions for building Ensemble on Unix systems.
Back to installation guide.
Multiple versions of Ensemble can co-exist within the same directory tree. All platform-dependent files have a suffix describing the platform for which they were compiled. For Unix platforms, you just need to ensure that the 'MACHTYPE' and 'OSTYPE' environment variables are correctly set. For Windows NT, the name of the platfrom ('nt') is embedded in the Windows NT makefiles and does not need to be set. For instance, the platform-independent bytecode library for Ensemble is called 'libens.cma' ('cma' is the O'Caml suffix used for bytecode libraryies). The platform-dependent, native code library for Ensemble on i386, Linux platforms is called 'libens-i386-linux.cmxa' ('cmxa' is the O'Caml suffix for native code libraries').
The only exceptions are the demo programs. These are platform independent but do not follow the naming convention. Whenever you compile executables for a new platform, the old executables are removed and replaced with the new ones.
This concludes the instructions for building Ensemble on multiple platforms.
Back to installation guide.
If your system does not have a native POSIX threads library, install the FSU pthreads.tar.gz package. You can get it from:
After installing the library. Update in ensemble/mk/config the macros
GTHREADS, GTHREADS_INC to point to your installation. If necessary, add
new HOT_CFLAGS_arch_os, HOT_MLLINK_arch_os, HOT_LINK_arch_os, and HOT_THREAD_OBJ_arch_os
macros to config.mk for your platform (and send them to us so we can add
them to the next distribution).
Back to installation guide.