
	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, twin-users@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 ont 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?

=============================================================================
