Developer How-To's

Detailed Process Plan

Verify the help file

Some tools are in a module file. Split the tools out into their own "tool".help files and include the "tool" file in the original module file. Check the helpfile against the glish file, adjust the help file as necessary.

Convert help file to XML

Run the help2xml perl script

help2xml thehelpfile.help > thehelpfile.xml

Refine XML file

Type information the .xml file is incomplete the param tags need some additional information

(1) xsi:type needs to be specified

(2) If the param is a quantity a units attribute will need to be added

Generate IDL and stub files

Assuming you created the .xml file in xmlcasa/implement/mypackage, copy over an existing makefile, i.e. cp ../tables/makefile .; then run gmake.

This will generate the gcode/tool.xml and gcode/tool.idl files and run ccmtools to produce the stub files. You then need to copy over the $AIPSROOT/gcode/$ARCH/impl/tool_cmpt.* files to the current directory. To regenerate $AIPSROOT/gcode where the stubs exist after gmake is ran in the directory with the XML file, first remove the old gcode and then: cd code/xmlcasa gmake

Refine component files

Edit the _cmpt files.

(1) Typically a private pointer class to the underlying casa object is needed in the _cmpt.h, ala

private : Imager *itsImager

you'll need to forward declare the class

namespace casa { class Imager; }

(2) In the _cmpt.cc file we do the impedence matching with the underlying casa object(s).

a) First map the arguments from standard types to casa types b) Invoke the method via itsObject->method(args) c) _cmpt.* files are in the casa code tree near the source code for the objects they represent.

(3) Glish only methods will need to be C++ified.

Build the shared Casa libraries

Build the component

  1. cd code/xmlcasa
  2. gmake componentslib (or casac). Use componentslib to include a new tool or task in the ccmtools mix, use the casac target to just update the casac.so library needed for casapy.

Avoiding a "bad" tool

Occasionally a tool gets checked but fails to build and causes a bottle neck for your development. There is a workaround.
cd gcode
find . -name "*thebadtool*" -exec rm {} \;
ignore the warning messages about not deleting directories.
cd ../code
gmake componentslib
To avoid building the gcode xml and idl files, remove the makefile from the bad tool's directory or the bad tool's xml file.

Migrate existing Tool to new Framework

  1. verify help files correspond to existing GlishDO interface
  2. convert help file into XML (PRODUCT: XML FILE)
    1. help2xml to produce XML output 1 create DO (PRODUCT: DOXXX HEADER AND SOURCE FILE)
    2. source stub and complete header DO
    3. generated from xml file based on xslt translator
    4. header will contain include of private externally
    5. fill in details of library calls
    6. all references to tasking layer are removed
    7. inheritance from ApplicationObject
    8. needs to be DOBase
    9. remove virtual methods
  3. compile DO (PRODUCT: DOXXX OBJECT FILE)
  4. create unit test for DO (PRODUCT: tDOXXX SOURCE FILE)
  5. compile unit test (PRODUCT: tDOXXX OBJECT FILE)
  6. system will generate bindings Python and ACS

DO Modification

  1. modify XML file
    1. documentation / help infomation
    2. interface description
      1. method name(s) and signature(s)
  2. regenerate DO header file
  3. modify DO source file
    1. create method in agreement with XML interface description
  4. compile DO
  5. modify unit test for DO
  6. compile unit test
  7. system will generate bindings Python and ACS

DO Creation

  1. create XML
  2. generate DO header file
  3. add private header information
  4. generate DO source stub file
  5. modify DO source file
    1. fill in method stubs
  6. compile DO
  7. modify unit test for DO
  8. compile unit test
  9. system will generate bindings Python and ACS

Generating User Reference Manual Documentation

If you've added a new tool, you need to add a \input{mytool.htex} into the appropriate Module.tex file. The Module.tex files can be found in code/doc/casaref/CasaRef.dir.

So what if my Module.tex file doesn't exists? Lucky you, you find the old help file with module text and create a new Module.tex file for that untranslated module. Anything that looks like LaTeX, you can leave in there.

Notes on build targets and makedefs

First, don't set CONSORTIA or AUXILIARY in your local makedefs, the global makedefs should be good enough. If you must set them, then make sure xmlcasa is the last entry in CONSORTIA. This insures that the xmlcasa lib is built all all the parts are available for building the casac.so python shared library.

Second, a sneeze -l -m cumulative, will clear out the gcode area and rebuild, if casac.so does not build check to make sure you've got xmlcasa last in the CONSORTIA list.

Third, there are some special targets in xmlcasa,

  1. gmake updatelib
  2. gmake casac
  3. gmake componentslib

updatelib does python setup.py build in the Python_Converter directory in gcode. Use this to compile and link generated C++ code.

casac removes the casac.so file and rebuilds it recompiling and relinking.

componentslib runs ccmtools, regenerates the setup.py file found in Python_Converter, then compiles and links the generated C++ code.

In general you shouldn't need to do "gmake componentslib" unless you've just added a new tool/task in xml.

The builds in the xmlcasa/implement subdirectories, does not rebuild the casac.so, you must explicitly do this via gmake casac or gmake updatelib in the directory. Sorry it's a limitation right now.

How to remove the HISTORY from a FITS file

FITS files in radio astronomy often contain a very large number of HISTORY header rows. They can take up more than 50% of the total filesize. If you need the file only as an example, you may not need to store the history. This script ( striphistory.sh ) removes all HISTORY rows from the header of a FITS file. It's a bash script and needs FTOOLS 6.5.1 installed (see the ftools homepage ).

Usage: ./striphistory.sh filename

The original file is preserved. The stripped file is in filename.stripped .

Note that the presently available ftool for editing header keywords can only delete one row at a time. I contacted the HEASARC people about this and they say that in a future version they will permit to delete all rows containing the same keyword. Then this script will become superfluous.

-- DirkPetry - 08 Dec 2008

-- WesYoung - 03 Nov 2006
Topic revision: r5 - 2008-12-08, DirkPetry
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback