STAF V3 Developer's Guide

Software Testing Automation Framework (STAF) Developer's Guide

August 4, 2005

Version 3.0.0


Contents

·  Introduction

·  Obtaining the STAF Source Code

·  Requirements for Building STAF

·  Explaining the STAF Source Tree and Build Environment

·  Building STAF

·  Running STAF from the Built Executables

·  Running on Unix

·  Running on Windows

·  Explaining how STAF is Packaged for Installation

·  STAF Design Documentation

·  STAF Coding Conventions

·  Debugging on Linux

·  Reporting/Browsing/Fixing Bugs and Features

·  Appendix A: Important Links

·  Appendix B: Common CVS Commands

·  Appendix C: New Developer Activities

·  Join the Open Source STAF Development Projects

·  Subscribe to Mailing Lists and Monitor Newsgroups

·  Appendix D: Shutting Down STAF on Unix


Introduction

 

This document explains how to build STAF. It assumes that you are familiar with the operating system(s) in question and the process of building software in general. It will walk you through the process of:

  1. Obtaining the STAF source code
  2. Setting up your build environment
  3. Building STAF
  4. Using the output of the build

STAF developers are the intended audience for this document.


Obtaining the STAF Source Code

 

Externally open sourced STAF code is available on SourceForge via two methods:

Obtaining STAF Source Code Via a Tar File

Each tar file contains a snapshot of the source code for a released version of STAF.

  1. Download the tar file for the STAF Version you want from SourceForge (e.g. STAF300-src.tar.gz) from http://staf.sourceforge.net/getcurrent.php.
  2. Uncompress the tar file:
gunzip STAF300-src.tar.gz
  1. Untar the file:
tar -xvf STAF300-src.tar

Obtaining STAF Source Code Via CVS

The current STAF code is contained in CVS, including code that has not been released yet.

  1. If on Windows:
    1. Open a Cygwin window.
b.                 cd /cygdrive/d

Where d is the drive where you want to put STAF code.

c.                 md build

Where build is the name of the directory to where you are checking out STAF code.

d.                 cd build
  1. If on Unix:
    1. Log on as root
b.                 cd /
c.                 mkdir build

Where build is the name of the directory to where you want to check out STAF code.

d.                 cd build
3.           export CVS_RSH=ssh

This must be done once for each window.

  1. The following command only needs to be done once per userid to set up your account. Change developername to your userid.
ssh developername@staf.sourceforge.net

Enter your SourceForge password when prompted. Exit.

  1. The following command only needs to be done once per userid to create your home directory (e.g. /home/users/d/de/developername). Change developername to your userid.
ssh developername@cvs.staf.sourceforge.net

Enter your SourceForge password when prompted. You cannot execute anything here so it will exit for you.

  1. The following command only needs to be done once per system to check out code. It specifies where the cvs root is, that you are doing a check out (co), and the directory (src) from the root of the code you are checking out. Change developername to your userid.
cvs -d :ext:developername@cvs.sourceforge.net:/cvsroot/staf co src

Enter your SourceForge password when prompted.
Enter Yes if prompted to permanently add cvs.sourceforge.net to the list of known hosts.

7.           cd src/staf
8.           cvs update

Enter your SourceForge password when prompted.
Refer to the "Common CVS Commands" section for more information on "cvs update".


Requirements for Building STAF

 

To build STAF, you need to install the following software based on the operating system where you are building:

To build the Java interface component of STAF and to build any STAF services written in Java, you need to install Java. Currently, we are mostly using Java 1.3.1 (IBM or Sun), but also support Java 1.4.0.

To build the REXX interface component of STAF, you need to install REXX.


Explaining the STAF Source Tree and Build Environment

 

All STAF source code is contained in the /src/staf directory. This is the directory from which you run 'make' to build various STAF projects.

The STAF uses the "whole-project makefile" approach described in Peter Miller's Recursive Make Considered Harmful article.

The /src/staf/stafif directory contains STAF daemon and internal STAF Services source code.
The /src/staf/stafproc directory contains STAF C interface library source code.
The /src/staf/services directory contains source code for external STAF services like Log, Monitor, and Resource Pool.

Any operating system specific code is contained in a subdirectory (e.g. win32, unix) under the STAF component.

There are subdirectories for each language in which STAF services can be implemented in the /src/staf/lang directory.

The STAF source tree looks like the following:

 
/src/staf/                - Contains all STAF source code
/src/staf/makefile        - The master STAF makefile
/src/staf/build/          - Contains auxilliary makefiles used in building STAF
/src/staf/codepage/       - Contains additional code pages
/src/staf/docs/           - Contains STAF documentation, including makefile to build STAF docs
/src/staf/History         - A file containing a history of changes made to STAF by version
/src/staf/install/        - Contains STAF installation source code
/src/staf/install/unix/   - Contains the STAFInst program used to install from a STAF tar file
/src/staf/install/ismp/   - Contains InstallShield Multi-Platform source code for installing STAF
/src/staf/lang/           - Contains source code for supporting the different languages in which
                            STAF services can be implemented
/src/staf/lang/java/      - Contains source code for supporting STAF services implemented in Java
/src/staf/lang/jython/      - Contains source code for supporting STAF services that package Jython
/src/staf/lang/perl/      - Contains source code for supporting STAF services implemented in Perl
/src/staf/lang/rexx/      - Contains source code for supporting STAF services implemented in REXX
/src/staf/lang/tcl/       - Contains source code for supporting STAF services implemented in Tcl
/src/staf/lang/python     - Contains source code for supporting STAF services implemented in Python
/src/staf/package/        - Contains makefiles used for packaging STAF
/src/staf/samples/        - Contains sample source code showing how to interact with STAF from
                            different languages such as C, C++, and REXX
/src/staf/samples/demo/   - Contains the STAF Demo source code
/src/staf/services/       - Contains source code for external STAF services like Log, Monitor, and
                            Resource Pool, STAX
/src/staf/stafclnt/       - Contains STAF command line utility source code
/src/staf/stafif/         - Contains STAF C interface library source code
/src/staf/stafinfo/       - Contains the STAF information utility source code
/src/staf/stafproc/       - Contains STAF daemon and internal STAF Services source code
/src/staf/stafreg/        - Contains source code for the STAF Registration program
/src/staf/test/           - Contains source code used to test STAF
/src/staf/utils/          - Contains source code for STAF utilities like fmtlog (Format Log Utility)
/src/staf/webpages/sf     - Contains source code for the STAF SourceForge web pages

Building STAF

 

This section describes how to build STAF from a valid source tree.
STAF's master Makefile is located in the /src/staf directory. See it for additional information about the environment variables used.

To build a IPv6 enabled version of STAF, the STAF_USE_IPV6 variable needs to be set. For example: export STAF_USE_IPV6=yes.

  1. If on Windows, do the following steps in a Cygwin window.
  2. Check out the latest STAF source code (if not already checked out). Refer to the "Obtaining the STAF Source Code" section.
3.           cd /build/src/staf

Assuming /build is the directory where you checked out STAF source code.

  1. Set the appropriate environment variables:
    • OS_NAME - Set to the operating system where you are building STAF. Valid values for OS_NAME are documented in the master STAF make file. Some of the values are: linux, win32, aix.
    • BUILD_ARCH - Set to the architecture type being used. Currently, this is only supported for HP-UX builds. Valid values are: PA-RISC, IA64-32, and IA64-64. The default value is PA-RISC.
    • CC_TYPE - Set to the type of compiler being used. Currently, this is only supported for Windows builds. Valid values:
      • MVC6 - Microsoft Visual C++ 6 (This is the default)
      • MVC7 - Microsoft Visual C++ 7 (also known as Microsoft Visual Studio.NET 2003)
      • MVC-SDK-IA64 - The IA-64 compiler shipped as part of the Microsoft Platform SDK (currently, we have only validated the compiler shipped as part of the February 2003 Platform SDK, but others may work)
    • MSVCDIR - If on Windows, set to the directory where you installed the Microsoft Visual C/C++ Compiler. For example:
  export MSVCDIR=c:/MVStudio
    • VSCOMMONDIR - If on Windows, set to the Microsoft Visual C++ Compiler's COMMON directory. For example:
  export VSCOMMONDIR=d:/MVStudio/Common

Note: The VSCOMMONDIR environment variable is not needed if you selected the default install location for the common Microsoft Visual C++ components.

    • MSSDKDIR - If on Windows, set to the directory in which you installed the Micosoft Platform SDK. For example,
  export MSSDKDIR=d:/MicrosoftSDK

Note: MSSDKDIR only needs to be set if you are building IA-64 code for Windows. Typically, only MSSDKDIR or MSVCDIR (and, possibly, VSCOMMONDIR) need to be set. You don't normally need to set both.

    • BUILD_TYPE - Set to either retail or debug.
    • PROJECTS - Set to the project(s) that you want to build. Valid projects are:
      • all - Builds all of the STAF projects
      • staf - Builds the STAF core code
      • connprov* - Builds the STAF TCP/IP and Local connection providers
      • java - Builds the STAF Java Interface
      • rexx - Builds the STAF Rexx Interface
      • docs - Builds the STAF documentation
      • demo - Builds the STAF Demo
      • jython - Builds the STAF Jython package that is packaged with some STAF services such as the STAX, EventManager, and Cron services
      • Plus many more (e.g. stax, event, cron, etc.)

The PROJECTS environment variable can be set to any valid project or to multiple projects (in double quotes and separated by a space). For example, PROJECTS=staf or PROJECTS="staf connprov* java docs"

    • If building the java project or a STAF service that is written in Java, the following environment variables must be set:
      • JAVA_DRIVE - If on Windows, set to drive where you installed Java
      • JAVA_LIBS - set to jvm
      • JAVA_VERSION - set to the version of Java use are using. For example, 1.3
      • JAVA_BUILD_V11 - set to 1 if using Java 1.1.x; otherwise set to 0. Note that STAF now requires Java 1.2 or later so the default for this environment variable is 0.
      • JAVA_BUILD_V12 - set to 1 if using Java 1.2 or later; otherwise set to 0. Note that STAF now requires Java 1.2 or later so the default for this environment variable is 1.
      • JAVA_V12_ROOT - set to the location where you installed Java. For example, on Windows, if Java is installed in D:\ibmjdk1.3, specify /cygdrive/d/ibmjdk1.3
      • JAVA_V12_LIBDIRS - set to the Java lib directory. For example on Windows, if Java is installed in D:\ibmjdk1.3, specify /cygdrive/d/ibmjdk1.3/lib
  1. To start the build, type:
  make

You may want to put these commands in a shell script that you run instead, e.g. ". ./setstaf.sh". Examples of some common shell scripts that you make want to use are:

·                  export PROJECTS="staf connprov*"
·                  export OS_NAME=win32
·                  export BUILD_TYPE=retail
·                  export MSVCDIR=d:/MVStudio                (Only needed if on Windows)
·                  export VSCOMMONDIR=d:/MVStudio/Common     (Only needed if on Windows)
·                  export MSSDKDIR=d:/MicrosoftSDK           (Only needed if on Windows and building IA-64 code)
  make
·                  export PROJECTS=java
·                  export JAVA_DRIVE=d
·                  export JAVA_LIBS=jvm
·                  export JAVA_VERSION=1.3
·                  export JAVA_BUILD_V11=0
·                  export JAVA_BUILD_V12=1
·                  export JAVA_V12_ROOT=/cygdrive/d/ibmjdk1.3
·                  export JAVA_V12_LIBDIRS=/cygdrive/d/ibmjdk1.3/lib
·                  export JAVA_V12_BIN_DIR=/usr/java_dev2/sh  (this is only required on AIX, when using Java 1.2+ to build)
  make
·                  export PROJECTS=docs
·                  export OS_NAME=win32
·                  export BUILD_TYPE=retail
·                  export B2H_ROOT=d:/tools/b2h
·                  export JAVA_V12_ROOT=d:/tools/sunjdk1.4
·                  export SAXON_ROOT=d:/tools/saxon
·                  export DOCBOOK_ROOT=d:/tools/docbook
·                  export MSVCDIR=d:/MVStudio                (Only needed if on Windows)
·                  export VSCOMMONDIR=d:/MVStudio/Common     (Only needed if on Windows)
·                  export MSSDKDIR=d:/MicrosoftSDK           (Only needed if on Windows and building IA-64 code)
  make

Notes:

·                 
·                  export PROJECTS=rexx
·                  export OS_NAME=win32
·                  export REXX_ROOT=/cygdrive/d/ObjREXX
·                  export REXX_LIBDIRS=d:/ObjREXX/API
·                  export RXPP_ROOT=d:/tools/rxpp
  make

Note that you need to have RXPP installed in order to build the STAF Documentation. On Windows, you should download the rxpp.tar file (available on staf1b.austin.ibm.com in the /tools directory) to d:/tools/rxpp, and untar the file in this directory.

·                 
·                  export PROJECTS=perl
·                  PERL_V58_ROOT ?= c:/perl583
·                  PERL_V58_INCLUDEDIRS ?= $(PERL_V58_ROOT)/lib/CORE
·                  PERL_V58_LIBDIRS ?= $(PERL_V58_ROOT)/lib/CORE
·                  PERL_V58_LIBS ?= perl58
·                  PERL_BUILD_V58 ?= 1
·                  PERL_V56_ROOT ?= c:/perl
·                  PERL_V56_INCLUDEDIRS ?= $(PERL_V56_ROOT)/lib/CORE
·                  PERL_V56_LIBDIRS ?= $(PERL_V56_ROOT)/lib/CORE
·                  PERL_V56_LIBS ?= perl56
·                  PERL_BUILD_V56 ?= 1
  make

Note that you need to have (on Windows or Linux) ActivePerl 5.6 and 5.8 installed. It can be downloaded from http://aspn.activestate.com/ASPN/Downloads/ActivePerl/ After installing ActivePerl, note that if you are using cygwin, when you are running STAF perl testcases, you must fully-qualify where the perl binary exists (i.e., /cygdrive/d/perl/bin/perl teststaf.pl).

To run perl testcases, you must set the environment variable PERLLIB=c:/staf/bin.

To build STAF support for Perl 5.0 on Linux, you need to build project "perl50". The "perl" project will only build STAF support for Perl 5.6 and Perl 5.8.

·                 
·                  export PROJECTS=python
·                  export OS_NAME=win32
·                  export PYTHON_ROOT=d:/python
·                  export PYTHON_INCLUDEDIRS=d:/python/include
·                  export PYTHON_LIBDIRS=d:/python/Libs
·                  export PYTHON_ROOT=d:/python
·                  export PYTHON_LIBS=python22
  make

Note that you need to have (on Windows) Python 2.2 installed. It can be downloaded from http://www.python.org/2.2.1/ Note that that you must run a RETAIL build for Python (a DEBUG build will fail).

To run python testcases, you must set the environment variable PYTHONPATH=c:/staf/bin (or else copy the .pl file to c:/staf/bin and run it from that directory).

·                 
·                  export PROJECTS=tcl
·                  export OS_NAME=win32
·                  export TCL_INCLUDEDIRS=d:/tcl/include
·                  export TCL_LIBS=d:/tcl/lib/tcl83
  make

Note that you need to have (on Windows) TCL 8.3 installed. It can be downloaded from http://tcl.sourceforge.net.

To run tcl testcases, you must set the environment variable TCLLIBPATH=c:/staf/bin. To start a tcl testcase, an example command is "tclsh83 TestTcl.tcl"

·                 
·                  export PROJECTS=demo
·                  export OS_NAME=win32
·                  export BUILD_TYPE=retail
·                  export MSVCDIR=d:/MVStudio                (Only needed if on Windows)
·                  export VSCOMMONDIR=d:/MVStudio/Common     (Only needed if on Windows)
·                  export MSSDKDIR=d:/MicrosoftSDK           (Only needed if on Windows and building IA-64 code)
·                  make
  

·                  export PROJECTS=stax
·                  export JAVA_DRIVE=d
·                  export JAVA_LIBS=jvm
·                  export JAVA_VERSION=1.3
·                  export JAVA_BUILD_V11=0
·                  export JAVA_BUILD_V12=1
·                  export JAVA_V12_ROOT=/cygdrive/d/ibmjdk1.3
·                  export JAVA_V12_LIBDIRS=/cygdrive/d/ibmjdk1.3/lib
·                  export JAVA_V12_BIN_DIR=/usr/java_dev2/sh  (this is only required on AIX, when using Java 1.2+ to build)
·                  export XERCES_ROOT=d:/xerces-2_6_2
  make

Notes:

·                  export PROJECTS=event
·                  export JAVA_DRIVE=d
·                  export JAVA_LIBS=jvm
·                  export JAVA_VERSION=1.3
·                  export JAVA_BUILD_V11=0
·                  export JAVA_BUILD_V12=1
·                  export JAVA_V12_ROOT=/cygdrive/d/ibmjdk1.3
·                  export JAVA_V12_LIBDIRS=/cygdrive/d/ibmjdk1.3/lib
·                  export JAVA_V12_BIN_DIR=/usr/java_dev2/sh  (this is only required on AIX, when using Java 1.2+ to build)
  make
·                  export PROJECTS=cron
·                  export JAVA_DRIVE=d
·                  export JAVA_LIBS=jvm
·                  export JAVA_VERSION=1.3
·                  export JAVA_BUILD_V11=0
·                  export JAVA_BUILD_V12=1
·                  export JAVA_V12_ROOT=/cygdrive/d/ibmjdk1.3
·                  export JAVA_V12_LIBDIRS=/cygdrive/d/ibmjdk1.3/lib
·                  export JAVA_V12_BIN_DIR=/usr/java_dev2/sh  (this is only required on AIX, when using Java 1.2+ to build)
  make
·                  export PROJECTS=eventmanager
·                  export JAVA_DRIVE=d
·                  export JAVA_LIBS=jvm
·                  export JAVA_VERSION=1.3
·                  export JAVA_BUILD_V11=0
·                  export JAVA_BUILD_V12=1
·                  export JAVA_V12_ROOT=/cygdrive/d/ibmjdk1.3
·                  export JAVA_V12_LIBDIRS=/cygdrive/d/ibmjdk1.3/lib
·                  export JAVA_V12_BIN_DIR=/usr/java_dev2/sh  (this is only required on AIX, when using Java 1.2+ to build)
  make
·                  export PROJECTS=http
·                  export JAVA_DRIVE=d
·                  export JAVA_LIBS=jvm
·                  export JAVA_VERSION=1.3
·                  export JAVA_BUILD_V11=0
·                  export JAVA_BUILD_V12=1
·                  export JAVA_V12_ROOT=/cygdrive/d/sunjdk1.3
·                  export JAVA_V12_LIBDIRS=/cygdrive/d/sunjdk1.3/lib
·                  export JAVA_V12_BIN_DIR=/usr/java_dev2/sh  (this is only required on AIX, when using Java 1.2+ to build)
·                  export APACHE_XERCES_ROOT=c:/tools/xerces-2_6_2
·                  export COMMONS_LOGGING_ROOT=c:/tools/commons-logging-1.0.4
·                  export COMMONS_CODEC_ROOT=c:/tools/commons-codec-1.3
·                  export COMMONS_HTTPCLIENT_ROOT=c:/tools/commons-httpclient-3.0-rc2
·                  export NEKOHTML_ROOT=c:/tools/nekohtml-0.9.4
  make

Notes:

 

·                  export PROJECTS=http
·                  export JAVA_DRIVE=d
·                  export JAVA_LIBS=jvm
·                  export JAVA_VERSION=1.3
·                  export JAVA_BUILD_V11=0
·                  export JAVA_BUILD_V12=1
·                  export JAVA_V12_ROOT=/cygdrive/d/sunjdk1.3
·                  export JAVA_V12_LIBDIRS=/cygdrive/d/sunjdk1.3/lib
·                  export JAVA_V12_BIN_DIR=/usr/java_dev2/sh  (this is only required on AIX, when using Java 1.2+ to build)
·                  export COMMONS_CODEC_ROOT=c:/tools/commons-codec-1.3
·                  make

Notes:

 

·                 
·                  export PROJECTS=zip
·                  export ZLIB_SOURCEDIR=d:/zlib-1.2.1                

Notes:

On Linux, Solaris, and AIX, there is an additional file that is not built with STAF but must be included in the lib directory. The file should already reside on your build system, so simply copy this file to the lib directory before packaging the build for distribution. The files are:

Note that on Solaris, even if you build a retail version of STAF, the binary and library files will still contain symbolic information. After the build completes, you must run the "strip" command on every binary and library file before packaging the build for distribution.

Note that on AIX, you may receive the following error message when building STAF:

 
    xlC_r: 1501-230 Internal Compiler error; Please contact your Service Representative

If you receive this error message, ignore it (it is a compiler bug on AIX) and re-start the build (by typing "make" again). The second make should be successful.

To run using the version of STAF you just built, refer to the "Running STAF from the Built Executables" section.


Running STAF from the Built Executables

 

To run STAF from the executables you built, perform the following based on the operating system you are using:

Running on Unix

 

  1. If STAF is already running, shut it down:
STAF local SHUTDOWN SHUTDOWN
  1. Change the environment settings to use the STAF directories you just built. For example, on Linux, do:
3.            
4.           cd /build/rel/linux/staf/retail   (or /build/rel/linux/staf/debug)
5.           export STAFHome=$PWD
6.           export LD_LIBRARY_PATH=$STAFHome/lib:$STAFHome/lib/java12:$LD_LIBRARY_PATH
7.           export PATH=$STAFHome/bin:$PATH
export STAFCONVDIR=$STAFHome/codepage
  1. Set up the STAF config file that you want to use. If you already have one set up where STAF was installed, you can copy it. For example:
cp /usr/local/staf/bin/STAF.cfg bin
  1. Make sure you are now using version of STAF that you just build:
which STAFProc

Should show something like: /build/rel/linux/staf/retail/bin/STAFProc

  1. Start STAF:
STAFProc&

If you get error "mprotect reset:Bad address", then check the version (uname -a), and if 2.4, type the following and then restart STAF:

export LD_ASSUME_KERNEL=2.2.25

Running on Windows

 

You can run STAF from the executables you built from a Cygwin window or from a Windows command prompt.

Running in a Windows Command Prompt Window

  1. If STAF is already running, shut it down:
STAF local SHUTDOWN SHUTDOWN
  1. Change the environment settings to use the STAF retail (or debug) directories you just built. For example, if you built a retail version of STAF in directory D:\build, do:
3.            
4.           D:
5.           cd \build\rel\win32\staf\retail   (or \build\rel\win32\staf\debug)
6.           set STAFHome=D:\build\rel\win32\staf\retail
7.           set PATH=%STAFHome%\bin;%STAFHome%\lib;%STAFHome%\lib\java12;%PATH%
set STAFCONVDIR=%STAFHome%\codepage
  1. Set up the STAF config file that you want to use (in directory D:\build\rel\win32\staf\retail\bin). If you already have one set up where STAF was installed, you can copy it. For example:
cp C:\STAF\bin\STAF.cfg D:\build\rel\win32\staf\retail\bin
  1. Make sure you are now using version of STAF that you just build:
which STAFProc

Note: The "which" utility for Windows does not come with Windows. Should show something like: d:\build\rel\win32\staf\retail\bin/STAFProc.exe

  1. Start STAF:
STAFProc

Running in a Cygwin Window

  1. If STAF is already running, shut it down:
STAF local SHUTDOWN SHUTDOWN
  1. Change the environment settings to use the STAF retail (or debug) directories you just built. For example, if you built a retail version of STAF in directory D:\build, do:
3.            
4.           cd /cygdrive/d/build/rel/win32/staf/retail   (or /cygdrive/d/build/rel/win32/staf/debug)
5.           export STAFHome=$PWD
6.           export PATH=$STAFHome/bin:$STAFHome/lib:$STAFHome/lib/java12:$PATH
export STAFCONVDIR=d:/build/rel/win32/staf/retail/codepage
  1. Set up the STAF config file that you want to use (in directory /cygdrive/d/build/rel/win32/staf/retail/bin). If you already have one set up where STAF was installed, you can copy it. For example:
cp /cygdrive/c/STAF/bin/STAF.cfg /cygdrive/d/build/rel/win32/staf/retail/bin/STAF.cfg
  1. Make sure you are now using version of STAF that you just build:
type STAFProc

Should show something like:

STAFProc is /cygdrive/d/build/rel/win32/staf/retail/bin/STAFProc
  1. Start STAF:
STAFProc

Explaining How STAF is Packaged for Installation

STAF is packaged for installation using InstallShield MultiPlatform for most operating systems and/or as GNU zipped tar files for some of the Unix operating systems.

We use InstallShield MultiPlatform (ISMP) to provide a GUI interface to install STAF. In order to package STAF using ISMP, you need a license for InstallShield MultiPlatform. We provide both a ISMP jar file and an ISMP executable for each operating system supported by STAF, except for Irix and AIX 4.3.2 or earlier which are not supported by InstallShield MultiPlatform.

For example, for STAF 3.0.0 for Windows, files STAF300-setup-win32.jar and STAF300-setup-win32.exe are available for download from the STAF SourceForge website. If you already have Java 1.2 or later installed, you would probably download the ISMP jar file because it is smaller. If you do not already have Java installed, you would need to download the ISMP executable file (which includes a bundled JVM).

For Unix systems whose platforms are not supported by InstallShield MultiPlatform, such as Irix and AIX 4.3.2 or earlier, a GNU zipped tar file is provided. We also provide GNU zipped tar files for some of the other operating systems as well. Once the tar file is untarred, the STAFInst executable is used to install STAF.

For example, for STAF 3.0.0 for Linux, file STAF300-linux.tar.gz is available for download from the STAF SourceForge website.

Here are the steps to create a Tar File (these steps will use Linux as an example):


STAF Design Documentation

 

When adding a features to STAF, provide a design document in the docs/features directory in CVS. The feature design should be sent to the entire STAF development team to be reviewed before implementation.

The template to use when creating a feature design document is docs/features/Feature_nnnnnn.txt. The naming convention for a design document is Feature_nnnnnn.txt where you replace nnnnnn with the actual feature number.

The feature design template contains:

 
Feature ID  : nnnnnn
Response Due: mm/dd/yyyy
Title       : Add info on which interfaces are enabled
 
 
Description
-----------
 
 
 
Problem(s) Solved
-----------------
 
 
 
Related Features
----------------
 
 
 
External Changes
----------------
 
 
 
Internal Changes
----------------
 
 
 
Design Considerations
---------------------
 
 
 
Backward Compatibility Issues
-----------------------------
 
 
 

STAF Coding Conventions

 

STAF provides consistent and easily readable source code by adhering to the following conventions:

  1. Use unix (\n) end of line characters. Developers will be editing the source code on a variety of platforms with a variety of editors unix EOL are universal, windows EOL (\r\n) are not. STAF FS service provides a command to convert EOL characters. This can be used to convert the files you edit if your editor automatically uses native EOL and not unix EOL.
  2. Keep all lines at 80 or less. Some editors (EMACS) only show 80 chars wide.
  3. Don't use tab. The \t converts to a different number of spaces in different environments. The indent convention is 4 spaces. If you use tabs make sure they are converted to spaces.
  4. Open and close all blocks on their own line '{' and '}' should be alone on the lines where they occur. For example:
    try
    {
        connection->writeUInt(0);
    }

Not:

    try{ connection->writeUInt(0); }
  1. Horizontal white space is you friend.
    1. Separate arguments in function calls and declarations.
void rollBuffer(char * buffer, int bufferLen, int rollLen)
    1. Separate operators from the arguments.
int endIndx = bufferLen - rollLen;
    1. Separate comparators from the arguments.
if ((i == offset) || (last == -1))
  1. Vertical white space is your friend.
    1. Separate variable declarations.
    2. Separate clauses (if/while/for)
    3. Separate comments
    4. Separate logically independent sections of code
    5. Separate functions
  2. Comments make life easier for the next person. Accurate and informative comments allow other people to understand and modify your code. It allows for easy identification of the pertinent section of code that needs to be edited.
    1. Comment function declarations. Tell what the function does and the effect of all arguments
2.                  
3.                       /***********************************************************************/
4.                       /* STAFStringNumOfWords - Returns the number of words in a STAFString  */
5.                       /*                                                                     */
6.                       /* Accepts: (In)  A STAFString_t                                       */
7.                       /*          (Out) The number of words                                  */
8.                       /*          (Out) A pointer to an OS return code (may be NULL)         */
9.                       /*                                                                     */
10.                   /* Returns: kSTAFOk on success                                         */
11.                   /*          other on error                                             */
      /***********************************************************************/
    1. Comment blocks of code. Allow editors to easily identify which block is relevant to them
13.              
14.                   /* This clause establishes the new eol marker.
15.                      It causes the use of binary transfer if
16.                      the eol on both sides are the same and no codepage conversion
17.                      is to be done.
         This allows for a faster transfer.    */
    1. Comment confusing statements. Allow editors to understand what and why things are happening.
19.              
20.                 // offset = buffer length - null char - ending
21.                 //   index of eol
    offset = len - 1 - endBuffer;
  1. Use self documenting code. Highly descriptive variable names and indentation make code legible, making the need for comments lower.
  2. Naming convention
    1. Class names: Starts with "STAF" 1st letter of each word uppercase, no - or _, remaining letters lower-case.
class STAFHandleManager
    1. Variables: Lowercase, no - or _, 1st word all lower-case, subsequent words 1st letter uppercase
unsigned int maxConvertedLength;
    1. Function declarations: variable naming convention
void rollBuffer(char * buffer, int bufferLen, int rollLen)
    1. Enumerations: 1st letter k, variable naming convention
enum IndexRep { kChar = 0, kByte = 1 };
  1. Use simple code. The simpler the code the easier it is to maintain.

Reporting/Browsing/Fixing Bugs and Features

 

All bug reports and feature requests for STAF are kept on SourceForge.

When you begin work on a bug or feature, set the "Assigned to" field to your userid. Make the changes and test them. Update the history file to describe the new feature or bug fix you made, making sure you reference the request ID. Commit your changes into CVS, specifying the request ID in the commit message. Then update the bug/feature, adding comments on the changes you made, specify the Resolution and Status, and submit your changes.


Debugging on Linux

 

On Linux systems, you can use gdb to debug STAF, usually with more success using a debug version of STAF. Using gdb can be useful when a SIGSEGV problem is occurring.

Use gdb to debug STAF locally as follows:

1.           gdb STAFProc
2.           run
  1. Recreate the problem.

Use gdb to debug STAF remotely as follows:

  1. You need to establish two telnet sessions to the system to be debugged.
  2. From one telnet session, type:
3.           gdb STAFProc
run
  1. From the other telnet session, recreate the problem.

Various commands that you might need while using gdb are:


Appendix A: Important Links

 

Here are some commonly used links for STAF:


Appendix B: Common CVS Commands

 

Here are some of the common CVS commands that you will use. Use the 'man cvs' command to get more information about these CVS commands and others.

·                cvs update

Compares your directory tree with the tree in the CVS repository, by file, based on the directory that you are currently in. Execute this command from within your private source directory when you wish to update your copies of source files from changes that other developers have made to the source in the CVS repository. A -d option can be used to add any new directories. Each file that has changed will have one of the following codes which indicate how it was changed:

·                cvs add file...

Add a new file or directory to the CVS repository, pending a 'cvs commit' on the same file. Can only be done from within sources created by a previous 'cvs checkout' invocation. (Does not directory affect repository; changes working directory.)

Note that if you are checking in a binary file (such as a gif or pdf file), you must add the -kb option to the add command. This indicates that the file is a binary file. This is important so that when updates are made to the file, cvs will not attempt to "merge" the 2 versions of the binary file, which may cause bad things to happen.

·                cvs checkout

Make a working directory of source files for editing. (Creates or changes working directory.) This is a necessary preliminary for most cvs work: creates your private copy of the source. You can also use a path relative to the source respository here. You can work with this copy without interfering with others' work. At least one subdirectory level is always created.

·                cvs diff

Show differences between files in working directory and source repository, or between two revisions in source repository. (Does not change either repository or working directory.) Used to show the code changes. < in front of lines of code indicate that these lines have been removed and > in front of lines of code indicate that these lines have been added.

·                cvs commit -m "Enter a message here that describes the change including the bug/feature ID (#0123456)"

Apply to the source repository changes, additions, and deletions from your working directory. (Changes repository.) Use this command when you wish to 'publish' your changes to other developers, by incorporating them in the source repository.

·                cvs log

Display log information. (Does not change repository or working directory.)

·                cvs remove file...

Use this command (after erasing any files listed)

To list all of the CVS commands, type:

cvs help

To get help for a specific CVS command, for example update, type:

cvs --help update

Appendix C: New Developer Activities

 

When a new developer joins the STAF team, he/she must perform the following activities.

Join the Open Source STAF Development Project

 

  1. First read the IBM Open Source Guidelines at http://ltc.linux.ibm.com/open_source.
  2. Get an approval note from your manager saying that you can participate in the External Open Source STAF Project (and send David Bender a copy of this note).
  3. Register with SourceForge at:
  4. Let another STAF Developer know your userid so they can add you as a developer for the projects.
  5. Get with another STAF Developer to help you get your office machine set up to download the code and build it.

Subscribe to Mailing Lists and Monitor Newsgroups

 

External and internal STAF customers can send questions to the STAF SourceForge mailing lists and forums, and internal IBM STAF customers can post questions on the AWE Newsgroup. Part of the job responsibilities of a STAF Developer is to monitor the newsgroups, the SourceForge Mailing Lists, and the SourceForge Forums and respond to any questions or support requests. STAF developers get notes sent to them when anyone sends a note to one of the mailing lists or posts a message on a forum. However, STAF developers must monitor the Newsgroups to check for any new postings.

  1. Subscribe to the three STAF SourceForge mailing lists. Click on the links below to signup for a list, to post a message, to view archived messages, or to change your subscription. We try to respond to any questions within a couple of hours during normal business hours.
    • staf-news - is a moderated, low-traffic list which carries only periodic announcements of STAF releases and important updates.
    • staf-users - is the list for questions, suggestions, support, and general discussion of STAF.
    • staf-devel - is the list for STAF developers only.
  2. Add the following IBM STAF newsgroup to your browser. You can click on the link below to access the newsgroup:
  3. Subscribe to the SourceForge staf-dev-bugs mailing list. We use this private mailing list to mirror incoming bugs and feature requests for STAF.

Appendix D: Shutting Down STAF on Unix

 

Currently, there is a bug that occurs sometimes where STAF cannot be restarted after shutting it down via "STAF LOCAL SHUTDOWN SHUTDOWN". If this happens, perform the following:

killall -9 STAFProc
ps -ea | grep STAF
2.                 kill -9 

Replace with STAF's pid.

ps -ea | grep STAF

End Of Document

This is the end of the document.