.if n .pH port.chap01 @(#)chap01	40.5
.\" Porting manual: Introduction
.\"
.\" Ps = POSTSCRIPT
.\" Sd = 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 Cs \CS\s-2CRIPT\s+2
.\"
.BK "Porting the X11/NeWS Server"
.CH "Introduction" 1
.H 1 "Introduction" 
.H 2 Overview
This manual describes how to port the \*(Sd Window Server to 
different computer systems.
The minimum hardware and software requirements for a development
system are:
.BL
.LI
A C Programming Environment
.LI
8 Megabytes of RAM
.LI
3-button Mouse 
.AB N
Using another type of mouse may be possible, but this would
require changes in the \*(Ps state tables, as well as changes to
other code.  In this manual we assume the use of a 3-button mouse.
.AC
.LI
A Keyboard
.LI
Display Frame Buffer (Monochrome or Color)
.LI
Inter-Process Communication Capability
.LI
100 Megabytes of Free Disk Space
.LE
.H 2 "Default Configuration
The default configuration for \*(Sd is a system using \s-1UNIX\s+1\(rg
System 5 Release 4(SVR4.0) with a color EGA or VGA running in monochrome
mode.
If you are using this environment, the software is already configured
and you can simply use the existing Makefiles to build the server and
clients for you.
Detailed instructions for doing this are given in a following section.
.P
The remaining chapters in this manual are devoted to describing the tasks
involved in porting \*(Sd to non-Sun and Non-SVR4 platforms.
This involves understanding, modifying, and compiling the different
parts of the server, testing and debugging each part,
and finally integrating all the parts to form a complete working server.
.H 2 "Graphics Device Support"
The supplied version of \*(Sd supports both monochrome (1 bit) and
color (1, 8 or 32 bit) framebuffers.
1 bit support should be easily portable to framebuffers that
can be addressed as a linear block of memory. This includes
the Cornerstone 1600x1200 display and the Sun monochrome framebuffers
(BW2 low and high resolution). EGA/VGA video
adaptors in monochrome mode that are supported by the console
driver are also useable.
.P
Supported color displays include the EGA/VGA (4 bit color) and
Sun's Color graphics cards (8 and 32 bit color).
.P
In addition to ``dumb'' (memory addressable) framebuffers, the Shapes
graphics interface allows the developer to support
hardware graphics accelerators and other custom graphics interfaces.

.H 2 "Non-UNIX Support"
.P
The \*(Sd software, as delivered, does not support a
non-Unix environment.

.H 2 "Building and Running the Product under SVR4.0"
.P
This section describes how to build the product under Unix System V
Release 4.0. The top level directory of the development tree
will be referred to as
.UI ~/ 
in textual descriptions.  The file 
.UI ~/setup
defines an environmental variable named
.UI $SRCROOT 
to be the absolute path name of this directory.
Thus, directories directly under the source root could be referred to as
.UI ~/usr.lib
or 
.UI ~/usr.bin .
For example, if you loaded the source into 
.UI /usr/src/xnews , 
and the manual refers to 
.UI ~/Makefile , 
you would refer to 
.UI /usr/src/xnews/Makefile .
The environmental variable
.UI $SRCROOT
would have a value of 
.UI /usr/src/xnews.
The file
.UI ~/Makefile
can be used to generate the \*(Sd server automatically.

.\" 
.\" Several of the manuals for OpenWindows products use examples
.\" written in "csh".  This comment is included to ease transition
.\" from/to these other manuals
.\"
The installation examples below assume that you are using 
the Bourne shell
.br
(
.UI sh
).
Users of the C shell (
.UI csh ) 
will need to modify the commands shown below appropriately.
.P
The shell script
.UI ~/setup
provides a simple way of setting up all the 
environment variables needed to build and run \*(Sd.
.UI DESTDIR
refers to the directory where the binary product will be installed.  The 
default is 
.UI /usr/xnews .
.UI SRCROOT 
refers to the absolute path of the directory where you
loaded the source to \*(Sd.  Once you have edited 
.UI ~/setup 
to modify these variables, it needs to be "sourced":
.SS
\f4Example$\fP cd /usr/src/xnews
\f4Example$\fP vi /setup
\f4Example$\fP . ./setup
.ft1
.SE

After loading the source code, make sure that the
.UI DESTDIR
file system has at least 30MB of work space 
and that you are in the root of the source tree. Then enter the
following:
.SS
\f4Example$\fP make build
	\.\.\.\.
.ft1
.SE

Instead of having the output of the make scroll off 
the screen, you may wish to capture the output in
a file.  This is the method we use:
.SS
\f4Example$\fP make build >make.build 2>&1 &
\f4Example$\fP tail -f make.build
	\.\.\.\.
.ft1
.SE
.sp
Instead of using the commands shown above to install the system, 
you could also use the
.UI ~/tools/doit
script.  
Simply type the following:
.SS
\f4Example$\fP doit build
.ft1
.SE
.sp
Once everything has been built and installed, the server can be
rebuilt simply by using make in the directories affected.  This may be  
done if you are making changes
to the server and you wish to test them.
.SS
\f4Example$\fP \s-1cd ~/usr/src/xnews/usr.bin/xnews/xnews/server\s+1
\f4Example$\fP make all
	\.\.\.\.
\f4Example$\fP make install
	\.\.\.\.
.ft1
.SE
.sp
To run the server built by any of the above methods, you
must define several environmental variables with a
setup script(see below).
.P
.nf
.UI $OPENWINHOME=$DESTDIR
.UI PATH=$PATH:$DESTDIR/bin:$DESTDIR/demo:.
.fi
.P
To run the server enter:
.SS
\f4Example$\fP xnews
.ft1
.SE
.H 2 "Porting Strategy"
The procedure for porting \*(Sd
has been designed to be as modular as possible.  That is,
you will deal with only a small part of the product at
any one time.  As each part of the product is successfully
ported, they will be combined to produce a working \*(Sd system.
.P
We describe the porting process by addressing each part separately.
The following parts are covered in the chapters that follow:
.BL
.LI
Implementing System Interfaces and Libraries
.LI
Development tools used to build \*(Sd
.LI
Interfacing to the Graphics Hardware (Shapes)
.LI
Porting the PostScript Interpreter
.LI
I/O Multiplexing
.LI
Keyboard and Mouse Event Handling
.LI
Networking I/O
.LI
Implementing Miscellaneous NPSI Routines
.LI
Font Support (Bitmap and Outline)
.LI
Server Initialization (PostScript files)
.LI
Porting NeWS Clients (PostScript Demos)
.LE
.P
.H 2 "Significant Portability Issues"
Two significant portability issues in the \*(Sd server must
be mentioned.
The first concerns the target system's processor.
The
.UI #ifdef
macros
.UI LITTLEENDIAN
and
.UI BIGENDIAN
are used to control this.
.P
The second portability issue concerns the assumption pointers
in the server have only 24 bits of significance.  
The 
.UI REF 
structure is used as a pointer substitute.  
This structure contains a six-bit field which indicates the type of data 
structure referred to, and two other 1 bit fields (executable and soft).
This leaves 24 bits for pointer information.  If your system uses
pointers with more than 24 significant bits, you may have problems
with this.  You might try making the entity field in the 
.UI REF 
structure big enough to hold your pointers.  This will result in a performance
penalty, but should work if your computer generates code to pass
structures properly.



