Developers guide - Index

On this page:

Intended audience
Introduction
Environment setup
Directory structure
How to set up a new application directory
Testing and debugging
Building a release
MTK related files

Intended audience

This document is intended for developers of the pfspd toolset. It takes only a few minutes to read it. All developers are expected to adhere to the guidelines described in this document to assure a similar development infrastructure and a similar way of working in the pfspd project.

It is assumed that the reader is familiar with the project philosophy. A short, generic cvs introduction is described in the cvs guideline.

Introduction

This document describes which infrastructure is assumed, how to setup an account at the sourceforge server, how to setup a working environment, how to define a new utility. In addition, the release procedure is described.

Descriptions in this document in italics font refer to information that is site specific. Usually, the Nat. Lab. (the Philips research site in Eindhoven, Netherlands) is taken as an example.

Environment setup

On all platforms, the gcc compiler is used. We recommend release 3.2.3 for its compatibility with the purify test and debug tools (see this page here). Nov. 2009, we changed to version 4.2.0, but at that time, purify were not available to me (BR) for testing. You should have installed cvs, perl and ssh. For release building, gtar (gnu tar) is required. We also use gmake (gnu make), not the standard unix make. In addition to these, we use the standard unix commands like: sed, cksum, find etc.
On our systems (at the NatLab) these are installed by:
```
    cadenv cvs
    cadenv perl
    cadenv -r3.80 gmake
    cadenv -r4.2.0 gcc
    
```
The ssh and gtar commands are by default installed at the Nat. Lab. The current versions are (feb. 2005):

cvs: 1.11.17

perl: 5.6.1

ssh: OpenSSH_2.3.0p1

gtar: 1.13.25

gmake: 3.80
All development will take place in your home directory in a directory under ~/opensource/pfspd. You should create this directory.
```
    mkdir -p ~/opensource/pfspd
    
```
To make sure cvs creates files with readonly access, add the following to your ~/.profile file (if you use ksh or bash):
```
    CVSREAD=
    CVS_RSH=ssh
    export CVSREAD CVS_RSH
    
```
Or make to following change to your .cshrc if you are using csh/tcsh:
```
    setenv CVSREAD ""
    setenv CVS_RSH ssh
    
```
Make sure to activate these settings in your current shell. With ksh or bash, use ". ~/.profile"; with csh or tsh use "source .cshrc".
Register yourself as user at the sourceforge system. See user account registration. If your sourceforge username matches your local username, there is no need to specify the username in subsequent commands.
Setup a private/public key pair to access the sourceforge server without password identification. Go to your personal Account Options page. Then follow the unstructions in section "Host Access Information". Test the result with (if the key accepted, then the following command is executed without entering a password):
```
    ssh -t <username>,pfspd@shell.sourceforge.net create
    
```
Getting a development tree on the local system. Usually, one does not need all modules. We have setup this system in such a way, that a cvs "module" equals a single library or utility. In the example, we show how to get mtk. This is required by any developer.
```
    cd ~/opensource/pfspd
    cvs -d <username>@pfspd.cvs.sourceforge.net:/cvsroot/pfspd checkout mtk
    
```
This will create a local development directory ~/opensource/pfspd/mtk. All the files will be created with readonly acces (due to CVSREAD) so you can not make unwanted modifications. You are in business.
To checkout everything from the repository, use ".".

Directory structure

All directory names shall not contain uppercase characters.

All applications reside in their own separate directory in the cvs repository on the sourceforge server.

Examples of applications are:

    Application name          : directory name
    ------------------------------------------
    make tool kit             : mtk
    pfspd file access library : cpfspd
    pfspd viewer              : pv
    pfspd player              : pp

How to set up a new application directory

Before starting a new application, contact the development team to discuss and agree on the application name, purpose and scope. For this description, we will use "newtool" as example.

Make its base directory in ~/innersource/pfspd:

    cd ~/innersource/pfspd
    mkdir newtool

Add the new directory to the cvs repository:
```
    cvs add newtool
    
```
Make a source directory (src) in the new directory, and add it to the cvs repository:
```
    cd newtool
    mkdir src
    cvs add src
    
```
Initial project setup, using files from "make tool kit" (mtk).
- Copy the following files from the most recent mtk release "src" directory to the newtool/src directory: Makefile, Make.mtk. Only Makefile needs to be adapted to your needs. Make sure your application name in Makefile matches newtool (the invoke script relies on this convention).
- If you are developing a program (not a library), then also copy the invoke script from the most recent mtk release prog.sh into your module and rename it to ~innersouce/pfspd/newtool/newtool.sh.
- If the application is based on other libraries (like cpfspd), it needs to know where they are installed. Since this information is site specific, it is not in the makefiles, nor in the CVS repository. As an example, script setup.sh can be used. This generates a file Make.env that contains the path names, based on site specific definitions in files Make.env.[site]. Mtk shows examples of environment definitions for the TriMedia compiler. The skeleton application shows how this is combined with cpfspd library usage.
- Also copy the Readme.txt file from the most recent mtk release and use it as a template for your application.
- Copy the parse_options module (.c and .h files) from the most recent mtk release to your "src" directory. This module does not need modifications.
- File prog.c can serve as a template for your own newtool.c file. Alternatively, you can use the main program of one of the pfspd utilities as starting point.

Add the files to the repository with subsequent cvs add commands:

    cvs add Readme.txt newtool.sh
    cvs add src/Make*
    cvs add src/parse_options.*
    cvs add src/newtool.*

Start development by modifying newtool.c and adding your own files.

Testing and debugging

MTK supports several features for testing and debugging. First of all, the command "gmake debug" compiles the application with debug information. Furthermore the Rational tools purify, pureconverage and quantify are supported by MTK using build target "purify", "purecov" and "quantify" respectively. These tools enable detection of run time memory corruption or memory leaks, test coverage and performance analysis.

As the Rational tools manipulate object code, the version relation between compilers and tools is quite critical. We have used the Rational tools only on HP systems. Versions are shown in the table below. With the latest release, we only tested purify. The tools purecov and quantify suffered from licence problems.

Tool Version

gcc/g++ 3.2.3

purify hp.2003a.06.13-Fix_0172

purecov hp.2003a.06.13-Fix_0172

quantify hp.2003a.06.13-Fix_0172

Tool	Version
gcc/g++	3.2.3
purify	hp.2003a.06.13-Fix_0172
purecov	hp.2003a.06.13-Fix_0172
quantify	hp.2003a.06.13-Fix_0172

Building a release

It is strongly recommended not to build a release on the cygwin platform. During release build, the access rights of the whole directory tree are set according to the application requirements. There is some subtile unwanted behaviour with access rights in the cygwin environment. This is especially true when the directory tree is on a samba mounted unix network disk. Also when unpacking the generated tar file, the access rights are not restored properly. And then, the unpacking on a unix machine differs from unpacking on cygwin. Apart from this, cygwin has it's own understanding of the unix "x" access bit. In spite of all these objections, release build on cygwin is supported (only after a confirmation check in the makefile) for situations where no unix machine is readily available.

During a release the cvs tree will be tagged with that version. Because dots are not allowed in cvs tag name, we use a dash '-' instead.

On the Nat. Lab, releases of an application reside in directory /natlab/softtv/appls/utils/pv/release.

To create a release follow the procedure described here. This example builds release version "1.0.0" of the tool pv.

Stop all development. Use "cvs editors" to check if anybody is still editing a file.
Your release name is: "pv-1.0.0". The tag name is "rel_1-0-0".
Update Readme.txt (release version/date, changes wrt previous version, etc.).
Update VERSION in Makefile or Make.set file.
Mtk note: also update the version number in Make.mtk.
Cpfspd note: also update the version number the Doxyfile file.
Build all and test (yes, again ;-).
Go to the root dir of the application: ~/opensource/pfspd/pv. Tag the current sources (mind the replacement of "." by "-"):
```
    cvs tag rel_1-0-0 Readme.txt pv.sh setup.sh Make.env.* src
    
```
Maybe there are more directories and/or files, e.g. doc, test, etc.

Export all source files tagged with the release tag into an independent directory. If the release directory does not yet exist, create it first.

    cd /natlab/softtv/appls/utils/pv/release
    cvs -d <username>@pfspd.cvs.sourceforge.net:/cvsroot/pfspd/ export -r rel_1-0-0 -d pv-1.0.0 pv

Run the setup.sh script in the exported release directory.
Build on all platforms that should be supported.
Build the release package (tar-file plus readme) by:
```
    gmake release
    
```
For the Nat. Lab. infrastructure: update the make_links.sh script in /natlab/softtv/appls/utils. Also update the "latest" link in /natlab/softtv/appls/utils/<tool>/release.
Prepare for the next release. Update Readme.txt and VERSION in Makefile. Use new version number extended with -indev. E.g. "1.0.1-indev". This way an executable can be indentified as being an official release and is never confused with a development version.
Inform all developers to update there working directory. Each of them should issue:
```
    cd ~/opensource/pfspd/pts
    cvs update
    
```
Start working on the next release.
Install the release on the sourceforge server and inform users.

MTK related files

./setup.sh            # script to creat a Make.env file with site specific
                      # definitions of the location of tools and libraries
                      # in the file system
./Make.env            # generated by setup_natlab.sh script; NOT in cvs repository
./Make.env.natlab     # input to setup.sh for the Nat. Lab. environment
./Make.env.svl        # input to setup.sh for the Sunnyvale environment
src/Makefile          # application specific definitions; includes Make.mtk
src/Make.mtk          # copy from mtk.
src/parse_options.c   # copy from mtk.
src/parse_options.h   # copy from mtk.

File Make.mtk shall not be edited. ./Make.env shall be generated by ./setup.sh and does not need to be edited when you are situated at the NatLab.

Note that mtk contains a simple application example, mainly illustrating standard command option handling. This does not show all functionality to keep it straightforward and clear.

Authors: Bram Riemens Robert Jan Schutten Martijn van Balen

Copyright (c) KONINKLIJKE PHILIPS ELECTRONICS N.V. 2000-2006
Philips Research Laboratories, Eindhoven, The Netherlands
CVS id: $Id: developers.html,v 1.8 2009/11/19 15:28:12 riemens Exp $

This page is hosted by