mirror of
git://source.winehq.org/git/wine.git
synced 2024-10-31 12:54:13 +00:00
- more up-to-date description of source tree
- better example of required comments for an API implementation - replacement of WINE_PACKED by "pshpack1.h", etc. - naming conventions for non-api calls and types - location conventions for non-api header files and prototypes
This commit is contained in:
parent
1c9b13e9d6
commit
0a7aa169c2
1 changed files with 98 additions and 17 deletions
115
DEVELOPERS-HINTS
115
DEVELOPERS-HINTS
|
@ -1,6 +1,7 @@
|
||||||
This document should help new developers get started. Like all of Wine, it
|
This document should help new developers get started. Like all of Wine, it
|
||||||
is a work in progress.
|
is a work in progress.
|
||||||
|
|
||||||
|
|
||||||
SOURCE TREE STRUCTURE
|
SOURCE TREE STRUCTURE
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
|
@ -23,19 +24,40 @@ KERNEL:
|
||||||
GDI:
|
GDI:
|
||||||
|
|
||||||
graphics/ - graphics drivers
|
graphics/ - graphics drivers
|
||||||
graphics/x11drv/ - X11 display driver
|
x11drv/ - X11 display driver
|
||||||
graphics/metafiledrv/ - metafile driver
|
win16drv/ -> see below
|
||||||
|
ttydrv/ - tty display driver
|
||||||
|
psdrv/ - PostScript graphics driver
|
||||||
|
metafiledrv/ - metafile drivr
|
||||||
|
enhmetafiledrv/ - enhanced metafile driver
|
||||||
objects/ - logical objects
|
objects/ - logical objects
|
||||||
|
|
||||||
USER:
|
USER:
|
||||||
|
|
||||||
controls/ - built-in widgets
|
controls/ - built-in widgets
|
||||||
resources/ - built-in dialog resources
|
resources/ - built-in menu and message box resources
|
||||||
windows/ - window management
|
windows/ - window management
|
||||||
|
|
||||||
Other DLLs:
|
Other DLLs:
|
||||||
|
|
||||||
dlls/*/ - Other system DLLs implemented by Wine
|
dlls/ - Other system DLLs implemented by Wine
|
||||||
|
advapi32/ - crypto, systeminfo, security, eventlogging
|
||||||
|
avifil32/ - COM object to play AVI files
|
||||||
|
comctl32/ - common controls
|
||||||
|
commdlg/ - common dialog boxes (both 16 & 32 bit)
|
||||||
|
imagehlp/ - PE (Portable Executable) Image Helper lib
|
||||||
|
msacm/ - audio compression manager (multimedia)
|
||||||
|
msacm32/ - audio compression manager (multimedia)
|
||||||
|
ntdll/ - NT implementation of kernel calls
|
||||||
|
psapi/ - process status API
|
||||||
|
rasapi32/ - remote access server API
|
||||||
|
shell32/ - COM object implementing shell views
|
||||||
|
tapi32/ - telephone API
|
||||||
|
ver/ - File Installation Library (16 bit)
|
||||||
|
version/ - File Installation Library (32 bit)
|
||||||
|
winaspi/ -
|
||||||
|
winspool/ - Printing & Print Spooler
|
||||||
|
wnaspi32/ -
|
||||||
|
|
||||||
Miscellaneous:
|
Miscellaneous:
|
||||||
|
|
||||||
|
@ -43,12 +65,16 @@ Miscellaneous:
|
||||||
multimedia/ - multimedia driver
|
multimedia/ - multimedia driver
|
||||||
ipc/ - SysV IPC based interprocess communication
|
ipc/ - SysV IPC based interprocess communication
|
||||||
win32/ - misc Win32 functions
|
win32/ - misc Win32 functions
|
||||||
|
ole/ - OLE code
|
||||||
|
nls/ - National Language Support
|
||||||
|
configuration files
|
||||||
|
|
||||||
Tools:
|
Tools:
|
||||||
------
|
------
|
||||||
|
|
||||||
rc/ - old resource compiler
|
rc/ - old resource compiler
|
||||||
tools/ - relay code builder, new rc, etc.
|
tools/ - relay code builder, new rc, bugreport
|
||||||
|
generator, wineconfigurator, etc.
|
||||||
documentation/ - some documentation
|
documentation/ - some documentation
|
||||||
|
|
||||||
|
|
||||||
|
@ -59,6 +85,8 @@ Binary loader specific directories:
|
||||||
if1632/ - relay code
|
if1632/ - relay code
|
||||||
miscemu/ - hardware instruction emulation
|
miscemu/ - hardware instruction emulation
|
||||||
graphics/win16drv/ - Win16 printer driver
|
graphics/win16drv/ - Win16 printer driver
|
||||||
|
server/ - the main, controlling thread of wine
|
||||||
|
tsx11/ - thread-safe X11 wrappers (auto generated)
|
||||||
|
|
||||||
Winelib specific directories:
|
Winelib specific directories:
|
||||||
-----------------------------
|
-----------------------------
|
||||||
|
@ -67,6 +95,7 @@ Winelib specific directories:
|
||||||
libtest/ - Small samples and tests
|
libtest/ - Small samples and tests
|
||||||
programs/ - Extended samples / system utilities
|
programs/ - Extended samples / system utilities
|
||||||
|
|
||||||
|
|
||||||
IMPLEMENTING NEW API CALLS
|
IMPLEMENTING NEW API CALLS
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
|
@ -79,7 +108,8 @@ unimplemented call will look like (from gdi32.spec)
|
||||||
To implement this call, you need to do the following four things.
|
To implement this call, you need to do the following four things.
|
||||||
|
|
||||||
1. Find the appropriate parameters for the call, and add a prototype to
|
1. Find the appropriate parameters for the call, and add a prototype to
|
||||||
[include/windows.h]. In this case, it might look like
|
the correct header file. In this case, that means [include/wingdi.h],
|
||||||
|
and it might look like
|
||||||
BOOL WINAPI PolyBezierTo(HDC, LPCVOID, DWORD);
|
BOOL WINAPI PolyBezierTo(HDC, LPCVOID, DWORD);
|
||||||
If the function has both an ASCII and a Unicode version, you need to
|
If the function has both an ASCII and a Unicode version, you need to
|
||||||
define both and add a #define WINELIB_NAME_AW declaration. See below
|
define both and add a #define WINELIB_NAME_AW declaration. See below
|
||||||
|
@ -101,26 +131,38 @@ Add a function called 'PolyBezierTo' somewhere. Good things to put
|
||||||
into a stub:
|
into a stub:
|
||||||
o a correct prototype, including the WINAPI
|
o a correct prototype, including the WINAPI
|
||||||
o header comments, including full documentation for the function and
|
o header comments, including full documentation for the function and
|
||||||
arguments
|
arguments (see documentation/README.documentation)
|
||||||
o A FIXME message and an appropriate return value are good things to
|
o A FIXME message and an appropriate return value are good things to
|
||||||
put in a stub.
|
put in a stub.
|
||||||
|
|
||||||
/************************************************************
|
/************************************************************
|
||||||
* PolyBezierTo (GDI32.269) Draw many Bezier curves
|
* PolyBezierTo (GDI32.269)
|
||||||
|
*
|
||||||
|
* Draw many Bezier curves
|
||||||
|
*
|
||||||
|
* RETURNS
|
||||||
|
* nonzero on success or zero on faillure
|
||||||
*
|
*
|
||||||
* BUGS
|
* BUGS
|
||||||
* Unimplemented
|
* Unimplemented
|
||||||
*/
|
*/
|
||||||
BOOL WINAPI PolyBezierTo(HDC hdc, LPCVOID p, DWORD count) {
|
BOOL WINAPI PolyBezierTo(HDC hdc, /* handle to device context */
|
||||||
/* tell the user they've got a substandard implementation */
|
LPCVOID p, /* ptr to array of Point structs */
|
||||||
|
DWORD count /* nr of points in array */
|
||||||
|
)
|
||||||
|
{
|
||||||
|
/* tell the user they've got a substandard implementation */
|
||||||
FIXME(gdi, ":(%x,%p,%d): stub\n", hdc, p, count);
|
FIXME(gdi, ":(%x,%p,%d): stub\n", hdc, p, count);
|
||||||
/* some programs may be able to compensate,
|
|
||||||
if they know what happened */
|
/* some programs may be able to compensate,
|
||||||
|
* if they know what happened
|
||||||
|
*/
|
||||||
SetLastError(ERROR_CALL_NOT_IMPLEMENTED);
|
SetLastError(ERROR_CALL_NOT_IMPLEMENTED);
|
||||||
return FALSE; /* error value */
|
return FALSE; /* error value */
|
||||||
}
|
}
|
||||||
|
|
||||||
4. Implement and test the function.
|
4. Implement and test the rest of the function.
|
||||||
|
|
||||||
|
|
||||||
MEMORY AND SEGMENTS
|
MEMORY AND SEGMENTS
|
||||||
===================
|
===================
|
||||||
|
@ -177,14 +219,24 @@ struct { BYTE x; WORD y; };
|
||||||
|
|
||||||
will take 3 bytes under Windows, but 4 with gcc, because gcc will add a
|
will take 3 bytes under Windows, but 4 with gcc, because gcc will add a
|
||||||
dummy byte between x and y. To have the correct layout for structures
|
dummy byte between x and y. To have the correct layout for structures
|
||||||
used by Windows code, you need to use the WINE_PACKED attribute; so you
|
used by Windows code, you need to embed the struct within two special
|
||||||
would declare the above structure like this:
|
#include's which will take care of the packing for you:
|
||||||
|
|
||||||
|
#include "pshpack1.h"
|
||||||
|
struct {BYTE x; WORD y; };
|
||||||
|
#include "poppack1.h"
|
||||||
|
|
||||||
|
For alignment on a 2-byte boundary, there is a "pshpack2.h", etc.
|
||||||
|
|
||||||
|
The use of the WINE_PACKED attribute is obsolete. Please remove these
|
||||||
|
in favour of the above solution.
|
||||||
|
Using WINE_PACKED, you would declare the above structure like this:
|
||||||
|
|
||||||
struct { BYTE x; WORD y WINE_PACKED; };
|
struct { BYTE x; WORD y WINE_PACKED; };
|
||||||
|
|
||||||
You have to do this every time a structure member is not aligned
|
You had to do this every time a structure member is not aligned
|
||||||
correctly under Windows (i.e. a WORD not on an even address, or a
|
correctly under Windows (i.e. a WORD not on an even address, or a
|
||||||
DWORD on a address that is not a multiple of 4).
|
DWORD on a address that was not a multiple of 4).
|
||||||
|
|
||||||
|
|
||||||
NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES
|
NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES
|
||||||
|
@ -234,6 +286,35 @@ and this will use the correct declaration depending on the definition
|
||||||
of the UNICODE symbol.
|
of the UNICODE symbol.
|
||||||
|
|
||||||
|
|
||||||
|
NAMING CONVENTIONS FOR NON-API FUNCTIONS AND TYPES
|
||||||
|
==================================================
|
||||||
|
|
||||||
|
Functions and data which are internal to your code (or at least shouldn't be
|
||||||
|
visible to any WineLib or Windows program) should be preceded by
|
||||||
|
an identifier to the module:
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
ENUMPRINTERS_GetDWORDFromRegistryA() (in dlls/winspool/info.c)
|
||||||
|
IAVIFile_fnRelease() (in dlls/avifil32/avifile.c)
|
||||||
|
X11DRV_CreateDC() (in graphics/x11drv/init.c)
|
||||||
|
TIMER_Init() (implemented in windows/timer.c,
|
||||||
|
used in loader/main.c )
|
||||||
|
|
||||||
|
if you need prototypes for these, there are a few possibilities:
|
||||||
|
- within same source file only:
|
||||||
|
put the prototypes at the top of your file and mark them as prototypes.
|
||||||
|
- within the same module:
|
||||||
|
create a header file within the subdirectory where that module resides,
|
||||||
|
e.g. graphics/ddraw_private.h
|
||||||
|
- from a totally different module, or for use in winelib:
|
||||||
|
put your header file entry in /include/wine/
|
||||||
|
but be careful not to clutter this directory!
|
||||||
|
under no circumstances, you should add non-api calls to the standard
|
||||||
|
windoze include files. Unfortunately, this is often the case, e.g.
|
||||||
|
the above example of TIMER_Init is defined in include/message.h
|
||||||
|
|
||||||
|
|
||||||
API ENTRY POINTS
|
API ENTRY POINTS
|
||||||
================
|
================
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue