wine/tools/build-spec.txt
James Juran c4c129dc50 Document use of "init" in build-spec.txt, and make build.c print a
warning if someone tries to use "init" in a Win16 spec file.
1999-08-15 14:17:50 +00:00

146 lines
4.7 KiB
Text

Spec file format
----------------
name NAME
type win16|win32
[file WINFILENAME]
[base ORDINAL]
[heap SIZE]
[init FUNCTION]
[import DLL]
ORDINAL VARTYPE EXPORTNAME (DATA [DATA [DATA [...]]])
ORDINAL FUNCTYPE EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
ORDINAL stub EXPORTNAME
ORDINAL equate EXPORTNAME DATA
ORDINAL extern EXPORTNAME SYMBOLNAME
ORDINAL forward EXPORTNAME SYMBOLNAME
# COMMENT_TEXT
--------------------
General:
========
"name" and "type" fields are mandatory. Specific ordinal
declarations are optional, but the default handler will print an error
message.
"base" gives the offset of the first ordinal; default is 0.
"heap" is the size of the module local heap (only valid for Win16
modules); default is no local heap.
"file" gives the name of the Windows file that is replaced by the
builtin. <name>.DLL is assumed if none is given. (This is important
for kernel, which lives in the Windows file KRNL386.EXE).
"init" specifies a function which will be called when this dll
is loaded. This is only valid for Win32 modules.
"import" names a module that this one depends on (only for Win32
modules at the present). The import declaration can be present several
times.
Lines whose first character is a '#' will be ignored as comments.
Variable ordinals:
==================
This type defines data storage at the ordinal specified. You may
store items as bytes, 16-bit words, or 32-bit words.
"ORDINAL" is replaced by the ordinal number corresponding to the
variable. "VARTYPE" should be "byte", "word" or "long" for 8, 16, or
32 bits respectively. "EXPORTNAME" will be the name available for
dynamic linking. "DATA" can be a decimal number or a hex number preceeded
by "0x". The following example defines the variable "VariableA" at
ordinal 2 and containing 4 bytes:
2 byte VariableA(-1 0xff 0 0)
Function ordinals:
==================
This type defines a function entry point. The prototype defined by
"EXPORTNAME ([ARGTYPE [ARGTYPE [...]]])" specifies the name available for
dynamic linking and the format of the arguments. "ORDINAL" is replaced
by the ordinal number corresponding to the function.
"FUNCTYPE" should be one of:
- "pascal16" for a Win16 function returning a 16-bit value
- "pascal" for a Win16 function returning a 32-bit value
- "register" for a function using CPU register to pass arguments
- "interrupt" for a Win16 interrupt handler routine
- "stdcall" for a normal Win32 function
- "cdecl" for a Win32 function using the C calling convention
- "varargs" for a Win32 function taking a variable number of arguments
"ARGTYPE" should be one of:
- "word"
- "long"
- "ptr" (linear pointer)
- "str" (linear pointer to a null-terminated string)
- "s_word" (signed word)
- "segptr" (segmented pointer).
- "segstr" (segmented pointer to a null-terminated string)
Only "ptr", "str" and "long" are valid for Win32 functions.
"HANDLERNAME" is the name of the actual Wine function that will
process the request in 32-bit mode.
This first example defines an entry point for the CreateWindow()
call (the ordinal 100 is just an example):
100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word
word word word ptr)
WIN_CreateWindow
This second example defines an entry point for the GetFocus()
call (the ordinal 100 is just an example):
100 pascal GetFocus() WIN_GetFocus()
To declare a function using a variable number of arguments in Win16,
specify the function as taking no arguments. The arguments are then
available with CURRENT_STACK16->args. In Win32, specify the function
as 'varargs' and declare it with a '...' parameter in the C file. See
the wsprintf* functions in user.spec and user32.spec for an example.
Stub ordinals:
==============
This type defines a stub function. It makes the name and ordinal
available for dynamic linking, but will terminate execution with an
error message if the function is ever called.
Equate ordinals:
================
This type defines an ordinal as an absolute value.
"ORDINAL" is replaced by the ordinal number corresponding to the
variable. "EXPORTNAME" will be the name available for dynamic linking.
"DATA" can be a decimal number or a hex number preceeded by "0x".
Extern ordinals:
================
This type defines an entry that simply maps to a Wine symbol
(variable or function); "EXPORTNAME" will point to the symbol
"SYMBOLNAME" that must be defined in C code. This type only works with
Win32.
Forwarded ordinals:
===================
This type defines an entry that is forwarded to another entry
point (kind of a symbolic link). "EXPORTNAME" will forward to the
entry point "SYMBOLNAME" that must be of the form "DLL.Function". This
type only works with Win32.