494 lines
15 KiB
Groff
494 lines
15 KiB
Groff
.\" -*- nroff -*-
|
|
.TH WINEBUILD 1 "October 2005" "@PACKAGE_STRING@" "Wine Developers Manual"
|
|
.SH NAME
|
|
winebuild \- Wine dll builder
|
|
.SH SYNOPSIS
|
|
.BI winebuild\ [options]\ [input\ files]
|
|
.SH DESCRIPTION
|
|
.B winebuild
|
|
generates the 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 \--dll
|
|
Build an assembly file from a .spec file (see \fBSPEC FILE SYNTAX\fR
|
|
for details), or from a standard Windows .def file. The .spec/.def
|
|
file is specified via the -E option. The resulting file must be
|
|
assembled and linked to the other object files to build a working Wine
|
|
dll. In this 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
|
|
Build an assembly file for an executable. This is basically the same as
|
|
the --dll mode except that it doesn't require a .spec/.def file as input,
|
|
since an executable need not export functions. Some executables however
|
|
do export functions, and for those a .spec/.def file can be specified via
|
|
the -E option. The executable is named from the .spec/.def file name if
|
|
present, or explicitly through the -F option. The resulting file must be
|
|
assembled 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
|
|
Build a .def file from a spec file. The .spec file is specified via the
|
|
-E option. This is used when building dlls with a PE (Win32) compiler.
|
|
.TP
|
|
.BI \--implib
|
|
Build a PE import library from a spec file. The .spec file is
|
|
specified via the -E option.
|
|
.TP
|
|
.B \--resources
|
|
Generate a .o file containing all the input resources. This is useful
|
|
when building with a PE compiler, since the PE binutils cannot handle
|
|
multiple resource files as input. For a standard Unix build, the
|
|
resource files are automatically included when building the spec file,
|
|
so there's no need for an intermediate .o file.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BI \--as-cmd= as-command
|
|
Specify the command to use to compile assembly files; the default is
|
|
\fBas\fR.
|
|
.TP
|
|
.BI \-b,\ --target= cpu-manufacturer[-kernel]-os
|
|
Specify the target CPU and platform on which the generated code will
|
|
be built. The target specification is in the standard autoconf format
|
|
as returned by config.sub.
|
|
.TP
|
|
.BI \-d,\ --delay-lib= name
|
|
Set the delayed import mode for the specified library, which must be
|
|
one of the libraries imported with the \fB-l\fR option. Delayed mode
|
|
means that the library won't be loaded until a function imported from
|
|
it is actually called.
|
|
.TP
|
|
.BI \-D\ symbol
|
|
Ignored for compatibility with the C compiler.
|
|
.TP
|
|
.BI \-e,\ --entry= function
|
|
Specify the module entry point function; if not specified, the default
|
|
is
|
|
.B DllMain
|
|
for dlls, and
|
|
.B main
|
|
for executables (if the standard C
|
|
.B main
|
|
is not defined,
|
|
.B WinMain
|
|
is used instead). This is only valid for Win32 modules.
|
|
.TP
|
|
.BI \-E,\ --export= filename
|
|
Specify a .spec file (see \fBSPEC FILE SYNTAX\fR for details),
|
|
or a standard Windows .def file that defines the exports
|
|
of the DLL or executable that is being built.
|
|
.TP
|
|
.B \--external-symbols
|
|
Allow linking to external symbols directly from the spec
|
|
file. Normally symbols exported by a dll have to be defined in the dll
|
|
itself; this option makes it possible to use symbols defined in
|
|
another Unix library (for symbols defined in another dll, a
|
|
.I forward
|
|
specification must be used instead).
|
|
.TP
|
|
.BI \-f\ option
|
|
Specify a code generation option. Currently \fB\-fPIC\fR and
|
|
\fB\-fasynchronous-unwind-tables\fR are supported. Other options are
|
|
ignored for compatibility with the C compiler.
|
|
.TP
|
|
.B \--fake-module
|
|
Create a fake PE module for a dll or exe, instead of the normal
|
|
assembly or object file. The PE module contains the resources for the
|
|
module, but no executable code.
|
|
.TP
|
|
.BI \-F,\ --filename= filename
|
|
Set the file name of the module. The default is to use the base name
|
|
of the spec file (without any extension).
|
|
.TP
|
|
.B \-h, --help
|
|
Display a usage message and exit.
|
|
.TP
|
|
.BI \-H,\ --heap= size
|
|
Specify the size of the module local heap in bytes (only valid for
|
|
Win16 modules); default is no local heap.
|
|
.TP
|
|
.BI \-i,\ --ignore= [-]symbol[,[-]symbol]
|
|
Specify a list of symbols that should be ignored when resolving
|
|
undefined symbols against the imported libraries. This forces these
|
|
symbols to be resolved from the Unix C library (or from another Unix
|
|
library linked with the application). If a symbol is prefixed by '-'
|
|
it is removed from the list instead of being added; a stand-alone '-'
|
|
clears the whole list.
|
|
.TP
|
|
.BI \-I\ directory
|
|
Ignored for compatibility with the C compiler.
|
|
.TP
|
|
.B \-k, --kill-at
|
|
Remove the stdcall decorations from the symbol names in the
|
|
generated .def file. Only meaningful in \fB--def\fR mode.
|
|
.TP
|
|
.BI \-K\ flags
|
|
Ignored for compatibility with the C compiler.
|
|
.TP
|
|
.BI \--large-address-aware
|
|
Set a flag in the executable to notify the loader that this
|
|
application supports address spaces larger than 2 gigabytes.
|
|
.TP
|
|
.BI \--ld-cmd= ld-command
|
|
Specify the command to use to link the object files; the default is
|
|
\fBld\fR.
|
|
.TP
|
|
.BI \-L,\ --library-path= directory
|
|
Append the specified directory to the list of directories that are
|
|
searched for import libraries.
|
|
.TP
|
|
.BI \-l,\ --library= name
|
|
Import the specified library, looking for a corresponding
|
|
\fIlibname.def\fR file in the directories specified with the \fB-L\fR
|
|
option.
|
|
.TP
|
|
.B \-m32, -m64
|
|
Generate 32-bit, respectively 64-bit code.
|
|
.TP
|
|
.BI \-M,\ --main-module= module
|
|
When building a 16-bit dll, set the name of its 32-bit counterpart to
|
|
\fImodule\fR. This is used to enforce that the load order for the
|
|
16-bit dll matches that of the 32-bit one.
|
|
.TP
|
|
.BI \-N,\ --dll-name= dllname
|
|
Set 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.
|
|
.TP
|
|
.BI \--nm-cmd= nm-command
|
|
Specify the command to use to get the list of undefined symbols; the
|
|
default is \fBnm\fR.
|
|
.TP
|
|
.BI --nxcompat= yes|no
|
|
Specify whether the module is compatible with no-exec support. The
|
|
default is yes.
|
|
.TP
|
|
.BI \-o,\ --output= file
|
|
Set the name of the output file (default is standard output). If the
|
|
output file name end in \fB.o\fR, the text output is sent to a
|
|
temporary file that is then assembled to produce the specified .o
|
|
file.
|
|
.TP
|
|
.BI \-r,\ --res= rsrc.res
|
|
Load resources from the specified binary resource file. The
|
|
\fIrsrc.res\fR file can be produced from a source resource file with
|
|
.BR wrc(1)
|
|
(or with a Windows resource compiler).
|
|
.br
|
|
This option is only necessary for Win16 resource files, the Win32 ones
|
|
can simply listed as
|
|
.I input files
|
|
and will automatically be handled correctly (though the
|
|
.B \-r
|
|
option will also work for Win32 files).
|
|
.TP
|
|
.B --save-temps
|
|
Do not delete the various temporary files that \fBwinebuild\fR generates.
|
|
.TP
|
|
.BI --subsystem= subsystem[:major[.minor]]
|
|
Set the subsystem of the executable, which can be one of the following:
|
|
.br
|
|
.B console
|
|
for a command line executable,
|
|
.br
|
|
.B windows
|
|
for a graphical executable,
|
|
.br
|
|
.B native
|
|
for a native-mode dll,
|
|
.br
|
|
.B win16
|
|
for a 16-bit module.
|
|
.br
|
|
The entry point of a command line executable is a normal C \fBmain\fR
|
|
function. A \fBwmain\fR function can be used instead if you need the
|
|
argument array to use Unicode strings. A graphical executable has a
|
|
\fBWinMain\fR entry point.
|
|
.br
|
|
Optionally a major and minor subsystem version can also be specified;
|
|
the default subsystem version is 4.0.
|
|
.TP
|
|
.BI \-u,\ --undefined= symbol
|
|
Add \fIsymbol\fR to the list of undefined symbols when invoking the
|
|
linker. This makes it possible to force a specific module of a static
|
|
library to be included when resolving imports.
|
|
.TP
|
|
.B \-v, --verbose
|
|
Display the various subcommands being invoked by
|
|
.B winebuild.
|
|
.TP
|
|
.B \--version
|
|
Display the program version and exit.
|
|
.TP
|
|
.B \-w, --warnings
|
|
Turn on warnings.
|
|
.SH "SPEC FILE SYNTAX"
|
|
.SS "General syntax"
|
|
A spec file should contain a list of ordinal declarations. The general
|
|
syntax is the following:
|
|
.PP
|
|
.I ordinal functype
|
|
.RI [ flags ]\ exportname \ \fB(\fR\ [ args... ] \ \fB) \ [ handler ]
|
|
.br
|
|
.IB ordinal\ variable
|
|
.RI [ flags ]\ exportname \ \fB(\fR\ [ data... ] \ \fB)
|
|
.br
|
|
.IB ordinal\ extern
|
|
.RI [ flags ]\ exportname \ [ symbolname ]
|
|
.br
|
|
.IB ordinal\ stub
|
|
.RI [ flags ]\ exportname
|
|
.br
|
|
.IB ordinal\ equate
|
|
.RI [ flags ]\ exportname\ data
|
|
.br
|
|
.BI #\ comments
|
|
.PP
|
|
Declarations must fit on a single line, except if the end of line is
|
|
escaped using a backslash character. The
|
|
.B #
|
|
character anywhere in a line causes the rest of the line to be ignored
|
|
as a comment.
|
|
.PP
|
|
.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 -norelay
|
|
The entry point is not displayed in relay debugging traces (Win32
|
|
only).
|
|
.TP
|
|
.B -noname
|
|
The entry point will be exported by ordinal instead of by name. The
|
|
name is still available for importing.
|
|
.TP
|
|
.B -ret16
|
|
The function returns a 16-bit value (Win16 only).
|
|
.TP
|
|
.B -ret64
|
|
The function returns a 64-bit value (Win32 only).
|
|
.TP
|
|
.B -register
|
|
The function uses CPU register to pass arguments.
|
|
.TP
|
|
.B -private
|
|
The function cannot be imported from other dlls, it can only be
|
|
accessed through GetProcAddress.
|
|
.TP
|
|
.B -ordinal
|
|
The entry point will be imported by ordinal instead of by name. The
|
|
name is still exported.
|
|
.TP
|
|
.BI -arch= cpu[,cpu]
|
|
The entry point is only available on the specified CPU
|
|
architecture(s). The names \fBwin32\fR and \fBwin64\fR match all
|
|
32-bit, respectively 64-bit, CPU architectures. In 16-bit dlls,
|
|
specifying \fB-arch=win32\fR causes the entry point to be exported
|
|
from the 32-bit wrapper module.
|
|
.SS "Function ordinals"
|
|
Syntax:
|
|
.br
|
|
.I ordinal functype
|
|
.RI [ flags ]\ exportname \ \fB(\fR\ [ args... ] \ \fB) \ [ 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 pascal
|
|
for a normal Win16 function
|
|
.TP
|
|
.B cdecl
|
|
for a Win16 or Win32 function using the C calling convention
|
|
.TP
|
|
.B varargs
|
|
for a Win16 or Win32 function using the C calling convention with a
|
|
variable number of arguments
|
|
.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. The handler can also be specified as
|
|
.IB dllname . function
|
|
to define a forwarded function (one whose implementation is in another
|
|
dll). If
|
|
.I handler
|
|
is not specified, it is assumed to be identical to
|
|
.I exportname.
|
|
.PP
|
|
This first example defines an entry point for the 32-bit GetFocus()
|
|
call:
|
|
.IP
|
|
@ stdcall GetFocus() GetFocus
|
|
.PP
|
|
This second example defines an entry point for the 16-bit
|
|
CreateWindow() call (the ordinal 100 is just an example); it also
|
|
shows how long lines can be split using a backslash:
|
|
.IP
|
|
100 pascal CreateWindow(ptr ptr long s_word s_word s_word \\
|
|
s_word word word word ptr) WIN_CreateWindow
|
|
.PP
|
|
To declare a function using a variable number of arguments, specify
|
|
the function as
|
|
.B varargs
|
|
and declare it in the C file with a '...' parameter for a Win32
|
|
function, or with an extra VA_LIST16 argument for a Win16 function.
|
|
See the wsprintf* functions in user.exe.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 preceded by "0x". The
|
|
following example defines the variable VariableA at ordinal 2 and
|
|
containing 4 ints:
|
|
.IP
|
|
2 variable VariableA(-1 0xff 0 0)
|
|
.PP
|
|
This declaration only works in Win16 spec files. In Win32 you should
|
|
use
|
|
.B extern
|
|
instead (see below).
|
|
.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). It only works in Win32 spec files.
|
|
.I exportname
|
|
will point to the symbol
|
|
.I symbolname
|
|
that must be defined in the C code. Alternatively, it can be of the
|
|
form
|
|
.IB dllname . symbolname
|
|
to define a forwarded symbol (one whose implementation is in another
|
|
dll). If
|
|
.I symbolname
|
|
is not specified, it is assumed to be identical to
|
|
.I exportname.
|
|
.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 preceded by "0x".
|
|
.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.org
|
|
.B http://bugs.winehq.org.
|
|
.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.org/
|
|
.B http://www.winehq.org/.
|
|
.UE
|
|
.SH "SEE ALSO"
|
|
.BR wine (1),
|
|
.BR winegcc (1),
|
|
.BR wrc (1).
|