Authors: Chris Morgan <cmorgan@wpi.edu>, James Abbatiello <abbeyj@wpi.edu>
[wine/multimedia.git] / DEVELOPERS-HINTS
blob937c30651b9e0412ccd024149fa0606873e998b7
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.
139   
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 Generic directions
193 ------------------
195 Apart from writing the set of needed .c files, you also need to do the 
196 following:
198 1.  Create a directory <MyDll> where to store the implementation of
199     the DLL. 
201     If the DLL exists under Windows as both 16 and 32 bit DLL, you can
202     either create one directory for each, or have a single directory
203     with both implementations. 
205     This (those) directory(ies) have to be put under the dlls/
206     directory in Wine tree structure.
208 2.  Create the Makefile.in in the ./dlls/<MyDll>/ directory. You can
209     copy an existing Makefile.in from another ./dlls/ subdirectory.
211     You need at least to change the MODULE, SPEC_SRCS, and C_SRCS
212     macros. 
214 3.  Add the directory (and the generated .o file for the module) in: 
215     + ./configure.in (in AC_OUTPUT macro at the end of the file to
216       trigger the Makefile generation),
217     + ./Makefile.in (in LIBSUBDIRS and LIBOBJS macros)
218     + ./dlls/Makefile.in (in SUBDIRS macro)
220 4.  You can now regenerate ./configure file (with 'make configure')
221     and the various Makefiles (with 'configure; make depend') (run
222     from the top of Wine's tree).
224     You shall now have a Makefile file in ./dlls/<MyDll>/
226 5.  You now need to declare the DLL in the module lists. This is done
227     by adding the corresponding descriptor in ./if1632/builtin.c if
228     your DLL is 16 bit (resp. ./relay32/builtin.c for a 32 bit DLL)
229     (or both if your directory contains the dual 16/32
230     implementations). 
232     Note: the name of the descriptor is based on the module name, not
233     on the file name (they are the same in most of the case, but for
234     some DLLs it's not the case).
236 6.  You also need to define the loadorder for the created DLL
237     (./wine.ini and ./loader/loadorder.c). Usually, "native,builtin"
238     is ok. If you have written a paired 16/32 bit implementation, don't
239     forget to define it also in those files. 
241 7.  Create the .spec file for the DLL export points in your
242     directory. Refer to 'Implementation of new API calls' earlier in
243     this document for more information on this part.
245 8.  Don't forget the .cvsignore file. The .cvsignore contain (on a per
246     directory basis) all the files generated by the compilation
247     process, why cvs shall ignore when processing the dir. 
248     *.o is in there by default, but in Wine case you will find:
249     - Makefile (generated from Makefile.in)
250     - *.spec.c: those c files are generated by tools/build from the
251       .spec file
252     - when thunking down to 16 bit DLLs, you'll get some others (.glue.c)
253     - result of .y => .c translation (by yacc or bison)
254     - result of .rc compilation
255     - ...
256     For a simple DLL, listing in .cvsignore Makefile and
257     <MyDll>.spec.c will do. 
259 9.  You can now start adding .c files.
261 10. For the .h files, if they are standard Windows one, put them in
262     include/. If they are linked to *your* implementation of the DLL,
263     put them in your newly created directory.
265 Debug channels
266 --------------
268 If you need to create a new debug channel, just add the
269 DECLARE_DEBUG_CHANNEL to your .c file(s) and rerun
270 tools/make_debug. When sending out your patch, you don't need to
271 provide nor ./configure nor the ./include/debugdefs.h diffs. Just
272 indicate that those files need to be regenerated.
274 Resources
275 ---------
277 If you also need to add resources to your DLL, the create the .rc
278 file. Since, the .rc file will be translated into a .s file, and then
279 compiled as a .o file, its basename must be different from the
280 basename of any .c file.
281 Add to your ./dlls/<MyDll>/Makefile.in, in the RC_SRCS macro, the list 
282 of .rc files to add to the DLL. You may also have to add the following
283 directives
284 1/ to tell gnumake to translate .rc into .s files,
285         $(RC_SRCS:.rc=.s): $(WRC)
286 2/ to give some parameters to wrc for helping the translation.
287         WRCEXTRA  = -s -p$(MODULE)
289 See dlls/comctl32/ for an example of this.
291 Thunking
292 --------
294 If you're building a 16 & 32 bit DLLs pair, then from the 32 bit code
295 you might need to call 16 bit routine. The way to do it to add in the
296 code, fragments like:
297 /* ### Start build ### */
298 extern WORD CALLBACK <PREFIX>_CallTo16_word_wwlll(FARPROC16,WORD,WORD,LONG,LONG,LONG);
299 /* ### stop build ### */
300 Where <PREFIX>_ is an internal prefix for your module. The first
301 parameter is always of type FARPROC16. Then, you can get the regular
302 list of parameters. The _word_wwlll indicates the type of return (long
303 or word) and the size of the parameters (here l=>long, w=>word; which
304 maps to WORD,WORD,LONG,LONG,LONG.
305 You can put several functions between the Start/Stop build pair.
307 You can also read tools/build.txt for more details on this.
309 Then, add to ./dlls/<MyDll>/Makefile.in to the macro GLUE the list of
310 .c files containing the /* ### Start build ### */ directives.
312 See dlls/winmm/ for an example of this.
314 MEMORY AND SEGMENTS
315 ===================
317 NE (Win16) executables consist of multiple segments.  The Wine loader
318 loads each segment into a unique location in the Wine processes memory
319 and assigns a selector to that segment.  Because of this, it's not
320 possible to exchange addresses freely between 16-bit and 32-bit code.
321 Addresses used by 16-bit code are segmented addresses (16:16), formed
322 by a 16-bit selector and a 16-bit offset.  Those used by the Wine code
323 are regular 32-bit linear addresses.
325 There are four ways to obtain a segmented pointer:
326   - Use the SEGPTR_* macros in include/heap.h (recommended).
327   - Allocate a block of memory from the global heap and use
328     WIN16_GlobalLock to get its segmented address.
329   - Allocate a block of memory from a local heap, and build the
330     segmented address from the local heap selector (see the
331     USER_HEAP_* macros for an example of this).
332   - Declare the argument as 'segptr' instead of 'ptr' in the spec file
333     for a given API function.
335 Once you have a segmented pointer, it must be converted to a linear
336 pointer before you can use it from 32-bit code.  This can be done with
337 the PTR_SEG_TO_LIN() and PTR_SEG_OFF_TO_LIN() macros.  The linear
338 pointer can then be used freely with standard Unix functions like
339 memcpy() etc. without worrying about 64k boundaries.  Note: there's no
340 easy way to convert back from a linear to a segmented address.
342 In most cases, you don't need to worry about segmented address, as the
343 conversion is made automatically by the callback code and the API
344 functions only see linear addresses. However, in some cases it is
345 necessary to manipulate segmented addresses; the most frequent cases
346 are:
347   - API functions that return a pointer
348   - lParam of Windows messages that point to a structure
349   - Pointers contained inside structures accessed by 16-bit code.
351 It is usually a good practice to used the type 'SEGPTR' for segmented
352 pointers, instead of something like 'LPSTR' or 'char *'.  As SEGPTR is
353 defined as a DWORD, you'll get a compilation warning if you mistakenly
354 use it as a regular 32-bit pointer.
357 STRUCTURE PACKING
358 =================
360 Under Windows, data structures are tightly packed, i.e. there is no
361 padding between structure members. On the other hand, by default gcc
362 aligns structure members (e.g. WORDs are on a WORD boundary, etc.).
363 This means that a structure like
365 struct { BYTE x; WORD y; };
367 will take 3 bytes under Windows, but 4 with gcc, because gcc will add a
368 dummy byte between x and y. To have the correct layout for structures
369 used by Windows code, you need to embed the struct within two special
370 #include's which will take care of the packing for you:
372 #include "pshpack1.h"
373 struct { BYTE x; WORD y; };
374 #include "poppack1.h"
376 For alignment on a 2-byte boundary, there is a "pshpack2.h", etc.
378 The use of the WINE_PACKED attribute is obsolete. Please remove these 
379 in favour of the above solution. 
380 Using WINE_PACKED, you would declare the above structure like this:
382 struct { BYTE x; WORD y WINE_PACKED; };
384 You had to do this every time a structure member is not aligned
385 correctly under Windows (i.e. a WORD not on an even address, or a
386 DWORD on a address that was not a multiple of 4).
389 NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES
390 ==============================================
392 In order to support both Win16 and Win32 APIs within the same source
393 code, the following convention must be used in naming all API
394 functions and types. If the Windows API uses the name 'xxx', the Wine
395 code must use:
397  - 'xxx16' for the Win16 version,
398  - 'xxx'   for the Win32 version when no ASCII/Unicode strings are
399    involved,
400  - 'xxxA'  for the Win32 version with ASCII strings,
401  - 'xxxW'  for the Win32 version with Unicode strings.
403 If the function has both ASCII and Unicode version, you should then
404 use the macros WINELIB_NAME_AW(xxx) or DECL_WINELIB_TYPE_AW(xxx)
405 (defined in include/windef.h) to define the correct 'xxx' function
406 or type for Winelib. When compiling Wine itself, 'xxx' is _not_
407 defined, meaning that code inside of Wine must always specify
408 explicitly the ASCII or Unicode version.
410 If 'xxx' is the same in Win16 and Win32, you can simply use the same
411 name as Windows, i.e. just 'xxx'.  If 'xxx' is Win16 only, you could
412 use the name as is, but it's preferable to use 'xxx16' to make it
413 clear it is a Win16 function.
415 Examples:
417 typedef struct { /* Win32 ASCII data structure */ } WNDCLASSA;
418 typedef struct { /* Win32 Unicode data structure */ } WNDCLASSW;
419 typedef struct { /* Win16 data structure */ } WNDCLASS16;
420 DECL_WINELIB_TYPE_AW(WNDCLASS);
422 ATOM RegisterClass16( WNDCLASS16 * );
423 ATOM RegisterClassA( WNDCLASSA * );
424 ATOM RegisterClassW( WNDCLASSW * );
425 #define RegisterClass WINELIB_NAME_AW(RegisterClass)
427 The Winelib user can then say:
429     WNDCLASS wc = { ... };
430     RegisterClass( &wc );
432 and this will use the correct declaration depending on the definition
433 of the UNICODE symbol.
436 NAMING CONVENTIONS FOR NON-API FUNCTIONS AND TYPES
437 ==================================================
439 Functions and data which are internal to your code (or at least shouldn't be
440 visible to any WineLib or Windows program) should be preceded by
441 an identifier to the module:
443 Examples:
445 ENUMPRINTERS_GetDWORDFromRegistryA()    (in dlls/winspool/info.c)
446 IAVIFile_fnRelease()                    (in dlls/avifil32/avifile.c)
447 X11DRV_CreateDC()                       (in graphics/x11drv/init.c)
448 TIMER_Init()                            (implemented in windows/timer.c,
449                                          used in loader/main.c )
451 if you need prototypes for these, there are a few possibilities:
452 - within same source file only:
453   put the prototypes at the top of your file and mark them as prototypes.
454 - within the same module:
455   create a header file within the subdirectory where that module resides,
456   e.g.  graphics/ddraw_private.h
457 - from a totally different module, or for use in winelib:
458   put your header file entry in /include/wine/
459   but be careful not to clutter this directory!
460 under no circumstances, you should add non-api calls to the standard
461 windoze include files. Unfortunately, this is often the case, e.g.
462 the above example of TIMER_Init is defined in include/message.h
465 API ENTRY POINTS
466 ================
468 Because Win16 programs use a 16-bit stack and because they can only
469 call 16:16 addressed functions, all API entry points must be at low
470 address offsets and must have the arguments translated and moved to
471 Wines 32-bit stack.  This task is handled by the code in the "if1632"
472 directory.  To define a new API entry point handler you must place a
473 new entry in the appropriate API specification file.  These files are
474 named *.spec.  For example, the API specification file for the USER
475 DLL is contained in the file user.spec.  These entries are processed
476 by the "build" program to create an assembly file containing the entry
477 point code for each API call.  The format of the *.spec files is
478 documented in the file "tools/build-spec.txt".
481 DEBUG MESSAGES
482 ==============
484 To display a message only during debugging, you normally write something
485 like this:
487         TRACE(win,"abc...");  or
488         FIXME(win,"abc...");  or
489         WARN(win,"abc...");   or
490         ERR(win,"abc...");
492 depending on the seriousness of the problem. (documentation/degug-msgs
493 explains when it is appropriate to use each of them)
495 These macros are defined in include/debug.h. The macro-definitions are
496 generated by the shell-script tools/make_debug. It scans the source
497 code for symbols of this forms and puts the necessary macro
498 definitions in include/debug.h and include/debugdefs.h. These macros
499 test whether the debugging "channel" associated with the first
500 argument of these macros (win in the above example) is enabled and
501 thus decide whether to actually display the text.  In addition you can
502 change the types of displayed messages by supplying the "-debugmsg"
503 option to Wine.  If your debugging code is more complex than just
504 printf, you can use the symbols TRACE_ON(xxx), WARN_ON(xxx),
505 ERR_ON(xxx) and FIXME_ON(xxx) as well. These are true when channel xxx
506 is enabled, either permanent or in the command line. Thus, you can
507 write:
509         if(TRACE_ON(win))DumpSomeStructure(&str);
511 Don't worry about the inefficiency of the test. If it is permanently 
512 disabled (that is TRACE_ON(win) is 0 at compile time), the compiler will 
513 eliminate the dead code.
515 You have to start tools/make_debug only if you introduced a new macro,
516 e.g.  TRACE(win32).
518 For more info about debugging messages, read:
520 documentation/debug-msgs
523 MORE INFO
524 =========
526 1. There is a FREE online version of the MSDN library (including
527    documentation for the Win32 API) on http://www.microsoft.com/msdn/
529 2. http://www.sonic.net/~undoc/bookstore.html
531 3. In 1993 Dr. Dobbs Journal published a column called "Undocumented Corner".
533 4. You might want to check out BYTE from December 1983 as well :-)