Galaxy Communicator Documentation:

Installing the Galaxy Communicator Distribution

License / Documentation home / Help and feedback


Preliminaries

Supported and semi-supported platforms

The Galaxy Communicator distribution is actively supported on the following platforms: Labels in parentheses correspond to the ARCHOS values described below.

The Galaxy Communicator distribution has also been recently tested to some degree or another on the following platforms:

These platforms are not actively supported, but we will continue to test on these platforms when possible and incorporate appropriate fixes.

To the best of our knowledge, the following table reflects the status of the distribution on these six platforms. In all cases, the Hub and core C libraries, compiled statically, are known to work and pass our test suite.
 

Static libraries Shared libraries Python bindings Allegro bindings Java bindings Threads 64-bit integer XDR encode/decode
Sparc Solaris 2.7 yes yes yes yes yes yes not tested
Red Hat Linux for x86 yes yes yes unknown yes yes not tested
Win32 yes no yes unknown yes yes not tested
SGI IRIX yes yes no (don't know how to do dynamic loading yet) unknown unknown yes not tested
FreeBSD yes yes yes unknown unknown unknown no (xdr_hyper missing)
MacOS X/Darwin yes no no (don't know how to do dynamic loading yet) unknown yes no (pthread implementation incomplete) no (xdr_hyper missing)

For more details on how to configure these various options, see the configuration section.

Unsupported platforms

The Galaxy Communicator distribution is not yet supported on the following current platforms, because we don't have access to them, but we have reports from users that these distributions work just fine: The Galaxy Communicator distribution, at one point or another, has also worked on the following platforms, and may still work, although these platforms are no longer tested or supported.

ARCHOS

The Galaxy Communicator infrastructure uses an MIT-developed system for maintaining libraries and binaries for multiple architectures and operating systems under a single source tree. There are values for the machine architecture (ARCH), the operating system (OS), and their combination (ARCHOS = $(ARCH)-$(OS)). At compile time, object files, libraries, and binaries are created in ARCHOS subdirectories. For more details, see the directory structure documentation.

The computation of ARCHOS differs depending on the platform, as described in the remainder of the installation notes.


Unix configuration and build

In 2.0, we began a slow migration toward GNU configure. As of version 3.3, this migration is finally complete. The old configuration method still works, but there are new options which make it even easier to preserve configuration information, and all aspects of the configuration can be controlled by arguments to GNU configure. On Win32, we've provided header files which reflect the values which GNU configure would have generated for Windows. The instructions here are for Unix.

ARCHOS on Unix

[This information is also provided in file config.make, described below.]

On Unix, environment/make variables provide ARCH, OS and ARCHOS. For each C executable, there's a corresponding platform-independent shell script  which determines the appropriate ARCHOS-dependent binary to call at run time based on the name of the script and the value of ARCHOS. The values for ARCH and OS are determined by the scripts templates/set_arch.cmd and templates/set_os.cmd. These values will be used both in shell environments and in Makefiles.  The C files in the distribution will also be compiled with the preprocessor flags -D__$(ARCH)__ -D__$(OS)__ if you use the MIT Makefile templates and these flags aren't already provided by the preprocessor; if you don't use the MIT Makefile templates, you may still find these settings useful (if you don't use GNU configure and you're trying to  do cross-platform development, for instance).

Here are the settings for ARCHOS:

In almost all other cases, ARCH = `uname -m` and OS = `uname -s`. You can run the two scripts by hand to verify that the ARCH, OS, and ARCHOS variables will be set correctly.

Third-party applications

The Galaxy Communicator distribution requires gcc and GNU make. We also recommend using GNU mkdir and GNU ar for best results. Sources for the GNU libraries and tools can be obtained from GNU: Python 1.5 or later with Tkinter support is recommended for a number of the MITRE demos, examples and utilities. Python is available from www.python.org: We have tested the Python bindings with distributions up to 2.2, and we believe that they still work, but we haven't upgraded our day-to-day development to the current versions of Python yet.

New configuration method

The new configuration method works basically like this:
% cd templates
% ./configure <args>
% cd ..
% make
The possible arguments to configure are described below.

The first thing the configure script will do is compute the appropriate values for your architecture and operating system. Then, the configure script will check your environment for a range of features, and generate two files which it will place in templates/<arch>-<os>. The first, config.make, contains compilation and configuration settings which you may change after you run configure, if you have to (for example, you may want to enable the Python bindings, but forget to pass the appropriate arguments to configure to do so). The second, GC_config.h, is a header file which sets the appropriate compilation flags for your platform; do not edit this file.

Old configuration method

The old method does not allow you to pass arguments to configure, at least in its simplest form (there's a way to do it which we'll describe below). The old configuration method works as follows:
% cd templates # optional
% make site-init # invokes the configure script, among other things
% cd .. # if you did cd templates
% make
After it runs configure, make site-init will exit to allow you to make your changes to templates/<arch>-<os>/config.make before system compilation.

Arguments to configure and contents of config.make

The file config.make contains all the configuration information you will need. It is organized into two main sections, one for the core distribution and the other for MITRE extensions such as the examples and programming language bindings. Each section is arranged into a series of steps. All the documentation for these steps is also found in config.make. All of the settings which are user-settable are also controllable using the configure script.

Core distribution

Step config.make variables configure arguments description
Configure your csh environment ARCHOS_PREFIX (none) The Communicator system mirrors the compiler variables in some of the csh shell scripts it uses. In some cases, the variable names clash with the environment on the installed machine. By default, we enable a prefix for these variables using the ARCHOS_PREFIX variable, which is GALAXY_ by default; this setting makes the csh variables GALAXY_ARCH, GALAXY_OS, and GALAXY_ARCHOS. Change this prefix if you prefer.
Configure your utilities CC, AR, MKDIR, CHMOD, etc. (none) Here, you have the opportunity to change the values of CC, AR, MKDIR, CHMOD, etc. based on your platform. These settings should be right in almost all cases.
Configure your compiler options CFLAGS_O, CFLAGS_P, CFLAGS_D, etc. (none) Here, you have the opportunity to modify your CPPFLAGS, CFLAGS, etc. for your platform. Most of these settings should be correct. You may wish to change the optimization flags for CFLAGS_O (normal compilation), CFLAGS_D (debug compilation) and CFLAGS_P (profile compilation).
Configure shared libraries SHARED_LIBS --enable-shared If you want to compile the Communicator libraries as shared libraries, use the --enable-shared argument to configure or uncomment this line. This will significantly reduce the size of your executables; however, the executables will then depend on the presence of the shared libraries to run. The location of the shared libraries is automatically compiled in to the executables by the Makefile templates.
Configure Purify and Insure INSURE, PURIFY --with-insure=<insure_binary>,
--with-purify=<purify_binary>
MIT's Makefile template has built-in support for make purify and make insure", which will create instrumented executables for Rational's Purify tool and Parasoft's Insure tool. These settings are disabled by default. If you have either of these tools and want to make use of the MIT Makefile support, use the --with-insure or --with-purify arguments to configure or uncomment (and perhaps modify) the appropriate lines.
Choose your Hub scripting module (none) (none) By default, the distribution is configured to use the MIT Hub scripting module. Currently, the Hub will not compile without at least some scripting module provided. You can probably write your own, but we haven't documented that process yet. If you comment out COMPILE_MIT in the next step, the scripting module will still be compiled.
Enable contributions COMPILE_MIT, COMPILE_MITRE --enable-MIT-extensions,
--enable-MITRE-extensions
MIT has contributed useful libraries, and MITRE has contributed examples, tools, etc. Both are compiled by default, if present in the distribution. You may disable either or both by using the appropriate arguments to configure (e.g., --enable-MIT-extensions=no or --disable-MIT-extensions) or commenting out the COMPILE_MIT or COMPILE_MITRE variables.

MITRE extensions

If you have commented out COMPILE_MITRE, you may ignore this section.
 
Step config.make variables configure arguments description
Locate your xterm program XTERM --with-x,
--with-xterm=<xterm_binary>
MITRE uses xterm for process monitoring under some circumstances.
Locate your Java installation JDK_HOME --with-jdk=<dir_above_bin/javac> MITRE uses Java for the Communicator Java bindings and Java examples. The MITRE Java bindings require at least JDK 1.2.
Enable Python bindings and examples PYTHONBIN, PYINCLUDE --with-python=<python_executable>,
--with-pycppflags=<cmdline_args_to_cpp>
If you want to enable the MITRE Python bindings, servers and demos, use with --with-python argument to configure or uncomment PYTHONBIN and set it to the appropriate path. Communicator requires Python 1.5 or later. Your Python installation must be built with Tkinter (Python's bindings for Tcl/Tk).

Note: As of 3.0, the Python bindings use C wrappers around the core Galaxy Communicator library. In order to compile Python, you must have PYINCLUDE or the --with-pycppflags argument to configure set to the include flags which provide the location of the Python header files (typically, something like -I/usr/include/python1.5). On Linux, you may have to install the python-devel RPM.

Enable Allegro CL bindings and examples ALLEGROBIN --with-allegro=<allegro_executable> If you want to enable the MITRE Allegro Common Lisp bindings, servers and demos, use the --with-allegro argument to configure or uncomment ALLEGROBIN and set it to the appropriate path. Communicator requires Allegro 5.0 or later.

Storing and reusing your configuration information

By default, when you run the configure script and you provide arguments, those arguments are cached in the file templates/<arch>-<os>/config.args. The --with-cached-args argument to the configure script will reuse these stored arguments (and also won't overwrite config.args). When you call configure via make (as, for instance, in the old configuration method), the --with-cached-args argument is always used, so if you run configure by hand once, the settings will be available to you no matter which configuration method you use subsequently (in case you need or want to reconfigure, or the compilation script detects a need to run the configuration script again).

At MITRE, we cache our config.make and config.args files for each platform and insert them instead of running either configuration process. If you do this, you can use make partial-site-init in the templates subdirectory to generate the remainder of the site files without overwriting config.make or config.args.

Compilation

To compile the entire distribution:
% cd $ROOT_DIR (the top of the distribution tree)
% make
make will automatically stop to allow editing of newly-created site configuration files. This will compile the Hub and support libraries, all the MIT servers, and all the MITRE examples, servers, demos and tools.

Each directory supports the following targets:

There are also five thread-specific targets, one for each non-threaded target: If threads are enabled in a Makefile, these targets will create threaded versions of the library or executable. If threads are not enabled, the targets will default to the non-threaded correspondents, in order to keep the recursive compilation from breaking.

Additional toplevel targets are listed below:

Setting up the tutorial

If you intend to work through the tutorial, the following two points are crucial:

Windows configuration and build

As of version 4.0, the entire Communicator distribution works on Windows NT and later. It may or may not work on Windows 98 or 95.

ARCHOS on Windows

Since there's only one Windows, we don't need to determine the value of ARCHOS programmatically. It is fixed as x86-nt. Also unlike Unix, we do not provide the ARCH and OS values as compiler preprocessor flags; we use the WIN32 flag, already provided.

Third-party applications

The Galaxy Communicator distribution is known to build with Microsoft Visual Studio version 6.0. We do not know of any attempts to build it with, e.g., gcc under Cygwin.

Python 2.0 or later with Tkinter support is recommended for a number of the MITRE demos, examples and utilities. Python is available from www.python.org: Note that this is a more recent version of Python than the oldest possible Unix version. This is because some crucial cross-platform improvements to Python which our Windows port relies on did not occur until version 2.0. If you download the precompiled binaries for Windows, you'll need Python 2.2.

You'll also need to install Mark Hammond's Windows extensions:

These extensions are required by the Python process monitor.

Configuration and compilation

We strongly recommend that you download the precompiled Windows binaries for Galaxy Communicator. This package can be accessed from  the Communicator download page, and contains all the executables for the Hub, examples, demos and utilities. However, if you would like to build the distribution yourself, we provide a Microsoft Visual Studio workspace GC.dsw at the root of the Galaxy Communicator source distribution. You should be able to build the distribution straighforwardly using it.

Threads are enabled by default in the Windows distribution.

On Unix, we generate a large number of shell scripts to hide some of the details of execution from the user. We do not provide the analogous batch files on Windows. While this is inconvenient in some ways, it also simplifies the configuration of the distribution considerably. Here are the only required distribution steps:

Setting up the tutorial

If you intend to work through the tutorial, the following two points are crucial:

Installation

There's no make install for the Galaxy Communicator infrastructure. Once you compile, you're done.

Note: In some ways this is convenient, but in other ways in can be an obstacle. This is because in some cases, it's necessary to compile absolute paths into executables. For example, if we want to avoid environment variables like GC_HOME, we must encode the location of the compiled distribution into shell scripts which run Python, Allegro or Java servers, so that these servers know where to find the various Galaxy Communicator code libraries which implement the Galaxy Communicator infrastructure for that language. Similarly, if we want to avoid the LD_LIBRARY_PATH environment variable for shared libraries, it's necessary to compile the location of the shared libraries into Galaxy Communicator C executables.

What this means is that in many cases, these executables can't be moved. Any installation process would have to address these issues; it's straightforward to see how to address it for the shell scripts, but it's something of a mystery how to address it for the C executables short of relinking them. And even then, the resulting installation also couldn't be moved. Therefore, we've chosen not to worry about the complexities of make install.


Cross compilation (Unix)

Because of the changes to the configuration process in version 3.3, we've had to make significant changes to the experimental Unix support for cross-compilation, introduced in version 3.1.

This support is now enabled via an environment variable visible to configure and make called GC_CROSS. This variable is the name of a /bin/sh file which contains settings for the host variable (which should be the <arch>-<os> value for the platform being compiled for), for any variables in config.make which must be specified for the target platform and can't be derived from the environment (such as CC), and for some special cross-compilation variables whose values couldn't be derived without executing code. The value of GC_CROSS must be an absolute pathname; configure will refuse to run otherwise.

For instance, for compiling for the StrongARM processor running Linux, we provide the following settings. This sample configuration can be found in templates/cross_compilation/armv4l-linux-config.sh.

# This is a /bin/sh file which sets variable values.
# It is sourced in two places.
# It must always have a value for host. This value should
# be a value for ARCH-OS.
host=armv4l-linux
# We need to set the following tools: CC, CXX, AR.
CC=/usr/local/arm-linux/bin/arm-linux-gcc
CXX=/usr/local/arm-linux/bin/arm-linux-g++
AR="/usr/local/arm-linux/bin/arm-linux-ar crsv"
# These variables are special cross-compilation variables which could not
# be derived without executing code.
ac_cc_sizeof_char=1
ac_cc_sizeof_short=2
ac_cc_sizeof_int=4
ac_cc_sizeof_long=4
ac_cc_sizeof_long_long=8
ac_cc_sizeof_float=4
ac_cc_sizeof_double=8
ac_cc_c_bigendian=no


The special cross-compilation variables shown here, like host, are required; if configure concludes that it's cross-compiling and it doesn't find these values, it will refuse to run. As a convenience, we've provided a C file, templates/cross_compilation/configure_values.c, which will compute and print out these settings. Just run your cross-compiler on that file, run the resulting executable on the target platform, and paste the output directly into your GC_CROSS file. You only need to do this once.

If the value of GC_CROSS is visible to configure, it will create the appropriate subdirectory in templates to hold the configuration information. After configure runs, you'll have the usual opportunity to edit config.make. For the StrongARM, we edit templates/armv4l-linux/config.make to set the STRIP makefile variable to arm-linux-strip to reduce the size of the executables.

When you compile after configuring, make sure that the value of GC_CROSS is visible to make. If it is, make will use the correct config.make and create and use the appropriate set of subdirectories.


License / Documentation home / Help and feedback
Last updated August 16, 2002