Installation

This section describes the procedure for downloading the latest version of PyPBS and installing it on your location.

System Requirements

Operating System

Any UNIX, Linux, and other platforms (basically operating systems striving to achieve POSIX compliance) on which you can compile Python, SWIG, gcc, and OpenPBS should be able to compile this module. So far, we have only tried various versions of RedHat Linux on i386 platforms. However, the module should work on many others. Please let us know if you are able to compile on any other platforms (of course, we will hear from you if you have trouble compiling this module :-).

Python

This is a Python module; needless to say that it will be quite useless if you do not have Python installed on your system. We have successfully compiled and used this module on Python versions 1.5.7, 2.1, and 2.2. It should work for all later versions too. If you manage to compile and use it with any other versions of Python please drop us an email.

If you do not have Python if this module refuses to work with your version of Python, you can download the latest version from [BIB.PYTHON-HOME-PAGE].

SWIG

SWIG is an extremely useful package if you want to allow access to your software libraries from high-level scripting languages such as Python, Perl, Java, Tcl and such. We use SWIG to generate the wrapper code needed to access the OpenPBS library routines from Python.

At present (early 2002), SWIG is going through some major changes; all good, of course. This also means that it is essential that you use the correct version of SWIG while compiling this module. We suggest that you have SWIG version 1.3.10 or higher. This module will definitely not work with version 1.1 (it will compile but will not work as intended). It may work with other version in the 1.3.x series but we have not tried that. If you are able to use any version of SWIG other than 1.3.10 to compile this module, please let us know.

C Compiler

The module generated by PyPBS is in the form of a shared library and a Python wrapper file. In order to create the shared library, you will need a C compiler package. We expect that any C compiler which is able to compile Python, SWIG, and OpenPBS will be able to compile this module too. So far, we have tried various versions of GNU gcc (2.91.66, and 2.96 for sure) on RedHat Linux 6.1 through 7.2 and everything works like a charm. If you are able to compile and use this module using any other compiler or on any other distribution or operating system, please drop us a line.

OpenPBS

Of course, you need OpenPBS installed on your system to compile and use this module. In particular, you must have compiled the OpenPBS library and have the associated header files available (in particular pbs_ifl.h). PyPBS extracts a list of variables, structures, and functions from the pbs_ifl.h file and the corresponding object code from libpbs.a.

Important

The file pbs_ifl.h distributed with OpenPBS refers to a function named pbs_statdest. However, this function is never defined anywhere in the source code (atleast, I could not find it in any of the C or header files). As a consequence, the OpenPBS library does not contain this function.

The PyPBS package uses the file pbs_ifl.h to extract the names and prototypes of all the functions to support in the Python module. Obviously, it also picks up the pbs_statdest function and attempts to compile it in the OpenPBS module of the PyPBS package. Needless to say, this does not work. In order to avoid this problem, we need to remove the declaration of the pbs_statdest function from pbs_ifl.h. We have a script in the Makefile which automatically takes care of this (or atleast is supposed to). However, this script is not perfect and if you get any errors related to this function, please comment out this function declaration from your local pbs_ifl.h file. If you do not have write access to the pbs_ifl.h file, you can remove the function declaration from the src/pbs.i file that is generated by PyPBS and then recompile the module. If you still have problems or if all this is not making any sense at all, please send an email to us.

This module works with any version of OpenPBS after version 2.3.12. It might work with some older versions too but we have never tried this. If you manage to use this module with older versions of OpenPBS, please send us an email.

Obtaining PyPBS Source Code

The latest version of PyPBS source code can be obtained from PyPBS SourceForge Page. The source code is available as a compressed archive file named pypbs-<version>.tar.gz where <version> will be a version number such as 0.1. Once you obtain this file, you can extract the source code from it using a command like the following:

gzip -dc pypbs-0.1.tar.gz | tar xvf -

This will create a new directory named pypbs-0.1 which contains the source code for PyPBS package and associated documentation. The rest of this section assumes that this newly created directory is your current working directory i.e. you should enter this directory and run the rest of the commands from this directory.

Configuration, Compilation and Installation

Quick Install

If the required packages such as OpenPBS, SWIG, Python and C Compiler are installed at fairly standard locations, you should be able to compile and install PyPBS using the following commands:

./configure
make
make install

This will install the PyPBS package files under the directory /usr/local/lib/pypbs. You should add this directory to you PYTHONPATH environment variable to access the module from Python.

Configuration Options

The configure script in the top-level directory of the PyPBS source code provides several customization options. You can get a list of these options using the command:

./configure --help

In most cases, you would probably end up using one or more of the following options in order to configure PyPBS:

--prefix=PREFIX

This option is used to specify the directory under which the module files will be installed. For example, consider the following command:

./configure --prefix=/home/foo/pypbs

In this case, the module files will be installed in the directory /home/foo/pypbs/lib/pypbs/. You can use this option to customize the location of the PyPBS installation.

--with-swig=PATH

If the SWIG executable is not accessible from your PATH environment variable, then you can use this option to specify its location. For example, if SWIG is available under /home/foo/swig/bin then you would use the following command:

./configure --with-swig=/home/foo/swig/bin/swig
--with-python=PATH

If the PYTHON executable is not accessible from your PATH environment variable, then you can use this option to specify the its location. For example, if PYTHON is available under /home/foo/python/bin, then you can use the command:

./configure --with-python=/home/foo/python/bin/python
--with-pbs=PATH

If OpenPBS library and header files are installed at a non-standard location on your system, then you can use this option to specify their location. For example, if OpenPBS headers are installed under /home/foo/openpbs/include and the OpenPBS library is under /home/foo/openpbs/lib, then you can use the command:

./configure --with-openpbs=/home/foo/openpbs

If the configure command you use finishes without any error messages, you should be able to compile and install PyPBS using the commands:

make
make install

How PyPBS Creates Python Bindings

You do not need to read this section to use the PyPBS package. It briefly describes the procedure used by PyPBS to generate the Python module and might of interest to people who want to generate similar bindings for other libraries. You can skip this section if you are not one of these people.

The procedure through which PyPBS generates the Python module for accessing the OpenPBS library functions is quite simple. In fact, most of the real work is done by the SWIG package; we just provide the "interface file" needed by SWIG. In order to make sure that this interface file is consistent with your OpenPBS installation, we generate the interface file, src/pbs.i, directly from the pbs_ifl.h that is installed on your system. Please read the SWIG documentation if you want to understand the format of this interface file.

The file src/pbs.i.top contains the header part of the interface file. This part does not depend on the version of OpenPBS you have. The file src/pbs.i.h is used to extract all the variable and function declarations and preprocessors macros contained in your local pbs_ifl.h file using the C processor cpp. You can peek into the file src/Makefile.am to see how this is done. Finally, a small awk script is used to remove the declaration of the function pbs_statdest from the interface file (see the section called OpenPBS for the reason for doing this).

After the interface file has been generated, it is used to obtain the Python wrapper code using the SWIG utility. SWIG generates the wrapper file src/pbs_wrap.c which gets compiled into a shared library file src/pbscmodule.so. SWIG also generates the pbs module file src/pbs.py which contains the shadow classes necessary to access the OpenPBS library routines. The two files, src/pbscmodule.so and src/pbs.py, are the files needed to access OpenPBS library routines from Python.