Willows TWIN APIW Frequently Asked Questions version 3.0 - May 2, 1997 Intro This is the latest edition of the Willows TWIN FAQ. This will be posted every two weeks to our mailing list, twinusers@willows.com. This will include additional information about installing, configuring and running windows applications with our binary emulator. Additionally, it will include what programs have been tested, and what the current status of those programs are. Much of the information contained here will be put onto our ftp site, in the doc directory, and referenced in future versions of this faq. I have included it here to provide as much information as I can, to get one started using the Willows Twin Libraries. =============================================================================== Table of Contents Section 1: General Information 1.1 What are the Willows Twin Libraries? 1.2 What is the LGPL? 1.3 What is the availability of the sources? 1.4 What resources are available to help use Willows Twin? Section 2: How do I need to run Willows TWIN Software? 2.1 Do I need Microsoft Windows installed to run? 2.2 What platforms do you support? Section 3: How do I configure Willows TWIN to run binary applications? 3.1 Which files do I need to configure to run xwin? 3.2 What do I need to do to run the Willows TWIN Binary Emulator? 3.3 How do I run winword? 3.4 How can I access executables on the floppy disk? 3.5 What existing win32 applications run? (NONE, at this time) Section 4: What can I do with the sources? 4.1 Building either 16 or 32 bit, debug or optimized libraries. 4.2 Building the win16 emulator. 4.3 Building the resource compiler. 4.4 Building the sample sources. 4.5 Building the TwinHelp Help File Viewer. 4.6 Building the Twin Program Manager. Section 5: What programs work with Willows TWIN Binary Emulator? 5.1 Windows Accessories 5.2 Microsoft Windows Games 5.3 Microsoft Windows Office Section 6: How do I use the builtin debugger? Section 7: What are the source porting issues involved with Willows TWIN? Section 8: Functionality? 8.1 Does Twin support OLE? 8.2 Does Twin support Windows95/NT platforms? 8.3 What does binary emulation buy you? 8.4 Can Willows Twin Cut and Paste to the X Clipboard? 8.5 What additional Windows Libraries are supported by Willows Twin? common controls, common dialogs? shell? registration database? 8.6 What about printing? Printer fonts? Print Drivers? 8.7 What about Window fonts? Font API's, truetype, etc. 8.8 What support does Willows Twin provide for existing window applications and binaries? Does Willows support existing third party intel DLL's? 8.9: What about MFC? Section 9: Troubleshooting Q&A =============================================================================== Section 1: General Information 1.1 What exactly are the Willows Twin Libraries? Willows Twin Libraries are a cross platform implementation of the Windows API's. It is available to support both win 3.x 16bit interface as well as the win32 32bit interface. As far as this software is concerned, we are a cross between source level products such as Mainsoft and Bristol, and the binary software efforts such as Wabi, Insignia Solutions and wine. Twin has three notable features: 1) Runs on all major Unix platforms, not just intel. 2) Twin is not just a Unix solution, Twin supports several operating systems, and several different graphics systems. 3) Supports intel code execution even on risc platforms, through cpu emulation, allowing print drivers, and third party dll's to run. The Willows Twin Libraries come in two parts, the first the platform independent Windows compatible libraries, and the second the platform dependent interface layer. The libraries are available in either the traditional archive library format as well as a dynamically loadable shared libraries. 1.2 What are the license restrictions on the Willows Twin Libraries? The Willows Twin Libraries are licensed under the GNU Library GPL, v2. This means you get the sources for the complete library, and all tools necessary to rebuild the libraries. 1.3: What is the availability of the sources? The software is available from http://www.willows.com. We anticipate that it will be mirrored to several sites very soon. The software is being released under the GNU Library General Public License, (LGPL), in hopes that others will find it useful, and make contributions to it. 1.4 What resources are available to help use Willows Twin? Two mailing lists are being setup, one for developer oriented issues, the other for twin user issues. For information about supporting the library on other platforms, send mail to twin@willows.com. Please see http://www.willows.com to join either of those mailing lists, or to get further information. =============================================================================== Section 2: How do I install Willows TWIN Software? 2.1 Do I need Microsoft Windows installed to run? No, you do not need Microsoft Windows installed. We can use, but do not require any components for our library. Applications that you wish to run may require additional components that we do not support, which may require some components form Microsoft Windows. 2.2 What platforms do you support? You can visit our WEB site to get an updated list, as of this writing, we support the following platforms: 1. Dec ALPHA OSF/1 7. Sun Solaris 2.4 2. IBM AIX 8. Sun SunOS 4.1.3 3. HP HP/UX 10.0 9. MIPS ABI Systems, (SGI) 4. SCO OpenDesktop 10. Macintosh PowerMac 5. Unixware 6. Linux ============================================================================ Section 3: How do I configure Willows TWIN to run binary applications? 3.1 Which files do I need to configure to run xwin? The key to configuring Willows TWIN software is to setup a twin configuration file, and make it accessible to xwin. The rules for finding the file are 1) use the file designated by the environment variable TWINRC, 2) use the file twinrc in the current directory, and 3) use the file .twinrc in the your home directory. For this discussion, I have setup my own private twinrc file in my home directory. The file contains the following lines... [boot] control=0x1001 windows=/windows openpath=/willows/bin/win:/willows/bin/demo:/dos/windows:/willows/winword [xdos] C:=/ D:=/willows/bin In this twinrc file, control set to 0x1001 means to print verbose xwin startup information, (the 1 bit), and do NOT map the current drive to a dos logical drive, (the 0x1000 bit). This is important in that some MS applications expect to be in a specific location. The second line, windows=/windows is the windows directory that I will use when running xwin. This is where common help files, and shared data will exist, and can be shared by all users. It is also where the 'system' directory is located which will contain all shared dll's. The third line, openpath, says where to look to find windows executables, for instance if you run 'xwin sol', this would allow us to find sol.exe in the /dos/windows directory. In the next section,[xdos], I have configured the dos emulation library to map drive C: to the root directory, and drive D: to the /willows/bin directory. It is important to note that if I have, for instance, winword in a dos partition, it would be in the /dos/winword directory, or, C:\dos\winword, while it was installed as C:/winword. This is a major issue, that causes most of the configuration issues, specifically, because the registration database thinks its in one place while it is in another. For willows, I copy the win.ini file from windows and the setup.reg file from /dos/winword, and put them in my windows directory, /windows. (Note: I also created the directory /windows/system, which looks to a binary application as C:\windows\system. The next file that needs to be available, is the win.ini file. We need to set an entry to disable truetype fonts, I have... # This section is used by print drivers, specifically, pscript.drv. It # will try to use truetype fonts, and fail, if this is not set to 0. # [TrueType] TTEnable=0 Otherwise, the win.ini file is exactly what it was under windows, including printer setup etc. Setup.reg The setup.reg file is an ascii version of what we load into the registration database. We keep it in the setup.reg file, and load it as needed. You can start with the setup.reg file from either winword or excel to bootstrap the initial file. This file needs to be located in the windows directory. The single most important aspect of the setup.reg file is that references to any application that are in the file, eg. winword and excel,(or powerpoint or any other applications you have) to reflect their 'logical' locations. If they were installed in one location, and now are in another, the setup.reg file must reflect the correct location. This is very important, and will lead to 'NOT ENOUGH MEMORY' errors if not done. Windows and System Directory In my windows directory, I have the following files... > ls /windows setup.reg system/ win.ini In my system directory, I have the following files... > ls /windows/system compobj.dll@ ole2disp.dll@ sdm.dll@ typelib.dll@ ole2.dll@ ole2nls.dll@ storage.dll@ w32sys.dll@ NOTE! The are all symbolically linked to the 'real' versions in my windows system directory, /dos/windows/system. 3.2 What do I need to do to run the Willows TWIN Binary Emulator? The essential parts to run the Willows Twin Emulator, xwin, are a version of xwin for your platform, the shared library libtwin.so, in either the debug or optimized flavors. As described in the Getting Started Guide, you may need to configure your system to run xwin by setting up the dynamic loader, in the case of linux, you need to make sure that /lib/ld.so is configured correctly. I have configured ld.so to recognize where libtwin.so actually lives, but on most machines, you can also use the environment variable LD_LIBRARY_PATH as a colon separated list of directories that ld.so should search to find dynamic libraries. Xwin can be launched without any command line arguments, in which case it will put up a file open dialog box, asking you to select which windows executable you want to run. 3.3 How do I run winword? I have winword installed in /willows/winword, and have this directory in my openpath list in my .twinrc file. I can now type > xwin winword Windows Directory: /windows System Directory: /windows/system X11 Configuration -------------------- Display: ncd:0.0 Vendor: Network Computing Devices Inc. Mode: Syncronous Hostname: t4900ct XDOS Configuration ------------------ C: / (native file system) LASTDRIVE = C DRIVES = 1 BOOTDRIVE = C ROOTDRIVE = 3 MEMORY = 640Kb EXTENDED = 15360Kb FILES = 100 Twin Debugger enabled... LoadModule: /winword/winword.exe LoadModule: /winword/wwintl.dll LoadModule: /windows/system/sdm.dll LoadModule: /windows/system/storage.dll LoadModule: /windows/system/compobj.dll LoadModule: /windows/system/w32sys.dll LoadModule: /windows/system/ole2.dll LoadModule: /windows/system/ole2disp.dll LoadModule: /windows/system/ole2nls.dll *** Failed to load library pscript.drv*** The last line failed to load the pscript.drv driver, because I had not copied it to my /windows directory. 3.4 How can I access executables on the floppy disk? In the twinrc configuration file, if you set the following line, we can access the floppy disk and read files from it. A:=/dev/fd0 You must have read permission, and the name for your floppy driver may differ. Any file access to files on the floppy, can be done using a:\setup.exe for example. (Note: to access the floppy from the shell, quote the \) The following will have the emulator run the setup program from the floppy. $ xwin a:\\setup.exe 3.5 What win32 applications run? NONE! =============================================================================== Section 4: What can I do with the sources? 4.1 Building either 16 or 32 bit, debug or optimized libraries. See the README file. 4.2 Building the win16 emulator. See the README file. 4.3 Building the resource compiler. See the README file. 4.4 Building the sample sources. 4.5 Building the TwinHelp Help File Viewer. 4.6 Building the Twin Program Manager. =============================================================================== Section 5: What programs work with Willows TWIN Binary Emulator? The following is the current state of xwin, based on the Willows TWIN library. I use the numeric system of 1-5 to rate the applications, 1 means fails completely, 5 means works completely. The difference between 2, 3 and 4 are the degrees of the problems that remain. Software Category Status Comments 5.1 Windows Accessories ------------------- calc.exe* 5 calendar.exe* 5 cardfile.exe* 5 charmap.exe* 5 clipbrd.exe* 5 clock.exe* 5 control.exe* 4 notepad.exe* 5 pbrush.exe* 5 printman.exe* 1 progman.exe* 1 missing some undocumented api's recorder.exe* - regedit.exe* 4 does not update setup.reg file sol.exe* 5 taskman.exe* 5 terminal.exe* 5 vershow.exe* 5 winfile.exe* 1 missing some undocumented api's winhelp.exe* 5 wintutor.exe* - winver.exe* 5 write.exe* 4 some minor font problems 5.2 Microsoft Windows Games ----------------------- pegged.exe* 5 cruel.exe* 5 reversi.exe* 5 freecell.exe* 5 winmine.exe* 5 golf.exe* 5 mshearts.exe* 5 tic.exe* 5 tp.exe* 5 5.3 Microsoft Windows Office ---------------------------- There is currently NO support for win32 binaries. The following applies only to windows 3.x applications. For the following applications, we have not rigorously tested them, so can only put out comments about the state of the application. winword.exe comes up runs, loads/saves files, enter data, etc. Have exercised most menu options, except those dealing with ole. Have some font problems and printing is erratic. excel4.exe excel5.exe comes up runs, loads/saves files, enter data, etc. Have exercised most menu options, except those dealing with ole. powerpnt.exe comes up runs, loads/saves files, enter data, etc. Have exercised most menu options, except those dealing with ole. project.exe comes up runs, loads/saves files, enter data, etc. Have exercised some menu options. access.exe currently does not come up at all, but we have had it come up and exercised some menu options. Have loaded a database successfully, but could not execute many functions. =============================================================================== 6.0 How do I use the built-in debugger? 6.1 See the new document doc/debugger.1 =============================================================================== Section 7: What are the source porting issues involved with Willows TWIN? 1 Do NOT define STRICT. It current includes some 16 bit definitions that clash with our 32 bit definitions. 2 Structure Packing. 2.1 If available, do not use Pragma PACK on risc platforms. The structure elements should be double word aligned, or you will get memory faults. 2.2 Be cautious of assertions of the type if (! sizeof(struct something) == CONSTANT) The sizes of structures have probably grown to accomodate 32 bit longs and ints. 3 Pointer Alignment. Make sure to have double word aligned pointers. Also byte stream data that contains packed structures must be extracted byte by byte, do not cast odd addresses to a pointer to a larger object. 4 Big/Little Endian. The library is written native to the target platform. Binary data should not be assumed to be Intel Format. A portable set of routines should be used to extract data when it is available across multiple platforms. 5 VarArgs. Use caution with variable argument lists that may not be portable, or assume the incorrect size of the underlying data. 6 ANSI C++ Comments. You cannot use // style comments on normal C code. Use the dtu/dos2unix utilities to move sources across, giving a cleaner resulting source file. 7 DLL Shared Library. This version of the Willows Library is statically linked to each application. If multiple DLL's are used, they should all bne linked into a single monolithic library. 8 Name Space Collision. We do use some names that may be available to applications. We are removing these from the library. ============================================================================= Section 8: Functionality? 8.1 Does Twin provide full OLE 2.0 support? No. We started, and went down the design path, of a OLE 1.x implementation using the OLE 2.x interface. The idea is that we could have an OLE 2.x application link to another application, but think that it is only OLE 1.x compliant. Both applications proceed as if they were OLE 1.x enabled, even though one or both might actually be OLE 2.x enabled. 8.2 Does twin support the Win32 platform? The libraries do compile and build under Microsoft Visual C. We link that library to the X11 Client Libraries, and produced a library that could be linked to Windows application, instead of the default USER, KERNEL, GDI. This application then runs on Windows95/NT, but can display on any X11 compatible system. This is meant as a first step at allowing developers to compile and develop on windows, but target any platform that supports the Willows Twin Libraries. The plan is first compile and link on Windows, then re-link for X11, then re-compile and re-link for the alternative platform. With the recent availability of the GNU C compiler on Win32, this will allow easy and flexible cross platform development with native performance, using the Windows API as the basis of cross-platform applications. 8.3 What does binary emulation buy you? A distinguishing feature of the Twin Libraries is the support for both source and binaries with one shared library. The cpu emulation code is 'built-in' and allows existing binaries to execute even on non-intel cpu's. We have included in the library many of the standard PC run-time library calls, to aid in porting applications to multiple platforms. A ported application, can actually access files using the syntax: _lopen("a:\autoexec.bat",0); The BinaryInterface Library contains all the support for Windows 3.x binaries. This includes a loader, to load .exe, .dll and .drv code, a hook into the XDOS Library for DOS support, a DPMI Module to implement support for DOS Protected Memory Model, and finally, an extensible thunking layer to switch between binary mode and native mode. We believe that our solution is 1) platform independent, the same code runs on intel and risc, 2) superior to the Universal Thunk that Microsoft uses, in that it is also extensible to support Windows 32[cs], and user provided thunks. The switch on an intel platform from running in 16bit space to 32bit space is very quick, and can range from just a few dozen assembly instructions, to hundreds to handle more complex transitions. As far as defect-prone, from a purely software bug fixing ratio, the library has over 40 times the amount of code, but over 100 times the number of bugs. An average thunk has on the average about 10-20 lines of C code, with a common assembler gate of about 20 instructions. All issues of addressing, and byte order are handled in this layer, as the library handles only native addressing and pointers. There are three reasons why we support this dual execution mode: 1) Access to a wide range of applications to test the library. As a way to get applications to test the library. We are currently running Microsoft Office Applications, Word, Excel and Project. These are the best ways for us to verify the library, other than to use small 100 line programs that don't reflect what developers really do. 2) Access to a wide range of print drivers. We realized early on that we could not write enough printer drivers for the world to test, so we wrote 2. The first was our own, roll your own postscript printer driver, the the second is our universal binary driver, which should run with any printer driver that works for Windows 3.x. A binary printer driver interfaces to our library just like any other Windows DLL, and is presented with the same run time environment that it has under Windows. 3) Third party DLL's. We saw early on in porting some applications, that they were dependent on third party VBX, and custom controls, that they only had in binary form, and that the vendor is/was not likely to port in a reasonable time, hence we should. 8.4 Can Willows Twin Cut and Paste to the X Clipboard? Willows Twin supports CF_TEXT format data, (standard text) cutting and pasting to and from the X clipboard. Applications may put to the clipboard many more formats, that other applications can use. 8.5 What additional Windows Libraries are supported by Willows Twin? The Twin Library supports commdlg.dll functions, with all the user options for customization etc. This includes OpenFile/Savefile, ChooseFont, ChooseColor, Find/Replace.... The 32bit version, supports the common controls. The only major common control NOT supported at this time is the Rich-Text Edit control. The Twin library does support the shell.dll interfaces, including those to the registration database, although the data is not currently persistent from one invocation to the next. 8.6 What about printing? Printer fonts? Print Drivers? Printing is done precisely as under Windows. Our print driver uses the DDK interface to printers, including escapes, printer dialogs, etc. Our extension to the printing system is that the output of a printer.drv is captured by the Twin Library, and via settings in system.ini, and then re-directed, printed, saved to a file, spooled to the system printer etc. 8.7 What about Window fonts? Font API's, truetype, etc. Window Font API, CreateFont..., GetTextMetrics..., EnumFont... These API's are supported just as they are in Windows. We take the font request and use a font search algorithm that utilises font aliasing, height and character attributes, bold, italic..., and generates a platform dependent font request. On X11, this turns into load/query font calls, while on a Mac, turns into TrueType font requests. The additional TrueType specific API's, getabcchar, GetOutline... are only supported if a TrueType font server is running, and you have the same ability to paint the characters as you have with Windows. The Font Metric requests are likewise handled in the same fashion, with the Twin Library returning the appropriate values for a given request, so that any drawing dependent on those measurements will be correct. 8.8 What support does Willows Twin provide for existing window applications and binaries? Does Willows support existing third party intel DLL's? Willows Twin provides a binary execution environment layer that sits above our Willows Twin API's. This binary execution environment allows us to load Window binaries (.exe, .dll and .drv's), and execute them directly, (or with an interpreter for risc platforms). 8.9: What about MFC? MFC, we've taken the source for MFC, that comes with Visual C++, and compiled it, after serious massaging of Microsoft specific constructs. With it, we were able to compile and run the sample code using our Libraries. The sample C++, MFC code runs natively, and can do dynamic linking ala LoadLibrary(), of an intel DLL, (the meter.dll sample source), the transition from native C++ ported code to intel 16bit code was completely transparent to the application, it did GetProcAddress, etc. and did a straight call to the address returned, without doing any fancy data conversion. Using the GNU C++ compilers, we have been able to support applications using MFC 4.x. ============================================================================= Section 9: Troubleshooting Q&A 1) does xwin work without your printer driver installed? Remove the printer specification from your win.ini file. Applications will still run, but not be able to print. 2) have you modified all entries in setup.reg to reflect the new location of where the files are? 3) have you added the [truetype] line to your win.ini file? 4) does xwin run with no arguments? This is key to make sure that Willows TWIN Shared Library can be found and loaded. 5) are you modifying and using the right twin configuration file, ie. there is not a twinrc file in the directory where your apps reside? 6) there is a /tmp directory, and you have C: mapped to /? 7) does openpath have : separator? =============================================================================