[Rcpp-devel] useDynLib

[Davor Cubranic]

On 31 March 2011 at 3:53 PM, Sean Robert McGuffee wrote:

> This link has a lot of information in it, but I don't understand much
> of it because it seems to be written for people who already
> understand it.

You make a very good point here, and I think it's largely true for most 
of R's documentation. But that's because it's a reference, not a 
tutorial, and succinctness is valued more than hand-holding. That's what 
man pages are, too, btw.

I actually think R-exts should be even more like a reference, or (more 
likely) it should have a reference-like counterpart. Like you showed 
with "useDynLib", important functions are described conversationally, 
instead of formally and exhaustively, they way help pages do for user-
facing functions.

> Under section 1.6: For example, I'm having trouble figuring out the
> meaning of the following terms and or phrases:
> 
> name spaces, management system, package writer, top level package
> directory, name space directives, imports, exports
[...]

I don't mean to be glib, but how do you expect to get anywhere with 
packages when you don't understand basic concepts behind modularity like 
exporting a function so it's callable outside a module? As a first 
resort, look it up on Wikipedia: the article on name spaces ought to 
clear up a few things at least.

A good way to avoid frustration is to read the manual lazily, start your 
code small and build up. For instance, you probably don't know what the 
section 1.6.2 on S3 methods is going on about because you're not using 
S3 classes in your code. if that's the case, fine, you don't need to read 
how to deal with them in the package declarations.

I grant you that some terms are needlessly obfuscated, though. For 
example, "package writer" could have been "package author" -- but, 
honestly, is that really that hard to figure out?

> "There can be one or more useDynLib directives which allows shared
> objects that need to be loaded to be specified in the NAMESPACE
> file.  The directive
> 
>      useDynLib(foo)"
> 
> This also is followed by other inconsistent examples:
> 
> "useDynLib(foo, myRoutine, myOtherRoutine)"
> 
> "myDLL = useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)"

I'm sorry, but after re-reading this section, i don't see any 
inconsistency. There are different ways of calling "useDynLib", but what 
they do is explained in the text. And, back to reading the manual 
lazily, only the first one is used in 99% of the time. I, for one, use 
Rcpp extensively, and never needed (or even known) anything other than 
the very first one form of useDynLib. (And, in all likelihood, might have 
just used whatever Rcpp.package.skeleton put into the NAMESPACE for me.)

> Does anyone have any links to something more like an API of what
> appears to be some type of function called useDynLib?
> In particular, I'm looking to find out what arguments the method
> useDynLib takes with descriptions of their types?

I don't know of one, but can you describe what exactly you're trying to 
do? If all you need is allow the R code in your package to call into a 
dynamic library "mylib.so" that's distributed with the package, it is 
sufficient to have a declaration "useDynLib(mylib)". This will ensure that 
when the package is loaded into the session, the dynamic library will 
also be loaded and ready for calling into with ".Call" and related 
functions.