/Modules/_ctypes/darwin/README

 1dlcompat for Darwin
 2=========================
 3
 4This is dlcompat, a small library that emulates the dlopen()
 5interface on top of Darwin's dyld API.
 6
 7dlcompat allows loading a ".dylib" library (as long as the RTLD_LOCAL 
 8flag isn't passed to dlopen()). It can be configured to yield a warning 
 9when trying to close it (dynamic libraries cannot currently be unloaded).
10
11It automatically searches for modules in several directories when no 
12absolute path is specified and the module is not found in the current 
13directory.
14
15The paths searched are those specified in the environment variables
16LD_LIBRARY_PATH and DYLD_LIBRARY_PATH plus /lib, /usr/local/lib and 
17/usr/lib or the path specified in the environment variable 
18DYLD_FALLBACK_LIBRARY_PATH.
19
20In the default install the behavior of dlsym is to automatically prepend
21an underscore to passed in symbol names, this allows easier porting of
22applications which were written specifically for ELF based lifeforms.
23
24Installation
25--------------
26Type:
27	./configure
28	make
29	sudo make install
30
31This will compile the source file, generate both a static and shared
32library called libdl and install it into /usr/local/lib. The header
33file dlfcn.h will be installed in /usr/local/include.
34
35If you want to place the files somewhere else, run
36
37  make clean
38  ./configure --prefix=<prefix>
39  make
40  sudo make install
41
42where <prefix> is the hierarchy you want to install into, e.g. /usr
43for /usr/lib and /usr/include (_NOT_ recommended!).
44
45To enable debugging output (useful for me), run
46
47  make clean
48  ./configure --enable-debug
49  make
50  sudo make install
51  
52If you want old dlcompat style behavior of not prepending the underscore
53on calls to dlsym then type:
54
55  make clean
56  ./configure --enable-fink
57  make
58  sudo make install
59
60Usage
61-------
62Software that uses GNU autoconf will likely check for a library called
63libdl, that's why I named it that way. For software that doesn't find
64the library on its own, you must add a '-ldl' to the appropriate
65Makefile (or environment) variable, usually LIBS.
66
67If you installed dlcompat into a directory other than /usr/local/lib,
68you must tell the compiler where to find it. Add '-L<prefix>/lib' to
69LDFLAGS (or CFLAGS) and '-I<prefix>/include' to CPPFLAGS (or CFLAGS).
70
71Notes
72-----
73If you are writing new software and plan to have Mac OX X compatibility you
74should look at the dyld api's in /usr/include/mach-o/dyld.h, rather than
75using dlcompat, using the native api's is the supported method of loading
76dynamically on Mac OS X, if you want an small example, look at dlfcn_simple.c,
77which should help get you started.
78
79Also note that the functions in dlcompat are not thread safe, and while it is not
80POSIX spec compliant, it is about as close to compliance as it is going to get though.
81
82You can always get the latest version from opendarwin cvs:
83
84  cvs -d :pserver:anonymous@anoncvs.opendarwin.org:/cvs/od login
85  cvs -z3 -d :pserver:anonymous@anoncvs.opendarwin.org:/cvs/od \
86               co -d dlcompat proj/dlcompat
87
88
89It is hoped that this library will be useful, and as bug free as possible, if you find
90any bugs please let us know about them so they can be fixed.
91
92Please send bug reports to Peter O'Gorman <ogorman@users.sourceforge.net>
93
94Thanks.
95