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