Update FreeBSD infos.
[wine] / 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.org</email>.
149       </para>
150     </sect1>
151
152   </chapter>
153
154 <!-- Keep this comment at the end of the file
155 Local variables:
156 mode: sgml
157 sgml-parent-document:("winelib-user.sgml" "book" "chapter" "")
158 End:
159 -->