Added a winebuild man page.

tools/winebuild/.cvsignore

 Makefile
 winebuild
+winebuild.man

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:

tools/winebuild/README

-			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.

tools/winebuild/winebuild.man.in

+.\" -*- 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).