1WINEBUILD(1) Wine Developers Manual WINEBUILD(1)
2
6 winebuild - Wine dll builder
7
9 winebuild [options] [input files]
10
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
14 library.
15 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
22 You have to specify exactly one of the following options, depending on
23 what you want winebuild to generate.
24 --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
31 final dll, to allow winebuild to get the list of all undefined
32 symbols that need to be imported from other dlls.
33 --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
41 assembled and linked to the other object files to build a work‐
42 ing Wine executable, and all the other object files must be
43 listed as input files.
44 --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 --implib
50 Build a PE import library from a spec file. The .spec file is
51 specified via the -E option.
52 --resources
54 Generate a .o file containing all the input resources. This is
55 useful when building with a PE compiler, since the PE binutils
56 cannot handle multiple resource files as input. For a standard
57 Unix build, the resource files are automatically included when
58 building the spec file, so there's no need for an intermediate
59 .o file.
60
62 --as-cmd=as-command
63 Specify the command to use to compile assembly files; the
64 default is as.
65 -b, --target=cpu-manufacturer[-kernel]-os
67 Specify the target CPU and platform on which the generated code
68 will be built. The target specification is in the standard auto‐
69 conf format as returned by config.sub.
70 -d, --delay-lib=name
72 Set the delayed import mode for the specified library, which
73 must be one of the libraries imported with the -l option.
74 Delayed mode means that the library won't be loaded until a
75 function imported from it is actually called.
76 -D symbol
78 Ignored for compatibility with the C compiler.
79 -e, --entry=function
81 Specify the module entry point function; if not specified, the
82 default is DllMain for dlls, and main for executables (if the
83 standard C main is not defined, WinMain is used instead). This
84 is only valid for Win32 modules.
85 -E, --export=filename
87 Specify a .spec file (see SPEC FILE SYNTAX for details), or a
88 standard Windows .def file that defines the exports of the DLL
89 or executable that is being built.
90 --external-symbols
92 Allow linking to external symbols directly from the spec file.
93 Normally symbols exported by a dll have to be defined in the dll
94 itself; this option makes it possible to use symbols defined in
95 another Unix library (for symbols defined in another dll, a for‐
96 ward specification must be used instead).
97 -f option
99 Specify a code generation option. Currently -fPIC and -fasyn‐
100 chronous-unwind-tables are supported. Other options are ignored
101 for compatibility with the C compiler.
102 --fake-module
104 Create a fake PE module for a dll or exe, instead of the normal
105 assembly or object file. The PE module contains the resources
106 for the module, but no executable code.
107 -F, --filename=filename
109 Set the file name of the module. The default is to use the base
110 name of the spec file (without any extension).
111 -h, --help
113 Display a usage message and exit.
114 -H, --heap=size
116 Specify the size of the module local heap in bytes (only valid
117 for Win16 modules); default is no local heap.
118 -I directory
120 Ignored for compatibility with the C compiler.
121 -k, --kill-at
123 Remove the stdcall decorations from the symbol names in the gen‐
124 erated .def file. Only meaningful in --def mode.
125 -K flags
127 Ignored for compatibility with the C compiler.
128 --large-address-aware
130 Set a flag in the executable to notify the loader that this
131 application supports address spaces larger than 2 gigabytes.
132 --ld-cmd=ld-command
134 Specify the command to use to link the object files; the default
135 is ld.
136 -L, --library-path=directory
138 Append the specified directory to the list of directories that
139 are searched for import libraries.
140 -l, --library=name
142 Import the specified library, looking for a corresponding lib‐
143 name.def file in the directories specified with the -L option.
144 -m16, -m32, -m64
146 Generate 16-bit, 32-bit, respectively 64-bit code.
147 -M, --main-module=module
149 When building a 16-bit dll, set the name of its 32-bit counter‐
150 part to module. This is used to enforce that the load order for
151 the 16-bit dll matches that of the 32-bit one.
152 -N, --dll-name=dllname
154 Set the internal name of the module. It is only used in Win16
155 modules. The default is to use the base name of the spec file
156 (without any extension). This is used for KERNEL, since it lives
157 in KRNL386.EXE. It shouldn't be needed otherwise.
158 --nm-cmd=nm-command
160 Specify the command to use to get the list of undefined symbols;
161 the default is nm.
162 --nxcompat=yes|no
164 Specify whether the module is compatible with no-exec support.
165 The default is yes.
166 -o, --output=file
168 Set the name of the output file (default is standard output). If
169 the output file name end in .o, the text output is sent to a
170 temporary file that is then assembled to produce the specified
171 .o file.
172 -r, --res=rsrc.res
174 Load resources from the specified binary resource file. The
175 rsrc.res file can be produced from a source resource file with
176 wrc(1) (or with a Windows resource compiler).
177 This option is only necessary for Win16 resource files, the
178 Win32 ones can simply listed as input files and will automati‐
179 cally be handled correctly (though the -r option will also work
180 for Win32 files).
181 --save-temps
183 Do not delete the various temporary files that winebuild gener‐
184 ates.
185 --subsystem=subsystem[:major[.minor]]
187 Set the subsystem of the executable, which can be one of the
188 following:
189 console for a command line executable,
190 windows for a graphical executable,
191 native for a native-mode dll,
192 wince for a ce dll.
193 The entry point of a command line executable is a normal C main
194 function. A wmain function can be used instead if you need the
195 argument array to use Unicode strings. A graphical executable
196 has a WinMain entry point.
197 Optionally a major and minor subsystem version can also be spec‐
198 ified; the default subsystem version is 4.0.
199 -u, --undefined=symbol
201 Add symbol to the list of undefined symbols when invoking the
202 linker. This makes it possible to force a specific module of a
203 static library to be included when resolving imports.
204 -v, --verbose
206 Display the various subcommands being invoked by winebuild.
207 --version
209 Display the program version and exit.
210 -w, --warnings
212 Turn on warnings.
213
215 General syntax
216 A spec file should contain a list of ordinal declarations. The general
217 syntax is the following:
218 ordinal functype [flags] exportname ( [args...] ) [handler]
220 ordinal variable [flags] exportname ( [data...] )
221 ordinal extern [flags] exportname [symbolname]
222 ordinal stub [flags] exportname [ (args...) ]
223 ordinal equate [flags] exportname data
224 # comments
225 Declarations must fit on a single line, except if the end of line is
227 escaped using a backslash character. The # character anywhere in a line
228 causes the rest of the line to be ignored as a comment.
229 ordinal specifies the ordinal number corresponding to the entry point,
231 or '@' for automatic ordinal allocation (Win32 only).
232 flags is a series of optional flags, preceded by a '-' character. The
234 supported flags are:
235 -norelay
237 The entry point is not displayed in relay debugging
238 traces (Win32 only).
239 -noname
241 The entry point will be exported by ordinal instead of by
242 name. The name is still available for importing.
243 -ret16 The function returns a 16-bit value (Win16 only).
245 -ret64 The function returns a 64-bit value (Win32 only).
247 -register
249 The function uses CPU register to pass arguments.
250 -private
252 The function cannot be imported from other dlls, it can
253 only be accessed through GetProcAddress.
254 -ordinal
256 The entry point will be imported by ordinal instead of by
257 name. The name is still exported.
258 -arch=cpu[,cpu]
260 The entry point is only available on the specified CPU
261 architecture(s). The names win32 and win64 match all
262 32-bit, respectively 64-bit, CPU architectures. In 16-bit
263 dlls, specifying -arch=win32 causes the entry point to be
264 exported from the 32-bit wrapper module.
265 Function ordinals
267 Syntax:
268 ordinal functype [flags] exportname ( [args...] ) [handler]
269 This declaration defines a function entry point. The prototype defined
271 by exportname ( [args...] ) specifies the name available for dynamic
272 linking and the format of the arguments. '@' can be used instead of
273 exportname for ordinal-only exports.
274 functype should be one of:
276 stdcall
278 for a normal Win32 function
279 pascal for a normal Win16 function
281 cdecl for a Win16 or Win32 function using the C calling conven‐
283 tion
284 varargs
286 for a Win16 or Win32 function using the C calling conven‐
287 tion with a variable number of arguments
288 thiscall
290 for a Win32 function using the thiscall calling conven‐
291 tion (first parameter in %ecx register on i386)
292 args should be one or several of:
294 word (16-bit unsigned value)
296 s_word (16-bit signed word)
298 long (pointer-sized integer value)
300 int64 (64-bit integer value)
302 int128 (128-bit integer value)
304 float (32-bit floating point value)
306 double (64-bit floating point value)
308 ptr (linear pointer)
310 str (linear pointer to a null-terminated ASCII string)
312 wstr (linear pointer to a null-terminated Unicode string)
314 segptr (segmented pointer)
316 segstr (segmented pointer to a null-terminated ASCII string).
318 Note: The 16-bit and segmented pointer types are only valid for
320 Win16 functions.
321 handler is the name of the actual C function that will implement that
323 entry point in 32-bit mode. The handler can also be specified as dll‐
324 name.function to define a forwarded function (one whose implementation
325 is in another dll). If handler is not specified, it is assumed to be
326 identical to exportname.
327 This first example defines an entry point for the 32-bit GetFocus()
329 call:
330 @ stdcall GetFocus() GetFocus
332 This second example defines an entry point for the 16-bit CreateWin‐
334 dow() call (the ordinal 100 is just an example); it also shows how long
335 lines can be split using a backslash:
336 100 pascal CreateWindow(ptr ptr long s_word s_word s_word \
338 s_word word word word ptr) WIN_CreateWindow
339 To declare a function using a variable number of arguments, specify the
341 function as varargs and declare it in the C file with a '...' parameter
342 for a Win32 function, or with an extra VA_LIST16 argument for a Win16
343 function. See the wsprintf* functions in user.exe.spec and user32.spec
344 for an example.
345 Variable ordinals
347 Syntax:
348 ordinal variable [flags] exportname ( [data...] )
349 This declaration defines data storage as 32-bit words at the ordinal
351 specified. exportname will be the name available for dynamic linking.
352 data can be a decimal number or a hex number preceded by "0x". The
353 following example defines the variable VariableA at ordinal 2 and con‐
354 taining 4 ints:
355 2 variable VariableA(-1 0xff 0 0)
357 This declaration only works in Win16 spec files. In Win32 you should
359 use extern instead (see below).
360 Extern ordinals
362 Syntax:
363 ordinal extern [flags] exportname [symbolname]
364 This declaration defines an entry that simply maps to a C symbol (vari‐
366 able or function). It only works in Win32 spec files. exportname will
367 point to the symbol symbolname that must be defined in the C code.
368 Alternatively, it can be of the form dllname.symbolname to define a
369 forwarded symbol (one whose implementation is in another dll). If sym‐
370 bolname is not specified, it is assumed to be identical to exportname.
371 Stub ordinals
373 Syntax:
374 ordinal stub [flags] exportname [ (args...) ]
375 This declaration defines a stub function. It makes the name and ordinal
377 available for dynamic linking, but will terminate execution with an
378 error message if the function is ever called.
379 Equate ordinals
381 Syntax:
382 ordinal equate [flags] exportname data
383 This declaration defines an ordinal as an absolute value. exportname
385 will be the name available for dynamic linking. data can be a decimal
386 number or a hex number preceded by "0x".
387
389 winebuild has been worked on by many people over the years. The main
390 authors are Robert J. Amstadt, Alexandre Julliard, Martin von Loewis,
391 Ulrich Weigand and Eric Youngdale. Many other Wine developers have con‐
392 tributed, please check the file Changelog in the Wine distribution for
393 the complete details.
394
396 It is not yet possible to use a PE-format dll in an import specifica‐
397 tion; only Wine dlls can be imported.
398 If you find a bug, please submit a bug report at
400 http://bugs.winehq.org. ⟨http://bugs.winehq.org⟩
401
403 winebuild is part of the wine distribution, which is available through
404 WineHQ, the wine development headquarters, at http://www.winehq.org/.
405 ⟨http://www.winehq.org/⟩
406
408 wine(1), winegcc(1), wrc(1).
409Wine 1.3.24 October 2005 WINEBUILD(1)