diff options
Diffstat (limited to 'winsup/doc/dll.sgml')
-rw-r--r-- | winsup/doc/dll.sgml | 120 |
1 files changed, 0 insertions, 120 deletions
diff --git a/winsup/doc/dll.sgml b/winsup/doc/dll.sgml deleted file mode 100644 index 274f129..0000000 --- a/winsup/doc/dll.sgml +++ /dev/null @@ -1,120 +0,0 @@ -<sect1 id="dll"><title>Building and Using DLLs</title> - -<para>DLLs are Dynamic Link Libraries, which means that they're linked -into your program at run time instead of build time. There are three -parts to a DLL:</para> - -<itemizedlist spacing="compact"> -<listitem><para> the exports </para></listitem> -<listitem><para> the code and data </para></listitem> -<listitem><para> the import library </para></listitem> -</itemizedlist> - -<para>The code and data are the parts you write - functions, -variables, etc. All these are merged together, like if you were -building one big object files, and put into the dll. They are not -put into your .exe at all.</para> - -<para>The exports contains a list of functions and variables that the -dll makes available to other programs. Think of this as the list of -"global" symbols, the rest being hidden. Normally, you'd create this -list by hand with a text editor, but it's possible to do it -automatically from the list of functions in your code. The -<filename>dlltool</filename> program creates the exports section of -the dll from your text file of exported symbols.</para> - -<para>The import library is a regular UNIX-like -<filename>.a</filename> library, but it only contains the tiny bit of -information needed to tell the OS how your program interacts with -("imports") the dll. This information is linked into your -<filename>.exe</filename>. This is also generated by -<filename>dlltool</filename>.</para> - -<sect2 id="dll-build"><title>Building DLLs</title> - -<para>OK, let's go through a simple example of how to build a dll. -For this example, we'll use a single file -<filename>myprog.c</filename> for the program -(<filename>myprog.exe</filename>) and a single file -<filename>mydll.c</filename> for the contents of the dll -(<filename>mydll.dll</filename>).</para> - -<para>Now compile everything to objects:</para> - -<screen> -gcc -c myprog.c -gcc -c mydll.c -</screen> - -<para>Unfortunately, the process for building a dll is, well, convoluted. -You have to run five commands, like this:</para> - -<screen> -gcc -s -Wl,--base-file,mydll.base -o mydll.dll mydll.o -Wl,-e,_mydll_init@12 -dlltool --base-file mydll.base --def mydll.def --output-exp mydll.exp --dllname mydll.dll -gcc -s -Wl,--base-file,mydll.base,mydll.exp -o mydll.dll mydll.o -Wl,-e,_mydll_init@12 -dlltool --base-file mydll.base --def mydll.def --output-exp mydll.exp --dllname mydll.dll -gcc -Wl,mydll.exp -o mydll.dll mydll.o -Wl,-e,_mydll_init@12 -</screen> - -<para>The extra steps give <filename>dlltool</filename> the -opportunity to generate the extra sections (exports and relocation) -that a dll needs. After this, you build the import library:</para> - -<screen> -dlltool --def mydll.def --dllname mydll.dll --output-lib mydll.a -</screen> - -<para>Now, when you build your program, you link against the import -library:</para> - -<screen> -gcc -o myprog myprog.o mydll.a -</screen> - -<para>Note that we linked with <command>-e _mydll_init@12</command>. -This tells the OS what the DLL's "entry point" is, and this is a -special function that coordinates bringing the dll to life withing the -OS. The minimum function looks like this:</para> - -<screen> -#include <windows.h> - -int WINAPI -mydll_init(HANDLE h, DWORD reason, void *foo) -{ - return 1; -} -</screen> - -</sect2> - -<sect2 id="dll-link"><title>Linking Against DLLs</title> - -<para>If you have an existing DLL already, you need to build a -Cygwin-compatible import library (The supplied ones should work, but -you might not have them) to link against. Unfortunately, there is not -yet any tool to do this automatically. However, you can get most of -the way by creating a .def file with these commands (you might need to -do this in <filename>bash</filename> for the quoting to work -correctly):</para> - -<screen> -echo EXPORTS > foo.def -nm foo.dll | grep ' T _' | sed 's/.* T _//' >> foo.def -</screen> - -<para>Note that this will only work if the DLL is not stripped. -Otherwise you will get an error message: "No symbols in -foo.dll".</para> - -<para>Once you have the <filename>.def</filename> file, you can create -an import library from it like this:</para> - -<screen> -dlltool --def foo.def --dllname foo.dll --output-lib foo.a -</screen> - -</sect2> - -</sect1> |