Schedtop version 5.02
=====================

Schedtop is derived from pbstop, and this package it now able to build both 
pbstop (for Torque), and slurmtop (for Slurm). Both pbstop and slurmtop share
the same functionality through the common Perl module schedtop.pm. Since 
Torque, unlike Slurm, does not come with a Perl API, this package also 
builds a Perl API for PBS when building pbstop.


PBSTOP

This package contains the 'pbstop' interactive monitoring program.  It is a
fully-functional and highly useful way to monitor your cluster.  After
installing, 'man pbstop' and 'pbstop -h' to get started.

PBS (version 0.35)

This is a perl binding for the Portable Batch System client library (as from
Torque).  This allows you to stat the server, nodes, or jobs, submit
jobs, alter jobs, etc.  Demo code is included.

Specifically, the ifl, rpp, and rm APIs are implemented here.

SLURMTOP

This package contains the 'slurmtop' interactive monitoring program.  It is a
fully-functional and highly useful way to monitor your cluster.  After
installing, 'man slurmtop' and 'slurmtop -h' to get started.


DEPENDENCIES

This module requires these other modules and libraries:

   Torque client libraries and programs (pbstop only)
   Slurm client libraries and programs (slurmtop only)
   Curses perl modules from CPAN
   optionally, swig >= 1.3.19 (if you want/need to rebuild PBS_wrap.c)

swig 1.3.21 is known not to work.  If you need to generate a new PBS_wrap.c
(and you probably don't), consider upgrading to version 3.0.2 or later.


INSTALLATION

To build and install schedtop type the following:

   perl Makefile.PL <slurmtop|pbstop>
   make
   make test (pbstop only)
   make install

If the first step fails to find pbs_ifl.h or libpbs.a (or it finds ones that
you don't want to use), export PBS_INCLUDE and PBS_LIB with the directories
that contain those files and try it again.

If there are any problems building PBS_wrap.c, then make sure swig >= 1.3.19
is installed and touch PBS.i.  This will force the generation of a new
PBS_wrap.c and PBS.pm.

Makefile.PL uses ExtUtils::MakeMaker to create the Makefile, I recommend
reading 'perldoc ExtUtils::MakeMaker' for a wealth of valuable options.


DEMO CODE

There are currently three demo programs in the demos/ directory.  They are simple
scripts to demonstrate the data structures used by the module.  To run them,
simply type the following commands after building the module:

   perl demos/dumpmom
   perl demos/pbsnodes-a
   perl demos/qstat-f

Those demo programs optionally take one argument, nodenames or a jobid
respectively,  Set the PBS_DEFAULT environmental variable to change the server
hostname.  Note that the output of those programs is almost identical to the
"real" versions distributed with Torque (qstat-f just needs to fold
the longer output lines).  'dumpmom' contacts the RM on the given node and
prints out some interesting information (this might need to be run as root).


GENERATED FILES

PBS_wrap.c and PBS.pm are generated by swig from PBS.i.  Any modifications to PBS.i 
will cause them to be regenerated.  Unlike in the past, you will need to use
the PBS.pm generated by swig, merged with the provided one in the src directory.
This is taken care of by the build process.

If you change the "PBS" module's version number in VERSION, be sure to also change it in
t/01_PBS.t and near the top of this file.


SUBPACKAGES

The PBS::rm and PBS::rpp subpackages are fakes.  All they do is import the
correct symbols from the main PBS package.  Their real purpose is convenient
packaging of documentation.  That said, I think it will also help
user-programmers to better compartmentalize their programs.


COPYRIGHT AND LICENSE

Copyright (C) 2004, 2005, 2006 Garrick Staples

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation or under the same terms as perl itself.

