INSTALL.txt

============================================================================
 mouse:~ppr/src/INSTALL.txt
 mouse:~ppr/src/docs/misc/INSTALL.txt (symbolic link)
 Last revised 29 September 2006 for PPR version 2.00a1
============================================================================

This document describes the steps required to compile and install PPR.  See
README.txt to learn where the other documentation is.

This document does not specificly discuss installing PPR from an .rpm file. 
Obviously in such as case you will not have to compile it, but some of the
information about other packages still applies.

=============================================================================
 Table of Contents
=============================================================================

* Requirements for Installing PPR
* Programs for PostScript Filters
* Notes for CAP
* Notes for Netatalk
* Notes X-Windows
* Notes for RedHat Linux 4.x
* Notes for Linux 2.6.x
* Notes for DEC OSF/1
* Notes for SGI IRIX 6.3
* Notes for HP-UX 10.20
* Notes for ULTRIX
* Notes for MS-Windows NT 4.0 and UWIN 2.0
* Notes for MS-Windows NT 4.0 and Cygwin
* Simple Compiling Instructions
* Compiling from CVS
* Hacking Without Being Root
* Upgrading from previous versions

=============================================================================
 Requirements for Installing PPR
=============================================================================

1) The PPR source archive (ppr-X.XX.tar.gz)

2) Gzip (to uncompress the source archive)
   (Gzip may be obtained from <http://www.gzip.org/>.)

3) Tar (to unpack the source archive)

4) A Make that understands $^ (such as GNU Make)

5) GCC version 2.5.8 or later or the native C compiler on certain systems (the
   Configure script will tell you if you have this option.
   <GCC may be obtained from <http://gcc.gnu.org/>.)

6) Perl 5.005 or later
   (Which may be obtained form <http://www.cpan.org/>.)

7) GNU dbm (GDBM)
   (Which may be obtained from <http://www.gnu.org/directory/gdbm.html>.)

8) TDB <http://sourceforge.net/projects/tdb/>
   (Which may be obtained from <http://sourceforge.net/projects/tdb/>.)

With the exception of TDB, all of these items are probably already installed
on Linux systems.  For other systems, you should check first.  The version
of GCC may be determined with the command "gcc -v".

While Perl is not absolutely required to use PPR, it is strongly recomended
that you install Perl 5.005 or later. If you do not have Perl, the following
things will not work:

* The TeX filter.  This means that you will have to run TeX source files
  through TeX or LaTeX before sending them to be printed.  (But, the DVI
  filter will still work.)

* Automatic Microsoft Windows driver installation for Samba.

* The World Wide Web interface.

* The ppr-panel GUI (which also requires Perl/Tk).

* The audio commentator and responder.

It is possible to compile and use PPR even if you don't have GDBM, but
the ppuser command and the printer accounting features associated with it
won't work.

It is possible to compile and use PPR without TDB, but automatic Microsoft
Windows driver download for Samba won't work.

Compiling from CVS requires the following additional packages:

* Transfig

* Doxygen

* HTMLDOC 

* GNU Gettext utilities

=============================================================================
 Programs for PostScript Filters
=============================================================================

If the following software is present, more input filters will be available:

* NetPBM (pnmtops, etc.)

* IJG Jpeg utilites (djpeg)

* Groff (groff, grog, grops, etc.) or AT&T Troff (troff, dpost, etc.)

* TeX/LaTeX

* Perl

* DVIPS

* plot2ps (Available from ftp://ppr-dist.trincoll.edu/pub/ppr/)

* Transfig

* GNU Texinfo

* Uncompress

* GZIP

* HTMLDOC (Available from http://www.easysw.com/~mike/htmldoc/)

* Xpdf

* Adobe Acrobat Reader

Most of these programs are a standard component of many Linux distributions.

=============================================================================
 Notes for CAP
=============================================================================

If you will be using PPR with CAP and you will be sharing more than about 10
printers using papd, you must change two values in a CAP library header
file and re-compile the CAP library.

You should go to the directory "cap60/lib/cap" and edit the file "abpap.h".
Change the values in the defines of NUMPAP and NUMSPAP from their normal
values of 12 and 10 respectively to something higher such as 70 and 70.
Once you have made the change you must re-compile and re-install the CAP
library by running "make install".

You must also copy a header file from a CAP source directory to
"/usr/include/netat" (or wherever your CAP netat/ include directory is).  The
file is the one you may have edited in the procedure described above,
"cap60/lib/cap/abpap.h".

=============================================================================
 Notes for Netatalk
=============================================================================

In order to use Netatalk with PPR you must first obtain and install NATALI,
the Netatalk AppleTalk Library Interface compatibility library.  This
library, written by the author of PPR, may be obtained from the same place
you got PPR.

NATALI only works with Linux, though it is probably possible to port it to
other operating systems without a lot of trouble.

NOTE: be sure to read the README.txt file that comes with NATALI.  If you
don't follow the directions, there will be an unresolved symbol when you try
to link a program with NATALI and Netatalk.

=============================================================================
 Notes for Solaris
=============================================================================

PPR version 1.52 and later will use zlib if available.  However, the version
of zlib supplied with Solaris 9.0 appears to be old and doesn't have all of
the functions required by PPR.  It is recomended that you install a recent
version of Zlib such as 1.1.4.  If you have installed zlib in /usr or
/usr/local, then Configure will find it.

If you are depending on LD_LIBRARY_PATH to help PPR to find shared libraries
such as GDBM and Zlib, you will have problems.  This is because
LD_LIBRARY_PATH doesn't work with setuid programs and because processes
started by Init or Inetd probably don't have it set.

In an attempt to solve this problem, when compiling on Solaris PPR compiles
/usr/local into the binaries as an internal search path.  This seems to work
OK except for libgcc_s.so.1.  A quick-and-dirty fix that will work on all
versions of Solaris is to do this:

# ln -s /usr/local/lib/libgcc_s.so.1 /usr/lib

This links the GCC library into a directory that is in the system search
path.

Newer versions of Solaris (such as 9.0) provide a way to alter the system
search path.  This is done with the crle command.  You should read the
crle(8) manpage before trying to use it as you will be tampering with a
critical system setting.  But briefly:

To see the current search path:

# crle

Configuration file [3]: /var/ld/ld.config
  Default Library Path (ELF):   /usr/lib
  Trusted Directories (ELF):    /usr/lib/secure  (system default)

Command line:
  crle -c /var/ld/ld.config -l /usr/lib

The command line show is the command needed to establish the current
configuration.  Write it down.  To append a directory to the search path, do
this:

# crle -u -l /usr/local/lib

Note that you can easily disable your system with the crle command.  For
example, if you leave out the -u in the command above it will replace the
current search path with one that contains only /usr/local/lib.  Now most
programs won't work.  Fortunately, crle seems to be unaffected, so you
should be able to restore the original settings by running the command which
you wrote down above.

=============================================================================
 Notes for RedHat Linux 4.x
=============================================================================

In 4.0 release, the file /usr/include/libintl.h contains an appearent bug.
The line "#include <locale.h>" is enclosed by "#ifdef HAVE_LOCALE_H" and
"#endif".  The condition should be removed.  It is not known if this problem
is present in 4.1 or 4.2.

If you want international messages support, then after you have run Configure
and said "yes" to the appropriate option you must edit Makefile.conf and
change the line which says:

INTLLIBS=#-lintl

to

INTLLIBS=-lintl

Configure does not put the option -lintl in because the file /usr/lib/libintl.a
is not present in RedHat 5.1 or 5.2.  Worse yet, if you upgrade a 4.x system
to 5.1 the old file will be left in place.  Linking against the old file will
result in executables that fail and dump core.

=============================================================================
 Notes for DEC OSF/1
=============================================================================

I believe these steps are not needed for PPR 1.40 or later.  If you have definite
information on this point, write to <ppr-bugs@mail.trincoll.edu>.

Installing PPR on DEC OSF/1 systems is straightforward.  The only
required system modification is to insure that the System V STREAMS
based modules are built into the kernel.

You should find kernel configuration parameters in the file
/sys/conf/HOSTNAME.  Examine the file and determine if the following
lines are present.

options     STREAMS
options     FFM_FS
options     PCKT

If the above are present all the necessary components are already in place.
Otherwise, you will need to rebuild the OS kernel using /usr/sbin/doconfig
as root.  In the doconfig script you will be asked to select kernel options.
Be sure to include the following: System V Devices, STREAMS, and File on File
Filesystem.  When doconfig finishes copy the new kernel to /vmunix and reboot.

From this point on, you should be able to follow the usual PPR
installation procedures.  When you run Configure, it will give you
the option of using the C compiler that comes with the operating system.

=============================================================================
 Notes for Linux 2.6.x
=============================================================================

Early versions of Linux 2.6.x have serious bugs in their drivers for parallel
printer ports and USB printers.  These bugs lead to a variety of problems
such as excessive CPU time consumption and the printing of pages and pages of
garbage.  PPR's "parallel" and "usb" printer interface programs will abort if
they detect these bugs.

The USB printer driver is broken in the 2.6.4 kernel distributed by Debian
but is fixed in 2.6.6.  The parallel port driver is still not fixed in
version 2.6.6.

=============================================================================
 Notes for SGI IRIX 6.3 and 6.5
=============================================================================

IRIX 6.5 includes Perl 5.004 which is a little to old to run the PPR web
interface.  Install a newer version and make sure it is first in your
path when you run Configure.

Make sure you have Bash installed and that /bin/bash is a either Bash or
a link to it. 

The make provided with IRIX has mysterious problems with some of the PPR
makefiles.  Use Gmake instead.  The required commands are:

$ gmake
$ gmake install

If you want to use lprsrv, then you must make lpsched stop binding to the lpd
port.  To do this, add -nobsd to the line in /etc/init.d/lp that starts
lpsched.

=============================================================================
 Notes for HP-UX 10.20
=============================================================================

When the xwin responder pops up an xterm with a message in it, you may find
that the close button does not work.  This is apparently due to a bug in
xterm.

If this happens to you, you might want to install Tcl/Tk and the xmessage
script described in the "X-Windows" section of this document.

It is reported that CAP60 AppleTalk support works.

=============================================================================
 Notes for ULTRIX
=============================================================================

This port is still inmature, so there are still problems.

The /bin/sh supplied with this system is very old.  It does not support
shell functions.  Fortunately, a more modern shell is supplied as /bin/sh5.
The Configure script uses shell functions.  So, to run it you must use
the command "sh5 Configure" rather than "./Configure".

This operating system may be missing the header files <sys/bitypes.h> and
<sys/cdefs.h>.  If so, try the following:

Link sys/bitypes.h to types.h and made a dummy sys/cdefs.h:
  #define __BEGIN_DECLS
  #define __P(x) x
  #define __END_DECLS

You may also notice that compiling with GCC is not an option.  If one does,
seteuid() and setegid() don't work correctly.  (They don't work perfectly
with the bundled compiler either, but they are better.)  Presumably there
is a way to fix this.

=============================================================================
 Notes for MS-Windows NT 4.0 and UWIN 2.0
=============================================================================

This port is new, so there are still problems.  These instructions are
out-of-date.

You will probably have to use the GUI tools to create the user "ppr".  Since
NT does not allow a group with the same name, after running Configure, you
will have to edit Makefile.conf and change GROUP_PPR to something else
and uncomment the line below its definition.

=============================================================================
 Notes for MS-Windows NT 4.0 and Cygwin
=============================================================================

This port is barely functional or non-functional.  You will probably have to
make some adjustments to the section in sysdep.h or Makefile.conf.  The install
may also require some manual intervention.  This is not for the
inexperienced user!

=============================================================================
 Notes X-Windows
=============================================================================

If your X-Windows distribution does not include xmessage, but you have Tcl/Tk,
then you can install the xmessage clone from the misc/ directory.  You should
probably put it in the /usr/bin/X11 directory.  This script is not a perfect
clone but it is good enough for PPR's purposes

=============================================================================
 Notes for MacOS X
=============================================================================

The MacOS port is preliminary.  In particular, the code in
z_install_begin/install_create_accounts.sh that creates the accounts ppr and
pprwww assigns them the ids 100 and 101 respectively.  It does not check to
see if these ids are already in use.  A patch to fix this would be welcome.

There is no AppleTalk support on MacOS X.  If anyone knows how to link to
the AppleTalk libraries, that would be very helpful.

=============================================================================
 Simple Compiling Instructions
=============================================================================

1) Unpack the PPR source archive in a suitable place.
   "/usr/local/src" is good.  You can do this with these commands:

	mkdir /usr/local/src
	cd /usr/local/src
	gunzip -c ppr-X.XX.tar.gz | tar xvf -

   Or if you have GNU Tar, you can change the last command to:

	tar zxvf ppr-X.XX.tar.gz

2) Change directory to "ppr-X.XX" and run "./Configure".  Answer the questions.

3) Run "make".

4) Run "make install" as root.

If you have problems building PPR and want to delve into the Makefiles, you
should probably read docs/misc/PORTING.txt first.

============================================================================
 Compiling from CVS
============================================================================

The documentation distributed in the PPR tarball is partially built.  If
built from CVS, you will have to install additional software in order to
build the documentation.  These programs are:

* xsltproc
* Doxygen
* Transfig
* Docbook XSL stylesheets (in nonppr_misc/docbook-xsl-1.60.1)
* HTMLDOC

============================================================================
 Hacking Without Being Root
============================================================================

Note that if you start hacking PPR, you won't always need to run "make
install" as root.  The first time it runs it will create a user called
"ppr".  If you subsequently do "chmod -R ppr:ppr ppr-X.XX" to set the
ownership of the source directory, you can work in it as the user "ppr",
make changes, and do "make install" as that user.  However if you edit a few
specific things such as a setuid root program or the init script, "make
install" will stop and tell you that it needs to be run as root (at least in
that one directory).

============================================================================
 Making Binary Distributions
============================================================================

If you are compiling a binary distribution of PPR, such as an RPM, you can
use the variable RPM_BUILD_ROOT to control where "make install" installs
PPR.  If this environment variable is set, then its contents will be
prepended to all install paths.  The sample ppr.spec uses this feature.

For example, here are commands to build a tar archive binary distribution
from a configured and built PPR source directory:

$ mkdir /tmp/ppr-binary
$ make RPM_BUILD_ROOT=/tmp/ppr-binary install
$ cd /tmp/ppr-binary
$ tar zcvf ../ppr-binary.tar.gz .

An RPM spec file (called ppr.spec) can be found in the top-level source
directory.

A Debian package can be found in debian/.

============================================================================
 Upgrading from previous versions
============================================================================

PPR version 2.XX's directory layout is significantly different from 1.5X.
For this reason it was not though wise to install version 2.XX over
1.5X.  Therefor by default PPR 2.XX installs itself in new directories 
which means it can be installed alongside PPR 1.XX.

PPR 1.XX directory       Cooresponding PPR 2.XX directory
-----------------------------------------------------------------------
/etc/ppr                 /etc/ppr2
/usr/lib/ppr             /usr/lib/ppr2
/usr/share/ppr           /usr/share/ppr2
/var/spool/ppr           /var/spool/ppr2

Once you have installed PPR 2.XX, you can copy your printer, group, and
alias configuration files from /etc/ppr to /etc/ppr2 and restart PPR 2.XX.

============================================================================
 End of instructions for compiling PPR
============================================================================