This page contains some information on how to access and contribute to the pep-n project software
This is just a temporary solution, hopefully after the spring workshop things will be organized in a better way
The code management is based on the BaBar code management, but does not use SRT or similar tools (at least for the moment)
The organization of the code is intended to be by packages, that are self contained software units needed to build programs.
The source code is maintained using the Concurrent Versions System, CVS. This is a widely used public domain tool for maintaining software. CVS allows several people to modify software, keeping track of the modifications and allowing specific copies to be tagged (for those interested, CVS is a front end for the Revision Control System, RCS, common for many years on UNIX systems). These tagged versions can then easily be accessed at any later time, even though many changes may have been implemented since the original tag. The released package versions referred to above correspond to CVS tags of the appropriate files.
CVS can maintain more than simple files, including hierarchical collections of directories consisting of revision controlled files. These collections of directories and files, called modules, are maintained as a coherent whole. Thus the files and subdirectories of a package can be maintained as a whole, with new versions tagged as required.
CVS keeps a single copy of the master sources. This copy is called the source repository; it contains all the information to permit extracting previous software releases at any time based on either a symbolic revision tag, or a date in the past.
This repository is kept under AFS and is in /afs/infn.it/pd/project/pepn/repo.
As most of us are working with BaBar, to avoid conflicts, the bersion of CVS that must be used to access the software is the one modified by BaBar and available for several platforms, the source code and the RPM (only for Linux RH6.2) can be found in /afs/infn.it/pd/project/pepn/software.
For more information on CVS look at the info (prompt>
info cvs), the manual (here is the postscript
or HTML
version).
Software developers must learn how the system works in order
to contribute to code development.
The following is a very brief introduction to CVS. Consult the complete documentation (see above) for further details.
The basic idea is that any file or collection of files which is being developed by more that one person is maintained by CVS in a central repository. The basic unit of files/directories handled by CVS is called a module. For us a module equates to a package and the latter term is preferred.
The CVS repository is referenced via an environment variable, $CVSROOT, which must be set before operating with CVS. It can be set in .login or in .cshrc, BaBar users must not confuse the two repositories to avoid corrupting them.
In practice this means that CVS keeps special copies of the files (version files, denoted by names like simple.c,v) which contain enough information to reconstruct the current and any previous state of the file or collection of files. These files must not be edited directly by users. When required (for modification or simply for viewing), a user gets his/her own personal copy of a CVS module by checking out a copy:
cvs co <package name>
This will create a subdirectory (called <package name>) in the users current directory containing all the source files and subdirectories which make up the specified package.
The user is free to edit this personal copy of the package as required. If the user wishes to incorporate any modifications into the main repository then they can be checked in to the repository:
cvs ci <package name>
This command should be issued from the same directory as the original cvs co. The users changes will then be incorporated into the master files. Note if more than one file has been modified then all of the modifications will be incorporated.
It is often useful to check what you have changed before committing your code. You can do this with the command
cvs diff <package name>
This command will then list all the differences between your code and the version that you originally checked out. (This is exactly the list of changes that cvs will assume that you then want to commit). If only changes to specific files should be checked in then individual files can be checked in as follows:
cvs ci <package name>/<file name>
cvs ci <file name>
The first form should be issued from the same directory as the original cvs co command, the second from the module subdirectory itself. It is possible that in between checking out a file and committing a new version that someone else checked in some changes, CVS does not lock files which are checked out. CVS only provides the tools to help manage the development of software, it is does not do the management. This is the responsibility of the package coordinator and other developers. In cases where potentially conflicting modifications have been committed to the repository, CVS warns of possible conflicts and the user must fix them before the commit is accepted. Users can update their private copies:
cvs update <package name>
This should always be done before attempting to commit any changes. An update brings users private copies up to date with recent changes. All files in the module are listed during an update, preceded by a letter indicating whether the files have been Updated or Modified by the user. If any files modified by the user have also been modified by others, these files are flagged and both sets of changes are incorporated into the users code. It is the users responsibility to resolve any conflicts arising before the modified code will be accepted into the repository.
If you have a tagged version of a module checked out, the default update action will only look for changes to the tagged version and will not bring your code completely up to date. This is generally not what is required. An important variation of update is, therefore,
cvs update -A <package name>
this update command will bring your code up to date with the head version in CVS, whatever version you originally checked out.
By default cvs co will check out the current or head version of a module. This may be a problem if this is a development version, i.e. it probably won't work! Specific versions of modules can be checked out by specifying a tag:
cvs co -r <tag> <package name>
Of course the user must know what the appropriate tags are.
Other commands are available for adding new files (cvs add) and removing files (cvs remove). Refer to the CVS manual and/or a CVS expert for further details before trying these.
After checking out a specific version it is not unusual to discover some modifications which you would then like to commit. NOTE that what you probably really want to do is to commit the changes to the latest version of the source code (the head version) and NOT changes to the particular version that you have checked out, which may be very out of date and which should not be changed in any case (this is why the code was tagged in the first place). Your checked out copy knows that it originally came from a tagged version. In CVS jargon it has a sticky tag which means that when you do a cvs update or cvs commit your code is compared to the tagged verson in the repository. To bring your code up to date with the head version you must perform a special update:
cvs update -A <package name>
You should always do this before commiting any changes to the code. The way we use CVS is such that we do not make modifications to released versions once they have been tagged so almost all changes should be commited against the head version. After updating your code you should always make sure to resolve any conflicts which turn up (as a result of other changes committed since the tag was made).
As mentioned above, CVS knows which version of the package you originally checked out. This information is kept in the CVS subdirectory which you find in any checked out package and not in the files themselves. One consequence of the way in which CVS remembers this information is that if you replace a file with a different one (of the same name) CVS assumes that all the differences are real changes that you wanted to make. This can cause problems for the unwary. e.g.
You check out a package P containing a file F on a certain day when the file is version F1. This creates sub directory P(1)
You edit the file F and add your changes
You check out P again into a different directory, maybe on a different computer, this creates sub directory P(2). Since your first checkout, others have made changes to file F and this is now version F2.
You copy your modified file F1 (from P(1)) into your new package directory (P(2)) [You probably do this because you want to commit your changes to F and its easier to do this from the computer where P(2) is].
You commit your new package P(2) to CVS.
CVS looks at your second directory P(2) and thinks you
checked out F2 into that directory (you did). It then looks at
your file F, modified from F1, and compares it with the
F2 in the repository. CVS notes your intended modifications
but it also sees that you have removed all the changes that the other
developer had made in going from F1 to F2. CVS assumes
that all the changes are intentional and commits the file. All the
changes from the other developer(s) are thus lost. NOTE
the standard cvs update
would not help here, because CVS believes, from the
information in the CVS subdirectory, that your package version in
P(2) is up to date (no more changes have been committed since
you checked out P(2)). The cvs diff
command, described above, will spot and alert you to these problems
as it will list all the things that cvs thinks you changed (ie
removing the other peoples changes). The moral of this tale is never
never never Never move CVS controlled files between different
directories in this way.
The following is a list of common problems that users have encountered to date:
If you are refused access to the CVS repository, with an error like
cvs server: Sorry, you don't have read/write access to the history file
cvs [server aborted]: /afs/infn.it/pd/project/pepn/repo/CVSROOT/history: Permission denied
cvs [checkout aborted]: premature end of file from server
then check that you have a valid AFS
token. If not then klog into
infn.it.
To get access to the pep-n packages you have:
to obtain a valid AFS token:
klog pepnmgr@infn.it
the password (for obvious reasons) is not shown, request it by e-mail
set the repository:
setenv CVSROOT /afs/infn.it/pd/project/pepn/repo
checkout the package
cvs checkout -r <tag name> <package name>
To help new users to get some experience with CVS there's a dummy package (called testdir) with one file, you can edit it, add new files, tag etc. to learn how to use CVS
To
add new packages to the repository please request
it, don't do it by yourself
Committing changes to CVS without first comparing files with HEAD in CVS is quite dangerous. One may accidentally wipe out changes committed by others.
The following procedure is recommended before you commit changes to CVS:
Type one of the following commands
cvs diff -Dnow <file> [compare one file with HEAD in CVS]
or
cvs diff -Dnow [compare whole package]
to compare local version with the HEAD. Carefully look for changes that do not belong to you. If there is none, proceed with the commit. If there are differences that do not belong to you, consider the following options:
If there is concurrent changes in CVS committed by another user. Type:
cvs update -dA [merge with HEAD version]
now go back to step 1) until only your changes remain in diff.
If your version is actually a copy from a previous version. Type:
mv {file} {file}.old [save your version]
cvs update -dA {file} [get a fresh copy]
emacs {file} [put your changes back]
to redo the editing. Do not copy CVS files from one directory to another. If you have to do so for special reasons, following the procedure above can prevent mistakes.
Note: Do not commit a copy back if you see any changes that
do not belong to you. When in doubt, always check out a fresh copy
and starting over the editing session.
Last
changed: