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