Contributing new programs to Madagascar

If you want to share your code with other Madagascar users:

1. Follow the guide on Adding new programs to Madagascar.
2. If your employer holds the copyright for your software, obtain a permission to distribute under a GPL license and place a copyright and GPL license notice in each file with code.
3. Register at SourceForge.
4. Find out who the project administrators are (Look for "Project Admins" on this page) and pass your SourceForge user name to one of them.
5. Upload your directory to the repository using svn add and svn commit.
6. Make sure to add reproducible examples of using your program under the MADAGASCAR/book tree. Create new directories if necessary and commit them to the repository. As a rule, programs without examples are not included in the release version.

Some additional useful information is included below.

Repository procedure suggestions

Please try to:

• Do atomic commits.
• Use svn commit -m "your message here" to let others know what changed.
  • Alternatively, set the EDITOR or SVN_EDITOR environmental variables to your favorite editor and edit your message there.
• If you plan to do large-scale substantive changes, create a Subversion branch by running

svn copy https://rsf.svn.sourceforge.net/svnroot/rsf/trunk https://rsf.svn.sourceforge.net/svnroot/rsf/yourbranchname
svn co https://rsf.svn.sourceforge.net/svnroot/rsf/yourbranchname

For coding style suggestions, please see the "Adding new programs" section.

Backward compatibility features

If you introduce or notice a feature that is used solely for backwards compatibility with an old version of a dependency, please document it here, so that the feature can be eliminated when the Madagascar community stops supporting that version of that dependency.

Python 2.2 and older

• In framework/rsfdoc.py: Everything in the have_datetime_module=False branches

Python 2.3 and older

• In configure.py: Everything in the have_subprocess=False branches
• In configure.py: See code after comment "For Py 2.4 and up this can be done more elegantly..."
• In user/ivlad/ivlad.py: Everything in the have_subprocess=False branches
• The entire api/python/rsfbak.py (also needed on systems which do not have recent versions of numpy and SWIG)

Mitigating missing dependencies

The main idea is to attempt to provide graceful degradation when facing a missing dependency. Quoting the Wikipedia page on fault-tolerant systems, this "enables a system to continue operating properly in the event of the failure of (or one or more faults within) some of its components. If its operating quality decreases at all, the decrease is proportional to the severity of the failure, as compared to a naively-designed system in which even a small failure can cause total breakdown."

SWIG or numpy

Graceful degradation is implemented. Please see the Advanced Installation / Python API for an introduction to this issue. The module providing the limited functionality is api/python/rsfbak.py, which emulates header and command-line parameter reading functions from headers from the "official" development kit. When writing a Python program manipulating headers, it may be tempting to write import rsfbak because it is present anyway, but it is not a good idea. Use instead something like: <python> try:

   import rsf

except: # Python devkit not installed

   import rsfbak as rsf

</python> The reason is that the rsf Python module is an interface to the homonymous C library, which ensures a unitary implementation of I/O throughout the package, and it should be used whenever possible. Having programs that do RSF I/O but never uses the official library practically forks the API, which is a Bad Thing. Using the pattern above ensures the alternate partial implementation is permanently synced with the principal implementation.

Reasons for the existence of certain features

Why pyc files are generated during the install step

Python bytecode files, with the pyc extensions, are created during the scons install in order to:

• Register them in SCons' dependency tree, so that they are removed by scons -c install
• Avoid a situation in which a user tries to executes a Madagascar Python program, but creating the pyc file during a module import fails because of lack of write access to $RSFROOT/lib.

cfortran.h

This source code file provides a machine-independent interface between C procedures, Fortran procedures and global data (more details on the website of its initial author). It is a dependency of the F77 and F90 APIs, as well as of vplot. It is included in m8r in two places. Version 4.3 (2002) is still distributed through the website of the original author. Another version (fork?) is maintained at CERN and distributed in the include directory of the interface to event generators in the Monte Carlo libraries in the CERN Program Library (CERNlib). Debian distributes the Free Software part of this package as cernlib. Under Fedora, cfortran.h is included in cernlib-g77-devel and cernlib-devel, which happily overwrite each other's files and create copies of cfortran.h in two different locations deeply nested under /usr/include. CERNlib's Debian maintainer states that "CERNlib is an ancient mass of mostly Fortran code" and that "Most components of CERNLIB are completely broken on modern 64-bit architectures", so m8r developers should be aware that CERNlib will probably be superseded at some point in the future by ROOT, with upstream cfortran.h maintenance possibly continuing this way.

Static code checks

Madagascar contains the beginning of an implementation of static code checks for security vulnerabilities and coding mistakes with Splint. This is visible in the code through the presence of comments like /*@out@*/ and /*@null@*/, which instruct Splint about the intent of different variables and function return values. Future plans include using also dynamic checking by Valgrind or IBM's Rational Purify. Madagascar code metrics are assessed periodically by Ohloh.

Maintaining the maintenance tools

Please document scripts used to maintain the Madagascar codebase, and save them in RSFSRC/adm. Cleanup procedures may need to be repeated in the future, as authors are human and can make the same mistakes again.

Information flow map

The vector graphics original of this map in Dia format is available upon request through the rsf-devel mailing list.