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

1.0 Directory Source Layout

The twin source tree consists of all the sources and makefiles required
to build the many libraries that comprise the twin software.  Most of the
shared libraries are self contained in their own directories.  The only
dependency on the twin software is based on the environment variable
TWINDIR.  It is probably desirable to maintain the directory hierarchy,
and all of the separate tar files for the various components use it.


2.0 Configure and autoconf

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


--enable-optimization         build optimized version of libraries"
--enable-win16                build win16 version of libraries"
--enable-debugger             enable internal debugger "
--enable-bin32                enable win32 binary support libraries"
--with-x                use the X Window System"

        ====================================================================
	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.
