documentation/winelib-porting.sgml

   1   <chapter id="portability-issues">
   2     <title id="portability-issues.title">Portability issues</title>
   3
   4     <sect1 id="anon">
   5       <title id="anon.title">Anonymous unions/structs</title>
   6       <para>
   7         Anonymous structs and unions support depends heavily on the compiler.
   8         The best support is provided by gcc/g++ 2.96 and later. But these
   9         versions of gcc come from the development branch so you may want to
  10         hold off before using them in production. g++ 2.95 supports anonymous
  11         unions but not anonymous structs and gcc 2.95 supports neither. Older
  12         versions of gcc/g++ have no support for either.
  13         since it is anonymous unions that are the most frequent in the
  14         windows headers, you should at least try to use gcc/g++ 2.95.
  15       </para>
  16       <para>
  17         But you are stuck with a compiler that does not support anonymous
  18         structs/unions all is not lost. The Wine headers should detect this
  19         automatically and define <varname>NONAMELESSUNION</varname> /
  20         <varname>NONAMELESSSTRUCT</varname>. Then any anonymous union will
  21         be given a name
  22         <literal>u</literal> or <literal>u2</literal>, <literal>u3</literal>,
  23         etc. to avoid name clashes. You will then have to modify your code to
  24         include those names where appropriate.
  25       </para>
  26       <para>
  27         The name that Wine adds to anonymous unions should match that used
  28         by the Windows headers. So all you have to do to compile your
  29         modified code in Windows is to explicitly define the
  30         <varname>NONAMELESSUNION</varname> macro. Note that it would be wise
  31         to also explicitly define this macro on in your Unix makefile
  32         (<filename>Makefile.in</filename>) to make sure your code will
  33         compile even if the compiler does support anonymous unions.
  34       </para>
  35       <para>
  36         Things are not as nice when dealing with anonymous structs.
  37         Unfortunately the Windows headers make no provisions for compilers
  38         that do not support anonymous structs. So you will need to be more
  39         subtle when modifying your code if you still want it to compile in
  40         Windows. Here's a way to do it:
  41       </para>
  42       <programlisting>
  43 #ifdef WINELIB
  44 #define ANONS .s
  45 #else
  46 #define ANONS
  47 #endif
  48
  49 . . .
  50
  51 {
  52 SYSTEM_INFO si;
  53 GetSystemInfo(&amp;si);
  54 printf("Processor architecture=%d\n",si ANONS .wProcessorArchitecture);
  55 }
  56       </programlisting>
  57       <para>
  58         You may put the <literal>#define</literal> directive directly in the
  59         source if only few files are impacted. Otherwise it's probably best
  60         to put it in one of your project's widely used headers.
  61         Fortunately usage of an anonymous struct is much rarer than usage of
  62         an anonymous union so these modifications should not be too much work.
  63       </para>
  64     </sect1>
  65
  66     <sect1 id="unicode">
  67       <title id="unicode.title">Unicode</title>
  68
  69       <para>
  70         Because gcc and glibc use 4 byte unicode characters, the
  71         compiler intrinsic <literal>L"foo"</literal> generates unicode
  72         strings which cannot be used by Winelib (Win32 code expects 16
  73         bit unicode characters). There are 3 workarounds for this:
  74       </para>
  75
  76       <orderedlist>
  77         <listitem>
  78           <para>
  79             Use the latest gcc version (2.9.7 or later), and pass the
  80             <parameter>-fshort-wchar</parameter> option to every file
  81             that is built.
  82           </para>
  83         </listitem>
  84         <listitem>
  85           <para>
  86             Use the <function>__TEXT("foo")</function> macro, define
  87             <constant>WINE_UNICODE_REWRITE</constant> for each file
  88             that is built, and add
  89             <parameter>-fwritable-strings</parameter> to the compiler
  90             command line. You should replace all occurances of
  91             <type>wchar_t</type> with <type>WCHAR</type> also, since
  92             <type>wchar_t</type> is the native (32 bit) type. These
  93             changes allow Wine to modify the native unicode strings
  94             created by the compiler in place, so that they are 16 bit
  95             by the time any functions get to use them. This scheme
  96             works with older versions of gcc (2.95.x+).
  97           </para>
  98         </listitem>
  99         <listitem>
 100           <para>
 101             Use the compiler default, but don't call any Win32 unicode
 102             function without converting the strings first!
 103           </para>
 104         </listitem>
 105       </orderedlist>
 106
 107       <para>
 108         If you are using Unicode and you want to be able to use
 109         standard library calls (e.g. <function>wcslen</function>,
 110         <function>wsprintf</function>) as well as Win32 unicode calls
 111         (API functions ending in W, or having
 112         <constant>_UNICODE</constant> defined), then you should use
 113         the msvcrt runtime library instead of glibc. The functions in
 114         glibc will not work correctly with 16 bit strings.
 115       </para>
 116       <para>
 117         If you need a Unicode string even when
 118         _<constant>UNICODE</constant> isn't defined, use
 119         <function>WINE_UNICODE_TEXT("foo")</function>. This will need
 120         to be wrapped in <function>#ifdef WINELIB</function> to
 121         prevent breaking your source for windows compiles.
 122       </para>
 123       <para>
 124         To prevent warnings when declaring a single unicode character
 125         in C, use <function>(WCHAR)L'x'</function>, rather than
 126         <function>__TEXT('x')</function>.  This works on Windows also.
 127       </para>
 128     </sect1>
 129
 130     <sect1 id="C-library">
 131       <title id="C-library.title">C library</title>
 132
 133       <!-- *** Is all of this covered now?  Make sure before deleting ***
 134       <para>
 135         Winelib currently only supports on C library: that of your
 136         compiler.  three solutions: native, mixed or msvcrt except we
 137         only have native right now, using the native C library ->
 138         different behavior: fopen, O_TEXT, unicode support,
 139         reimplement msvcrt
 140       </para>
 141       -->
 142
 143       <para>
 144         There are 3 choices available to you regarding which C library
 145         to use:
 146       </para>
 147
 148       <orderedlist>
 149         <listitem>
 150           <para>
 151             Use the glibc native C library.
 152           </para>
 153         </listitem>
 154         <listitem>
 155           <para>
 156             Use the msvcrt C library.
 157           </para>
 158         </listitem>
 159         <listitem>
 160           <para>
 161             Use a custom mixture of both.
 162           </para>
 163         </listitem>
 164       </orderedlist>
 165
 166       <para>
 167         Note that under Wine, the crtdll library is implemented using
 168         msvcrt, so there is no benefit in trying to use it.
 169       </para>
 170       <para>
 171         Using glibc in general has the lowest overhead, but this is
 172         really only important for file I/O. Many of the functions in
 173         msvcrt are simply resolved to glibc, so in reality options 2
 174         and 3 are fairly similar choices.
 175       </para>
 176       <para>
 177         To use glibc, you don't need to make changes to your
 178         application; it should work straight away. There are a few
 179         situations in which using glibc is not possible:
 180       </para>
 181       <orderedlist>
 182         <listitem>
 183           <para>
 184             Your application uses Win32 and C library unicode
 185             functions.
 186           </para>
 187         </listitem>
 188         <listitem>
 189           <para>
 190             Your application uses MS specific calls like
 191             <function>beginthread()</function>,
 192             <function>loadlibrary()</function>, etc.
 193           </para>
 194         </listitem>
 195         <listitem>
 196           <para>
 197             You rely on the precise semantics of the calls, for
 198             example, returning <literal>-1</literal> rather than
 199             non-zero. More likely, your application will rely on calls
 200             like <function>fopen()</function> taking a Windows path
 201             rather than a Unix one.
 202           </para>
 203         </listitem>
 204       </orderedlist>
 205       <para>
 206         In these cases you should use msvcrt to provide your C runtime
 207         calls. To do this, add a line:
 208       </para>
 209
 210       <programlisting>import msvcrt.dll</programlisting>
 211
 212       <para>
 213         to your applications <filename>.spec</filename> file. This
 214         will cause <command>winebuild</command> to resolve your c
 215         library calls to <filename>msvcrt.dll</filename>. Many simple
 216         calls which behave the same have been specified as
 217         non-importable from msvcrt; in these cases
 218         <command>winebuild</command> will not resolve them and the
 219         standard linker <command>ld</command> will link to the glibc
 220         version instead.
 221       </para>
 222       <para>
 223         In order to avoid warnings in C (and potential errors in C++)
 224         from not having prototypes, you may need to use a set of MS
 225         compatable header files. These are scheduled for inclusion
 226         into Wine but at the time of writing are not available. Until
 227         they are, you can try prototyping the functions you need, or
 228         just live with the warnings.
 229       </para>
 230       <para>
 231         If you have a set of include files (or when they are available
 232         in Wine), you need to use the <parameter>-isystem
 233         "include_path"</parameter> flag to gcc to tell it to use your
 234         headers in preference to the local system headers.
 235       </para>
 236       <para>
 237         To use option 3, add the names of any symbols that you don't
 238         want to use from msvcrt into your applications
 239         <filename>.spec</filename> file. For example, if you wanted
 240         the MS specific functions, but not file I/O, you could have a
 241         list like:
 242       </para>
 243
 244       <programlisting>@ignore = ( fopen fclose fwrite fread fputs fgets )</programlisting>
 245       <para>
 246         Obviously, the complete list would be much longer. Remember
 247         too that some functions are implemented with an underscore in
 248         their name and <function>#define</function>d to that name in
 249         the MS headers. So you may need to find out the name by
 250         examing <filename>dlls/msvcrt/msvcrt.spec</filename> to get
 251         the correct name for your <function>@ignore</function> entry.
 252       </para>
 253     </sect1>
 254
 255     <sect1 id="porting-compiling">
 256       <title id="porting-compiling.title">Compiling Problems</title>
 257       <para>
 258         If you get undefined references to Win32 API calls when
 259         building your application: if you have a VC++
 260         <filename>.dsp</filename> file, check it for all the
 261         <filename>.lib</filename> files it imports, and add them to
 262         your applications <filename>.spec</filename>
 263         file. <command>winebuild</command> gives you a warning for
 264         unused imports so you can delete the ones you don't need
 265         later. Failing that, just import all the DLL's you can find in
 266         the <filename>dlls/</filename> directory of the Wine source
 267         tree.
 268       </para>
 269       <para>
 270         If you are missing GUIDs at the link stage, add
 271         <parameter>-lwine_uuid</parameter> to the link line.
 272       </para>
 273       <para>
 274         gcc is more strict than VC++, especially whan compiling
 275         C++. This may require you to add casts to your C++ to prevent
 276         overloading abiguities between similar types (such as two
 277         overloads that take int and char respectively).
 278       </para>
 279       <para>
 280         If you come across a difference between the Windows headers
 281         and Wine's that breaks compilation, try asking for help on
 282         <email>wine-devel@winehq.com</email>.
 283       </para>
 284     </sect1>
 285
 286     <sect1 id="init-problems">
 287       <title id="init-problems.title">Initialization problems</title>
 288       <para>
 289         Initialization problems occur when the application calls the Win32 API
 290         before Winelib has been initialized. How can this happen?
 291       </para>
 292       <para>
 293         Winelib is initialized by the application's <function>main</function>
 294         before it calls the regular <function>WinMain</function>. But, in C++,
 295         the constructors of static class variables are called before the
 296         <function>main</function> (by the module's initializer). So if such
 297         a constructor makes calls to the Win32 API, Winelib will not be
 298         initialized at the time of the call and you may get a crash. This
 299         problem is much more frequent in C++ because of these class
 300         constructors but could also, at least in theory, happen in C if you
 301         were to specify an initializer making calls to Winelib. But of
 302         course, now that you are aware of this problem you won't do it :-).
 303       </para>
 304       <para>
 305         Further compounding the problem is the fact that Linux's (GNU's?)
 306         current dynamic library loader does not call the module
 307         initializers in their dependency order. So even if Winelib were to
 308         have its own initializer there would be no garantee that it would be
 309         called before the initializer of the library containing this static
 310         variable. Finally even if the variable is in a library that your
 311         application links with, that library's initializer may be called
 312         before Winelib has been initialized. One such library is the MFC.
 313       </para>
 314       <para>
 315         The current workaround is to move all the application's code in a
 316         library and to use a small Winelib application to dynamically load
 317         this library. Tus the initialization sequence becomes:
 318       </para>
 319       <itemizedlist>
 320         <listitem>
 321           <para>
 322             the wrapper application starts.
 323           </para>
 324         </listitem>
 325         <listitem>
 326           <para>
 327             its empty initializer is run.
 328           </para>
 329         </listitem>
 330         <listitem>
 331           <para>
 332             its <function>main</function> is run. Its first task is to
 333             initialize Winelib.
 334           </para>
 335         </listitem>
 336         <listitem>
 337           <para>
 338             it then loads the application's main library, plus all its
 339             dependent libraries.
 340           </para>
 341         </listitem>
 342         <listitem>
 343           <para>
 344             which triggers the execution of all these libraries initializers
 345             in some unknown order. But all is fine because Winelib has
 346             already been initialized anyway.
 347           </para>
 348         </listitem>
 349         <listitem>
 350           <para>
 351             finally the main function calls the <function>WinMain</function>
 352             of the application's library.
 353           </para>
 354         </listitem>
 355       </itemizedlist>
 356       <para>
 357         This may sound complex but Winemaker makes it simple. Just specify
 358         <option>--wrap</option> or <option>--mfc</option> on the command line
 359         and it will adapt its makefiles to build the wrapper and the
 360         application library.
 361       </para>
 362     </sect1>
 363
 364     <sect1 id="com-support">
 365       <title id="com-support.title">VC's native COM support</title>
 366       <para>
 367         don't use it,
 368         guide on how to replace it with normal C++ code (yes, how???):
 369         extracting a .h and .lib from a COM DLL
 370         Can '-fno-rtti' be of some use or even required?
 371       </para>
 372     </sect1>
 373
 374     <sect1 id="SEH">
 375       <title id="SEH.title">SEH</title>
 376       <para>
 377         how to modify the syntax so that it works both with gcc's macros and Wine's macros,
 378         is it even possible?
 379       </para>
 380     </sect1>
 381
 382     <sect1 id="others">
 383       <title id="others.title">Others</title>
 384       <para>
 385         -fpermissive and -fno-for-scope,
 386         maybe other options
 387       </para>
 388     </sect1>
 389   </chapter>
 390
 391 <!-- Keep this comment at the end of the file
 392 Local variables:
 393 mode: sgml
 394 sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
 395 End:
 396 -->