--- vendor/wine/tools/winebuild/current/winebuild.man.in 2005-03-14 10:32:28 UTC (rev 14052)
+++ trunk/reactos/tools/winebuild/winebuild.man.in 2005-03-14 10:36:02 UTC (rev 14053)
@@ -0,0 +1,441 @@
+.\" -*- nroff -*-
+.TH WINEBUILD 1 "March 2003" "@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 \--dll
+Build a C 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 C file must be compiled
+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 a C 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 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
+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
+.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 \--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,\ --source-dir= directory
+Change to the specified directory before reading source files. Only
+meaningful in
+.BR \--debug\ mode.
+.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 WinMain
+for executables (if
+.B WinMain
+is not defined, the standard C
+.B main
+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
+.BI \-f\ flags
+Ignored for compatibility with the C compiler.
+.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 \--ld-cmd= ld-command
+Specify the command to use to link the object files; the default is
+\fBld\fR.
+.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 \-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
+.BI \-d,\ --delay-lib= name
+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,\ --main-module= 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--dll\fR mode.
+.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 \-o,\ --output= file
+Set the name of the output file (default is standard output).
+.TP
+.BI \-r,\ --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).
+.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
+.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
+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
+.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 imported by ordinal instead of by name.
+.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 -i386
+The entry point is only available on i386 platforms.
+.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.
+.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).
Property changes on: trunk/reactos/tools/winebuild/winebuild.man.in
___________________________________________________________________
Name: svn:eol-style
+ native