root/trunk/docs/index_a.html

Revision 260, 10.8 kB (checked in by aldacron, 2 years ago)

[Docs]
* added a Dependencies section to index_a.html, so that the libdl dependency is more obvious
* touched up index_a.html a bit

  • Property svn:mime-type set to text/html
  • Property svn:mim-type set to text/html
Line 
1 <html lang="en">
2 <head>
3     <title>Derelict Documentation</title>
4     <link rel="stylesheet" type="text/css" href="styles.css">
5 </head>
6 <body>
7 <hr>
8 <hr>
9 <h2 align="center">Front Page</h2>
10 <hr>
11 <hr>
12 <h3>Introduction</h3>
13 Derelict is a collection of D bindings to C shared (dynamic) libraries which are
14 useful for multimedia applications, with a heavy bias toward libraries commonly
15 used in game development. Derelict currently includes bindings for the following
16 libraries:
17
18 <ul>
19 <li><a href="http://www.ode.org/">Open Dynamics Engine</a></li>
20 <li><a href="http://www.openal.org/">OpenAL</a></li>
21 <li><a href="http://www.opengl.org/">OpenGL</a></li>
22 <li><a href="http://rush3d.com/reference/opengl-bluebook-1.0/ch06.html">OpenGL Utility Library (GLU)</a></li>
23 <li><a href="http://openil.sourceforge.net/">DevIL, ILU, and ILUT</a></li>
24 <li><a href="http://www.libsdl.org/">SDL</a></li>
25 <li><a href="http://www.libsdl.org/projects/SDL_image/">SDL_image</a></li>
26 <li><a href="http://www.libsdl.org/projects/SDL_mixer/">SDL_mixer</a></li>
27 <li><a href="http://www.libsdl.org/projects/SDL_net/">SDL_net</a></li>
28 <li><a href="http://www.libsdl.org/projects/SDL_ttf/">SDL_ttf</a></li>
29 <li><a href="http://www.freetype.org/">FreeType</a></li>
30 <li><a href="http://www.xiph.org/ogg">libogg</a></li>
31 <li><a href="http://www.xiph.org/vorbis">libvorbis</a></li>
32 </ul>
33 <p>
34
35 Over the past few years, D bindings for some of the above libraries have been created
36 as part of other projects. One thing all of the existing bindings had in common
37 was that they required users to statically link to import libraries. None of the
38 bindings were designed to allow a user to manually load libraries via an operating
39 system API (such as LoadLibrary/GetProcAddress on Windows, or libdl on Linux and
40 Mac). Linking to a shared library's static import library is not a bad thing,
41 but having the option to load a shared library manually allows the developer a
42 great deal more flexibility - particularly when things go wrong.
43
44 </p>
45 <h4>Static Import Issues</h4>
46 One issue with static import libraries is that of the object format used. If the
47 D linker on your platform does not support a particular object format for a library
48 you wish to link with, then you need to go through the step of converting the
49 library to the proper format, or, if the library's source is available, compile
50 the library with a compiler that outputs the proper object format (currently,
51 this is only an issue on Windows when using the DMD tools). This is only a minor
52 annoyance that can usually be handled once and forgotten about until you upgrade
53 to a new version of a library. But, there is a more serious issue with static
54 import libraries in that they lack flexibility and robustness.
55 </p><p>
56 When an application is linked with a static import library, the shared library
57 from which the import library derives will be loaded automatically at application
58 startup. If the shared library is missing or corrupt, then the application will
59 fail to load and the operating system will display an error message to the user.
60 This could also occur if the only version of a shared library available on the
61 user's system is older than the version of the static import library. The
62 error message displayed may not be very user-friendly. Some users who do not
63 understand the concepts behind the error message could become frustrated with
64 you, the developer, and may even view you as unprofessional. When it comes to
65 software, there is no such thing as one-size-fits-all. A large company like Adobe,
66 or someone making free software, may not find such errors a concern. A solo
67 game developer attempting to sell casual games online may find such errors costly.
68 For that developer, having the option to avoid such errors is ideal.
69 </p>
70 <h4>Derelict's Solution</h4>
71 Derelict solves both potential problems by eliminating the requirement of a
72 static import library. Instead, Derelict handles the loading of shared libraries
73 manually after the application has already started. This gives a great amount of
74 flexibility to the application developer. Object file formats are irrelevant, as
75 the application will be linked to a D library rather than a C library. The case
76 of missing or corrupt shared libraries can be handled gracefully in an application
77 specific manner. For example, the application could display an error message
78 that details how to solve the problem, or where to go for technical support. But
79 the benefits don't stop there.
80 </p><p>
81 With Derelict, shared libraries can be loaded and unloaded at will. When you
82 consider that each shared library, when loaded, consumes system resources, then
83 you might find it beneficial to only load the library when it is needed and
84 not before. Some applications could also benefit from a hot-swap system. For
85 example, a game might have a generic audio interface with implementations
86 for both OpenAL and SDL_mixer, and provide a means for players to switch between
87 the two at runtime. Derelict makes implementing such a feature a snap.
88 </p>
89 <h4>Special Features</h4>
90 Derelict goes one step further and allows selective loading of shared library
91 symbols. This gives you the freedom to do things like falling back to older
92 versions of a shared library when a current version is not available. For example,
93 if a particular Derelict package is setup to load version 2 of a shared library,
94 but your application does not use any exported functions or variables that are
95 specific to version 2, then you can use selective symbol loading to allow
96 version 1 of the shared library to be loaded if version 2 fails to load.
97 </p><p>
98 While some of the functionality that Derelict provides is baked into the process
99 of manually loading libraries, other features (such as <a href="selective.html">
100 selective symbol exceptions</a>) are provided through the DerelictUtil package.
101 As a side effect, all Derelict packages have an implicit dependency upon DerelictUtil.
102 This means that when compiling any individual packages, DerelictUtil <b>must</b>
103 be available on the import path, and when linking, DerelictUtil <b>must be</b>
104 linked into the application. See the <a href="util.html">DerelictUtil documentation</a>
105 for more details.
106
107 <h4>The Future</h4>
108 Derelict has grown quite a bit since its humble beginnnings as OpenGL and SDL
109 bindings created by one guy as a hobby project. Users have contributed a number
110 of packages, bugfixes and improvements over the project's lifetime. The build
111 system has been overhauled twice. The internal loading system has been rewritten
112 twice. Other packages are waiting in the wings to be added somewhere down the
113 road. Most importantly, the user community has continued to grow.
114 <p>
115 More users also means more demand for new Derelict packages. Rather than adding
116 just any old binding to Derelict, there must be some guidelines in place to
117 keep things under control. The following (loose) criteria are used to determine
118 the fitness of bindings to any given library for inclusion in the Derelict trunk:
119
120 <ul>
121 <li>Is the library useful for games or other multimedia applications?</li>
122 <li>Is the library in widespread use or at least well-known in its domain?</li>
123 <li>Is the library too complex to easily port to D?</li>
124 <li>Does the library abstract away cross-platform APIs?</li>
125 <li>Is the library easily compiled into DLL form?</li>
126 <li>Does the library use a non-viral license that would not require commercial
127 applications to release source code?</li>
128 </ul>
129
130 If "yes" can be answered to all of the above questions for any given library,
131 its chances for inclusion into Derelict are high. While the given criteria are
132 not etched in stone and anything is possible, you can be certain that no library
133 licensed under the <a href="http://www.gnu.org/copyleft/gpl.html">GPL</a> will
134 ever make it into Derelict. Keeping Derelict free of viral licenses like the GPL
135 allows users to make their own decision about whether or not to open their source,
136 rather than being forced to do so.
137 </p><p>
138 If a particular library you want to use is not currently in Derelict, you can
139 feel free to make a Derelictified binding for the library and request on the
140 <a href="http://www.dsource.org/forums/viewforum.php?f=19&sid=d6f86cfb804d7c8727af1f58cd327d2c">Derelict
141 forums</a> that it be included. Even if your work is not officially added
142 to the trunk, you are still free to use it yourself or even distribute it as
143 a separate package from your own website. Read <a href="derelictify.html">Aldacron's
144 Guide to Derelictification</a> for instructions on how to create your own
145 Derelict packages.
146 </p>
147 <h4>Dependencies</h4>
148 On Windows, Derelict has no external dependencies for compilation other than the Win32 API
149 libraries which are linked in automatically. However, on Unix-like platforms (such as
150 Linux and Mac) there is a dependency upon libdl. Therefore, any time you compile Derelict
151 application on such a platform you must link with libdl. Failure to do so will result in
152 linker errors.
153 <p>
154 Internally, every Derelict package depends upon DerelictUtil. Some packages have other internal
155 dependencies as well (for example, DerelictGLU depends upon DerelictGL). Dependent packages
156 must be on the import path when you compile the Derelict libraries (an optional step) and
157 when compiling Derelict applications. Additionally, dependencies must be linked or compiled with
158 Derelict applications. More details can be found in the documentation below.
159 </p>
160 <h4>The Docs</h4>
161 The documents linked in the first section below give a general overview of
162 Derelict, explaining functionality common to all Derelict packages. The
163 documents linked in the second section give details on building and using
164 specific packages.
165 </p>
166 <h3>General Documentation</h3>
167 <ul>
168 <li><a href="terms.html">Terminology</a></li>
169 <li><a href="loading.html">Loading/Unloading Shared Libraries</a></li>
170 <li><a href="selective.html">Selective Symbol Loading</a></li>
171 <li><a href="build.html">Building Derelict</a></li>
172 <li><a href="derelictify.html">Aldacron's Guide to Derelictification</a></li>
173 <li><a href="credit.html">Contributors</a></li>
174 </ul>
175 <h3>Package Documentation</h3>
176 <ul>
177 <li><a href="al.html">DerelictAL</a></li>
178 <li><a href="gl.html">DerelictGL</a></li>
179 <li><a href="glfw.html">DerelictGLFW</a></li>
180 <li><a href="il.html">DerelictIL</a></li>
181 <li><a href="ilu.html">DerelictILU</a></li>
182 <li><a href="ilut.html">DerelictILUT</a></li>
183 <li><a href="ode.html">DerelictODE</a></li>
184 <li><a href="sdl.html">DerelictSDL</a></li>
185 <li><a href="sdlimg.html">DerelictSDLImage</a></li>
186 <li><a href="sdlmix.html">DerelictSDLMixer</a></li>
187 <li><a href="sdlnet.html">DerelictSDLNet</a></li>
188 <li><a href="sdlttf.html">DerelictSDLttf</a></li>
189 <li><a href="ft.html">DerelictFT</a></li>
190 <li><a href="ogg.html">DerelictOgg</a></li>
191 <li><a href="vorbis.html">DerelictVorbis</a></li>
192 <li><a href="util.html">DerelictUtil</a></li>
193
194 </ul>
195 </body>
196 </html>
Note: See TracBrowser for help on using the browser.