Fixed an error and an off-by-one bug in DSA_SetItem(). This
[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.
12
13 Wine API directories:
14 ---------------------
15
16 KERNEL:
17
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
23
24 GDI:
25
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 drivr
32                 enhmetafiledrv/ - enhanced metafile driver
33         objects/                - logical objects
34
35 USER:
36
37         controls/               - built-in widgets
38         resources/              - built-in menu and message box resources
39         windows/                - window management
40
41 Other DLLs:
42
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                 imagehlp/       - PE (Portable Executable) Image Helper lib
49                 msacm/          - audio compression manager (multimedia)
50                 msacm32/        - audio compression manager (multimedia)
51                 ntdll/          - NT implementation of kernel calls
52                 psapi/          - process status API
53                 rasapi32/       - remote access server API
54                 shell32/        - COM object implementing shell views
55                 tapi32/         - telephone API
56                 ver/            - File Installation Library (16 bit)
57                 version/        - File Installation Library (32 bit)
58                 winaspi/        - 
59                 winspool/       - Printing & Print Spooler 
60                 wnaspi32/       - 
61
62 Miscellaneous:
63
64         misc/                   - shell, registry, winsock, etc.
65         multimedia/             - multimedia driver
66         ipc/                    - SysV IPC based interprocess communication
67         win32/                  - misc Win32 functions
68         ole/                    - OLE code 
69                 nls/            - National Language Support 
70                                   configuration files
71
72 Tools:
73 ------
74
75         rc/                     - old resource compiler
76         tools/                  - relay code builder, new rc, bugreport
77                                   generator, wineconfigurator, etc.
78         documentation/          - some documentation
79
80
81 Binary loader specific directories:
82 -----------------------------------
83
84         debugger/               - built-in debugger
85         if1632/                 - relay code
86         miscemu/                - hardware instruction emulation
87         graphics/win16drv/      - Win16 printer driver
88         server/                 - the main, controlling thread of wine
89         tsx11/                  - thread-safe X11 wrappers (auto generated)
90
91 Winelib specific directories:
92 -----------------------------
93
94         library/                - Required code for programs using Winelib
95         libtest/                - Small samples and tests
96         programs/               - Extended samples / system utilities
97
98
99 IMPLEMENTING NEW API CALLS
100 ==========================
101
102 This is the simple version, and covers only Win32. Win16 is slightly uglier,
103 because of the Pascal heritage and the segmented memory model.
104
105 All of the Win32 APIs known to Wine are listed in [relay32/*.spec]. An
106 unimplemented call will look like (from gdi32.spec)
107   269 stub PolyBezierTo
108 To implement this call, you need to do the following four things.
109
110 1. Find the appropriate parameters for the call, and add a prototype to
111 the correct header file. In this case, that means [include/wingdi.h],
112 and it might look like
113   BOOL WINAPI PolyBezierTo(HDC, LPCVOID, DWORD);
114 If the function has both an ASCII and a Unicode version, you need to
115 define both and add a #define WINELIB_NAME_AW declaration. See below
116 for discussion of function naming conventions.
117   
118 2. Modify the .spec file to tell Wine that the function has an
119 implementation, what the parameters look like and what Wine function
120 to use for the implementation. In Win32, things are simple--everything
121 is 32-bits. However, the relay code handles pointers and pointers to
122 strings slightly differently, so you should use 'str' and 'wstr' for
123 strings, 'ptr' for other pointer types, and 'long' for everything else.
124   269 stdcall PolyBezierTo(long ptr long) PolyBezierTo
125 The 'PolyBezierTo' at the end of the line is which Wine function to use
126 for the implementation.
127
128 3. Implement the function as a stub. Once you add the function to the .spec
129 file, you must add the function to the Wine source before it will link.
130 Add a function called 'PolyBezierTo' somewhere. Good things to put
131 into a stub:
132   o a correct prototype, including the WINAPI
133   o header comments, including full documentation for the function and
134     arguments (see documentation/README.documentation)
135   o A FIXME message and an appropriate return value are good things to
136     put in a stub.
137
138   /************************************************************
139    *                    PolyBezierTo   (GDI32.269)  
140    *  
141    * Draw many Bezier curves
142    *
143    * RETURNS
144    *   nonzero on success or zero on faillure
145    *
146    * BUGS
147    *   Unimplemented
148    */
149    BOOL WINAPI PolyBezierTo(HDC hdc,     /* handle to device context */
150                             LPCVOID p,   /* ptr to array of Point structs */
151                             DWORD count  /* nr of points in array */
152    ) 
153    {
154       /* tell the user they've got a substandard implementation */
155       FIXME(gdi, ":(%x,%p,%d): stub\n", hdc, p, count);
156
157       /* some programs may be able to compensate, 
158        * if they know what happened 
159        */
160       SetLastError(ERROR_CALL_NOT_IMPLEMENTED);  
161       return FALSE;    /* error value */
162    }
163
164 4. Implement and test the rest of the function.
165
166
167 MEMORY AND SEGMENTS
168 ===================
169
170 NE (Win16) executables consist of multiple segments.  The Wine loader
171 loads each segment into a unique location in the Wine processes memory
172 and assigns a selector to that segment.  Because of this, it's not
173 possible to exchange addresses freely between 16-bit and 32-bit code.
174 Addresses used by 16-bit code are segmented addresses (16:16), formed
175 by a 16-bit selector and a 16-bit offset.  Those used by the Wine code
176 are regular 32-bit linear addresses.
177
178 There are four ways to obtain a segmented pointer:
179   - Use the SEGPTR_* macros in include/heap.h (recommended).
180   - Allocate a block of memory from the global heap and use
181     WIN16_GlobalLock to get its segmented address.
182   - Allocate a block of memory from a local heap, and build the
183     segmented address from the local heap selector (see the
184     USER_HEAP_* macros for an example of this).
185   - Declare the argument as 'segptr' instead of 'ptr' in the spec file
186     for a given API function.
187
188 Once you have a segmented pointer, it must be converted to a linear
189 pointer before you can use it from 32-bit code.  This can be done with
190 the PTR_SEG_TO_LIN() and PTR_SEG_OFF_TO_LIN() macros.  The linear
191 pointer can then be used freely with standard Unix functions like
192 memcpy() etc. without worrying about 64k boundaries.  Note: there's no
193 easy way to convert back from a linear to a segmented address.
194
195 In most cases, you don't need to worry about segmented address, as the
196 conversion is made automatically by the callback code and the API
197 functions only see linear addresses. However, in some cases it is
198 necessary to manipulate segmented addresses; the most frequent cases
199 are:
200   - API functions that return a pointer
201   - lParam of Windows messages that point to a structure
202   - Pointers contained inside structures accessed by 16-bit code.
203
204 It is usually a good practice to used the type 'SEGPTR' for segmented
205 pointers, instead of something like 'LPSTR' or 'char *'.  As SEGPTR is
206 defined as a DWORD, you'll get a compilation warning if you mistakenly
207 use it as a regular 32-bit pointer.
208
209
210 STRUCTURE PACKING
211 =================
212
213 Under Windows, data structures are tightly packed, i.e. there is no
214 padding between structure members. On the other hand, by default gcc
215 aligns structure members (e.g. WORDs are on a WORD boundary, etc.).
216 This means that a structure like
217
218 struct { BYTE x; WORD y; };
219
220 will take 3 bytes under Windows, but 4 with gcc, because gcc will add a
221 dummy byte between x and y. To have the correct layout for structures
222 used by Windows code, you need to embed the struct within two special
223 #include's which will take care of the packing for you:
224
225 #include "pshpack1.h"
226 struct {BYTE x; WORD y; };
227 #include "poppack1.h"
228
229 For alignment on a 2-byte boundary, there is a "pshpack2.h", etc.
230
231 The use of the WINE_PACKED attribute is obsolete. Please remove these 
232 in favour of the above solution. 
233 Using WINE_PACKED, you would declare the above structure like this:
234
235 struct { BYTE x; WORD y WINE_PACKED; };
236
237 You had to do this every time a structure member is not aligned
238 correctly under Windows (i.e. a WORD not on an even address, or a
239 DWORD on a address that was not a multiple of 4).
240
241
242 NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES
243 ==============================================
244
245 In order to support both Win16 and Win32 APIs within the same source
246 code, the following convention must be used in naming all API
247 functions and types. If the Windows API uses the name 'xxx', the Wine
248 code must use:
249
250  - 'xxx16' for the Win16 version,
251  - 'xxx'   for the Win32 version when no ASCII/Unicode strings are
252    involved,
253  - 'xxxA'  for the Win32 version with ASCII strings,
254  - 'xxxW'  for the Win32 version with Unicode strings.
255
256 If the function has both ASCII and Unicode version, you should then
257 use the macros WINELIB_NAME_AW(xxx) or DECL_WINELIB_TYPE_AW(xxx)
258 (defined in include/wintypes.h) to define the correct 'xxx' function
259 or type for Winelib. When compiling Wine itself, 'xxx' is _not_
260 defined, meaning that code inside of Wine must always specify
261 explicitly the ASCII or Unicode version.
262
263 If 'xxx' is the same in Win16 and Win32, you can simply use the same
264 name as Windows, i.e. just 'xxx'.  If 'xxx' is Win16 only, you could
265 use the name as is, but it's preferable to use 'xxx16' to make it
266 clear it is a Win16 function.
267
268 Examples:
269
270 typedef struct { /* Win32 ASCII data structure */ } WNDCLASSA;
271 typedef struct { /* Win32 Unicode data structure */ } WNDCLASSW;
272 typedef struct { /* Win16 data structure */ } WNDCLASS16;
273 DECL_WINELIB_TYPE_AW(WNDCLASS);
274
275 ATOM RegisterClass16( WNDCLASS16 * );
276 ATOM RegisterClassA( WNDCLASSA * );
277 ATOM RegisterClassW( WNDCLASSW * );
278 #define RegisterClass WINELIB_NAME_AW(RegisterClass)
279
280 The Winelib user can then say:
281
282     WNDCLASS wc = { ... };
283     RegisterClass( &wc );
284
285 and this will use the correct declaration depending on the definition
286 of the UNICODE symbol.
287
288
289 NAMING CONVENTIONS FOR NON-API FUNCTIONS AND TYPES
290 ==================================================
291
292 Functions and data which are internal to your code (or at least shouldn't be
293 visible to any WineLib or Windows program) should be preceded by
294 an identifier to the module:
295
296 Examples:
297
298 ENUMPRINTERS_GetDWORDFromRegistryA()    (in dlls/winspool/info.c)
299 IAVIFile_fnRelease()                    (in dlls/avifil32/avifile.c)
300 X11DRV_CreateDC()                       (in graphics/x11drv/init.c)
301 TIMER_Init()                            (implemented in windows/timer.c,
302                                          used in loader/main.c )
303
304 if you need prototypes for these, there are a few possibilities:
305 - within same source file only:
306   put the prototypes at the top of your file and mark them as prototypes.
307 - within the same module:
308   create a header file within the subdirectory where that module resides,
309   e.g.  graphics/ddraw_private.h
310 - from a totally different module, or for use in winelib:
311   put your header file entry in /include/wine/
312   but be careful not to clutter this directory!
313 under no circumstances, you should add non-api calls to the standard
314 windoze include files. Unfortunately, this is often the case, e.g.
315 the above example of TIMER_Init is defined in include/message.h
316
317
318 API ENTRY POINTS
319 ================
320
321 Because Win16 programs use a 16-bit stack and because they can only
322 call 16:16 addressed functions, all API entry points must be at low
323 address offsets and must have the arguments translated and moved to
324 Wines 32-bit stack.  This task is handled by the code in the "if1632"
325 directory.  To define a new API entry point handler you must place a
326 new entry in the appropriate API specification file.  These files are
327 named *.spec.  For example, the API specification file for the USER
328 DLL is contained in the file user.spec.  These entries are processed
329 by the "build" program to create an assembly file containing the entry
330 point code for each API call.  The format of the *.spec files is
331 documented in the file "tools/build-spec.txt".
332
333
334 DEBUG MESSAGES
335 ==============
336
337 To display a message only during debugging, you normally write something
338 like this:
339
340         TRACE(win,"abc...");  or
341         FIXME(win,"abc...");  or
342         WARN(win,"abc...");   or
343         ERR(win,"abc...");
344
345 depending on the seriousness of the problem. (documentation/degug-msgs
346 explains when it is appropriate to use each of them)
347
348 These macros are defined in include/debug.h. The macro-definitions are
349 generated by the shell-script tools/make_debug. It scans the source
350 code for symbols of this forms and puts the necessary macro
351 definitions in include/debug.h and include/debugdefs.h. These macros
352 test whether the debugging "channel" associated with the first
353 argument of these macros (win in the above example) is enabled and
354 thus decide whether to actually display the text.  In addition you can
355 change the types of displayed messages by supplying the "-debugmsg"
356 option to Wine.  If your debugging code is more complex than just
357 printf, you can use the symbols TRACE_ON(xxx), WARN_ON(xxx),
358 ERR_ON(xxx) and FIXME_ON(xxx) as well. These are true when channel xxx
359 is enabled, either permanent or in the command line. Thus, you can
360 write:
361
362         if(TRACE_ON(win))DumpSomeStructure(&str);
363
364 Don't worry about the inefficiency of the test. If it is permanently 
365 disabled (that is TRACE_ON(win) is 0 at compile time), the compiler will 
366 eliminate the dead code.
367
368 You have to start tools/make_debug only if you introduced a new macro,
369 e.g.  TRACE(win32).
370
371 For more info about debugging messages, read:
372
373 documentation/debug-msgs
374
375
376 MORE INFO
377 =========
378
379 1. There is a FREE online version of the MSDN library (including
380    documentation for the Win32 API) on http://www.microsoft.com/msdn/
381
382 2. http://www.sonic.net/~undoc/bookstore.html
383
384 3. In 1993 Dr. Dobbs Journal published a column called "Undocumented Corner".
385
386 4. You might want to check out BYTE from December 1983 as well :-)
387