[Rd] Forthcoming change in the API of the Matrix package

[Douglas Bates]

Martin and I will soon release a new version of the Matrix package
with a modified API.  This will affect the authors of any packages
that use calls to the C function R_GetCCallable to directly access C
functions in the DLL or shared object object in the libs directory of
the Matrix package.  (If you didn't understand that last sentence,
relax - it means that you can ignore this message.)

We strongly suspect that I am the only such author (this mechanism is
used in the lme4 package) and, because I was the one who made the API
change, I do indeed know about it.  However, if others do use this
mechanism for, say, accessing functions in the CHOLMOD sparse matrix C
library, you should be aware of this.

The current version of the Matrix package is 0.99875-3.  This version
exports the C functions according to the old API.  The next version
will be 0.999375-0 using the new API.  I will soon upload version
0.99875-3 of the lme4 package that depends on

Matrix(<= 0.99875-3)

Version 0.999375-0 of the lme4 package will depend on

Matrix(>= 0.999375-0)

The changes in the API are in the functions as_cholmod_sparse,
as_cholmod_dense and as_cholmod_factor.  After the change the first
argument will be a pointer to a struct of the appropriate return type
(i.e. the first argument in as_cholmod_sparse is a cholmod_sparse *
and the second argument is an SEXP).  This allows the calling function
to handle both the allocation and the freeing of the storage for the
struct.

Also the new API provides several macros and typedefs for such
pointers to structs.

The development version of the Matrix package is available at

https://svn.R-project.org/R-packages/branches/Matrix-APIchange/

The corresponding  version of the lme4 package is at

https://svn.R-project.org/R-packages/branches/gappy-lmer/