The purpose of this document is to define rules and methods for software development and organization of 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 still some open points which will be defined and clarified later.
This is an up-to-date version of
KLOE Memo #40.
If you are already familiar with this document
look out for the chapters marked with
which have
been updated in the meantime. Mainly there is now a
general purpose tool named
packman
for all necessary management task which is described
in detail on a seperate page.
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 (for example the "o" packages are 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 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. Also for cross-development envrionments like HP-RT one must be able to define a non default flavor.
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 etc.
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 KLOE Memo #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>.h.
A useful idea is to write embedded documentation into
the source files which then can be extract with a
HTML-doc-generator program allowing to give quick access
to the library routines via index and hyperlinks. Again
the "o" packages version 2 could serve as an example:
click
here
if you want to have a look. With some modification it
could be used for KLOE as well.
Skeleton and example files for standard Ansi-C (*.c), header (*.h),
make and requirement files etc. are now available and collected in
package skel. They are described in the
Getting-Started page.
There is a convenient method to produce multi-platform code with only one set of source files. It 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 defined 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 the flavor dependent variables. This is described later.
A similar scheme can also be used for UIMX code production.
The KLOE Online packages will be housed in a directory tree under:
$KLOE/onl/<package>
On the LNF KLOE UNIX cluster the environment name $KLOE is setup at login time and pointed at the time of writing to /kloe/soft. 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/onl tree.
Each package is subdivided into different versions. 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. This will allow to setup a package without explicitely specifying the version. Note: The management of the default version is under the responsability of package maintainer. They will not be define automaticaly.
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 HP-UX.csh) in the mgr directory.
The file setup.csh defines the following default environment variables:
<package>VERSION <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:
For examples to setup the KLOE offline environment. Note: these lines are preserved at package reconfiguration.#--- User area ----------------------------------- #--- End of user area ----------------------------
The configuration scheme uses absolute pathnames! This needs
package reconfiguration after each move of the directory tree.
If you have setup the package manage the alias packman is defined. packman should be used in the following way:
% cd <package>/<version>/mgr % packman -f <flavor> -s
If you omit -f <flavor> the default flavor will be used as returned by uname.
At the moment only the tcsh version 6.03
or greater is fully supported including the
packman utility.
All the mamangent commands could also be done
'manually'
without packman on a standard c-shell csh.
Configuration and setup files for other shells like sh, ksh or zsh could be implemented quickly on request and if needed.
To setup the main package tree and some management commands you should put into your c-shell startup file .tcshrc or .cshrc.
[ setenv MANAGEFLAVOR LynxOS ] source $KLOE/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 defined at configuration time. If necessary replace $KLOE with your appropriate online software pathname. The definition of MANAGEFLAVOR is only needed, if you do not want to use the default flavor retrieved by uname. You can also (re)define and fix the flavor for the existing session with the command:
which defines the environment variable MANAGEFLAVOR as well.% packman -f <flavor>
Then the following commands can be used to setup the package:
which makes:% packman -s <package> % packman -s <package> <version>
Note: If you omit the version, a default version must be defined via symbolic link.% source <package>/<version>/mgr/setup.csh
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 tags 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.
This copies and installs the specified package in your main software tree <mainroot>. The package will be stored as compressed tar file in a central directory $KLOE/ftp/dist/online with the name <package>.<version>.tar.Z. The responsible developers should place an appropriate distribution file with the commands:% cd <mainroot> % packimport.csh <package> <version>
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.% make tar % packman -e
Another command packman -u could be introduced to allow updates for one or all packages (not yet existing).
The stored packages could also be regarded as a backup.
A more practical description about storing and distributing packages can be reteived from the Getting-Started page.
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.
As already mentioned previously a HTML-doc-generator extracting embedded documentation from the source files could be a powerful tool for program and library routine documentation.
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 ~/onl/<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 Online 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 Online 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.
Please use the methods and rules defined in this document and contact me if there is something not defined, unclear or not working.
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.