| blob | 2e24e96e31a93cfc97f8ecd291382e63e0eb6cba |
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. Note that several of the libraries
12 listed here are "stubbed out", meaning they still need to be implemented.
14 DLLs (under dlls/):
15 -------------------
17 activeds/ - Active Directory Service Interface
18 advapi32/ - Crypto, systeminfo, security, eventlogging
19 advpack/ - Reads and verifies .INF files
20 amstream/ - MultiMedia Streams
21 atl/ - Active Template Library
22 avicap32/ - AVI capture window class
23 avifil32/ - COM object to play AVI files
24 cabinet/ - Cabinet file interface
25 capi2032/ - Wrapper library for CAPI4Linux access
26 cards/ - Card graphics
27 cfgmgr32/ - Config manager
28 comcat/ - Component category manager
29 comctl32/ - Common controls
30 commdlg/ - Common dialog boxes (both 16 & 32 bit)
31 crtdll/ - Old C runtime library
32 crypt32/ - Cryptography
33 cryptdll/ - Cryptography Manager
34 ctl3d32/ - 3D Effects for Common GUI Components
35 d3d8/ - Direct3D (3D graphics)
36 d3d9/ - Direct3D (3D graphics)
37 d3dim/ - Direct3D Immediate Mode
38 d3drm/ - Direct3D Retained Mode
39 d3dx8/ - Direct3D (3D graphics)
40 d3dxof/ - DirectX Files Functions
41 dbghelp/ - Engine for symbol and module enumeration
42 dciman32/ - DCI Manager (graphics)
43 ddraw/ - DirectDraw (graphics)
44 devenum/ - Device enumeration (part of DirectShow)
45 dinput/ - DirectInput (device input)
46 dinput8/ - DirectInput (device input)
47 dmband/ - DirectMusic Band
48 dmcompos/ - DirectMusic Composer
49 dmime/ - DirectMusic Interactive Engine
50 dmloader/ - DirectMusic Loader
51 dmscript/ - DirectMusic Scripting
52 dmstyle/ - DirectMusic Style Engine
53 dmsynth/ - DirectMusic Software Synthesizer
54 dmusic/ - DirectMusic Core Services
55 dmusic32/ - DirectMusic Legacy Port
56 dnsapi/ - DNS support
57 dplay/ - DirectPlay (networking)
58 dplayx/ - DirectPlay (networking)
59 dpnet/ - DirectPlay (networking)
60 dpnhpast/ - DirectPlay NAT Helper PAST
61 dsound/ - DirectSound (audio)
62 dswave/ - DirectMusic Wave
63 dxdiagn/ - DirectX Diagnostic Tool
64 gdi/ - GDI (graphics)
65 glu32/ - OpenGL Utility library (graphics)
66 glut32/ - OpenGL Utility Toolkit
67 gphoto2.ds/ - Contains libgphoto2 based TWAIN datasource driver
68 hhctrl.ocx/ - HHCTRL OCX implementation
69 iccvid/ - Radius Cinepak Video Decoder
70 icmp/ - ICMP protocol (networking)
71 ifsmgr.vxd/ - IFSMGR VxD implementation
72 imaadp32.acm/ - IMA ADPCM Audio Codec
73 imagehlp/ - PE (Portable Executable) Image Helper lib
74 imm32/ - Input Method Manager
75 iphlpapi/ - IP Helper API
76 itss/ - Infotech Structured Storage (HTML Help)
77 kernel/ - The Windows kernel
78 lz32/ - Lempel-Ziv compression/decompression
79 mapi32/ - Mail interface
80 mciavi32/ - MCI video driver
81 mcicda/ - MCI audio CD driver
82 mciseq/ - MCI MIDI driver
83 midimap/ - MIDI mapper
84 mlang/ - Multi Language Support
85 mmdevldr.vxd/ - MMDEVLDR VxD implementation
86 monodebg.vxd/ - MONODEBG VxD implementation
87 mpr/ - Multi-Protocol Router (networking)
88 msacm/ - Audio Compression Manager (multimedia)
89 msadp32.acm/ - MS ADPCM Audio Codec
90 mscms/ - Color Management System
91 msdmo/ - DirectX Media Objects
92 msftedit/ - Rich text editing control (Version 4.1)
93 msg711.acm/ - MS G711 Audio Codec (includes A-Law & MU-Law)
94 mshtml/ - MS HTML component
95 msi/ - Microsoft Installer
96 msimg32/ - Gradient and transparency (graphics)
97 msisys/ - System information
98 msnet32/ - Network interface
99 msrle32/ - Video codecs
100 msvcrt/ - C runtime library
101 msvcrt20/ - C runtime library version 2.0
102 msvcrt40/ - C runtime library version 4.0
103 msvcrtd/ - C runtime library debugging
104 msvfw32/ - 16 bit video manager
105 msvidc32/ - Microsoft Video-1 Decoder
106 mswsock/ - Misc networking
107 msxml3/ - MSXML Class Factory
108 netapi32/ - Network interface
109 newdev/ - New Hardware Device Library
110 ntdll/ - NT implementation of kernel calls
111 objsel/ - Object Picker Dialog
112 odbc32/ - Open DataBase Connectivity driver manager
113 odbccp32/ - Open DataBase Connectivity driver installer
114 ole32/ - 32 bit OLE 2.0 libraries
115 oleacc/ - OLE accessibility support
116 oleaut32/ - 32 bit OLE 2.0 automation
117 olecli32/ - 16 bit OLE client
118 oledlg/ - OLE 2.0 user interface support
119 olepro32/ - 32 bit OLE 2.0 automation
120 olesvr32/ - 16 bit OLE server
121 opengl32/ - OpenGL implementation (graphics)
122 powrprof/ - Power Management and Profiling
123 psapi/ - Process Status interface
124 qcap/ - DirectShow runtime
125 quartz/ - DirectShow runtime
126 rasapi32/ - Remote Access Server interface
127 riched20/ - Rich text editing control (Version 2.0 and 3.0)
128 richedit/ - Rich text editing control
129 rpcrt4/ - Remote Procedure Call runtime
130 rsabase/ - RSA encryption
131 rsaenh/ - Crypto API (DES, 3DES, RSA, etc.)
132 sane.ds/ - Contains sane based TWAIN datasource driver
133 secur32/ - Contains Windows Security functions
134 security/ - Security Support Provider Interface
135 sensapi/ - System Event Notification Service
136 serialui/ - Serial port property pages
137 setupapi/ - Setup interface
138 sfc/ - System File Checker (Windows File Protection)
139 shdocvw/ - Shell document object and control
140 shell32/ - COM object implementing shell views
141 shfolder/ - Shell folder service
142 shlwapi/ - Shell Light-Weight interface
143 snmpapi/ - SNMP protocol interface (networking)
144 spoolss/ - Spooler Subsystem Library ("spooler" - Service)
145 stdole2.tlb/ - OLE Automation typelib
146 stdole32.tlb/ - Standard OLE typelib
147 sti/ - Still Image service
148 tapi32/ - Telephone interface
149 twain_32/ - TWAIN Imaging device communications
150 unicows/ - Unicows replacement (Unicode layer for Win9x)
151 url/ - Internet shortcut shell extension
152 urlmon/ - URL Moniker allows binding to a URL
153 user/ - Window management, standard controls, etc.
154 usp10/ - Uniscribe Script Processor
155 uxtheme/ - Theme library
156 vdhcp.vxd/ - VDHCP VxD implementation
157 vdmdbg/ - Virtual DOS machine debug library
158 version/ - File installation library
159 vmm.vxd/ - VMM VxD implementation
160 vnbt.vxd/ - VNBT VxD implementation
161 vnetbios.vxd/ - VNETBIOS VxD implementation
162 vtdapi.vxd/ - VTDAPI VxD implementation
163 vwin32.vxd/ - VWIN32 VxD implementation
164 win32skrnl/ - 32-bit function access for 16-bit systems
165 wined3d/ - Wine internal Direct3D helper
166 winedos/ - DOS features and BIOS calls (Wine specific)
167 winemp3.acm/ - Mpeg Layer 3 Audio Codec
168 wineps/ - Postscript driver (Wine specific)
169 wininet/ - Internet extensions
170 winmm/ - Multimedia (16 & 32 bit)
171 winmm/joystick/ - Joystick driver
172 winmm/mciwave/ - MCI wave driver
173 winmm/wavemap/ - Audio mapper
174 winmm/winealsa/ - ALSA audio driver
175 winmm/winearts/ - aRts audio driver
176 winmm/wineaudioio/ - audioio audio driver
177 winmm/winejack/ - JACK audio server driver
178 winmm/winenas/ - NAS audio driver
179 winmm/wineoss/ - OSS audio driver
180 winnls32/ - National Language Support
181 winspool/ - Printing & Print Spooler
182 wintab32/ - Tablet device interface
183 wintrust/ - Trust verification interface
184 wldap32/ - LDAP support
185 wnaspi32/ - 16 bit Advanced SCSI Peripheral Interface
186 wow32/ - WOW subsystem
187 ws2_32/ - Sockets 2.0 (networking)
188 wsock32/ - Sockets 1.1 (networking)
189 wtsapi32/ - Terminal Services
190 x11drv/ - X11 display driver (Wine specific)
192 Winelib programs (under programs/):
193 -----------------------------------
195 avitools/ - AVI information viewer and player
196 clock/ - Graphical clock
197 cmdlgtst/ - Common dialog tests
198 control/ - Control panel
199 expand/ - Decompress Lempel-Ziv compressed archive
200 msiexec/ - Microsoft Installer frontend
201 notepad/ - Notepad replacement
202 progman/ - Program manager
203 regedit/ - Registry editor
204 regsvr32/ - Register COM server
205 rpcss/ - RPC services
206 rundll32/ - Execute DLL functions directly
207 start/ - Replacement for start.exe
208 taskmgr/ - Manage running Windows/Winelib applications
209 uninstaller/ - Remove installed programs
210 view/ - Metafile viewer
211 wcmd/ - Command line interface
212 wineboot/ - Wine bootstrap process
213 winecfg/ - Wine configuration utility
214 wineconsole/ - Console
215 winedbg/ - Debugger
216 winefile/ - File manager
217 winemenubuilder/ - Helper program for building Unix menu entries
218 winemine/ - Mine game
219 winepath/ - Translate between Wine and Unix paths
220 winetest/ - Wine testing shell
221 winevdm/ - Wine virtual DOS machine
222 winhelp/ - Help viewer
223 winver/ - Windows Version Program
226 Support programs, libraries, etc:
227 ---------------------------------
229 dlls/dxerr8/ - DirectX 8 error import lib
230 dlls/dxerr9/ - DirectX 9 error import lib
231 dlls/dxguid/ - DirectX UUID import lib
232 dlls/strmiids/ - Exports class CLSIDs and interface IIDs
233 dlls/uuid/ - Windows-compatible UUID import lib
234 documentation/ - some documentation
235 include/ - Windows standard includes
236 include/msvcrt/ - MSVC compatible libc headers
237 include/wine/ - Wine specific headers
238 libs/ - the Wine libraries
239 libs/port/ - portability library
240 libs/unicode/ - Unicode support shared
241 libs/wine/ - Wine bootstrap library
242 libs/wpp/ - C preprocessor
243 loader/ - the main Wine loader
244 server/ - the Wine server
245 tools/ - various tools used to build/check Wine
246 tools/widl/ - the IDL compiler
247 tools/winapi/ - A Win32 API checker
248 tools/winebuild/ - Wine build tool
249 tools/winedump/ - a .DLL dump utility
250 tools/winegcc/ - a MinGW command line compatible gcc wrapper
251 tools/wmc/ - the message compiler
252 tools/wpp/ - the C pre-processor library
253 tools/wrc/ - the resource compiler
257 IMPLEMENTING NEW API CALLS
258 ==========================
260 This is the simple version, and covers only Win32. Win16 is slightly
261 uglier, because of the Pascal heritage and the segmented memory model.
263 All of the Win32 APIs known to Wine are listed in the .spec file of
264 their corresponding dll. An unimplemented call will look like (from
265 gdi32.spec)
266 269 stub PolyBezierTo
267 To implement this call, you need to do the following four things.
269 1. Find the appropriate parameters for the call, and add a prototype to
270 the correct header file. In this case, that means [include/wingdi.h],
271 and it might look like
272 BOOL WINAPI PolyBezierTo(HDC, LPCVOID, DWORD);
273 If the function has both an ASCII and a Unicode version, you need to
274 define both and add a #define WINELIB_NAME_AW declaration. See below
275 for discussion of function naming conventions.
277 2. Modify the .spec file to tell Wine that the function has an
278 implementation, what the parameters look like and what Wine function
279 to use for the implementation. In Win32, things are simple--everything
280 is 32-bits. However, the relay code handles pointers and pointers to
281 strings slightly differently, so you should use 'str' and 'wstr' for
282 strings, 'ptr' for other pointer types, and 'long' for everything else.
283 269 stdcall PolyBezierTo(long ptr long) PolyBezierTo
284 The 'PolyBezierTo' at the end of the line is which Wine function to use
285 for the implementation.
287 3. Implement the function as a stub. Once you add the function to the .spec
288 file, you must add the function to the Wine source before it will link.
289 Add a function called 'PolyBezierTo' somewhere. Good things to put
290 into a stub:
291 o a correct prototype, including the WINAPI
292 o header comments, including full documentation for the function and
293 arguments (see documentation/README.documentation)
294 o A FIXME message and an appropriate return value are good things to
295 put in a stub.
297 /************************************************************
298 * PolyBezierTo (GDI32.269)
299 *
300 * Draw many Bezier curves.
301 *
302 * PARAMS
303 * hdc [I] Device context to draw to
304 * p [I] Array of POINT structs
305 * count [I] Number of points in p
306 *
307 * RETURNS
308 * Success: Non-zero.
309 * Failure: FALSE. Use GetLastError() to find the error cause.
310 *
311 * BUGS
312 * Unimplemented
313 */
314 BOOL WINAPI PolyBezierTo(HDC hdc, LPCVOID p, DWORD count)
315 {
316 /* tell the user they've got a substandard implementation */
317 FIXME("(%x,%p,%d): stub\n", hdc, p, count);
319 /* some programs may be able to compensate,
320 * if they know what happened
321 */
322 SetLastError(ERROR_CALL_NOT_IMPLEMENTED);
323 return FALSE; /* error value */
324 }
326 4. Implement and test the rest of the function.
329 IMPLEMENTING A NEW DLL
330 ======================
332 Generic directions
333 ------------------
335 Apart from writing the set of needed .c files, you also need to do the
336 following:
338 1. Create a directory <MyDll> where to store the implementation of
339 the DLL. This directory has to be put under the dlls/ directory.
340 If the DLL exists under Windows as both 16 and 32 bit DLL, you
341 should have a single directory with both implementations.
343 2. Create the Makefile.in in the ./dlls/<MyDll>/ directory. You can
344 copy an existing Makefile.in from another ./dlls/ subdirectory.
345 You need at least to change the MODULE and C_SRCS macros.
347 3. Add the directory in ./configure.ac (in AC_OUTPUT macro at the end
348 of the file to trigger the Makefile generation)
350 4. Run ./make_dlls in the dlls directory to update Makefile.in in
351 that directory.
353 5. You can now regenerate ./configure file (with 'autoconf')
354 and the various Makefiles (with 'configure; make depend') (run
355 from the top of Wine's tree).
356 You should now have a Makefile file in ./dlls/<MyDll>/
358 6. Create the .spec file for the DLL exported functions in your
359 directory. Refer to 'Implementation of new API calls' earlier in
360 this document for more information on this part.
362 7. You can now start adding .c files. For the .h files, if they are
363 standard Windows one, put them in include/. If they are linked to
364 *your* implementation of the dll, put them in your newly created
365 directory.
367 Debug channels
368 --------------
370 If you need to create a new debug channel, just add the
371 WINE_DEFAULT_DEBUG_CHANNEL to your .c file(s), and use them.
372 All the housekeeping will happen automatically.
374 Resources
375 ---------
377 If you also need to add resources to your DLL, then create the .rc
378 file. Add to your ./dlls/<MyDll>/Makefile.in, in the RC_SRCS macro,
379 the list of .rc files to add to the DLL. See dlls/comctl32/ for an
380 example of this.
382 Thunking
383 --------
385 If you're building a 16 & 32 bit DLLs pair, then from the 32 bit code
386 you might need to call 16 bit routine. The way to do it to add in the
387 code, fragments like:
388 /* ### Start build ### */
389 extern WORD CALLBACK <PREFIX>_CallTo16_word_wwlll(FARPROC16,WORD,WORD,LONG,LONG,LONG);
390 /* ### stop build ### */
391 Where <PREFIX>_ is an internal prefix for your module. The first
392 parameter is always of type FARPROC16. Then, you can get the regular
393 list of parameters. The _word_wwlll indicates the type of return (long
394 or word) and the size of the parameters (here l=>long, w=>word; which
395 maps to WORD,WORD,LONG,LONG,LONG.
396 You can put several functions between the Start/Stop build pair.
398 You can also read the winebuild manpage for more details on this.
400 Then, add to ./dlls/<MyDll>/Makefile.in a line like:
402 EXTRA_OBJS = $(MODULE).glue.o
404 See dlls/winmm/ for an example of this.
406 MEMORY AND SEGMENTS
407 ===================
409 NE (Win16) executables consist of multiple segments. The Wine loader
410 loads each segment into a unique location in the Wine processes memory
411 and assigns a selector to that segment. Because of this, it's not
412 possible to exchange addresses freely between 16-bit and 32-bit code.
413 Addresses used by 16-bit code are segmented addresses (16:16), formed
414 by a 16-bit selector and a 16-bit offset. Those used by the Wine code
415 are regular 32-bit linear addresses.
417 There are four ways to obtain a segmented pointer:
418 - Using the MapLS function (recommended).
419 - Allocate a block of memory from the global heap and use
420 WIN16_GlobalLock to get its segmented address.
421 - Declare the argument as 'segptr' instead of 'ptr' in the spec file
422 for a given API function.
424 Once you have a segmented pointer, it must be converted to a linear
425 pointer before you can use it from 32-bit code. This can be done with
426 the MapSL function. The linear pointer can then be used freely with
427 standard Unix functions like memcpy() etc. without worrying about 64k
428 boundaries. Note: there's no easy way to convert back from a linear
429 to a segmented address.
431 In most cases, you don't need to worry about segmented address, as the
432 conversion is made automatically by the callback code and the API
433 functions only see linear addresses. However, in some cases it is
434 necessary to manipulate segmented addresses; the most frequent cases
435 are:
436 - API functions that return a pointer
437 - lParam of Windows messages that point to a structure
438 - Pointers contained inside structures accessed by 16-bit code.
440 It is usually a good practice to used the type 'SEGPTR' for segmented
441 pointers, instead of something like 'LPSTR' or 'char *'. As SEGPTR is
442 defined as a DWORD, you'll get a compilation warning if you mistakenly
443 use it as a regular 32-bit pointer.
446 STRUCTURE PACKING
447 =================
449 Under Windows, data structures are tightly packed, i.e. there is no
450 padding between structure members. On the other hand, by default gcc
451 aligns structure members (e.g. WORDs are on a WORD boundary, etc.).
452 This means that a structure like
454 struct { BYTE x; WORD y; };
456 will take 3 bytes under Windows, but 4 with gcc, because gcc will add a
457 dummy byte between x and y. To have the correct layout for structures
458 used by Windows code, you need to embed the struct within two special
459 #include's which will take care of the packing for you:
461 #include "pshpack1.h"
462 struct { BYTE x; WORD y; };
463 #include "poppack1.h"
465 For alignment on a 2-byte boundary, there is a "pshpack2.h", etc.
468 NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES
469 ==============================================
471 In order to support both Win16 and Win32 APIs within the same source
472 code, the following convention must be used in naming all API
473 functions and types. If the Windows API uses the name 'xxx', the Wine
474 code must use:
476 - 'xxx16' for the Win16 version,
477 - 'xxx' for the Win32 version when no strings are involved,
478 - 'xxxA' for the Win32 version with ASCII strings,
479 - 'xxxW' for the Win32 version with Unicode strings.
481 If the function has both ASCII and Unicode version, you should then
482 use the macros WINELIB_NAME_AW(xxx) or DECL_WINELIB_TYPE_AW(xxx)
483 (defined in include/windef.h) to define the correct 'xxx' function
484 or type for Winelib. When compiling Wine itself, 'xxx' is _not_
485 defined, meaning that code inside of Wine must always specify
486 explicitly the ASCII or Unicode version.
488 If 'xxx' is the same in Win16 and Win32, you can simply use the same
489 name as Windows, i.e. just 'xxx'. If 'xxx' is Win16 only, you could
490 use the name as is, but it's preferable to use 'xxx16' to make it
491 clear it is a Win16 function.
493 Examples:
495 typedef struct { /* Win32 ASCII data structure */ } WNDCLASSA;
496 typedef struct { /* Win32 Unicode data structure */ } WNDCLASSW;
497 typedef struct { /* Win16 data structure */ } WNDCLASS16;
498 DECL_WINELIB_TYPE_AW(WNDCLASS);
500 ATOM RegisterClass16( WNDCLASS16 * );
501 ATOM RegisterClassA( WNDCLASSA * );
502 ATOM RegisterClassW( WNDCLASSW * );
503 #define RegisterClass WINELIB_NAME_AW(RegisterClass)
505 The Winelib user can then say:
507 WNDCLASS wc = { ... };
508 RegisterClass( &wc );
510 and this will use the correct declaration depending on the definition
511 of the UNICODE symbol.
514 DEBUG MESSAGES
515 ==============
517 To display a message only during debugging, you normally write something
518 like this:
520 TRACE("abc..."); or
521 FIXME("abc..."); or
522 WARN("abc..."); or
523 ERR("abc...");
525 depending on the seriousness of the problem. (documentation/debugging.sgml
526 explains when it is appropriate to use each of them). You need to declare
527 the debug channel name at the top of the file (after the includes) using
528 the WINE_DEFAULT_DEBUG_CHANNEL macro, like so:
530 WINE_DEFAULT_DEBUG_CHANNEL(win);
532 If your debugging code is more complex than just printf, you can use
533 the macros:
535 TRACE_ON(xxx), WARN_ON(xxx), ERR_ON(xxx) and FIXME_ON(xxx)
537 to test if the given channel is enabled. Thus, you can 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 For more info about debugging messages, read:
547 http://www.winehq.org/site/docs/wine-devel/debugging
550 MORE INFO
551 =========
553 1. There is a FREE online version of the MSDN library (including
554 documentation for the Win32 API) on http://msdn.microsoft.com/
555 or http://www.msdn.com/
557 2. Windows apilist: http://www.mentalis.org/apilist/apilist.php
559 3. http://www.sonic.net/~undoc/bookstore.html
561 4. In 1993 Dr. Dobbs Journal published a column called "Undocumented Corner".
563 5. www.geocities.com/SiliconValley/4942/