| 1 |
<html lang="en"> |
|---|
| 2 |
<head> |
|---|
| 3 |
<title>Loading/Unloading Shared Libraries</title> |
|---|
| 4 |
<link rel="stylesheet" type="text/css" href="styles.css"> |
|---|
| 5 |
</head> |
|---|
| 6 |
<body> |
|---|
| 7 |
<hr> |
|---|
| 8 |
<hr> |
|---|
| 9 |
<h2 align="center">Loading/Unloading Shared Libraries</h2> |
|---|
| 10 |
<hr> |
|---|
| 11 |
<hr> |
|---|
| 12 |
<h3>Introduction</h3> |
|---|
| 13 |
All Derelict packages are bindings to C shared libraries. No package in Derelict |
|---|
| 14 |
is designed to work with static C libraries. The interface for loading and |
|---|
| 15 |
unloading shared libraries is the same for all packages in Derelict, so the |
|---|
| 16 |
instructions on this page apply to each package. However, some libraries may have |
|---|
| 17 |
special features that require more than the common loader interface. Any such |
|---|
| 18 |
exceptions will be noted in the documentation for those packages. |
|---|
| 19 |
|
|---|
| 20 |
<h3>Derelict's Common Loader Interface</h3> |
|---|
| 21 |
You are probably already aware of Derelict's package naming convention. Each |
|---|
| 22 |
package name is a combination of 'Derelict' with some form of the name of the |
|---|
| 23 |
library the package binds with. No matter what form of the library name is used, |
|---|
| 24 |
the Derelict package name is the same throughout all documentation and code |
|---|
| 25 |
related to that package. For example, DerelictGL is always referred to as |
|---|
| 26 |
'DerelictGL'. If you aren't sure about a package name, look at the documentation |
|---|
| 27 |
list at the bottom of the |
|---|
| 28 |
<a href="index_a.html">front page</a>. All of the package document titles in |
|---|
| 29 |
that list correlate to Derelict package names. |
|---|
| 30 |
</p><p> |
|---|
| 31 |
Loading and unloading shared libraries is done through a global object declared |
|---|
| 32 |
in each Derelict package. The object is named exactly as the package in which it |
|---|
| 33 |
is declared. The loader interface defines load methods that can be used to load |
|---|
| 34 |
a shared library into memory, and an unload method that can be used to remove |
|---|
| 35 |
the shared library from memory. |
|---|
| 36 |
</p> |
|---|
| 37 |
<h4>Loading</h4> |
|---|
| 38 |
The important thing to remember about loading is that |
|---|
| 39 |
<span class="important">a package's load method must be called before any functions |
|---|
| 40 |
from the bound library can be used</span>. If you tried to use a library function |
|---|
| 41 |
without first calling the load method for that package, you would find yourself |
|---|
| 42 |
with an access violation. The library interface consists of function pointers. |
|---|
| 43 |
The load method pulls the shared library in to memory and points each function |
|---|
| 44 |
pointer to the address of the appropriate function. Until that time, the function |
|---|
| 45 |
pointers are all null. |
|---|
| 46 |
<p> |
|---|
| 47 |
As an example, if you were using DerelictSDL, you would use the following |
|---|
| 48 |
syntax to load the SDL shared library: |
|---|
| 49 |
|
|---|
| 50 |
<pre> |
|---|
| 51 |
DerelictSDL.load(); |
|---|
| 52 |
</pre> |
|---|
| 53 |
|
|---|
| 54 |
From that point onward you would be able to use all SDL functions normally. |
|---|
| 55 |
</p><p> |
|---|
| 56 |
The load method accepts an optional shared library name string parameter that will |
|---|
| 57 |
overload the default search mechanism. For example, on Windows DerelictAL attempts |
|---|
| 58 |
to load "openal32.dll" by default. Some systems have audio drivers that provide |
|---|
| 59 |
a hardware accelerated version of OpenAL, some do not. You may want to ship the |
|---|
| 60 |
OpenAL dll with your app, but renamed to something like "myopenal.dll", or perhaps |
|---|
| 61 |
with the same name but in a subdirectory of the application directory ("al/openal32.dll"). |
|---|
| 62 |
If the <tt>DerelictAL.load()</tt> fails, then you can call |
|---|
| 63 |
<tt>DerelictAL.load("myopenal.dll")</tt> instead. This is important because |
|---|
| 64 |
Windows (and other OSes) will look in the application's directory for a given |
|---|
| 65 |
shared library before looking in system directories. If you were to drop openal32.dll |
|---|
| 66 |
in your application's directory, that version would be loaded every time and any |
|---|
| 67 |
hardware accelerated version in the system directories would be ignored. This |
|---|
| 68 |
technique can be used for every Derelict package, not just DerelictAL. |
|---|
| 69 |
</p><p> |
|---|
| 70 |
Sometimes, loads fail. There are several root causes for this, the end result |
|---|
| 71 |
being either that the system couldn't find the shared library or that one of the |
|---|
| 72 |
functions Derelict expected to find in the library wasn't there. In either |
|---|
| 73 |
case, the load method will throw an exception. You can read more about Derelict |
|---|
| 74 |
exceptions in the documentation for <a href="util.html">DerelictUtil</a>. |
|---|
| 75 |
You can also learn how to bypass some exceptions in the documentation on |
|---|
| 76 |
Derelict's <a href="selective.html">selective loading system</a>. |
|---|
| 77 |
</p> |
|---|
| 78 |
|
|---|
| 79 |
<h4>Unloading</h4> |
|---|
| 80 |
Unloading a shared library uses the same syntax as when loading, but you call |
|---|
| 81 |
the <tt>unload</tt> method instead: |
|---|
| 82 |
|
|---|
| 83 |
<pre> |
|---|
| 84 |
DerelictSDL.unload(); |
|---|
| 85 |
</pre> |
|---|
| 86 |
|
|---|
| 87 |
In normal usage of Derelict, <span class="important">you do not need to unload |
|---|
| 88 |
any of the shared libraries</span>. Derelict will do this for you automatically. |
|---|
| 89 |
The <tt>unload</tt> method is provided as a convenience for those who want to implement |
|---|
| 90 |
hot swapping or want to free up memory if a library is no longer needed during |
|---|
| 91 |
execution. |
|---|
| 92 |
</p> |
|---|
| 93 |
|
|---|
| 94 |
<h4>Loader Properties</h4> |
|---|
| 95 |
Loaders have two properties you may find useful. The <tt>loaded</tt> property |
|---|
| 96 |
is true if the loader's shared library has been loaded, false if not. The <tt>libName</tt> |
|---|
| 97 |
property will return the name of the shared library that has been loaded, or <tt>null</tt> |
|---|
| 98 |
when the loader has no library loaded. |
|---|
| 99 |
|
|---|
| 100 |
<h4>Note For Linux/Mac Users</h4> |
|---|
| 101 |
On Linux and Mac, there is one additional dependency that must be linked into |
|---|
| 102 |
your executable: libdl. On Windows, the functions used to load shared libraries |
|---|
| 103 |
are part of the core libraries linked automatically during compilation. On other |
|---|
| 104 |
platforms, this is not the case. So any time you compile a Derelict application |
|---|
| 105 |
on Linux or Mac, regardless of whether you are using DMD or GDC, you must link |
|---|
| 106 |
to libdl. Otherwise, compilation will fail with symbol errors. |
|---|
| 107 |
|
|---|
| 108 |
|
|---|
| 109 |
</body> |
|---|
| 110 |
</html> |
|---|
