How to Create a New Module

STAR Computing	Tutorials main page
How to Create a New Module (incl. PAM and Domain)
Offline computing tutorial	Maintained by Kathy Turner

Set up directories needed
- go to your work area, e.g. cd ~/workdir
- It is easiest to create a new domain in your area, so that you can compile and run your code separately from the main libraries - even if your code will eventually end up in a standard domain/package.
- If you are creating a new domain, then you must create the directories under ~/workdir
```
       mkdir pams; cd pams
       mkdir domain; cd domain;   # what domain you want to have
       mkdir idl
       mkdir inc
       mkdir kumac
       mkdir package(s)            # new package(s)
          cd package
          mkdir doc                  # doc subdirectory
          cd ..
     
```
- If you need to use an existing domain, then you must first check out the domain from cvs (check out whole domain in order to avoid problems)
```
 cvs co pams/domain  
```
Now write files as needed
- For each package, you may have more than one MODULE (e.g. package tpt in $STAR/pams/tpc/tpt/ has 2 modules: tpt & tpt_sts).
- In pams/domain/package you should have the following:
  1. module.idl
  2. module.c or .F (must have same name as module.idl)
    - NOTE: Once you have your module.idl file, you can generate template C and Fortran files using stic:
      > stic module.idl
    - Now you have module.F.template, module.c.template
    - You can delete the module_i.cc,module.inc,module.idl, module.h files created by stic - they aren't needed
    - You can now change the name of the template source code (and delete the one you don't want) and put in your code
    - Of course, you don't have to use stic - you can just write the code yourself.
    - Note that the source code MUST have:
      #include "module.inc" (fortran)
      #include "module.h" (C)
      right at beginning of file! These are not files you need to write yourself - they will be automatically generated!
  3. any other source code called by your module (but the only code callable by STAF is the module itself)
  4. any header or include files used only by this package
  5. doc subdirectory with html files
  6. README file
- In pams/domain/idl - table idl files
- In pams/domain/inc - include or header files used by more than 1 package.
- In pams/domain/kumac - For each package, you should have a package_init.kumac and package_run.kumac with separate macros for each module. For each domain, you should have a create_tables_domain.kumac with separate macros for each package or module.
Compile & Make Library
- Now make shared libraries for each of your domains:
  >cd pams/domain
  > makes (do this outside of STAF - it's different!)
- If you mess it up and have to do it again, you might need to do:
  > makes clean clean_share NODEPEND=1
- If it's *really* messed up, you may have to go delete dependency files:
  > cd ~/workdir
  > cd *arch*
  > delete files under dep,lib,obj