Installing and building GNUspool
================================

  Copyright 2008 Free Software Foundation, Inc.

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.

----------------------------------------------------------------------

GNUspool uses a configure script generated by Autoconf. This generates
all the internal Makefiles and a printer installation script.

After running configure, run "make" and then as superuser "make
install".

Options to configure
====================

Run "configure --help" to see the various options. These include the
standard "prefix" and "exec_prefix" options which default to
/usr/local.

WARNING: You may want to consider locations in which to store the
spool directory and alternate spool directory using
--with-spool-directory=/new/dir and
--with-alt-spool-directory=/another/new/dir as these can become very
large if a lot of large files are being printed.

There are also some specific options which determine which mechanism
of shared memory or file locking is to be used.

Shared Memory
=============

You can select either:

1.  Shared memory itself --disable-using-mmap
2.  Memory-mapped files. --enable-using-mmap (default)

The reason there is a choice of this is because shared memory is
sometimes very restricted in its size or there are strange bugs on
some kernels.

Memory-mapped files can be used to achieve the same purpose, however
they take up space in the spool directory, usually /var/spool/gnuspool,
as opposed to the swap area.

There is otherwise little to choose performance-wise.

Note that the default is to use memory-mapped files, so please check
that there is enough space in the relevant filesystem, specify a
different home for the spooldir by default using
--with-spool-directory=/new/dir

File locking
============

This is for locking access to the shared memory (or memory-mapped files)

You can select either:

1.  Semaphores --disable-using-flock
2.  File-locking --enable-using-flock (default)

Semaphores are evil because all kinds of nasty things can happen if
there are not the right amount of "locks" and "unlocks" (not that that
happens in my code of course) and non-deterministic things can happen
if processes exit unexpectedly. There is a resource called "undo
structures" which can be seriously limited on some UNIX kernels (but
not Linux ones).

Unless you are a complete glutton for punishment I suggest you stick
to file locking which is the default. Locks are set on the
memory-mapped file or a separate lock file if shared-memory is used.

Shared libraries
================

The option --enable-sharedlibs will build GNUspool to use shared
libraries for the internal library rather than statically
linking. Curses-based routines go into a separate library to avoid
cluttering various software that doesn't use it.

Executive summary
=================

At the first attempt, just run "configure" and see how it goes. Try
fancy options later.

Building
========

After running configure, type "make". It should build all the main
programs and halt.

Note that help messages are extracted from GNUSPOOL.msg and some help
files created according to the usage in the modules. This happens
using a program "helpparse" created during the first stage of the
build, in "util". Edited sources are put in the "build" directory and
the actual build takes place there.

If you are building the Motif programs, cd to build/motif and run
"make" from there after the main make has completed (see next
paragraph).

I hope I've covered all known hardware.

Note that hdrs/infiles.h.in is used to make hdrs/infiles.h and then this is
edited to make hdrs/files.h. This is to avoid nested ${${prefix}}
constructs in the header file.

Motif
=====

A Makefile for Motif is generated, if you have the Motif library you
can try it by entering the Motif subdirectory and typing "make".

Motif is not supported by GNU so only do this if you've got that and
not GTK+. It is a much inferior X toolkit as it doesn't do mouse
wheels nor does it do drag and drop properly. There are all sorts of
weird things that make it crash.

Please don't use LessTif as that has some strange bugs like "wrap
around" on spin boxes doesn't work properly.

Installation
============

Use "make install" to install the various programs and data in the
right places.

There is provision to relocate files and directories in other places
than where the software was built for, using the file
${prefix}/etc/gnuspool.conf Please note that "make install" doesn't
currently support this, so please don't try to change where things are
put when you install. Instead reconfigure and rebuild if you've done
it wrong.

I'll fix this fairly soon.

Gnuspool user
=============

The first stage of install attempts to create a new system user
"gnuspool", who owns all the GNUspool files. This is done using a Perl
script which knows about common layouts of password and shadow files.

Network setup
=============

The second stage of install attempts to create services entries used
by GNUspool in /etc/services. It will warn you if there are possible
conflicts and abort if completely confused.

To communicate with other hosts running GNUspool and share jobs and
printers, you will need to set up a file
${prefix}/etc/gnuspool.hosts. This may be set up initially by the
network script if it is sure about the IP address of the local host.

Later on the interactive program "gspl-hostedit", moved to the
$exec_prefix/sbin directory, can be used to set up the required host
name entries, thus

gspl-hostedit -I /usr/local/etc/gnuspool.hosts

Running the GTK programs
========================

Most of the user binaries are set-user and many X servers have to be
told to accept the use of such programs with the command

xhost +

Someone may be able to tell me a better way of doing this.

Setting yourself up as a super-user
===================================

We think you will want to be "super-user" for the purposes of the
spooler and the last thing that "make install" does is to set you (or
the login that "who am i" gives up as administrator for the spooler.

Starting the spooler
====================

Once "make install" has completed successfully, start the spooler by
typing (for example)

gspl-start 200 10

This will start the spooler and reserve space for 200 jobs and 10
printers. You can put just "gspl-start" but that will allocate the
maximum amount of shared memory for jobs and printers which is
probably unnecessary.

You will probably want to insert this command into the system startup
scripts at some point.

Installing printers
===================

In the system bin directory (by default /usr/local/sbin) a Perl script
gspl-ptrinstall is created. Please use this to create a printer
description and install it.

This is fairly interactive owing to the huge number of options, but it
does find out what it can. We suggest that you first connect a printer
on a network device which will use LPD protocol and take PCL.

Submitting a print job
======================

We suggest you create a simple print job by typing

gspl-spr -f notyet /etc/hosts

(/etc/hosts being a short text file).

Next invoke gspl-xpq. This should display a screen showing the job
with a title of hosts and possibly the newly-installed printer. Try
selecting the job and use the menu to select various job attributes.

You can also select the printer and perhaps start it from the menu,
the right-click menu or shift-G.

Unless the form type on the job matches the printer (which is unlikely
as the form type is initially set to "standard" for each user *CHANGE
THIS*, nothing will happen yet (although the printer type will change
to idle).

Next change the form type of the job to match the printer. The job
will show the printer it is being printed on and the "progress" bar
will shift across to 100%. When complete it will disappear and the job
should be printed.

Networking
==========

Please see the manuals as to how jobs and printers can be shared
across the network by editing the file /etc/gnuspool.hosts to indicate
which hosts to attach to. This should be done on each machine using
the "hostedit" program described above.

Very quickly I suggest you build it on two machines and have
/etc/gnuspool.hosts on machine.one have the following contents

localaddress ip.address.of.machine.one
machine.two	-	probe,trusted

and vice versa on machine.two

Stop and restart on both machines and it should interconnect.

Stopping the scheduler
======================

Before shutting down, run "gspl-stop" or "gspl-stop -y" to avoid the
confirmation question to shut down the scheduler. You will probably
want to insert the command into the system shutdown script at some
point. You may find the shell scripts in STARTUP helpful for this.

John Collins
July 2008
