A.4 Installation

Ptolemy is a large software system that relies on a properly configured software environment. This section will take you step by step through the installation of Ptolemy, including all of the basic information required to get from an FTP archive or distribution tape to being able to run the system. Note that this information may have changed after the manual was printed. Thus, the most up-to-date instructions are included in $PTOLEMY/doc/html/install.

Ptolemy is distributed in several forms:

The Ptolemy group provides Ptolemy and Gnu tools binaries for Solaris2.5.1, SunOS4.1.3 and HPUX10.20. We use these three platforms for in-house development and testing, so they are more stable than other platforms.
We also make binaries for other architectures available. These binaries have been contributed by users and have not been tested in-house. You can find these binaries at http://ptolemy.eecs.berkeley.edu/ptolemyclassic. The list of contributed binaries varies, but usually includes Linux, AIX and DEC Alpha.
If your machine is not one of the three primary platforms, and we do not have contributed binaries for it, then you will have to do a compile from scratch. For more information see "Rebuilding Ptolemy From Source" on page A-10.

Ptolemy is available via the Ptolemy Web site at http://ptolemy.eecs.berkeley.edu. The Ptolemy releases can be found under the Releases link. The Ptolemy release can also be found on the Ptolemy ftp site at http://ptolemy.eecs.berkeley.edu/ follow the instructions in the README file, and be sure to download in binary mode.

Untarring the distribution

Go to the directory where you either saved the downloaded *.tar.gz files. These files have been compressed with the Gnu gzip program, a compression program from the Free Software Foundation. In order to uncompress the files, you need the program gzcat.The gzcat program is available via anonymous FTP from http://ptolemy.eecs.berkeley.edu/ptolemyclassic/gnu/src/. Now proceed as follows:

: a. gzcat pt-0.7.doc.tar.gz | ( cd ~ptolemy/..; tar xf - )

This uncompresses the documentation, changes directory to the parent of the ptolemy user, and then creates all of the documentation files.

: b. gzcat pt-0.7.src.tar.gz | ( cd ~ptolemy/..; tar xf - )

This uncompresses the src tar file and creates the source files. You must not skip this step. Ptolemy depends on these files being present. Note that you may get a few warning messages during this and the following step about the tar program not being able to create some directories because they already exist. This is expected (the same directory is mentioned in several of the tar files), so you need not worry.

: c. If you are running the SunOS4.1.3 version:
gzcat pt-0.7.sun4.tar.gz | ( cd ~ptolemy/..; tar xf - )(If you are running SunOS4.1.3 /bin/tar, and you see messages about
tar: read error: unexpected EOFthen see "EOF messages while using tar on Suns" on page A-23)
If you are running the HPUX 10.20 version:
gzcat pt-0.7.hppa.tar.gz | ( cd ~ptolemy/..; tar xf - )If you are running the Solaris2.5.1 version:
gzcat pt-0.7.sol2.5.tar.gz | ( cd ~ptolemy/..; tar xf - )If you are running another platform for which a binary has been provided:
gzcat pt-0.7.platform.tar.gz | \ ( cd ~ptolemy/..; tar xf - )This uncompresses the binaries and creates the executable files. Note that is possible to install binaries for multiple platforms on the same file system because different directories are used for each set of binaries. Just execute whichever of the above commands apply.
: d. (Optional) If you are planning on porting Ptolemy, you will need the other sources file:
gzcat pt-0.7.other.src.tar.gz| \ (cd ~ptolemy/..; tar xf - )The other.src tar file includes sources to a subset of Octtools (including vem), Tcl/Tk and xv. If you wish to rebuild Ptolemy completely from source, then you will need this tar file. Alternatively, you may be able to use the Octtools libraries from a binary tar file.
If you are planning on recompiling Ptolemy, but are really short on disk space, and you already have Tcl/Tk (comes with most Linux installations) then you can download pt-0.7.oct.src.tar.gz instead of pt-0.7.other.src.tar.gz. Note that this file has not been extensively tested. For more information, see "Ptolemy and Tcl/Tk" on page A-13
: e. (Optional) You no longer need the *.tar.gz files that your got from the Web site or the tape. Remember to delete these files to free up disk space.
: f. (Optional) The X11 program xv is used by some of the image processing demos. If you already have a version of xv, or you don't plan on doing any image processing, you can also remove the xv binary in $PTOLEMY/bin.$PTARCH/xv.

A.4.6 Special considerations for use under OpenWindows

Ptolemy was developed using the X11R4 through X11R6 distributions from MIT. Although Ptolemy runs fine under OpenWindows 2, there are problems with running the Ptolemy graphical interface with OpenWindows version 3.0 under SunOS4.x. Some users have had no problems at all, but others have had intermittent problems such as "bad match" errors. We believe this may be a problem with the X-server supplied with the OpenWindows 3.0, but the error is elusive and we have not yet tracked it down. These problems seem not to occur in OpenWindows 3.3 and later (OW3.3 was distributed with Solaris2.3).

In order for all utilities included with this distribution to work under OpenWindows 2, you must install the shared libraries for the Athena widgets (the freely redistributable widget set from the MIT X11 distribution), which are provided with this distribution under the $PTOLEMY/athena.sun4 directory. To install them, become root and copy all files in that directory into /usr/openwin/lib (or, if you have installed OpenWindows in a non-standard place, into $OPENWINHOME/lib). If you do not wish to do this, you could leave them in place and have every Ptolemy user change their LD_LIBRARY_PATH environment variable to search ~ptolemy/athena.sun4 before /usr/openwin/lib. Consult the Unix manual entry for the ld program to learn more about LD_LIBRARY_PATH.

After installation, the $PTOLEMY directory will contain several scripts for starting up X11R6 (Xrun), OpenWindows with olwm (Xrun.ow), or OpenWindows with twm (Xrun.ow.twm).

If only have OpenWindows, and not X11R5 or X11R6 and you plan on rebuilding from source, you may need the libraries in athena.sun4. athena.sun4 is part of the pt-0.7.sun4.tar.gz tar file.

A.4.7 Gnu Installation

If you are planning on extending Ptolemy by writing your own stars and you are using prebuilt binaries, you will need to install the same compiler that was used to build the prebuilt binaries. In particular, Ptolemy supports dynamic linking of newly defined stars. Dynamic linking will not work, however, if the new stars are compiled with a different version of the compiler than that used for the rest of the system. Thus, you must either use the same compiler that we used for this distribution of Ptolemy or you must recompile the entire Ptolemy system. Note that this is not a complete set of Gnu software.

It is also possible to build Ptolemy with other, non-Gnu C++ compilers, such as SunSoft's C++ compiler. We have built this release of Ptolemy with the following compilers:

sol2.5.cfront

Sun CC, version 4.0 (native) for Solaris2.5.1

hppa.cfront

HP-UX CC version 4 ¹ This release has also been built by others with SGI Delta-C++ for Irix5.3 (irix5.cfront).

We do not distribute these non-Gnu C++ binaries. If you choose to use a non-Gnu C++ compiler, you must completely rebuild Ptolemy. The libraries in the tar files were produced by the Gnu C++ compiler and are not interoperable with code from other compilers. When you completely rebuild Ptolemy, you must be sure to first remove all previously compiled object files. Note that to compile Ptolemy with a non-Gnu C++ compiler, you will still need to use Gnu make.

Ptolemy 0.7 was built with gcc-2.7.2.2 and libg++-2.7.2. Note that Ptolemy uses the gcc and libg++ shared libraries, if you are using your own version of gcc and libg++, it must have been configured with --enable-shared. For further information, see "Can I use my own version of gcc and libg++?" on page A-28.

The Gnu compiler is dependent upon where it was built. The executable that we supply assumes that the compiler is installed in a directory called /users/ptolemy. If you do not wish to rebuild the compiler, then you must either install Ptolemy in this directory, or create a symbolic link from this directory to the actual directory in which Ptolemy is installed. If you cannot install such a link, then you will still be able to run Ptolemy, but you may not be able to dynamically link new stars or recompile Ptolemy.

Even if your Ptolemy installation in not in /users/ptolemy and even if you cannot create a link from /users/ptolemy to the actual location of Ptolemy, you may still be able to use this compiler by setting Gnu environment variables before using the compiler. We provide a script in $PTOLEMY/bin/g++-setup that sets these variables. If you will always be using the prebuilt Gnu compiler shipped with Ptolemy with these variables, you may want to edit your copies of $PTOLEMY/bin/pigiEnv.csh and $PTOLEMY/bin/ptcl and add the following line:

source $PTOLEMY/bin/g++-setup

You should not set these variables if you are using a version of the Gnu compiler that is different from the version that we are shipping. If you are using a different version of the Gnu compiler, then you will probably need to do a complete rebuild for dynamic linking to work. Please note that setting the environment variables does not work in all installations and that creating a link is better. If you are running under SunOS4.1.x and are using the prebuilt Gnu binaries, please see "Sun OS4 specific bugs" on page A-39. Here are the Gnu environment variables that worked for Solaris2.5.1:

setenv GCC_EXEC_PREFIX \ $PTOLEMY/gnu/$PTARCH/lib/gcc-lib/$PTARCH/2.7.2/ setenv C_INCLUDE_PATH $PTOLEMY/gnu/$PTARCH/lib/gcc-lib/$PTARCH setenv CPLUS_INCLUDE_PATH \ $PTOLEMY/gnu/$PTARCH/lib/g++-include:\ $PTOLEMY/gnu/$PTARCH/$PTARCH/include setenv LIBRARY_PATH $PTOLEMY/gnu/$PTARCH/lib

The above assumes that the environment variable PTOLEMY is set to the name of the actual installation directory of Ptolemy, and PTARCH is set to the type of workstation (such as sun4, hppa, etc.).

To install the Ptolemy Gnu subset, proceed as follows:

: a. Change to the directory that contains the files you downloaded via the Web.

You should now have a pt-0.7.gnu.xxx.tar.gz file (where xxx is an architecture supported by Ptolemy such as sun4, hppa, or sol2) in your current directory.

: b. If you are running on a SunOS4.1.3 then:
gzcat pt-0.7.gnu.sun4.tar.gz| \ (cd ~ptolemy/..; tar xf - )(If you are running SunOS4.1.3 /bin/tar, and you see messages about
tar: read error: unexpected EOFthen see "EOF messages while using tar on Suns" on page A-23)
If you are running on an HP workstation under HPUX10.20 then:
gzcat pt-0.7.gnu.hppa.tar.gz | \ (cd ~ptolemy/..; tar xf - )
If you are running the Solaris2.5.1 version:
gzcat pt-0.7.gnu.sol2.5.tar.gz | \ ( cd ~ptolemy/..; tar xf - )If you are running another platform for which we provide a tar file:
gzcat pt-0.7.gnu.platform.tar.gz | \ ( cd ~ptolemy/..; tar xf - )Note that these are single commands split over two lines for readability. Do not type a space after the backslash at the end of the first line, just press Return.
: c. There is also a Gnu tar file which contains the Gnu source code. You will save disk space and Ptolemy will still run if you do not untar the Gnu source code. However, if you plan to redistribute the Gnu tools (give them to anyone else) you must include sources, according to the Gnu Public License. Therefore, it may be a good idea to keep these source files around.
If you want to untar the Gnu source code:
gzcat pt-0.7.gnu.tar.gz | ( cd ~ptolemy/..; tar xf - )
: d. You no longer need the *gnu*.tar.gz files that your got from the Web site or the tape. You may delete these files to free up disk space.

A.4.8 Testing the Installation

Note that the following tests assume that you have created a ptolemy user and installed the system there. One advantage of such an installation, is that the ptolemy user already has a working .cshrc and .login file to make start-up easier.

To test Ptolemy, assuming you have set up a ptolemy user:

: a. login as ptolemy

If the X server is not already running, the .login script will attempt to start it. If your installation is different from ours, you may need to modify .login to work at your site (in particular, you may need a different path variable).

: b. cd demo
: c. pigi

Follow instructions in "Starting Ptolemy" on page 2-2.

If you have not set up a ptolemy user, then set your PTOLEMY environment variable to point to the installation directory. If your Ptolemy distribution is at /users/myptolemy, under the C shell, you would type:

setenv PTOLEMY /users/myptolemy

If you use a shell other than csh, consult your documentation on how to set environment variables. The next steps are to change to the Ptolemy directory and to start up Ptolemy:

cd $PTOLEMY

bin/pigi

Note that the ptolemy user provides a model of a user properly configured to run Ptolemy. All the dot files (.cshrc, .login etc. ) in the home directory are set up according to the tastes of the Ptolemy authors and according the standard use of windowing software in the Ptolemy development group.

A.4.9 Rebuilding Ptolemy From Source

If you wish to rebuild Ptolemy from source (this step is recommended if you plan to do major development work, such as adding a new domain), it is simply a matter of editing the appropriate configuration file and typing make. This is explained in a bit more detail below. Note that to rebuild completely from source, you need the pt-0.7.other.srcs.tar.gz tar overlay, as well as the pt-0.7.src.tar.gz tar overlay. If you are having problems rebuilding, you may want to look over "Ptolemy will not recompile" on page A-27.

To do a build of all of Ptolemy using the Gnu compiler from the distribution, first make sure that either Ptolemy is installed in /users/ptolemy, or that there is a symbolic link from /users/ptolemy to the installation directory. Alternatively, you can try setting the four environment variables described in "Gnu Installation" on page A-7.

$PTOLEMY should point to the location of the installation so that the toplevel makefile is at $PTOLEMY/makefile. $PTARCH should be set to the name of the architecture you are running. $PTARCH is used to select a makefile from $PTOLEMY/mk/config-$PTARCH.mk. The script $PTOLEMY/bin/ptarch will return the architecture of the machine on which it is run.

Next make sure that $PTOLEMY/bin.$PTARCH and $PTOLEMY/bin are both in your path ($PTOLEMY/bin.$PTARCH is where the compiler is installed. $PTOLEMY/bin is where certain scripts used to build star lists are located).

Then proceed as follows:

: a. setenv PTOLEMY /users/ptolemy
: b. setenv PTARCH `$PTOLEMY/bin/ptarch`
: c. set path = ($PTOLEMY/bin $PTOLEMY/bin.$PTARCH $path)
: d. cd $PTOLEMY (or cd /users/ptolemy)

The toplevel makefile at $PTOLEMY/makefile can rebuild some or all of Ptolemy.

To rebuild the Gnu tools, Tcl/Tk, xv, Octtools and Ptolemy, type make bootstrap. This target requires the following files: pt-0.7.gnu.tar.gz, pt-0.7.other.src.tar.gz and pt-0.7.src.tar.gz.
To rebuild Tcl/Tk, xv, Octtools and Ptolemy, type make everything. This target requires the following files: pt-0.7.other.src.tar.gz and pt-0.7.src.tar.gz.
To rebuild just Octtools and Ptolemy, type
make install_octtools install.This target requires the following files: pt-0.7.other.src.tar.gz and pt-0.7.src.tar.gz. (If you are short on disk space, you may be able to download pt-0.7.octtools.tar.gz instead of pt-0.7.other.src.tar.gz).
To rebuild just Ptolemy, type make install.This target requires the following files: pt-0.7.src.tar.gz.

An easier approach is to log in as "ptolemy" (assuming you created such a user). The path and environment variables are already set up for this user. Yet a third approach is to make use of the setup for this user, as follows:

: a. cd $PTOLEMY (or cd /users/ptolemy)
: b. edit $PTOLEMY/.cshrc to define PTOLEMY correctly
: c. source $PTOLEMY/.cshrc
: d. make install

If you wish to customize your installation, you may have to edit the configuration files. These files are in $PTOLEMY/mk. The configuration files are all named config-$PTARCH.mk where the $PTARCH is something like sun4 for a Sun Sparc system running SunOS4.1.3 or hppa for an HP Precision Architecture machine. They are included by other makefiles and define symbols specifying compiler flags, the directory where X include files are located, etc.

If you wish to rebuild using a non-Gnu C++ compiler rather than g++, use config-sol2.5.cfront.mk as a starting point to produce your configuration file. This has been tested with Sun CC version 4.0 with Solaris2.5.1. For other platforms, you may need to do some tweaking. See config-hppa.cfront.mk for using HP CC version 4, and config-irix5.cfront.mk for using SGI Irix CC. Note that the term "cfront" is historical, and that not all of these compilers are actually cfront based. We use the term cfront to refer to non-Gnu C++ compilers.

To rebuild the system, first adjust the configuration parameters in the appropriate configuration file. For example, if you are using the Gnu tools on a Sun-4 running SunOS4.1.3, then you will need to adjust the config-sun4.mk file.

Next, run make. The Ptolemy source files include extensions found only in Gnu make, which is included in the Gnu subset of the Ptolemy distribution. (Make sure that the Gnu tools are installed correctly.) Sun make will fail on certain makefiles that have Gnu make extensions. See $PTOLEMY/src/gnu/README for a discussion of Gnu make compatibility.

You will get some warnings from the compiler, but the following warnings can safely be ignored:

any warning about file_id defined but not used.
any warning about SccsId defined but not used
variable might be clobbered by longjmp or vfor'
This warning may be a problem under heavy optimization. We will work to remove these from future releases.
many warnings about cast discards const.

Details of how Ptolemy is built and the general layout

Below we describe some of the details of how Ptolemy is built from sources.

To build Ptolemy, you must have your PTOLEMY and PTARCH environment variables set. PTOLEMY is set to the location of the Ptolemy tree, PTARCH is set to the name of the machine architecture (the script $PTOLEMY/bin/ptarch will return the architecture of the machine on which it is run). The directory $PTOLEMY/mk contains master makefiles that are included by other makefiles (The makefile include directive does this for us). $PTOLEMY/mk/config-$PTARCH.mk refers to the makefile for the architecture $PTARCH. For instance, $PTOLEMY/mk/config-sun4.mk is the makefile that contains the sun4 specific details.

When you change to the $PTOLEMY directory and type make, $PTOLEMY/makefile contains a rule that checks to see if the directory $PTOLEMY/obj.$PTARCH exists. If this directory does not exist, then make runs the command csh -f MAKEARCH, where MAKEARCH is a C shell script at $PTOLEMY/MAKEARCH. MAKEARCH will create the necessary subdirectories under $PTOLEMY/obj.$PTARCH for $PTARCH if they do not exist.

We split up the sources and the object files into separate directories in part to make it easier to support multiple architectures from one source tree. The directory $PTOLEMY/obj.$PTARCH contains the platform-dependent object files for a particular architecture. The platform-dependent binaries are installed into $PTOLEMY/bin.$PTARCH, and the libraries go into $PTOLEMY/lib.$PTARCH. Octtools, Tcl/Tk, and Gnu tools have their own set of architecture-dependent directories. The Ptolemy Programmer's Manual describes the directory tree structure in more detail.

We are able to have separate object and source directories by using the make program's VPATH facility. Briefly, VPATH is a way of telling make to look in another directory for a file if that file is not present in the current directory. For more information, see the Gnu make documentation, in Gnu Info format files in $PTOLEMY/gnu/common/info/make-*.

Ptolemy and Tcl/Tk

Ptolemy0.7 uses itcl2.2, which is an object-oriented extension to tcl (Tool Command Language) and tk. itcl2.2 includes a modified version of tcl7.6 and tk4.2. If you have itcl2.2 already installed, you may use your installed version. You will need to either edit
$PTOLEMY/mk/config-default.mk or create the proper links in $PTOLEMY/tcltk.

In theory, it is possible to build Ptolemy0.7 without itcl2.2. However, without itcl2.2, Tycho, the syntax manager and the Gantt chart facilities will not work. There may be other features that fail to operate. We strongly encourage you to build with itcl2.2.

In previous releases, the layout of the $PTOLEMY/tcltk directory was such that Tcl and Tk were in separate directories so that upgrading Tcl and Tk could be done separately if necessary. In Ptolemy 0.7, we are using itcl2.2, the Tcl and Tk are under the $PTOLEMY/tcltk/itcl* directories. We have left separate $PTOLEMY/tcltk/tcl* and $PTOLEMY/tcltk/tk* directories so that we can easily support separate Tcl and Tk releases in the future.

$PTOLEMY/tcltk/itcl contains the architecture-independent Itcl directories include, lib and man. For instance, tcl.h might be at ~ptolemy/tcltk/itcl/include/tcl.h.
$PTOLEMY/tcltk/itcl.$PTARCH contains the architecture-dependent Itcl directories bin and lib. For instance, on the sun4, libtcl.a might be at ~ptolemy/tcltk/itcl.sun4/lib/libtcl.a.

Notes for building on the sol2.5 platform (Sun4s running Solaris2.5.1)

Solaris2.5.1 is not shipped with a C compiler, and the Gnu tar file we ship does not include absolutely everything necessary to build on a compilerless Solaris2.5.1 machine. Notably, bison may be necessary to compile the Gnu C compiler and the Ptolemy program ptlang. If, when you are building the Gnu C compiler, bison is called and you do not have it, try using the Unix touch command on the offending .c file. The tar files we distribute include ptlang.c, which is generated from ptlang.y, so you should not need bison to compile Ptolemy. You can get a fairly complete set of Gnu tools via anonymous ftp from ftp://ftp.uu.net/systems/gnu/solaris2.3/. See also http://www.sunfreeware.com

If you choose to compile Gnu gcc with SunSoft's cc, be sure that you are not using
/usr/ucb/cc. Otherwise, you may see errors while compiling gcc/protoize.c:

"/usr/include/sys/ucontext.h", line 25: syntax error before or at: stack_t

The solution is to place /opt/SUNWspro/bin in your path before /usr/ucb.

You will need/usr/ccs/bin in your path to pick up ar, lex and yacc.
If you are building gcc-2.7.2 under Solaris, you must have /bin in your path before
/usr/ucb. See $PTOLEMY/src/gnu/README for more information.
Under sol2.5.cfront, $OPENWINHOME must be defined to build xv since xmkmf relies on $OPENWINHOME. In the C shell, one would type:

setenv OPENWINHOME /usr/openwin

A.4.10 Freeing up Disk Space

If you are short on disk space, you can consider removing the following files

$PTOLEMY/src/domains/sdf/demo/ppimage (~1020 Kb). This file is used by some of the image processing demos.
If you rebuild and reinstall Ptolemy from source, you may remove the $PTOLEMY/obj.$PTARCH directory once you are done installing.
If you do not plan to rebuild Ptolemy from source, you can remove all the .cc, .c and .h files in the $PTOLEMY/src directory. Note that the $PTOLEMY/src directory contains the icons and interpreted Tcl code used in the user interface, so removing the src directory completely will prevent pigi from running.
If you are very short on space, you may want to run Ptiny, a version of Ptolemy that only contains most of the SDF and DE domains. Ptiny is available viaafrom ptolemy.eecs.berkeley.edu. Note that Ptiny might be from an older release than the current release of the main Ptolemy distribution.

A.4.11 Other useful software packages

Some parts of Ptolemy use other software packages. The packages below are all available on the internet. If you have internet FTP access, you can find lots of FAQs (Frequently Asked Questions) via anonymous FTP at pit-manager.mit.edu in /pub/usenet/news.answers.

The Utah Raster Toolkit (URT) is used by some of the Multimedia demos. Most of the URT utilities work with images in RLE (run-length encoded) format, so most of its utilities begin with the prefix rle such as is rletoppm. The original URT is available via anonymous FTP from ftp.cs.utah.edu in /pub/urt-*. Note that the original URT does not include configuration files for many modern platforms, including Solaris2.5.1. We have made URT sources and binaries for Solaris2.5.1 available via anonymous ftp from ptolemy.eecs.berkeley.edu in pub/misc/urt.
The following Gnu utilities are available via anonymous FTP from prep.ai.mit.edu. See the file /pub/gnu/GETTING.GNU.SOFTWARE on that site. For further information, write to:

Free Software Foundation
675 Mass Ave
Cambridge, MA 02139
USA

Ptolemy uses the following Gnu software:

ghostscript - PostScript previewer. Note that oct2ps can use ghostscript to generate Encapsulated PostScript (EPS).

gdb - needed for pigi -debug

gzip - Used to compress and uncompress files.

¹ On the HP, type "what /usr/bin/CC" to see what version you are running.