Added missing prototypes for some implemented functions.
[wine] / documentation / winelib-intro.sgml
1   <chapter id="winelib-introduction">
2     <title id="introduction.title">Winelib Introduction</title>
3
4     <sect1 id="winelib-whatis">
5       <title>What is Winelib?</title>
6
7       <para>
8         Winelib is a development toolkit which allows you to compile your
9         Windows applications on Unix.
10       </para>
11       <para>
12         Most of Winelib's code consists of the Win32 API implementation.
13         Fortunately this part is 100 percent shared with Wine. The remainder
14         consists of Windows compatible headers and tools like the resource
15         compiler (and even these are used when compiling Wine).
16       </para>
17       <para>
18         Thanks to the above, Winelib supports most C and C++ 32bit source code,
19         resource and message files, and can generate graphical or console
20         applications as well as dynamic libraries.
21       </para>
22       <para>
23         What is not supported is 16bit source code as the types it depends on
24         (especially segmented pointers) are not supported by Unix compilers.
25         Also missing are some of the more exotic features of Microsoft's
26         compiler like native COM support and structured exception handling.
27         So you may need to perform some modifications in your code when
28         recompiling your application with Winelib. This guide is here to help
29         you in this task.
30       </para>
31       <para>
32         What you gain by recompiling your application with Winelib is the
33         ability to make calls to Unix APIs, directly from your
34         Windows source code. This allows for a better integration with the
35         Unix environment than is allowed by running an unmodified Windows
36         application running in Wine. Another benefit is that a Winelib
37         application can relatively easily be recompiled on a non-Intel
38         architecture and run there without the need for a slow software
39         emulation of the processor.
40       </para>
41     </sect1>
42
43     <sect1 id="winelib-requirements">
44       <title id="requirements.title">System requirements</title>
45       <para>
46         The requirements for Winelib are similar to those for Wine.
47       </para>
48       <para>
49         Basically if you can run Wine on your computer then you can run
50         Winelib. But the converse is not true. You can also build Winelib
51         and Winelib applications on platforms not supported by Wine,
52         typically platforms with a non i386 processor. But this is still
53         pretty much uncharted territory. It would be more reasonable to
54         target one of the more mundane i386-based platforms first.
55       </para>
56       <para>
57         The main difference is that the compiler becomes much more important.
58         It is highly recommended that you use gcc, g++, and the GNU binutils. 
59         The more recent your gcc compiler the better.
60         For any serious amount of code you should not consider anything older
61         than gcc 2.95.2. The latest gcc snapshots contain some useful bug
62         fixes and much better support for anonymous structs and unions. This
63         can help reduce the number of changes you have to do in your code but
64         these are not stable releases of the compiler so you may not want to
65         use them in production.
66       </para>
67     </sect1>
68
69     <sect1 id="winelib-getting-started">
70       <title id="getting-started.title">Getting Started</title>
71
72       <sect2 id="winemaker-introduction">
73         <title id="winemaker-introduction.title">Winemaker introduction</title>
74         <para>
75           So what is needed to compile a Windows application with Winelib?
76           Well, it really depends on the complexity of your application but
77           here are some issues that are shared by all applications:
78         </para>
79         <itemizedlist>
80           <listitem>
81             <para>
82               the case of your files may be bad. For example they could be
83               in all caps: <filename>HELLO.C</filename>. It's not very nice to
84               work with and probably not what you intended.
85             </para>
86           </listitem>
87           <listitem>
88             <para>
89               then the case of the filenames in your include statements may be
90               wrong: maybe they include 'Windows.h' instead of 'windows.h'.
91             </para>
92           </listitem>
93           <listitem>
94             <para>
95               your include statements may use '\' instead of '/'. '\' is not
96               recognized by Unix compilers while '/' is recognized in both
97               environments.
98             </para>
99           </listitem>
100           <listitem>
101             <para>
102               you will need to perform the usual Dos to Unix text file conversion
103               otherwise you'll get in trouble when the compiler considers that
104               your '\' is not at the end of the line since it is followed by a
105               pesky carriage return.
106             </para>
107           </listitem>
108           <listitem>
109             <para>
110               you will have to write new makefiles.
111             </para>
112           </listitem>
113         </itemizedlist>
114
115         <para>
116           The best way to take care of all these issues is to use winemaker.
117         </para>
118         <para>
119           Winemaker is a perl script which is designed to help you bootstrap
120           the conversion of your Windows projects to Winelib. In order to do
121           this it will go analyze your code, fixing the issues listed above
122           and generate autoconf-based Makefiles.
123         </para>
124         <para>
125           Let's suppose that Wine/Winelib has been installed in the
126           <filename class="Directory">/usr/local/wine</filename>
127           directory, and that you are already in the top directory of your
128           sources. Then converting your project to Winelib may be as simple
129           as just running the three commands below (note the dot indicating
130           current directory at the end of the first command):
131         </para>
132         <programlisting>
133           $ winemaker --lower-uppercase .
134           $ ./configure --with-wine=/usr/local/wine
135           $ make
136         </programlisting>
137
138         <para>
139           But of course things are not always that simple which is why we have
140           this guide at all.
141         </para>
142       </sect2>
143
144       <sect2 id="winemaker-test">
145         <title id="winemaker-test.title">Test Drive</title>
146
147         <para>
148           Before starting to work on a big project you may want to try to port a
149           small application. The winemine application from the Wine source tree
150           suits well for testing purposes. It can be found in the programs
151           subdirectory. winemine is a simple application, but has a few C,
152           header and resource files.
153         </para>
154         <para>
155           Run <command>make clean</command> in the
156           winemine source directory if it contains results of previous builds.
157           Create a separate directory with name winemine2, so it won't conflict
158           with the Wine copy of the application. Copy the sources of winemine
159           (files *.c, *.h, *.rc) to this directory. Now run the commands,
160           mentioned above from the winemine2 directory:
161         </para>
162         <programlisting>
163           $ winemaker --lower-uppercase .
164           $ ./configure --with-wine=/usr/local/wine
165           $ make
166         </programlisting>
167
168         <para>
169           You are done! Now you can start the application as
170           <command>./winemine2</command>.
171         </para>
172         <para>
173           If you come across problems preparing and building this application
174           this probably means that winemaker utility is broken by some changes
175           in Wine. Try asking for help on <email>wine-devel@winehq.org</email>
176         </para>
177       </sect2>
178
179       <sect2 id="winemaker-guide">
180         <title id="winemaker-guide.title">Step by step guide</title>
181
182         <para>
183           Let's retrace the steps above in more details.
184         </para>
185         <variablelist>
186           <varlistentry>
187             <term><option>Getting the source</option></term>
188             <listitem>
189               <para>
190                 First if you can try to get the sources together with the
191                 executables/libraries that they build. In the current state of
192                 winemaker having these around can help it guess what it is that
193                 your project is trying to build. Later, when it is able to
194                 understand Visual C++ projects, and if you use them, this will
195                 no longer be necessary. Usually the executables and libraries
196                 are in a <filename class="Directory">Release</filename> or
197                 <filename class="Directory">Debug</filename> subdirectory of the
198                 directory where the sources are. So it's best if you can
199                 transfer the source files and either of these directories to
200                 Linux. Note that you don't need to transfer the
201                 <filename>.obj</filename>, <filename>.pch</filename>,
202                 <filename>.sbr</filename> and other files that also reside in
203                 these directories; especially as they tend to be quite big.
204               </para>
205             </listitem>
206           </varlistentry>
207           <varlistentry>
208             <term><option>cd &lt;root_dir&gt;</option></term>
209             <listitem>
210               <para>
211                 Then go to the root directory where are your source files.
212                 Winemaker can deal with a whole directory hierarchy at once so
213                 you don't need to go into a leaf directory, quite the contrary.
214                 Winemaker will automatically generate makefiles in each
215                 directory where one is required, and will generate a global
216                 makefile so that you can rebuild all your executables and
217                 libraries with a single <command>make</command> command.
218               </para>
219             </listitem>
220           </varlistentry>
221           <varlistentry>
222             <term><option>Making the source writable</option></term>
223             <listitem>
224               <para>
225                 Then make sure you have write access to your sources. It may
226                 sound obvious, but if you copied your source files from a
227                 CD-ROM or if they are in Source Safe on Windows, chances are
228                 that they will be read-only.
229                 But Winemaker needs write access so that it can fix them. You
230                 can arrange that by running <command>chmod -R u+w .</command>.
231                 Also you will want to make sure that you have a backup copy of
232                 your sources in case something went horribly wrong, or more
233                 likely, just for reference at a later point. If you use a
234                 version control system you're already covered.
235               </para>
236               <para>
237                 If you have already modified your source files and you want
238                 to make sure that winemaker will not make further changes to
239                 them then you can use the --nosource-fix option to protect
240                 them.
241               </para>
242             </listitem>
243           </varlistentry>
244           <varlistentry>
245             <term><option>Running winemaker</option></term>
246             <listitem>
247               <para>
248                 Then you'll run winemaker. Here are the options you will most
249                 likely want to use. For complete list of options see
250                 the winemaker man page.
251               </para>
252               <variablelist>
253                 <varlistentry>
254                   <term><option>--lower-uppercase</option></term>
255                   <term><option>--lower-all</option></term>
256                   <listitem>
257                     <para>
258                       These options specify how to deal with files, and
259                       directories, that have an 'incorrect' case.
260                       <option>--lower-uppercase</option> specifies they should
261                       only be renamed if their name is all uppercase. So files
262                       that have a mixed case, like 'Hello.c' would not be
263                       renamed. <option>--lower-all</option> will rename any
264                       file. If neither is specified then no file or directory
265                       will be renamed, almost. As you will see
266                       <link linkend="renaming">later</link> winemaker may
267                       still have to rename some files.
268                     </para>
269                   </listitem>
270                 </varlistentry>
271                 <varlistentry>
272                   <term><option>--nobackup</option></term>
273                   <listitem>
274                     <para>
275                       Winemaker normally makes a backup of all the files in which
276                       it does more than the standard Dos to Unix conversion.
277                       But if you already have (handy) copies of these files
278                       elsewhere you may not need these so you should use this
279                       option.
280                     </para>
281                   </listitem>
282                 </varlistentry>
283                 <varlistentry>
284                   <term><option>--dll</option></term>
285                   <term><option>--console</option></term>
286                   <listitem>
287                     <para>
288                       These option lets winemaker know what kind of target you are
289                       building. If you have the windows library in your source
290                       hierarchy then you should not need to specify
291                       <option>--dll</option>. But if you have console executables
292                       then you will need to use the corresponding option.
293                     </para>
294                   </listitem>
295                 </varlistentry>
296                 <varlistentry>
297                   <term><option>--mfc</option></term>
298                   <listitem>
299                     <para>
300                       This option tells winemaker that you are building an MFC
301                       application/library.
302                     </para>
303                   </listitem>
304                 </varlistentry>
305                 <varlistentry>
306                   <term><option>-Dmacro[=defn]</option></term>
307                   <term><option>-Idir</option></term>
308                   <term><option>-Ldir</option></term>
309                   <term><option>-idll</option></term>
310                   <term><option>-llibrary</option></term>
311                   <listitem>
312                     <para>
313                       The <option>-i</option> specifies a Winelib library to
314                       import via the <link linkend="spec-file">spec file</>
315                       mechanism. Contrast this with the <option>-l</option>
316                       which specifies a Unix library to link with. The other
317                       options work the same way they would with a C
318                       compiler. All are applied to all the targets found.
319                       When specifying a directory with either
320                       <option>-I</option> or <option>-L</option>, winemaker
321                       will prefix a relative path with
322                       <literal>$(TOPDIRECTORY)/</literal> so that it is valid
323                       from any of the source directories. You can also use a
324                       variable in the path yourself if you wish (but don't
325                       forget to escape the '$'). For instance you could specify
326                       <literal>-I\$(WINELIB_INCLUDE_ROOT)/msvcrt</literal>.
327                     </para>
328                   </listitem>
329                 </varlistentry>
330               </variablelist>
331               <para>
332                 So your command may finally look like:
333                 <literal>winemaker --lower-uppercase -Imylib/include .</literal>
334               </para>
335             </listitem>
336           </varlistentry>
337           <varlistentry>
338             <term id="renaming"><option>File renaming</option></term>
339             <listitem>
340               <para>
341                 When you execute winemaker it will first rename files to bring
342                 their character case in line with your expectations and so that they can
343                 be processed by the makefiles. This later category implies that
344                 files with a non lowercase extension will be renamed so that the
345                 extension is in lowercase. So, for instance,
346                 <filename>HELLO.C</filename> will be renamed to
347                 <filename>HELLO.c</filename>. Also if a file or directory name
348                 contains a space or a dollar, then this
349                 character will be replaced with an underscore. This is because
350                 these characters cause problems with current versions of autoconf
351                 (2.13) and make (3.79).
352               </para>
353             </listitem>
354           </varlistentry>
355           <varlistentry>
356             <term><option>Source modifications and makefile generation</option></term>
357             <listitem>
358               <para>
359                 winemaker will then proceed to modify the source files so that
360                 they will compile more readily with Winelib. As it does so it
361                 may print warnings when it has to make a guess or identifies a
362                 construct that it cannot correct. Finally it will generate the
363                 autoconf-based makefiles. Once all this is done you can review
364                 the changes that winemaker did to your files by using
365                 <command>diff -uw</command>. For instance:
366                 <command>diff -uw hello.c.bak hello.c</command>
367               </para>
368             </listitem>
369           </varlistentry>
370           <varlistentry>
371             <term><option>Running the configure script</option></term>
372             <listitem>
373               <para>
374                 Before you run <command>make</command> you must run the
375                 autoconf <command>configure</command> script. The goal of this
376                 step is to analyze your system and generate customized
377                 makefiles from the <filename>Makefile.in</filename> files. This
378                 is also when you have to tell where Winelib resides on your
379                 system. If wine is installed in a single directory or you have
380                 the Wine sources compiled somewhere then you can just run
381                 <command>./configure --with-wine=/usr/local/bin</command>
382                 or <command>./configure --with-wine=~/wine</command>
383                 respectively.
384               </para>
385             </listitem>
386           </varlistentry>
387           <varlistentry>
388             <term><option>Running make</option></term>
389             <listitem>
390               <para>
391                 This is a pretty simple step: just type <command>make</command>
392                 and voila, you should have all your executables and libraries.
393                 If this did not work out, then it means that you will have to
394                 read this guide further to:
395                 <itemizedlist>
396                   <listitem>
397                     <para>
398                       review the <filename>Makefile.in</filename> files to
399                       adjust the default compilation and link options set by
400                       winemaker. See the <xref linkend="source-analysis"
401                       endterm="source-analysis.title"> section for some hints.
402                     </para>
403                   </listitem>
404                   <listitem>
405                     <para>
406                       fix the portability issues in your sources. See
407                       <xref linkend="portability-issues"
408                             endterm="portability-issues.title"> for more details.
409                     </para>
410                   </listitem>
411                 </itemizedlist>
412               </para>
413               <para>
414                 If you find yourself modifying the Makefile.in to specify the
415                 location of the Wine header or library files then go back to
416                 the previous step (the configure script) and use the various
417                 --with-wine-* options to specify where they are.
418               </para>
419             </listitem>
420           </varlistentry>
421         </variablelist>
422       </sect2>
423     </sect1>
424   </chapter>
425
426 <!-- Keep this comment at the end of the file
427 Local variables:
428 mode: sgml
429 sgml-parent-document:("winelib-user.sgml" "book" "chapter" "")
430 End:
431 -->