
                CMAIN: Delivering Talk Software to C/C++ world
                ==============================================

Overview
--------

RATIO is a toy example of a Talk program --- in this case, the
built-in Talk <rational> arithmetic --- made available to C++
programmers.  All the source code is in the subdirectory src.  To
build and run the example, do the following:

$ build-ratiox                          to build the delivery
$ test-ratiox                           to build and run an application
$ $HOME/talk-play/<port>/ratiotest      to run again

Note: Your environment must be set up correctly to run Talk, or you
must use a shell from within a XEmacs session started with the
"runtalk" command.  To find out more about setting your environment,
see ../../<port>/START.

Note: This example only works on Unix platforms.

Note: You need a C++ compiler in your path to build and run this example.


Introduction
------------

The Talk software we are going to deliver to C++ programmers in this
example is rational arithmetic, which provides exact arithmetic --- an
attractive alternative to the approximate float arithmetic of C in
many cases.  The test application shows how rational arithmetic lets
you control loops with non-integral values where float arithmetic
leads to unexpected behavior.


How To Create A Deliverable
---------------------------

To deliver a facility to C++ programmers, we wrap the Talk rational
arithmetic facility in a C++ class called 'ratio'.  Most of the code
in src/ concerns this class's declaration and its hooks to the
appropriate Talk functions.

What we want to supply to the C++ programmer is:
 - A header file 'ratio.h' providing the interface.
 - A set of binaries (.o) and libraries (.so) implementing the
   package.
 - Documentation of how to link these into the client's code.

We must manually write the header file 'ratio.h' which will be
delivered to the C++ programmer, and the interface implementation file
'ratio.cc'.  It is also important to provide an initialization
function --- in this case, ratio_init() --- which calls iltmain() to
initialize Talk.  Now let's see how to build the rest of the
deliverable, following the model in the script build-ratiox.

We first need a Talk module which tracks the ratio object file ---
let's call it 'ratioe'.  We create this module and add 'ratio.o' to
its list of external object files in the 'externals:' key of its td
file.  We then build it.

Next we create a Talk executable, say "ratiox", containing that module
and build it.  This executable is somewhat artificial: Because the
"user-main-p:" key is set, build-program-unit will not produce an
executable, but instead a shell script to be run by the C++ programmer
to produce the final executable.  This shell script will help you
document how your client will link the deliverable with his or her
code; it is not itself part of the deliverable.

The shell script is system-dependent, and it lists the objects which
need to be delivered to the C++ programmer, such as the object files
and shared libraries.  Building the Talk executable ratiox produces
$HOME/talk-play/<port>/ratiox, which you should read it carefully.
You may notice that while building ratiox, Talk temporarily creates a
dummy executable file: Don't worry, this is just to determine
experimentally how big the final executable's image should be. This
information is placed in ratioxboot.o.

The deliverable is now ready, and includes the following files:

 - ratio.h
 - ratiox (the executable-generating script shell)
 - ratioe.o, ratio.o, ratioxboot.o, libiltcrt.so, and libiltrt.so
   (as mentioned in the shell script ratiox)


How To Use A Deliverable
------------------------

The simplest use is to write a C++ program using ratio.h and defining
main(), and pass it to the script ratiox.  In real development, C++
modules including ratio.h will be separately compiled and linked
together later; this will require cutting information from ratiox and
pasting it to a Makefile.

The resulting C++ executable will automatically build its own Talk
image (unless "imagep:" was set to "()" in ratiox.td) the first time
it is started.

In src/, the program ratiotest.cc is an application which compares
Talk's rational numbers with C++'s doubles.  The script 'test-ratiox'
creates the executable by simply passing ratiotest.cc to ratiox, which
produces the executable file ratiotest.

Then ratiotest can be invoked to show which type of arithmetic is more
precise.  Naturally, Talk's rationals win.  The first call to
ratiotest builds the Talk image, and so will take somewhat longer than
subsequent calls.

If you have any further questions regarding the integration of ILOG
Talk into a C or C++ program, please write to <talk-support@ilog.fr>.
