HowToWrap

*** NOTE:  YOU SHOULD NOT HAVE TO DO THIS!! ***

These are random notes about my experience wrapping "_skysub.c" in
python using SWIG.  I have included this, and the "skysub.i" 
configuration file which SWIG uses, in case you need to alter the 
skysub source code and recompile it.  As the headline says, you
shouldn't have to do this.  

In the normal course of events, the "skysub_wrap.c" included in this
package (which was generated by SWIG) should simply compile 
together with the "_skysub.c" source code to produce a working
module, "_skysub.so", which gets installed in a place where your
python system will see it.  So, don't mess with this unless you
have to.

I'm not expert on SWIG, I learned just enough to get this working.
But if you're trying to wrap your own C code in a SWIG of version
1.3 or higher, you might find the information here (and in skysub.i)
to be useful.  Otherwise refer to the extensive SWIG documentation
online.

*********************************************************************

Capsule summary on Bouree 2004 Apr 19:

swig -python skysub.i
gcc -c -fpic skysub.c skysub_wrap.c -I/usr/include/python2.2
gcc -shared skysub.o skysub_wrap.o -o skysub.so -lm

... look at skysub.i and cooclasses.py to see how the slightly tricky
    array etc. issues get handled in swig 1.3+.  I've got it running
    now ... some changes:

    - INPUT, OUTPUT, and INOUT used for variables ..
    - need to call shared object library _skysub to get the init right
    - Use "array_functions" and "pointer_functions" to define pointers
       to arrays of doubles and simple pointers of doubles, for handing
       to C routines which require values handed in on pointers.  See
       the cooclasses.py (working!) code to see how this is handled.

*********************************************************************



Wrapping these subroutines in Python wasn't quite as hard as I'd feared,
thanks to SWIG (Simplified Wrapper Interface Generator).

SWIG is available from sourceforge.  The home page for swig is
www.swig.org, and it has lots of documentation as to how to use it.

I had to get and install swig first but this was easy.

The steps were:

1) Prepare an interface file "skysub.i".  This is mostly just the
  subroutine declarations, but there's some tricky business in 
  getting values handed back properly when they're passed back
  in C as pointers.   As of the first day trying this I still haven't
  got character strings handed back properly yet, but these may seldom
  or never be of value from scripts.  

  The tricky business involves including the swig "typemaps" stuff
  and declaring the particular variables handed back by routines as

%apply double *OUTPUT {double *az, double *parang,  ... };

  and then explicitly naming them in the function definitions

extern double altit((double, double, double, double *az, double *parang);

  Note also that all the routines you want need to be extern.  
  Probably the declared constants, too, but I haven't got quite that
  far.

2) I had to go through and make a new copy of skyansb.c, called skysub.c,
  in which all the subroutine declarations are pure ANSI style.  Somehow
  these mostly migrated back to old K&R style.  This was very tedious but
  do-able.

3) Once everything was prepared, this worked:

	swig -python skysub.i

   This generates a file called "skysub_wrap.c".  

% **** not needed -- change include path later *****
%   This file neede to have the 
%
%#include "Python.h" 
% 
%    modified to /usr/include/python2.1/Python.h on partita.
%  **************************************************

   Then:

**********
% superseded	gcc -c -fpic skysub.c skysub_wrap.c -I/usr/local/include
**********

NOT THIS : [[gcc -c -fpic skysub.c skysub_wrap.c -I/usr/include/python2.1]]

THIS: gcc -c -fpic skysub.c skysub_wrap.c -I/usr/include/python2.2



(or on allemande:)
	gcc -c -fpic skysub.c skysub_wrap.c -I/usr/local/include/python2.0
        
        gcc -shared skysub.o skysub_wrap.o -o _skysub.so -lm

*** NOTE THE LEADING UNDERSCORE IN THE OUTPUT FILE!! ***
   This is new as of Swig 1.3.something.

Then copy the _skysub.so file to /usr/lib/python2.2/site-packages, and
off you go ... 

   And then, one can simply

	python
	import _skysub 

	... and away it goes!  

STILL TO DO:  

----------
	- Flesh out all the simple (double, int, etc) arguments which might
 		need to be passed back
---> I think I got almost all of those ... except for the get_double etc
  	which might be nice to have still for interactive use

-------------------------------------------------

	- Determine whether any string values need to be passed back
		Yes, they do, load_site is esp problematic.  Did figure
		out how to do it, see below.
	- Figure out how to handle data structures, etc.  
		(needed for "caldat" at least).

		The planet elements structure is (thankfully) hidden,
		not needed explicitly.  It's a global. But in a number of
		places it would be good to pass around a "struct date".

	Hey, I got it!  --
		put the struct_date definition "out in the open" outside
		the %} line ....

		Then it works to say 

		v = skysub.new_date_time()
		skysub.date_time_y_set(v,2002)  
				etc. for mo, d, h, mn, s .... awkward 
				but it does work!

-------------------------------------------------

	I did figure out how to handle simple arrays of doubles etc as in
	planetpos .... in the interface file,

%include pointer.i

	and then in the python script

**** This is now superseded in SWIG 1.3, with e.g.

		raptr =  _skysub.new_doubleArray(10) 
	then later
		_skysub.delete_doubleArray(raptr)
	to clean up.

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx