mingw/doc/a2dll/a2dll.html

   1 <html>
   2 <head>
   3 <title>
   4 a2dll: An utility (to help) to convert static library into Win32 DLL
   5 </title>
   6 </head>
   7 <body>
   8 <h1>
   9 a2dll: An utility (to help) to convert static library into Win32 DLL
  10 </h1>
  11 <h2>
  12 Synopsis
  13 </h2>
  14 <p>
  15 a2dll is shell script (see <a href="#requirements">requirements</a>) to
  16 automotize process of converting existing static libraries (produced
  17 by gnu-win32 tools, of course) into DLL. First of all, yes it's possible:
  18 if you have binary static distribution of some library (i.e. library
  19 itself and its headers), that's all you need to convert it to DLL and
  20 use in your programs. Read <a href="static2dll_howto.txt">HOWTO</a> for
  21 underlying magic. So, you may not waste time if you need DLL: just
  22 grab existing static distribution and convert. Also, you may use it to
  23 build Win32 DLL of your library. Also, until GNU libtool will allow
  24 seamless building of Win32 DLLs, you may build static lib (what
  25 libtool of course supports) and then convert it to DLL.
  26 <blockquote>
  27 <tt>
  28 a2dll &lt;static_lib> [-o &lt;dll_name>] [&lt;linker_flags>] [--relink]
  29 </tt>
  30 </blockquote>
  31 where:
  32 <dl>
  33 <dt>
  34 <tt>&lt;static_lib></tt>
  35 </dt>
  36 <dd>
  37 Static library you want to convert
  38 </dd>
  39 <dt>
  40 <tt>-o &lt;dll_name></tt>
  41 </dt>
  42 <dd>
  43 Name of resulting dll. If not given, three first chars of input
  44 name are stripped and <tt>.a</tt> suffix replaced with <tt>.dll</tt> .
  45 So, from '<tt>libfoo.a</tt>' you'll get '<tt>foo.dll</tt>'.
  46 </dd>
  47 <dt>
  48 <tt>&lt;linker_flags></tt>
  49 </dt>
  50 <dd>
  51 Linker flags:
  52 <ul>
  53 <li>Use '<tt>-s</tt>' to get library without debugging symbols and information.
  54 <li>Use '<tt>--driver-name=&lt;name></tt>' to link library with specified
  55 linker (well, compiler, to be precise). For example, for C++ library use
  56 <tt>--driver-name=g++</tt> .
  57 <li>You should list all libraries on which your library depends with
  58 <tt>-l</tt> switches and directories they are reside in with <tt>-L</tt>
  59 switches. For example, if your library uses PCRE library you just built and
  60 not yet installed, use something like <tt>-L../pcre -lpcre</tt>
  61 </ul>
  62 </dd>
  63 <dt>
  64 <tt>--relink</tt>
  65 </dt>
  66 <dd>
  67 Skip exploding library stage (see below). Use this flag to continue
  68 process after some error occured.
  69 </dd>
  70 </dl>
  71 </p>
  72
  73 <h2>
  74 Performing
  75 </h2>
  76
  77 <p>
  78 a2dll works in following way:
  79 <ol>
  80 <li>If you did not specify <tt>--relink</tt> option,
  81 explodes source library under newly-created <tt>.dll</tt> subdirectory.
  82
  83 <li>Links all resulting objects into DLL with exporting all non-static
  84 symbols. On this stage, link errors
  85 (such as underfined symbols) may occur. In such case, a2dll terminates
  86 and all linker messages are available in '<tt>ld.err</tt>' file. You
  87 should correct errors (mostly by finding out additional
  88 dependecies, but sometimes by deleting 'superfluos' objects under .dll)
  89 and re-run a2dll with all the options you gave it before,
  90 plus new dependencies, plus <tt>--relink</tt> flag. You may need to
  91 repeat this several times.
  92
  93 <li>Renames original static library with suffix <tt>.static</tt> .
  94
  95 <li>Creates import library for produced DLL with the name of original
  96 static library.
  97
  98 <li>Check whether DLL exports data symbols. If no, congratulations,
  99 you've done. However, if some present, it lists all of them in file
 100 '<tt>&lt;dll_name>.data</tt>' . Presense of such symbols generally
 101 means that you should patch library's headers to mark those symbols
 102 as dll-imported. But don't hurry with that, first, do following:
 103 <ol>
 104 <li>Look into <tt>&lt;dll_name>.data</tt> file. If all what you see
 105 is something like '<tt>internal_counter_of_bogons</tt>' or
 106 '<tt>_ksdauso</tt>', don't worry - those symbols are hardly part of
 107 external interface of the library.
 108 <li>If all you need is to link your application against that
 109 library, try it. If it succeeds, congratulation.
 110 <li>Only if above is failed, or you are going to distribute produced
 111 library, so you need to be sure that everything is ok, proceed with
 112 marking symbols in headers. Read <a href="static2dll_howto.txt">Static2DLL
 113 HOWTO</a> for more information on suggested ways of doing this. Use
 114 '<tt>grep -f <tt>&lt;dll_name>.data</tt> *.h</tt>' command to find
 115 out where offending symbols defined in library headers.
 116 </ol>
 117 </ol>
 118 </p>
 119
 120 <h2>
 121 Examples
 122 </h2>
 123 <p>
 124 Since converting static libraries to DLLs is not fully automated and
 125 formal process, some experience with it is required. Learing
 126 by example is known to be one of the efficient way of communicating
 127 experince, so I would like to provide some realistic examples of
 128 converting statics to DLLs with the help of a2dll.
 129 </p>
 130
 131 <h3>
 132 Zlib
 133 </h3>
 134 <p>
 135 Build libz.a . Now, run '<tt>a2dll libz.a</tt>'. It builds cleanly,
 136 but warns us about data symbols. Let's look at them:
 137 <blockquote>
 138 <pre>
 139 inflate_mask
 140 z_errmsg
 141 </pre>
 142 </blockquote>
 143 What they could be. The first one is probably some internal variable,
 144 while second is probably array of error messages. As we know, zlib
 145 provides functional way of getting error messages, something like. So
 146 our hypothesis is that job's done. Let's prove it:
 147 '<tt>grep -f z.dll.data zlib.h</tt>'. Yes, we're right: no mentioning
 148 of those symbols in interface header file.
 149 </p>
 150
 151 <h3>
 152 libstdc++
 153 </h3>
 154 <p>
 155 I've got an idea to DLLize libstdc++ coming with my mingw32 distribution.
 156 '<tt>a2dll "libstdc++.a"</tt>'. Note that we don't use
 157 <tt>--driver-name=g++</tt> - that option need to be used when we link
 158 something <i>against</i> libstdc++ . But when we link libstdc++
 159 <i>itself</i>, we need libc (whatever it is in mingw32), nothing else.
 160 But, process aborts due to linker errors. <tt>ld.err</tt> tells us:
 161 <blockquote>
 162 <pre>
 163 strerror.o(.text+0x303): undefined reference to `sys_nerr'
 164 vfork.o(.text+0x7): undefined reference to `fork'
 165 waitpid.o(.text+0x15): undefined reference to `wait'
 166 </pre>
 167 </blockquote>
 168 Well, strerror, vfork, waitpid are libc functions, what they do in
 169 libstdc++? Probably, stubs, delete them and
 170 '<tt>a2dll "libstdc++.a" --relink</tt>'. Of course,
 171 <tt>stdc++.dll.data</tt> is here. Looking into it, I may tell you
 172 that everything starting with '<tt>__ti&lt;digit></tt>' is RTTI
 173 internal data structures and everything starting with
 174 '<tt>_vt$</tt>' is virtual tables (use c++filt if in doubt),
 175 you can leave them alone.
 176 (If so, why I don't filter them? Because "you can leave them alone"
 177 is hypothesis for now, I haven't linked too much C++ libraries to
 178 be sure). From the rest, there's stuff starting
 179 with '<tt>_IO_</tt>'. That's probably some internal variables, let's
 180 don't do anything about them, unless we'll be forced to. Than, as
 181 c++filt shows, there're some static members of templated classes. Darkness.
 182 Forget for now. Than, there's '<tt>io_defs__</tt>'. Does your C++ application
 183 reference something like that? Mine not. So, what is left? Our four
 184 happy friends, <tt>cin, cout, cerr,</tt> and <tt>clog</tt>. Do mark them as
 185 __declspec(dllimport) in <tt>iostream.h</tt>.
 186 </p>
 187
 188 <h3>
 189 Some C++ library
 190 </h3>
 191 <p>
 192 Suppose we have following file:
 193 <pre>
 194 #include &lt;iostream.h>
 195
 196 void foo()
 197 {
 198   cout&lt;&lt;"hi!"&lt;&lt;endl;
 199 }
 200 </pre>
 201 and want to turn it into DLL. Create static liba.a from it. Now,
 202 '<tt>a2dll liba.a --driver-name=g++</tt>'. Well, our DLL contains
 203 single function, why then it complains about data symbols? Oh, it's
 204 those stupid RTTI structures. Next time, compile with <tt>-fno-rtti</tt> unless
 205 you really need it, ok? Ditto for <tt>-fno-exceptions</tt> .
 206 </p>
 207
 208 <h2>
 209 <a name="requirements">
 210 Requirements
 211 </h2>
 212 <p>
 213 a2dll requires POSIX shell (<tt>sh</tt>) to run. It is developed and
 214 tested with <tt>ash</tt> from
 215 <a href="http://pw32.sourceforge.net">PW32</a> distribution. Additionally,
 216 a2dll requires following utilities to perform its tasks:
 217 <ul>
 218 <li>GNU fileutils: mkdir, mv, rm
 219 <li>GNU textutils: wc
 220 <li>GNU grep
 221 <li>GNU awk
 222 <li>GNU binutils: dllwrap, dlltool (and the rest of binutils and gcc, of course)
 223 <li>pexports, an utility to dump symbols exported by dll. You'll need a
 224 version 0.43 or above, capable of distinguishing between code and data symbols, as one
 225 from <a href="http://www.is.lg.ua/~paul/devel/binutils.html">here</a>.
 226 </ul>
 227 </p>
 228 <hr noshade>
 229 <i><a href="mailto:Paul.Sokolovsky@technologist.com">Paul Sokolovsky</a></i>
 230 </body>
 231 </html>