Last Revised: Wed May 19, 15:33:48 EDT 1999
Maintainers:
Mark Hayden,
Tim
Clark,
Ohad Rodeh.
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. Also, please read the file RELEASE_NOTES for the latest information on this release.
These installation instructions are aimed at getting Ensemble up and running on your system as quickly as possible. 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.
On Unix platforms, to compile the HOT C interface, you need a POSIX compliant threads package. (On Solaris, you can use the native threads library). More recent versions of Linux now provide a POSIX compliant pthreads package (pthreads), however, Linux users with older versions of the operating system, or users who still use SunOS, will need to acquire a threads package, such as the FSU threads package or the rvr_threads package. Click here for information on how to acquire and install the FSU pthreads package. The rvr_threads package will be available from Cornell in a separate tar file of contributed code.
To compile the Maestro tools C++ interface, you will need a C++ compiler. We use the Microsoft C++ compiler on Windows NT and gcc on Unix platforms, but other compilers should work. On NT to build the optimized versions of HOT C and Maestro, you will also need the masm (MS Compatibility Driver) and ml (MS Macro Assembler) executables installed and located in your path.
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_' , as shown above.
After you have made these changes, to upgrade your system simply install the new version of Ensemble as described below. For further information on the changes in this release, please read the RELEASE_NOTES found in the ensemble directory.
Some environment variables will need to be set before running Ensemble applications which need to communicate with other processes (via the gossip or groupd servers) - see ensemble/doc/tut.ps for more information:
ENSROOT (set to root directory of ensemble distribution, e.g: /usr/u/ensemble)
ENS_ID (set to your user login id)
ENS_PORT (for all Ensemble applications, set to an unused port number)
ENS_GOSSIP_PORT, ENS_GOSSIP_HOSTS (for gossip applications, an unused port number and a list of colon-separated host names, e.g.: mymachine1:mymachine2:mymachine3)
ENS_GROUPD_PORT, ENS_GROUPD_HOSTS (for groupd applications, an unused port number and a list of colon-separated host names)
ENS_DEERING_PORT (for IP Multicast, an unused port number)
ENS_OUTBOARD (if you will be using the HOT outboard application, a full pathway to the outboard executable, e.g: /usr/u/ensemble/demo/outboard)
If you already have O'Caml you can check which version you have by typing:
ocamlc -vThis 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 ocaml 2.02If you have some other version, then obtain version 2.02 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.
http://pauillac.inria.fr/ocaml/distrib
# uncompress and untar the distribution gunzip ensemble-0.61.tar.gz tar xvf ensemble.tarBack to installation guide.
You can also compile everything to run on the native instruction set of your computer instead of using an interpreter. This will run faster.
Compile the bytecode and demonstration programs as follows. Note that on Windows NT, you need to use nmake and the Makefile.nt versions of the makefiles:
# build bytecode ensemble # directory: ensemble\def nmake -f Makefile.nt
# build ensemble demos # directory: ensemble\demo nmake -f Makefile.ntIf all went smoothly, the initial installation is now complete.
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 would do the following:
# build native code libraries in opt directory # directory: ensemble\opt nmake -f Makefile.nt # change directory to demo and build native code demo programs # directory: ensemble\demo nmake -f Makefile.nt opt # change back to opt and build the HOT tools # directory: ensemble\opt nmake -f Makefile.nt libhotOnce you have built the HOT tools, there will be 3 executable files placed in the ensemble\demo directory: hot_test.exe, hot_testo.exe, and outboard.exe. The file hot_test.exe runs basic single-process sanity checks of the HOT C / Ensemble interface. The files hot_testo.exe ("o" is for outboard) and outboard.exe perform the same sanity checks, however, the Ensemble protocols are isolated in a separate process (outboard.exe) and communication takes place via TCP sockets. The hot library file, ensemble\lib\nt\libhot.a will be placed in the ensemble\lib\nt directory. You will need to link this hot library with your own "C" applications.
There is also an auxilliary HOT test program, called hot_test2.c, which can be compiled as follows:
# build the hot_test2 demo program # directory: ensemble\opt nmake -f Makefile.nt hot_test2This will build and install the program hot_test2.exe in the demo directory. The program hot_test2 is a two-process RPC performance test.
In order to run hot_testo.exe, you first have to set environment variables. This is done through the Control Panel, by selecting the System icon, and then selecting the Environment tab. You then enter the environment variable ENS_OUTBOARD and for its value, you enter the complete path to the outboard.exe file, e.g.:
ENS_OUTBOARD
c:\ensemble\demo\outboard.exe
Then select "Set" and "OK". The Environment data entry window will close. You may now open a MS DOS Console window and run hot_testo.exe.
If you attempt to run hot_testo.exe and you get the following output, it means that you did not set the ENS_OUTBOARD environment variable before you opened the Command prompt window (it needs to be set before the Command prompt is opened in order to be exported):
HOT_TEST: CDEMO: starting
PANIC: spawnvp
Close the Command prompt window, go to the Control Panel, open the System icon, select Environment, add the ENS_OUTBOARD variable, then select "Set", and "OK". Open a new Command prompt window and try again.
The HOT tools can also be built with cryptographic support as follows. First you will need to edit the file, config.nmk, and uncomment the CRYPTO_LINK lines. Then perform the following at the command line:
# build crypto library # directory: ensemble\opt nmake -f Makefile.nt crypto
# build HOT tools with crypto support # directory: ensemble\opt nmake -f Makefile.nt libhot-cryptoThis will build versions of the hot_tests and outboard executables with a "-crypto" extension and place them in the demo directory.
# build the Maestro tools # directory: ensemble\opt nmake -f Makefile.nt maestro-ntYou should now have three test programs, ensemble\maestro\maestro-nt\maestro_test.exe, ensemble\maestro\maestro-nt\maestro_perf.exe, and ensemble\maestro\maestro-nt\group.exe. maestro_test is a single process sanity test in which several group-member objects are created which then randomly send messages and leave/rejoin the group. maestro_perf is a two-process RPC performance test. group is an application which tests the new, simpler state transfer algorithm. 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.
# build the EJava interface # directory: ensemble\ejava nmake -f Makefile.ntOnce complete, you must first copy the outboard.exe file from the demo directory to the ejava directory:
# directory: ensemble\ejava copy ..\demo\outboard.exe .After you have copied this file, you can then run one of the demo programs, EnsDemo, EnsDemoOutboard or ThreadTest as follows:
java EnsDemoThe demo application, ThreadTest, requires one parameter, the number of group members to wait for before beginning the test. For example, to run the test with 2 members, start the test on 2 machines (or 2 consoles) as follows:
java ThreadTest 2
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.
# make the Ensemble system # directory: ensemble/def makeIf all went smoothly, the initial installation is now complete, and you can try out the demo programs following the instructions below.
# make the Ensemble tk library # directory: ensemble/def make tk
# make the white board demo # directory: ensemble/demo/tk make # make the game-of-life demo # directory: ensemble/demo/life make
MACHTYPE=i386 export MACHTYPE OSTYPE=linux export OSTYPE
% ocamlc -v The Objective Caml compiler, version 2.02 Standard library directory: /usr/local/lib/ocamlThe 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 CAMLLIBIn tcsh, set them like this:
setenv CAMLLIB /usr/local/lib/ocaml setenv PATH /usr/local/bin/ocaml:$PATHWe recommend you add these to your '.profile' or equivalent for your shell.
# In ensemble/mk/config.mk, edit the macro definition for HSYS_TYPE to be "skt". # directory: ensemble/def make socket
# directory: ensemble/def make clean; makeWhen you compile other parts of Ensemble in the future, the Socket library will be used in place of the Unix library.
This step generates the file 'ensemble/lib/PLATFORM/libhot.a' (where PLATFORM is the name of your platform) and installs the HOT library files into 'ensemble/lib/PLATFORM'.
**NOTE ** For users on SunOS, lacking Solaris threads, you can download the "ENS_CONTRIB-061" package provided on our website and use the rvr_threads package provided. Alternatively, please see the section below on POSIX threads. You will have to obtain this threads package, install it, and modify the ensemble/mk/config.mk file to reference the corresponding threads interface file (either ensemble/hot/rvr_intf.c or pthread_intf.c).
# build the HOT tools # directory: ensemble/def (or ensemble/opt) make libhotThere is also an auxilliary HOT test program, called hot_test2.c, which can be compiled as follows:
# build the hot_test2 demo program # directory: ensemble/def make hot_test2This will build and install the program hot_test2 in the demo directory. The program hot_test2 is a two-process RPC performance test.
# build the HOT tools with crypto # directory: ensemble/def (or ensemble/opt) make libhot-cryptoThis will install the hot_test-crypto, hot_testo-crypto and outboard-crypto files in the demo directory.
# build the Maestro and IIOP libraries and utilities # directory: ensemble/def make maestro
# build the Maestro and IIOP test applications # directory: ensemble/def make maestro_test(** NOTE ** You can also run "make" in the maestro directory)
You should now have five test programs, ensemble/maestro/test/maestro-test , ensemble/maestro/test/maestro-perf, ensemble/maestro/test/test-replicated, ensemble/maestro/test/test-simple, and ensemble/maestro/test/group. maestro-test is a single process sanity test in which several group-member objects are created which then randomly send messages and leave/rejoin the group. maestro-perf is a two-process RPC performance test. Both test-replicated and test-simple are Maestro IIOP test applications. group is an application which tests the new, simpler state transfer algorithm. See ensemble/maestro/REF.ps for more information on the Maestro IIOP tools. To get started with Maestro and Ensemble, we also recommend you read the Maestro documentation and start from the test programs (in the corresponding .C files) -- you can modify and experiment with them.
# build native code libraries # directory: ensemble/opt make # build the HOT tools for native code # directory: ensemble/opt make libhot # build the Maestro and IIOP libraries and utilities # directory: ensemble/opt make maestro
# build the Maestro and IIOP test applications # directory: ensemble/opt make maestro_test
# build the EJava interface # directory: ensemble/ejava makeOnce complete, you must first copy the outboard file from the demo directory to the ejava directory:
# directory: ensemble/ejava cp ../demo/outboard .After you have copied this file, you can then run one of the demo programs, EnsDemo, EnsDemoOutboard or ThreadTest as follows:
java EnsDemoThe demo application, ThreadTest, requires one parameter, the number of group members to wait for before beginning the test. For example, to run the test with 2 members, start the test on 2 machines (or 2 consoles) as follows:
java ThreadTest 2
For information on building and using these add-ons, please refer to
the INSTALL.htm(.txt) or README files included with the desired contrib
distribution.
NOTE: This Java interface was developed using Sun Microsystem's JDK 1.2. Other versions of Java or earlier versions of the JDK may not work properly.
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 executable demos are removed and replaced with the new ones.
This concludes the instructions for building Ensemble on multiple platforms.
Back to installation guide.
The command "make realclean" will attempt to perform the "make clean" operations ON ALL PLATFORMS, e.g. sparc-solaris, linux, and NT, and so is to be used only when cleaning up the entire distribution directory of ALL compiled object files and executables.
(** NOTE: This version of the security code requires PGP5.0 on Unix.)
Unix:
# Make the regular crypto library # directory: ensemble/def make crypto # Make the demo's with the crypto library # directory: ensemble/def make # Make the optimized crypto library # directory: ensemble/opt make crypto
# Make the demo's with the optimized crypto library # directory: ensemble/opt make # Make libhot with the optmized crypto library # directory: ensemble/opt make libhot-crypto
** NOTE: on NT, change "make" to:
nmake -f Makefile.ntand things should compile smoothly.