
              An OpenMath C library

From the European project 24.969: "OpenMath: Accessing and Using 
Mathematical Information Electronically". 

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

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

This  is  a  release  of the  OpenMath  C   library.  This library  is
developed  in the CAFE team at  INRIA (Sophia Antipolis).  The contact
persons   are  Olivier   Arsac ("olivier.arsac@sophia.inria.fr")   and
Ste'phane Dalmas ("stephane.dalmas@sophia.inria.fr").

This library is the sample implementation of the OpenMath standard and 
C API as specified in the European project.

The  sources needed  to build  the OpenMath  library are in  directory
src. (Some documentation may be found in doc directory).


For Unix users
--------------

You should get the ".tar.gz"   ot ".tgz" version of the  deliverables.
The  ".zip"   version   contains windows precompiled    executables or
libraries.

 gunzip OM*gz
 tar xf OM*.tar
 cd OMCv*/src/

To make the OpenMath library, you first have  to generate a (possibly)
system-dependent "Makefile".  This is  done by running the "configure"
shell script.  Then you have to run "make".  Usually, you just have to
type:

  ./configure
  make

The  "configure"  script  tries  to   use  the  "gcc"  C  compiler  if
available. If you want to compile  the library with another C compiler
("cc" for instance), type:

  CC=cc ./configure

If  your    system requires  unusual  options  you   can  pass them to
"configure" via environment variables:

  CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

If  your shell is some sort  of "csh" you  may need to run "configure"
with "sh" explicitly   and  to pass environment variables   in another
way.  The following  should almost  always   work for  these kinds  of
shells:
 
  setenv CC acc
  sh ./configure
  unsetenv CC

"make" will make both   "libOM.a" and "libOMconn.a" and   perform some
automatic tests.   It is possible  that the  tests   may fail even  if
everything is correct.  This is usually a problem due to the shell. If
this  happens please send us information  about your system.

To use the library, you  just need  the  include  file "OM.h" and  the
archive "libOM.a" (and possibly "libOMconn.a").

If you intend to  use the same  directory for compiling the library on
several architectures, you should do a "make distclean" before running
"configure" again to generate the proper "Makefile".

Some hand tuning in the generated Makefile  may be used if compilation
fails. Some AIX  users have  been reported  to need a  -lisode in  the
LDFLAGS.


For Windows users
-----------------

You should use the ".zip" version  of   the deliverable.  This special
package  contains all what  is  needed under  Unices  plus the windows
project  files and precompiled objects.  The  project files are for MS
Visual Studio 5, but I guess it should be easy for any Windows user to
define such project files for other environments. (BTW: if you do that
I would be glad to collect these efforts.)

The package  contains the precompiled   versions  of the core  library
OMlib.lib.   It is provided  in   two flavors.  A debug version   with
maximum checking    is located in  the  "D"   directory and  the fully
optimized version  is in the "R"  directory. The OMconn utility API is
not yet available under Windows.

To use the  library in your  own applications you  have to include the
OMlib.h header and link to one of the OMlib.lib archives.

There is a  small  test programm  provided for MFC  users in directory
OMTest. It is  here mainly to give you  the right environment for link
with MFC libraries (by default they conflicts with std C runtime).


Documentation
-------------

The documentation   of the library is  available  as a PostScript file
"api.ps" that    should   have been   shipped with   this distribution
(standard  location is "doc"  directory  at the same  level  tha "src"
directory). If you have  trouble printing this file,  please send us a
note.


Sample applications
-------------------

Three applications are shipped along  the library  to provide you with
sample code.  Under  Unix they are used in  the auto-test part of  the
Makefile.

- "tenc": do some low level I/O of OpenMath tokens to check them.

- "tpipe": is  a syntax checker for  OpenMath objects.  It may also be
used to convert from one format to another  (binary/XML). It is a good
starting point to dive into sources (if you dare to).

- "omproxy": is a test for the  OMconn part of the API. It may be used
as a proxy or as a fake OpenMath client  or server that pipes files to
other side.   It needs OMconn  part and thus it  is  not yet available
under Windows.


For comments, suggestions and (of course) bug reports email to:
olivier.arsac@sophia.inria.fr
