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