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