| blob | 86fe7318fd738b7943eebb3ae207bb932f67d9e4 |
1 This document should help new developers get started. Like all of Wine, it
2 is a work in progress.
5 SOURCE TREE STRUCTURE
6 =====================
8 The Wine source tree is loosely based on the original Windows modules.
9 Most of the source is concerned with implementing the Wine API, although
10 there are also various tools, documentation, sample Winelib code, and
11 code specific to the binary loader.
13 Wine API directories:
14 ---------------------
16 KERNEL:
18 files/ - file I/O
19 loader/ - Win16-, Win32-binary loader
20 memory/ - memory management
21 msdos/ - DOS features and BIOS calls (interrupts)
22 scheduler/ - process and thread management
24 GDI:
26 graphics/ - graphics drivers
27 x11drv/ - X11 display driver
28 win16drv/ -> see below
29 ttydrv/ - tty display driver
30 psdrv/ - PostScript graphics driver
31 metafiledrv/ - metafile driver
32 enhmetafiledrv/ - enhanced metafile driver
33 objects/ - logical objects
35 USER:
37 controls/ - built-in widgets
38 resources/ - built-in menu and message box resources
39 windows/ - window management
41 Other DLLs:
43 dlls/ - Other system DLLs implemented by Wine
44 advapi32/ - crypto, systeminfo, security, eventlogging
45 avifil32/ - COM object to play AVI files
46 comctl32/ - common controls
47 commdlg/ - common dialog boxes (both 16 & 32 bit)
48 dplayx/ - DirectX dplayx
49 dsound/ - DirectX dsound
50 imagehlp/ - PE (Portable Executable) Image Helper lib
51 imm32/
52 lzexpand/ - Liv-Zempel compression/decompression
53 mpr/ - Multi-Protocol Router (interface to various
54 network transport protocols)
55 msacm/ - audio compression manager (multimedia) (16 bit)
56 msacm32/ - audio compression manager (multimedia) (32 bit)
57 msnet/
58 msvideo/ - 16 bit video manager
59 ole32/ - 32 bit OLE 2.0 librairies
60 oleaut32/ - 32 bit OLE 2.0 automation
61 olecli/ - 16 bit OLE client
62 oledlg/ - OLE 2.0 user interface support
63 olesvr/ - 16 bit OLE server
64 ntdll/ - NT implementation of kernel calls
65 psapi/ - process status API
66 rasapi32/ - remote access server API
67 shell32/ - COM object implementing shell views
68 sound/ - Sound on loudspeaker (not sound card)
69 tapi32/ - telephone API
70 ver/ - File Installation Library (16 bit)
71 version/ - File Installation Library (32 bit)
72 win32s
73 win87em - 80387 math-emulation
74 winaspi/ - 16 bit Advanced SCSI Peripheral Interface
75 windebug/ - Windows debugger
76 wing/ - WinG (for games) internface
77 winmm/ - multimedia (16 & 32 bit)
78 mciXXX/ - various MCI drivers
79 wineoss/- MM driver for OSS systems
80 wavemap/- audio mapper
81 midimap/- midi mapper
82 winspool/ - Printing & Print Spooler
83 wnaspi32/ - 32 bit ASPI
85 Miscellaneous:
87 misc/ - shell, registry, winsock, etc.
88 ipc/ - SysV IPC based interprocess communication
89 win32/ - misc Win32 functions
90 ole/ - OLE code
91 nls/ - National Language Support
92 configuration files
94 Tools:
95 ------
97 rc/ - old resource compiler
98 tools/ - relay code builder, new rc, bugreport
99 generator, wineconfigurator, etc.
100 documentation/ - some documentation
103 Binary loader specific directories:
104 -----------------------------------
106 debugger/ - built-in debugger
107 if1632/ - relay code
108 miscemu/ - hardware instruction emulation
109 graphics/win16drv/ - Win16 printer driver
110 server/ - the main, controlling thread of wine
111 tsx11/ - thread-safe X11 wrappers (auto generated)
113 Winelib specific directories:
114 -----------------------------
116 library/ - Required code for programs using Winelib
117 libtest/ - Small samples and tests
118 programs/ - Extended samples / system utilities
121 IMPLEMENTING NEW API CALLS
122 ==========================
124 This is the simple version, and covers only Win32. Win16 is slightly uglier,
125 because of the Pascal heritage and the segmented memory model.
127 All of the Win32 APIs known to Wine are listed in [relay32/*.spec]. An
128 unimplemented call will look like (from gdi32.spec)
129 269 stub PolyBezierTo
130 To implement this call, you need to do the following four things.
132 1. Find the appropriate parameters for the call, and add a prototype to
133 the correct header file. In this case, that means [include/wingdi.h],
134 and it might look like
135 BOOL WINAPI PolyBezierTo(HDC, LPCVOID, DWORD);
136 If the function has both an ASCII and a Unicode version, you need to
137 define both and add a #define WINELIB_NAME_AW declaration. See below
138 for discussion of function naming conventions.
140 2. Modify the .spec file to tell Wine that the function has an
141 implementation, what the parameters look like and what Wine function
142 to use for the implementation. In Win32, things are simple--everything
143 is 32-bits. However, the relay code handles pointers and pointers to
144 strings slightly differently, so you should use 'str' and 'wstr' for
145 strings, 'ptr' for other pointer types, and 'long' for everything else.
146 269 stdcall PolyBezierTo(long ptr long) PolyBezierTo
147 The 'PolyBezierTo' at the end of the line is which Wine function to use
148 for the implementation.
150 3. Implement the function as a stub. Once you add the function to the .spec
151 file, you must add the function to the Wine source before it will link.
152 Add a function called 'PolyBezierTo' somewhere. Good things to put
153 into a stub:
154 o a correct prototype, including the WINAPI
155 o header comments, including full documentation for the function and
156 arguments (see documentation/README.documentation)
157 o A FIXME message and an appropriate return value are good things to
158 put in a stub.
160 /************************************************************
161 * PolyBezierTo (GDI32.269)
162 *
163 * Draw many Bezier curves
164 *
165 * RETURNS
166 * nonzero on success or zero on faillure
167 *
168 * BUGS
169 * Unimplemented
170 */
171 BOOL WINAPI PolyBezierTo(HDC hdc, /* handle to device context */
172 LPCVOID p, /* ptr to array of Point structs */
173 DWORD count /* nr of points in array */
174 )
175 {
176 /* tell the user they've got a substandard implementation */
177 FIXME(gdi, ":(%x,%p,%d): stub\n", hdc, p, count);
179 /* some programs may be able to compensate,
180 * if they know what happened
181 */
182 SetLastError(ERROR_CALL_NOT_IMPLEMENTED);
183 return FALSE; /* error value */
184 }
186 4. Implement and test the rest of the function.
189 IMPLEMENTING A NEW DLL
190 ======================
192 Apart from writing the set of needed .c files, you also need to do the
193 following:
195 1. Create a directory <MyDll> where to store the implementation of
196 the DLL.
198 If the DLL exists under Windows as both 16 and 32 bit DLL, you can
199 either create one directory for each, or have a single directory
200 with both implementations.
202 This (those) directory(ies) have to be put under the dlls/
203 directory in Wine tree structure.
205 2. Create the Makefile.in in the ./dlls/<MyDll>/ directory. You can
206 copy an existing Makefile.in from another ./dlls/ subdirectory.
208 You need at least to change the MODULE, SPEC_SRCS, and C_SRCS
209 macros.
211 3. Add the directory (and the generated .o file for the module) in:
212 + ./configure.in (in AC_OUTPUT macro at the end of the file to
213 trigger the Makefile generation),
214 + ./Makefile.in (in LIBSUBDIRS and LIBOBJS macros)
216 4. You can now regenerate ./configure file (with 'make configure')
217 and the various Makefiles (with 'configure; make depend') (run
218 from the top of Wine's tree).
220 You shall now have a Makefile file in ./dlls/<MyDll>/
222 5. You now need to declare the DLL in the module lists. This is done
223 by adding the corresponding descriptor in ./if1632/builtin.c if
224 your DLL is 16 bit (resp. ./relay32/builtin.c for a 32 bit DLL)
225 (or both if your directory contains the dual 16/32
226 implementations).
228 Note: the name of the descriptor is based on the module name, not
229 on the file name (they are the same in most of the case, but for
230 some DLLs it's not the case).
232 6. You also need to define the loadorder for the created DLL
233 (./wine.ini and ./module/loadorder.c). Usually, "native,builtin"
234 is ok. If you have written a paired 16/32 bit implementation, don't
235 forget to define it also in those files.
237 7. Create the .spec file for the DLL export points in your
238 directory. Refer to 'Implementation of new API calls' earlier in
239 this document for more information on this part.
241 8. Don't forget the .cvsignore file.
243 9. You can now start adding .c files.
245 10. For the .h files, if they are standard Windows one, put them in
246 include/. If they are linked to *your* implementation of the DLL,
247 put them in your newly created directory.
249 If you need to create a new debug channel, just add the
250 DECLARE_DEBUG_CHANNEL to your .c file(s) and rerun
251 tools/make_debug. When sending out your patch, you don't need to
252 provide nor ./configure nor the ./include/debugdefs.h diffs. Just
253 indicate that those files need to be regenerated.
255 MEMORY AND SEGMENTS
256 ===================
258 NE (Win16) executables consist of multiple segments. The Wine loader
259 loads each segment into a unique location in the Wine processes memory
260 and assigns a selector to that segment. Because of this, it's not
261 possible to exchange addresses freely between 16-bit and 32-bit code.
262 Addresses used by 16-bit code are segmented addresses (16:16), formed
263 by a 16-bit selector and a 16-bit offset. Those used by the Wine code
264 are regular 32-bit linear addresses.
266 There are four ways to obtain a segmented pointer:
267 - Use the SEGPTR_* macros in include/heap.h (recommended).
268 - Allocate a block of memory from the global heap and use
269 WIN16_GlobalLock to get its segmented address.
270 - Allocate a block of memory from a local heap, and build the
271 segmented address from the local heap selector (see the
272 USER_HEAP_* macros for an example of this).
273 - Declare the argument as 'segptr' instead of 'ptr' in the spec file
274 for a given API function.
276 Once you have a segmented pointer, it must be converted to a linear
277 pointer before you can use it from 32-bit code. This can be done with
278 the PTR_SEG_TO_LIN() and PTR_SEG_OFF_TO_LIN() macros. The linear
279 pointer can then be used freely with standard Unix functions like
280 memcpy() etc. without worrying about 64k boundaries. Note: there's no
281 easy way to convert back from a linear to a segmented address.
283 In most cases, you don't need to worry about segmented address, as the
284 conversion is made automatically by the callback code and the API
285 functions only see linear addresses. However, in some cases it is
286 necessary to manipulate segmented addresses; the most frequent cases
287 are:
288 - API functions that return a pointer
289 - lParam of Windows messages that point to a structure
290 - Pointers contained inside structures accessed by 16-bit code.
292 It is usually a good practice to used the type 'SEGPTR' for segmented
293 pointers, instead of something like 'LPSTR' or 'char *'. As SEGPTR is
294 defined as a DWORD, you'll get a compilation warning if you mistakenly
295 use it as a regular 32-bit pointer.
298 STRUCTURE PACKING
299 =================
301 Under Windows, data structures are tightly packed, i.e. there is no
302 padding between structure members. On the other hand, by default gcc
303 aligns structure members (e.g. WORDs are on a WORD boundary, etc.).
304 This means that a structure like
306 struct { BYTE x; WORD y; };
308 will take 3 bytes under Windows, but 4 with gcc, because gcc will add a
309 dummy byte between x and y. To have the correct layout for structures
310 used by Windows code, you need to embed the struct within two special
311 #include's which will take care of the packing for you:
313 #include "pshpack1.h"
314 struct { BYTE x; WORD y; };
315 #include "poppack1.h"
317 For alignment on a 2-byte boundary, there is a "pshpack2.h", etc.
319 The use of the WINE_PACKED attribute is obsolete. Please remove these
320 in favour of the above solution.
321 Using WINE_PACKED, you would declare the above structure like this:
323 struct { BYTE x; WORD y WINE_PACKED; };
325 You had to do this every time a structure member is not aligned
326 correctly under Windows (i.e. a WORD not on an even address, or a
327 DWORD on a address that was not a multiple of 4).
330 NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES
331 ==============================================
333 In order to support both Win16 and Win32 APIs within the same source
334 code, the following convention must be used in naming all API
335 functions and types. If the Windows API uses the name 'xxx', the Wine
336 code must use:
338 - 'xxx16' for the Win16 version,
339 - 'xxx' for the Win32 version when no ASCII/Unicode strings are
340 involved,
341 - 'xxxA' for the Win32 version with ASCII strings,
342 - 'xxxW' for the Win32 version with Unicode strings.
344 If the function has both ASCII and Unicode version, you should then
345 use the macros WINELIB_NAME_AW(xxx) or DECL_WINELIB_TYPE_AW(xxx)
346 (defined in include/windef.h) to define the correct 'xxx' function
347 or type for Winelib. When compiling Wine itself, 'xxx' is _not_
348 defined, meaning that code inside of Wine must always specify
349 explicitly the ASCII or Unicode version.
351 If 'xxx' is the same in Win16 and Win32, you can simply use the same
352 name as Windows, i.e. just 'xxx'. If 'xxx' is Win16 only, you could
353 use the name as is, but it's preferable to use 'xxx16' to make it
354 clear it is a Win16 function.
356 Examples:
358 typedef struct { /* Win32 ASCII data structure */ } WNDCLASSA;
359 typedef struct { /* Win32 Unicode data structure */ } WNDCLASSW;
360 typedef struct { /* Win16 data structure */ } WNDCLASS16;
361 DECL_WINELIB_TYPE_AW(WNDCLASS);
363 ATOM RegisterClass16( WNDCLASS16 * );
364 ATOM RegisterClassA( WNDCLASSA * );
365 ATOM RegisterClassW( WNDCLASSW * );
366 #define RegisterClass WINELIB_NAME_AW(RegisterClass)
368 The Winelib user can then say:
370 WNDCLASS wc = { ... };
371 RegisterClass( &wc );
373 and this will use the correct declaration depending on the definition
374 of the UNICODE symbol.
377 NAMING CONVENTIONS FOR NON-API FUNCTIONS AND TYPES
378 ==================================================
380 Functions and data which are internal to your code (or at least shouldn't be
381 visible to any WineLib or Windows program) should be preceded by
382 an identifier to the module:
384 Examples:
386 ENUMPRINTERS_GetDWORDFromRegistryA() (in dlls/winspool/info.c)
387 IAVIFile_fnRelease() (in dlls/avifil32/avifile.c)
388 X11DRV_CreateDC() (in graphics/x11drv/init.c)
389 TIMER_Init() (implemented in windows/timer.c,
390 used in loader/main.c )
392 if you need prototypes for these, there are a few possibilities:
393 - within same source file only:
394 put the prototypes at the top of your file and mark them as prototypes.
395 - within the same module:
396 create a header file within the subdirectory where that module resides,
397 e.g. graphics/ddraw_private.h
398 - from a totally different module, or for use in winelib:
399 put your header file entry in /include/wine/
400 but be careful not to clutter this directory!
401 under no circumstances, you should add non-api calls to the standard
402 windoze include files. Unfortunately, this is often the case, e.g.
403 the above example of TIMER_Init is defined in include/message.h
406 API ENTRY POINTS
407 ================
409 Because Win16 programs use a 16-bit stack and because they can only
410 call 16:16 addressed functions, all API entry points must be at low
411 address offsets and must have the arguments translated and moved to
412 Wines 32-bit stack. This task is handled by the code in the "if1632"
413 directory. To define a new API entry point handler you must place a
414 new entry in the appropriate API specification file. These files are
415 named *.spec. For example, the API specification file for the USER
416 DLL is contained in the file user.spec. These entries are processed
417 by the "build" program to create an assembly file containing the entry
418 point code for each API call. The format of the *.spec files is
419 documented in the file "tools/build-spec.txt".
422 DEBUG MESSAGES
423 ==============
425 To display a message only during debugging, you normally write something
426 like this:
428 TRACE(win,"abc..."); or
429 FIXME(win,"abc..."); or
430 WARN(win,"abc..."); or
431 ERR(win,"abc...");
433 depending on the seriousness of the problem. (documentation/degug-msgs
434 explains when it is appropriate to use each of them)
436 These macros are defined in include/debug.h. The macro-definitions are
437 generated by the shell-script tools/make_debug. It scans the source
438 code for symbols of this forms and puts the necessary macro
439 definitions in include/debug.h and include/debugdefs.h. These macros
440 test whether the debugging "channel" associated with the first
441 argument of these macros (win in the above example) is enabled and
442 thus decide whether to actually display the text. In addition you can
443 change the types of displayed messages by supplying the "-debugmsg"
444 option to Wine. If your debugging code is more complex than just
445 printf, you can use the symbols TRACE_ON(xxx), WARN_ON(xxx),
446 ERR_ON(xxx) and FIXME_ON(xxx) as well. These are true when channel xxx
447 is enabled, either permanent or in the command line. Thus, you can
448 write:
450 if(TRACE_ON(win))DumpSomeStructure(&str);
452 Don't worry about the inefficiency of the test. If it is permanently
453 disabled (that is TRACE_ON(win) is 0 at compile time), the compiler will
454 eliminate the dead code.
456 You have to start tools/make_debug only if you introduced a new macro,
457 e.g. TRACE(win32).
459 For more info about debugging messages, read:
461 documentation/debug-msgs
464 MORE INFO
465 =========
467 1. There is a FREE online version of the MSDN library (including
468 documentation for the Win32 API) on http://www.microsoft.com/msdn/
470 2. http://www.sonic.net/~undoc/bookstore.html
472 3. In 1993 Dr. Dobbs Journal published a column called "Undocumented Corner".
474 4. You might want to check out BYTE from December 1983 as well :-)