[Rd] Use of PACKAGE= argument in .C etc calls

[Prof Brian Ripley]

As from R 2.0.0, R CMD check has not flagged .C etc calls without a 
PACKAGE argument in packages with a namespace.  Unfortunately that was 
based on too optimistic assumptions.

1) The mechanism to find the DLL from the namespace only works if the DLL 
is declared via a useDynLib declaration in NAMESPACE (and only if there is 
one such declaration).  This is checked in R-devel.

2) In 2.1.1, the mechanism only finds the DLL correctly for functions 
defined at the top level in a namespace, and not for example for functions 
defined inside functions or as S4 methods.  There is an enhanced 
mechanism in R-devel.

3) Prior to 2.1.1, a bug meant that the mechanism often found the 
incorrect namespace, and there was not mechanism at all prior to 2.0.0 (I 
believe).

For compatibility with 2.1.x and earlier a PACKAGE= argument is needed in 
many more calls than are flagged by R-devel's 'check'.  To check this, 
use

> library(tools)
> checkFF("my_package", verbose=TRUE)

for example:

> checkFF("mgcv", verbose=TRUE)
.C("construct_cr", ...): OK
.C("predict_tprs", ...): OK
.C("MinimumSeparation", ...): OK
.C("update_beta", ...): MISSING but in a function in a namespace
.C("update_beta", ...): MISSING but in a function in a namespace
.C("magic", ...): OK
.C("mgcv", ...): OK
.C("RMonoCon", ...): OK
.C("RPCLS", ...): OK
.C("construct_cr", ...): OK
.C("construct_tprs", ...): OK
.C("RuniqueCombs", ...): OK

where the qualified MISSING reports need attention.

Botton line: always use a PACKAGE= argument unless you are only intending 
your package to be used with (pre-)2.2.0 or later.

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595