documentation/winelib-porting.sgml

   1   <chapter id="portability-issues">
   2     <title id="portability-issues.title">Portability issues</title>
   3
   4     <sect1 id="unicode">
   5       <title id="unicode.title">Unicode</title>
   6
   7       <para>
   8         The <literal>wchar_t</literal> type has different standard
   9         sizes in Unix (4 bytes) and Windows (2 bytes). Recent versions
  10         of gcc (2.9.7 or later) support the
  11         <parameter>-fshort-wchar</parameter> option to set the
  12         size of <literal>wchar_t</literal> to the one expected
  13         by Windows applications. Pass this option to every file
  14         that is built.
  15       </para>
  16
  17       <para>
  18         If you are using Unicode and you want to be able to use
  19         standard library calls (e.g. <function>wcslen</function>,
  20         <function>wsprintf</function>), then you must use
  21         the msvcrt runtime library instead of glibc. The functions in
  22         glibc will not work correctly with 16 bit strings.
  23       </para>
  24       <para>
  25         To prevent warnings when declaring a single unicode character
  26         in C, use <function>(WCHAR)L'x'</function>, rather than
  27         <function>__TEXT('x')</function>.  This works on Windows also.
  28       </para>
  29     </sect1>
  30
  31     <sect1 id="C-library">
  32       <title id="C-library.title">C library</title>
  33
  34       <!-- *** Is all of this covered now?  Make sure before deleting ***
  35       <para>
  36         Winelib currently only supports on C library: that of your
  37         compiler.  three solutions: native, mixed or msvcrt except we
  38         only have native right now, using the native C library ->
  39         different behavior: fopen, O_TEXT, unicode support,
  40         reimplement msvcrt
  41       </para>
  42       -->
  43
  44       <para>
  45         There are 2 choices available to you regarding which C library
  46         to use: the native glibc C library or the msvcrt C library.
  47       </para>
  48
  49       <para>
  50         Note that under Wine, the crtdll library is implemented using
  51         msvcrt, so there is no benefit in trying to use it.
  52       </para>
  53       <para>
  54         Using glibc in general has the lowest overhead, but this is
  55         really only important for file I/O, as many of the functions
  56         in msvcrt are simply resolved to glibc.
  57       </para>
  58       <para>
  59         To use glibc, you don't need to make changes to your
  60         application; it should work straight away. There are a few
  61         situations in which using glibc is not possible:
  62       </para>
  63       <orderedlist>
  64         <listitem>
  65           <para>
  66             Your application uses Win32 and C library unicode
  67             functions.
  68           </para>
  69         </listitem>
  70         <listitem>
  71           <para>
  72             Your application uses MS specific calls like
  73             <function>beginthread()</function>,
  74             <function>loadlibrary()</function>, etc.
  75           </para>
  76         </listitem>
  77         <listitem>
  78           <para>
  79             You rely on the precise semantics of the calls, for
  80             example, returning <literal>-1</literal> rather than
  81             non-zero. More likely, your application will rely on calls
  82             like <function>fopen()</function> taking a Windows path
  83             rather than a Unix one.
  84           </para>
  85         </listitem>
  86       </orderedlist>
  87       <para>
  88         In these cases you should use msvcrt to provide your C runtime
  89         calls.
  90       </para>
  91
  92       <programlisting>import msvcrt.dll</programlisting>
  93
  94       <para>
  95         to your applications <filename>.spec</filename> file. This
  96         will cause <command>winebuild</command> to resolve your c
  97         library calls to <filename>msvcrt.dll</filename>. Many simple
  98         calls which behave the same have been specified as
  99         non-importable from msvcrt; in these cases
 100         <command>winebuild</command> will not resolve them and the
 101         standard linker <command>ld</command> will link to the glibc
 102         version instead.
 103       </para>
 104       <para>
 105         In order to avoid warnings in C (and potential errors in C++)
 106         from not having prototypes, you may need to use a set of MS
 107         compatible header files. These are scheduled for inclusion
 108         into Wine but at the time of writing are not available. Until
 109         they are, you can try prototyping the functions you need, or
 110         just live with the warnings.
 111       </para>
 112       <para>
 113         If you have a set of include files (or when they are available
 114         in Wine), you need to use the <parameter>-isystem
 115         "include_path"</parameter> flag to gcc to tell it to use your
 116         headers in preference to the local system headers.
 117       </para>
 118       <para>
 119         To use option 3, add the names of any symbols that you don't
 120         want to use from msvcrt into your applications
 121         <filename>.spec</filename> file. For example, if you wanted
 122         the MS specific functions, but not file I/O, you could have a
 123         list like:
 124       </para>
 125
 126       <programlisting>@ignore = ( fopen fclose fwrite fread fputs fgets )</programlisting>
 127       <para>
 128         Obviously, the complete list would be much longer. Remember
 129         too that some functions are implemented with an underscore in
 130         their name and <function>#define</function>d to that name in
 131         the MS headers. So you may need to find out the name by
 132         examining <filename>dlls/msvcrt/msvcrt.spec</filename> to get
 133         the correct name for your <function>@ignore</function> entry.
 134       </para>
 135     </sect1>
 136
 137     <sect1 id="porting-compiling">
 138       <title id="porting-compiling.title">Compiling Problems</title>
 139       <para>
 140         If you get undefined references to Win32 API calls when
 141         building your application: if you have a VC++
 142         <filename>.dsp</filename> file, check it for all the
 143         <filename>.lib</filename> files it imports, and add them to
 144         your applications <filename>.spec</filename>
 145         file. <command>winebuild</command> gives you a warning for
 146         unused imports so you can delete the ones you don't need
 147         later. Failing that, just import all the DLL's you can find in
 148         the <filename>dlls/</filename> directory of the Wine source
 149         tree.
 150       </para>
 151       <para>
 152         If you are missing GUIDs at the link stage, add
 153         <parameter>-lwine_uuid</parameter> to the link line.
 154       </para>
 155       <para>
 156         gcc is more strict than VC++, especially when compiling
 157         C++. This may require you to add casts to your C++ to prevent
 158         overloading ambiguities between similar types (such as two
 159         overloads that take int and char respectively).
 160       </para>
 161       <para>
 162         If you come across a difference between the Windows headers
 163         and Wine's that breaks compilation, try asking for help on
 164         <email>wine-devel@winehq.com</email>.
 165       </para>
 166     </sect1>
 167
 168     <sect1 id="init-problems">
 169       <title id="init-problems.title">Initialization problems</title>
 170       <para>
 171         Initialization problems occur when the application calls the Win32 API
 172         before Winelib has been initialized. How can this happen?
 173       </para>
 174       <para>
 175         Winelib is initialized by the application's <function>main</function>
 176         before it calls the regular <function>WinMain</function>. But, in C++,
 177         the constructors of static class variables are called before the
 178         <function>main</function> (by the module's initializer). So if such
 179         a constructor makes calls to the Win32 API, Winelib will not be
 180         initialized at the time of the call and you may get a crash. This
 181         problem is much more frequent in C++ because of these class
 182         constructors but could also, at least in theory, happen in C if you
 183         were to specify an initializer making calls to Winelib. But of
 184         course, now that you are aware of this problem you won't do it :-).
 185       </para>
 186       <para>
 187         Further compounding the problem is the fact that Linux's (GNU's?)
 188         current dynamic library loader does not call the module
 189         initializers in their dependency order. So even if Winelib were to
 190         have its own initializer there would be no guarantee that it would be
 191         called before the initializer of the library containing this static
 192         variable. Finally even if the variable is in a library that your
 193         application links with, that library's initializer may be called
 194         before Winelib has been initialized. One such library is the MFC.
 195       </para>
 196       <para>
 197         The current workaround is to move all the application's code in a
 198         library and to use a small Winelib application to dynamically load
 199         this library. Tus the initialization sequence becomes:
 200       </para>
 201       <itemizedlist>
 202         <listitem>
 203           <para>
 204             the wrapper application starts.
 205           </para>
 206         </listitem>
 207         <listitem>
 208           <para>
 209             its empty initializer is run.
 210           </para>
 211         </listitem>
 212         <listitem>
 213           <para>
 214             its <function>main</function> is run. Its first task is to
 215             initialize Winelib.
 216           </para>
 217         </listitem>
 218         <listitem>
 219           <para>
 220             it then loads the application's main library, plus all its
 221             dependent libraries.
 222           </para>
 223         </listitem>
 224         <listitem>
 225           <para>
 226             which triggers the execution of all these libraries initializers
 227             in some unknown order. But all is fine because Winelib has
 228             already been initialized anyway.
 229           </para>
 230         </listitem>
 231         <listitem>
 232           <para>
 233             finally the main function calls the <function>WinMain</function>
 234             of the application's library.
 235           </para>
 236         </listitem>
 237       </itemizedlist>
 238       <para>
 239         This may sound complex but Winemaker makes it simple. Just specify
 240         <option>--wrap</option> or <option>--mfc</option> on the command line
 241         and it will adapt its makefiles to build the wrapper and the
 242         application library.
 243       </para>
 244     </sect1>
 245
 246     <sect1 id="com-support">
 247       <title id="com-support.title">VC's native COM support</title>
 248       <para>
 249         don't use it,
 250         guide on how to replace it with normal C++ code (yes, how???):
 251         extracting a .h and .lib from a COM DLL
 252         Can '-fno-rtti' be of some use or even required?
 253       </para>
 254     </sect1>
 255
 256     <sect1 id="SEH">
 257       <title id="SEH.title">SEH</title>
 258       <para>
 259         how to modify the syntax so that it works both with gcc's macros and Wine's macros,
 260         is it even possible?
 261       </para>
 262     </sect1>
 263
 264     <sect1 id="others">
 265       <title id="others.title">Others</title>
 266       <para>
 267         -fpermissive and -fno-for-scope,
 268         maybe other options
 269       </para>
 270     </sect1>
 271   </chapter>
 272
 273 <!-- Keep this comment at the end of the file
 274 Local variables:
 275 mode: sgml
 276 sgml-parent-document:("winelib-user.sgml" "book" "chapter" "")
 277 End:
 278 -->