ApCoCoALib:ReadMe

This is a copy of ApCoCoALib's README file:

ApCoCoALib README
===============

Date: 13 December 2007
 
This subtrree contains the sources of the C++ library ApCoCoALib.  The ApCoCoA
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 ApCoCoALib 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 FGLM.txt.


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

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 ApCoCoALib.


Writing and compiling your own programs
---------------------------------------
An easy way to write your own program using ApCoCoALib 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 (Ap-) CoCoA Forum
---------------
You can find discussions about various aspects of ApCoCoALib on the ApCoCoA
forum which is hosted at the following address:
    http://apcocoa.org/forum/
It is also be a good place to seek help and advice about using ApCoCoALib or CoCoALib,
and to contribute to ApCoCoALib with your own comments and opinions.


Principal Changes from ApCoCoALib-1.00
-----------------------
* ???

Debugging with ApCoCoALib
-----------------------
ApCoCoALib does offer some help in tracking down bugs in programs which
use it.  If the preprocessor symbol CoCoA::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 in CoCoALib 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 of CoCoALib 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 (Ap-) CoCoA Forum (its URL is
http://apcocoa.org/forum/); specifically put your
message in the group "ApCoCoA Users".