1.2 File Organization

Ptolemy is distributed with source code. The complete distribution even includes the compiler we use (g++, from the Free Software Foundation), Tcl/Tk, and vem, programs that were developed quite independently, but upon which Ptolemy relies. The distribution also includes a large number of demonstrations. Perusing the demonstrations can be an excellent way to get familiar with the system. Perusing the source code is by far the best way to understand the system. At a minimum, anyone wishing to write new stars should read the source code for a few of the built-in stars.

1.2.1 Ptolemy environment variables

The root of the Ptolemy tree is often installed in the home directory of a fictitious user called ptolemy. If the installation follows this model at your site, you can find the Ptolemy code with the following command:

cd ~ptolemy If your installation does not have a user named ptolemy, then you must find out where your system administrator has installed the system, and set an environment variable called PTOLEMY to point to this directory. For instance, if your system administrator installed Ptolemy in /users/ptolemy, then you should issue the following command:

setenv PTOLEMY /users/ptolemy $PTARCH is an environment variable representing the architecture on which you are running, and has one (or more) of the following values: sun4, sol2, or hppa, for Sun (under Sun O/S), Sun (under Solaris 2.X), and HP machines respectively. There are a few other possible values for the PTARCH variable as well. There might be variations like


sol2.cfront


hppa.cfront

to store an object tree created by the Cfront C++ compiler or some other non-g++ compiler.The script $PTOLEMY/bin/ptarch will return the architecture of the machine on which it is run. For example, if you were on a machine running SunOS4.1.3, you would type:

setenv PTARCH sun4 You can use the following fragment in your .cshrc file to set $PTOLEMY and $PTARCH. The $PTOLEMY/.cshrc file contains the fragment below and many other csh setup commands you may find useful.

setenv PTOLEMY /users/ptolemy
if (! $?$PTARCH) setenv $PTARCH \Q $PTOLEMY/bin/ptarch\Q
set path = ( $PTOLEMY/bin $PTOLEMY/bin.$PTARCH $path ) Note that if you are using a prebuilt Gnu compiler that you obtained from the Ptolemy project, you must either place the Ptolemy distribution at /users/ptolemy, or you must set certain environment variables so that the Gnu compiler can find the necessary pieces of itself. Appendix A, Installation and Troubleshooting of the Ptolemy User's Manual discusses these variables in detail. The variables change with different releases of the compilers, so we do not document them here. The User's Manual also documents other useful environment variables, such as LD_LIBRARY_PATH.

For every directory under the src tree (see figure 1-2) that contains source code that is compiled, there is a corresponding directory under the obj.$PTARCH tree. Many developers find it convenient to set the following aliases:

alias srcdir `cd \Qpwd | sed "s?/obj.$PTARCH/?/src/?"\Q'
alias objdir `cd \Qpwd | sed "s?/src/?/obj.$PTARCH/?"\Q' For your convenience, these can be found in the file

$PTOLEMY/
.alias

. They make it easy to move between the source directory and the corresponding object directory. For example, if you are running on a Sun machine running Solaris 2.4,

% cd $PTOLEMY/src/kernel
% pwd
/users/ptolemy/src/kernel
% objdir
% pwd
/users/ptolemy/obj.sol2/kernel
% srcdir
% pwd
/users/ptolemy/src/kernel
%

1.2.2 Directory Structure

The documentation (usually) refers to the root of the Ptolemy directory tree as $PTOLEMY, but occasional slips will refer to ~ptolemy. Below this root, you can find the directories indicated in figure 1-1.

The src directory is key to much of what this volume deals with. Its structure is shown in figure

1-2. Within the src directory, the kernel directory is most important. It contains all the classes that define what Ptolemy is. Second most important is the domains directory. Its structure is shown in figure

1-3. This directory contains one subdirectory that defines each of the domains distributed with Ptolemy. Each domain directory contains at least the subdirectories shown in figure 1-4. If you are going to write stars for the SDF domain, for example, then you would be well advised to look at a few examples contained in the directory $PTOLEMY/src/domains/sdf/stars.

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 cd to $PTOLEMY 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 makefiles are all designed to be run from the obj.$PTARCH tree so that object files from different platforms are kept separate (when you run make in the $PTOLEMY top level, the appropriate obj.$PTARCH tree is selected for you automatically).

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

There are three primary Ptolemy binaries:

pigiRpc The graphical version that uses vem as a front end. pigiRpc contains an interface to Octtools, the package that is used to store facets. When you run pigi, you actually run a script called $PTOLEMY/bin/pigiEnv.csh which calls vem which, in turn, starts up pigiRpc.
ptcl A prompt version that contains most of the functionality in pigiRpc not including the Tk stars. ptcl does not contain an interface to Octtools
tysh The Tycho shell version, which is similar to pigiRpc, except that tysh does not contain an interface to Octtools. Note that Tycho can be run from a basic itkwish binary that contains no Ptolemy functionality. Each of the three binaries above has three different versions that contain different functionality. Below we only list the different version of pigiRpc, but ptcl and tysh have similar versions.
pigiRpc This binary contains all of the domains, so it is the largest binary.
pigiRpc.ptrim This binary contains SDF, DE, BDF, DDF and CGC domains only.
pigiRpc.ptiny This binary contains SDF (no image stars) and DE domains only. Each of the above versions can also be built as a .debug version that contains debugging information. The file $PTOLEMY/mk/ptbin.mk contains rules to build the above binaries in combination with debugging and other features. The file $PTOLEMY/mk/stars.mk contains rules that indicate dependencies between domains and other features.