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