The purpose of this document is to define some first rules and methods for software development and organization for the KLOE online and data acquisition group. There is strong need for such rules to allow easy interconnection, access and distribution of the various parts of the DAQ and online software.
The rules and methods described here should be regarded as a
starting point for discussion. For this reason they are likely to
change with time reflecting the progress, experience and result of
ongoing discussions. There are also some open points which will
be defined and clarified later.
An up-to-date document is maintained and accessabile on www:
http://www.lnf.infn.it//kloe/private/online/software/online-software-rules.html
The KLOE DAQ and online environment is a distributed heterogeneous UNIX environment. Various UNIX operating systems, also real-time, mainly HP-UX, OSF/1, LynxOS, HP-RT are in use on different hardware platforms including VME processor boards. The main programming language is C but Fortran or other languages could be fully included. The restriction to UNIX means a real simplification and allows to use common management tools for package organization, configuration and distribution.
The software organization and tools presented here try to follow the following main guidelines:
The methods used at LAL/Orsay (the OnX display package comes from there) fulfil most of the above requirements. With some additions and modifications they proved to be well suited for our purpose.
Here briefly some clarification about names: A software package is a collection of code with a well defined name and purpose. Another common name for package is product. A platform or flavor defines a name for the hardware and operating system type under which the package runs. The name is usually derived with the UNIX command uname -s but it could also be used in a more general context distinguishing different versions of the OS like LYNXOS2.1 for LynxOS or special hardware platforms.
This also defines the basic skills every developer need to produce
and maintain code for the KLOE ONLINE group.
The main programming language for KLOE DAQ is C. Whenever possible Ansi-C should be used including features like function prototyping, const and volatile data types.
On all platforms the native Ansi-C compiler should be used to guarantee well optimize code which seems to be crucial especially for OSF/1. On LynxOS systems the gcc compiler is the default Ansi-C compiler.
Unfortunately there is no common debugger environment for all platforms if we choose the native Ansi-C compilers. But I think that gcc together with gdb is not the better solution first because of the optimization problem and second gdb is also not well adapted and equipped on all platforms, for example there is no multi-thread or process support on LynxOS.
C++ and in more general object-oriented (OO) programming has some distinct advantage about the usual procedural and modular style especially when the OO design is well done. But this needs time and experience. Big parts of the HEP community are moving in this direction and we should adopt it whenever it is appropriate. For sure it is the natural choice for the graphic software based on Motif. The UIMX Motif toolkit supports OO style programming also implemented with Ansi-C.
Whenever Fortran interface routines for the KLOE analysis software have to be written they should confirm with the rules and methods defined for the KLOE offline group as described in memo No.4. This means the use of ups for package setup and expand for conditional compilation. A typical example is the event display
For a package a short name should be used with, lets say, not more than 4 letters like VME or XRec. For library and interface routines the routine names should be prefixed with this package name. For example: VMEmap, VMEread etc. Sure, this restricts the freedom of choosing any name but on the other hand it's clear that it make the source code much more readable and it avoids name conflicts.
The source code files and routines should be documented in the usual way defining author, creation and modification date, purpose and so on. If necessary more strict rules could be released in the near future. The CVS version management tool allows to maintain most of this requirements.
For Ansi-C library routines a proper header file including the necessary prototype definitions for the library functions should be supplied with the name <package>_protos.h.
A useful idea is to write embedded html-style documentation into the source file and extract them with a simple UNIX script (which does not yet exist). Here is a simple example:
/*<HTML>
uint VMEmap(int* id, uint addr, int size, int am)
<DL>
<DT>id:
<DD>VME map identifier
<DT>addr:
<DD>VME address to be mapped
<DT>size:
<DD>Size of mapped VME address space
<DT>am:
<DD>VME address modifier
</DL>
</HTML>*/
Skeleton (or template) files for standard Ansi-C (*.c), header
(*.h), make and requirement file will be available soon !
There is a rather simple method to produce multi-platform code with only one set of source files. This could be achieved by creating all flavor dependent files like binaries, object files or libraries in a flavor specific directory like HP-UX, OSF1 or LynxOS. The makefile has to be written in an appropriate way placing all target files in a separate directory. This means a bit more to write but for the big benefit of having only one unique set of source files for all flavors.
The following example makefile in the src directory illustrates how this could be implemented:
# Gnu Makefile for package Exa
#
# Package name, here Exa(mple)
package=Exa
#
# Package environment definitions
#
version=${EXAVERSION}
flavor =${EXAFLAVOR}
src=${EXASRC}/
doc=${EXADOC}/
bin=${EXABIN}/
#
# EXACC is at package setup. $@ will be
# replaced with the target name.
#
ccomp = $(EXACC) -c -o $@ -D$(EXAFLAVOR)
clink = $(EXACC) -o $@
#
CFLAGS = -O
#
OBJS = $(bin)main $(bin)sub1.o $(bin)sub2.o
#
all : $(objs)
#
$(bin)sub1.o : sub1.c sub1.h
$(ccomp) sub1.c
#
$(bin)sub1.o : sub2.c sub2.h
$(ccomp) sub2.c
#
$(bin)main : $(OBJS)
$(clink) $(CFLAGS) $(OBJS) -D$(EXAFLAVOR)
#
All flavor dependent code should then be implemented with C preprocessor directives. As you can see from the example the flavor type is passed to the compile step using the variable EXAFLAVOR. The flavor dependent variables are defined at package setup time. A file with the name requirements should be used to define all flavor dependent variables. This is described later.
A similar scheme can also be used for UIMX code production.
The KLOE DAQ packages will be housed in a directory tree under:
$KLOE/daq/<package>
On the LNF KLOE UNIX cluster the environment name $KLOE is setup at login time and pointed at the time of writing to /u/kloe. On other systems a similar structure and name should be established. Each package has a name, a version and one or more flavors resulting in the following minimal directory tree shown on the left. The environment names defined at package setup for these directories are listed on the right.
<package>/<version> <package>ROOT
<package>/<version>/mgr <package>MGR
<package>/<version>/src <package>SRC
<package>/<version>/doc <package>DOC
<package>/<version>/<flavor(s)> <package>BIN
The minimal set of areas needed usually are the management, the source, the documentation and the binary directory. But there could be other useful directories for test etc.
<package>/<version>/test
<package>/<version>/uimx
Here is an example for the package XRec (XReceiver):
XRec/v1/ XRECROOT
XRec/v1/mgr XRECMGR
XRec/v1/src XRECSRC
XRec/v1/doc XRECDOC
XRec/v1/HP-UX XRECBIN
XRec/v1/OSF1 ...
You will find other examples in the $KLOE/daq tree when they become available.
Each package is subdivided into different version. Version names should usually be something like v1, v2 etc. but also other nameing schemes like old, pro and new are possible and allowed. There could also be implemented more than one depth of version level (with releases) like v2r1 etc. More strict version management rules might be released at a later stage if necessary.
There should always be a symbolic link defined with the name default pointing to the default (or production) version of the package.
Each version of the package must be completely autonomous which means that each version corresponds to a complete set of files needed to describe, implement and manage the package. This also implies that one version should not use parts of another one.
The package configuration is done with the script packconf.csh. It creates the package directory tree and the flavor independent and dependent setup files namely setup.csh and <flavor>.csh (for example setup.HP-UX.csh ) in the mgr directory.
The file setup.csh defines the following default environment variables:
<package>VERSION
<package>FLAVOR
<package>ROOT
<package>MGR
<package>SRC
<package>BIN
To create <flavor>.csh the file requirement is consulted. This file allows flavor dependent definitions to be used later in the makefile for package building. The following example illustrates the usage and syntax:
# requirement file for package XRec
use database
use bufflib
set XRECCC "cc" \
HP-UX "cc -Aa -D_HPUX_SOURCE" \
LYNXOS "gcc"
alias start_xrec "source $XRECSRC/xrec.csh"
This file allows to define and setup other packages (dependencies), setting flavor dependent environment variables (here XRECCC) and aliases. If necessary additional definitions could be inserted in setup.csh or <flavor> .csh between the lines:
#--- User area -----------------------------------
#--- End of user area ----------------------------
For examples to setup the KLOE offline environment. This lines are
preserved at package reconfiguration.
The configuration utility uses absolute pathnames! This needs
package reconfiguration after each move of the directory tree.
If you have setup the package manage the alias packconf is defined. packconf should be used in the following way:
% cd <package>/<version>/mgr
% packconf <flavor>
If you omit <flavor> the default flavor will be used as returned by uname -s.
At the moment only the c-shell (csh) is supported but configuration and setup files for other shells like sh, ksh or zsh could be implemented quickly if needed.
To setup the main package tree and some management commands you should put into your login file .cshrc
source <mainroot>/manage/v1/mgr/setup.csh
which makes the setup for the package manage. Note that this does not need any environment variables defined for the main tree because absolute pathnames are used.
Then the command packuse could be used in the following way to setup the package:
% packuse <package>
% packuse <package> <version>
% packuse <package> <version> <flavor>
packuse executes mainly the following command:
% source <package>/<version>/mgr/setup.csh
You can (re)define and fix the flavor for the existing session if you do not use the default system name with the command:
% packuse manage default <flavor>
To build the package standard UNIX makefiles should be used. A makefile must exist in mgr to completely build the package. Other makefiles could exist for example in src which should be written in a way that all flavor dependent target files (*.o, binaries etc.) are prefixed with the name of the bin directory (< package>BIN) as already described above.
For portability and convenience reasons the GNU Make utility is strongly recommended which is easily available for (more or less) all UNIX platforms. And real time OS like LynxOS have GNU Make as default make utility anyhow. Furthermore GNU Make offers some other powerful functions like static pattern rules and conditional parts of makefiles which could make the writing of makefiles much more simpler. And there is good documentation available as well.
If the makefile is simple enough it will also work with other make utilities but the requirement is that it must work at least with GNU Make.
For global package building a makefile must exist as:
<package>/<version>/mgr/Makefile
This makefile should have other targets like:
Other makefiles might exist in other directories like src but should then be called from the global makefile file to build all necessary parts of the package.
% cd <mainroot>
% packimport <package> <version>/
This copies and installs the specified package in your main software
tree < mainroot>. This is similar to the procedure
used at LAL. The package will be stored as compressed tar file in a
central directory $KLOE/daq/dist with the name <
package >.<version> .tar.Z. The responsible
developers should place an appropriate distribution file with a
make tar command. This tar file must
not include flavor dependent parts of the package e.g. the
flavor directories which can be easily recreated on the
destination system. Finally the compressed tar files can be put in
place via anonymous ftp if the package was developed
outside LNF.
Another script packupdate could be written to allow updates for one or all packages.
The stored packages could also be regarded as a backup.There are still some pieces missing especially anonymous ftp is not setup so far. When this is done a more detailed description about storing and distributing packages will follow here.
I propose to produce documents in HTML. HTML is a simple and easy to learn markup language e.g. much easier than (La)TeX. HTML is, together with an appropriate browser, a powerful tool for documentation especially because of its ability to link regions of text to other documents.
Also the CERN computing devision is now officially following this line. We should use the CERN recommended browsers and HTML standard. This is at the moment NCSA Mosaic and HTML2 and later HTML3 when this standard is finalized.
Furthermore a (nice) and up-to-date WWW homepage for the KLOE ONLINE group should be created and maintained informing about new software, updates etc.
Do not use the extensions to the HTML2 standard added and
implemented by the
netscape
group. Please click
here
if you want to know why.
This is a brief proposal how code should be developed by the software developers of the ONLINE group. In general there must be distinguished between code development on the LNF UNIX cluster and on other systems and sites.
The LNF UNIX cluster should be regarded as the main development area including all software packages on disk for code development, storage and distribution. This main DAQ software tree is $KLOE/daq.
Each user should have an account on the LNF UNIX cluster. In the very first phase (version v0) the user should develop his software on his own account. If disk space is a problem some other place could be arranged. Therefore the user should have a similar tree ~/daq/ < package>/< version> on his account and a symbolic link from the main tree should point to the package.
After the software is stable, complete and ready for distribution the package should be copied to the main tree as version v1. To do so the package should be installed and build from the compressed tar file to check that package building works correctly. This could also be done by the responsible person of the library.
The same procedure could be applied for new versions and releases as well. So the main development is always done on the developers account. Sure, this makes only sense if there is mainly one single developer for a package but I think this is true in most cases.
The KLOE DAQ software will be stored under the group name kloedaq so that every user belonging to that group will have access to the files on the main package tree.
Code will also be used and developed outside the LNF UNIX cluster
e.g. on systems which do not have NFS access to the DAQ software
disk. To deal with this case similar package trees should be
setup on these systems.
Packages developed in this way should be copied to the main
package tree when they are ready for distribution with the
procedure described previously.
If more than one developer is working on the same package things
are getting more complicated especially when they develop on
different systems and sites. For the moment, this should be
managed with intensive communication between the involved
developers.
CVS
could really help to handle and maintain this multi-developer case
well and we should adopt it as soon as possible.
There is still not everything ready. The tools are almost ready to be used and have already been successfully tested for packages like buffman, database and xrec .
We just got a new HP workstation and disk exclusively dedicated to the DAQ group. The disk will be used to develop, store and distribute the software packages. But this system must be setup properly first (disks, users, accounts, compilers, Motif) and so on, which will need some more time. Here are briefly some open points which will be resolved as the DAQ software especially for the DAQ test stand develops with time. Please contact me if there is something you need now to start or continue your work.
The next big step is to use CVS for source code and version management. So everybody should try to get in touch with this useful tool as soon as possible.
It is likely that there are other improvements and changes as a result of experience and discussion.