==========================================================================
 mouse:~ppr/src/docs/misc/PORTING.txt
 Last revised 12 March 2003.
==========================================================================

This document describes the PPR build process in more detail than INSTALL.txt
does.  It is intended to help people who want to port PPR to additional
operating systems.  Suggestions for improving this document should be sent to:

ppr-bugs@mail.trincoll.edu

==========================================================================
 Introduction
==========================================================================

The operating system dependent parts of the PPR build process are controled
by three files.  These are ./Configure, Makefile.conf, and include/sysdep.h.

Briefly, the ./Configure script generates Makefile.conf.  A preprocessor
macro set in the CFLAGS in Makefile.conf takes care of selecting the proper
section of sysdep.h.

==========================================================================
 ./Configure
==========================================================================

This shell script has only one purpose, to create Makefile.conf.  If you run
it and then edit Makefile.conf by hand to suit your system, you won't need
to change Configure in order to build for your system. Of course, if you are
ambitious, you can do those changes too!

It would by nice though if you could provide definitions of the
Makefile.conf settings CC, CFLAGS, and CPP not just for GCC but also for the
compiler which comes with the system.  (If the compiler that comes with your
system is not GCC.)

==========================================================================
 Makefile.conf
==========================================================================

The file Makefile.conf is included by each Makefile.  It is generated by the
shell script ./Configure.

If you are making a new port, you should run Configure and select an
operating system which you believe is similiar to yours.  You should then
edit Makefile.conf.

The first thing you should change is the definition of PORT_NAME at the top. 
Its value is used to select a section in include/sysdep.h.

Next you should go to the System Dependent Section and make any changes
needed.

The values for CC, CFLAGS, and CPP will have to be changed to suit your C
compiler.  Here are typical values for GCC:

CC=gcc
CFLAGS=-Wall -O2 -I ../include $(MISC_OPTS)
CPP=gcc -E -P -xc-header

Notice that the value for CPP should be a command which will run the C
pre-processor on stdin and write the result to stdout.

==========================================================================
 include/sysdep.h
==========================================================================

The file include/sysdep.h is not modified by Configure.  If has a section
for each operating system.  The correct section is selected by the value of
PORT_NAME as defined in Makefile.conf.  For example, if "PORT_NAME=LINUX"
appears in Makefile.conf, then the section which begins with "#ifdef
PPR_LINUX" will be used.

In each operating system section there is a pass 1 section and a pass 2
section.  At the top of the file there are comments explaining the various
parameters and which ones should go in the pass 1 section and which should
go in the pass 2 section.

==========================================================================
 Creating Users and Groups
==========================================================================

There seems to be little standardization in the way various operating
systems create users and groups, so you may have to research the commands
for your operating system and insert them in
z_install_begin/install_create_accounts.sh.

==========================================================================
 Starting PPR at System Bootstrap
==========================================================================

The script z_install_end/install_init_script.sh attempts to configure 
your system to start PPR at system bootstrap time.

Most Unix systems today use a System V style init system.  The script
already handles some common directory layout variants, but you should pay
careful attention to what this script does and check the results for
reasonableness.

If your system uses BSD style init scripts, then the script will attempt
to find rc.local and append PPR startup commands to it.

==========================================================================
 Contributing New Ports
==========================================================================

If you would like your new port to be included in the next version of PPR,
send your new include/sysdep.h section and your hacked up Makefile.conf to:

ppr-bugs@mail.trincoll.edu

It is not absolutely necessary to provide the changes for ./Configure, so if
you can't figure it out easily, don't bother.  The maintainer will work it
out from your Makefile.conf.

==========================================================================
 End of mouse:~ppr/src/docs/misc/PORTING.txt
==========================================================================