ApCoCoALib:ReadMe

This is a copy of ApCoCoALib's README file:

CoCoALib README
===============

Date: 9 March 2007
 
This subtrree contains the sources of the C++ library CoCoALib.  The CoCoA
library offers functions to perform calculations in Computational Commutative 
Algebra, and some other related areas.  Our intention is that the library
should be pleasant to use while offering good run-time performance.  To use
the library you will need to have some knowledge of C++.


Where to start
--------------
(a) Compile CoCoALib following the instructions in the file INSTALL.
(b) Look at the example programs in the directory examples/, and try
    compiling and running them.  See the file examples/README.
(c) Read a little documentation (in the directory doc/): we suggest
    starting with ring.txt.


Documentation and how to use the library
----------------------------------------
The documentation for CoCoALib comes in three parts:-
 (1) example programs in the directory examples/
 (2) hand-written documentation in the directory doc/
 (3) automatically generated documentation in the directory doc/doxygen/ 

We believe that many simple questions are probably best answered by looking
at the example programs (and perhaps applying a little intelligent guesswork).
The hand-written documentation in the directory doc/ is supposed to be
exhaustive (and is doubtless also rather exhausting).  The Doxygen files
will be of more use to those already experienced in using CoCoALib.


Writing and compiling your own programs
---------------------------------------
An easy way to write your own program using CoCoALib is to make a copy of
the file ex-empty.C (in the examples/ directory), and then insert your code
inside the procedure called "program".  Assuming you have called your program
"proc.C" and placed it in the examples/ directory, compiling it is very easy:
just type the command "make prog"; if compilation succeeded, your program will
be in the file "prog".


The CoCoA Forum
---------------
You can find discussions about various aspects of CoCoALib on the CoCoA
forum which is hosted at the following address:
    http://cocoa.mathematik.uni-dortmund.de/forum/
It is also be a good place to seek help and advice about using CoCoALib,
and to contribute to CoCoALib with your own comments and opinions.


Principal Changes from CoCoALib-0.94
------------------------------------
Here are the main changes from version 0.94:

- operations on ideals (and major rewriting of G* files)
- ref counting template (SmartPtrIRC)
- operations on ideals and modules
- GBases on FrF(R)[x] are now performed in R[x]
- preprocessing routines for approximate points (ApproxPts.H/C)
- code cleaner and better organized
- improved code portability (even to some Microsoft platforms)


Debugging with CoCoALib
-----------------------
CoCoALib does offer some help in tracking down bugs in programs which
use it.  If the preprocessor symbol CoCoA_DEBUG is set then various
run-time assertions are enabled which perform extra checks in various
functions.  If you use the compiler  g++  then the simplest way to
activate debugging is to modify two lines in the file
configuration/autoconf.mk -- the file contains comments to guide you.
You may like to read doc/assert.txt to learn about CoCoA_ASSERT.

If your program seems to have memory leaks, or other problems to do with
memory alloccation, try reading the files doc/MemPool.txt, doc/debug_new.txt
and doc/leak_checker.txt which give advice on tracking down such problems.
NB these are oriented towards programmers with a fair amount of experience.
   
  
  
Bugs and other problems
-----------------------
The code here is still quite young, and has been little tested.  It is
likely that you will come across some bugs or other undesirable 
behaviour.  If that happens, please let us know.  Your bug report should
include a SMALL program which exhibits the bad behaviour with a clear
indication of what you think the program should do, and where it 
apparently goes wrong.  The best way to inform us of the problem is to
send a description of the bug to the CoCoA Forum (its URL is
http://cocoa.mathematik.uni-dortmund.de/forum/); specifically put your
message in the group "CoCoA 5 Users".

If you'd rather not post to the CoCoA Forum, you can send email to:
  cocoa@dima.unige.it


=============================================================================
RCS header/log

$Header: /Volumes/Home/cocoa/cvs-repository/CoCoALib-0.99/README,v 1.2 2007/03/20 12:34:32 abbott Exp $
$Log: README,v $
Revision 1.2  2007/03/20 12:34:32  abbott
Minor rephrasing.

Revision 1.1.1.1  2007/03/09 15:16:10  abbott
Imported files

Revision 1.2  2006/06/21 17:04:12  cocoa
Improved README, INSTALL and configure script.
(perhaps I should have done this prior to release?)