2.2 Adding stars dynamically to Ptolemy

To get a quick sense of what it means to create a new star, you can use one of the existing stars as a template. Create a new directory in which you have write permission. Copy the source code for an existing Ptolemy star. For example,

cd my_directory
cp $PTOLEMY/src/domains/sdf/stars/SDFSin.pl SDFMyStar.pl
chmod +w SDFMyStar.pl The "

.pl

" extensions on the file names stand for "Ptolemy language" or "preprocessor language." The file name must be of the form DomainStarname.pl for dynamic linking and the look-inside command to work. The last command just ensures that you can modify the file. Edit the file to change the name of the star from Sin to MyStar. This is necessary so that the name does not conflict with the existing Sin star in the SDF domain.

You can now dynamically link your new star. Start pigi, the graphical editor. If you start pigi in your new directory, you will get a blank init.pal facet. Place your mouse cursor in this facet, and issue the " make-star" command (the shortcut is "*"). A dialog box like the following will appear:

Enter the name of the star, MyStar, its domain, SDF, the location of the directory that defines it, such as ~user_name/my_directory, and the name of palette in which you would like its icon to appear, user.pal. The star will be compiled and dynamically linked with the Ptolemy executable. An icon for it will appear in the facet user.pal. Try using this in a simple system.

Three details about dynamic linking may prove useful:

If the name of the star source directory has a /src/ component, pigi will replace this with /obj.$PTARCH/ depending on the type of machine you are running, to get the name of the directory in which to store the object file. This is especially useful if you are jointly doing development with others who use a different type of machine. If there is no /src/ component in the name, then the object file is placed in the same directory with the source file.
If there is a file named Makefile or makefile in the object file directory, pigi will run the make program, using the makefile to create the object file (or make sure it is up to date). If there is no makefile, pigi will run a make-like procedure on its own, running the preprocessor as needed to produce the C++ source files, then running the C++ compiler to create the object file. By default, the C++ compiler will be told to look for include files in the kernel directory and the domain-specific kernel and star directories; if this is not adequate, then you need to write a makefile. Once compilation (if any) is complete, the dynamic linker is used to load the star into the system. Compilation errors, if any, will appear in a popup window.
Whenever the definition of a star is changed so that the new definition has different I/O ports, the icon must be updated as well. You can do this by calling make-star again to replace the old icon with a new one. If the linking fails, one of the following situations may apply:
Whoever installed Ptolemy did not install the compiler.
The compiler is not configured correctly. If you are using a prebuilt compiler obtained from the Ptolemy ftp site, you may need to set some environment variables if your Ptolemy installation is not at /users/ptolemy. See Appendix A of the Ptolemy User's Manual for more information.
A spurious makefile exists in your directory. If a makefile exists in your directory, Ptolemy will attempt to use it to compile your star. Remove it, and try again.
The version of the compiler used to build Ptolemy is not the same as the version used to compile your star. This should not occur if you are using the compiler distributed with Ptolemy, but can occur if the compiler has been updated since Ptolemy was last built, or if you are not using the compiler distributed with Ptolemy.
You have a /src/ component in the directory name, but the corresponding
/obj.$PTARCH/ directory does not exist or cannot be written. A common error is to put the Ptolemy sources in /usr/local/src/ptolemy, which confuses Ptolemy since a star might be in /usr/local/src/ptolemy/src/domains/sdf/stars, which has two /src/ directories in the path. You may find it helpful to refer to the Appendix A, Installation and Troubleshooting in the User's Manual.
The star you just created performs exactly the same function as an existing star in the Ptolemy library, and hence is not very interesting. Try modifying the star. For example, you could add 1.0 to the sine before producing the output. Find the definition of the go method, which should look like this:

go {
output%0 << sin (double(input%0));
} The one line of code is ordinary C++ code, although the "<<" and "%" operators have been overloaded. This line means that the current value (%0) of the output named "output" should be assigned the value returned by the sin function applied to the current value of the input named "input". The cast to double indicates that we are not really interested in the Particle object supplied by the input, but rather its value, interpreted as a double-precision floating point number. Try changing this code to

go {
output%0 << sin (double(input%0)) + 1.0;
} To recompile and reload the star, place your mouse cursor on any instance of the icon for the star, and type "L" (or invoke the "Extend: load-star" command through the menus).

Sometimes, you will wish to dynamically link stars that are derived from other stars that you have dynamically linked. To do this, the base class stars must be permanently linked. This can be done with the "Extend:load-star-perm" command ("K"). To do this, place the mouse over an icon representing the parent star, and type "K". Once the parent star is permanently linked, it cannot be replaced or redefined: you must restart pigi.

The go and all other entries in the .pl file defining the star are explained in the following sections.