Requirements for Submitting Software

For the annual report, source code, makefiles, and documentation should be sent as a tar file to Rolf maier@ucalgary.ca.

To submit software to be released at the CREWES meeting, please see which of the following requirements apply to your software. We no longer include compiled object files or compiled programs as a matter of course, there are too many variant systems around. Various kinds of documentation required to recompile and rebuild are hence important.

Prerequisites

Some code depends on other code, often whole packages. If the new code is for one particular package like ProMAX, state which version you used. If the new code requires external packages to be loaded with packages like BLAS, LAPACK, MPI, etc., please state the following in a README file:

  - packages required and versions used.
  - location of the packages on the net.
  - dependencies: what needs to be compiled first, where does a subsequent
        package find its precursor.
  - Any special points regarding the compilation and installation of the
        packages.

It may even be necessary to get additional compilers, for instance, only gfortran incorporates OpenMP among GNU compilers, g77 and g95 do not.

Code

Code should be in C, C++, or one of the Fortran dialects. The case of MATLAB files is handled elsewhere. Only the newer versions of Fortran have stream I/O and other features which once made C a prime candidate for I/O, hence code may be in mixed format. All code should come with some internal documentation, so sponsors can adapt it to their systems. A large collection of files may require a few subdirectories. That is fine. Put function xxx into xxx.c, etc.

Avoid precompilers and vendor-specific code in Fortran to enhance portability. Remember that PARAMETER statements leave no code after compilation if the parameters are only used in if statements taking the role of #ifdef statements in preprocessor code.
Similarly, a CONTAINS block (per function or subroutine), or MODULEs can be used to contain what in C might be preprocessor macros. F77 programmers are limitted to the now defunct statement function.

Compilation

Code should compile cleanly, and there should be a make file to do this. On GNU compilers add the compiler flag -Wall to CFLAG or FFLAG in the makefile. This informs you of unused variables, variables which are referenced before being set, etc. Please fix your code until all is quiet.

Annotate the makefile(s) sufficiently to avoid having others guess what should be what.

Separate pieces of code should be kept separate, even if they are intended to be included into the same package.

Documentation - Contents

General descriptions, theory, or limits of applicability, are fodder for a CREWES report. You may refer to a CREWES report in a README file; years after release this could become a useful link.

Freestanding code should have brief internal documentation which tells a user what do to if the command is called without arguments yet needs some. It also should be accompanied by some simple text in the manner, but not necessarily in the format of, UNIX man pages, say, which can be installed as independent documentation and will tell a user a bit more than a command's usage message. Such a file could contain: a description of what the command does, and by what method; name and purpose of any related commands, and the order in which to run them; how to generate a parameter file template; anything else you may consider necessary or at least desirable like how to calculate certain critical values, etc.

Package related code will have files of a type specified by the package which will have to be installed in predefined locations. Again, the package will have an internal parameter selection mechanism and internal help (menu files and PDF files in ProMAX). Ensure that these files are present and that they work in the target environment.

Documentation - Format

The easiest format to use that is still easily converted into several more sophisticated formats is POD. The perlpod manual on Linux (or Cygwin) tells you how it works. Its rules are few, and its syntax is rather limitted. I do not want to reproduce the manual here, just add a few points.

1. A dot ending a sentence should be at the end of a line, others dots (as in eg., etc., vis., p., ...) should not. This is to help groff which makes UNIX man pages.

2. Do not use tabs to create tables: the result can be a bit shakey when other formatters get such text because they indent the page, shortening the first tab's range. The unexpand command might be handy at this point, it replaces tabs without changing the looks of a file.

3. To indent text you not only must indent the text, but the line before the first indented line must be empty.

The command podchecker tells you what is still wrong, and where. Whatever the ultimately intended format, please include the original POD file. This allows for easy corrections and fixes. The sponsors can easily add their comments and cross references to POD files.

Documentation - POD to PDF

To turn a POD file into PDF, intermediate steps are necessary. Say our pod file is called eg1.pod. First, run

    pod2latex eg1.pod

to get a file called eg1.tex. At the very least prepend this new file with the lines

    \documentclass{article}
    \begin{document}

and end it with the line

    \end{document}

Second, run LaTeX to create a DVI file:

    latex eg1

Third, turn the DVI file into a PDF file:

    dvi2pdf eg1

Does this contain anything you still recognize? Let's hope so.

Documentation - POD to man

This is useful to create man pages for an independent package of code. Issue the command

    pod2man eg1.pod

Alternatively you may create man pages directly; they will look a little nicer than what pod2man produces, but they are harder to write.

Documentation - POD to HTML

Although not required for the deliverables, an HTML version is easily created via

    pod2html eg1.pod > eg1.html

On Cygwin you can immediately see the result with

    cygstart eg1.html

As in the case of a program, syntactic correctness is no guarantee of correct execution.

If you are reading this in HTML then you are looking at a converted POD document.

Installation

Write into a little file called INSTALL what is required in terms of compiled software, documentation, accesses, changes to (make)files, etc. Package related code will have to be installed as the package demands, besides possible differences between different versions there is not likely much to be added.

Care should be taken in the way independent code is deployed. The install command gives you more freedom than cp or mv.

An alternative is to call stow where available. Nothing is copied or moved, only links are made, which clearly identify the origin of any file. Furthermore, since files are not installed they can stay under the control of the originator, allowing for easy fixes or the additions of new, stable developments without root access.

Sources of stow and its sibblings, nstow and xstow, are available from the FSF at http://linux.softpedia.com/get/Utilities/ Simply search for stow.

Personally I like stow, but an alternative installation path should be available in the case of independent software.