Top Up Prev Next Bottom Contents Index Search

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:

A.4.1 Location of the Ptolemy installation

The Ptolemy system uses the environment variable $PTOLEMY to locate the Ptolemy distribution. If you are rebuilding Ptolemy from sources without using any prebuilt Ptolemy binaries, then you can set $PTOLEMY to any location. If you are using prebuilt binaries, then there are a few issues concerning exactly to what value $PTOLEMY is set. The issues occur because certain facilities, such as shared libraries, the Gnu compiler and Tcl/Tk save certain pathnames at build time. If at run time, certain files cannot be found that were present at build time, then there will be various failures.

The Ptolemy binaries that we distribute were built with $PTOLEMY equal to
/users/ptolemy. If you can create a symbolic link from /users/ptolemy to your Ptolemy distribution, then you may find using the prebuilt binaries easier. If you cannot create a link and are using prebuilt binaries, then be aware of the following points:

A.4.2 Basic Ptolemy installation

First note the approximate disk space requirements for Ptolemy. The numbers below are for the Solaris version of Ptolemy, but other distributions are similar:

Important Note: Although we distribute binaries, you must also install the source tree in pt-0.7.src.tar.gz. Installing this src directory is not optional. The src directory contains the Ptolemy source code, but it also contains the icons and interpreted Tcl code used in the user interface. If you absolutely must discard the source code, you can remove all files under src with extensions .cc, .h, or .c. For more information, see "Freeing up Disk Space" on page A-14.

A.4.3 The ptolemy user

The preferred way to install Ptolemy involves creating a fictitious user with the userid ptolemy, together with a home directory for the ptolemy user. Using the binaries is easier if the ptolemy user's home directory is /users/ptolemy. Once the ptolemy user account has been created, log in or su to user ptolemy. If you do not wish to create a user called ptolemy, see below for an alternative.

A.4.4 Installation without creating a ptolemy user

The preferred installation technique, as indicated above, is to create a user called ptolemy. The reason for this is that running Ptolemy requires an appropriate user configuration. At minimum, the user's path must be set up properly. The ptolemy user is also configured to run an X window manager (twm) with suitable X resources that are known to work well. In troubleshooting an installation, having the ptolemy user properly configured can be very valuable.

Ptolemy can be installed without creating a ptolemy user. If you do this, every Ptolemy user must set a PTOLEMY environment variable to point to the root directory of Ptolemy. The installation is the same as below, except that ~ptolemy is replaced with $PTOLEMY.

A.4.5 Obtaining Ptolemy

Ptolemy is available via the Ptolemy Web site at The Ptolemy releases can be found under the Releases link. The Ptolemy release can also be found on the Ptolemy ftp site at 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 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 EOF
then 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:

Sun CC, version 4.0 (native) for Solaris2.5.1
HP-UX CC version 41 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- 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 C_INCLUDE_PATH $PTOLEMY/gnu/$PTARCH/lib/gcc-lib/$PTARCH

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 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 EOF
then 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:

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-$ 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.

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-$ 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 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 for using HP CC version 4, and 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 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:

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-$ refers to the makefile for the architecture $PTARCH. For instance, $PTOLEMY/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/ 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.

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 See also

"/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.

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

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 in /pub/usenet/news.answers.

Free Software Foundation
675 Mass Ave
Cambridge, MA 02139

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.

Top Up Prev Next Bottom Contents Index Search

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

Copyright © 1990-1997, University of California. All rights reserved.