Description
-----------

This package provides one way to automate wrapping application C++ functions that use
OA objects -- as well as app-defined class objects -- for use in Tcl programs.

Many C++ programmers use SWIG to automate the creation of Tcl (and other extension
language) wrappers for their C++ code.  However, oaTcl does not implement its Tcl
wrappers for OA objects and functions in the same way SWIG does it. While manually
coding up wrappers for each app function and its arguments
(https://www.si2.org/openeda.si2.org/si2_online/oa22_04p007api/doc/oa/html/Tcl/index.html#programmingtclapi)
may be suitable if only one or two functions need to be wrapped, for most function
libraries, some level of automation is necessary.


Contents
--------

sample/          A testdata directory copied from the Si2 OA Course labs.
Solution/
  gold.out       A copy of the console output representing a successful run after a `make clean`
si2tcl/
  README.txt     This file.
  Makefile       Unix make targets to automate stages of build, link, and run for the
                 various components in the package (uses makefile.defs for targets).
  makefile.defs  A master make definitions file with many target definitions
                 that is reused across Si2 course labs and utility tools.
  makedefs.gcc   A Linux gcc-specific set of compiler and linker settings.
  si2tcl.h       The declarations for the mock application API to be made callable in Tcl.
  si2tcl.cpp     The implementations for the si2tcl.h file.
  si2tcl.i       The SWIG declarations that will wrap all the OA (and app-defined) types
                 properly for use in a Tcl program.
  si2tcl.tcl     A Tcl testcase driver that calls the functions in the mock app (si2tcl.h)
                 API which use various OA types in their function calls.


QuickStart
----------

make llf          # Creates a library definition file pointing to the sample/ data
make run          # Builds the app library, SWIG wrappers, and runs the Tcl testcase.

Then check the console output against that in Solution/gold.out


Customization
-------------

The current example has wrapped only a few utility classes and managed object handles
in order to illustrate how the use of SWIG macros and typemaps together can reduce
the amount of work involved in wrapping APIs that use oaTcl by eliminating much of
the handwork.

Several comments at the top of si2tcl.i indicate the major sections to update when
adding more object wrapper code for other objects.


Future Directions
-----------------

The approach exemplified in this package still requires some level of manual
intervention in the wrapping process.  The si2tcl.i module only takes care of a few
of the objects from the OA API that can appear in app function calls by way of
example.  There are two approaches to complete automation from this point:

1. Create a master si2tcl.i file that has the appropriate SWIG macros and
   typemaps for every possible OA managed and utility object in the model.
   Update this master file with each new OA release.

2. Write a generator program that analyzes the .h files to be input to the
   system for wrapping, pull out the various arg types and return values and
   generate a si2tcl.i file on demand that includes the SWIG artifacts necesary
   only for a particular library.

Hopefully, experiments by other engineers will suggest which is the more practical
direction to take this approach.