1WINEBUILD(1)                Wine Developers Manual                WINEBUILD(1)
2
3
4

NAME

6       winebuild - Wine dll builder
7

SYNOPSIS

9       winebuild [options] [inputfile...]
10

DESCRIPTION

12       winebuild  generates  the  assembly files that are necessary to build a
13       Wine dll, which is basically a Win32 dll encapsulated inside a Unix li‐
14       brary.
15
16       winebuild  has  different  modes,  depending on what kind of file it is
17       asked to generate. The mode is specified by one  of  the  mode  options
18       specified below. In addition to the mode option, various other command-
19       line option can be specified, as described in the OPTIONS section.
20

MODE OPTIONS

22       You have to specify exactly one of the following options, depending  on
23       what you want winebuild to generate.
24
25       --dll  Build  an  assembly file from a .spec file (see SPEC FILE SYNTAX
26              for  details),  or  from  a  standard  Windows  .def  file.  The
27              .spec/.def  file  is  specified via the -E option. The resulting
28              file must be assembled and linked to the other object  files  to
29              build  a working Wine dll.  In this mode, the input files should
30              be the list of all object files that will be linked into the fi‐
31              nal  dll,  to  allow  winebuild to get the list of all undefined
32              symbols that need to be imported from other dlls.
33
34       --exe  Build an assembly file for an executable. This is basically  the
35              same  as  the  --dll  mode  except  that  it  doesn't  require a
36              .spec/.def file as input, since an executable  need  not  export
37              functions. Some executables however do export functions, and for
38              those a .spec/.def file can be specified via the -E option.  The
39              executable is named from the .spec/.def file name if present, or
40              explicitly through the -F option. The resulting file must be as‐
41              sembled  and linked to the other object files to build a working
42              Wine executable, and all the other object files must  be  listed
43              as input files.
44
45       --def  Build  a .def file from a spec file. The .spec file is specified
46              via the -E option. This is used when building  dlls  with  a  PE
47              (Win32) compiler.
48
49       --implib
50              Build  a  .a  import library from a spec file. The .spec file is
51              specified via the -E option. If the output library name ends  in
52              .delay.a, a delayed import library is built.
53
54       --staticlib
55              Build a .a static library from object files.
56
57       --resources
58              Generate  a  .o file containing all the input resources. This is
59              useful when building with a PE compiler, since the  PE  binutils
60              cannot  handle  multiple resource files as input. For a standard
61              Unix build, the resource files are automatically  included  when
62              building  the  spec file, so there's no need for an intermediate
63              .o file.
64
65       --builtin
66              Mark a PE module as a Wine builtin module, by adding  the  "Wine
67              builtin DLL" signature string after the DOS header.
68
69       --fixup-ctors
70              Fixup constructors after a module has been built. This should be
71              done on the final .so module if its code contains  constructors,
72              to ensure that Wine has a chance to initialize the module before
73              the constructors are executed.
74

OPTIONS

76       --as-cmd=as-command
77              Specify the command to use to compile assembly  files;  the  de‐
78              fault is as.
79
80       -b, --target=cpu-manufacturer[-kernel]-os
81              Specify  the target CPU and platform on which the generated code
82              will be built. The target specification is in the standard auto‐
83              conf format as returned by config.sub.
84
85       -B directory
86              Add  the  directory  to the search path for the various binutils
87              tools like as, nm and ld.
88
89       --cc-cmd=cc-command
90              Specify the C compiler to use to compile assembly files; the de‐
91              fault is to instead use the assembler specified with --as-cmd.
92
93       --data-only
94              Build a module that contains only data and resources, and no ex‐
95              ecutable code.  With this option, winebuild directly  outputs  a
96              PE file, instead of an assembly or object file.
97
98       -d, --delay-lib=name
99              Set  the  delayed  import  mode for the specified library, which
100              must be one of the libraries imported with the  -l  option.  De‐
101              layed  mode means that the library won't be loaded until a func‐
102              tion imported from it is actually called.
103
104       -D symbol
105              Ignored for compatibility with the C compiler.
106
107       -e, --entry=function
108              Specify the module entry point function; if not  specified,  the
109              default  is  DllMain  for dlls, and main for executables (if the
110              standard C main is not defined, WinMain is used  instead).  This
111              is only valid for Win32 modules.
112
113       -E, --export=filename
114              Specify  a  .spec  file (see SPEC FILE SYNTAX for details), or a
115              standard Windows .def file that defines the exports of  the  DLL
116              or executable that is being built.
117
118       --external-symbols
119              Allow  linking  to external symbols directly from the spec file.
120              Normally symbols exported by a dll have to be defined in the dll
121              itself;  this option makes it possible to use symbols defined in
122              another Unix library (for symbols defined in another dll, a for‐
123              ward specification must be used instead).
124
125       -f option
126              Specify  a  code  generation option. Currently -fPIC and -fasyn‐
127              chronous-unwind-tables are supported. Other options are  ignored
128              for compatibility with the C compiler.
129
130       --fake-module
131              Create  a fake PE module for a dll or exe, instead of the normal
132              assembly or object file. The PE module  contains  the  resources
133              for the module, but no executable code.
134
135       -F, --filename=filename
136              Set  the file name of the module. The default is to use the base
137              name of the spec file (without any extension).
138
139       -h, --help
140              Display a usage message and exit.
141
142       -H, --heap=size
143              Specify the size of the module local heap in bytes  (only  valid
144              for Win16 modules); default is no local heap.
145
146       -I directory
147              Ignored for compatibility with the C compiler.
148
149       -k, --kill-at
150              Remove the stdcall decorations from the symbol names in the gen‐
151              erated .def file. Only meaningful in --def mode.
152
153       -K flags
154              Ignored for compatibility with the C compiler.
155
156       --large-address-aware
157              Set a flag in the executable to notify the loader that this  ap‐
158              plication supports address spaces larger than 2 gigabytes.
159
160       --ld-cmd=ld-command
161              Specify the command to use to link the object files; the default
162              is ld.
163
164       -L, --library-path=directory
165              Append the specified directory to the list of  directories  that
166              are searched for import libraries.
167
168       -l, --library=name
169              Import  the  specified library, looking for a corresponding lib‐
170              name.def file in the directories specified with the -L option.
171
172       -m16, -m32, -m64
173              Generate respectively 16-bit, 32-bit or 64-bit code.
174
175       -marm, -mthumb, -march=option, -mcpu=option, -mfpu=option, -mfloat-
176       abi=option
177              Set code generation options for the assembler.
178
179       -mno-cygwin
180              Build  a  library  that  uses the Windows runtime instead of the
181              Unix C library.
182
183       -M, --main-module=module
184              When building a 16-bit dll, set the name of its 32-bit  counter‐
185              part  to module. This is used to enforce that the load order for
186              the 16-bit dll matches that of the 32-bit one.
187
188       -N, --dll-name=dllname
189              Set the internal name of the module. It is only  used  in  Win16
190              modules.  The  default  is to use the base name of the spec file
191              (without any extension). This is used for KERNEL, since it lives
192              in KRNL386.EXE. It shouldn't be needed otherwise.
193
194       --nm-cmd=nm-command
195              Specify the command to use to get the list of undefined symbols;
196              the default is nm.
197
198       --nxcompat=yes|no
199              Specify whether the module is compatible with  no-exec  support.
200              The default is yes.
201
202       -o, --output=file
203              Set the name of the output file (default is standard output). If
204              the output file name ends in .o, the text output is  sent  to  a
205              temporary  file  that is then assembled to produce the specified
206              .o file.
207
208       --prefer-native
209              Specify that the native DLL should be preferred if available  at
210              run  time.  This can be used on modules that are mostly unimple‐
211              mented.
212
213       -r, --res=rsrc.res
214              Load resources from the  specified  binary  resource  file.  The
215              rsrc.res  file  can be produced from a source resource file with
216              wrc(1) (or with a Windows resource compiler).
217              This option is only necessary  for  Win16  resource  files,  the
218              Win32  ones  can simply listed as input files and will automati‐
219              cally be handled correctly (though the -r option will also  work
220              for Win32 files).
221
222       --safeseh
223              Mark object files as SEH compatible.
224
225       --save-temps
226              Do  not delete the various temporary files that winebuild gener‐
227              ates.
228
229       --subsystem=subsystem[:major[.minor]]
230              Set the subsystem of the executable, which can  be  one  of  the
231              following:
232              console for a command line executable,
233              windows for a graphical executable,
234              native for a native-mode dll,
235              wince for a ce dll.
236              The  entry point of a command line executable is a normal C main
237              function. A wmain function can be used instead if you  need  the
238              argument  array  to  use Unicode strings. A graphical executable
239              has a WinMain entry point.
240              Optionally a major and minor subsystem version can also be spec‐
241              ified; the default subsystem version is 4.0.
242
243       --syscall-table=id
244              Set the system call table id, between 0 and 3. The default is 0,
245              the ntdll syscall table. Only  useful  in  modules  that  define
246              syscall entry points.
247
248       -u, --undefined=symbol
249              Add  symbol  to  the list of undefined symbols when invoking the
250              linker. This makes it possible to force a specific module  of  a
251              static library to be included when resolving imports.
252
253       -v, --verbose
254              Display the various subcommands being invoked by winebuild.
255
256       --version
257              Display the program version and exit.
258
259       -w, --warnings
260              Turn on warnings.
261
262       --without-dlltool
263              Generate import library without using dlltool.
264

SPEC FILE SYNTAX

266   General syntax
267       A  spec file should contain a list of ordinal declarations. The general
268       syntax is the following:
269
270       ordinal functype [flags] exportname ( [args...] ) [handler]
271       ordinal variable [flags] exportname ( [data...] )
272       ordinal extern [flags] exportname [symbolname]
273       ordinal stub [flags] exportname [ (args...) ]
274       ordinal equate [flags] exportname data
275       # comments
276
277       Declarations must fit on a single line, except if the end  of  line  is
278       escaped using a backslash character. The # character anywhere in a line
279       causes the rest of the line to be ignored as a comment.
280
281       ordinal specifies the ordinal number corresponding to the entry  point,
282       or '@' for automatic ordinal allocation (Win32 only).
283
284       flags  is  a series of optional flags, preceded by a '-' character. The
285       supported flags are:
286
287              -norelay
288                     The entry point  is  not  displayed  in  relay  debugging
289                     traces (Win32 only).
290
291              -noname
292                     The entry point will be exported by ordinal instead of by
293                     name. The name is still available for importing.
294
295              -ret16 The function returns a 16-bit value (Win16 only).
296
297              -ret64 The function returns a 64-bit value (Win32 only).
298
299              -register
300                     The function uses CPU register to pass arguments.
301
302              -private
303                     The function cannot be imported from other dlls,  it  can
304                     only be accessed through GetProcAddress.
305
306              -ordinal
307                     The entry point will be imported by ordinal instead of by
308                     name. The name is still exported.
309
310              -thiscall
311                     The function uses the thiscall calling convention  (first
312                     parameter in %ecx register on i386).
313
314              -fastcall
315                     The  function uses the fastcall calling convention (first
316                     two parameters in %ecx/%edx registers on i386).
317
318              -syscall
319                     The function is an NT system call. A  system  call  thunk
320                     will be generated, and the actual function will be called
321                     by the __wine_syscall_dispatcher function  that  will  be
322                     generated on the Unix library side.
323
324              -import
325                     The function is imported from another module. This can be
326                     used instead of a forward specification when an  applica‐
327                     tion expects to find the function's implementation inside
328                     the dll.
329
330              -arch=[!]cpu[,cpu]
331                     The entry point is only available on  the  specified  CPU
332                     architecture(s).  The  names  win32  and  win64 match all
333                     32-bit  or  64-bit  CPU  architectures  respectively.  In
334                     16-bit  dlls,  specifying  -arch=win32  causes  the entry
335                     point to be exported from the 32-bit  wrapper  module.  A
336                     CPU name can be prefixed with ! to exclude only that spe‐
337                     cific architecture.
338
339   Function ordinals
340       Syntax:
341       ordinal functype [flags] exportname ( [args...] ) [handler]
342
343       This declaration defines a function entry point.  The prototype defined
344       by  exportname ( [args...] )  specifies  the name available for dynamic
345       linking and the format of the arguments. '@' can be used instead of ex‐
346       portname for ordinal-only exports.
347
348       functype should be one of:
349
350              stdcall
351                     for a normal Win32 function
352
353              pascal for a normal Win16 function
354
355              cdecl  for a Win16 or Win32 function using the C calling conven‐
356                     tion
357
358              varargs
359                     for a Win16 or Win32 function using the C calling conven‐
360                     tion with a variable number of arguments
361
362       args should be one or several of:
363
364              word   (16-bit unsigned value)
365
366              s_word (16-bit signed word)
367
368              long   (pointer-sized integer value)
369
370              int64  (64-bit integer value)
371
372              int128 (128-bit integer value)
373
374              float  (32-bit floating point value)
375
376              double (64-bit floating point value)
377
378              ptr    (linear pointer)
379
380              str    (linear pointer to a null-terminated ASCII string)
381
382              wstr   (linear pointer to a null-terminated Unicode string)
383
384              segptr (segmented pointer)
385
386              segstr (segmented pointer to a null-terminated ASCII string).
387
388              Note:  The 16-bit and segmented pointer types are only valid for
389                     Win16 functions.
390
391       handler is the name of the actual C function that will  implement  that
392       entry  point  in 32-bit mode. The handler can also be specified as dll‐
393       name.function to define a forwarded function (one whose  implementation
394       is  in  another  dll). If handler is not specified, it is assumed to be
395       identical to exportname.
396
397       This first example defines an entry point  for  the  32-bit  GetFocus()
398       call:
399
400              @ stdcall GetFocus() GetFocus
401
402       This  second  example  defines an entry point for the 16-bit CreateWin‐
403       dow() call (the ordinal 100 is just an example); it also shows how long
404       lines can be split using a backslash:
405
406              100 pascal CreateWindow(ptr ptr long s_word s_word s_word \
407                  s_word word word word ptr) WIN_CreateWindow
408
409       To declare a function using a variable number of arguments, specify the
410       function as varargs and declare it in the C file with a '...' parameter
411       for  a  Win32 function, or with an extra VA_LIST16 argument for a Win16
412       function.  See the wsprintf* functions in user.exe.spec and user32.spec
413       for an example.
414
415   Variable ordinals
416       Syntax:
417       ordinal variable [flags] exportname ( [data...] )
418
419       This  declaration  defines  data storage as 32-bit words at the ordinal
420       specified.  exportname will be the name available for dynamic  linking.
421       data  can  be  a  decimal number or a hex number preceded by "0x".  The
422       following example defines the variable VariableA at ordinal 2 and  con‐
423       taining 4 ints:
424
425              2 variable VariableA(-1 0xff 0 0)
426
427       This  declaration  only  works in Win16 spec files. In Win32 you should
428       use extern instead (see below).
429
430   Extern ordinals
431       Syntax:
432       ordinal extern [flags] exportname [symbolname]
433
434       This declaration defines an entry that simply maps to a C symbol (vari‐
435       able  or function). It only works in Win32 spec files.  exportname will
436       point to the symbol symbolname that must be defined in the C code.  Al‐
437       ternatively,  it can be of the form dllname.symbolname to define a for‐
438       warded symbol (one whose implementation is in another dll). If  symbol‐
439       name is not specified, it is assumed to be identical to exportname.
440
441   Stub ordinals
442       Syntax:
443       ordinal stub [flags] exportname [ (args...) ]
444
445       This declaration defines a stub function. It makes the name and ordinal
446       available for dynamic linking, but will terminate execution with an er‐
447       ror message if the function is ever called.
448
449   Equate ordinals
450       Syntax:
451       ordinal equate [flags] exportname data
452
453       This  declaration  defines an ordinal as an absolute value.  exportname
454       will be the name available for dynamic linking.  data can be a  decimal
455       number or a hex number preceded by "0x".
456
457   Api sets
458       Syntax:
459       apiset apiset_dll = target.dll [host.dll:target.dll]
460
461       This declaration defines that the apiset_dll (of the form api-ms-*) re‐
462       solves to the target dll. Optionally other targets can be specified  to
463       resolve differently for specific host dlls. For example:
464
465              api-ms-win-core-processenvironment-l1-1-0 = kernelbase.dll
466              api-ms-win-core-processthreads-l1-1-0 = kernel32.dll \
467                kernel32.dll:kernelbase.dll
468
469       If  apisets are defined, a corresponding .apiset section will be gener‐
470       ated in the PE binary. This  requires  building  the  module  with  the
471       --data-only option.
472

AUTHORS

474       winebuild  has  been  worked on by many people over the years. The main
475       authors are Robert J. Amstadt, Alexandre Julliard, Martin  von  Loewis,
476       Ulrich  Weigand  and Eric Youngdale. Many other people have contributed
477       new features and bug fixes. For a complete list,  see  the  git  commit
478       logs.
479

BUGS

481       It  is  not yet possible to use a PE-format dll in an import specifica‐
482       tion; only Wine dlls can be imported.
483
484       Bugs can be reported on the Wine bug tracker https://bugs.winehq.org⟩.
485

AVAILABILITY

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

SEE ALSO

491       wine(1), winegcc(1), wrc(1),
492       Wine documentation and support https://www.winehq.org/help⟩.
493
494
495
496Wine 8.19                        October 2005                     WINEBUILD(1)
Impressum