
This is the standalone distribution of Willows Twin Libraries.

If you find bugs in Willows Software Twin Libraries, send reports to 
twin-bugs@willows.com.  To have source extensions and additions added
to the software libraries, send your modifications and updates to 
twin@willows.com.  For additional information about the Willows Twin
libraries, and download the latest versions of the software, contact
http://www.willows.com.

The Willows Twin Libraries are distributed under the GNU Library General
Public License.  See the file COPYING.LIB for copying conditions.

The makefile builds libtwin.so.  You may optionally build libtwin32.so,
or static libraries libtwin.a or libtwin32.a.  The makefile will also
build a library tester, xwin which can execute existing windows 16 
executables.

These are the instructions for doing a source build.
For additional information see the README file in
the makeinclude subdirectory.


Basic Installations to build Willows TWIN libraries
===================================================

1. 	[REQUIRED]

	Configuring the source makefiles for your platform.
	---------------------------------------------------

 	The sources are rooted in a tree based on the version of the
	release, eg. ./twin/3.v.r/..., multiple releases can be kept
	under the ./twin hierarchy.  The environment variable TWINDIR
	can be set to this path, eg. /home/robf/src/twin/3.v.r in for
	example.

	Change to the $TWINDIR directory, and run the ./configure script.

	This script will create three files that will be included by the
	various makefiles.

		./Makefile.config
		./makeinclude/Makefile.rules
		./makeinclude/Makeinclude.config

	This script is generated by the autoconf, and the input file,
	configure.in.

	The script understands the following options:

		--with-win32		to build as a win32 library
		--with-optimization	to build without debug information

	(not yet implemented)
		
		--with-debugger		to use built-in debugger (if possible)
		--with-notrace		to build without tracing

        ====================================================================
	NOTE:  The library is compiled as an  implementation of either 
	the win16 or win32 interfaces.  Support for win16 binary applications
	is provided in a binary interface library that should correctly call
	the twin library you've built, allowing win16 binary applications to
	be executed with the win32 library.  If any differences are noted in
	the behavior of the win32 vs. the win16 library when executing a 16bit
	binary application, it is a bug in th win16 binary interface, and 
	should be reported to me to fix.
	======================================================================
	
2.   	[OPTIONAL (should be done after changing configurations)]

	Verify a clean build environment.
	---------------------------------

		make clean
 
3.   	[REQUIRED]

	Building the libraries.
	-----------------------

	The Willows TWIN libraries are a collection of shared libraries that
	have the equivalent functionality of windows.  The library has been
	broken out into multiple dll's,  (shared libraries), rather than having
	a monolithic library.  The build process will build each of the
	components libraries, in addition to the main library, libtwin.so.

	The component libraries that are built are:
		libcommdlg.so			all functions from COMMDLG.DLL
		libcommctrl.so			all functions from COMMCTRL.DLL
		libshell.so			all functions from SHELL.DLL
		libwinsock.so			all functions from WINSOCK.DLL
		libmmsystem.so			all functions from MMSYSTEM.DLL
		libkeyboard.so			all functions from KEYBOARD.DLL
		libsound.so			all functions from SOUND.DLL
		libddeml.so			all functions from DDEML.DLL
		liblzexpand.so			all functions from LZEXPAND.DLL

	Having these libraries separate will allow them to be developed and
	extended separate from the twin library, and reduce the sizes of the
	libraries that need to be downloaded in the future.

	To build libtwin.so, and the component libraries, and the Willows
	Windows resource compiler, type:

		make 		

	To build the source samples, you can type

		make world

4.	[REQUIRED]

	Run Time Configuration.
	-----------------------

	Create a twin runtime configuration file, in your home directory.
	The following is an example of a configuration file. You can modify
	it to suite your environment.

		[boot]
		control=0x1000
		windows=/willows/twin/windows
		openpath=/willows/bin/win:/willows/bin/demo

	This file is a standard windows .ini file, with 1 required section,
	the [boot] section.  This section allows you to set the following:

		control		This variable controls certain runtime
				configuration switches.  The default setting
				of 0x1000 is useful for running Microsoft
				Office Applications.  For more information
				on this file, see the file ./win/compat.h.
				NOTE: This variable should NOT have to be 	
				modified to run applications, and will not
				normally be used by users.


		windows		This variable points to where the microsoft
				windows directory is located, this is where
				C:\WINDOWS is located, if available.  This
				is where we will search for .ini files, and
				one of the locations we will search when 					running an application from the command line. 	
				It should be the standard unix path to the
				windows directory.  It is also used to find
				the system directory underneath it to find
				and installed windows dll's.

		openpath	This colon separated list is equivalent to
				the PATH variable under windows and unix.
				Since no windows applications will be under
				the unix PATH, this variable allows you to
				set the path to where you keep windows
				executables only.

	See the files:
		./template/readme.twinrc for more information, and file
		./template/sample.twinrc for an example file.

5.	[OPTIONAL]

	Verifying the library.
	----------------------

	The library has a win16 binary emulator, that will load and execute
	win16 applications.  We provide an interpreter for risc CPU's, and
	can run the win16 applications on risc or intel.  The binary emulator
	is called xwin, and is located/built in the ./win directory.  You
	can run the emulator with no arguments, and will be prompted for
	the application to run, or you can type the application as an argument
	to xwin.  Since the libraries are built as shared libraries, you may
	need to configure your systems run-time dynamic linker to be able to
	load the twin shared libraries.  On linux, you can set the environment
	variable LD_LIBRARY_PATH=$(TWINDIR)/win, and export it.  You may 
	need to run the system utility ldconfig, and modify your system's
	ld.so.conf file to include the path to the twin libraries.
	

	./win/xwin	will bring up the common file dialog asking for
			what 16 bit windows executable to run.

			note: if you've built the shared library, libtwin.so,
			be sure to make it available to the run-time linker
			ld.so.
	
	./win/xwin sol.exe or
	./win/xwin sol 
			will run sol.exe.  The ~/.twinrc configuration
			file should have an entry for openpath that points 
			to where the win 16 binaries are kept. 



6.	[OPTIONAL (installation of libraries)]

	Installation of the libraries and executables.
	----------------------------------------------

	We do not provide an installation script to install the libraries 
	on your machine.  You can run:

		 make install INSTALLDIR=<TWINROOT>

	where <TWINROOT> is where you want to keep the Twin files.  The
	TWINROOT will have subdirectories for bin, lib and include. You
	will need to modify the shared library loader setup configured
	in step 5 to account for the new library locations.


7.	[OPTIONAL (tracing binary applications)

	Enabling TRACE output of the debug library.
	-------------------------------------------

	To enable the library to trace api calls made by an application,
	you can use the WIN_OPENLOG variable.  If it is set to a log file, 
	the DEBUG versions of the library will log library trace information 
	to that file. 

		export WIN_OPENLOG=/tmp/log

	you can use "-" as the filename, to log to stdout.

	This file will give very comprehensive information about what is
	called, with its arguments and return values.  This can be invaluable
	in finding out why an application does not work.

8.	[OPTIONAL (source samples)]

	windemo				most basic simple window

	bindemo bindemo2 bn2demo	samples of sources, loading windows 3.x
					binaries...

	cdsdemo				sample of common dialogs

	cliptext			sample of using clipboard to interchange
					to text with X11 server 

	dlgdemo				sample of dialog boxes
	dlldemo				sample of dynamically loading shared 
					libraries, (dll's)
	hlpdemo				sample of launching twinview help viewer
	mdidemo				sample of MDI windows in X11
	msgdemo				sample of messages sent/receive library
	prtdemo				sample of using binary printer interface
	wmfdemo				sample of using windows metafiles

	ctrldemo			win32 demo of common controls
	listview			win32 demo of listview control
	treeview			win32 demo of treeview control
	progbar				win32 demo of progress bar


Source Directory Layout (see the file MANIFEST for specific file information)
=============================================================================

bin:		directory containing source for resource compiler and
		help file viewer.
bmp:		directory containing binary resources, icons, bitmaps, etc.
commctrl:	directory with win32 common controls dll.
commdlg:	directory with common dialogs dll.
configs:	directory with platform configuration files.
debugger:	directory with built-in debugger, for x86 platforms.
dll:		directory with sources to give shared libraries the same
		interfaces as windows DLL's, ie. LibMain, DllEntry...
doc:		directory with supplemental documentation.
include:	directory of public header files.
intp32:		directory with source to x86 interpreter.
makeinclude:	directory with platform independent makefile components.
multimedia:	directory with sources to multimedia libraries.
pal:		directory of platform abstraction layer sources, ie. x11...
readline:	directory with readline for debugger.
samples:	directory of sample sources demonstrating twin libraries.
shell:		directory of windows shell dll.
template:	directory with sample win.ini and ~/.twinrc files.
utilities:	directory of support functions for common controls.
xdos:		directory with dos emulation library.
win:		directory of core Willows Twin Library files.

Alternative Configuration
=========================

	The configure script will allow you to build 1 of 4 different
	configurations.  The alternatives are debug version vs not, and
	win32 vs win16.  The default configuration will be set in the
	file .config, and in the variable TWIN.  It will be of the form:

	TWIN=$(TARGET)$(TWIN_APISIZE)-$(TWINCPU)-$(TWINOPT)

	where TARGET 	     will be one of Linux, hppa, SunOS, Solaris, etc.
	      TWIN_APISIZE   will be empty, or the value 32
	      TWINCPU	     will be X386, sparc, hppa, etc.
	      TWINOPT	     will be DBG, OPT


	A make clean MUST be done afterwards.  The build script shows
	how to build all combinations, automatically, using the setup script.
	
   Copyright (c) 1997, Willows Software Inc.  All rights reserved.
