Top Up Prev Next Bottom Contents Index Search

1.3 Creating Custom Versions of pigiRpc

Ptolemy is an extensible system. Extensions can take the form of universes and galaxies, which are viewed by Ptolemy as applications, but they can also take the form of additional code linked to the Ptolemy kernel. New stars can be dynamically linked (see "Writing Stars for Simulation" on page 2-1). Other additional code has to be linked in statically. If you add many of your own stars to the system, you will want these stars to be statically linked as well, so that you do not have to wait for the dynamic linking to complete every time you execute your applications.

The Ptolemy kernel and vem (the schematic editor) run in separate Unix processes. The Ptolemy kernel process is called "pigiRpc", while the vem process is called "vem". You can create your own version of pigiRpc that contains your stars and other extensions permanently linked in.

There are at least three ways to build your own pigiRpc, depending on the kind of extensions you are making. The first way uses src/pigiExample, and it is intended for users who just need to add new stars. The second and third ways use the mkPtolemyTree script and csh aliases and are for users that are creating new domains or making other more extensive changes.

If you want to extend Ptolemy by modifying or adding a new scheduler, target, or even an entire domain, it is recommended that you create a duplicate directory hierarchy. This allows you to experiment with and fully test any changes separately, rather than incorporating them into the "official" version of Ptolemy. This way, your experimentation will not interfere with other Ptolemy users at your site, and your changes will not be overwritten by future installations of Ptolemy releases. It also means that all of the existing makefiles will work without modification because all of the paths specified are relative to the root of the hierarchy.

The most direct way to do this is to copy the entire Ptolemy hierarchy. This could be done with a command such as:

cp -r $PTOLEMY ~/ptolemy which would create a copy of the hierarchy in your home directory. Because this method requires excessive disk space and makes cooperative development difficult, many developers prefer to use symbolic links when creating a duplicate hierarchy. mkPtolemyTree and the csh aliases can help you setup these symbolic links.

1.3.1 Creating a pigiRpc that includes your own stars

For those who just want to statically link in their own stars with minimal hacking with makefiles, an example showing how to do this is provided in $PTOLEMY/src/pigiExample.

In the example below, we assume that $PTOLEMY and $PTARCH are set and that you have write permission to the Ptolemy source tree. If you don't have write permission, you can set up a parallel tree with the Unix ln -s command. If, for example, the Ptolemy tree was at
/users/ptolemy, but you wanted to build under ~/pt, you could do the following to create the directory and create symbolic links for the dot files, like .cshrc, and create symbolic links for the other files and directories in the distribution:

mkdir ~/pt
cd ~/pt
ln -s /users/ptolemy/* .
ln -s /users/ptolemy/.??* .
setenv PTOLEMY ~/pt
setenv PTARCH `$PTOLEMY/bin/ptarch`
rm obj.$PTARCH src bin.$PTARCH
mkdir -p src src/pigiExample bin.$PTARCH
cd bin.$PTARCH; ln -s /users/ptolemy/bin.$PTARCH
cd ../src; ln -s /users/ptolemy/src/* .
cd pigiExample; cp /users/ptolemy/src/pigiExample/* .
You also need to be sure that you have your environment set up properly for the compiler that you are using.

Continuing with our example of how to build a pigiRpc that includes your own stars:

1. Build a basic pigiRpc. PigiRpc depends on .o files under $PTOLEMY/obj.$PTARCH, so you must do a basic build. To build all the .o files, type:
cd $PTOLEMY; make install
The complete build process can take upwards of three hours. If you use an file, you can reduce the build time by building only the functionality you need. See "Using mkPtolemyTree to create a custom Ptolemy trees" on page 1-9 for more information.
2. Edit $PTOLEMY/src/pigiExample/make.template. Add your stars to LOCAL_OBJS and PL_SRCS.
3. cd to $PTOLEMY/obj.$PTARCH/pigiExample and type:
make depend
to update the makefile from the make.template. You will see messages something like:
makefile remade -- you must rerun make.
exit 1
make: *** [makefile] Error 1
This is normal and you may safely ignore the error message.
4. While still in $PTOLEMY/obj.$PTARCH/pigiExample, type
This will create a version of the pigiRpc executable with your own stars statically linked in. If later you add a new star, you should modify the symbols OBJS and PLSRCS in make.template to include it, and repeat the above procedure.
5. If you built your pigiRpc with SDFMyStar.o, you can test your pigiRpc by starting up with:
pigi -rpc $PTOLEMY/obj.$PTARCH/pigiExample/pigiRpc $PTOLEMY/src/pigiExample/init.pal
and then run the `wave' universe. If you want to have the binary you just built be the default binary for yourself, you can set your PIGIRPC environment variable to the name of the binary you just built:
setenv PIGIRPC $PTOLEMY/obj.$PTARCH/pigiExample/pigiRpc
Next time you start pigi, your new executable will be used instead of the standard one. To revert to using the installed pigiRpc, just type
unsetenv PIGIRPC
6. If you want your pigiRpc to be the default pigiRpc, you can install it in $PTOLEMY/bin.$PTARCH, but this will wipe out whatever pigiRpc is in that directory With the same makefile, you can make a version of the pigiRpc program that has debug symbols. Just type:

make pigiRpc.debug To use this, assuming the Gnu debugger gdb is in your path, specify the executable as follows:

setenv PIGIRPC \
assuming your executable is in $PTOLEMY/obj.$PTARCH/pigiExample/. Then start pigi as follows:

pigi -debug To revert to using the installed pigiRpc, just type

unsetenv PIGIRPC

1.3.2 Creating a pigiRpc with more extensive customizations

If you are extending Ptolemy in nontrivial ways, such as writing a new domain, we suggest that you create your own copy of the Ptolemy directory tree. You may use symbolic links to the "official" directories if you do not need to modify or work on them. Your new code should be placed in the parallel directory with the other similar Ptolemy subdirectories, using the same directory structure. This way you can reuse the makefiles of similar Ptolemy directories with minimal modifications. After you create your own Ptolemy tree and add your new directories and files, certain Ptolemy makefiles, typically $PTOLEMY/mk/ and $PTOLEMY/mk/, need to be modified to include your own code. Building your own pigiRpc, ptcl or tysh this way requires extensive knowledge of the Ptolemy directory tree structure and makefiles, but if you are doing serious development in Ptolemy, you will need to know this anyway.

Warning: If you have write permission in the directory where Ptolemy is installed, make sure to modify the place where "make install" puts the completed executable, or it will attempt to overwrite the pigiRpc in the Ptolemy installation, and other users may be upset with you if you succeed in doing that. (If you are using the makefile from $PTOLEMY/src/pigiExample, you do not need to worry about this because "make install" has been removed from that makefile.) The simplest thing to do is to replace the line in the makefile:

install: makefile $(DESTBIN) with:

install: makefile pigiRpc This will leave the pigiRpc in whatever directory you make it even if you type:

make install

Top Up Prev Next Bottom Contents Index Search

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