| .\" -*- 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= filename |
| Build a C file from a .spec file (see \fBSPEC FILE SYNTAX\fR for |
| details), or from a standard Windows .def file. 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 --dll 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 \--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 \-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 \-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 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) |
| .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 preceeded 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 wrc (1). |