Move the data around when the ring buffer is resized so that the empty
[wine] / documentation / winelib-toolkit.sgml
1   <chapter id="winelib-toolkit">
2     <title id="winelib-toolkit.title">The Winelib development toolkit</title>
3
4     <sect1 id="winemaker">
5       <title id="winemaker.title">Winemaker</title>
6
7       <sect2 id="vc-projects">
8         <title id="vc-projects.title">Support for Visual C++ projects</title>
9         <para>
10           Unfortunately Winemaker does not support the Visual C++ project 
11           files, ...yet. Supporting Visual C++ project files (the 
12           <filename>.dsp</filename> and some <filename>.mak</filename> files 
13           for older versions of Visual C++) is definitely on 
14           the list of important Winemaker improvements as it will allow it to 
15           properly detect the defines to be used, any custom include path, the 
16           list of libraries to link with, and exactly which source files to use
17           to build a specific target. All things that the current version of 
18           Winemaker has to guess or that you have to tell it as will become 
19           clear in the next section.
20         </para>
21         <para>
22           When the time comes Winemaker, and its associated build system, will 
23           need some extensions to support:
24         </para>
25         <itemizedlist>
26           <listitem>
27             <para>
28               per file defines and include paths. Visual C++ projects allow 
29               the user to specify compiler options for each individual file 
30               being compiled. But this is probably not very frequent so it 
31               might not be that important.
32             </para>
33           </listitem>
34           <listitem>
35             <para>
36               multiple configurations. Visual C++ projects usually have at 
37               least a 'Debug' and a 'Release' configuration which are compiled 
38               with different compiler options. How exactly we deal with these 
39               configurations remains to be determined.
40             </para>
41           </listitem>
42         </itemizedlist>
43       </sect2>
44
45       <sect2 id="source-analysis">
46         <title id="source-analysis.title">Winemaker's source analysis</title>
47         <para>
48           Winemaker can do its work even without a Windows makefile or a 
49           Visual Studio project to start from (it would not know what to do 
50           with a windows makefile anyway). This involves doing many educated 
51           guesses which may be wrong. But by and large it works. The purpose 
52           of this section is to describe in more details how winemaker 
53           proceeds so that you can better understand why it gets things 
54           wrong and how to fix it/avoid it.
55         </para>
56         <para>
57           At the core winemaker does a recursive traversal of 
58           your source tree looking for targets (things to build) and source 
59           files. Let's start with the targets.
60         </para>
61         <para>
62           First are executables and DLLs. Each time it finds one of these in 
63           a directory, winemaker puts it in the list of things to build and 
64           will later generate a <filename>Makefile.in</filename> file in this 
65           directory. Note that Winemaker also knows about the commonly used 
66           <filename>Release</filename> and <filename>Debug</filename> 
67           directories, so it will attribute the executables and libraries 
68           found in these to their parent directory. When it finds an 
69           executable or a DLL winemaker is happy because these give it more 
70           information than the other cases described below.
71         </para>
72         <para>
73           If it does not find any executable or DLL winemaker will look for 
74           files with a <filename>.mak</filename> extension. If they are not 
75           disguised Visual C++ projects (and currently even if they are), 
76           winemaker will assume that a target by that name should be built 
77           in this directory. But it will not know whether this target is an 
78           executable or a library. So it will assume it is of the default 
79           type, i.e. a graphical application, which you can override by using 
80           the <option>--cuiexe</option> and <option>--dll</option> options.
81         </para>
82         <para>
83           Finally winemaker will check to see if there is a file called 
84           <filename>makefile</filename>. If there is, then it will assume 
85           that there is exactly one target to build for this directory. But 
86           it will not know the name or type of this target. For the type it 
87           will do as in the above case. And for the name it will use the 
88           directory's name. Actually, if the directory starts with 
89           <filename>src</filename> winemaker will try to make use of the name 
90           of the parent directory instead.
91         </para>
92         <para>
93           Once the target list for a directory has been established, 
94           winemaker will check whether it contains a mix of executables and 
95           libraries. If it is so, then winemaker will make it so that each 
96           executable is linked with all the libraries of that directory.
97         </para>
98         <para>
99           If the previous two steps don't produce the expected results (or 
100           you think they will not) then you should put winemaker in 
101           interactive mode (see <xref linkend="interactive" 
102           endterm="interactive.title">). This will allow you to specify the 
103           target list (and more) for each directory.
104         </para>
105         <para>
106           In each directory winemaker also looks for source files: C, C++ 
107           or resource files. If it also found targets to build in this 
108           directory it will then try to assign each source file to one of 
109           these targets based on their names. Source files that do not seem 
110           to match any specific target are put in a global list for this 
111           directory, see the <literal>EXTRA_xxx</literal> variables in the 
112           <filename>Makefile.in</filename>, and linked with each of the 
113           targets. The assumption here is that these source files contain 
114           common code which is shared by all the targets.
115           If no targets were found in the directory where these files are 
116           located, then they are assigned to the parent's directory. So if a 
117           target is found in the parent directory it will also 'inherit' the 
118           source files found in its subdirectories.
119         </para>
120         <para>
121           Finally winemaker also looks for more exotic files like 
122           <filename>.h</filename> headers, <filename>.inl</filename> files 
123           containing inline functions and a few others. These are not put in 
124           the regular source file lists since they are not compiled directly. 
125           But winemaker will still remember them so that they are processed 
126           when the time comes to fix the source files.
127         </para>
128         <para>
129           Fixing the source files is done as soon as winemaker has finished 
130           its recursive directory traversal. The two main tasks in this step 
131           are fixing the CRLF issues and verifying the case of the include 
132           statements.
133         </para>
134         <para>
135           Winemaker makes a backup of each source file (in such a way that 
136           symbolic links are preserved), then reads it fixing the CRLF 
137           issues and the other issues as it goes. Once it has finished 
138           working on a file it checks whether it has done any non 
139           CRLF-related modification and deletes the backup file if it did 
140           not (or if you used <option>--nobackup</option>).
141         </para>
142         <para>
143           Checking the case of the include statements (of any form, 
144           including files referenced by resource files), is done in the 
145           context of that source file's project. This way winemaker can use 
146           the proper include path when looking for the file that is included. 
147           If winemaker fails to find a file in any of the directories of the 
148           include path, it will rename it to lowercase on the basis that it 
149           is most likely a system header and that all system headers names 
150           are lowercase (this can be overridden by using 
151           <option>--nolower-include</option>).
152         </para>
153         <para>
154           Finally winemaker generates the <filename>Makefile.in</filename> 
155           files and other support files (wrapper files, spec files, 
156           <filename>configure.in</filename>, 
157           <filename>Make.rules.in</filename>). From the above description 
158           you can guess at the items that winemaker may get wrong in 
159           this phase: macro definitions, include path, DLL path, DLLs to
160           import, library path, libraries to link with. You can deal with
161           these issues by using winemaker's <option>-D</>, <option>-P</>,
162           <option>-i</>, <option>-I</>, <option>-L</> and <option>-l</>
163           options if they are
164           homogeneous enough between all your targets. Otherwise you may 
165           want to use winemaker's <link linkend="interactive">interactive 
166           mode</link> so that you can specify different settings for each 
167           project / target.
168         </para>
169         <para>
170           For instance, one of the problems you are likely to encounter is 
171           that of the <varname>STRICT</varname> macro. Some programs will 
172           not compile if <varname>STRICT</varname> is not turned on, and 
173           others will not compile if it is. Fortunately all the files in a 
174           given source tree use the same setting so that all you have to do 
175           is add <literal>-DSTRICT</literal> on winemaker's command line 
176           or in the <filename>Makefile.in</filename> file(s).
177         </para>
178         <para>
179           Finally the most likely reasons for missing or duplicate symbols 
180           are:
181         </para>
182         <itemizedlist>
183           <listitem>
184             <para>
185               The target is not importing the right set of DLLs, or is not
186               being linked with the right set of libraries. You can avoid
187               this by using winemaker's <option>-P</>, <option>-i</>,
188               <option>-L</option> and <option>-l</> options or adding these
189               DLLs and libraries to the <filename>Makefile.in</> file.
190             </para>
191           </listitem>
192           <listitem>
193             <para>
194               Maybe you have multiple targets in a single directory and 
195               winemaker guessed wrong when trying to match the source files 
196               with the targets. The only way to fix this kind of problem is 
197               to edit the <filename>Makefile.in</filename> file manually.
198             </para>
199           </listitem>
200           <listitem>
201             <para>
202               Winemaker assumes you have organized your source files 
203               hierarchically. If a target uses source files that are in a 
204               sibling directory, e.g. if you link with 
205               <filename>../hello/world.o</filename> then you will get missing 
206               symbols. Again the only solution is to manually edit the 
207               <filename>Makefile.in</filename> file.
208             </para>
209           </listitem>
210         </itemizedlist>
211       </sect2>
212
213       <sect2 id="interactive">
214         <title id="interactive.title">The interactive mode</title>
215         <para>
216           what is it, 
217           when to use it,
218           how to use it
219         </para>
220       </sect2>
221
222       <sect2 id="Makefile.in">
223         <title id="Makefile.in.title">The Makefile.in files</title>
224         <para>
225           The <filename>Makefile.in</filename> is your makefile. More 
226           precisely it is the template from which the actual makefile will 
227           be generated by the <filename>configure</filename> script. It also 
228           relies on the <filename>Make.rules</filename> file for most of 
229           the actual logic. This way it only contains a relatively simple 
230           description of what needs to be built, not the complex logic of 
231           how things are actually built.
232         </para>
233         <para>
234           So this is the file to modify if you want to customize things. 
235           Here's a detailed description of its content:
236         </para>
237         <programlisting>
238 ### Generic autoconf variables
239
240 TOPSRCDIR             = @top_srcdir@
241 TOPOBJDIR             = .
242 SRCDIR                = @srcdir@
243 VPATH                 = @srcdir@
244         </programlisting>
245         <para>
246           The above is part of the standard autoconf boiler-plate. These 
247           variables make it possible to have per-architecture directories for 
248           compiled files and other similar goodies (But note that this kind 
249           of functionality has not been tested with winemaker generated 
250           <filename>Makefile.in</filename> files yet).
251         </para>
252         <programlisting>
253 SUBDIRS               =
254 DLLS                  =
255 EXES                  = hello.exe
256         </programlisting>
257         <para>
258           This is where the targets for this directory are listed. The names 
259           are pretty self-explanatory. <varname>SUBDIRS</varname> is usually 
260           only present in the top-level makefile. For libraries and
261           executables, specify the full name, including the '.dll' or '.exe'
262           extension. Note that these names must be in all lowercase.
263         </para>
264         <programlisting>
265 ### Global settings
266
267 DEFINES               = -DSTRICT
268 INCLUDE_PATH          =
269 DLL_PATH              =
270 LIBRARY_PATH          =
271 LIBRARIES             =
272         </programlisting>
273         <para>
274           This section contains the global compilation settings: they apply
275           to all the targets in this makefile. The <varname>LIBRARIES</>
276           variable allows you to specify additional Unix libraries to link
277           with. Note that you would normally not specify Winelib libraries
278           there. To link with a Winelib library, one uses the <varname>DLLS</>
279           variables of the Makefile. The exception is for C++ libraries where
280           you currently don't have  a choice but to link with them in the
281           Unix sense. One library you are likely to find here is 
282           <literal>mfc</> (note, the '-l' is omitted).
283         </para>
284         <para>
285           The other variable 
286           names should be self-explanatory. You can also use three additional 
287           variables that are usually not present in the file: 
288           <varname>CEXTRA</varname>, <varname>CXXEXTRA</varname> and 
289           <varname>WRCEXTRA</varname> which allow you to specify additional 
290           flags for, respectively, the C compiler, the C++ compiler and the 
291           resource compiler. Finally note that all these variable contain 
292           the option's name.
293         </para>
294         <para>
295           Then come one section per target, each describing the various 
296           components that target is made of.
297         </para>
298         <programlisting>
299 ### hello.exe sources and settings
300
301 hello_exe_C_SRCS          = hello.c
302 hello_exe_CXX_SRCS        =
303 hello_exe_RC_SRCS         =
304 hello_exe_SPEC_SRCS       =
305         </programlisting>
306         <para>
307           Each section will start with a comment indicating the name of the 
308           target. Then come a series of variables prefixed with the name of 
309           that target. Note that the name of the prefix may be slightly 
310           different from that of the target because of restrictions on the 
311           variable names.
312         </para>
313         <para>
314           The above variables list the sources that are used togenerate the 
315           target. Note that there should only be one resource file in 
316           <varname>RC_SRCS</varname>, and that <varname>SPEC_SRCS</varname> 
317           will usually be empty for executables, and will contain a single
318           spec file for libraries.
319         </para>
320         <programlisting>
321 hello_exe_DLL_PATH        =
322 hello_exe_DLLS            =
323 hello_exe_LIBRARY_PATH    =
324 hello_exe_LIBRARIES       =
325 hello_exe_DEPENDS         =
326         </programlisting>
327         <para>
328           The above variables specify how to link the target. Note that they 
329           add to the global settings we saw at the beginning of this file.
330         </para>
331         <para>
332           The <varname>DLLS</> field is where you would enumerate the list of
333           DLLs that executable imports. It should contain the full DLL name
334           including the '.dll' extension, but not the '-l' option.
335         </para>
336         <para>
337           <varname>DEPENDS</>, when present, specifies a list of other 
338           targets that this target depends on. Winemaker will automatically 
339           fill this field when an executable and a library are built in the
340           same directory.
341         </para>
342         <programlisting>
343 hello_exe_OBJS        = $(hello_exe_C_SRCS:.c=.o) \
344                         $(hello_exe_CXX_SRCS:.cpp=.o) \
345                         $(EXTRA_OBJS)
346         </programlisting>
347         <para>
348           The above just builds a list of all the object files that 
349           correspond to this target. This list is later used for the link 
350           command.
351         </para>
352         <programlisting>
353 ### Global source lists
354
355 C_SRCS                = $(hello_exe_C_SRCS)
356 CXX_SRCS              = $(hello_exe_CXX_SRCS)
357 RC_SRCS               = $(hello_exe_RC_SRCS)
358 SPEC_SRCS             = $(hello_exe_SPEC_SRCS)
359         </programlisting>
360         <para>
361           This section builds 'summary' lists of source files. These lists are 
362           used by the <filename>Make.rules</filename> file.
363         </para>
364         <note><para>
365           FIXME:The following is not up-to-date.
366         </para></note>
367         <programlisting>
368 ### Generic autoconf targets
369
370 all: $(DLLS:%=%.so) $(EXES:%=%.so)
371
372 @MAKE_RULES@
373
374 install::
375         for i in $(EXES); do $(INSTALL_PROGRAM) $$i $(bindir); done
376         for i in $(EXES:%=%.so) $(DLLS); do $(INSTALL_LIBRARY) $$i $(libdir); done
377
378 uninstall::
379         for i in $(EXES); do $(RM) $(bindir)/$$i;done
380         for i in $(EXES:%=%.so) $(DLLS); do $(RM) $(libdir)/$$i;done
381         </programlisting>
382         <para>
383           The above first defines the default target for this makefile. Here 
384           it consists in trying to build all the targets. Then it includes 
385           the <filename>Make.rules</filename> file which contains the build 
386           logic, and provides a few more standard targets to install / 
387           uninstall the targets. 
388         </para>
389         <programlisting>
390 ### Target specific build rules
391
392 $(hello_SPEC_SRCS:.spec=.tmp.o): $(hello_OBJS)
393         $(LDCOMBINE) $(hello_OBJS) -o $@
394         -$(STRIP) $(STRIPFLAGS) $@
395
396 $(hello_SPEC_SRCS:.spec=.spec.c): $(hello_SPEC_SRCS:.spec) $(hello_SPEC_SRCS:.spec=.tmp.o) $(hello_RC_SRCS:.rc=.res)
397         $(WINEBUILD) -fPIC $(hello_LIBRARY_PATH) $(WINE_LIBRARY_PATH) -sym $(hello_SPEC_SRCS:.spec=.tmp.o) -o $@ -spec $(hello_SPEC_SRCS)
398
399 hello.so: $(hello_SPEC_SRCS:.spec=.spec.o) $(hello_OBJS) $(hello_DEP
400 ENDS) 
401         $(LDSHARED) $(LDDLLFLAGS) -o $@ $(hello_OBJS) $(hello_SPEC_SRCS:.spec=.spec.o) $(hello_LIBRARY_PATH) $(hello_LIBRARIES:%=-l%) $(DLL_LINK) $(LIBS)
402         test -f hello || $(LN_S) $(WINE) hello
403         </programlisting>
404         <para>
405           Then come additional directives to link the executables and 
406           libraries. These are pretty much standard and you should not need 
407           to modify them.
408         </para>
409       </sect2>
410
411       <sect2 id="Make.rules.in">
412         <title id="Make.rules.in.title">The Make.rules.in file</title>
413         <para>
414           What's in the Make.rules.in...
415         </para>
416       </sect2>
417
418       <sect2 id="configure.in">
419         <title id="configure.in.title">The configure.in file</title>
420         <para>
421           What's in the configure.in...
422         </para>
423       </sect2>
424     </sect1>
425
426     <sect1 id="wrc">
427       <title id="wrc.title">Compiling resource files: WRC</title>
428       <para>
429         To compile resources you should use the Wine Resource Compiler, 
430         wrc for short, which produces a binary <filename>.res</filename> 
431         file. This resource file is then used by winebuild when compiling 
432         the spec file (see <xref linkend="spec-file" 
433         endterm="spec-file.title">).
434       </para>
435       <para>
436         Again the makefiles generated by winemaker take care of this for you. 
437         But if you were to write your own makefile you would put something 
438         like the following:
439       </para>
440       <programlisting>
441 WRC=$(WINE_DIR)/tools/wrc/wrc
442
443 WINELIB_FLAGS = -I$(WINE_DIR)/include -DWINELIB -D_REENTRANT
444 WRCFLAGS      = -r -L
445
446 .SUFFIXES: .rc .res
447
448 .rc.res:
449         $(WRC) $(WRCFLAGS) $(WINELIB_FLAGS) -o $@ $<
450       </programlisting>
451       <para>
452         There are two issues you are likely to encounter with resource files.
453       </para>
454       <para>
455         The first problem is with the C library headers. WRC does not know 
456         where these headers are located. So if an RC file, of a file it 
457         includes, references such a header you will get a 'file not found' 
458         error from wrc. Here are a few ways to deal with this:
459       </para>
460       <itemizedlist>
461         <listitem>
462           <para>
463             The solution traditionally used by the Winelib headers is to 
464             enclose the offending include statement in an 
465             <literal>#ifndef RC_INVOKED</literal> statement where 
466             <varname>RC_INVOKED</varname> is a macro name which is 
467             automatically defined by wrc.
468           </para>
469         </listitem>
470         <listitem>
471           <para>
472             Alternately you can add one or more <option>-I</option> directive 
473             to your wrc command so that it finds you system files. For 
474             instance you may add <literal>-I/usr/include 
475             -I/usr/lib/gcc-lib/i386-linux/2.95.2/include</literal> to cater 
476             to both C and C++ headers. But this supposes that you know where 
477             these header files reside which decreases the portability of your 
478             makefiles to other platforms (unless you automatically detect all 
479             the necessary directories in the autoconf script).
480           </para>
481           <para>
482             Or you could use the C/C++ compiler to perform the preprocessing. 
483             To do so, simply modify your makefile as follows:
484           </para>
485           <programlisting>
486 .rc.res:
487         $(CC) $(CC_OPTS) -DRC_INVOKED -E -x c $< | $(WRC) -N $(WRCFLAGS) $(WINELIB_FLAGS) -o $@
488
489           </programlisting>
490           <!-- FIXME: does this still cause problems for the line numbers? -->
491         </listitem>
492       </itemizedlist>
493       <para>
494         The second problem is that the headers may contain constructs that 
495         WRC fails to understand. A typical example is a function which return 
496         a 'const' type. WRC expects a function to be two identifiers followed 
497         by an opening parenthesis. With the const this is three identifiers 
498         followed by a parenthesis and thus WRC is confused (note: WRC should 
499         in fact ignore all this like the windows resource compiler does). 
500         The current work-around is to enclose offending statement(s) in an 
501         <literal>#ifndef RC_INVOKED</literal>.
502       </para>
503
504       <para>
505         Using GIF files in resources is problematic. For best results,
506         convert them to BMP and change your <filename>.res</filename>
507         file.
508       </para>
509       <para>
510         If you use common controls/dialogs in your resource files, you
511         will need to add <function>#include &lt;commctrl.h></function>
512         after the <function>#include &lt;windows.h></function> line,
513         so that <command>wrc</command> knows the values of control
514         specific flags.
515       </para>
516     </sect1>
517
518     <sect1 id="wmc">
519       <title id="wmc.title">Compiling message files: WMC</title>
520       <para>
521         how does one use it???
522       </para>
523     </sect1>
524
525     <sect1 id="spec-file">
526       <title id="spec-file.title">The Spec file</title>
527
528       <sect2 id="spec-intro">
529         <title id="spec-intro.title">Introduction</title>
530         <para>
531           In Windows the program's life starts either when its 
532           <function>main</function> is called,  for console applications, or 
533           when its <function>WinMain</function> is called, for windows 
534           applications in the 'windows' subsystem. On Unix it is always 
535           <function>main</function> that is called. Furthermore in Winelib it 
536           has some special tasks to accomplish, such as initializing Winelib, 
537           that a normal <function>main</function> does not have to do.
538         </para>
539         <para>
540           Furthermore windows applications and libraries contain some 
541           information which are necessary to make APIs such as 
542           <function>GetProcAddress</function> work. So it is necessary to 
543           duplicate these data structures in the Unix world to make these 
544           same APIs work with Winelib applications and libraries.
545         </para>
546         <para>
547           The spec file is there to solve the semantic gap described above. 
548           It provides the <function>main</function> function that initializes 
549           Winelib and calls the module's <function>WinMain</function> / 
550           <function>DllMain</function>, and it contains information about 
551           each API exported from a Dll so that the appropriate tables can be 
552           generated.
553         </para>
554         <para>
555           A typical spec file will look something like this:
556         </para>
557         <screen>
558 init    WinMain
559 rsrc    resource.res
560         </screen>
561         <para>
562           And here are the entries you will probably want to change: 
563         </para>
564         <variablelist>
565           <varlistentry>
566             <term>init</term>
567             <listitem>
568               <para>
569                 <literal>init</literal> defines what is the entry point of 
570                 that module. For a library this is customarily set to 
571                 <literal>DllMain</literal>, for a console application this 
572                 is <literal>main</literal> and for a graphical application 
573                 this is <literal>WinMain</literal>.
574               </para>
575             </listitem>
576           </varlistentry>
577           <varlistentry>
578             <term>rsrc</term>
579             <listitem>
580               <para>
581                 This item specifies the name of the compiled resource file 
582                 to link with your module. If your resource file is called 
583                 <filename>hello.rc</filename> then the wrc compilation step
584                 (see <xref linkend="wrc" endterm="wrc.title">) will generate 
585                 a file called <filename>hello.res</filename>. This is the 
586                 name you must provide here. Note that because of this you 
587                 cannot compile the spec file before you have compiled the 
588                 resource file. So you should put a rule like the following 
589                 in your makefile:
590               </para>
591               <programlisting>
592 hello.spec.c: hello.res
593               </programlisting>
594               <para>
595                 If your project does not have a resource file then you must 
596                 omit this entry altogether.
597               </para>
598             </listitem>
599           </varlistentry>
600           <varlistentry>
601             <term>@</term>
602             <listitem>
603               <note><para>
604                 FIXME: You must now export functions from DLLs.
605               </para></note>
606               <para>
607                 This entry is not shown above because it is not always 
608                 necessary. In fact it is only necessary to export functions 
609                 when you plan to dynamically load the library with 
610                 <function>LoadLibrary</function> and then do a 
611                 <function>GetProcAddress</function> on these functions. 
612                 This is not necessary if you just plan on linking with the 
613                 library and calling the functions normally. For more details 
614                 about this see: <xref linkend="spec-reference" 
615                 endterm="spec-reference.title">.
616               </para>
617             </listitem>
618           </varlistentry>
619         </variablelist>
620       </sect2>
621
622       <sect2 id="spec-compiling">
623         <title id="spec-compiling.title">Compiling it</title>
624           <note><para>
625             FIXME: This section is very outdated and does not correctly
626             describe the current use of winebuild and spec files. In
627             particular, with recent versions of winebuild most of the
628             information that used to be in the spec files is now specified on
629             the command line.
630           </para></note>
631           <para>
632             Compiling a spec file is a two step process. It is first 
633             converted into a C file by winebuild, and then compiled into an 
634             object file using your regular C compiler. This is all taken 
635             care of by the winemaker generated makefiles of course. But 
636             here's what it would like if you had to do it by hand:
637           </para>
638           <screen>
639 WINEBUILD=$(WINE_DIR)/tools/winebuild
640
641 .SUFFIXES: .spec .spec.c .spec.o
642
643 .spec.spec.c:
644         $(WINEBUILD) -fPIC -o $@ -spec $<
645
646 .spec.c.spec.o:
647         $(CC) -c -o $*.spec.o $<
648           </screen>
649           <para>
650             Nothing really complex there. Just don't forget the 
651             <literal>.SUFFIXES</literal> statement, and beware of the tab if 
652             you copy this straight to your Makefile.
653           </para>
654       </sect2>
655
656       <sect2 id="spec-reference">
657         <title id="spec-reference.title">More details</title>
658
659         <para>
660           Here is a more detailed description of the spec file's format.
661         </para>
662
663         <programlisting>
664 # comment text
665         </programlisting>
666         <para>
667           Anything after a '#' will be ignored as comments.
668         </para>
669
670         <programlisting>
671 init    FUNCTION
672         </programlisting>
673         <para>
674           This field is optional and specific to Win32 modules. It 
675           specifies a function which will be called when the DLL is loaded 
676           or the executable started.
677         </para>
678
679         <programlisting>
680 rsrc    RES_FILE
681         </programlisting>
682         <para>
683           This field is optional. If present it specifies the name of the 
684           .res file containing the compiled resources. See <xref 
685           linkend="wrc" endterm="wrc.title"> for details on compiling a 
686           resource file.
687         </para>
688
689         <programlisting>
690 ORDINAL VARTYPE EXPORTNAME (DATA [DATA [DATA [...]]])
691 2 byte Variable(-1 0xff 0 0)
692         </programlisting>
693         <para>
694           This field can be present zero or more times.
695           Each instance defines data storage at the ordinal specified. You 
696           may store items as bytes, 16-bit words, or 32-bit words.
697           <literal>ORDINAL</literal> is replaced by the ordinal number 
698           corresponding to the variable. <literal>VARTYPE</literal> should 
699           be <literal>byte</literal>, <literal>word</literal> or 
700           <literal>long</literal> for 8, 16, or 32 bits respectively. 
701           <literal>EXPORTNAME</literal> will be the name available for
702           dynamic linking. <literal>DATA</literal> can be a decimal number 
703           or a hex number preceded by "0x". The example defines the 
704           variable <literal>Variable</literal> at ordinal 2 and containing 
705           4 bytes.
706         </para>
707
708         <programlisting>
709 ORDINAL equate EXPORTNAME DATA
710         </programlisting>
711         <para>
712           This field can be present zero or more times.
713           Each instance defines an ordinal as an absolute value.
714           <literal>ORDINAL</literal> is replaced by the ordinal number 
715           corresponding to the variable. <literal>EXPORTNAME</literal> will 
716           be the name available for dynamic linking. 
717           <literal>DATA</literal> can be a decimal number or a hex number 
718           preceded by "0x".
719         </para>
720
721         <programlisting>
722 ORDINAL FUNCTYPE EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
723 100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word
724                         word word word ptr)
725            WIN_CreateWindow
726 101 pascal GetFocus() WIN_GetFocus()
727         </programlisting>
728         <para>
729           This field can be present zero or more times.
730           Each instance defines a function entry point. The prototype 
731           defined by <literal>EXPORTNAME ([ARGTYPE [ARGTYPE [...]]])</literal> 
732           specifies the name available for dynamic linking and the format 
733           of the arguments. <literal>ORDINAL</literal> is replaced
734           by the ordinal number corresponding to the function, or 
735           <literal>@</literal> for automatic ordinal allocation (Win32 only).
736         </para>
737         <para>
738           <literal>FUNCTYPE</literal> should be one of:
739         </para>
740         <variablelist>
741           <varlistentry>
742             <term>pascal16</term>
743             <listitem>
744               <para>
745                 for a Win16 function returning a 16-bit value
746               </para>
747             </listitem>
748           </varlistentry>
749           <varlistentry>
750             <term>pascal</term>
751             <listitem>
752               <para>
753                 for a Win16 function returning a 32-bit value
754               </para>
755             </listitem>
756           </varlistentry>
757           <varlistentry>
758             <term>register</term>
759             <listitem>
760               <para>
761                 for a function using CPU register to pass arguments
762               </para>
763             </listitem>
764           </varlistentry>
765           <varlistentry>
766             <term>interrupt</term>
767             <listitem>
768               <para>
769                 for a Win16 interrupt handler routine
770               </para>
771             </listitem>
772           </varlistentry>
773           <varlistentry>
774             <term>stdcall</term>
775             <listitem>
776               <para>
777                 for a normal Win32 function
778               </para>
779             </listitem>
780           </varlistentry>
781           <varlistentry>
782             <term>cdecl</term>
783             <listitem>
784               <para>
785                 for a Win32 function using the C calling convention
786               </para>
787             </listitem>
788           </varlistentry>
789           <varlistentry>
790             <term>varargs</term>
791             <listitem>
792               <para>
793                 for a Win32 function taking a variable number of arguments
794               </para>
795             </listitem>
796           </varlistentry>
797         </variablelist>
798
799         <para>
800           <literal>ARGTYPE</literal> should be one of:
801         </para>
802         <variablelist>
803           <varlistentry>
804             <term>word</term>
805             <listitem>
806               <para>
807                 for a 16 bit word
808               </para>
809             </listitem>
810           </varlistentry>
811           <varlistentry>
812             <term>long</term>
813             <listitem>
814               <para>
815                 a 32 bit value
816               </para>
817             </listitem>
818           </varlistentry>
819           <varlistentry>
820             <term>ptr</term>
821             <listitem>
822               <para>
823                 for a linear pointer
824               </para>
825             </listitem>
826           </varlistentry>
827           <varlistentry>
828             <term>str</term>
829             <listitem>
830               <para>
831                 for a linear pointer to a null-terminated string
832               </para>
833             </listitem>
834           </varlistentry>
835           <varlistentry>
836             <term>s_word</term>
837             <listitem>
838               <para>
839                 for a 16 bit signed word
840               </para>
841             </listitem>
842           </varlistentry>
843           <varlistentry>
844             <term>segptr</term>
845             <listitem>
846               <para>
847                 for a segmented pointer
848               </para>
849             </listitem>
850           </varlistentry>
851           <varlistentry>
852             <term>segstr</term>
853             <listitem>
854               <para>
855                 for a segmented pointer to a null-terminated string
856               </para>
857             </listitem>
858           </varlistentry>
859           <varlistentry>
860             <term>wstr</term>
861             <listitem>
862               <para>
863                 for a linear pointer to a null-terminated wide
864                 (16-bit Unicode) string
865               </para>
866             </listitem>
867           </varlistentry>
868         </variablelist>
869
870         <para>
871           Only <literal>ptr</literal>, <literal>str</literal>,
872           <literal>wstr</literal> and
873           <literal>long</literal> are valid for Win32 functions.
874           <literal>HANDLERNAME</literal> is the name of the actual Wine 
875           function that will process the request in 32-bit mode.
876         </para>
877         <para>
878           Strings should almost always map to str, 
879           wide strings - wstr.
880           As the general rule it depends on whether the
881           parameter is IN, OUT or IN/OUT.
882         </para>
883         <itemizedlist>
884           <listitem>
885             <para>
886               IN: str/wstr
887             </para>
888           </listitem>
889           <listitem>
890             <para>
891               OUT: ptr
892             </para>
893           </listitem>
894           <listitem>
895             <para>
896               IN/OUT: str/wstr
897             </para>
898           </listitem>
899         </itemizedlist>
900         <para>
901           It is for debug messages. If the parameter is OUT
902           it might not be initialized and thus it should not
903           be printed as a string.
904         </para>
905         <para>
906           The two examples define an entry point for the 
907           <function>CreateWindow</function> and <function>GetFocus</function> 
908           calls respectively. The ordinals used are just examples.
909         </para>
910         <para>
911           To declare a function using a variable number of arguments in 
912           Win16, specify the function as taking no arguments. The arguments 
913           are then available with CURRENT_STACK16->args. In Win32, specify 
914           the function as <literal>varargs</literal> and declare it with a 
915           '...' parameter in the C file.  See the wsprintf* functions in 
916           <filename>user.spec</filename> and 
917           <filename>user32.spec</filename> for an example.
918         </para>
919
920         <programlisting>
921 ORDINAL stub EXPORTNAME
922         </programlisting>
923         <para>
924           This field can be present zero or more times.
925           Each instance defines a stub function. It makes the ordinal 
926           available for dynamic linking, but will terminate execution with 
927           an error message if the function is ever called.
928         </para>
929
930         <programlisting>
931 ORDINAL extern EXPORTNAME SYMBOLNAME
932         </programlisting>
933         <para>
934           This field can be present zero or more times.
935           Each instance defines an entry that simply maps to a Wine symbol
936           (variable or function); <literal>EXPORTNAME</literal> will point 
937           to the symbol <literal>SYMBOLNAME</literal> that must be defined 
938           in C code. This type only works with Win32.
939         </para>
940
941         <programlisting>
942 ORDINAL forward EXPORTNAME SYMBOLNAME
943         </programlisting>
944         <para>
945           This field can be present zero or more times.
946           Each instance defines an entry that is forwarded to another entry
947           point (kind of a symbolic link). <literal>EXPORTNAME</literal>
948           will forward to the entry point <literal>SYMBOLNAME</literal> 
949           that must be of the form <literal>DLL.Function</literal>. This 
950           type only works with Win32.
951         </para>
952       </sect2>
953     </sect1>
954
955     <sect1 id="linking">
956       <title id="linking.title">Linking it all together</title>
957       <note><para>
958         FIXME:The following is not up-to-date.
959       </para></note>
960       <para>
961         To link an executable you need to link together: your object files, 
962         the spec file, any Windows libraries that your application depends
963         on, gdi32 for instance, and any additional library that you use. All 
964         the libraries you link with should be available as '.so' libraries. 
965         If one of them is available only in '.dll' form then consult 
966         <xref linkend="bindlls" endterm="bindlls.title">.
967       </para>
968       <para>
969         It is also when attempting to link your executable that you will 
970         discover whether you have missing symbols or not in your custom 
971         libraries. On Windows when you build a library, the linker will 
972         immediately tell you if a symbol it is supposed to export is 
973         undefined. In Unix, and in Winelib, this is not the case. The symbol 
974         will silently be marked as undefined and it is only when you try to 
975         produce an executable that the linker will verify all the symbols are 
976         accounted for.
977       </para>
978       <para>
979         So before declaring victory when first converting a library to 
980         Winelib, you should first try to link it to an executable (but you 
981         would have done that to test it anyway, right?). At this point you 
982         may discover some undefined symbols that you thought were implemented 
983         by the library. Then, you to the library sources and fix it. But you 
984         may also discover that the missing symbols are defined in, say, 
985         gdi32. This is because you did not link the said library with gdi32. 
986         One way to fix it is to link this executable, and any other that also 
987         uses your library, with gdi32. But it is better to go back to your 
988         library's makefile and explicitly link it with gdi32.
989       </para>
990       <para>
991         As you will quickly notice, this has unfortunately not been 
992         (completely) done for Winelib's own libraries. So if an application 
993         must link with ole32, you will also need to link with advapi32, 
994         rpcrt4 and others even if you don't use them directly. This can be 
995         annoying and hopefully will be fixed soon (feel free to submit a 
996         patch).
997       </para>
998       <!-- FIXME: try to give some sort of concrete example -->
999     </sect1>
1000   </chapter>
1001
1002 <!-- Keep this comment at the end of the file
1003 Local variables:
1004 mode: sgml
1005 sgml-parent-document:("winelib-user.sgml" "book" "chapter" "")
1006 End:
1007 -->