Provided by: wine64-tools_9.0~repack-4build3_amd64 bug

NAME

       winebuild - Wine dll builder

SYNOPSIS

       winebuild [options] [inputfile...]

DESCRIPTION

       winebuild  generates  the  assembly files that are necessary to build a Wine dll, which is
       basically a Win32 dll encapsulated inside a Unix library.

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

MODE OPTIONS

       You  have  to  specify  exactly  one  of the following options, depending on what you want
       winebuild to generate.

       --dll  Build an assembly file from a .spec file (see SPEC FILE  SYNTAX  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 input files should be the list of
              all object files that will be linked into the final dll, to allow winebuild to  get
              the list of all undefined symbols that need to be imported from other dlls.

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

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

       --implib
              Build  a .a import library from a spec file. The .spec file is specified via the -E
              option. If the output library name ends in .delay.a, a delayed  import  library  is
              built.

       --staticlib
              Build a .a static library from object files.

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

       --builtin
              Mark a PE module as a Wine  builtin  module,  by  adding  the  "Wine  builtin  DLL"
              signature string after the DOS header.

       --fixup-ctors
              Fixup  constructors after a module has been built. This should be done on the final
              .so module if its code contains constructors, to ensure that Wine has a  chance  to
              initialize the module before the constructors are executed.

OPTIONS

       --as-cmd=as-command
              Specify the command to use to compile assembly files; the default is as.

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

       -B directory
              Add the directory to the search path for the various binutils tools like as, nm and
              ld.

       --cc-cmd=cc-command
              Specify  the C compiler to use to compile assembly files; the default is to instead
              use the assembler specified with --as-cmd.

       --data-only
              Build a module that contains only data and resources, and no executable code.  With
              this option, winebuild directly outputs a PE file, instead of an assembly or object
              file.

       -d, --delay-lib=name
              Set the delayed import mode for the specified library, which must  be  one  of  the
              libraries imported with the -l option. Delayed mode means that the library won't be
              loaded until a function imported from it is actually called.

       -D symbol
              Ignored for compatibility with the C compiler.

       -e, --entry=function
              Specify the module entry point function; if not specified, the default  is  DllMain
              for  dlls, and main for executables (if the standard C main is not defined, WinMain
              is used instead). This is only valid for Win32 modules.

       -E, --export=filename
              Specify a .spec file (see SPEC FILE SYNTAX for details), or a standard Windows .def
              file that defines the exports of the DLL or executable that is being built.

       --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 forward specification must be used instead).

       -f option
              Specify a code generation option. Currently -fPIC and  -fasynchronous-unwind-tables
              are supported. Other options are ignored for compatibility with the C compiler.

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

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

       -h, --help
              Display a usage message and exit.

       -H, --heap=size
              Specify  the size of the module local heap in bytes (only valid for Win16 modules);
              default is no local heap.

       -I directory
              Ignored for compatibility with the C compiler.

       -k, --kill-at
              Remove the stdcall decorations from the symbol names in the  generated  .def  file.
              Only meaningful in --def mode.

       -K flags
              Ignored for compatibility with the C compiler.

       --large-address-aware
              Set  a  flag  in the executable to notify the loader that this application supports
              address spaces larger than 2 gigabytes.

       --ld-cmd=ld-command
              Specify the command to use to link the object files; the default is ld.

       -L, --library-path=directory
              Append the specified directory to the list of directories  that  are  searched  for
              import libraries.

       -l, --library=name
              Import  the  specified library, looking for a corresponding libname.def file in the
              directories specified with the -L option.

       -m16, -m32, -m64
              Generate respectively 16-bit, 32-bit or 64-bit code.

       -marm, -mthumb
              Select between generating code that executes in ARM and Thumb states.

       -march=option, -mcpu=option, -mfpu=option, -mfloat-abi=option
              Set code generation options for the assembler.

       -mno-cygwin
              Build a library that uses the Windows runtime instead of the Unix C library.

       -M, --main-module=module
              When building a 16-bit dll, set the name of its 32-bit counterpart to module.  This
              is  used  to  enforce  that  the  load order for the 16-bit dll matches that of the
              32-bit one.

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

       --nm-cmd=nm-command
              Specify the command to use to get the list of undefined symbols; the default is nm.

       --nxcompat=yes|no
              Specify whether the module is compatible with no-exec support. The default is yes.

       -o, --output=file
              Set the name of the output file (default is standard output). If  the  output  file
              name ends in .o, the text output is sent to a temporary file that is then assembled
              to produce the specified .o file.

       --prefer-native
              Specify that the native DLL should be preferred if available at run time. This  can
              be used on modules that are mostly unimplemented.

       -r, --res=rsrc.res
              Load  resources  from  the specified binary resource file. The rsrc.res file can be
              produced from a source resource file  with  wrc(1)  (or  with  a  Windows  resource
              compiler).
              This  option  is only necessary for Win16 resource files, the Win32 ones can simply
              listed as input files and will automatically be handled correctly  (though  the  -r
              option will also work for Win32 files).

       --safeseh
              Mark object files as SEH compatible.

       --save-temps
              Do not delete the various temporary files that winebuild generates.

       --subsystem=subsystem[:major[.minor]]
              Set the subsystem of the executable, which can be one of the following:
              console for a command line executable,
              windows for a graphical executable,
              native for a native-mode dll,
              wince for a ce dll.
              The  entry  point of a command line executable is a normal C main function. A wmain
              function can be used instead if you need the argument array to use Unicode strings.
              A graphical executable has a WinMain entry point.
              Optionally  a  major and minor subsystem version can also be specified; the default
              subsystem version is 4.0.

       --syscall-table=id
              Set the system call table id, between 0 and 3. The default is 0, the ntdll  syscall
              table. Only useful in modules that define syscall entry points.

       -u, --undefined=symbol
              Add symbol 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.

       -v, --verbose
              Display the various subcommands being invoked by winebuild.

       --version
              Display the program version and exit.

       -w, --warnings
              Turn on warnings.

       --without-dlltool
              Generate import library without using dlltool.

SPEC FILE SYNTAX

   General syntax
       A  spec  file  should  contain  a  list of ordinal declarations. The general syntax is the
       following:

       ordinal functype [flags] exportname ( [args...] ) [handler]
       ordinal variable [flags] exportname ( [data...] )
       ordinal extern [flags] exportname [symbolname]
       ordinal stub [flags] exportname [ (args...) ]
       ordinal equate [flags] exportname data
       # comments

       Declarations must fit on a single line, except if the end  of  line  is  escaped  using  a
       backslash  character. The # character anywhere in a line causes the rest of the line to be
       ignored as a comment.

       ordinal specifies 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:

              -norelay
                     The entry point is not displayed in relay debugging traces (Win32 only).

              -noname
                     The  entry point will be exported by ordinal instead of by name. The name is
                     still available for importing.

              -ret16 The function returns a 16-bit value (Win16 only).

              -ret64 The function returns a 64-bit value (Win32 only).

              -register
                     The function uses CPU register to pass arguments.

              -private
                     The function cannot be imported from other dlls, it  can  only  be  accessed
                     through GetProcAddress.

              -ordinal
                     The  entry point will be imported by ordinal instead of by name. The name is
                     still exported.

              -thiscall
                     The function uses the thiscall calling convention (first parameter  in  %ecx
                     register on i386).

              -fastcall
                     The  function  uses the fastcall calling convention (first two parameters in
                     %ecx/%edx registers on i386).

              -syscall
                     The function is an NT system call. A system call thunk  will  be  generated,
                     and  the  actual  function  will  be called by the __wine_syscall_dispatcher
                     function that will be generated on the Unix library side.

              -import
                     The function is imported from another module. This can be used instead of  a
                     forward  specification  when  an  application expects to find the function's
                     implementation inside the dll.

              -arch=[!]cpu[,cpu]
                     The entry point is only available on the specified CPU architecture(s).  The
                     names  win32  and  win64  match  all  32-bit  or  64-bit  CPU  architectures
                     respectively. In 16-bit dlls, specifying -arch=win32 causes the entry  point
                     to  be  exported  from the 32-bit wrapper module. A CPU name can be prefixed
                     with ! to exclude only that specific architecture.

   Function ordinals
       Syntax:
       ordinal functype [flags] exportname ( [args...] ) [handler]

       This  declaration  defines  a  function   entry   point.    The   prototype   defined   by
       exportname ( [args...] )  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:

              stdcall
                     for a normal Win32 function

              pascal for a normal Win16 function

              cdecl  for a Win16 or Win32 function using the C calling convention

              varargs
                     for a Win16 or Win32 function using the C calling convention with a variable
                     number of arguments

       args should be one or several of:

              word   (16-bit unsigned value)

              s_word (16-bit signed word)

              long   (pointer-sized integer value)

              int64  (64-bit integer value)

              int128 (128-bit integer value)

              float  (32-bit floating point value)

              double (64-bit floating point 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).

              Note: The 16-bit and segmented pointer types are only valid for Win16 functions.

       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 dllname.function to define  a  forwarded
       function  (one whose implementation is in another dll). If handler is not specified, it is
       assumed to be identical to exportname.

       This first example defines an entry point for the 32-bit GetFocus() call:

              @ stdcall GetFocus() GetFocus

       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:

              100 pascal CreateWindow(ptr ptr long s_word s_word s_word \
                  s_word word word word ptr) WIN_CreateWindow

       To  declare  a  function  using  a  variable  number of arguments, specify the function as
       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.

   Variable ordinals
       Syntax:
       ordinal variable [flags] exportname ( [data...] )

       This  declaration  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 preceded by "0x".  The following example defines the variable VariableA at
       ordinal 2 and containing 4 ints:

              2 variable VariableA(-1 0xff 0 0)

       This  declaration  only  works in Win16 spec files. In Win32 you should use extern instead
       (see below).

   Extern ordinals
       Syntax:
       ordinal extern [flags] exportname [symbolname]

       This declaration defines an entry that simply maps to a C symbol (variable  or  function).
       It  only  works  in Win32 spec files.  exportname will point to the symbol symbolname that
       must be defined in the C code. Alternatively, it can be of the form dllname.symbolname  to
       define  a  forwarded symbol (one whose implementation is in another dll). If symbolname is
       not specified, it is assumed to be identical to exportname.

   Stub ordinals
       Syntax:
       ordinal stub [flags] exportname [ (args...) ]

       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.

   Equate ordinals
       Syntax:
       ordinal equate [flags] exportname data

       This declaration 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 preceded by
       "0x".

   Api sets
       Syntax:
       apiset apiset_dll = target.dll [host.dll:target.dll]

       This declaration defines that the apiset_dll (of the form api-ms-*) resolves to the target
       dll.  Optionally  other  targets can be specified to resolve differently for specific host
       dlls. For example:

              api-ms-win-core-processenvironment-l1-1-0 = kernelbase.dll
              api-ms-win-core-processthreads-l1-1-0 = kernel32.dll \
                kernel32.dll:kernelbase.dll

       If apisets are defined, a corresponding .apiset  section  will  be  generated  in  the  PE
       binary. This requires building the module with the --data-only option.

AUTHORS

       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 people have contributed new features and bug fixes. For a complete list, see the git
       commit logs.

BUGS

       It is not yet possible to use a PE-format dll in an import specification; only  Wine  dlls
       can be imported.

       Bugs can be reported on the Wine bug tracker ⟨https://bugs.winehq.org⟩.

AVAILABILITY

       winebuild  is  part  of the Wine distribution, which is available through WineHQ, the Wine
       development headquarters ⟨https://www.winehq.org/⟩.

SEE ALSO

       wine(1), winegcc(1), wrc(1),
       Wine documentation and support ⟨https://www.winehq.org/help⟩.