FILE: CCF/README CCF Collaborative Computing Frameworks Emory University Atlanta, GA, USA March 1998 CCF is a software system that supports collaborative, distributed, computer-based problem solving in the natural sciences, business, government, and in educational environments. The goal is to evolve a virtual environment for distributed computation that supports integrated human AV communication, high performance heterogeneous computing and distributed data management facilities. CCF is a research project at Emory University involving the Math/Computer Science and Chemistry departments. DISCLAIMER: This is alpha release 0.99 of CCF -- Collaborative Computing Frameworks. This software is provided as is with no warranty expressed or implied. We hope you find it useful, but we won't be held responsible for any damage that may occur from reading, compiling, installing, using, or even thinking about it. LICENSE: CCF is Copyright (C) 1996 by Emory University except for the code in directories GSM, LPC, LPC10 in the CCFaudio directory and is distributed under the terms of GNU General Public License (GPL) and the GNU Library General Public License (LPGL). The files COPYING and COPYING.LIB in each directory will tell exact licensing restrictions. This package is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the license, or (at your option) any later version. CREDITS: CCF was created by Vaidy Sunderam, Injong Rhee, Alan Krantz, Shun Yan Cheung, Julie Sult, Soeren Olesen, Paul Gray, Phil Hutto, Sarah Chodrow, Michael Hirsch, Ted Goddard, Mic Grigni, N. Balaguru, Jim Nettles, Luigi Marzilli, Sue Onuschak, Scott Childs, Kevin Williams. The CCF project is sponsored by the U.S. National Science Foundation under the multidisciplinary challenges initiative. CCF currently supports three platforms: IRIX-6.2, SunOS-5.6, and SunOS-5.5.1. The SunOS-5.6 version is the most thoroughly tested. INSTALLATION: 1) Retrieve the latest source distribution via anonymous ftp or the Web. ftp.mathcs.emory.edu pub/ccf http://ccf.mathcs.emory.edu/ccf/software.html CCF is distributed as a compressed (GZIP) tar file (e.g. CCF-0.99.tar.gz) that unpacks as a single source tree (./CCF) containing C and C++ source files and makefiles. The top-level Makefile creates architecture specific bin and lib subdirectories (e.g. bin/SunOS-5.6 and lib/IRIX-6.2). A distribution containing only binaries is available as: CCFB-0.99.tar.gz You may wish to try installing the binaries before attempting a source build. Occasionally the binaries fail to execute properly due to version inconsistencies with dynamically linked libraries. 2) Unpack the distribution using the GNU gtar utility: gtar xzvf CCF-0.99.tar.gz (gtar is available at ftp://prep.ai.mit.edu/pub/gnu.) or if gtar is not available: gzip -dc CCF_0.99.tar.gz | tar xvf - (gzip is available at ftp://prep.ai.mit.edu/pub/gnu.) The latest distribution file is about 1M compressed, unpacks to 4M and expands to about 45M after compiling. This can be trimmed to about 35M by running "make clean" after building to remove .o files. This will create the following directories: CCF CCF/CCFaudio (Audio tool) CCF/CCFcb (Clearboard tool) CCF/CCFccds (Dataspace tool) CCF/CCFcctl (Multicast transport layer) CCF/CCFchat (Text communication tool) CCF/CCFgui (Gui library) CCF/CCFsns (Session nameserver) CCF/CCFxmux (X multiplexor and desktop) CCF/bin (initially empty) CCF/include (initially empty) CCF/lib (initially empty) 3) Build CCF for the current architecture: To build CCF, cd into the top-level directory and run make: make all CCF builds with standard Solaris, IRIX and GNU versions of make. This will create libraries and binaries for the current architecture. Building CCF requires access to the ANSI C and C++ compilers and utilities from the standard IRIX and Solaris development environments. Solaris: WorkShop 4.2 IRIX: MIPSpro 7.2 Note that the makefiles contain compiler specific flags. The current distribution will NOT make properly with gcc and g++ without some modifications. If your X11 lib and include files are in non-standard locations you will need to modify the CCF makefiles to specify the new locations. Also, the build process assumes you are specifically running on SunOS-5.5.1, SunOS-5.6 or IRIX-6.2. If "uname -sr" reports any other architecture you will need to modify the makefiles. You can probably build successfully on minor variants by manually defining the variable ARCH in the top-level Makefile. For example, if you are running on SunOS-5.5, add: ARCH=SunOS-5.5.1 The normal build process may generate makefile errors that are ignored (e.g. attempts to build directories that already exist) and a few compiler warnings. To restart a build after a failure: make archclean all to remove intermediate files produced by the failed build. If you have difficulties, you may be able to build some subsystems properly by using the "-k" option to make. 4) If you wish to build for another architecture in the same source tree, access the source from a machine of the appropriate type and run make: make archclean all If you do not clean before making, the build will fail trying to link .o files of the incorrect architecture from the previous build. EXECUTION: Overview: Running CCF requires three steps: 1) Select a machine to run the Session Name Server (ccfsns) and the multicast White Pages (cctlwp) and startup these demons (usually in the background): cctlwp & ccfsns & Both servers use a well-known TCP port so only one instance of each process may run on a given machine. All participants in a session share the same servers. Both processes must execute on the same machine. Independent sessions may run using different servers or they may share the same servers. 2) Define two environment variables identifying the directory containing CCF binaries (CCF_BIN) and the host running cctlwp and ccfsns (CCTL_WP_HOST_NAME). # in ksh export CCF_BIN= export CCTL_WP_HOST_NAME= Common errors include mistyping CCTL_WP_HOST_NAME, specifying the wrong host name, forgetting to start the servers, not exporting the CCF environment variables and not defining the CCF_BIN directory. If a session hangs or becomes corrupted, you may need to restart cctlwp and ccfsns. 3) Each session participant should start the virtual desktop (ccsm): $CCF_BIN/ccsm All participants must define environment variables and start a copy of the virtual desktop. The servers should be run only once. Detailed Execution Instructions: The first thing you need to do is determine what machine will be running the white page server (cctlwp) and the ccf server (ccfsns). cctlwp and ccfsns set up and monitor sessions that you may want to participate in. You will need only ONE cctlwp and ccfsns for every group of collaborators. One user should be chosen as the administrator of cctlwp and ccfsns. If you know of a machine that is running cctlwp and ccfsns, you can connect to them via the CCTL_WP_HOST_NAME environment variable. You do not need to execute cctlwp and ccfsns! If you are the administrator or the first user, you will need to execute cctlwp and ccfsns on the machine of your choosing (they must run on the same machine). cctlwp and ccfsns are located in the bin directory for your architecture. To execute cctlwp and ccfsns: (1) login to the machine you wish to run the white page server on. (2) cd to the bin directory for that machines architecture to get the executables. (Note: if this directory does not exist, you will need to do a compile on your white page server machine. See INSTALLATION above) (3) type: % cctlwp& % ccfsns& Second, each user should set the environment variable "CCTL_WP_HOST_NAME" to the machine where you are connecting with cctlwp and ccfsns. ie. % export CCTL_WP_HOST_NAME=white_page_server_machine -or % setenv CCTL_WP_HOST_NAME white_page_server_machine If you don't set CCTL_WP_HOST_NAME, ccsm will exit with: Checking CCTL_WP_HOST_NAME for server info....Not found. Exiting... Next, each user should set the environment variable "CCF_BIN" to the bin directory in the ccf package. ie. % export CCF_BIN=/home/user-name/CCF/bin/SunOS-5.5.1 -or- % setenv CCF_BIN /home/user-name/CCF/bin/SunOS-5.5.1 If you are using sh or ksh shell and will always connect with the same white page machine, you can add the following lines to your .profile file: export CCTL_WP_HOST_NAME=white_page_server_machine export CCF_BIN=/home/user-name/CCF/bin/SunOS-5.5.1 If you are using csh shell and will always connect with the same white page machine, you can add the following lines to your .cshrc file: setenv CCTL_WP_HOST_NAME white_page_server_machine setenv CCF_BIN /home/user-name/CCF/bin/SunOS-5.5.1 Finally, here's how to execute each sub-system in the bin directory for your architecture: ccsm (Virtual desktop for application sharing) % ccsm Once it is launched, click the session button. You may either join an existing session or create your own session using the panels. If a fellow user has created a session but it is not appearing in your join session panel, press cancel and click the session button and join button again. For more information about ccsm/ccfx, read the README in the CCFxmux directory NOTE: All of the following tools can be executed within the Virtual Desktop of ccsm. The following instructions are for launching them stand alone. ccfaudio (Audio communication tool) % ccfaudio -session [session_name] For more information about ccfaudio, read the README in the CCFaudio directory. ccfchat (Text communication tool) % ccfchat -session [session_name] For more information about ccfchat, read the README in the CCFchat directory. ccfcb (Clearboard) % ccfcb -session [session_name] For more information about ccfcb, read the README in the CCFcb directory. ccdssh (Dataspace tool) % ccdssh -session [session_name] For more information about ccdssh, read the README in the CCFccds/ccdssh directory. REPORTING BUGS/KUDOS: When reporting bugs, problems, suggestions or contributions, please be sure to send them to the ccf@mathcs.emory.edu.