Added environ support for Darwin.
[wine] / DEVELOPERS-HINTS
index 4c1d87e..beddbca 100644 (file)
@@ -11,167 +11,220 @@ there are also various tools, documentation, sample Winelib code, and
 code specific to the binary loader.  Note that several of the libraries
 listed here are "stubbed out", meaning they still need to be implemented.
 
-DLLs:
------
-       dlls/                   - All the DLLs implemented by Wine
-
-               advapi32/       - Crypto, systeminfo, security, eventlogging
-               avicap32/       - AVI capture window class
-               avifil32/       - COM object to play AVI files
-               cabinet/        - Cabinet file interface
-               comcat/         - Component category manager
-               comctl32/       - Common controls
-               commdlg/        - Common dialog boxes (both 16 & 32 bit)
-               crtdll/         - Old C runtime library
-               crypt32/        - Cryptography
-               ctl3d/          - 3D Effects for Common GUI Components
-               d3d8/           - Direct3D (3D graphics)
-               d3d9/           - Direct3D (3D graphics)
-               d3dim/          - Direct3D Immediate Mode
-               d3dx8/          - Direct3D (3D graphics)
-               dciman32/       - DCI Manager (graphics)
-               ddraw/          - DirectDraw (graphics)
-               devenum/        - Device enumeration (part of DirectShow)
-               dinput/         - DirectInput (device input)
-               dinput8/        - DirectInput (device input)
-               dmband/         - DirectMusic
-               dmcompos/       - DirectMusic
-               dmime/          - DirectMusic
-               dmloader/       - DirectMusic
-               dmscript/       - DirectMusic
-               dmstyle/        - DirectMusic
-               dmsynth/        - DirectMusic
-               dmusic/         - DirectMusic
-               dmusic32/       - DirectMusic
-               dplay/          - DirectPlay (networking)
-               dplayx/         - DirectPlay (networking)
-               dpnhpast/       - DirectPlay NAT Helper
-               dsound/         - DirectSound (audio)
-               gdi/            - GDI (graphics)
-               gdi/enhmfdrv/   - Enhanced metafile driver
-               gdi/mfdrv/      - Metafile driver
-               glu32/          - OpenGL Utility library (graphics)
-               icmp/           - ICMP protocol (networking)
-               imagehlp/       - PE (Portable Executable) Image Helper lib
-               imm32/          - Input Method Manager
-               iphlpapi/       - IP Helper API
-               kernel/         - The Windows kernel
-               lzexpand/       - Lempel-Ziv compression/decompression
-               mapi32/         - Mail interface
-               mpr/            - Multi-Protocol Router (networking)
-               msacm/          - Audio Compression Manager (multimedia)
-               msdmo/          - DirectX Media Objects
-               msimg32/        - Gradient and transparency (graphics)
-               msisys/         - System information
-               msi/            - Microsoft Installer
-               msnet32/        - Network interface
-               msvcrt/         - C runtime library 
-               msvcrt20/       - C runtime library version 2.0
-               msvcrtd/        - C runtime library debugging
-               msvideo/        - 16 bit video manager
-               mswsock/        - Misc networking
-               netapi32/       - Network interface
-               ntdll/          - NT implementation of kernel calls
-               odbc32/         - Open DataBase Connectivity driver manager
-               ole32/          - 32 bit OLE 2.0 libraries
-               oleaut32/       - 32 bit OLE 2.0 automation
-               olecli/         - 16 bit OLE client
-               oledlg/         - OLE 2.0 user interface support
-               olepro32/       - 32 bit OLE 2.0 automation
-               olesvr/         - 16 bit OLE server
-               opengl32/       - OpenGL implementation (graphics)
-               psapi/          - Process Status interface
-               qcap/           - DirectShow runtime
-               quartz/         - DirectShow runtime
-               rasapi32/       - Remote Access Server interface
-               richedit/       - Rich text editing control
-               rpcrt4/         - Remote Procedure Call runtime
-               serialui/       - Serial port property pages
-               setupapi/       - Setup interface
-               shdocvw/        - Shell document object and control
-               shfolder/       - Shell folder service
-               shell32/        - COM object implementing shell views
-               shlwapi/        - Shell Light-Weight interface
-               snmpapi/        - SNMP protocol interface (networking)
-               sti/            - Still Image service
-               tapi32/         - Telephone interface
-               ttydrv/         - TTY display driver (Wine specific)
-               twain/          - TWAIN Imaging device communications
-               url/            - Internet shortcut shell extension
-               urlmon/         - URL Moniker allows binding to a URL (like KIO/gnome-vfs)
-               user/           - Window management, standard controls, etc.
-               version/        - File installation library
-               win32s/         - 32-bit function access for 16-bit systems
-               winaspi/        - 16 bit Advanced SCSI Peripheral Interface
-               winedos/        - DOS features and BIOS calls (interrupts) (wine specific)
-               wineps/         - Postscript driver (Wine specific)
-               wininet/        - Internet extensions
-               winmm/          - Multimedia (16 & 32 bit)
-               winmm/mcianim/  - MCI animation driver
-               winmm/mciavi/   - MCI video driver
-               winmm/mcicda/   - MCI audio CD driver
-               winmm/mciseq/   - MCI MIDI driver
-               winmm/mciwave/  - MCI wave driver
-               winmm/midimap/  - MIDI mapper
-               winmm/wavemap/  - Audio mapper
-               winmm/winealsa/ - ALSA audio driver
-               winmm/winearts/ - aRts audio driver
-               winmm/winejack/ - JACK audio server driver
-               winmm/wineoss/  - OSS audio driver
-               winnls/         - National Language Support
-               winsock/        - Sockets 2.0 (networking)
-               wsock32/        - Sockets 1.1 (networking)
-               wintab32/       - Tablet device interface
-               winspool/       - Printing & Print Spooler
-               wintrust/       - Trust verification interface
-               wow32/          - WOW subsystem
-               x11drv/         - X11 display driver (Wine specific)
-
-Winelib programs:
------------------
-
-       programs/               - All the Winelib programs
-
-               avitools/       - AVI information viewer and player
-               clock/          - Graphical clock
-               cmdlgtst/       - Common dialog tests
-               control/        - Control panel
-               expand/         - Decompress Lempel-Ziv compressed archive
-               notepad/        - Notepad with RichEdit functionality
-               osversioncheck/ - Check version of Windows being indicated
-               progman/        - Program manager
-               regapi/         - Command line Registry implementation
-               regedit/        - Registry editor
-               regsvr32/       - Register COM server
-               regtest/        - Registry testing program
-               rpcss/          - RPC services
-               rundll32/       - Execute DLL functions directly
-               uninstaller/    - Remove installed programs
-               view/           - Metafile viewer
-               wcmd/           - Command line interface
-               wineconsole/    - Console
-               winedbg/        - Debugger
-               winefile/       - File manager
-               winemine/       - Mine game
-               winepath/       - Translate between Wine and Unix paths
-               winhelp/        - Help viewer
-               winver/         - Windows Version Program
+DLLs (under dlls/):
+-------------------
+
+       advapi32/               - Crypto, systeminfo, security, eventlogging
+       amstream/               - MultiMedia Streams
+       avicap32/               - AVI capture window class
+       avifil32/               - COM object to play AVI files
+       cabinet/                - Cabinet file interface
+       capi2032/               - Wrapper library for CAPI4Linux access
+       cards/                  - Card graphics
+       cfgmgr32/               - Config manager
+       comcat/                 - Component category manager
+       comctl32/               - Common controls
+       commdlg/                - Common dialog boxes (both 16 & 32 bit)
+       crtdll/                 - Old C runtime library
+       crypt32/                - Cryptography
+       ctl3d/                  - 3D Effects for Common GUI Components
+       d3d8/                   - Direct3D (3D graphics)
+       d3d9/                   - Direct3D (3D graphics)
+       d3dim/                  - Direct3D Immediate Mode
+       d3drm/                  - Direct3D Retained Mode
+       d3dx8/                  - Direct3D (3D graphics)
+       dbghelp/                - Engine for symbol and module enumeration
+       dciman32/               - DCI Manager (graphics)
+       ddraw/                  - DirectDraw (graphics)
+       devenum/                - Device enumeration (part of DirectShow)
+       dinput/                 - DirectInput (device input)
+       dinput8/                - DirectInput (device input)
+       dmband/                 - DirectMusic Band
+       dmcompos/               - DirectMusic Composer
+       dmime/                  - DirectMusic Interactive Engine
+       dmloader/               - DirectMusic Loader
+       dmscript/               - DirectMusic Scripting
+       dmstyle/                - DirectMusic Style Engine
+       dmsynth/                - DirectMusic Software Synthesizer
+       dmusic/                 - DirectMusic Core Services
+       dmusic32/               - DirectMusic Legacy Port
+       dplay/                  - DirectPlay (networking)
+       dplayx/                 - DirectPlay (networking)
+       dpnet/                  - DirectPlay (networking)
+       dpnhpast/               - DirectPlay NAT Helper PAST
+       dsound/                 - DirectSound (audio)
+       dswave/                 - DirectMusic Wave
+       dxdiagn/                - DirectX Diagnostic Tool 
+       gdi/                    - GDI (graphics)
+       glu32/                  - OpenGL Utility library (graphics)
+       glut32/                 - OpenGL Utility Toolkit
+       hhctrl.ocx/             - HHCTRL OCX implementation
+       iccvid/                 - Radius Cinepak Video Decoder
+       icmp/                   - ICMP protocol (networking)
+       ifsmgr.vxd/             - IFSMGR VxD implementation
+       imagehlp/               - PE (Portable Executable) Image Helper lib
+       imm32/                  - Input Method Manager
+       iphlpapi/               - IP Helper API
+       kernel/                 - The Windows kernel
+       lzexpand/               - Lempel-Ziv compression/decompression
+       mapi32/                 - Mail interface
+       mmdevldr.vxd/           - MMDEVLDR VxD implementation
+       monodebg.vxd/           - MONODEBG VxD implementation
+       mpr/                    - Multi-Protocol Router (networking)
+       msacm/                  - Audio Compression Manager (multimedia)
+       msacm/imaadp32/         - IMA ADPCM Audio Codec
+       msacm/msadp32/          - MS ADPCM Audio Codec
+       msacm/msg711/           - MS G711 Audio Codec (includes A-Law & MU-Law)
+       msacm/winemp3/          - Mpeg Layer 3 Audio Codec
+       msdmo/                  - DirectX Media Objects
+       mshtml/                 - MS HTML component
+       msi/                    - Microsoft Installer
+       msimg32/                - Gradient and transparency (graphics)
+       msisys/                 - System information
+       msnet32/                - Network interface
+       msvcrt/                 - C runtime library 
+       msvcrt20/               - C runtime library version 2.0
+       msvcrt40/               - C runtime library version 4.0
+       msvcrtd/                - C runtime library debugging
+       msvidc32/               - Microsoft Video-1 Decoder
+       msvideo/                - 16 bit video manager
+       msvideo/msrle32/        - Video codecs
+       mswsock/                - Misc networking
+       netapi32/               - Network interface
+       newdev/                 - New Hardware Device Library
+       ntdll/                  - NT implementation of kernel calls
+       odbc32/                 - Open DataBase Connectivity driver manager
+       ole32/                  - 32 bit OLE 2.0 libraries
+       oleacc/                 - OLE accessibility support
+       oleaut32/               - 32 bit OLE 2.0 automation
+       olecli/                 - 16 bit OLE client
+       oledlg/                 - OLE 2.0 user interface support
+       olepro32/               - 32 bit OLE 2.0 automation
+       olesvr/                 - 16 bit OLE server
+       opengl32/               - OpenGL implementation (graphics)
+       psapi/                  - Process Status interface
+       qcap/                   - DirectShow runtime
+       quartz/                 - DirectShow runtime
+       rasapi32/               - Remote Access Server interface
+       richedit/               - Rich text editing control
+       rpcrt4/                 - Remote Procedure Call runtime
+       rsabase/                - RSA encryption
+       secur32/                - Contains Windows Security functions
+       serialui/               - Serial port property pages
+       setupapi/               - Setup interface
+       setupx/                 - Contains functions used by the Windows Setup
+       shdocvw/                - Shell document object and control
+       shell32/                - COM object implementing shell views
+       shfolder/               - Shell folder service
+       shlwapi/                - Shell Light-Weight interface
+       snmpapi/                - SNMP protocol interface (networking)
+       sti/                    - Still Image service
+       tapi32/                 - Telephone interface
+       ttydrv/                 - TTY display driver (Wine specific)
+       twain/                  - TWAIN Imaging device communications
+       unicows/                - Unicows replacement (Unicode layer for Win9x)
+       url/                    - Internet shortcut shell extension
+       urlmon/                 - URL Moniker allows binding to a URL (like KIO/gnome-vfs)
+       user/                   - Window management, standard controls, etc.
+       uxtheme/                - Theme library
+       vdhcp.vxd/              - VDHCP VxD implementation
+       version/                - File installation library
+       vmm.vxd/                - VMM VxD implementation
+       vnbt.vxd/               - VNBT VxD implementation
+       vnetbios.vxd/           - VNETBIOS VxD implementation
+       vtdapi.vxd/             - VTDAPI VxD implementation
+       vwin32.vxd/             - VWIN32 VxD implementation
+       win32s/                 - 32-bit function access for 16-bit systems
+       winaspi/                - 16 bit Advanced SCSI Peripheral Interface
+       wined3d/                - Wine internal Direct3D helper
+       winedos/                - DOS features and BIOS calls (interrupts) (wine specific)
+       wineps/                 - Postscript driver (Wine specific)
+       wininet/                - Internet extensions
+       winmm/                  - Multimedia (16 & 32 bit)
+       winmm/joystick/         - Joystick driver
+       winmm/mcianim/          - MCI animation driver
+       winmm/mciavi/           - MCI video driver
+       winmm/mcicda/           - MCI audio CD driver
+       winmm/mciseq/           - MCI MIDI driver
+       winmm/mciwave/          - MCI wave driver
+       winmm/midimap/          - MIDI mapper
+       winmm/wavemap/          - Audio mapper
+       winmm/winealsa/         - ALSA audio driver
+       winmm/winearts/         - aRts audio driver
+       winmm/wineaudioio/      - audioio audio driver
+       winmm/winejack/         - JACK audio server driver
+       winmm/winenas/          - NAS audio driver
+       winmm/wineoss/          - OSS audio driver
+       winnls/                 - National Language Support
+       winsock/                - Sockets 2.0 (networking)
+       winspool/               - Printing & Print Spooler
+       wintab32/               - Tablet device interface
+       wintrust/               - Trust verification interface
+       wow32/                  - WOW subsystem
+       wsock32/                - Sockets 1.1 (networking)
+       x11drv/                 - X11 display driver (Wine specific)
+
+Winelib programs (under programs/):
+-----------------------------------
+
+       avitools/               - AVI information viewer and player
+       clock/                  - Graphical clock
+       cmdlgtst/               - Common dialog tests
+       control/                - Control panel
+       expand/                 - Decompress Lempel-Ziv compressed archive
+       notepad/                - Notepad replacement 
+       progman/                - Program manager
+       regedit/                - Registry editor
+       regsvr32/               - Register COM server
+       rpcss/                  - RPC services
+       rundll32/               - Execute DLL functions directly
+       start/                  - Replacement for start.exe
+       taskmgr/                - Manage running Windows/Winelib applications
+       uninstaller/            - Remove installed programs
+       view/                   - Metafile viewer
+       wcmd/                   - Command line interface
+       wineboot/               - Wine bootstrap process
+       winecfg/                - Wine configuration utility
+       wineconsole/            - Console
+       winedbg/                - Debugger
+       winefile/               - File manager
+       winemenubuilder/        - Helper program for building Unix menu entries
+       winemine/               - Mine game
+       winepath/               - Translate between Wine and Unix paths
+       winetest/               - Wine testing shell
+       winevdm/                - Wine virtual DOS machine
+       winhelp/                - Help viewer
+       winver/                 - Windows Version Program
 
 
 Support programs, libraries, etc:
 ---------------------------------
 
+       dlls/dxerr8/            - DirectX 8 error import lib
+       dlls/dxerr9/            - DirectX 9 error import lib
+       dlls/dxguid/            - DirectX UUID import lib
+       dlls/uuid/              - Windows-compatible UUID import lib
        documentation/          - some documentation
+       documentation/samples/  - sample configuration files
        include/                - Windows standard includes
+       include/msvcrt/         - MSVC compatible libc headers
+       include/wine/           - Wine specific headers
        libs/                   - the Wine libraries
        libs/port/              - portability library
        libs/unicode/           - Unicode support shared
-       libs/uuid/              - Windows-compatible UUID numbers
        libs/wine/              - Wine bootstrap library
        libs/wpp/               - C preprocessor
-       miscemu/                - the main Wine program
+       loader/                 - the main Wine loader
        server/                 - the Wine server
-       tools/                  - relay code builder, resource compiler, etc.
+       tools/                  - various tools used to build/check Wine
+       tools/widl/             - the IDL compiler
+       tools/winapi{,_check}/  - A Win32 API checker
+       tools/winebuild/        - Wine build tool
+       tools/winedump/         - a .DLL dump utility
+       tools/winegcc/          - a MinGW command line compatible gcc wrapper
+       tools/wmc/              - the message compiler
+       tools/wpp/              - the C pre-processor library
+       tools/wrc/              - the resource compiler
 
 
 Miscellaneous:
@@ -180,14 +233,8 @@ Miscellaneous:
 Note: these directories will ultimately get moved into their
 respective dlls.
 
-       files/                  - KERNEL file I/O
-       loader/                 - KERNEL loader code
-       memory/                 - KERNEL memory management
-       misc/                   - KERNEL shell, registry, winsock, etc.
-       msdos/                  - KERNEL DOS support
-       scheduler/              - KERNEL process and thread management
+       misc/                   - KERNEL registry 
 
-       graphics/               - GDI graphics drivers
        objects/                - GDI logical objects
 
        controls/               - USER built-in widgets
@@ -240,6 +287,11 @@ into a stub:
    *  
    * Draw many Bezier curves.
    *
+   * PARAMS
+   *   hdc   [I] Device context to draw to
+   *   p     [I] Array of POINT structs
+   *   count [I] Number of points in p
+   *
    * RETURNS
    *   Success: Non-zero.
    *   Failure: FALSE. Use GetLastError() to find the error cause.
@@ -247,19 +299,16 @@ into a stub:
    * BUGS
    *   Unimplemented
    */
-   BOOL WINAPI PolyBezierTo(HDC hdc,     /* [In] Device context to draw to */
-                            LPCVOID p,   /* [In] Array of POINT structs */
-                            DWORD count  /* [In] Number of points in p */
-   ) 
+   BOOL WINAPI PolyBezierTo(HDC hdc, LPCVOID p, DWORD count) 
    {
-      /* tell the user they've got a substandard implementation */
-      FIXME(gdi, ":(%x,%p,%d): stub\n", hdc, p, count);
-
-      /* some programs may be able to compensate, 
-       * if they know what happened 
-       */
-      SetLastError(ERROR_CALL_NOT_IMPLEMENTED);  
-      return FALSE;    /* error value */
+       /* tell the user they've got a substandard implementation */
+       FIXME(gdi, ":(%x,%p,%d): stub\n", hdc, p, count);
+
+       /* some programs may be able to compensate, 
+        * if they know what happened 
+        */
+       SetLastError(ERROR_CALL_NOT_IMPLEMENTED);  
+       return FALSE;    /* error value */
    }
 
 4. Implement and test the rest of the function.
@@ -403,16 +452,6 @@ struct { BYTE x; WORD y; };
 
 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; };
-
-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
-DWORD on a address that was not a multiple of 4).
-
 
 NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES
 ==============================================
@@ -423,8 +462,7 @@ functions and types. If the Windows API uses the name 'xxx', the Wine
 code must use:
 
  - 'xxx16' for the Win16 version,
- - 'xxx'   for the Win32 version when no ASCII/Unicode strings are
-   involved,
+ - 'xxx'   for the Win32 version when no strings are involved,
  - 'xxxA'  for the Win32 version with ASCII strings,
  - 'xxxW'  for the Win32 version with Unicode strings.
 
@@ -461,30 +499,6 @@ and this will use the correct declaration depending on the definition
 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)
-
-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:
-  you should never do that. Only exported APIs can be called across
-  module boundaries.
-
-
 DEBUG MESSAGES
 ==============