winelib-porting.sgml 6.12 KB
Newer Older
1 2 3 4 5 6 7
  <chapter id="portability-issues">
    <title id="portability-issues.title">Portability issues</title>

    <sect1 id="unicode">
      <title id="unicode.title">Unicode</title>

      <para>
8
	The <literal>wchar_t</literal> type has different standard
9 10
	sizes in Unix (4 bytes) and Windows (2 bytes). You need a
        recent gcc version (2.9.7 or later) that supports the
11 12
	<parameter>-fshort-wchar</parameter> option to set the
	size of <literal>wchar_t</literal> to the one expected
13
	by Windows applications. 
14 15 16 17 18
      </para>

      <para>
        If you are using Unicode and you want to be able to use
        standard library calls (e.g. <function>wcslen</function>,
19
        <function>wsprintf</function>), then you must use
20 21 22 23 24 25 26 27 28
        the msvcrt runtime library instead of glibc. The functions in
        glibc will not work correctly with 16 bit strings.
      </para>
    </sect1>

    <sect1 id="C-library">
      <title id="C-library.title">C library</title>

      <para>
29 30
        There are 2 choices available to you regarding which C library
        to use: the native glibc C library or the msvcrt C library.
31 32 33 34 35 36 37 38
      </para>

      <para>
        Note that under Wine, the crtdll library is implemented using
        msvcrt, so there is no benefit in trying to use it.
      </para>
      <para>
        Using glibc in general has the lowest overhead, but this is
39 40
        really only important for file I/O, as many of the functions
        in msvcrt are simply resolved to glibc.
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
      </para>
      <para>
        To use glibc, you don't need to make changes to your
        application; it should work straight away. There are a few
        situations in which using glibc is not possible:
      </para>
      <orderedlist>
        <listitem>
          <para>
            Your application uses Win32 and C library unicode
            functions.
          </para>
        </listitem>
        <listitem>
          <para>
            Your application uses MS specific calls like
            <function>beginthread()</function>,
            <function>loadlibrary()</function>, etc.
          </para>
        </listitem>
        <listitem>
          <para>
            You rely on the precise semantics of the calls, for
            example, returning <literal>-1</literal> rather than
            non-zero. More likely, your application will rely on calls
            like <function>fopen()</function> taking a Windows path
            rather than a Unix one.
          </para>
        </listitem>
      </orderedlist>
      <para>
        In these cases you should use msvcrt to provide your C runtime
73
        calls.
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
      </para>

      <programlisting>import msvcrt.dll</programlisting>

      <para>
        to your applications <filename>.spec</filename> file. This
        will cause <command>winebuild</command> to resolve your c
        library calls to <filename>msvcrt.dll</filename>. Many simple
        calls which behave the same have been specified as
        non-importable from msvcrt; in these cases
        <command>winebuild</command> will not resolve them and the
        standard linker <command>ld</command> will link to the glibc
        version instead.
      </para>
      <para>
        In order to avoid warnings in C (and potential errors in C++)
        from not having prototypes, you may need to use a set of MS
91
        compatible header files. These are scheduled for inclusion
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
        into Wine but at the time of writing are not available. Until
        they are, you can try prototyping the functions you need, or
        just live with the warnings.
      </para>
      <para>
        If you have a set of include files (or when they are available
        in Wine), you need to use the <parameter>-isystem
        "include_path"</parameter> flag to gcc to tell it to use your
        headers in preference to the local system headers.
      </para>
      <para>
        To use option 3, add the names of any symbols that you don't
        want to use from msvcrt into your applications
        <filename>.spec</filename> file. For example, if you wanted
        the MS specific functions, but not file I/O, you could have a
        list like:
      </para>

      <programlisting>@ignore = ( fopen fclose fwrite fread fputs fgets )</programlisting>
      <para>
        Obviously, the complete list would be much longer. Remember
        too that some functions are implemented with an underscore in
        their name and <function>#define</function>d to that name in
        the MS headers. So you may need to find out the name by
Tom Wickline's avatar
Tom Wickline committed
116
        examining <filename>dlls/msvcrt/msvcrt.spec</filename> to get
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
        the correct name for your <function>@ignore</function> entry.
      </para>
    </sect1>

    <sect1 id="porting-compiling">
      <title id="porting-compiling.title">Compiling Problems</title>
      <para>
        If you get undefined references to Win32 API calls when
        building your application: if you have a VC++
        <filename>.dsp</filename> file, check it for all the
        <filename>.lib</filename> files it imports, and add them to
        your applications <filename>.spec</filename>
        file. <command>winebuild</command> gives you a warning for
        unused imports so you can delete the ones you don't need
        later. Failing that, just import all the DLL's you can find in
        the <filename>dlls/</filename> directory of the Wine source
        tree.
      </para>
      <para>
        If you are missing GUIDs at the link stage, add
        <parameter>-lwine_uuid</parameter> to the link line.
      </para>
      <para>
Tom Wickline's avatar
Tom Wickline committed
140
        gcc is more strict than VC++, especially when compiling
141
        C++. This may require you to add casts to your C++ to prevent
Tom Wickline's avatar
Tom Wickline committed
142
        overloading ambiguities between similar types (such as two
143 144 145 146 147
        overloads that take int and char respectively).
      </para>
      <para>
        If you come across a difference between the Windows headers
        and Wine's that breaks compilation, try asking for help on
148
        <email>wine-devel@winehq.org</email>.
149 150 151 152 153 154 155 156
      </para>
    </sect1>

  </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
157
sgml-parent-document:("winelib-user.sgml" "book" "chapter" "")
158 159
End:
-->