Added description of using DLLs with WineLib.

documentation/HOWTO-winelib

@@ -1,5 +1,5 @@
 WineLib HOWTO
-Version 11-Jun-2000
+Version 30-Jul-2000
 
 AUTHOR: 
 Wilbur Dale
@@ -30,10 +30,10 @@ Table of Contents
   VI. Compiling A Win32 Program With Resources
 
  VII. DLLs
-    A. Native DLL.
+    A. Windows executable and Windows DLL.
-    B. so DLL.
+    B. Windows executable and WineLib DLL.
-    C. elfDLL.
+    C. WineLib executable and Windows DLL.
-    D. resource DLL.
+    D. WineLib executable and WineLib DLL.
 
 VIII. How to use MFC
     A. Using a native MFC DLL
@@ -47,6 +47,8 @@ Unix is a trademark of ???? FIXME: who has the trademark this week?
 
 CrypKey is a trademark of Kenonic Controls Ltd.
 
+FIXME: Codewright copyright ???
+
 All other trademarks are the property of their respective owners.
 
 =====================================================================
@@ -71,20 +73,35 @@ does not give you source, then you can use the Windows version of the
 DLL to provide the functions and compile the rest of your program in
 the native form for your system. [1]
 
-Windows compilers assume a different structure than standard
+Windows compilers and linkers generate executables with a different
-compilers. For example, standard compilers assume that the function
+structure than standard compilers. Windows has two executable formats:
-main() exists and is the entry point of the program. On the other
+the NE format and the PE format. The NE executable format provides for
-hand, windows compilers create a main() that issues an error message
+two entry points and the PE format provides for three entry points
-that states that windows is required for executing the program and the
+while a standard executable has a single entry point. Usually, a NE or
-real entry point is the function WinMain(). As a result, WineLib
+a PE executable will use one of the entry points for your program and
-provides certain aids to generate code so that your program can be
+the other entry points will print an error message and exit. However,
-compiled and run as written for windows. For example, WineLib
+a linker can link 16 bit objects into one or both of the alternate
-generates a main() to initialize the windows API, to load any
+entry points of a NE or PE executable.
+
+Standard compilers assume that the function main() exists. The entry
+point for a standard program is constructed from the C runtime
+library, initialization code for static variables in your program, the
+initialization code for your classes (C++), and your function main().
+On the other hand, windows compilers assume WinMain() exists. The
+entry point for a windows program is constructed from the C runtime
+library, initialization code for static variables in your program, the
+initialization code for your classes (C++), and your function
+WinMain(). [4]
+
+Since main() and WinMain() have different type signatures (parameter
+types), WineLib provides certain aids to generate code so that your
+program can be compiled and run as written for windows. For example,
+WineLib generates a main() to initialize the windows API, to load any
 necessary DLLs and then call your WinMain(). Therefore, you need to
 learn four basic operations to compile a windows program using
 WineLib: compiling a simple program, compiling resources, compiling
-libraries, and compiling MFC. These skills or operations are explained
+libraries, and compiling MFC (if you will be using MFC). Each of these
-in later sections of this HOWTO.
+skills or operations are explained in later sections of this HOWTO.
 
 Before you start porting your windows code to WineLib, you need to
 consider whether you are allowed to port your program to WineLib. As
@@ -216,6 +233,17 @@ implement.
 FIXME: give info on Wine command line options to control error
 messages. 
 
+During the compilation of Wine, you can control the amount of error
+messages and debug information that will be be generated by Wine and
+WineLib. For the version released to your customers, you may want to
+use the following command line to configure the Wine/WineLib
+libraries.
+
+./configure --disable-debug --disable-trace
+
+The option --disable-debug compiles out all debugging messages and the
+option --disable-trace compile out TRACE messages. [2] 
+
 It is not necessary for you to implement the entire documented
 behavior of an API function in order to get your program to work. For
 example, many API functions have pointer parameters that are NULL in
@@ -243,12 +271,20 @@ Before you can compile your program, you must deal with one major
 difference between Windows and WineLib. Window sources are in DOS
 format with carriage return / line feed at the end of each line of
 text while WineLib files are in Unix format with only line feed at the
-end of each line of text. Before you compile your sources, you will
+end of each line of text. 
-need to convert you DOS format sources to Unix format. There are
-several tools such as dos2unix and tr that are available to convert
-the format.
 
-FIXME: explain about line continuation in macros with CR/LF lines.
+The main problem with the difference between Unix and DOS format
+source files occurs with macro line continuation. A Unix compiler
+expects a backslash (\) followed by a newline (^J) to indict that a
+macro is continued on the next line. However, a file in DOS format will
+have the characters backslash (\), carriage return (^M), and newline
+(^J). The Unix compiler will interpret the backslash (\), carriage
+return (^M), newline (^) of a file in DOS format as a quoted carriage
+return and newline. The Unix compiler will think the line has ended
+and the macro is completely defined. Hence, before you compile your
+sources, you will need to convert you DOS format sources to Unix
+format. There are several tools such as dos2unix and tr that are
+available to convert the format.
 
 FIXME: get more info on dos2unix, tr, and all other such tools and
 give example commands. Until I do [3] is a good source.
@@ -285,13 +321,14 @@ mode	guiexe
 type	win32
 init	WinMain
 
-Name is the name of the application. Mode is the type of "glue" that
+Information on the complete format of the spec file can be found in
-winebuild needs to create. Possible modes are 'dll' for a library,
+<wine>/tools/winebuild/README. Name is the name of the
-'cuiexe' for a console application, and 'guiexe' for a regular
+application. Mode is the type of "glue" that winebuild needs to
-graphical application. Type is the type of API, either win32 or
+create. Possible modes are 'dll' for a library, 'cuiexe' for a console
-win16. Win16 is supported only in Wine, not WineLib, so you should use
+application, and 'guiexe' for a regular graphical application. Type is
-win32. Init is the function to call for initialization: in this case,
+the type of API, either win32 or win16. Win16 is supported only in
-WinMain.
+Wine, not WineLib, so you should use win32. Init is the function to
+call for initialization: in this case, WinMain.
 
 During compilation of the hello2 executable, the following command is
 executed. 
@@ -300,14 +337,16 @@ executed.
 
 The program winebuild will generate the output file hello2.spec.c (option
 -o hello2.spec.c) from the spec file hello2.spec (option -spec
-hello2.spec). The output file contains some assembly directives and
+hello2.spec). The option -pic specifies that winebuild should generate
-these directives are position independent code (option -fPIC). The
+position independent code and is only necessary for building shared
-winebuild program is used in several places in Wine as well as WineLib;
+library files (.so files). It is not needed when building the main
-however, only the -spec option will be used in WineLib. The output
+executable spec file, but since there is no assembly code generated
-file hello2.spec.c contains main() and the glue code to initialize
+for the main executable, it doesn't make any difference anyway. [5]
-WineLib and call WinMain().
 
-FIXME: for WineLib users -- is there ever a need to not specify -fPIC?
+The winebuild program is used in several places in Wine as well as
+WineLib; however, only the -spec option will be used in WineLib. The
+output file hello2.spec.c contains main() and the glue code to
+initialize WineLib and call WinMain().
 
 Now the compilation of hello2 can proceed as any other compilation for
 a program.
@@ -338,11 +377,11 @@ Thus, you now have the basics of compiling a simple windows
 program. There are two more things to learn for compiling more complex
 windows programs: windows resources and DLL dependencies. Window
 resources are described in the next section. DLL dependencies are
-handled by linker magic with windows compilers. Thus, you will need to
+handled by linker magic with windows compilers. Thus, in WineLib, you
-provide information about which DLLs your program depends. This
+will need to provide information about which DLLs your program
-information is given in the spec file. For example, if our hello2
+depends. This information is given in the spec file. For example, if
-program had a .wav file that it played, it would need the multi-media
+our hello2 program had a .wav file that it played, it would need the
-DLL winmm. Our spec file would then be
+multi-media DLL winmm. Our spec file would then be
 
 name	hello2
 mode	guiexe
@@ -362,16 +401,208 @@ Describe wrc.
 Go through hello world example 3.
 
 VII. DLLs
-    A. Native DLL.
-    B. so DLL.
-    C. elfdll.
-    D. resource DLL
 
-FIXME: to be continued.
+As mentioned in the introduction, Wine allows you to execute windows
-QUESTION: what are so DLL and elfdll. I think I have been doing so
+executables and windows libraries under non-Microsoft operating
-DLL. 
+systems. WineLib allows you to take sources intended for the windows
+operating system and to compile them to run as native executables
+under a Unix/Linux operating system. With an executable and a single
+library, there are four combinations in which to run the programs and
+the library:
+    1. a Windows executable with a Windows DLL,
+    2. a Windows executable with WineLib DLL,
+    3. a WineLib executable with Windows DLL, and
+    4. a WineLib executable with WineLib DLL.
+In this section, we will discuss each of these and discuss the steps
+required to implement the executable/DLL combination. 
 
-Go over an example similar to edrlib in Petzold.
+A. Windows executable and Windows DLL
+
+Running a windows executable with a windows DLL is not a WineLib
+program: it is a Wine program. If you type
+    wine program.exe
+and the DLL is in the search path, then the windows program should run
+using the windows DLL.
+
+FIXME: find out what is the search path.
+
+B. Windows executable and WineLib DLL
+
+Running a windows executable with a WineLib DLL is also accomplished
+using the Wine program. The source code for the DLL is compiled into a
+Unix style shared library. When the windows executable "loads" the
+DLL, Wine will use the shared library (.so file) instead.
+
+At first you may wonder why you would want to run a windows executable
+with a WineLib DLL. Such a situation implies you do not have the
+source for the executable, but you do have the source for the
+DLL. This is backwards from what you might expect. However, I do have
+an example where this situation might arise.
+
+Codewright is a popular editor in the windows world, and the
+capabilities of Codewright can be extended by using DLLs. Since
+Codewright is a commercial product, you do not have the source and
+must use the windows executable with Wine. If you have written a DLL
+to add functionality to Codewright, you have two choices: you can
+compile the DLL using a windows compiler and use both a windows
+executable and a windows DLL as in case A above, or you can use
+WineLib and compile the DLL as a shared library (.so file). I have no
+idea if Codewright actually runs under Wine, but this is an example of
+why you might decide to use a windows executable and a WineLib
+DLL. Many other editors and other programs use DLLs to extend their
+functionality.
+
+In order for Wine to use the WineLib DLL, certain glue code is need to
+replace the linker magic that windows compilers use. As with a simple
+executable, the winebuild program uses a spec file to generate the glue
+code. For example, in the spec file for the DLL will look something like
+    name	winedll
+    type	win32
+    init	winedll_DllMain
+    1 cdecl _WINEbirthDay@4 ( str ) WINEbirthDay
+    2 cdecl _WINEfullName@4 ( str ) WINEfullName
+The name is the name of the DLL. Since WineLib only supports win32,
+the type should always be win32. The init function is the name of the
+initialization function for the DLL. The initialization function for a
+windows DLL is named DllMain(). You will need to rename the function
+in the DLL source so there will not be any name clashes with the
+DllMain() of other DLLs in you program.
+
+The last two lines of the spec file above, provide the export
+information for the DLL. For example, the line
+    1 cdecl _WINEbirthDay@4 ( str ) WINEbirthDay
+says that the function at ordinal 1 uses the cdecl calling convention
+for the parameters. The DLL export name is _WINEbirthDay@4. The
+function takes a single parameter that is a string. Finally, the C
+function name to be called whenever this DLL function is called is
+WINEbirthday. You will need a function ordinal line for each function
+in the DLL. The export name and the ordinal can be obtained from the
+windows program dumpbin and the windows version of the DLL. See the
+file <wine>/tools/winebuild/README for more details on the spec file
+format.
+
+During the the compile process, a command like
+    winebuild -fPIC -o winedll.spec.c -spec winedll.spec
+will be executed to create the file winedll.spec.c from information in
+the file winedll.spec. The file winedll.spec.c and winedll.c are
+compiled into object files and used to create the shared library.
+
+In order for the program to run, a copy of the shared library must be in
+your EXTRA_LD_LIBRARY_PATH. For example, if your wine.conf file has
+the following line,
+    EXTRA_LD_LIBRARY_PATH=${HOME}/wine/lib
+then you must copy the shared library into the directory ~/wine/lib/
+and the shared library will now be in the correct search path.
+
+Now when you type 
+    wine program.exe
+the program will load the shared library (.so).
+
+C. WineLib executable and Windows DLL
+
+Running a WineLib executable with a Windows DLL is accomplished
+using WineLib. This situation will be common since you may have
+purchased DLLs to use with you project and the DLL vendor may not give
+you the source code for the DLL.
+
+In order for WineLib to use the Windows DLL, certain glue code is
+needed to replace the linker magic that windows compilers use. Part of
+the glue code must be written by you. The basic idea of the glue code
+is that you write a new DLL that consists of function pointers. Each
+function in the DLL will consist of a call on a function pointer. For
+example, 
+    WINEDLL_ConstString WINEDLL_INTERFACE 
+    WINEfullName( WINEDLL_ConstString handle ) {
+        return (* pWINEfullName) ( handle );
+    }
+The initialization function for the DLL will use the function
+LoadLibrary() to load the windows DLL and initialize the function
+pointers using the function GetProcAddress(). 
+
+Since Wine can use either windows DLLs or Unix shared libraries (.so),
+the LoadLibrary() function call may have unexpected results if there
+is a winedll.dll and a winedll.so file. Hence, the windows version of
+the DLL should be named something like hiddenWinedll.dll and the
+shared library should be named winedll.so. Now the shared library will
+use LoadLibrary() to load the "hidden" DLL.
+
+The shared library will need a spec file. Fortunately, it is simpler
+than case B above. The spec file will look something like
+    name	winedll
+    type	win32
+    init	winedll_DllMain
+The name is the name of the DLL. Since WineLib only supports win32,
+the type should always be win32. The init function is the name of the
+initialization function for the shared library. This is the function
+that will load the "hidden" DLL and initialize the function
+pointers. There is no need for any function ordinals unless your
+program calls functions by the ordinal.
+
+During the the compile process, a command like
+    winebuild -fPIC -o winedll.spec.c -spec winedll.spec
+will be executed to create the file winedll.spec.c from information in
+the file winedll.spec. The file winedll.spec.c and winedll.c are
+compiled into object files and used to create the shared library.
+
+Now that the shared library is compiled, you still need to compile
+your program. Part of the compile process for your program will
+consist of a spec file for you program. For example,
+    name	program
+    mode	guiexe
+    type	win32
+    init	WinMain
+    import winedll.dll
+This spec file is similar to the spec file of the simple WineLib
+example in part V above. The only difference is the import
+specification that tells WineLib that the main program uses
+winedll.dll. If this import line is not included, the "hidden" DLL
+will not be loaded and the function pointers will not be initialized.
+
+During the the compile process, a command like
+    winebuild -fPIC -o program.spec.c -spec program.spec
+will be executed to create the file program.spec.c from information in
+the file program.spec. The file program.spec.c and your source code are
+compiled into object files and used to create the executable.
+
+D. WineLib executable and WineLib DLL.
+
+Running a WineLib executable with a WineLib DLL is accomplished using
+WineLib. The source for the DLL will be combined with a spec file to
+generate the shared library. Likewise, the source for your program and
+a spec file will be combined to create the executable. In the source
+for the DLL, you should change the name of DllMain() to a name like
+winedll_DllMain() so that there will not be a name clash with other
+initialization functions for other DLLs.
+
+The shared library's spec file is like case C above. The spec file
+will look something like
+    name	winedll
+    type	win32
+    init	winedll_DllMain
+The init function is the name of the initialization function for the
+shared library (what you renamed DllMain to). There is no need for any
+function ordinals unless your program calls functions by the ordinal.
+
+During the the compile process, a command like
+    winebuild -fPIC -o winedll.spec.c -spec winedll.spec
+will be executed to create the file winedll.spec.c from information in
+the file winedll.spec. The file winedll.spec.c and the source code for
+your DLL are compiled into object files and used to create the shared
+library.
+
+Compiling your program is exactly like case C above. For example, the
+spec file for you program will look something like
+    name	program
+    mode	guiexe
+    type	win32
+    init	WinMain
+    import winedll.dll
+
+During the the compile process, a command like
+    winebuild -fPIC -o program.spec.c -spec program.spec
+will be executed to create the file program.spec.c from information in
+the file program.spec. The file program.spec.c and your source code are
+compiled into object files and used to create the executable.
 
 VIII. How to use MFC
     A. Using a native MFC DLL
@@ -406,6 +637,11 @@ instead of, as in your document, sometime one variant, sometimes
 another.
 
 Reference [2] 
+
+The exact options for controlling error messages mentioned in the
+reference are apparently incorrect, but may have been correct for some
+earlier version of Wine.
+
 From: michael cardenas <mbc@deneba.com>
 To: wilbur.dale@lumin.nl
 Date:   Mon, 5 Jun 2000 13:19:34 -0400
@@ -426,8 +662,74 @@ Take a look at configure.
 least for the release version of your app.
 
 Reference [3] 
-http://fgouget/wine/winelib-en.shtml
+http://fgouget.free.fr/wine/winelib-en.shtml
 
+Reference [4]
+Date: Wed, 21 Jun 2000 10:34:10 +0200
+From: Rob Carriere <rob.carriere@lumin.nl>
+To: Wilbur N Dale <wilbur.dale@lumin.nl>
+Subject: WineLib-HOWTO comments
+
+Hello Wilbur,
+
+Some picking of nits.  It reads right well.
+
+Some of Windows xyz are registered trade marks, other are vanilla:
+Microsoft: Registered
+Windows NT: Registered
+Windows (95,98): plain
+
+A Windows compiler does NOT generate a fake main.  Instead, the
+executable file format provides for 2 (NE) or 3 (PE) entry points.
+One of these is your program, the other(s) are normally filled with
+stubs that print an error message and exit.  It is possible to instruct
+the _linker_ to link 16-bit objects into one or both of the alternate
+entry points, and create a fat binary.
+
+At the C/C++ level, your statement about WinMain() is correct.  Of
+course the actual entry point first inits run time lib etc, and then
+calls the C/C++ level entry, but that is also true for main() in the
+standard setup.  It may be important to regurgitate this info here,
+though, because some of the fun things that can happen with multiple
+run time libs and DLLs occur at this level.
+
+Line 86: I only need to know how compile MFC if I use it... :-)
+
+
+Best regards,
+ Rob                          mailto:rob.carriere@lumin.nl
+
+Reference [5]
+To: wilbur.dale@lumin.nl
+Subject: Re: tool/build questions
+From: Alexandre Julliard <julliard@winehq.com>
+Date:   13 Jun 2000 20:06:23 -0700
+
+"Wilbur N. Dale" <wilbur.dale@lumin.nl> writes:
+
+> 2. tools/build for WineLib users -- is there ever a need to not specify -pic?
+
+-pic is only necessary for building .so files, so it's not needed when
+building the main executable spec file (but since there is no assembly
+code generated for the main exe it doesn't make any difference anyway).
+
+-- 
+Alexandre Julliard
+julliard@winehq.com
+
+Reference [6]
+Wine Weekly News #51 (2000 Week 28)
+
+Events, progress, and happenings in the Wine community for 
+July 10, 2000. 
+
+Uwe Bonnes and Ove Kaven also reminded of some tools to generate under
+   Linux some Windows executables:
+     * Cygwin/Mingw: as native Linux apps
+     * LCC-Win32: run with the help of Wine
+     * Borland C++ 5.5: command line version available for free (after
+       registering to Borland users' database)
+       
 =====================================================================
 
 The information included here is from various Wine-devel posting and
@@ -442,6 +744,10 @@ questions. The info I have mentions three problems:
     into Wine cvs? Do the changes need #ifdef for C vs. C++
     compilation? 
 
+    Francois Gouget <fgouget@psn.net> has been doing a lot of work in
+    this area. It should be a lot easier to compile using C++ now and to
+    compile MFC.
+
     2. DOS format files <CR/LF> and no case distinction in
     filenames. Do the extensions Corel made to gcc 2.95 handle this?
     If so, how?
@@ -720,6 +1026,11 @@ p.s.
 If any of You is interested in details I can share my
 experience.
 
+WND comment:
+    Francois Gouget <fgouget@psn.net> has been doing a lot of work in
+    the  headers of wine. It should be a lot easier to compile using
+    C++ now and to compile MFC. Many of the actions needed in the
+    following email are not needed any more.
 
 From: Damyan Ognyanoff <Damyan@rocketmail.com>
 Subject: Re: Wine MFC info request
@@ -966,26 +1277,12 @@ MFC
 Regards 
 Damyan.
 
- LocalWords:  WineLib HOWTO Jun vs DLLs DLL MFC NT FIXME CrypKey Kenonic API TM
+ LocalWords:  WineLib HOWTO Jul vs DLLs DLL MFC NT FIXME CrypKey Kenonic API TM
- LocalWords:  WinMain GPL LGPL EULA winver nt dos unix tr CR LF gcc libtest dll
+ LocalWords:  Codewright NE PE WinMain GPL LGPL EULA nonexclusive winver nt dos
- LocalWords:  guiexe init cuiexe pic lwine lncurses lm lutil ldl wav winmm wrc
+ LocalWords:  redistributables unix tr CR LF gcc libtest winebuild pic fPIC dll
- LocalWords:  elfdll edrlib Petzold Patrik Stridvall int michael cardenas msgs
+ LocalWords:  guiexe init cuiexe lwine lncurses lm lutil ldl wav winmm wrc lcc
- LocalWords:  wireoff msgs wireon app devel cvs ifdef Corel Damyan Ognyanoff IE
+ LocalWords:  dllExamples WindowsExeWindowsDLL WindowsExeWineDLL WineExeWineDLL
- LocalWords:  Gavriel MFC's Wine's VC underdocumented Google fromdos GCCs apps
+ LocalWords:  WineExeWindowsDLL Borland URL's cd distclean DllMain winemain exe
- LocalWords:  fpermissive whereever symlink filesystem tarball RFC linux Urk SP
+ LocalWords:  winedll cdecl WINEbirthDay str WINEfullName WINEbirthday libtool
- LocalWords:  misspoke TWine structs DNO XXX Microsofts occassionaly WineHQ Gav
+ LocalWords:  proost conf LD libwinedll Gouget docs dumpbin ConstString
- LocalWords:  TransGaming alright hairball Jer Visi IMHO MSVC nonexclusive mfc
+ LocalWords:  pWINEfullName LoadLibrary GetProcAddress hiddenWinedll
- LocalWords:  mfc's destructors zombi GPF aplication's InitInstance shapshot rc
- LocalWords:  TNX Bulid afxbld RBLD mfcdll FILEVERSION PRODUCTVERSION BOOL HWND
- LocalWords:  CALLBACK DLGPROC UINT WPARAM LPARAM WINAPI SomeFunction param TEB
- LocalWords:  param TYPEPtr TYPERef struct struct NtCurrentTeb semanticaly obj
- LocalWords:  stdcall obj defines's COM ICOM ret xfn ifdef's ISomeInterfase URL
- LocalWords:  IUnknown MethodName DWORD dwParam LPVOID qthere cplusplus AFXAPI
- LocalWords:  nSize commctrl DTWINE CMONIKER CMonikerFile urlmon AFX OLEDB SYNC
- LocalWords:  DNOWIN DHTML OCX DAO OCC INET RICHEDIT DLONGHANDLES afxcom CIP SW
- LocalWords:  IID CIP IID afxtempl ARG rValue const typename releated rsrc ptr
- LocalWords:  rdynamic wnen libmfc ARGV ARGC didn'n extention iint winMain hins
- LocalWords:  HINSTANCE HINSTANCE LPSTR cdecl splitpath LPCSTR makepath hlib
- LocalWords:  lpszCmdParam hInstance htst hform himag hexe retv LoadLibrary
- LocalWords:  CRTDLL GetProcAddress COMCTL COMDLG dlopen libmxformatslib
- LocalWords:  mxformatslib libmxpaint mxpaint FreeLibrary dlclose