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

  Copyright 2008, 2009 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".

Dependencies
============

To build GNUspool you will probably need YACC or preferably BISON,
however the grammar files are provided.

You will also probably need LEX or preferably FLEX, however the
lexical files are provided - but you will need the FLEX library.

You should have either a recent version of GTK+ or Motif to build the
X parts but you can make do with the "curses" option if you don't -
just ignore any build error with those - the "make" passes over those
directories if they don't build.

Some parts of the installation process use Perl scripts.

The optional CUPS emulation daemon uses Python.

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
================

Libtool is now used to build shared libraries portably so this is
turned on for most programs.

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.

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

The first time you attempt to install you should create a new system user
"gnuspool", which owns all the GNUspool files. This is done using a Perl
script which knows about common layouts of password and shadow files.
Invoke it using the command

       make install-user

You should only need to do this once per system.

(The configure script allows you to select a different user name if
you want but only do this if you know what you're doing).

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

Use

	make install

to install the various programs and data in the right places.

DON'T WORRY about errors in building the GTK programs or if you don't
have a recent version of GTK - you can still run most of the software
but you'll have to use the "curses"-based gspl-xpq. If you have a
Motif library on your system you might want to try that.

Then set the network entries (if you haven't created them from a
previous installation) with

	make install-net

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.

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.

CUPS Emulation
==============

To emulate CUPS printers for software which requires them, see the
"cupspy" subdirectory. You will need Python for this.

John Collins
July 2008 with updates March 2009 more updates April 2009
