.\" @(#)newstars	2.7	12/8/92
.H1 "Defining New Stars"
.pp
Only the most casual user will get by with the stars provided
in the Ptolemy palettes.
New stars are defined using the \*(PT preprocessor language,
which is described in its section in the manual.  This pigi section
will not attempt to teach you how to write your own stars.
.pp
There are two ways to use your own personal star with Ptolemy:
use the dynamic linking facility, or build your own version
of
.i pigiRpc .
If the incremental linking facility will suffice for your purposes,
all you need to do is create an icon for the star; pigi will
automatically link in the star when it is required.  The incremental
linking facility suffers from certain restrictions, however:
.bu
The star may not call any functions except for those defined in the
star's source file and those that are already present in pigi (you
can count on all the kernel routines and all the domain-specific
kernel support routines already being present in pigi).
.bu
You may not redefine a statically linked star.  (This restriction
may be removed in the future).
.lp
If you wish to dynamically link a star is derived from another
dynamically linked star, you must ``permanently'' link the parent star.
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.
.pp
You can make your own private version of
.i pigiRpc ;
this is described in a later section.
.pp
It is a simple matter to create an icon for a new star; the procedure
is the same for dynamically linked stars as it is for statically linked
ones.
The pigi command ``Extend:make-star'' (with accelerator ``*'')
creates the icon.
A dialog box will query you for the name of the star
and the location of its source code.
Please note that pigi requires the location be specified 
relative to your or some other user's home directory.
For instance, if your login name is ``joe'', and the star
is defined in ~joe/ptolemy/mystar.pl, then the src
directory is ~joe/ptolemy.
The master copy of the star icon to be generated by the
.i make-star
command is stored in a directory determined by pigi based on the 
following rule:  if the star source directory ends in ``.../stars'' and
there exists a ``.../icons'' directory, then put the icon in that ``.../icons''
directory.  Otherwise, just put the icon in the same star source directory.
It is your responsibility to make sure the star source code is 
indeed in the star source directory you enter into the dialog box.
Otherwise, pigi will not be able to locate the star source code when
executing the
.i look-inside
command.  The way pigi does a
.i look-inside
on a star icon is based on a similar rule: if the directory where the
master copy of the star icon is stored ends in ``.../icons'' then pigi
looks for the star source code in the ``.../stars'' directory,
otherwise it looks for the source code in the same directory
(the same rule is used when locating source files for dynamic linking).
.pp
If the star you specify is not already loaded into pigi, it will be
compiled and linked in.  If the star source directory ends in ``../src/stars'',
Pigi will build the object file in the directory ``../obj.\fIarch\fP/stars'',
where
.i arch
is replaced by
.c sun4
or
.c mips ,
depending on what
your machine type is; this feature is designed for supporting networked
clusters of dissimilar machines.  Similarly, if the source directory
ends in ``.../src'' the object file will be made in ``.../obj.\fIarch\fP''.
.pp
If there is a file named ``Makefile'' or ``makefile'' in the object file
directory, pigi will run the
.i 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.
.pp
Pigi will next query for the name of a palette into which
to store (an instance of) the icon.
If the palette does not already exist, it will be created.
The dialog box suggests using the palette ``./user.pal'', simply
because this is easy to access via the \fIopen-palette\fR (``O'') command.
Note that you can have many palettes named ``user.pal''; the one opened
by the \fIopen-palette\fR command is the one in the directory where
you started pigi.
.pp
After the icon has been created, you can use it immediately.  The icon
that pigi generates has a generic star symbol in it.  You can change
this symbol if you want;
see the section below on editing icons.
.pp
An important note: 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 \fImake-star\fP again to replace
the old icon with a new one. 
.pp
If you modify the code for a dynamically loaded star and wish to load
the new definition, execute the \fIload-star\fR command while pointing
to an instance of the star (or type ``L'').  This will not work if you
previously permanently linked the star with the \fIload-star-perm\fP command
(``K'' key).  In this case, you must restart pigi to load in the new version.
