'\"!  tbl | mmdoc
.if n .pH port.chap02 @(#)chap02	40.6
.\" Porting manual:  Source Code Overview
.\"
.\" Ps = POSTSCRIPT
.\" Sd = NeWS
.\" Cs = CSCRIPT
.\" At = AT&T SVR4.0 
.\" Sh = Shapes
.\"
.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
.ds At "AT&T SVR4.0
.ds Sh Shapes
.BK "Porting the X11/NeWS Server"
.CH "Source Code Overview" 2
.H 1 "Source Code Overview" 
.H 2 "Before Starting"
The following sections cover miscellaneous information you should know
before starting the porting process.
.BL
.LI
The major \*(Sd software components
.LI
Overview of the build process
.LI
Setting up the configuration files
.LE
.H 2 "\*(Sd Components"
\*(Sd is made up of several components, each of which can be built
and tested in a step by step manner.
The major semi-independent component is called \*(Sh.  \*(Sh is the
interface between
the server and the graphics devices used for output.
In broad terms, this layer is similar to the ddx layer of the 
\f3X Window System\fP\u\s-3\(tm\s0\d.\**
The code for \*(Sh and other \*(Sd components is located in 
the directories listed below.
.TS
tab (%) box;
lp8w(1.5i) lp8w(2.5i).
Shapes%\f4~/usr.bin/xnews/xnews/server/graphics\fP
PostScript Interpreter%\f4~/usr.bin/xnews/xnews/server/nucleus\fP
Typescaler (outline) font support%\f4~/usr.bin/xnews/xnews/folio\fP
Client libraries%\f4~/usr.lib/*\fP
Keyboard and mouse support routines%\f4~/usr.bin/xnews/xnews/server/npsi/os/sysV\fP
Networking code%\f4~/usr.bin/xnews/xnews/server/npsi/os/sysV
.TE

.H 2 "Overview of the Build Process"
.P
When porting \*(Sd, one of the first tasks will be to set up the support
libraries.  The support libraries are the lowest layer of the
\*(Sd package.
These libraries include the traditional UNIX C library and
system call interface, some routines found in Berkeley UNIX
systems, and some custom routines needed to interface with the
keyboard, mouse, and networking services that your system provides.
Chapter 3, \f2System Interfaces and Libraries\f1,
describes these libraries in more detail.
.P
After you have set up these libraries, you need to build a few
development tools used to help with the porting process.
The ones that might change between systems (ace and bsdinstall)
are described in chapter 4, \f2Development Tools\f1.
Other tools (font building, clients, etc.) are built automatically
by the supplied Makefiles.

.H 2 "Setting up the Configuration Files"
\*(Sd requires you to modify a configuration file in order to
specify the build environment.  This configuration file is
.UI ~/Master.cfg .
Macros in 
.UI ~/Master.cfg
define such things as debugging, memory allocation, where
files should be installed, library commands, and other system environment 
parameters.
.UI ~/Master.cfg
is included by every
.UI Makefile
in the \*(Sd source hierarchy except the AT&T \f3XWIN\fP\u\s-3\(tm\s0\d 
libraries in 
.UI ~/usr.lib/libX11/* ).\
Note that there are also configuration
files for \*(Sh and the \*(Sd server itself. These are covered in later
chapters.
.H 1 "\f5~/Master.cfg\fP"
.UI Master.cfg
contains many macros which tailor the build environment. You should be
familiar with this file and the macros used before
starting to build this software package.
.\" The following is not applicable to the AT&T version
.\" Note that before building
.\" any part of the server, you must link the appropriate system
.\" configuration file to
.\" .L Master.cfg .
.\" There are system configuration files for several environments such as
.\" .L SysVr32.cfg ,
.\" .L SysVr4.cfg ", and"
.\" .L SunOS.cfg .
The macros defined in
.UI Master.cfg
are described below:

.H 3 "P"
.I "Default value:"
\f4P= \s-2echo "---- [..."`pwd | cut -c15-`"] ----"\fP\s+2
.br
.I "Alternate value:"
\f4P=pwd\fP
.br
.I "Alternate value:"
\f4P=:\fP
.br
.I "Sample usage:"
.SS
.nf
for dir in $(DIRECTORIES) do
    (cd $$dir; $P; ${MAKE} ${MAKEDEST} all) ;
done
.SE
The macro 
.UI $P 
is invoked after every
.UI cd
in the Makefiles to leave a printed trail of directory
names when a \f4make\fP is performed.
In this example we assume that the source is loaded in
\f(CW/usr/src/xnews\fP.
Since the directory tree is deep in some places, we want to trim
any redundant information from the pathname so that when it is
printed it looks nice and doesn't extend beyond 80 columns.
To do this, the output of
.UI pwd
is sent through
.UI cut
to chop the first 14 characters of the pathname. (The characters
.UI "/usr/src/xnews/"
are deleted).
This macro is simple window-dressing.  Nothing depends on its output.
.H 3 BUILDENV
.I "Default value:"
.I "The full path name of the \f(CW~/tools\fP directory" .
.sp
This directory contains programs needed to build the rest of
the server, such as ace and bsdinstall.
.\"
.H 3 ACE
.I "Default value:"
.UI ${BUILDENV}/ace
.H 3 ACEOPTS
.I "Default value:"
.UI "-time -mingain 10 -lnc"
.br
This macro, and the one above control the Ace Preprocessor,
which is used to construct many of the source files within
the \*(Sh sub-system.  The
.UI ${BUILDENV}
directory might not be part of the user's
PATH, so the absolute pathname should be specified.
.P
As shown in the default ACEOPTS,
.UI -time
specifies that the build code be optimized for speed.
.UI "mingain 10"
specifies that if there is more than one way of performing
an action, Ace will optimize for size unless it is calculated that 
the estimated minimum gain
by doing it the long way is greater than 10%.
.UI -lnc
tells ace to output source file line numbers
as comments in the generated code.
.H 3 LIBCPS
.I "Default value:"
.UI ${LIBDIR}/libcps.a
.H 3 CPSLIBS
.I "Default value:"
.UI -lcps
.H 3 CPS
.I "Default value:"
.UI ${BINDIR}/cps
.br
This utility is generated in \f(CW~/usr.lib/libcps\fP.  It is used to
convert a program containing \*(Ps code into a C program that can communicate 
with the \*(Sd server.

.H 3 AR
.I "Default value:"
.UI ar
.H 3 AROPT
.I "Default value:"
.UI qv
.br
The Unix command to generate libraries.
.\"
.H 3 AWK
.I "Default value:"
.UI awk
.br
The AWK interpreter.  Used by \f4etc/NeWS/Makefile\fP
and \f4libX11/X/Makefile\fP.
.\"
.H 3 CB
.I "Default value:"
.UI cb
.br
.I "Alternate value:"
.UI cat
.\"
.H 3 CBOPTS
.I "Default value:"
.I <None>
.br
.I "Sample usage (from \*(Sh dd/mem1, dd/mvga and dd/cg2 Makefiles):"
.SS
${SED} -e '/^$$/d' temp.i|${CB} ${CBOPTS}>m\f2x\fPPthRas.c
.SE
C Beautifier (optional).  This program is used to clean up some of the
``program'' generated C source files so that people can read them.  If
you
don't have \f(CWcb\fP, don't worry too much, just use \f(CWcat\fP.
.\"
.H 3 CHMOD
.I "Default value:"
.UI chmod
.br
Change ownership and access permissions of files and directories.
.\"
.H 3 CMP
.I "Default value:"
.UI cmp
.br
Binary compare 2 files when determining whether to install a new
version.
This allows you to avoid rebuilding things that don't need to be
rebuilt, but would be because make(1) only looks at modification
dates.
.\"
.H 3 MKDIR
.I "Default value:"
.UI mkdir\0\0-p
.br
Make a directory.  The
.UI -p
option tells
.UI mkdir
to build any non-existent
parent directories also.
.\"
.H 3 RM
.I "Default value:"
.UI rm\0\0-f
.br
Remove files quietly and forcefully.
.\"
.H 3 SED
.I "Default value:"
.UI sed
.br
Unix stream editor, used in \*(Sh dd/mem1, dd/vga, and dd/cg2
Makefiles to remove blank lines from ``program'' generated C files.
See ${CB} above.
.\"
.H 3 TOUCH
.I "Default value:"
.UI touch
.br
Update date/time stamp of a file.
.\"
.H 3 INSTALL
.P
.H 3 BINSTALL
.P
.H 3 TINSTALL
.P
.H 3 DINSTALL
.I "Default value:"
.UI install
.br
.I "Alternate value:"
.UI bsdinstall
.\"
.H 3 INSTALLOPT
Install a file in a particular directory, with the appropriate
ownership
and permissions.
.\"
.H 3 RANLIB
.I "Default value (SysV):"
.UI true
.br
.I "Default value (SunOS/BSD):"
.UI ranlib
.br
.H 3 RANLIBOPT
Generates BSD/SunOS required archive table of contents.
.\"
.H 3 LN
.I "Default value:"
.UI ln
.\"
.H 3 LNOPT
.I "Default value (SVR3):"
.I <None>
.br
.I "Default value (SunOS/BSD/SYSVR4):"
.UI -s
.br
Give a file another name.  Under operating systems that allow it, symbolic
links may be used to allow users to NFS mount portions of the
source tree from other machines.
.P
.H 1 "Compile environment"

.H 3 LINTOPTS
.P
.H 3 CC
.I "Default value"
.UI cc
.br
Which C compiler to use
.H 3 DEFS
.I "Default value"
.UI "/-DSYSV -DSYSVR4 -Dat386 -DREFCOUNT_BY_FUNCTION"
.br
specific options needed.
.H 3 QOPT
.I "Default value"
.UI <none>
.br
Compiler specific options
.H 3 QPATH
.I "Default value"
.UI <none>
.br
Cross compiling info.
.H 3 DEBUG
.I "Default value"
.UI "-DDEBUG -g"
.br
.I "Alternate Value:"
.UI <none>
.br
Debugging flags.
.H 3 AS
.I "Default value"
.UI as
.br
Assembler to use.
.H 3 FRACT
.I "Default value"
.UI <fr-at386.s>
.br
Internal fract implementation.
.H 3 FRACT_INLINE
.I "Default value"
.UI <none>
.br
.H 3 FLOATING
.I "Default value"
.UI <none>
.br
Floating point options

.H 1 "Compile Time Flags"
The code in the server contains many sections of code bracketed by
.UI #ifdef
flags. This allows the same source file to be used for different
operating systems and machine types.  These flags are described below:

.H 3 NEWS_ONLY
Don't compile in the X protocol code.

.H 3 WHITE_IS_ONE
Writing a '1' bit turns on a pixel (monochrome only). 
Default is that '1' values are black.

.H 3 SYSV
Generic SystemV.

.H 3 SYSVR3
Specific to System V/386 r3.x.

.H 3 SYSVR4
Specific to SVR4.

.H 3 at386
Specific to "AT" style 386 machines (WGS6386, Compaq, etc).

.H 3 i386
Specific to the Intel 80386 - bit/byte ordering.
May be predefined by your compiler.
AT&T SVR3.2 and SVR4 compilers do define this.
