467 lines
13 KiB
Groff
467 lines
13 KiB
Groff
.\" -*- nroff -*-
|
|
.TH WINEBUILD 1 "July 2002" "@PACKAGE_STRING@" "Wine dll builder"
|
|
.SH NAME
|
|
winebuild \- Wine dll builder
|
|
.SH SYNOPSIS
|
|
.BI winebuild\ [options]\ [input\ files]
|
|
.SH DESCRIPTION
|
|
.B winebuild
|
|
generates the C and assembly files that are necessary to build a Wine
|
|
dll, which is basically a Win32 dll encapsulated inside a Unix
|
|
library.
|
|
.PP
|
|
.B winebuild
|
|
has different modes, depending on what kind of file it is asked to
|
|
generate. The mode is specified by one of the mode options specified
|
|
below. In addition to the mode option, various other command-line
|
|
option can be specified, as described in the \fBOPTIONS\fR section.
|
|
.SH "MODE OPTIONS"
|
|
You have to specify exactly one of the following options, depending on
|
|
what you want winebuild to generate.
|
|
.TP
|
|
.BI \-spec\ file.spec
|
|
Build a C file from a spec file (see \fBSPEC FILE SYNTAX\fR for
|
|
details). The resulting C file must be compiled and linked to the
|
|
other object files to build a working Wine dll.
|
|
.br
|
|
In that mode, the
|
|
.I input files
|
|
should be the list of all object files that will be linked into the
|
|
final dll, to allow
|
|
.B winebuild
|
|
to get the list of all undefined symbols that need to be imported from
|
|
other dlls.
|
|
.TP
|
|
.BI \-exe\ name
|
|
Build a C file for the named executable. This is basically the same as
|
|
the -spec mode except that it doesn't require a .spec file as input,
|
|
since an executable doesn't export functions. The resulting C file
|
|
must be compiled and linked to the other object files to build a
|
|
working Wine executable, and all the other object files must be listed
|
|
as
|
|
.I input files.
|
|
.TP
|
|
.BI \-def\ file.spec
|
|
Build a .def file from a spec file. This is used when building dlls
|
|
with a PE (Win32) compiler.
|
|
.TP
|
|
.B \-debug
|
|
Build a C file containing the definitions for debugging channels. In
|
|
that mode the
|
|
.I input files
|
|
should be a list of C files to search for debug channel
|
|
definitions. The resulting C file must be compiled and linked with the
|
|
dll.
|
|
.TP
|
|
.B \-glue
|
|
Build a C file containing the glue code for the 16-bit calls contained
|
|
in the
|
|
.I input files.
|
|
These calls must be specified in the source files using special
|
|
markers, as described in the \fBGLUE FUNCTIONS\fR section.
|
|
.TP
|
|
.B \-relay16
|
|
Generate the assembly code for the 16-bit relay routines. This is for
|
|
Wine internal usage only, you should never need to use this option.
|
|
.TP
|
|
.B \-relay32
|
|
Generate the assembly code for the 32-bit relay routines. This is for
|
|
Wine internal usage only, you should never need to use this option.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BI \-C\ directory
|
|
Change to the specified directory before reading source files. Only
|
|
meaningful in
|
|
.BR \-debug\ and\ -glue\ modes.
|
|
.TP
|
|
.BI \-D\ symbol
|
|
Ignored for compatibility with the C compiler.
|
|
.TP
|
|
.BI \-f\ flags
|
|
Ignored for compatibility with the C compiler.
|
|
.TP
|
|
.B \-h
|
|
Display a usage message and exit.
|
|
.TP
|
|
.BI \-I\ directory
|
|
Ignored for compatibility with the C compiler.
|
|
.TP
|
|
.BI \-K\ flags
|
|
Ignored for compatibility with the C compiler.
|
|
.TP
|
|
.BI \-L\ directory
|
|
Append the specified directory to the list of directories that are
|
|
searched for import libraries.
|
|
.TP
|
|
.BI \-l\ lib.dll
|
|
Import the specified library, looking for a corresponding
|
|
\fIlib.dll.so\fR file in the directories specified with the \fB-L\fR
|
|
option.
|
|
.TP
|
|
.BI \-dl\ lib.dll
|
|
Same as the \fB-l\fR option, but import the specified library in
|
|
delayed mode (i.e. the library won't be loaded until a function
|
|
imported from it is actually called).
|
|
.TP
|
|
.BI \-M\ module
|
|
Specify that we are building a 16-bit dll, that will ultimately be
|
|
linked together with the 32-bit dll specified in \fImodule\fR. Only
|
|
meaningful in \fB-spec\fR mode.
|
|
.TP
|
|
.BI \-m\ mode
|
|
Set the executable mode, which can be one of the following:
|
|
.br
|
|
.B cui
|
|
for a command line ASCII executable,
|
|
.br
|
|
.B gui
|
|
for a graphical ASCII executable,
|
|
.br
|
|
.B cuiw
|
|
for a command line Unicode executable,
|
|
.br
|
|
.B guiw
|
|
for a graphical Unicode executable.
|
|
.br
|
|
A command line executable entry point is a normal C \fBmain\fR
|
|
function. A graphical executable has a \fBWinMain\fR entry point
|
|
instead. The ASCII/Unicode distinction applies to the strings that are
|
|
passed to the entry point.
|
|
.br
|
|
This option is only meaningful in \fB-exe\fR mode.
|
|
.TP
|
|
.BI \-o\ file
|
|
Set the name of the output file (default is standard output).
|
|
.TP
|
|
.TP
|
|
.BI \-res\ rsrc.res
|
|
Load resources from the specified binary resource file. The
|
|
\fIrsrc.res\fR can be produced from a source resource file with
|
|
.BR wrc(1)
|
|
(or with a Windows resource compiler).
|
|
.TP
|
|
.B \-w
|
|
Turn on warnings.
|
|
.SH "SPEC FILE SYNTAX"
|
|
.SS "General syntax"
|
|
A spec file should contain a number of optional directives, and then a
|
|
list of ordinal declarations. The general syntax is the following:
|
|
.PP
|
|
.RB [ name\ \fIname\fR]
|
|
.br
|
|
.RB [ file\ \fIwinfilename\fR]
|
|
.br
|
|
.RB [ mode\ dll | cuiexe | guiexe | cuiexe_unicode | guiexe_unicode ]
|
|
.br
|
|
.RB [ heap\ \fIsize\fR]
|
|
.br
|
|
.RB [ init\ \fIfunction\fR]
|
|
.br
|
|
.RB [ rsrc\ \fIresfile\fR]
|
|
.br
|
|
.RB [ ignore\ (\ [ \fIsymbols...\fR ]\ )\ ]
|
|
.br
|
|
.BI #\ comments
|
|
.PP
|
|
.I ordinal functype
|
|
.RI [ flags ]\ exportname \ \fB(\fR\ [ args... ] \ \fB)\fI\ handler
|
|
.br
|
|
.IB ordinal\ variable
|
|
.RI [ flags ]\ exportname \ \fB(\fR\ [ data... ] \ \fB)
|
|
.br
|
|
.IB ordinal\ stub
|
|
.RI [ flags ]\ exportname
|
|
.br
|
|
.IB ordinal\ equate
|
|
.RI [ flags ]\ exportname\ data
|
|
.br
|
|
.IB ordinal\ extern
|
|
.RI [ flags ]\ exportname\ symbolname
|
|
.br
|
|
.IB ordinal\ forward
|
|
.RI [ flags ]\ exportname\ forwardname
|
|
.SS "Optional directives"
|
|
.B name
|
|
is the internal name of the module. It is only used in Win16
|
|
modules. The default is to use the base name of the spec file (without
|
|
any extension). This is used for KERNEL, since it lives in
|
|
KRNL386.EXE. It shouldn't be needed otherwise.
|
|
.PP
|
|
.B file
|
|
is used to give the name of the file containing the dll. If not
|
|
specified it is determined from the name of the source spec
|
|
file. Normally you shouldn't ever need to specify it explicitly.
|
|
.PP
|
|
.B mode
|
|
is used to specify whether this is the spec file for a dll or the main
|
|
exe. This is only valid for Win32 spec files.
|
|
.PP
|
|
.B heap
|
|
specifies the size of the module local heap (only valid for Win16
|
|
modules); default is no local heap.
|
|
.PP
|
|
.B init
|
|
specifies a function which will be called when this dll is
|
|
loaded. This is only valid for Win32 modules.
|
|
.PP
|
|
.B rsrc
|
|
specifies the path of the compiled resource file.
|
|
.PP
|
|
.B ignore
|
|
specifies a list of symbols that should be ignored when
|
|
resolving undefined symbols against the imported libraries.
|
|
.PP
|
|
Lines whose first character is a
|
|
.B #
|
|
will be ignored as comments.
|
|
.SS "Ordinal specifications"
|
|
.I ordinal
|
|
specifies the ordinal number corresponding to the entry point, or '@'
|
|
for automatic ordinal allocation (Win32 only).
|
|
.PP
|
|
.I flags
|
|
is a series of optional flags, preceded by a '-' character. The
|
|
supported flags are:
|
|
.RS
|
|
.TP
|
|
.B -noimport
|
|
The entry point is not made available for importing from Winelib
|
|
applications (Win32 only).
|
|
.TP
|
|
.B -norelay
|
|
The entry point is not displayed in relay debugging traces (Win32
|
|
only).
|
|
.TP
|
|
.B -noname
|
|
The entry point will be imported by ordinal instead of by name.
|
|
.TP
|
|
.B -ret64
|
|
The function returns a 64-bit value (Win32 only).
|
|
.TP
|
|
.B -i386
|
|
The entry point is only available on i386 platforms.
|
|
.TP
|
|
.B -register
|
|
The function uses CPU register to pass arguments.
|
|
.TP
|
|
.B -interrupt
|
|
The function is an interrupt handler routine.
|
|
.SS "Function ordinals"
|
|
Syntax:
|
|
.br
|
|
.I ordinal functype
|
|
.RI [ flags ]\ exportname \ \fB(\fR\ [ args... ] \ \fB)\fI\ handler
|
|
.br
|
|
|
|
This declaration defines a function entry point. The prototype defined by
|
|
.IR exportname \ \fB(\fR\ [ args... ] \ \fB)
|
|
specifies the name available for dynamic linking and the format of the
|
|
arguments. '@' can be used instead of
|
|
.I exportname
|
|
for ordinal-only exports.
|
|
.PP
|
|
.I functype
|
|
should be one of:
|
|
.RS
|
|
.TP
|
|
.B stdcall
|
|
for a normal Win32 function
|
|
.TP
|
|
.B cdecl
|
|
for a Win32 function using the C calling convention
|
|
.TP
|
|
.B varargs
|
|
for a Win32 function taking a variable number of arguments
|
|
.TP
|
|
.B pascal
|
|
for a Win16 function returning a 32-bit value
|
|
.TP
|
|
.B pascal16
|
|
for a Win16 function returning a 16-bit value.
|
|
.RE
|
|
.PP
|
|
.I args
|
|
should be one or several of:
|
|
.RS
|
|
.TP
|
|
.B word
|
|
(16-bit unsigned value)
|
|
.TP
|
|
.B s_word
|
|
(16-bit signed word)
|
|
.TP
|
|
.B long
|
|
(32-bit value)
|
|
.TP
|
|
.B double
|
|
(64-bit value)
|
|
.TP
|
|
.B ptr
|
|
(linear pointer)
|
|
.TP
|
|
.B str
|
|
(linear pointer to a null-terminated ASCII string)
|
|
.TP
|
|
.B wstr
|
|
(linear pointer to a null-terminated Unicode string)
|
|
.TP
|
|
.B segptr
|
|
(segmented pointer)
|
|
.TP
|
|
.B segstr
|
|
(segmented pointer to a null-terminated ASCII string).
|
|
.HP
|
|
.RB Only\ ptr ,\ str ,\ wstr ,\ long\ and\ double
|
|
are valid for Win32 functions.
|
|
.RE
|
|
.PP
|
|
.I handler
|
|
is the name of the actual C function that will implement that entry
|
|
point in 32-bit mode.
|
|
.PP
|
|
This first example defines an entry point for the 16-bit
|
|
CreateWindow() call (the ordinal 100 is just an example):
|
|
.IP
|
|
100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word word word word ptr) WIN_CreateWindow
|
|
.PP
|
|
This second example defines an entry point for the 32-bit GetFocus()
|
|
call:
|
|
.IP
|
|
@ stdcall GetFocus() GetFocus
|
|
.PP
|
|
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
|
|
.B varargs
|
|
and declare it with a '...' parameter in the C file. See the
|
|
wsprintf* functions in user.spec and user32.spec for an example.
|
|
.SS "Variable ordinals"
|
|
Syntax:
|
|
.br
|
|
.IB ordinal\ variable
|
|
.RI [ flags ]\ exportname \ \fB(\fR\ [ data... ] \ \fB)
|
|
.PP
|
|
This declaration defines data storage as 32-bit words at the ordinal
|
|
specified.
|
|
.I exportname
|
|
will be the name available for dynamic
|
|
linking.
|
|
.I 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 ints:
|
|
.IP
|
|
2 variable VariableA(-1 0xff 0 0)
|
|
.SS "Stub ordinals"
|
|
Syntax:
|
|
.br
|
|
.IB ordinal\ stub
|
|
.RI [ flags ]\ exportname
|
|
.PP
|
|
This declaration 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.
|
|
.SS "Equate ordinals"
|
|
Syntax:
|
|
.br
|
|
.IB ordinal\ equate
|
|
.RI [ flags ]\ exportname\ data
|
|
.PP
|
|
This declaration defines an ordinal as an absolute value.
|
|
.I exportname
|
|
will be the name available for dynamic linking.
|
|
.I data
|
|
can be a decimal number or a hex number preceeded by "0x".
|
|
.SS "Extern ordinals"
|
|
Syntax:
|
|
.br
|
|
.IB ordinal\ extern
|
|
.RI [ flags ]\ exportname\ symbolname
|
|
.PP
|
|
This declaration defines an entry that simply maps to a C symbol
|
|
(variable or function).
|
|
.I exportname
|
|
will point to the symbol
|
|
.I symbolname
|
|
that must be defined in C code. This declaration only works in Win32
|
|
spec files.
|
|
.SS "Forwarded ordinals"
|
|
Syntax:
|
|
.br
|
|
.IB ordinal\ forward
|
|
.RI [ flags ]\ exportname\ forwardname
|
|
.PP
|
|
This declaration defines an entry that is forwarded to another entry
|
|
point (kind of a symbolic link).
|
|
.I exportname
|
|
will forward to the
|
|
entry point
|
|
.I forwardname
|
|
that must be of the form
|
|
.B DLL.Function.
|
|
This declaration only works in Win32 spec files.
|
|
.SH "GLUE FUNCTIONS"
|
|
Glue functions are used to call down to 16-bit code from a 32-bit
|
|
function. This is done by declaring a special type of function
|
|
prototype in the source file that needs to call to 16-bit code, and
|
|
processing the source file through
|
|
.I winebuild -glue.
|
|
.PP
|
|
These prototypes must be of one of the following forms:
|
|
.PP
|
|
.B extern WORD CALLBACK \fIprefix\fB_CallTo16_word_\fIxxx\fB( FARPROC16 func, \fIargs\fB );
|
|
.br
|
|
.B extern LONG CALLBACK \fIprefix\fB_CallTo16_long_\fIxxx\fB( FARPROC16 func, \fIargs\fB );
|
|
.PP
|
|
The
|
|
.I prefix
|
|
can be anything you need to make the function names unique inside a
|
|
given dll. The
|
|
.I xxx
|
|
characters specify the type of the arguments, with one letter for each
|
|
argument. A \fBw\fR indicates a WORD argument, a \fBl\fR indicates a
|
|
LONG argument.
|
|
.PP
|
|
All the CallTo16 prototypes must be located between the special
|
|
markers
|
|
.B ### start build ###
|
|
and
|
|
.B ### stop build ###
|
|
(which have to be inside C comments of course).
|
|
.PP
|
|
Here's what a real life example looks like:
|
|
.PP
|
|
.B /* ### start build ### */
|
|
.br
|
|
.B extern WORD CALLBACK PRTDRV_CallTo16_word_ww(FARPROC16,WORD,WORD);
|
|
.br
|
|
.B /* ### stop build ### */
|
|
.SH AUTHORS
|
|
.B winebuild
|
|
has been worked on by many people over the years. The main authors are
|
|
Robert J. Amstadt, Alexandre Julliard, Martin von Loewis, Ulrich
|
|
Weigand and Eric Youngdale. Many other Wine developers have
|
|
contributed, please check the file Changelog in the Wine distribution
|
|
for the complete details.
|
|
.SH BUGS
|
|
It is not yet possible to use a PE-format dll in an import
|
|
specification; only Wine dlls can be imported.
|
|
.PP
|
|
If you find a bug, please submit a bug report at
|
|
.UR http://bugs.winehq.com
|
|
.B http://bugs.winehq.com.
|
|
.UE
|
|
.SH AVAILABILITY
|
|
.B winebuild
|
|
is part of the wine distribution, which is available through WineHQ,
|
|
the
|
|
.B wine
|
|
development headquarters, at
|
|
.UR http://www.winehq.com/
|
|
.B http://www.winehq.com/.
|
|
.UE
|
|
.SH "SEE ALSO"
|
|
.BR wine (1),
|
|
.BR wrc (1).
|