Installing and building GNUbatch
================================

  Copyright 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.

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

GNUbatch uses a configure script generated by Autoconf. This generates
all the internal Makefiles.

PLEASE NOTE that the following packages are assumed to be present:

Bison or YACC
Flex or Lex
Ncurses (including the development library and includes - note various
versions of GNU/Linux and UNIX require you to load the development
package as well as the binaries.
GTK+ library (and development library where applicable). (Note that
GNUbatch will build without the GTK+ library but obviously the GTK
clients won't be built..

On some systems GTK+ isn't available but Motif is - you might want to
try that.

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 using --with-spool-directory=/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/gnubatch,
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 GNUbatch 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 GNUBATCH.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/gnubatch.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.

Gnubatch user
=============

The first stage of install attempts to create a new system user
"gnubatch", who owns all the GNUbatch 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 GNUbatch in /etc/services. It will warn you if there are possible
conflicts and abort if completely confused.

To communicate with other hosts running GNUbatch and share jobs and
variables, you will need to set up a file
${prefix}/etc/gnubatch.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 "gbch-hostedit", moved to the
$exec_prefix/sbin directory, can be used to set up the required host
name entries, thus

gbch-hostedit -I /usr/local/etc/gnubatch.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
batch scheduler 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
batch scheduler.

Starting the batch scheduler
============================

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

gbch-start -j 200 -v 500

This will start the scheduler and reserve space for 200 jobs and 500
variables. You can put just "gbch-start" but that will allocate the
maximum amount of shared memory for jobs and variables which is
probably unnecessary.

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

Submitting a batch job
======================

We suggest you create a simple batch job by typing

echo sleep 10|gbch-r -C -h tryit

Next invoke gbch-xq. This should display a screen showing the job with
a title of tryit. Try selecting the job and use the menu to select
various job attributes.

You can also set it runnable and it should start running and display
as running for 10 seconds before stopping.

You may want to learn about variables, conditions and assignments
before you go further.

Networking
==========

Please see the manuals as to how jobs and variables can be shared
across the network by editing the file /etc/gnubatch.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/gnubatch.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 "gbch-quit" or "gbch-quit -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
February 2009
