10.2 Developing Software

Complete:
Detailed Review status

Goals of this page

When you finish this page, you should understand the basic concepts to consider when developing your own software. Additionally, you should know how to document your code so that it appears in the CMS online documentation.

Eventually this page will also contain instructions for contributing analysis documentation to the main documentation repository.

Contents

• Instruction for writing code
• Writing Code to run in the CMSSW Framework
• Writing Private Code to run in CMSSW
  • Creating a user area in the CMSSW repository
  • Commit your files to your own subdirectory
• General Principles for Software Development
  • Test your new code locally, on small data samples
  • Collating your results
• Contributing documentation
  • Contribute to the CMS WorkBook
  • Contribute to the CMSSW Reference Manual
• Review status

Instruction for writing code

Tools and instruction for writing code can be found in the Offline Guide Framework section. In particular, to avoid problems with memory leaks, you should follow the guidelines for using pointers.

Writing Code to run in the CMSSW Framework

Instructions for developing CMSSW code, adding packages, checking new code into the CVS repository, and maintaining your code are currently found in the CMSSW Developers Guide.

Writing private code to run in CMSSW

This section is intended for users who want to write "user" code which will never go into CMSSW public software releases. If you intend for your code to go into CMSSW releases, you should probably request a normal package with the normal procedure via the Tag Collector. For this see the Writing Code section below.

Creating a user area in the CMSSW repository

There is an area called "UserCode" in the CMSSW repository where you can create yourself a package to store your private user code and cfg files, for example:

UserCode/PElmer

To create such a user CVS area for yourself, do the following:

1) Choose a packagename for yourself. Typically this should be your name (e.g. with some capitalization as above, or your CERN unix username, etc.) so that it is semi-obvious whose package it is.

2) Then create your package (here for an example "JohnDoe" user):

         a) Set your CVSROOT to point to the CMSSW CVS repository.
         You do this by doing the following, for example:

         ***********************************************
        [malik@cmslpc02 ~/test]$ kserver_init
        Enter your username at CERN:malik
        Getting your Kerberos 5 credentials from CERN
        Password for malik@CERN.CH: 
       Ticket cache: FILE:/tmp/krb_cern_6398
        Default principal: malik@CERN.CH

        Valid starting     Expires            Service principal
        01/21/10 23:03:12  01/22/10 23:03:12  krbtgt/CERN.CH@CERN.CH
        renew until 01/28/10 23:03:12
        ***********************************************


         b) 'cd' to some temporary area
         cvs co UserCode/README
         c) mkdir UserCode/JohnDoe
         d) cd UserCode
         e) cvs add JohnDoe
  

In general it is advisable to structure it like a normal CMSSW package,

1. 1. e. with the same subdirectory structure. To do this, you can do:

         mkdir JohnDoe/src JohnDoe/interface
         cvs add JohnDoe/src JohnDoe/interface
         mkdir JohnDoe/data JohnDoe/test
         cvs add JohnDoe/data JohnDoe/test

If you do not think you need some of these subdirectories at the moment, you simply do not 'mkdir' and 'cvs add' them.

3) Then you can 'cd' into the "src" area of some scram working/developer area and do:

         cvs co UserCode/JohnDoe

and begin to add your code and cfg files to the subdirectories. If you need a CMS.BuildFile, you can copy an example from a normal CMSSW package and edit it to serve your purposes.

Commit your files to your own subdirectory

Please note that you should not commit files to the UserCode directory itself, but only in your equivalent of the JohnDoe sub-directory.... You should find your code on the url here to UserCode in CVS.

General Principles for Software Development

Test your new code locally, on small data samples

When writing your own code, it is important to run on your local working environment and test the analysis code on a small number of events - this saves time and resources.

You should develop your own code locally, and compile it, then run on small test samples to enable you to quickly track down and fix bugs.

You should also save and test your code regularly - otherwise it can be very time-consuming to track down errors which might produce obscure messages.

Once you are confident your user code is working correctly, you should run a short test job on the sample that you plan to use in your analysis (either data or Monte Carlo). This will enable you to test the compatibility between your code and the specific sample you want to analyse. Additionally it will enable you to test if your code runs properly in the case that a different submission process is used for the main job compared to local running (i.e., batch submission compared to interactive use) Sometimes certain commands or characters may cause the code to react differently.

Batch systems for job submission are prioritized to provide fair access for all users, and very short jobs attract a high priority - therefore small test jobs can be run quickly. This can provide a significant saving of time on a busy system.

Collating your results

At the end of your analysis job, you will want to "summarise" your analysis jobs and produce plots of information from the analysis and reconstruction. This is typically a less compute-intensive job, and tends to be something people do in their local environment.

Contributing documentation

While you are developing your own software, it is likely that you will find areas in which you can improve the online documentation so that other users can benefit from your experiences.

There are three principal ways in which you can do this.

• The first is the CMS Offline WorkBook, of which the current page is a part. If there are pages relevant to your code, you should give feedback and suggest improvements.
• The second is the CMS Offline Guide, which gives all the details of the CMS software. Whenever your code becomes public, you should provide a page which explains how it works and how to use it.
• The third is to make your code "self-documenting" by adding descriptive comments to your code which can later be farmed by the Doxygen system.

The CMS Software Documentation Policy is described in SWGuideDocumentationPolicy.

Contribute to the CMS WorkBook

Contributions to the documentation of the CMS WorkBook project are very welcome. Please see the Guide for contributors.

Contribute to the CMSSW Reference Manual

The CMSSW Reference Manual contains automatically generated documentation, produced by Doxygen, describing the classes and packages. The manual can be found at http://cmsdoc.cern.ch/cms/cpt/Software/html/General/gendoxy-doc.php.

An explanation of how contributors can annotate their code to add material to the Reference Manual is available following the link from the bottom of the Reference Manual main page.

---

Review status

Reviewer/Editor and Date (copy from screen)	Comments
KatiLassilaPerini - 22 Jan 2008	fixed ref. manual links
JennyWilliams - 20 Nov 2006	minor edits
JennyWilliams and AnneHeavey - 21 Jun 2006	minor edits
JennyWilliams - 22 Mar 2006	Author
Main.argiro - 06 Dec 2006	Reviewed
AndreasPfeiffer - 12 Feb 2008	Reviewed

Responsible: SudhirMalik
Last reviewed by: SudhirMalik - 21 Jan 2010