| blob | be0fc3c531c138c0c7787ddb11bf50abe9564922 |
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 memory/ - memory management
20 scheduler/ - process and thread management
21 winnls/ - National Language Support configuration files
23 GDI:
25 graphics/ - graphics drivers
26 x11drv/ - X11 display driver
27 win16drv/ -> see below
28 ttydrv/ - tty display driver
29 psdrv/ - PostScript graphics driver
30 metafiledrv/ - metafile driver
31 enhmetafiledrv/ - enhanced metafile driver
32 wing/ - WinG (for games) internface
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 avicap32/
46 avifil32/ - COM object to play AVI files
47 comctl32/ - common controls
48 commdlg/ - common dialog boxes (both 16 & 32 bit)
49 crtdll/ - Old C runtime library
50 crypt32/
51 dciman32/
52 ddraw/ - DirectX ddraw
53 dinput/ - DirectX dinput
54 dplay/ - DirectX dplay
55 dplayx/ - DirectX dplayx
56 dsound/ - DirectX dsound
57 glu32/
58 icmp/
59 imagehlp/ - PE (Portable Executable) Image Helper lib
60 imm32/
61 lzexpand/ - Liv-Zempel compression/decompression
62 mpr/ - Multi-Protocol Router (interface to various
63 network transport protocols)
64 msacm/ - audio compression manager (multimedia) (16 bit)
65 msacm32/ - audio compression manager (multimedia) (32 bit)
66 msdmo/
67 msimg32/
68 msisys/
69 msnet/
70 msrle32
71 msvcrt/ - 16 bit C runtime library
72 msvcrt20/ - 32 bit C runtime library
73 msvideo/ - 16 bit video manager
74 netapi32/
75 ntdll/ - NT implementation of kernel calls
76 odbc32/
77 ole32/ - 32 bit OLE 2.0 libraries
78 oleaut32/ - 32 bit OLE 2.0 automation
79 olecli/ - 16 bit OLE client
80 oledlg/ - OLE 2.0 user interface support
81 olepro32/ - 32 bit OLE 2.0 automation
82 olesvr/ - 16 bit OLE server
83 opengl32/ - OpenGL implementation
84 psapi/ - process status API
85 qcap/
86 quartz/
87 rasapi32/ - remote access server API
88 richedit/
89 rpcrt4/
90 serialui/
91 setupapi/
92 shdocvw/
93 shfolder/
94 shell32/ - COM object implementing shell views
95 shlwapi/
96 sti/
97 tapi32/ - telephone API
98 url
99 urlmon
100 ver/ - File Installation Library (16 bit)
101 version/ - File Installation Library (32 bit)
102 win32s/
103 win87em/ - 80387 math-emulation
104 winaspi/ - 16 bit Advanced SCSI Peripheral Interface
105 winedos/ - DOS features and BIOS calls (interrupts)
106 winmm/ - multimedia (16 & 32 bit)
107 mciXXX/ - various MCI drivers
108 midimap/- midi mapper
109 wavemap/- audio mapper
110 winearts/ - ARTS audio driver
111 wineoss/- MM driver for OSS systems
112 winnls/ - National Language Support
113 winsock/
114 wsock32/
115 winspool/ - Printing & Print Spooler
116 wintrust/
117 wnaspi32/ - 32 bit ASPI
119 Miscellaneous:
121 misc/ - shell, registry, winsock, etc.
122 ipc/ - SysV IPC based interprocess communication
123 win32/ - misc Win32 functions
125 Tools:
126 ------
128 tools/ - relay code builder, new rc, bugreport
129 generator, wineconfigurator, etc.
130 documentation/ - some documentation
133 Binary loader specific directories:
134 -----------------------------------
136 debugger/ - built-in debugger
137 if1632/ - relay code
138 miscemu/ - hardware instruction emulation
139 graphics/win16drv/ - Win16 printer driver
140 server/ - the main, controlling thread of wine
141 tsx11/ - thread-safe X11 wrappers (auto generated)
143 Winelib specific directories:
144 -----------------------------
146 library/ - Required code for programs using Winelib
147 libtest/ - Small samples and tests
148 programs/ - Extended samples / system utilities
151 IMPLEMENTING NEW API CALLS
152 ==========================
154 This is the simple version, and covers only Win32. Win16 is slightly uglier,
155 because of the Pascal heritage and the segmented memory model.
157 All of the Win32 APIs known to Wine are listed in [relay32/*.spec]. An
158 unimplemented call will look like (from gdi32.spec)
159 269 stub PolyBezierTo
160 To implement this call, you need to do the following four things.
162 1. Find the appropriate parameters for the call, and add a prototype to
163 the correct header file. In this case, that means [include/wingdi.h],
164 and it might look like
165 BOOL WINAPI PolyBezierTo(HDC, LPCVOID, DWORD);
166 If the function has both an ASCII and a Unicode version, you need to
167 define both and add a #define WINELIB_NAME_AW declaration. See below
168 for discussion of function naming conventions.
170 2. Modify the .spec file to tell Wine that the function has an
171 implementation, what the parameters look like and what Wine function
172 to use for the implementation. In Win32, things are simple--everything
173 is 32-bits. However, the relay code handles pointers and pointers to
174 strings slightly differently, so you should use 'str' and 'wstr' for
175 strings, 'ptr' for other pointer types, and 'long' for everything else.
176 269 stdcall PolyBezierTo(long ptr long) PolyBezierTo
177 The 'PolyBezierTo' at the end of the line is which Wine function to use
178 for the implementation.
180 3. Implement the function as a stub. Once you add the function to the .spec
181 file, you must add the function to the Wine source before it will link.
182 Add a function called 'PolyBezierTo' somewhere. Good things to put
183 into a stub:
184 o a correct prototype, including the WINAPI
185 o header comments, including full documentation for the function and
186 arguments (see documentation/README.documentation)
187 o A FIXME message and an appropriate return value are good things to
188 put in a stub.
190 /************************************************************
191 * PolyBezierTo (GDI32.269)
192 *
193 * Draw many Bezier curves
194 *
195 * RETURNS
196 * nonzero on success or zero on faillure
197 *
198 * BUGS
199 * Unimplemented
200 */
201 BOOL WINAPI PolyBezierTo(HDC hdc, /* handle to device context */
202 LPCVOID p, /* ptr to array of Point structs */
203 DWORD count /* nr of points in array */
204 )
205 {
206 /* tell the user they've got a substandard implementation */
207 FIXME(gdi, ":(%x,%p,%d): stub\n", hdc, p, count);
209 /* some programs may be able to compensate,
210 * if they know what happened
211 */
212 SetLastError(ERROR_CALL_NOT_IMPLEMENTED);
213 return FALSE; /* error value */
214 }
216 4. Implement and test the rest of the function.
219 IMPLEMENTING A NEW DLL
220 ======================
222 Generic directions
223 ------------------
225 Apart from writing the set of needed .c files, you also need to do the
226 following:
228 1. Create a directory <MyDll> where to store the implementation of
229 the DLL.
231 If the DLL exists under Windows as both 16 and 32 bit DLL, you can
232 either create one directory for each, or have a single directory
233 with both implementations.
235 This (those) directory(ies) have to be put under the dlls/
236 directory in Wine tree structure.
238 2. Create the Makefile.in in the ./dlls/<MyDll>/ directory. You can
239 copy an existing Makefile.in from another ./dlls/ subdirectory.
241 You need at least to change the MODULE, SPEC_SRCS, and C_SRCS
242 macros.
244 3. Add the directory (and the generated .o file for the module) in:
245 + ./configure.in (in AC_OUTPUT macro at the end of the file to
246 trigger the Makefile generation),
247 + ./Makefile.in (in LIBSUBDIRS and LIBOBJS macros)
248 + ./dlls/Makefile.in (in SUBDIRS macro)
250 4. You can now regenerate ./configure file (with 'make configure')
251 and the various Makefiles (with 'configure; make depend') (run
252 from the top of Wine's tree).
254 You shall now have a Makefile file in ./dlls/<MyDll>/
256 5. You now need to declare the DLL in the module lists. This is done
257 by adding the corresponding descriptor in ./if1632/builtin.c if
258 your DLL is 16 bit (resp. ./relay32/builtin.c for a 32 bit DLL)
259 (or both if your directory contains the dual 16/32
260 implementations).
262 Note: the name of the descriptor is based on the module name, not
263 on the file name (they are the same in most of the case, but for
264 some DLLs it's not the case).
266 6. You also need to define the loadorder for the created DLL
267 (./wine.ini and ./loader/loadorder.c). Usually, "native,builtin"
268 is ok. If you have written a paired 16/32 bit implementation, don't
269 forget to define it also in those files.
271 7. Create the .spec file for the DLL export points in your
272 directory. Refer to 'Implementation of new API calls' earlier in
273 this document for more information on this part.
275 8. Don't forget the .cvsignore file. The .cvsignore contain (on a per
276 directory basis) all the files generated by the compilation
277 process, why cvs shall ignore when processing the dir.
278 *.o is in there by default, but in Wine case you will find:
279 - Makefile (generated from Makefile.in)
280 - *.spec.c: those c files are generated by tools/build from the
281 .spec file
282 - when thunking down to 16 bit DLLs, you'll get some others (.glue.c)
283 - result of .y => .c translation (by yacc or bison)
284 - result of .rc compilation
285 - ...
286 For a simple DLL, listing in .cvsignore Makefile and
287 <MyDll>.spec.c will do.
289 9. You can now start adding .c files.
291 10. For the .h files, if they are standard Windows one, put them in
292 include/. If they are linked to *your* implementation of the DLL,
293 put them in your newly created directory.
295 Debug channels
296 --------------
298 If you need to create a new debug channel, just add the
299 DECLARE_DEBUG_CHANNEL to your .c file(s) and rerun
300 tools/make_debug. When sending out your patch, you don't need to
301 provide neither ./configure nor the ./include/debugdefs.h diffs. Just
302 indicate that those files need to be regenerated.
304 Resources
305 ---------
307 If you also need to add resources to your DLL, the create the .rc
308 file. Since, the .rc file will be translated into a .s file, and then
309 compiled as a .o file, its basename must be different from the
310 basename of any .c file.
311 Add to your ./dlls/<MyDll>/Makefile.in, in the RC_SRCS macro, the list
312 of .rc files to add to the DLL. You may also have to add the following
313 directives
314 1/ to tell gnumake to translate .rc into .s files,
315 $(RC_SRCS:.rc=.s): $(WRC)
316 2/ to give some parameters to wrc for helping the translation.
317 WRCEXTRA = -s -p$(MODULE)
319 See dlls/comctl32/ for an example of this.
321 Thunking
322 --------
324 If you're building a 16 & 32 bit DLLs pair, then from the 32 bit code
325 you might need to call 16 bit routine. The way to do it to add in the
326 code, fragments like:
327 /* ### Start build ### */
328 extern WORD CALLBACK <PREFIX>_CallTo16_word_wwlll(FARPROC16,WORD,WORD,LONG,LONG,LONG);
329 /* ### stop build ### */
330 Where <PREFIX>_ is an internal prefix for your module. The first
331 parameter is always of type FARPROC16. Then, you can get the regular
332 list of parameters. The _word_wwlll indicates the type of return (long
333 or word) and the size of the parameters (here l=>long, w=>word; which
334 maps to WORD,WORD,LONG,LONG,LONG.
335 You can put several functions between the Start/Stop build pair.
337 You can also read tools/build.txt for more details on this.
339 Then, add to ./dlls/<MyDll>/Makefile.in to the macro GLUE the list of
340 .c files containing the /* ### Start build ### */ directives.
342 See dlls/winmm/ for an example of this.
344 MEMORY AND SEGMENTS
345 ===================
347 NE (Win16) executables consist of multiple segments. The Wine loader
348 loads each segment into a unique location in the Wine processes memory
349 and assigns a selector to that segment. Because of this, it's not
350 possible to exchange addresses freely between 16-bit and 32-bit code.
351 Addresses used by 16-bit code are segmented addresses (16:16), formed
352 by a 16-bit selector and a 16-bit offset. Those used by the Wine code
353 are regular 32-bit linear addresses.
355 There are four ways to obtain a segmented pointer:
356 - Use the SEGPTR_* macros in include/heap.h (recommended).
357 - Allocate a block of memory from the global heap and use
358 WIN16_GlobalLock to get its segmented address.
359 - Allocate a block of memory from a local heap, and build the
360 segmented address from the local heap selector (see the
361 USER_HEAP_* macros for an example of this).
362 - Declare the argument as 'segptr' instead of 'ptr' in the spec file
363 for a given API function.
365 Once you have a segmented pointer, it must be converted to a linear
366 pointer before you can use it from 32-bit code. This can be done with
367 the PTR_SEG_TO_LIN() and PTR_SEG_OFF_TO_LIN() macros. The linear
368 pointer can then be used freely with standard Unix functions like
369 memcpy() etc. without worrying about 64k boundaries. Note: there's no
370 easy way to convert back from a linear to a segmented address.
372 In most cases, you don't need to worry about segmented address, as the
373 conversion is made automatically by the callback code and the API
374 functions only see linear addresses. However, in some cases it is
375 necessary to manipulate segmented addresses; the most frequent cases
376 are:
377 - API functions that return a pointer
378 - lParam of Windows messages that point to a structure
379 - Pointers contained inside structures accessed by 16-bit code.
381 It is usually a good practice to used the type 'SEGPTR' for segmented
382 pointers, instead of something like 'LPSTR' or 'char *'. As SEGPTR is
383 defined as a DWORD, you'll get a compilation warning if you mistakenly
384 use it as a regular 32-bit pointer.
387 STRUCTURE PACKING
388 =================
390 Under Windows, data structures are tightly packed, i.e. there is no
391 padding between structure members. On the other hand, by default gcc
392 aligns structure members (e.g. WORDs are on a WORD boundary, etc.).
393 This means that a structure like
395 struct { BYTE x; WORD y; };
397 will take 3 bytes under Windows, but 4 with gcc, because gcc will add a
398 dummy byte between x and y. To have the correct layout for structures
399 used by Windows code, you need to embed the struct within two special
400 #include's which will take care of the packing for you:
402 #include "pshpack1.h"
403 struct { BYTE x; WORD y; };
404 #include "poppack1.h"
406 For alignment on a 2-byte boundary, there is a "pshpack2.h", etc.
408 The use of the WINE_PACKED attribute is obsolete. Please remove these
409 in favour of the above solution.
410 Using WINE_PACKED, you would declare the above structure like this:
412 struct { BYTE x; WORD y WINE_PACKED; };
414 You had to do this every time a structure member is not aligned
415 correctly under Windows (i.e. a WORD not on an even address, or a
416 DWORD on a address that was not a multiple of 4).
419 NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES
420 ==============================================
422 In order to support both Win16 and Win32 APIs within the same source
423 code, the following convention must be used in naming all API
424 functions and types. If the Windows API uses the name 'xxx', the Wine
425 code must use:
427 - 'xxx16' for the Win16 version,
428 - 'xxx' for the Win32 version when no ASCII/Unicode strings are
429 involved,
430 - 'xxxA' for the Win32 version with ASCII strings,
431 - 'xxxW' for the Win32 version with Unicode strings.
433 If the function has both ASCII and Unicode version, you should then
434 use the macros WINELIB_NAME_AW(xxx) or DECL_WINELIB_TYPE_AW(xxx)
435 (defined in include/windef.h) to define the correct 'xxx' function
436 or type for Winelib. When compiling Wine itself, 'xxx' is _not_
437 defined, meaning that code inside of Wine must always specify
438 explicitly the ASCII or Unicode version.
440 If 'xxx' is the same in Win16 and Win32, you can simply use the same
441 name as Windows, i.e. just 'xxx'. If 'xxx' is Win16 only, you could
442 use the name as is, but it's preferable to use 'xxx16' to make it
443 clear it is a Win16 function.
445 Examples:
447 typedef struct { /* Win32 ASCII data structure */ } WNDCLASSA;
448 typedef struct { /* Win32 Unicode data structure */ } WNDCLASSW;
449 typedef struct { /* Win16 data structure */ } WNDCLASS16;
450 DECL_WINELIB_TYPE_AW(WNDCLASS);
452 ATOM RegisterClass16( WNDCLASS16 * );
453 ATOM RegisterClassA( WNDCLASSA * );
454 ATOM RegisterClassW( WNDCLASSW * );
455 #define RegisterClass WINELIB_NAME_AW(RegisterClass)
457 The Winelib user can then say:
459 WNDCLASS wc = { ... };
460 RegisterClass( &wc );
462 and this will use the correct declaration depending on the definition
463 of the UNICODE symbol.
466 NAMING CONVENTIONS FOR NON-API FUNCTIONS AND TYPES
467 ==================================================
469 Functions and data which are internal to your code (or at least shouldn't be
470 visible to any Winelib or Windows program) should be preceded by
471 an identifier to the module:
473 Examples:
475 ENUMPRINTERS_GetDWORDFromRegistryA() (in dlls/winspool/info.c)
476 IAVIFile_fnRelease() (in dlls/avifil32/avifile.c)
477 X11DRV_CreateDC() (in graphics/x11drv/init.c)
478 TIMER_Init() (implemented in windows/timer.c,
479 used in loader/main.c )
481 if you need prototypes for these, there are a few possibilities:
482 - within same source file only:
483 put the prototypes at the top of your file and mark them as prototypes.
484 - within the same module:
485 create a header file within the subdirectory where that module resides,
486 e.g. graphics/ddraw_private.h
487 - from a totally different module, or for use in winelib:
488 put your header file entry in /include/wine/
489 but be careful not to clutter this directory!
490 under no circumstances, you should add non-api calls to the standard
491 windoze include files. Unfortunately, this is often the case, e.g.
492 the above example of TIMER_Init is defined in include/message.h
495 API ENTRY POINTS
496 ================
498 Because Win16 programs use a 16-bit stack and because they can only
499 call 16:16 addressed functions, all API entry points must be at low
500 address offsets and must have the arguments translated and moved to
501 Wines 32-bit stack. This task is handled by the code in the "if1632"
502 directory. To define a new API entry point handler you must place a
503 new entry in the appropriate API specification file. These files are
504 named *.spec. For example, the API specification file for the USER
505 DLL is contained in the file user.spec. These entries are processed
506 by the "build" program to create an assembly file containing the entry
507 point code for each API call. The format of the *.spec files is
508 documented in the file "tools/build-spec.txt".
511 DEBUG MESSAGES
512 ==============
514 To display a message only during debugging, you normally write something
515 like this:
517 TRACE(win,"abc..."); or
518 FIXME(win,"abc..."); or
519 WARN(win,"abc..."); or
520 ERR(win,"abc...");
522 depending on the seriousness of the problem. (documentation/degug-msgs
523 explains when it is appropriate to use each of them)
525 These macros are defined in include/debug.h. The macro-definitions are
526 generated by the shell-script tools/make_debug. It scans the source
527 code for symbols of this forms and puts the necessary macro
528 definitions in include/debug.h and include/debugdefs.h. These macros
529 test whether the debugging "channel" associated with the first
530 argument of these macros (win in the above example) is enabled and
531 thus decide whether to actually display the text. In addition you can
532 change the types of displayed messages by supplying the "-debugmsg"
533 option to Wine. If your debugging code is more complex than just
534 printf, you can use the symbols TRACE_ON(xxx), WARN_ON(xxx),
535 ERR_ON(xxx) and FIXME_ON(xxx) as well. These are true when channel xxx
536 is enabled, either permanent or in the command line. Thus, you can
537 write:
539 if(TRACE_ON(win))DumpSomeStructure(&str);
541 Don't worry about the inefficiency of the test. If it is permanently
542 disabled (that is TRACE_ON(win) is 0 at compile time), the compiler will
543 eliminate the dead code.
545 You have to start tools/make_debug only if you introduced a new macro,
546 e.g. TRACE(win32).
548 For more info about debugging messages, read:
550 documentation/debug-msgs
553 MORE INFO
554 =========
556 1. There is a FREE online version of the MSDN library (including
557 documentation for the Win32 API) on http://www.microsoft.com/msdn/
559 2. http://www.sonic.net/~undoc/bookstore.html
561 3. In 1993 Dr. Dobbs Journal published a column called "Undocumented Corner".
563 4. You might want to check out BYTE from December 1983 as well :-)