diff --git a/tools/winebuild/.cvsignore b/tools/winebuild/.cvsignore index 705522986a2..c0248d62d1b 100644 --- a/tools/winebuild/.cvsignore +++ b/tools/winebuild/.cvsignore @@ -1,2 +1,3 @@ Makefile winebuild +winebuild.man diff --git a/tools/winebuild/Makefile.in b/tools/winebuild/Makefile.in index 6c8ea8249fb..158aaa0ee46 100644 --- a/tools/winebuild/Makefile.in +++ b/tools/winebuild/Makefile.in @@ -19,18 +19,25 @@ C_SRCS = \ spec32.c \ utils.c -all: $(PROGRAMS) +all: $(PROGRAMS) winebuild.man @MAKE_RULES@ winebuild$(EXEEXT): $(OBJS) $(CC) $(CFLAGS) -o $@ $(OBJS) $(LIBWINE) $(LIBUNICODE) $(LDFLAGS) -install:: $(PROGRAMS) - $(MKINSTALLDIRS) $(bindir) +winebuild.man: winebuild.man.in + sed -e 's,@PACKAGE_STRING\@,@PACKAGE_STRING@,g' $(SRCDIR)/winebuild.man.in >$@ || $(RM) $@ + +install:: $(PROGRAMS) winebuild.man + $(MKINSTALLDIRS) $(bindir) $(mandir)/man$(prog_manext) $(INSTALL_PROGRAM) winebuild$(EXEEXT) $(bindir)/winebuild$(EXEEXT) + $(INSTALL_DATA) winebuild.man $(mandir)/man$(prog_manext)/winebuild.$(prog_manext) uninstall:: - $(RM) $(bindir)/winebuild$(EXEEXT) + $(RM) $(bindir)/winebuild$(EXEEXT) $(mandir)/man$(prog_manext)/winebuild.$(prog_manext) + +clean:: + $(RM) winebuild.man ### Dependencies: diff --git a/tools/winebuild/README b/tools/winebuild/README deleted file mode 100644 index 9d7e31e47c5..00000000000 --- a/tools/winebuild/README +++ /dev/null @@ -1,161 +0,0 @@ - Spec file format - ---------------- - -[name NAME] -[file WINFILENAME] -[mode dll|cuiexe|guiexe|cuiexe_unicode|guiexe_unicode] -[heap SIZE] -[init FUNCTION] -[rsrc RESFILE] -[ignore ([SYMBOL [SYMBOL...]])] - -ORDINAL FUNCTYPE [FLAGS] EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME - -ORDINAL variable [FLAGS] EXPORTNAME (DATA [DATA [DATA [...]]]) - -ORDINAL stub [FLAGS] EXPORTNAME - -ORDINAL equate [FLAGS] EXPORTNAME DATA - -ORDINAL extern [FLAGS] EXPORTNAME SYMBOLNAME - -ORDINAL forward [FLAGS] EXPORTNAME SYMBOLNAME - -# COMMENT_TEXT - --------------------- -General: -======== - -All declarations are optional; reasonable defaults will be used for -anything that isn't specified. - -"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. - -"file" gives 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. - -"mode" specifies whether it is the spec file for a dll or the main exe. -This is only valid for Win32 spec files. - -"heap" is the size of the module local heap (only valid for Win16 -modules); default is no local heap. - -"init" specifies a function which will be called when this dll -is loaded. This is only valid for Win32 modules. - -"rsrc" specifies the path of the compiled resource file. - -"ignore" specifies a list of symbols that should be ignored when -resolving undefined symbols against the imported libraries. - -"ORDINAL" specified the ordinal number corresponding to the entry -point, or "@" for automatic ordinal allocation (Win32 only). - -"FLAGS" is a series of optional flags, preceded by a '-' character. -The supported flags are: - "-noimport": the entry point is not made available for importing - from winelib applications (Win32 only). - "-norelay": the entry point is not displayed in relay debugging - traces (Win32 only). - "-ret64": the function returns a 64-bit value (Win32 only). - "-i386": the entry point is only available on i386 platforms. - "-register": the function uses CPU register to pass arguments. - "-interrupt": the function is an interrupt handler routine. - -Lines whose first character is a '#' will be ignored as comments. - - -Variable ordinals: -================== - - This type defines data storage as 32-bit words at the ordinal specified. -"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 ints: - - 2 variable 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. "@" can be used -instead of "EXPORTNAME" for ordinal-only exports. - -"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 -- "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" (16-bit unsigned value) -- "s_word" (16-bit signed word) -- "long" (32-bit value) -- "double" (64-bit value) -- "ptr" (linear pointer) -- "str" (linear pointer to a null-terminated ASCII string) -- "wstr" (linear pointer to a null-terminated Unicode string) -- "segptr" (segmented pointer) -- "segstr" (segmented pointer to a null-terminated ASCII string) - -Only "ptr", "str", "wstr", "long" and "double" 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. -"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. diff --git a/tools/winebuild/winebuild.man.in b/tools/winebuild/winebuild.man.in new file mode 100644 index 00000000000..5db4125a243 --- /dev/null +++ b/tools/winebuild/winebuild.man.in @@ -0,0 +1,454 @@ +.\" -*- nroff -*- +.TH WINEBUILD 1 "July 2002" "@PACKAGE_STRING@" "Wine dll builder" +.SH NAME +winebuild \- Wine dll builder +.SH SYNOPSIS +.BI "winebuild " "[options] " "[inputfile]" +.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. +.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 +.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. +.TP +.BI \-debug\ [files] +Build a C file containing the definitions for debugging channels. The +\fIfiles\fR argument is a list of C files to search for debug channel +definitions. The resulting C file must be compiled and linked with the +dll. +.TP +.BI \-glue\ file.c +Build a C file containing the glue code for the 16-bit calls contained +in the \fIfile.c\fR source. These calls must be specified in the +source file 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 \fB-debug\fR mode. +.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). +.BI \-sym\ file.o +Read the list of undefined symbols from the object file file.o. +.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).