tools/winebuild/README

   1                         Spec file format
   2                         ----------------
   3
   4 [name   NAME]
   5 [file   WINFILENAME]
   6 [mode   dll|cuiexe|guiexe|cuiexe_unicode|guiexe_unicode]
   7 [heap   SIZE]
   8 [init   FUNCTION]
   9 [rsrc   RESFILE]
  10 [ignore ([SYMBOL [SYMBOL...]])]
  11
  12 ORDINAL FUNCTYPE [FLAGS] EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
  13
  14 ORDINAL variable [FLAGS] EXPORTNAME (DATA [DATA [DATA [...]]])
  15
  16 ORDINAL stub [FLAGS] EXPORTNAME
  17
  18 ORDINAL equate [FLAGS] EXPORTNAME DATA
  19
  20 ORDINAL extern [FLAGS] EXPORTNAME SYMBOLNAME
  21
  22 ORDINAL forward [FLAGS] EXPORTNAME SYMBOLNAME
  23
  24 # COMMENT_TEXT
  25
  26 --------------------
  27 General:
  28 ========
  29
  30 All declarations are optional; reasonable defaults will be used for
  31 anything that isn't specified.
  32
  33 "name" is the internal name of the module. It is only used in Win16
  34 modules. The default is to use the base name of the spec file (without
  35 any extension). This is used for KERNEL, since it lives in
  36 KRNL386.EXE. It shouldn't be needed otherwise.
  37
  38 "file" gives the name of the file containing the dll. If not specified
  39 it is determined from the name of the source spec file. Normally you
  40 shouldn't ever need to specify it explicitly.
  41
  42 "mode" specifies whether it is the spec file for a dll or the main exe.
  43 This is only valid for Win32 spec files.
  44
  45 "heap" is the size of the module local heap (only valid for Win16
  46 modules); default is no local heap.
  47
  48 "init" specifies a function which will be called when this dll
  49 is loaded. This is only valid for Win32 modules.
  50
  51 "rsrc" specifies the path of the compiled resource file.
  52
  53 "ignore" specifies a list of symbols that should be ignored when
  54 resolving undefined symbols against the imported libraries.
  55
  56 "ORDINAL" specified the ordinal number corresponding to the entry
  57 point, or "@" for automatic ordinal allocation (Win32 only).
  58
  59 "FLAGS" is a series of optional flags, preceded by a '-' character.
  60 The supported flags are:
  61   "-noimport":  the entry point is not made available for importing
  62                 from winelib applications (Win32 only).
  63   "-norelay":   the entry point is not displayed in relay debugging
  64                 traces (Win32 only).
  65   "-ret64":     the function returns a 64-bit value (Win32 only).
  66   "-i386":      the entry point is only available on i386 platforms.
  67   "-register":  the function uses CPU register to pass arguments.
  68   "-interrupt": the function is an interrupt handler routine.
  69
  70 Lines whose first character is a '#' will be ignored as comments.
  71
  72
  73 Variable ordinals:
  74 ==================
  75
  76     This type defines data storage as 32-bit words at the ordinal specified.
  77 "EXPORTNAME" will be the name available for dynamic linking.  "DATA"
  78 can be a decimal number or a hex number preceeded by "0x".  The
  79 following example defines the variable "VariableA" at ordinal 2 and
  80 containing 4 ints:
  81
  82         2 variable VariableA(-1 0xff 0 0)
  83
  84 Function ordinals:
  85 ==================
  86
  87     This type defines a function entry point.  The prototype defined by
  88 "EXPORTNAME ([ARGTYPE [ARGTYPE [...]]])" specifies the name available for
  89 dynamic linking and the format of the arguments. "@" can be used
  90 instead of "EXPORTNAME" for ordinal-only exports.
  91
  92 "FUNCTYPE" should be one of:
  93 - "pascal16" for a Win16 function returning a 16-bit value
  94 - "pascal" for a Win16 function returning a 32-bit value
  95 - "stdcall" for a normal Win32 function
  96 - "cdecl" for a Win32 function using the C calling convention
  97 - "varargs" for a Win32 function taking a variable number of arguments
  98
  99 "ARGTYPE" should be one of:
 100 - "word"   (16-bit unsigned value)
 101 - "s_word" (16-bit signed word)
 102 - "long"   (32-bit value)
 103 - "double" (64-bit value)
 104 - "ptr"    (linear pointer)
 105 - "str"    (linear pointer to a null-terminated ASCII string)
 106 - "wstr"   (linear pointer to a null-terminated Unicode string)
 107 - "segptr" (segmented pointer)
 108 - "segstr" (segmented pointer to a null-terminated ASCII string)
 109
 110 Only "ptr", "str", "wstr", "long" and "double" are valid for Win32 functions.
 111
 112 "HANDLERNAME" is the name of the actual Wine function that will
 113 process the request in 32-bit mode.
 114
 115     This first example defines an entry point for the CreateWindow()
 116 call (the ordinal 100 is just an example):
 117
 118         100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word
 119                                 word word word ptr)
 120                    WIN_CreateWindow
 121
 122    This second example defines an entry point for the GetFocus()
 123 call (the ordinal 100 is just an example):
 124
 125         100 pascal GetFocus() WIN_GetFocus()
 126
 127 To declare a function using a variable number of arguments in Win16,
 128 specify the function as taking no arguments. The arguments are then
 129 available with CURRENT_STACK16->args. In Win32, specify the function
 130 as 'varargs' and declare it with a '...' parameter in the C file.  See
 131 the wsprintf* functions in user.spec and user32.spec for an example.
 132
 133 Stub ordinals:
 134 ==============
 135
 136     This type defines a stub function. It makes the name and ordinal
 137 available for dynamic linking, but will terminate execution with an
 138 error message if the function is ever called.
 139
 140 Equate ordinals:
 141 ================
 142
 143     This type defines an ordinal as an absolute value.
 144 "EXPORTNAME" will be the name available for dynamic linking.
 145 "DATA" can be a decimal number or a hex number preceeded by "0x".
 146
 147 Extern ordinals:
 148 ================
 149
 150     This type defines an entry that simply maps to a Wine symbol
 151 (variable or function); "EXPORTNAME" will point to the symbol
 152 "SYMBOLNAME" that must be defined in C code. This type only works with
 153 Win32.
 154
 155 Forwarded ordinals:
 156 ===================
 157
 158     This type defines an entry that is forwarded to another entry
 159 point (kind of a symbolic link). "EXPORTNAME" will forward to the
 160 entry point "SYMBOLNAME" that must be of the form "DLL.Function". This
 161 type only works with Win32.