1 <book id="index-winelib">
3 <title>Winelib User Guide</title>
6 <chapter id="winelib-introduction">
7 <title id="introduction.title">Introduction</title>
9 Winelib is a development toolkit which allows you to compile your
10 Windows applications on Unix.
13 Most of Winelib's code consists of the Win32 API implementation.
14 Fortunately this part is 100 percent shared with Wine. The remainder
15 consists of Windows compatible headers and tools like the resource
16 compiler (and even these are used when compiling Wine).
19 Thanks to the above, Winelib supports most C and C++ 32bit source code,
20 resource and message files, and can generate graphical or console
21 applications as well as dynamic libraries.
24 What is not supported is 16bit source code as the types it depends on
25 (especially segmented pointers) are not supported by Unix compilers.
26 Also missing are some of the more exotic features of Microsoft's
27 compiler like native COM support and structured exception handling.
28 So you may need to perform some modifications in your code when
29 recompiling your application with Winelib. This guide is here to help
33 What you gain by recompiling your application with Winelib is the
34 ability to make calls to Unix APIs, directly from your
35 Windows source code. This allows for a better integration with the
36 Unix environment than is allowed by runnning an unmodified Windows
37 application running in Wine. Another benefit is that a Winelib
38 application can relatively easily be recompiled on a non-Intel
39 architecture and run there without the need for a slow software
40 emulation of the processor.
44 <chapter id="winelib-requirements">
45 <title id="requirements.title">System requirements</title>
47 The requirements for Winelib are similar to those for Wine.
50 Basically if you can run Wine on your computer then you can run
51 Winelib. But the converse is not true. You can also build Winelib
52 and Winelib applications on platforms not supported by Wine,
53 typically platforms with a non i386 processor. But this is still
54 pretty much an uncharted territory. It would be more reasonable to
55 first target one of the more mundane i386-based platforms first.
58 The main difference is that the compiler becomes much more important.
59 It is highly recommended that you use gcc, g++,
60 and the GNU binutils. The more recent your gcc compiler the better.
61 For any serious amount of code you should not consider anything older
62 than gcc 2.95.2. The latest gcc snapshots contain some useful bug
63 fixes and much better support for anonymous structs and unions. This
64 can help reduce the number of changes you have to do in your code but
65 these are not stable releases of the compiler so you may not want to
66 use them in production.
70 <chapter id="winelib-getting-started">
71 <title id="getting-started.title">Getting Started</title>
72 <sect1 id="winemaker-introduction">
73 <title id="winemaker-introduction.title">Winemaker introduction</title>
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:
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.
89 then the case of the filenames in your include statements may be
90 wrong: maybe they include 'Windows.h' instead of 'windows.h'.
95 your include statements may use '\' instead of '/'. '\' is not
96 recognized by Unix compilers while '/' is recognized in both
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.
110 you will have to write new makefiles.
116 The best way to take care of all these issues is to use winemaker.
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.
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:
132 $ winemaker --lower-uppercase
133 $ ./configure --with-wine=/usr/local/wine
138 But of course things are not always that simple which is why we have
143 <sect1 id="winemaker-guide">
144 <title id="winemaker-guide.title">Step by step guide</title>
146 Let's retrace the steps above in more details.
150 <term><option>Getting the source</option></term>
153 First if you can try to get the sources together with the
154 executables/libraries that they build. In the current state of
155 winemaker having these around can help it guess what it is that
156 your project is trying to build. Later, when it is able to
157 understand Visual C++ projects, and if you use them, this will
158 no longer be necessary. Usually the executables and libraries
159 are in a <filename class="Directory">Release</filename> or
160 <filename class="Directory">Debug</filename> subdirectory of the
161 directory where the sources are. So it's best if you can
162 transfer the source files and either of these directories to
163 Linux. Note that you don't need to transfer the
164 <filename>.obj</filename>, <filename>.pch</filename>,
165 <filename>.sbr</filename> and other files that also reside in
166 these directories; especially as they tend to be quite big.
171 <term><option>cd <root_dir></option></term>
174 Then go to the root directory where are your source files.
175 Winemaker can deal with a whole directory hierarchy at once so
176 you don't need to go into a leaf directory, quite the contrary.
177 Winemaker will automatically generate makefiles in each
178 directory where one is required, and will generate a global
179 makefile so that you can rebuild all your executables and
180 libraries with a single <command>make</command> command.
185 <term><option>Making the source writable</option></term>
188 Then make sure you have write access to your sources. It may
189 sound obvious, but if you copied your source files from a
190 CD-ROM or if they are in Source Safe on Windows, chances are
191 that they will be read-only.
192 But Winemaker needs write access so that it can fix them. You
193 can arrange that by running <command>chmod -R u+w .</command>.
194 Also you will want to make sure that you have a backup copy of
195 your sources in case something went horribly wrong, or more
196 likely, just for reference at a later point. If you use a
197 version control system you're already covered.
202 <term><option>Running winemaker</option></term>
205 Then you'll run winemaker. Here are the options you will most
210 <term><option>--lower-uppercase</option></term>
211 <term><option>--lower-all</option></term>
214 These options specify how to deal with files, and
215 directories, that have an 'incorrect' case.
216 <option>--lower-uppercase</option> specifies they should
217 only be renamed if their name is all uppercase. So files
218 that have a mixed case, like 'Hello.c' would not be
219 renamed. <option>--lower-all</option> will rename any
220 file. If neither is specified then no file or directory
221 will be renamed, almost. As you will see
222 <link linkend="renaming">later</link> winemaker may
223 still have to rename some files.
228 <term><option>--nobackup</option></term>
231 Winemaker normally makes a backup of all the files in which
232 it does more than the standard Dos to Unix conversion.
233 But if you already have (handy) copies of these files
234 elsewhere you may not need these so you should use this
240 <term><option>--dll</option></term>
241 <term><option>--console</option></term>
244 These option lets winemaker know what kind of target you are
245 building. If you have the windows library in your source
246 hierarchy then you should not need to specify
247 <option>--dll</option>. But if you have console executables
248 then you will need to use the corresponding option.
253 <term><option>--mfc</option></term>
256 This option tells winemaker that you are building an MFC
262 <term><option>-Dmacro[=defn]</option></term>
263 <term><option>-Idir</option></term>
264 <term><option>-Ldir</option></term>
265 <term><option>-idll</option></term>
266 <term><option>-llibrary</option></term>
269 The <option>-i</option> specifies a Winelib library to
270 import via the <link linkend="spec-file">spec file</>
271 mechanism. Contrast this with the <option>-l</option>
272 which specifies a Unix library to link with. The other
273 options work the same way they would with a C
274 compiler. All are applied to all the targets found.
275 When specifying a directory with either
276 <option>-I</option> or <option>-L</option>, winemaker
277 will prefix a relative path with
278 <literal>$(TOPDIRECTORY)/</literal> so that it is valid
279 from any of the source directories. You can also use a
280 variable in the path yourself if you wish (but don't
281 forget to escape the '$'). For instance you could specify
282 <literal>-I\$(WINELIB_INCLUDE_ROOT)/msvcrt</literal>.
288 So your command may finally look like:
289 <literal>winemaker --lower-uppercase -Imylib/include</literal>
294 <term id="renaming"><option>File renaming</option></term>
297 When you execute winemaker it will first rename files to bring
298 their character case in line with your expectations and so that they can
299 be processed by the makefiles. This later category implies that
300 files with a non lowercase extension will be renamed so that the
301 extension is in lowercase. So, for instance,
302 <filename>HELLO.C</filename> will be renamed to
303 <filename>HELLO.c</filename>. Also if a file or directory name
304 contains a space or a dollar, then this
305 character will be replaced with an underscore. This is because
306 these characters cause problems with current versions of autoconf
307 (2.13) and make (3.79).
312 <term><option>Source modifications and makefile generation</option></term>
315 winemaker will then proceed to modify the source files so that
316 they will compile more readily with Winelib. As it does so it
317 may print warnings when it has to make a guess or identifies a
318 construct that it cannot correct. Finally it will generate the
319 autoconf-based makefiles. Once all this is done you can review
320 the changes that winemaker did to your files by using
321 <command>diff -uw</command>. For instance:
322 <command>diff -uw hello.c.bak hello.c</command>
327 <term><option>Running the configure script</option></term>
330 Before you run <command>make</command> you must run the
331 autoconf <command>configure</command> script. The goal of this
332 step is to analyze your system and generate customized
333 makefiles from the <filename>Makefile.in</filename> files. This
334 is also when you have to tell where Winelib resides on your
335 system. If wine is installed in a single directory or you have
336 the Wine sources compiled somewhere then you can just run
337 <command>./configure --with-wine=/usr/local/bin</command>
338 or <command>./configure --with-wine=~/wine</command>
344 <term><option>Running make</option></term>
347 This is a pretty simple step: just type <command>make</command>
348 and voila, you should have all your executables and libraries.
349 If this did not work out, then it means that you will have to
350 read this guide further to:
354 review the <filename>Makefile.in</filename> files to
355 adjust the default compilation and link options set by
356 winemaker. See the <xref linkend="source-analysis"
357 endterm="source-analysis.title"> section for some hints.
362 fix the portability issues in your sources. See
363 <xref linkend="portability-issues"
364 endterm="portability-issues.title"> for more details.
375 <chapter id="portability-issues">
376 <title id="portability-issues.title">Portability issues</title>
378 <title id="anon.title">Anonymous unions/structs</title>
380 Anonymous structs and unions support depends heavily on the compiler.
381 The best support is provided by gcc/g++ 2.96 and later. But these
382 versions of gcc come from the development branch so you may want to
383 hold off before using them in production. g++ 2.95 supports anonymous
384 unions but not anonymous structs and gcc 2.95 supports neither. Older
385 versions of gcc/g++ have no support for either.
386 since it is anonymous unions that are the most frequent in the
387 windows headers, you should at least try to use gcc/g++ 2.95.
390 But you are stuck with a compiler that does not support anonymous
391 structs/unions all is not lost. The Wine headers should detect this
392 automatically and define <varname>NONAMELESSUNION</varname> /
393 <varname>NONAMELESSSTRUCT</varname>. Then any anonymous union will
395 <literal>u</literal> or <literal>u2</literal>, <literal>u3</literal>,
396 etc. to avoid name clashes. You will then have to modify your code to
397 include those names where appropriate.
400 The name that Wine adds to anonymous unions should match that used
401 by the Windows headers. So all you have to do to compile your
402 modified code in Windows is to explicitly define the
403 <varname>NONAMELESSUNION</varname> macro. Note that it would be wise
404 to also explicitly define this macro on in your Unix makefile
405 (<filename>Makefile.in</filename>) to make sure your code will
406 compile even if the compiler does support anonymous unions.
409 Things are not as nice when dealing with anonymous structs.
410 Unfortunately the Windows headers make no provisions for compilers
411 that do not support anonymous structs. So you will need to be more
412 subtle when modifying your code if you still want it to compile in
413 Windows. Here's a way to do it:
426 GetSystemInfo(&si);
427 printf("Processor architecture=%d\n",si ANONS .wProcessorArchitecture);
431 You may put the <literal>#define</literal> directive directly in the
432 source if only few files are impacted. Otherwise it's probably best
433 to put it in one of your project's widely used headers.
434 Fortunately usage of an anonymous struct is much rarer than usage of
435 an anonymous union so these modifications should not be too much work.
439 <title id="unicode.title">Unicode</title>
441 L"foo" generates 4-byte chars,
442 use __TEXT (or _TEXT?),
446 <sect1 id="C-library">
447 <title id="C-library.title">C library</title>
449 Winelib currently only supports on C library: that of your compiler.
452 three solutions: native, mixed or msvcrt except we only have native right now,
453 using the native C library -> different behavior: fopen, O_TEXT,
458 <sect1 id="init-problems">
459 <title id="init-problems.title">Initialization problems</title>
461 Initialization problems occur when the application calls the Win32 API
462 before Winelib has been initialized. How can this happen?
465 Winelib is initialized by the application's <function>main</function>
466 before it calls the regular <function>WinMain</function>. But, in C++,
467 the constructors of static class variables are called before the
468 <function>main</function> (by the module's initializer). So if such
469 a constructor makes calls to the Win32 API, Winelib will not be
470 initialized at the time of the call and you may get a crash. This
471 problem is much more frequent in C++ because of these class
472 constructors but could also, at least in theory, happen in C if you
473 were to specify an initializer making calls to Winelib. But of
474 course, now that you are aware of this problem you won't do it :-).
477 Further compounding the problem is the fact that Linux's (GNU's?)
478 current dynamic library loader does not call the module
479 initializers in their dependency order. So even if Winelib were to
480 have its own initializer there would be no garantee that it would be
481 called before the initializer of the library containing this static
482 variable. Finally even if the variable is in a library that your
483 application links with, that library's initializer may be called
484 before Winelib has been initialized. One such library is the MFC.
487 The current workaround is to move all the application's code in a
488 library and to use a small Winelib application to dynamically load
489 this library. Tus the initialization sequence becomes:
494 the wrapper application starts.
499 its empty initializer is run.
504 its <function>main</function> is run. Its first task is to
510 it then loads the application's main library, plus all its
516 which triggers the execution of all these libraries initializers
517 in some unknown order. But all is fine because Winelib has
518 already been initialized anyway.
523 finally the main function calls the <function>WinMain</function>
524 of the application's library.
529 This may sound complex by Winemaker makes it simple. Just specify
530 <option>--wrap</option> or <option>--mfc</option> on the command line
531 and it will adapt its makefiles to build the wrapper and the
535 <sect1 id="com-support">
536 <title id="com-support.title">VC's native COM support</title>
539 guide on how to replace it with normal C++ code (yes, how???):
540 extracting a .h and .lib from a COM dll
541 Can '-fno-rtti' be of some use or even required?
545 <title id="SEH.title">SEH</title>
547 how to modify the syntax so that it works both with gcc's macros and Wine's macros,
552 <title id="others.title">Others</title>
554 -fpermissive and -fno-for-scope,
560 <chapter id="winelib-toolkit">
561 <title id="winelib-toolkit.title">The Winelib development toolkit</title>
562 <sect1 id="winemaker">
563 <title id="winemaker.title">Winemaker</title>
564 <sect2 id="vc-projects">
565 <title id="vc-projects.title">Support for Visual C++ projects</title>
567 Unfortunately Winemaker does not support the Visual C++ project
568 files, ...yet. Supporting Visual C++ project files (the
569 <filename>.dsp</filename> and some <filename>.mak</filename> files
570 for older versions of Visual C++) is definitely on
571 the list of important Winemaker improvements as it will allow it to
572 properly detect the defines to be used, any custom include path, the
573 list of libraries to link with, and exactly which source files to use
574 to build a specific target. All things that the current version of
575 Winemaker has to guess or that you have to tell it as will become
576 clear in the next section.
579 When the time comes Winemaker, and its associated build system, will
580 need some extensions to support:
585 per file defines and include paths. Visual C++ projects allow
586 the user to specify compiler options for each individual file
587 being compiled. But this is probably not very frequent so it
588 might not be that important.
593 multiple configurations. Visual C++ projects usually have at
594 least a 'Debug' and a 'Release' configuration which are compiled
595 with different compiler options. How exactly we deal with these
596 configurations remains to be determined.
601 <sect2 id="source-analysis">
602 <title id="source-analysis.title">Winemaker's source analysis</title>
604 Winemaker can do its work even without a Windows makefile or a
605 Visual Studio project to start from (it would not know what to do
606 with a windows makefile anyway). This involves doing many educated
607 guesses which may be wrong. But by and large it works. The purpose
608 of this section is to describe in more details how winemaker
609 proceeds so that you can better understand why it gets things
610 wrong and how to fix it/avoid it.
613 At the core winemaker does a recursive traversal of
614 your source tree looking for targets (things to build) and source
615 files. Let's start with the targets.
618 First are executables and dlls. Each time it finds one of these in
619 a directory, winemaker puts it in the list of things to build and
620 will later generate a <filename>Makefile.in</filename> file in this
621 directory. Note that Winemaker also knows about the commonly used
622 <filename>Release</filename> and <filename>Debug</filename>
623 directories, so it will attribute the executables and libraries
624 found in these to their parent directory. When it finds an
625 executable or a dll winemaker is happy because these give it more
626 information than the other cases described below.
629 If it does not find any executable or dll winemaker will look for
630 files with a <filename>.mak</filename> extension. If they are not
631 disguised Visual C++ projects (and currently even if they are),
632 winemaker will assume that a target by that name should be built
633 in this directory. But it will not know whether this target is an
634 executable or a library. So it will assume it is of the default
635 type, i.e. a graphical application, which you can override by using
636 the <option>--cuiexe</option> and <option>--dll</option> options.
639 Finally winemaker will check to see if there is a file called
640 <filename>makefile</filename>. If there is, then it will assume
641 that there is exactly one target to build for this directory. But
642 it will not know the name or type of this target. For the type it
643 will do as in the above case. And for the name it will use the
644 directory's name. Actually, if the directory starts with
645 <filename>src</filename> winemaker will try to make use of the name
646 of the parent directory instead.
649 Once the target list for a directory has been established,
650 winemaker will check whether it contains a mix of executables and
651 libraries. If it is so, then winemaker will make it so that each
652 executable is linked with all the libraries of that directory.
655 If the previous two steps don't produce the expected results (or
656 you think they will not) then you should put winemaker in
657 interactive mode (see <xref linkend="interactive"
658 endterm="interactive.title">). This will allow you to specify the
659 target list (and more) for each directory.
662 In each directory winemaker also looks for source files: C, C++
663 or resource files. If it also found targets to build in this
664 directory it will then try to assign each source file to one of
665 these targets based on their names. Source files that do not seem
666 to match any specific target are put in a global list for this
667 directory, see the <literal>EXTRA_xxx</literal> variables in the
668 <filename>Makefile.in</filename>, and linked with each of the
669 targets. The assumption here is that these source files contain
670 common code which is shared by all the targets.
671 If no targets were found in the directory where these files are
672 located, then they are assigned to the parent's directory. So if a
673 target is found in the parent directory it will also 'inherit' the
674 source files found in its subdirectories.
677 Finally winemaker also looks for more exotic files like
678 <filename>.h</filename> headers, <filename>.inl</filename> files
679 containing inline functions and a few others. These are not put in
680 the regular source file lists since they are not compiled directly.
681 But winemaker will still remember them so that they are processed
682 when the time comes to fix the source files.
685 Fixing the source files is done as soon as winemaker has finished
686 its recursive directory traversal. The two main tasks in this step
687 are fixing the CRLF issues and verifying the case of the include
691 Winemaker makes a backup of each source file (in such a way that
692 symbolic links are preserved), then reads it fixing the CRLF
693 issues and the other issues as it goes. Once it has finished
694 working on a file it checks whether it has done any non
695 CRLF-related modification and deletes the backup file if it did
696 not (or if you used <option>--nobackup</option>).
699 Checking the case of the include statements (of any form,
700 including files referenced by resource files), is done in the
701 context of that source file's project. This way winemaker can use
702 the proper include path when looking for the file that is included.
703 If winemaker fails to find a file in any of the directories of the
704 include path, it will rename it to lowercase on the basis that it
705 is most likely a system header and that all system headers names
706 are lowercase (this can be overriden by using
707 <option>--nolower-include</option>).
710 Finally winemaker generates the <filename>Makefile.in</filename>
711 files and other support files (wrapper files, spec files,
712 <filename>configure.in</filename>,
713 <filename>Make.rules.in</filename>). From the above description
714 you can guess at the items that winemaker may get wrong in
715 this phase: macro definitions, include path, library path,
716 list of libraries to import. You can deal with these issues by
717 using winemaker's <option>-D</option>, <option>-I</option>,
718 <option>-L</option> and <option>-i</option> options if they are
719 homogeneous enough between all your targets. Otherwise you may
720 want to use winemaker's <link linkend="interactive">interactive
721 mode</link> so that you can specify different settings for each
725 For instance, one of the problems you are likely to encounter is
726 that of the <varname>STRICT</varname> macro. Some programs will
727 not compile if <varname>STRICT</varname> is not turned on, and
728 others will not compile if it is. Fortunately all the files in a
729 given source tree use the same setting so that all you have to do
730 is add <literal>-DSTRICT</literal> on winemaker's command line
731 or in the <filename>Makefile.in</filename> file(s).
734 Finally the most likely reasons for missing or duplicate symbols
740 The target is not being linked with the right set of libraries.
741 You can avoid this by using winemaker's <option>-L</option> and
742 <option>-i</option> options or adding these libraries to the
743 <filename>Makefile.in</filename> file.
748 Maybe you have multiple targets in a single directory and
749 winemaker guessed wrong when trying to match the source files
750 with the targets. The only way to fix this kind of problem is
751 to edit the <filename>Makefile.in</filename> file manually.
756 Winemaker assumes you have organized your source files
757 hierarchically. If a target uses source files that are in a
758 sibling directory, e.g. if you link with
759 <filename>../hello/world.o</filename> then you will get missing
760 symbols. Again the only solution is to manually edit the
761 <filename>Makefile.in</filename> file.
766 <sect2 id="interactive">
767 <title id="interactive.title">The interactive mode</title>
774 <sect2 id="Makefile.in">
775 <title id="Makefile.in.title">The Makefile.in files</title>
777 The <filename>Makefile.in</filename> is your makefile. More
778 precisely it is the template from which the actual makefile will
779 be generated by the <filename>configure</filename> script. It also
780 relies on the <filename>Make.rules</filename> file for most of
781 the actual logic. This way it only contains a relatively simple
782 description of what needs to be built, not the complex logic of
783 how things are actually built.
786 So this is the file to modify if you want to customize things.
787 Here's a detailed description of its content:
790 ### Generic autoconf variables
792 TOPSRCDIR = @top_srcdir@
798 The above is part of the standard autoconf boiler-plate. These
799 variables make it possible to have per-architecture directories for
800 compiled files and other similar goodies (But note that this kind
801 of functionality has not been tested with winemaker generated
802 <filename>Makefile.in</filename> files yet).
810 This is where the targets for this directory are listed. The names
811 are pretty self-explanatory. <varname>SUBDIRS</varname> is usually
812 only present in the top-level makefile. For libraries you should
813 put the full Unix name, e.g. <literal>libfoo.so</literal>.
824 This section contains the global compilation settings: they apply
825 to all the targets in this makefile. The <varname>LIBRARIES</varname>
826 variable allows you to specify additional Unix libraries to link with.
827 Note that you would normally not specify Winelib libraries there. To
828 link with a Winelib library, one uses the 'import' statement of the
829 <link linkend="spec-file">spec files</link>. The exception is when you
830 have not explicitly exported the functions of a Winelib library. One
831 library you are likely to find here is <literal>mfc</literal> (note,
832 the '-l' is omitted).
836 names should be self-explanatory. You can also use three additional
837 variables that are usually not present in the file:
838 <varname>CEXTRA</varname>, <varname>CXXEXTRA</varname> and
839 <varname>WRCEXTRA</varname> which allow you to specify additional
840 flags for, respectively, the C compiler, the C++ compiler and the
841 resource compiler. Finally note that all these variable contain
842 the option's name except <varname>IMPORTS</varname>. So you should
843 put <literal>-DSTRICT</literal> in <varname>DEFINES</varname> but
844 <literal>winmm</literal> in <varname>IMPORTS</varname>.
847 Then come one section per target, each describing the various
848 components that target is made of.
851 ### hello sources and settings
853 hello_C_SRCS = hello.c
856 hello_SPEC_SRCS = hello.spec
859 Each section will start with a comment indicating the name of the
860 target. Then come a series of variables prefixed with the name of
861 that target. Note that the name of the prefix may be slightly
862 different from that of the target because of restrictions on the
866 The above variables list the sources that are used togenerate the
867 target. Note that there should only be one resource file in
868 <varname>RC_SRCS</varname>, and that <varname>SPEC_SRCS</varname>
869 will always contain a single spec file.
877 The above variables specify how to link the target. Note that they
878 add to the global settings we saw at the beginning of this file.
881 <varname>DEPENDS</varname>, when present, specifies a list of other
882 targets that this target depends on. Winemaker will automatically
883 fill this field, and the <varname>LIBRARIES</varname> field, when an
884 executable and a library are built in the same directory.
887 The reason why winemaker also links with libraries in the Unix sense
888 in the case above is because functions will not be properly exported.
889 Once you have exported all the functions in the library's spec file
890 you should remove them from the <varname>LIBRARIES</varname> field.
893 hello_OBJS = $(hello_C_SRCS:.c=.o) \
894 $(hello_CXX_SRCS:.cpp=.o) \
898 The above just builds a list of all the object files that
899 correspond to this target. This list is later used for the link
903 ### Global source lists
905 C_SRCS = $(hello_C_SRCS)
906 CXX_SRCS = $(hello_CXX_SRCS)
907 RC_SRCS = $(hello_RC_SRCS)
908 SPEC_SRCS = $(hello_SPEC_SRCS)
911 This section builds 'summary' lists of source files. These lists are
912 used by the <filename>Make.rules</filename> file.
915 ### Generic autoconf targets
917 all: $(DLLS) $(EXES:%=%.so)
922 for i in $(EXES); do $(INSTALL_PROGRAM) $$i $(bindir); done
923 for i in $(EXES:%=%.so) $(DLLS); do $(INSTALL_LIBRARY) $$i $(libdir); done
926 for i in $(EXES); do $(RM) $(bindir)/$$i;done
927 for i in $(EXES:%=%.so) $(DLLS); do $(RM) $(libdir)/$$i;done
930 The above first defines the default target for this makefile. Here
931 it consists in trying to build all the targets. Then it includes
932 the <filename>Make.rules</filename> file which contains the build
933 logic, and provides a few more standard targets to install /
934 uninstall the targets.
937 ### Target specific build rules
939 $(hello_SPEC_SRCS:.spec=.tmp.o): $(hello_OBJS)
940 $(LDCOMBINE) $(hello_OBJS) -o $@
941 -$(STRIP) $(STRIPFLAGS) $@
943 $(hello_SPEC_SRCS:.spec=.spec.c): $(hello_SPEC_SRCS:.spec) $(hello_SPEC_SRCS:.spec=.tmp.o) $(hello_RC_SRCS:.rc=.res)
944 $(WINEBUILD) -fPIC $(hello_LIBRARY_PATH) $(WINE_LIBRARY_PATH) -sym $(hello_SPEC_SRCS:.spec=.tmp.o) -o $@ -spec $(hello_SPEC_SRCS)
946 hello.so: $(hello_SPEC_SRCS:.spec=.spec.o) $(hello_OBJS) $(hello_DEP
948 $(LDSHARED) $(LDDLLFLAGS) -o $@ $(hello_OBJS) $(hello_SPEC_SRCS:.spec=.spec.o) $(hello_LIBRARY_PATH) $(hello_LIBRARIES:%=-l%) $(DLL_LINK) $(LIBS)
949 test -e hello || $(LN_S) $(WINE) hello
952 Then come additional directives to link the executables and
953 libraries. These are pretty much standard and you should not need
957 <sect2 id="Make.rules.in">
958 <title id="Make.rules.in.title">The Make.rules.in file</title>
960 What's in the Make.rules.in...
963 <sect2 id="configure.in">
964 <title id="configure.in.title">The configure.in file</title>
966 What's in the configure.in...
971 <title id="wrc.title">Compiling resource files: WRC</title>
973 To compile resources you should use the Wine Resource Compiler,
974 wrc for short, which produces a binary <filename>.res</filename>
975 file. This resource file is then used by winebuild when compiling
976 the spec file (see <xref linkend="spec-file"
977 endterm="spec-file.title">).
980 Again the makefiles generated by winemaker take care of this for you.
981 But if you were to write your own makefile you would put something
985 WRC=$(WINE_DIR)/tools/wrc/wrc
987 WINELIB_FLAGS = -I$(WINE_DIR)/include -DWINELIB -D_REENTRANT
993 $(WRC) $(WRCFLAGS) $(WINELIB_FLAGS) -o $@ $<
996 There are two issues you are likely to encounter with resource files.
999 The first problem is with the C library headers. WRC does not know
1000 where these headers are located. So if an RC file, of a file it
1001 includes, references such a header you will get a 'file not found'
1002 error from wrc. Here are a few ways to deal with this:
1007 The solution traditionally used by the Winelib headers is to
1008 enclose the offending include statement in an
1009 <literal>#ifndef RC_INVOKED</literal> statement where
1010 <varname>RC_INVOKED</varname> is a macro name which is
1011 automatically defined by wrc.
1016 Alternately you can add one or more <option>-I</option> directive
1017 to your wrc command so that it finds you system files. For
1018 instance you may add <literal>-I/usr/include
1019 -I/usr/lib/gcc-lib/i386-linux/2.95.2/include</literal> to cater
1020 to both C and C++ headers. But this supposes that you know where
1021 these header files reside which decreases the portability of your
1022 makefiles to other platforms (unless you automatically detect all
1023 the necessary directories in the autoconf script).
1026 Or you could use the C/C++ compiler to perform the preprocessing.
1027 To do so, simply modify your makefile as follows:
1031 $(CC) $(CC_OPTS) -DRC_INVOKED -E -x c $< | $(WRC) -N $(WRCFLAGS) $(WINELIB_FLAGS) -o $@
1034 <!-- FIXME: does this still cause problems for the line numbers? -->
1038 The second problem is that the headers may contain constructs that
1039 WRC fails to understand. A typical example is a function which return
1040 a 'const' type. WRC expects a function to be two identifiers followed
1041 by an opening parenthesis. With the const this is three identifiers
1042 followed by a parenthesis and thus WRC is confused (note: WRC should
1043 in fact ignore all this like the windows resource compiler does).
1044 The current work-around is to enclose offending statement(s) in an
1045 <literal>#ifndef RC_INVOKED</literal>.
1049 <title id="wmc.title">Compiling message files: WMC</title>
1051 how does one use it???
1054 <sect1 id="spec-file">
1055 <title id="spec-file.title">The Spec file</title>
1056 <sect2 id="spec-intro">
1057 <title id="spec-intro.title">Introduction</title>
1059 In Windows the program's life starts either when its
1060 <function>main</function> is called, for console applications, or
1061 when its <function>WinMain</function> is called, for windows
1062 applications in the 'windows' subsystem. On Unix it is always
1063 <function>main</function> that is called. Furthermore in Winelib it
1064 has some special tasks to accomplish, such as initializing Winelib,
1065 that a normal <function>main</function> does not have to do.
1068 Furthermore windows applications and libraries contain some
1069 information which are necessary to make APIs such as
1070 <function>GetProcAddress</function> work. So it is necessary to
1071 duplicate these data structures in the Unix world to make these
1072 same APIs work with Winelib applications and libraries.
1075 The spec file is there to solve the semantic gap described above.
1076 It provides the <function>main</function> function that initializes
1077 Winelib and calls the module's <function>WinMain</function> /
1078 <function>DllMain</function>, and it contains information about
1079 each API exported from a Dll so that the appropriate tables can be
1083 A typical spec file will look something like this:
1095 And here are the entries you will probably want to change:
1102 This is the name of the Win32 module. Usually this is the
1103 same as that of the application or library (but without the
1104 'lib' and the '.so').
1113 <literal>mode</literal> defines whether what you are
1114 building is a library, <literal>dll</literal>, a console
1115 application, <literal>cuiexe</literal> or a regular
1116 graphical application <literal>guiexe</literal>. Then
1117 <literal>init</literal> defines what is the entry point of
1118 that module. For a library this is customarily set to
1119 <literal>DllMain</literal>, for a console application this
1120 is <literal>main</literal> and for a graphical application
1121 this is <literal>WinMain</literal>.
1129 Add an 'import' statement for each library that this
1130 executable depends on. If you don't, these libraries will
1131 not get initialized in which case they may very well not
1140 This item specifies the name of the compiled resource file
1141 to link with your module. If your resource file is called
1142 <filename>hello.rc</filename> then the wrc compilation step
1143 (see <xref linkend="wrc" endterm="wrc.title">) will generate
1144 a file called <filename>hello.res</filename>. This is the
1145 name you must provide here. Note that because of this you
1146 cannot compile the spec file before you have compiled the
1147 resource file. So you should put a rule like the following
1151 hello.spec.c: hello.res
1154 If your project does not have a resource file then you must
1155 omit this entry altogether.
1163 This entry is not shown above because it is not always
1164 necessary. In fact it is only necessary to export functions
1165 when you plan to dynamically load the library with
1166 <function>LoadLibrary</function> and then do a
1167 <function>GetProcAddress</function> on these functions.
1168 This is not necessary if you just plan on linking with the
1169 library and calling the functions normally. For more details
1170 about this see: <xref linkend="spec-reference"
1171 endterm="spec-reference.title">.
1177 <sect2 id="spec-compiling">
1178 <title id="spec-compiling.title">Compiling it</title>
1180 Compiling a spec file is a two step process. It is first
1181 converted into a C file by winebuild, and then compiled into an
1182 object file using your regular C compiler. This is all taken
1183 care of by the winemaker generated makefiles of course. But
1184 here's what it would like if you had to do it by hand:
1187 WINEBUILD=$(WINE_DIR)/tools/winebuild
1189 .SUFFIXES: .spec .spec.c .spec.o
1192 $(WINEBUILD) -fPIC -o $@ -spec $<
1195 $(CC) -c -o $*.spec.o $<
1198 Nothing really complex there. Just don't forget the
1199 <literal>.SUFFIXES</literal> statement, and beware of the tab if
1200 you copy this straight to your Makefile.
1203 <sect2 id="spec-reference">
1204 <title id="spec-reference.title">More details</title>
1206 (Extracted from tools/winebuild/README)
1207 <!-- FIXME: this seems to be rather outdated and sometimes even incorrect, check with the source! -->
1211 Here is a more detailed description of the spec file's format.
1218 Anything after a '#' will be ignored as comments.
1223 type win16|win32 <--- the |'s mean it's one or the other
1226 These two fields are mandatory. <literal>name</literal>
1227 defines the name of your module and <literal>type</literal>
1228 whether it is a Win16 or Win32 module. Note that for Winelib
1229 you should only be using Win32 modules.
1236 This field is optional. It gives the name of the Windows file that
1237 is replaced by the builtin. <literal><name>.DLL</literal>
1238 is assumed if none is given. This is important for kernel, which
1239 lives in the Windows file <filename>KRNL386.EXE</filename>.
1246 This field is optional and specific to Win16 modules. It defines
1247 the size of the module local heap. The default is no local heap.
1251 mode dll|cuiexe|guiexe
1254 This field is optional. It specifies specifies whether it is the
1255 spec file for a dll or the main exe. This is only valid for Win32
1263 This field is optional and specific to Win32 modules. It
1264 specifies a function which will be called when the dll is loaded
1265 or the executable started.
1272 This field can be present zero or more times.
1273 Each instance names a dll that this module depends on (only for
1274 Win32 modules at the present).
1281 This field is optional. If present it specifies the name of the
1282 .res file containing the compiled resources. See <xref
1283 linkend="wrc" endterm="wrc.title"> for details on compiling a
1288 ORDINAL VARTYPE EXPORTNAME (DATA [DATA [DATA [...]]])
1289 2 byte Variable(-1 0xff 0 0)
1292 This field can be present zero or more times.
1293 Each instance defines data storage at the ordinal specified. You
1294 may store items as bytes, 16-bit words, or 32-bit words.
1295 <literal>ORDINAL</literal> is replaced by the ordinal number
1296 corresponding to the variable. <literal>VARTYPE</literal> should
1297 be <literal>byte</literal>, <literal>word</literal> or
1298 <literal>long</literal> for 8, 16, or 32 bits respectively.
1299 <literal>EXPORTNAME</literal> will be the name available for
1300 dynamic linking. <literal>DATA</literal> can be a decimal number
1301 or a hex number preceeded by "0x". The example defines the
1302 variable <literal>Variable</literal> at ordinal 2 and containing
1307 ORDINAL equate EXPORTNAME DATA
1310 This field can be present zero or more times.
1311 Each instance defines an ordinal as an absolute value.
1312 <literal>ORDINAL</literal> is replaced by the ordinal number
1313 corresponding to the variable. <literal>EXPORTNAME</literal> will
1314 be the name available for dynamic linking.
1315 <literal>DATA</literal> can be a decimal number or a hex number
1320 ORDINAL FUNCTYPE EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
1321 100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word
1324 101 pascal GetFocus() WIN_GetFocus()
1327 This field can be present zero or more times.
1328 Each instance defines a function entry point. The prototype
1329 defined by <literal>EXPORTNAME ([ARGTYPE [ARGTYPE [...]]])</literal>
1330 specifies the name available for dynamic linking and the format
1331 of the arguments. <literal>"ORDINAL</literal>" is replaced
1332 by the ordinal number corresponding to the function, or
1333 <literal>@</literal> for automatic ordinal allocation (Win32 only).
1336 <literal>FUNCTYPE</literal> should be one of:
1340 <term>pascal16</term>
1341 <listitem><para>for a Win16 function returning a 16-bit value</para></listitem>
1345 <listitem><para>for a Win16 function returning a 32-bit value</para></listitem>
1348 <term>register</term>
1349 <listitem><para>for a function using CPU register to pass arguments</para></listitem>
1352 <term>interrupt</term>
1353 <listitem><para>for a Win16 interrupt handler routine</para></listitem>
1356 <term>stdcall</term>
1357 <listitem><para>for a normal Win32 function</para></listitem>
1361 <listitem><para>for a Win32 function using the C calling convention</para></listitem>
1364 <term>varargs</term>
1365 <listitem><para>for a Win32 function taking a variable number of arguments</para></listitem>
1370 <literal>ARGTYPE</literal> should be one of:
1375 <listitem><para>for a 16 bit word</para></listitem>
1379 <listitem><para>a 32 bit value</para></listitem>
1383 <listitem><para>for a linear pointer</para></listitem>
1387 <listitem><para>for a linear pointer to a null-terminated string</para></listitem>
1391 <listitem><para>for a 16 bit signed word</para></listitem>
1395 <listitem><para>for a segmented pointer</para></listitem>
1399 <listitem><para>for a segmented pointer to a null-terminated string</para></listitem>
1404 Only <literal>ptr</literal>, <literal>str</literal> and
1405 <literal>long</literal> are valid for Win32 functions.
1406 <literal>HANDLERNAME</literal> is the name of the actual Wine
1407 function that will process the request in 32-bit mode.
1410 The two examples define an entry point for the
1411 <function>CreateWindow</function> and <function>GetFocus</function>
1412 calls respectively. The ordinals used are just examples.
1415 To declare a function using a variable number of arguments in
1416 Win16, specify the function as taking no arguments. The arguments
1417 are then available with CURRENT_STACK16->args. In Win32, specify
1418 the function as <literal>varargs</literal> and declare it with a
1419 '...' parameter in the C file. See the wsprintf* functions in
1420 <filename>user.spec</filename> and
1421 <filename>user32.spec</filename> for an example.
1425 ORDINAL stub EXPORTNAME
1428 This field can be present zero or more times.
1429 Each instance defines a stub function. It makes the ordinal
1430 available for dynamic linking, but will terminate execution with
1431 an error message if the function is ever called.
1435 ORDINAL extern EXPORTNAME SYMBOLNAME
1438 This field can be present zero or more times.
1439 Each instance defines an entry that simply maps to a Wine symbol
1440 (variable or function); <literal>EXPORTNAME</literal> will point
1441 to the symbol <literal>SYMBOLNAME</literal> that must be defined
1442 in C code. This type only works with Win32.
1446 ORDINAL forward EXPORTNAME SYMBOLNAME
1449 This field can be present zero or more times.
1450 Each instance defines an entry that is forwarded to another entry
1451 point (kind of a symbolic link). <literal>EXPORTNAME</literal>
1452 will forward to the entry point <literal>SYMBOLNAME</literal>
1453 that must be of the form <literal>DLL.Function</literal>. This
1454 type only works with Win32.
1458 <sect1 id="linking">
1459 <title id="linking.title">Linking it all together</title>
1460 <!-- FIXME: This is outdated -->
1462 To link an executable you need to link together: your object files,
1463 the spec file, any Windows libraries that your application depends
1464 on, gdi32 for instance, and any additional library that you use. All
1465 the libraries you link with should be available as '.so' libraries.
1466 If one of them is available only in '.dll' form then consult
1467 <xref linkend="bindlls" endterm="bindlls.title">.
1470 It is also when attempting to link your executable that you will
1471 discover whether you have missing symbols or not in your custom
1472 libraries. On Windows when you build a library, the linker will
1473 immediately tell you if a symbol it is supposed to export is
1474 undefined. In Unix, and in Winelib, this is not the case. The symbol
1475 will silently be marked as undefined and it is only when you try to
1476 produce an executable that the linker will verify all the symbols are
1480 So before declaring victory when first converting a library to
1481 Winelib, you should first try to link it to an executable (but you
1482 would have done that to test it anyway, right?). At this point you
1483 may discover some undefined symbols that you thought were implemented
1484 by the library. Then, you to the library sources and fix it. But you
1485 may also discover that the missing symbols are defined in, say,
1486 gdi32. This is because you did not link the said library with gdi32.
1487 One way to fix it is to link this executable, and any other that also
1488 uses your library, with gdi32. But it is better to go back to your
1489 library's makefile and explicitly link it with gdi32.
1492 As you will quickly notice, this has unfortunately not been
1493 (completely) done for Winelib's own libraries. So if an application
1494 must link with ole32, you will also need to link with advapi32,
1495 rpcrt4 and others even if you don't use them directly. This can be
1496 annoying and hopefully will be fixed soon (feel free to submit a
1499 <!-- FIXME: try to give some sort of concrete example -->
1504 <title id="mfc.title">Dealing with the MFC</title>
1505 <sect1 id="mfc-introduction">
1506 <title id="mfc-introduction.title">Introduction</title>
1508 To use the MFC in a Winelib application you will first have to
1509 recompile the MFC with Winelib. In theory it should be possible to
1510 write a wrapper for the Windows MFC as described in
1511 <xref linkend="bindlls" endterm="bindlls.title">. But in practice
1512 it does not seem to be a realistic approach for the MFC:
1517 the huge number of APIs makes writing the wrapper a big task in
1523 furthermore the MFC contain a huge number of APIs which are tricky
1524 to deal with when making a wrapper.
1529 even once you have written the wrapper you will need to modify
1530 the MFC headers so that the compiler does not choke on them.
1535 a big part of the MFC code is actually in your application in
1536 the form of macros. This means even more of the MFC headers have
1537 to actually work to in order for you to be able to compile an
1538 MFC based application.
1543 This is why this guide includes a section dedicated to helping you
1544 compile the MFC with Winelib.
1547 <sect1 id="mfc-legal-issues">
1548 <title id="mfc-legal-issues.title">Legal issues</title>
1550 (Extracted from the HOWTO-Winelib written by Wilbur Dale
1551 <wilbur.dale@lumin.nl>)
1554 The purpose of this section is to make you aware of potential legal
1555 problems. Be sure to read your licenses and to consult your lawyers.
1556 In any case you should not consider the remainder of this section to
1557 be authoritative since it has not been written by a lawyer.
1560 Well, let's try to have a look at the situation anyway.
1563 During the compilation of your program, you will be combining code
1564 from several sources: your code, Winelib code, Microsoft MFC code,
1565 and possibly code from other vendor sources. As a result, you must
1566 ensure that the licenses of all code sources are obeyed. What you are
1567 allowed and not allowed to do can vary depending on how you compile
1568 your program and if you will be distributing it. For example, if you
1569 are releasing your code under the GPL, you cannot link your code to
1570 MFC code because the GPL requires that you provide ALL sources to your
1571 users. The MFC license forbids you from distributing the MFC source so
1572 you cannot both distribute your program and comply with the GPL
1573 license. On the other hand, if your code is released under the LGPL,
1574 you cannot statically link your program to the MFC and distribute it,
1575 but you can dynamically link your LGPL code and the MFC library and
1579 Wine/Winelib is distributed under an X11-like license. It places few
1580 restrictions on the use and distribution of Wine/Winelib code. I doubt
1581 the Wine license will cause you any problems. On the other hand, MFC
1582 is distributed under a very restrictive license and the restrictions
1583 vary from version to version and between service packs. There are
1584 basically three aspects you must be aware of when using the MFC.
1587 First you must legally get MFC source code on your computer. The MFC
1588 source code comes as a part of Visual Studio. The license for
1589 Visual Studio implies it is a single product that can not
1590 be broken up into its components. So the cleanest way to get MFC on
1591 your system is to buy Visual Studio and install it on a dual boot
1595 Then you must check that you are allowed to recompile MFC on a
1596 non-Microsoft operating system! This varies with the version of MFC.
1597 The MFC license from Visual Studio 6.0 reads in part:
1601 1.1 General License Grant. Microsoft grants to you as an
1602 individual, a personal, nonexclusive license to make and use
1603 copies of the SOFTWARE PRODUCT for the sole purposes of designing,
1604 developing, and testing your software product(s) that are designed
1605 to operate in conjunction with any Microsoft operating system
1606 product. [Other unrelated stuff deleted.]
1610 So it appears you cannot even compile MFC for Winelib using this
1611 license. Fortunately the Visual Studio 6.0 service pack 3 license
1612 reads (the Visual Studio 5.0 license is similar):
1616 1.1 General License Grant. Microsoft grants to you as an
1617 individual, a personal, nonexclusive license to make and use
1618 copies of the SOFTWARE PRODUCT for the purpose of designing,
1619 developing, and testing your software product(s). [Other unrelated
1624 So under this license it appears you can compile MFC for Winelib.
1627 Finally you must check whether you have the right to distribute an
1628 MFC library. Check the relevant section of the license on
1629 <quote>redistributables and your redistribution rights</quote>. The
1630 license seems to specify that you only have the right to distribute
1631 binaries of the MFC library if it has no debug information and if
1632 you distribute it with an application that provides significant
1633 added functionality to the MFC library.
1634 <!-- FIXME: quote relevant sections of EULA in above paragraph. -->
1637 <sect1 id="mfc-compiling">
1638 <title id="mfc-compiling.title">Compiling the MFC</title>
1641 why we have to disable them (lack of Wine support),
1642 where things don't compile,
1645 what to put in the Makefile,
1646 maybe try to point to a place with a ready-made makefile...
1649 <sect1 id="mfc-using">
1650 <title id="mfc-using.title">Using the MFC</title>
1654 Specific winemaker options,
1655 the configure options,
1656 the initialization problem...
1661 <chapter id="bindlls">
1662 <title id="bindlls.title">Dealing with binary only dlls</title>
1663 <sect1 id="bindlls-intro">
1664 <title id="binary-dlls-intro.title">Introduction</title>
1666 describe the problem,
1667 use an example and reuse it in the following sections...
1670 <sect1 id="bindlls-spec">
1671 <title id="bindlls-spec.title">Writing the spec file</title>
1676 <sect1 id="bindlls-cxx-apis">
1677 <title id="bindlls-cxx-apis.title">How to deal with C++ APIs</title>
1679 names are mangled, how to demangle them, how to call them
1682 <sect1 id="bindlls-wrapper">
1683 <title id="bindlls-wrapper.title">Writing the wrapper</title>
1690 <chapter id="packaging">
1691 <title id="packaging.title">Packaging your Winelib application</title>
1693 Selecting which libraries to deliver,
1694 how to avoid interference with other Winelib applications,
1695 how to play nice with other Winelib applications
1701 <!-- Keep this comment at the end of the file
1704 sgml-parent-document:("wine-doc.sgml" "set" "book" "")
projects / wine / blob