tools/build-spec.txt

   1                         Spec file format
   2                         ----------------
   3
   4 name    NAME
   5 type    win16|win32
   6 [file   WINFILENAME]
   7 [base   ORDINAL]
   8 [heap   SIZE]
   9 [init   FUNCTION]
  10 [import DLL]
  11
  12 ORDINAL VARTYPE EXPORTNAME (DATA [DATA [DATA [...]]])
  13
  14 ORDINAL FUNCTYPE EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
  15
  16 ORDINAL stub EXPORTNAME
  17
  18 ORDINAL equate EXPORTNAME DATA
  19
  20 ORDINAL extern EXPORTNAME SYMBOLNAME
  21
  22 ORDINAL forward EXPORTNAME SYMBOLNAME
  23
  24 # COMMENT_TEXT
  25
  26 --------------------
  27 General:
  28 ========
  29
  30     "name" and "type" fields are mandatory.  Specific ordinal
  31 declarations are optional, but the default handler will print an error
  32 message.
  33
  34 "base" gives the offset of the first ordinal; default is 0.
  35
  36 "heap" is the size of the module local heap (only valid for Win16
  37 modules); default is no local heap.
  38
  39 "file" gives the name of the Windows file that is replaced by the
  40 builtin. <name>.DLL is assumed if none is given. (This is important
  41 for kernel, which lives in the Windows file KRNL386.EXE).
  42
  43 "init" specifies a function which will be called when this dll
  44 is loaded. This is only valid for Win32 modules.
  45
  46 "import" names a module that this one depends on (only for Win32
  47 modules at the present). The import declaration can be present several
  48 times.
  49
  50 Lines whose first character is a '#' will be ignored as comments.
  51
  52
  53 Variable ordinals:
  54 ==================
  55
  56     This type defines data storage at the ordinal specified.  You may
  57 store items as bytes, 16-bit words, or 32-bit words.
  58     "ORDINAL" is replaced by the ordinal number corresponding to the
  59 variable.  "VARTYPE" should be "byte", "word" or "long" for 8, 16, or
  60 32 bits respectively.  "EXPORTNAME" will be the name available for
  61 dynamic linking.  "DATA" can be a decimal number or a hex number preceeded
  62 by "0x".  The following example defines the variable "VariableA" at
  63 ordinal 2 and containing 4 bytes:
  64
  65         2 byte VariableA(-1 0xff 0 0)
  66
  67 Function ordinals:
  68 ==================
  69
  70     This type defines a function entry point.  The prototype defined by
  71 "EXPORTNAME ([ARGTYPE [ARGTYPE [...]]])" specifies the name available for
  72 dynamic linking and the format of the arguments. "ORDINAL" is replaced
  73 by the ordinal number corresponding to the function.
  74
  75 "FUNCTYPE" should be one of:
  76 - "pascal16" for a Win16 function returning a 16-bit value
  77 - "pascal" for a Win16 function returning a 32-bit value
  78 - "register" for a function using CPU register to pass arguments
  79 - "interrupt" for a Win16 interrupt handler routine
  80 - "stdcall" for a normal Win32 function
  81 - "cdecl" for a Win32 function using the C calling convention
  82 - "varargs" for a Win32 function taking a variable number of arguments
  83
  84 "ARGTYPE" should be one of:
  85 - "word"
  86 - "long"
  87 - "ptr" (linear pointer)
  88 - "str" (linear pointer to a null-terminated string)
  89 - "s_word" (signed word)
  90 - "segptr" (segmented pointer).
  91 - "segstr" (segmented pointer to a null-terminated string)
  92
  93 Only "ptr", "str" and "long" are valid for Win32 functions.
  94
  95 "HANDLERNAME" is the name of the actual Wine function that will
  96 process the request in 32-bit mode.
  97
  98     This first example defines an entry point for the CreateWindow()
  99 call (the ordinal 100 is just an example):
 100
 101         100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word
 102                                 word word word ptr)
 103                    WIN_CreateWindow
 104
 105    This second example defines an entry point for the GetFocus()
 106 call (the ordinal 100 is just an example):
 107
 108         100 pascal GetFocus() WIN_GetFocus()
 109
 110 To declare a function using a variable number of arguments in Win16,
 111 specify the function as taking no arguments. The arguments are then
 112 available with CURRENT_STACK16->args. In Win32, specify the function
 113 as 'varargs' and declare it with a '...' parameter in the C file.  See
 114 the wsprintf* functions in user.spec and user32.spec for an example.
 115
 116 Stub ordinals:
 117 ==============
 118
 119     This type defines a stub function. It makes the name and ordinal
 120 available for dynamic linking, but will terminate execution with an
 121 error message if the function is ever called.
 122
 123 Equate ordinals:
 124 ================
 125
 126     This type defines an ordinal as an absolute value.
 127 "ORDINAL" is replaced by the ordinal number corresponding to the
 128 variable.  "EXPORTNAME" will be the name available for dynamic linking.
 129 "DATA" can be a decimal number or a hex number preceeded by "0x".
 130
 131 Extern ordinals:
 132 ================
 133
 134     This type defines an entry that simply maps to a Wine symbol
 135 (variable or function); "EXPORTNAME" will point to the symbol
 136 "SYMBOLNAME" that must be defined in C code. This type only works with
 137 Win32.
 138
 139 Forwarded ordinals:
 140 ===================
 141
 142     This type defines an entry that is forwarded to another entry
 143 point (kind of a symbolic link). "EXPORTNAME" will forward to the
 144 entry point "SYMBOLNAME" that must be of the form "DLL.Function". This
 145 type only works with Win32.
 146