STAF V2 Developer's Guide

Software Testing Automation Framework (STAF) V2 Developer's Guide

January 30, 2006

V 2.6.9

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 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. STAF252-src.tar.gz) from http://staf.sourceforge.net/getcurrent.php.

    2. Uncompress the tar file: 
      gunzip STAF252-src.tar.gz
    3. Untar the file: 
      tar -xvf STAF252-src.tar
      Note: The STAF230-src.tar.gz file was tarred up wrong in that it didn't include the src/staf directory structure. So, if you use this file, create a src/staf directory structure and untar the file into it.

    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. 

      2. cd /cygdrive/d
        Where d is the drive where you want to put STAF code. 

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

      4. cd build

    2. If on Unix:

      1. Log on as root 

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

      3. cd build
    3. export CVS_RSH=ssh
      This must be done once for each window.

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

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

    6. 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.4.2 (IBM or Sun), but also support other versions of Java.

    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)
                            and GenWl (Generic Workload Processor)
/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.

    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.

    4. Set the appropriate environment variables:

    5. 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:

    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
    2. Change the environment settings to use the STAF directories you just built. For example, on Linux, do: 
      cd /build/rel/linux/staf/retail   (or /build/rel/linux/staf/debug)
export STAFHome=$PWD
export LD_LIBRARY_PATH=$STAFHome/lib:$STAFHome/lib/java12:$LD_LIBRARY_PATH
export PATH=$STAFHome/bin:$PATH
export STAFCONVDIR=$STAFHome/codepage
    3. 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
    4. 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

    5. 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
    2. 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: 
      D:
cd \build\rel\win32\staf\retail   (or \build\rel\win32\staf\debug)
set STAFHome=D:\build\rel\win32\staf\retail
set PATH=%STAFHome%\bin;%STAFHome%\lib;%STAFHome%\lib\java12;%PATH%
set STAFCONVDIR=%STAFHome%\codepage
    3. 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
    4. 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

    5. Start STAF: 
      STAFProc

    Running in a Cygwin Window

    1. If STAF is already running, shut it down: 
      STAF local SHUTDOWN SHUTDOWN
    2. 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: 
      cd /cygdrive/d/build/rel/win32/staf/retail   (or /cygdrive/d/build/rel/win32/staf/debug)
export STAFHome=$PWD
export PATH=$STAFHome/bin:$STAFHome/lib:$STAFHome/lib/java12:$PATH
export STAFCONVDIR=d:/build/rel/win32/staf/retail/codepage
    3. 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
    4. 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
    5. 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.

    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); }
    5. Horizontal white space is you friend.

      1. Separate arguments in function calls and declarations.
        void rollBuffer(char * buffer, int bufferLen, int rollLen)
      2. Separate operators from the arguments.
        int endIndx = bufferLen - rollLen;
      3. Separate comparators from the arguments.
        if ((i == offset) || (last == -1))

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

    7. 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
              /***********************************************************************/
      /* STAFStringNumOfWords - Returns the number of words in a STAFString  */
      /*                                                                     */
      /* Accepts: (In)  A STAFString_t                                       */
      /*          (Out) The number of words                                  */
      /*          (Out) A pointer to an OS return code (may be NULL)         */
      /*                                                                     */
      /* Returns: kSTAFOk on success                                         */
      /*          other on error                                             */
      /***********************************************************************/
      2. Comment blocks of code. Allow editors to easily identify which block is relevant to them 
              /* This clause establishes the new eol marker.
         It causes the use of binary transfer if 
         the eol on both sides are the same and no codepage conversion 
         is to be done.
         This allows for a faster transfer.    */
      3. Comment confusing statements. Allow editors to understand what and why things are happening.
            // offset = buffer length - null char - ending 
    //   index of eol
    offset = len - 1 - endBuffer;

    8. Use self documenting code. Highly descriptive variable names and indentation make code legible, making the need for comments lower.

    9. Naming convention

      1. Class names: Starts with "STAF" 1st letter of each word uppercase, no - or _, remaining letters lower-case. 
        class STAFHandleManager
      2. Variables: Lowercase, no - or _, 1st word all lower-case, subsequent words 1st letter uppercase 
        unsigned int maxConvertedLength;
      3. Function declarations: variable naming convention 
        void rollBuffer(char * buffer, int bufferLen, int rollLen)
      4. Enumerations: 1st letter k, variable naming convention 
        enum IndexRep { kChar = 0, kByte = 1 };

    10. 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
    3. 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: 
      gdb STAFProc
run
    3. 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.

    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.

    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:

    End Of Document

    This is the end of the document.