\section{Extending the System} 
\label{sec:compiling}
index{compiling LINK programs}

Assuming that LINK has been installed properly, the procedure for 
customizing the system to meet individual needs is relatively 
straightforward.  This first release of manual will serve as an
introduction to this process, but, unfortunately, is not yet a complete
reference guide.  This section of the manual will grow from release
to release of LINK, and will give references to examples in the code
when the current text is inadequate.

The process of extending the STk interpreter is a derivative of the
process described by Erick Gallesio in the STk documentation.  If
you plan to add several commands to the system, the document entitled
{\em Extending the STk Interpreter} and found in the STk distribution
is a valuable reference.  However, the LINK system does include many helpful 
routines which help in the extension of the interpreter in a systematic
way.  In particular, new STk primitives for {\em Collection}, {\em List}, 
and {\em Array} methods are generated automatically by a process
described below.

To begin, let us consider a simple example.  We assume is that the
following environment variables have
been set:\index{compiling LINK programs}\index{environment variables}
\index{NEWLINKBASE}
\index{STK\_LOAD\_PATH}
\index{STK\_LIBRARY}

\vspace{2mm}

\begin{center}
\begin{tabular}{|l|c|} \hline
Environment Variable & Value \\ \hline\hline
NEWLINKBASE          & full pathname of link's root directory \\\hline
STK\_LOAD\_PATH      & \$(NEWLINKBASE)/stklos \\ \hline
STK\_LIBRARY         & depends on the location of your STk distribution \\ \hline
\end{tabular}
\end{center}

\vspace{2mm}

\subsection{The Makefile}

The file {\em Makefile}\index{Makefile!system} 
\index{Makefile!user applications}
in the NEWLINKBASE directory is useful
not only as the root makefile of the system, but also as a makefile 
for stand-alone user applications which use LINK's libraries. 
The programmer may link his or her C/C++ code with the LINK libraries
to produce a C++ program, or to produce a new version of the whole 
system with new features.  

\begin{figure}
\begin{verbatim}
#####################################################################
#USER_SOURCE = \
#               demo.cc \
#               linkUserInit.cc # must edit this file and include it
#                               # in this list to augment the GUI
#
USER_SOURCE = \
                demoNoGUI.cc  # demoNoGUI.cc is a sample program
                                # using LINK objects, but not the GUI.
#####################################################################

#####################################################################
## Name your executable file below.
#####################################################################
#EXECUTABLE = demo
EXECUTABLE = demoNoGUI
#####################################################################
\end{verbatim}
\caption{Makefile macros intended to be modified by the LINK library
         programmer.}
\label{fig:make-demo}
\end{figure}


In order to use the makefile to compile your Link applications,
you must add your source files to the USER\_SOURCE list in the
Makefile (see Figure~\ref{fig:make-demo}, making sure to end each line
except the last one with a backslack.  There is a demonstration
application in \$NEWLINKBASE/standalone, which the Makefile
is set up to build.  To build and run this example application,
Copy all of the files in that directory and the LINK Makefile to an 
an empty directory. Then you can type

\begin{quote}
make demoNoGUI
\end{quote}

to build the first demo.  The result is a program called {\em demo}
which computes a simple function using LINK objects.  

The function computed by the demo program can also be included into
the LINK interface so that users may experiment with it interactively.
To build a version that includes the GUI, reverse the comments in
USER\_SOURCE and EXECUTABLE so that demo.cc and linkUserInit.cc
are compiled.  A new version of the system which includes new
commands is then built with the command:

\begin{quote}
make -D STK\_GUI=yes demo
\end{quote}

NOTE:  The LINK Makefile links your program with all of the
Link libraries (layouts, generators, algorithms, graph, and basic).
If executable size is a problem for you, edit the LINK\_LIBS macro
in the makefile so that only the appropriate libraries are included.

Note also that since LINK uses manual template instantiation 
with g++,
new types of objects (e.g. Set$<$NewObject$>$) need special treatment.  
LINK employs some mechanisms which automatically generate template
instantiations.~\footnote{This is, they automatically generate files
which perform manual instantiation from g++'s point of view.  Manual
instantiation reduces the burden placed on the compiler and linker
during compilation.}  The programs which accomplish this are 
{\em instantiate}\index{instantiate} and 
{\em genMethods}\index{genMethods}, located in the directory
\$NEWLINKBASE/autowrap.  These programs are currently undocumented,
but dozens of examples of their usage to generate template 
instantiations and STk wrappings for various Collection and
Container objects such as sets and lists are found in the
{\em GENERATION\_COMMANDS.*} files located in the directories
{\em linkTemplates}, {\em STkTemplates}, and {\em autogenSTkMethods}
\index{linkTemplates directory}
\index{STkTemplates directory}
\index{autogenSTkMethods directory}
under the {\em src/basic}, {\em src/graph}, and {\em src/userobj}
directories.

When the requirements for instantiation new templates exceed the
capabilities of {\em instantiate} and {\em genMethods}, 
manually-generated template instantiations are put into the
files {\em basicTemplate.cc}, {\em graphTemplate.cc}, and 
{\em userobjTemplate.cc}.  Note that \$NEWLINKBASE/bin 
contains some useful utilities for quick editing and searching
in the LINK file hierarchy.

\subsection{Adding a Menu Option}\index{menu option! adding}

\begin{figure}[hbt]
\begin{verbatim}
//**************************************************************************
PRIMITIVE evenOddRanksWrapper(SCM g)
{
        Graph *gr;
        if (!(gr = getGraph(g)))   // see src/stkWrapper/stkUtils.cc
                Err("even-odd-ranks: expected <graph*> ", g);

        Set<Set<Vertex*> > result = evenOddRanks(gr);
        Set<Set<Vertex*> >* new_copy = new Set<Set<Vertex*> >(result);

        return STk_make_CXXwrapper(
                Wrapper<Set<Set<Vertex*> > >::type,     // stkWrapper/Wrapper.h
                Wrapper<Set<Set<Vertex*> > >::name,
                (void *) new_copy,
                LINK_DYNAMIC);          // tells STk's garbage collector
                                        // to delete new_copy when the user
                                        // is finished with it
}

//
// This is what must go into userinit.cc
//
void STk_evenOddRanks_Init()
{
        STk_add_new_cpp_primitive("even-odd-ranks",     // cmd name
                                  tc_subr_1,            // # parms
                                  (PRIMITIVE (*)(...))evenOddRanksWrapper);
}
//***********************************************************************
\end{verbatim}
\caption{An example wrapper routine}
\label{fig:even-odd}
\end{figure}

Any algorithm you wrap into the user interface can easily be added
to the menu of each graph window.  Simply make your own
copy the file {\em \$NEWLINKBASE/stklos/graph-menu.stklos} and edit it.
It will probably not be necessary to learn any Scheme, since you
should be able to copy the menu entry of an existing algorithm and
change the name.  If it becomes necessary to make more interesting
changes, see the STk manual and the GUI part of the Link manual.
If you put your copy of \verb+graph-menu.stklos+ (and any other interface
files you wish to customize) in the current directory, they will be
loaded automatically when the application starts.  If, however, you
wish to keep your customized interface files in a separate directory,
modify the STK\_LOAD\_PATH environment variable to include that directory
before \$NEWLINKBASE/stklos.  For an example of this customization, 
consider the menu option for the 
{\em spring-layout} command was created by adding the following line
to the ``Layouts'' sublist of the menu string contained in 
\verb+graph-menu.stklos+:
\begin{verbatim}
    ("Spring" ,(lambda ()(spring-layout* (slot-ref gv 'graph) gv)))
\end{verbatim}

The first element in the list is the text of the menu item, while the 
second element is the function which is to be called if the user selects
this menu item.  The comma is used since this line is used to force 
evaluation of the expression (this line is found within a back-quoted
list in the file.  See the Scheme standard for an explanation of Scheme
quoting).

\subsection{An Example Wrapper} \index{wrapper!example}
A {\em wrapper} routine is one which translates its input into a new
format, calls a routine which requires this format, and then translates
the return value back into the format of the calling environment.
In LINK, wrappers extract C++ data from STk structures, call a LINK
method, and store the return value in a new Scheme object.
As stated above, Erick Gallesio's document {\em Extending the STk
Interpreter} will be a helpful guide to extending the LINK system,
though there are dozens small wrapper programs in LINK which can
serve as examples.  In particular, the file {\em graph\_Graph\_Methods.cc}

in \verb+src/graph/manualSTkMethods+ contains wrappers for the 
many methods of the \Graph class, while the files in 
\verb+src/algorithm/manualSTkMethods+ contain individual wrapper
programs for the library algorithms.  

Let us consider the example wrapper in Figure~\ref{fig:even-odd}.
This is the wrapper associated with the example program \verb+demoNoGUI.cc+.
The input is an STk ``cons'' element, which is simple a structure pointer.
STk provides many helpful macros for extracting useful information from
this structure (see stk.h).  However, LINK provides several shortcut
functions to abstract some of the detail away.