Next: C. Flow Chart of
Up: Suzaku Project Data Management
Previous: A. Acronyms
Contents
Index
Subsections
B. FTOOLS developers guideline
Here is a guideline by the GSFC FTOOLS team for
the programmers developing Suzaku FTOOLS.
This guideline is particularly aimed for Japanese
instrument members who are developing in the ANL environment and
going to convert ANL modules into FTOOLS.
The delivery to the GSFC Suzaku GOF/FTOOLS team
should include the software and test example(s).
- Software
- Source Codes
- Parameter files (default)
- Makefile
- Documents: in plain ASCII text and IRAF ``lroff'' format.
- Examples:
- Relevant input files and resulted output files.
- Test parameter files or test script.
- Useful informations can be found at:
http://heasarc.gsfc.nasa.gov/ftools/others/develop/develop.html
(FTOOLS developer's guide, slightly outdated).
http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html
(CFITSIO HTML guide)
and
http://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/cfitsio.html
(CFITSIO manual for C programmer)
- Use the languages of ANSI C, ANSI C++ and FORTRAN 77 only.
- For scripts, use Perl 5.0 or Tcl/Tk 8.0.
- Comply with the standards of ANSI C, ANSI C++ or Fortran 77; do not use
system-dependent extensions or features.
- For codes of mixing FORTRAN and C(i.e, C calls Fortran and
Fortran calls C), use cfortran.h from CERN.
- For C or FORTRAN FTOOLS, use the cdummyftool and fdummyftool
as templates. They can be found in src/examples/src in FTOOLS release.
- Subroutine or function name must be unique. This is a requirement of
packaging the FTOOLS.
- Do not use the hard-coded ``scanf'' or command line options to read in
the parameter in C or Fortran codes. Use XPI parameter interface.
The routines are documented in pfile.h for the C FTOOLS.
- Do not directly write the message to stdout, use the fcecho or
fcerr routines in cFTOOLS and xpi libraries. Put messages
into the stdout directly will prevent the task from being used
in a pipeline. In case the use of fcecho/fcerr is undesirable in
the development environment, as a compromise, a centralized
output routine should be used whenever ``printf'' is necessary.
- Provide the English translations for the important comments written in
other languages.
- For handling of FITS files, use cfitsio. Do not try to read/write
the files using specialized routines.
- In C FTOOLS, do not use the obsolete fcfitsio routines,
which are the wrapped Fortran fitsio routines, which are the wrapped
cfitsio routines.
- Before calling the cfitsio routine, make sure the error status
is set to zero, otherwise, the routine returns immediately.
- After calling the cfitsio routine, make sure that the error status
still stays at zero. If not, provide the error handling and return
gracefully.
- CFITSIO routine ``ffopen'' automatically handles the filename parsing,
file existing tests etc. Do not use any parsing routine or file open
routines before ffopen. It can hinder the abilities of cfitsio to
open a network file or compressed file.
- ``stderr'' should only be used to output critical error messages,
since the presence of stderr messages are used by many scripts as part
of the error handling mechanism. This restriction does not apply to
``stdout,'' but even this should be used with restraint.
- The Suzaku FTOOLS defines the chatter levels in the softwares from 0 (min) to
5 (max) as does the Swift package. Each chatter level displays 0: critical
error messages only, 1: warning messages, 2 (default): useful information,
3: debugging level 1, 4: debugging level 2, 5: maximum debugging level.
- Finally, do not try to be fancy and clever, do not reinvent the
wheel, and KISS (Keep It Simple, Stupid).
It is well documented in URL:
http://heasarc.gsfc.nasa.gov/ftools/others/pfiles.html
For FTOOLS development, ``hmake'' is used, which is a version of
the ``make'' utility developed locally by the HEASARC. It is not
necessary for the developers to write the
``hmake'' style make file. However, developers should provide a makefile
in one of the popular Unix platforms
(OSF, Solaris, SunOS, HPUX, Linux or SGI, Apple/Darwin).
the software and understand the dependencies between modules.
The help file should be provided in a plain ASCII text file with
the extension .txt and a file with the IRAF ``lroff'' format and
extension .hlp. The ``lroff'' format is quite similar to the UNIX
nroff/troff. You can find it in any .hlp files in FTOOLS
distribution.
The help file should include the following sections:
- Name: Name plus a one sentence description.
- Usage: Synnopsis of the tool
- Description: Detailed description of the tools.
- Parameters: Descriptions for parameters.
- Examples: Examples of using the tool.
- Bugs: Known bugs or features of the tool.
- See Also: References to other relevant tools.
- Author: Authorship, credits and e-mail address for
questions and bug reports
(It is usually
ftoolshelp@olegacy.gsfc.nasa.gov or the help
desk of the mission).
Next: C. Flow Chart of
Up: Suzaku Project Data Management
Previous: A. Acronyms
Contents
Index
Michael Arida
2007-09-29