8142972d87
effect is to move away from DocBook SGML and DJ Delorie's doctool and toward pure DocBook XSL. (There remains just one use of doctool, and we have plans for replacing it, too.) See ChangeLog for details.
146 lines
4.8 KiB
XML
146 lines
4.8 KiB
XML
<?xml version="1.0" encoding='UTF-8'?>
|
|
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
|
|
<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>This page gives only a few simple examples of gcc's DLL-building
|
|
capabilities. To begin an exploration of the many additional options,
|
|
see the gcc documentation and website, currently at
|
|
<ulink url="http://gcc.gnu.org/">http://gcc.gnu.org/</ulink>
|
|
</para>
|
|
|
|
<para>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>Fortunately, with the latest gcc and binutils the process for building a dll
|
|
is now pretty simple. Say you want to build this minimal function in mydll.c:</para>
|
|
|
|
<screen>
|
|
#include <stdio.h>
|
|
|
|
int
|
|
hello()
|
|
{
|
|
printf ("Hello World!\n");
|
|
}
|
|
</screen>
|
|
|
|
<para>First compile mydll.c to object code:</para>
|
|
|
|
<screen>gcc -c mydll.c</screen>
|
|
|
|
<para>Then, tell gcc that it is building a shared library:</para>
|
|
|
|
<screen>gcc -shared -o mydll.dll mydll.o</screen>
|
|
|
|
<para>
|
|
That's it! To finish up the example, you can now link to the
|
|
dll with a simple program:
|
|
</para>
|
|
|
|
<screen>
|
|
int
|
|
main ()
|
|
{
|
|
hello ();
|
|
}
|
|
</screen>
|
|
|
|
<para>
|
|
Then link to your dll with a command like:
|
|
</para>
|
|
|
|
<screen>gcc -o myprog myprog.c -L./ -lmydll</screen>
|
|
|
|
<para>However, if you are building a dll as an export library,
|
|
you will probably want to use the complete syntax:</para>
|
|
|
|
<screen>gcc -shared -o cyg${module}.dll \
|
|
-Wl,--out-implib=lib${module}.dll.a \
|
|
-Wl,--export-all-symbols \
|
|
-Wl,--enable-auto-import \
|
|
-Wl,--whole-archive ${old_libs} \
|
|
-Wl,--no-whole-archive ${dependency_libs}</screen>
|
|
|
|
<para>
|
|
The name of your library is <literal>${module}</literal>, prefixed with
|
|
<literal>cyg</literal> for the DLL and <literal>lib</literal> for the
|
|
import library. Cygwin DLLs use the <literal>cyg</literal> prefix to
|
|
differentiate them from native-Windows MinGW DLLs, see
|
|
<ulink url="http://mingw.org">the MinGW website</ulink> for more details.
|
|
<literal>${old_libs}</literal> are all
|
|
your object files, bundled together in static libs or single object
|
|
files and the <literal>${dependency_libs}</literal> are import libs you
|
|
need to link against, e.g
|
|
<userinput>'-lpng -lz -L/usr/local/special -lmyspeciallib'</userinput>.
|
|
</para>
|
|
</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. If you have the source to compile
|
|
the DLL, see <xref linkend="dll-build"></xref> for details on having
|
|
<filename>gcc</filename> build one for you. If you do not have the
|
|
source or a supplied working import library, 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>
|