| blob | 199e5144c170a43177137f42ffe32d6a7a11d763 |
4 <sect1>
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 runnning 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>
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 an uncharted territory. It would be more reasonable to
54 first 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++,
59 and the GNU binutils. 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>
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
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>
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
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:
130 </para>
131 <programlisting>
132 $ winemaker --lower-uppercase .
133 $ ./configure --with-wine=/usr/local/wine
134 $ make
135 </programlisting>
137 <para>
138 But of course things are not always that simple which is why we have
139 this guide at all.
140 </para>
141 </sect2>
146 <para>
147 Let's retrace the steps above in more details.
148 </para>
149 <variablelist>
150 <varlistentry>
152 <listitem>
153 <para>
154 First if you can try to get the sources together with the
155 executables/libraries that they build. In the current state of
156 winemaker having these around can help it guess what it is that
157 your project is trying to build. Later, when it is able to
158 understand Visual C++ projects, and if you use them, this will
159 no longer be necessary. Usually the executables and libraries
162 directory where the sources are. So it's best if you can
163 transfer the source files and either of these directories to
164 Linux. Note that you don't need to transfer the
167 these directories; especially as they tend to be quite big.
168 </para>
169 </listitem>
170 </varlistentry>
171 <varlistentry>
173 <listitem>
174 <para>
175 Then go to the root directory where are your source files.
176 Winemaker can deal with a whole directory hierarchy at once so
177 you don't need to go into a leaf directory, quite the contrary.
178 Winemaker will automatically generate makefiles in each
179 directory where one is required, and will generate a global
180 makefile so that you can rebuild all your executables and
182 </para>
183 </listitem>
184 </varlistentry>
185 <varlistentry>
187 <listitem>
188 <para>
189 Then make sure you have write access to your sources. It may
190 sound obvious, but if you copied your source files from a
191 CD-ROM or if they are in Source Safe on Windows, chances are
192 that they will be read-only.
193 But Winemaker needs write access so that it can fix them. You
195 Also you will want to make sure that you have a backup copy of
196 your sources in case something went horribly wrong, or more
197 likely, just for reference at a later point. If you use a
198 version control system you're already covered.
199 </para>
200 <para>
201 If you have already modified your source files and you want
202 to make sure that winemaker will not make further changes to
203 them then you can use the --nosource-fix option to protect
204 them.
205 </para>
206 </listitem>
207 </varlistentry>
208 <varlistentry>
210 <listitem>
211 <para>
212 Then you'll run winemaker. Here are the options you will most
213 likely want to use.
214 </para>
215 <variablelist>
216 <varlistentry>
219 <listitem>
220 <para>
221 These options specify how to deal with files, and
222 directories, that have an 'incorrect' case.
224 only be renamed if their name is all uppercase. So files
225 that have a mixed case, like 'Hello.c' would not be
227 file. If neither is specified then no file or directory
228 will be renamed, almost. As you will see
230 still have to rename some files.
231 </para>
232 </listitem>
233 </varlistentry>
234 <varlistentry>
236 <listitem>
237 <para>
238 Winemaker normally makes a backup of all the files in which
239 it does more than the standard Dos to Unix conversion.
240 But if you already have (handy) copies of these files
241 elsewhere you may not need these so you should use this
242 option.
243 </para>
244 </listitem>
245 </varlistentry>
246 <varlistentry>
249 <listitem>
250 <para>
251 These option lets winemaker know what kind of target you are
252 building. If you have the windows library in your source
253 hierarchy then you should not need to specify
255 then you will need to use the corresponding option.
256 </para>
257 </listitem>
258 </varlistentry>
259 <varlistentry>
261 <listitem>
262 <para>
263 This option tells winemaker that you are building an MFC
264 application/library.
265 </para>
266 </listitem>
267 </varlistentry>
268 <varlistentry>
274 <listitem>
275 <para>
279 which specifies a Unix library to link with. The other
280 options work the same way they would with a C
281 compiler. All are applied to all the targets found.
282 When specifying a directory with either
284 will prefix a relative path with
286 from any of the source directories. You can also use a
287 variable in the path yourself if you wish (but don't
288 forget to escape the '$'). For instance you could specify
290 </para>
291 </listitem>
292 </varlistentry>
293 </variablelist>
294 <para>
295 So your command may finally look like:
297 </para>
298 </listitem>
299 </varlistentry>
300 <varlistentry>
302 <listitem>
303 <para>
304 When you execute winemaker it will first rename files to bring
305 their character case in line with your expectations and so that they can
306 be processed by the makefiles. This later category implies that
307 files with a non lowercase extension will be renamed so that the
308 extension is in lowercase. So, for instance,
311 contains a space or a dollar, then this
312 character will be replaced with an underscore. This is because
313 these characters cause problems with current versions of autoconf
315 </para>
316 </listitem>
317 </varlistentry>
318 <varlistentry>
320 <listitem>
321 <para>
322 winemaker will then proceed to modify the source files so that
323 they will compile more readily with Winelib. As it does so it
324 may print warnings when it has to make a guess or identifies a
325 construct that it cannot correct. Finally it will generate the
326 autoconf-based makefiles. Once all this is done you can review
327 the changes that winemaker did to your files by using
330 </para>
331 </listitem>
332 </varlistentry>
333 <varlistentry>
335 <listitem>
336 <para>
339 step is to analyze your system and generate customized
341 is also when you have to tell where Winelib resides on your
342 system. If wine is installed in a single directory or you have
343 the Wine sources compiled somewhere then you can just run
346 respectively.
347 </para>
348 </listitem>
349 </varlistentry>
350 <varlistentry>
352 <listitem>
353 <para>
355 and voila, you should have all your executables and libraries.
356 If this did not work out, then it means that you will have to
357 read this guide further to:
358 <itemizedlist>
359 <listitem>
360 <para>
362 adjust the default compilation and link options set by
365 </para>
366 </listitem>
367 <listitem>
368 <para>
369 fix the portability issues in your sources. See
372 </para>
373 </listitem>
374 </itemizedlist>
375 </para>
376 <para>
377 If you find yourself modifying the Makefile.in to specify the
378 location of the Wine header or library files then go back to
379 the previous step (the configure script) and use the various
380 --with-wine-* options to specify where they are.
381 </para>
382 </listitem>
383 </varlistentry>
384 </variablelist>
385 </sect2>
386 </sect1>
387 </chapter>
389 <!-- Keep this comment at the end of the file
390 Local variables:
391 mode: sgml
392 sgml-parent-document:("wine-doc.sgml" "book" "chapter" "")
393 End:
394 -->