ld, -rpath documentation seems incomplete

["John Gabriele" <jmg3000 at gmail dot com>]

I originally posted this to gnu.gcc.help, but after looking into it
more, I think it belongs here instead. (With a couple of tiny edits,)
I wrote:

I'm working on a creating a shared object that acts like a plug-in --
actually, it's a Ruby extension module (a .so file), but that's not
terribly relevant here. The idea is, the code makes calls to hooks in
the Ruby interpreter, after it's been loaded by the interpreter at
runtime.

When building my .so, the link command looks like this:

gcc -shared  -L'/opt/ruby-1.8.4/lib' -Wl,-R'/opt/ruby-1.8.4/lib' -o
mytest.so MyTest.o -ldl -lcrypt -lm -lc

I see that ld is being passed -R'/opt/ruby-1.8.4/lib', and that this
option seems to be the key to allowing there to be unresolved symbols
in mytest.so -- so that they get resolved once this shared lib is
loaded by ruby at runtime.

When I look up the docs on -R, they say that when you pass a directory
name, it acts like the -rpath option. Cool. So I check the docs on
-rpath. It says that the directory name given is used by the runtime
dynamic linker to find libs. (The docs also go on to talk about it
being "used when locating shared objects which are needed by shared
objects explicitly included in the link". I don't think that 2nd part
applies here though.)

The problem is, the ld docs don't seem to describe what actually
happens. I'd heard elsewhere that what the -rpath option is *really*
doing is telling ld to allow unresolved symbols in the .so file --
such that they can be looked up at run-time. This is the crucial point
I believe, and if accurate, should go into the ld docs.

Thanks,
---John