.if n .pH port.chap12 @(#)chap12	40.4
.\" Porting manual:  Ch 12 Server Initialization
.\"
.\" Ps = POSTSCRIPT
.\" Nw = NeWS
.\" Cs = CSCRIPT
.ds Ps P\s-2OST\s+2S\s-2CRIPT\s+2
.ds Sd \s-2X11/Ne\h'-0.2n'WS\s+2
.ds Nw \s-2NeWS\s+2
.ds Cs \CS\s-2CRIPT\s+2
.BK "Porting the X11/NeWS Server"
.CH "Server Initialization" 12
.H 1 "Server Initialization" 
This chapter describes how to integrate the various parts of \*(Sd
to get the server up and and running.
.H 2 "Integrating C\s-2SCRIPT\s+2, Shapes, and the \*(Ps Interpreter
Once you have both Shapes and the \*(Ps interpreter running stand-alone,
you can try integrating them with \*(Cs and running some \*(Ps
code which renders graphics on the screen.
In our experience,
\*(Cs seems to be the most portable part of the server,
and has posed no problems in the porting process.
It should not be necessary to test \*(Cs in stand-alone.
.P
If you have not done so yet, you will need to build \*(Cs.
To do this, go into the 
.UI server/cscript 
directory and do a 
.UI make .
Once this is complete,
go to the directory
.UI server/portinghelp/graphics 
and execute the shell scripts
.UI "init.sh, ld_dummy.sh"
and 
.UI make.sh 
(in that order).
These scripts will build the interpreter integrated
with \*(Cs and Shapes.
Since these are shell scripts and not makefiles, 
the 
.UI -D 
and other flags used may have to be changed to correspond to
changes made in the make configuration file.
.P
Once the server is linked, you can run it.
Do this by first setting the environment variable 
.UI XNEWSHOME 
to "." 
so that the server will look for 
.UI init.ps 
in 
.UI ./etc/NeWS (
.UI "XNEWSHOME=. export XNEWSHOME"
).
Then run \*(Nw as follows:
.SS
\f4Example%\fP 	./news
.ft1
.SE

Don't run the server from the system console if
the system console is also the frame buffer.
If all is well, you should see a butterfly rendered onto the frame buffer.
If not, you will have to debug the system.
You can put a breakpoint near 
.UI execute_top 
in the interpreter and see if the interpreter is functioning properly.
That is, you will be able to verify that the \*(Ps interpreter is parsing 
each token and executing each invoked operator properly.
.P
If this is the case, but it is still not working,
the problem is probably in Shapes.
Refer to the Shapes documentation for help in debugging it.
Also check to see that the frame buffer is being initialized properly.
This is done via the 
.B createframebuffer 
\*(Nw operator.
.H 2 "Integrating the Complete Server"
Once you have all of the NPSI code written and debugged, 
and the \*(Ps interpreter, \*(Cs, and Shapes are all working,
you should be able to build a complete server.
To do this is to go into the server directory and do a 
.UI "make clean" 
followed by a 
.UI "make checkinstall" .
This should completely rebuild all parts of the code, and 
more than likely, everything will compile properly.
Note that before reaching this stage of the port, all the \*(Sd components 
should be compiled and debugged.  
.P
While the compilation should proceed smoothly, the 
.UI make 
is likely fail on the link step due to 
unresolved references or possibly multiple references.
It will probably take a week or two to resolve all of these references.
.P
Once you have a server linked, your job is about half done.
Remember that the server executable is just the mechanism
used to execute initialization of the \*(Ps/\*(Nw code.
Client programs rely on services provided by the \*(Ps/\*(Nw code itself,
as well as the server executable.
There is a great deal of this code,
and it is very complex.
It can also be very difficult to read
due to the nature of postfix notation languages like the \*(Ps Language.
Function-based languages like C and Pascal contain clues to the interfaces
between functions in their syntax.  That is, parameter lists are clearly 
delimited in calls, and return values are explicitly assigned.
.P
Unfortunately,
an exhaustive description of how the \*(Ps/\*(Nw initialization code
works is beyond the scope of this document. 
For detailed information refer to the Adobe Systems, 
\*(Ps Language Reference Manuals, and the \*(Nw Programming Manual.
.P
If you run into some code which is failing (i.e., causing the server
executable to crash or hang) and you are at a loss to understand what
the \*(Ps/\*(Nw code is doing,
try describing what you think the code is doing on paper.
Also, it may be helpful to have a \*(Ps expert on hand.
Be forewarned, however, 
that \*(Nw contains many extensions to \*(Ps Language,
especially for interest and event handling
(for further information refer to the NeWS Programming Guide.
.P
A knowledge of the \*(Ps Language alone will be insufficient;
you'll have to understand something of the \*(Nw extensions.
.P
There is some debugging assistance in the \*(Ps/\*(Nw 
initialization code.
If you set the shell environment variable 
.UI DEBUG :
.P
.UI "DEBUG=1 export DEBUG"
.P
the \*(Ps/\*(Nw initialization code will print out a line for 
each \*(Ps/\*(Nw file read. That way, when the code fails, 
you'll have an idea where it failed.
.P 
The \*(Ps/\*(Nw initialization code should be installed in 
.UI $DESTDIR/usr/etc/NeWS .
If it is not, go to the 
.UI xnews/xnews/etc 
directory and do a 
.UI makeinstall .
.P
Once the code is installed,
set 
.UI XNEWSHOME 
to 
.UI $DESTDIR/usr:
.P
.UI "XNEWSHOME=$DESTDIR/usr export XNEWSHOME"
.P
Then run the server.
.P
Once a failure is isolated to a file,
the best way to further debug the problem is by putting 
.UI printfs 
in the \*(Ps/\*(Nw initialization code to track its
progress within the file.
.P
Once the server is initializing,
you can run some clients directly in the 
.UI init 
code rather than setting up a network connection.
To do this, edit 
.UI init.ps
(the one in 
.UI $DESTDIR/usr/etc/NeWS ).
There is a line of code which says
.P
.UI "server pause"
.P
Comment this out with a % in the first character of the line
and add a line of code which contains the full path name of a 
\*(Ps/\*(Nw client followed by the operator run.
.P
For example, the client below draws M.C. Escher's fish.  It is a good choice 
because it doesn't require any mouse or keyboard input.
.SS
.UI (/usr/src/xnews/usr.bin/xnews/xnews/client/NeWS/fish.ps)
run
.ft1
.SE
When you run the server,
a canvas for the client should be created and the client's output should
be displayed therein. Once it comes up,
try resizing the window and changing the complexity of the output.
This will test the mouse interface.
.P
If this works, uncomment the 
.UI "server pause" 
line.
Bring up the server
and see if you can establish a network connection to it.
Try running other \*(Ps/\*(Nw clients over the network connection,
perhaps from a different machine.
Test for keyboard event handling as well as mouse event handling.
Try running multiple clients simultaneously.
In general, test for robustness.
Make sure there aren't any memory leaks.
