tools/winebuild/README

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