*********************************************************************
****************************** UQLX *********************************
*********************************************************************

This is an alpha version of the QL emulator for Unix

The REAL DOCUMENTATION  containing all INSTALLATION hints is now in 
the 'docs' subdirectory.
Type
	'make docs'

to build the files 'uqlx.dvi' and 'uqlx.info'. View the documentation
either by
	'cd docs;xdvi uqlx'
or in Emacs
	c-u c-h i  uqlx.info
You can also html-ise the documentation, try
	'cd docs; texi2html uqlx.texi; netscape uqlx_toc.html'

An HTML version of the documentation can be found in the WWW
at : http://www.geocities.com/SiliconValley/Bay/2602/uqlx_main.html

The rest of the document is the OLD README, just in case you have
some trouble reading the documentation.



COMPILING
=========

Unpack the acrhive in a fresh directory, make sure "make" points to
GNU make ('which make'; gmake is often alias of GNU make) and invoke
make. Something like this might work

>mkdir uqlx
>cd uqlx
>unzip ../uqlx
>make

Many machines/OS are supported by the Makefile but even than you might need
to add some libraries or includes to the path.
If your OS isn't recognised make attempts to generate a version with
a limited functionality that usually compiles well; you may later try to
get the more advanced functionality like serial ports and VM_SCR.

If you still have problems compiling it, you may need to specify NO_GETOPT
or NO_MEMOVE as described below in "Build Options"


INSTALL
=======

Now you should copy the .uqlxrc file to your $HOME and customise it for your
configuration. "options.me" gives some more hints about this, read it eg using
nroff -me options.me


Build Options
----------------

Are controlled mostly by the BUILDFLAGS in Makefile. When you change the Makefile you should probably also 

> make clean

to avoid trouble

If you run LINUX you will probably wish to enable the serial and pty drivers
provided by Jonathan Hudson,
the Makefile. 

- SERIAL enables ser and pty drivers for Linux. On other OS's you may need
  to define -DNO_FIONREAD if FIONREAD is not supported.

- NEWSERIAL
- NEWPTY  somewhat changed serial ports, this is required to get them work
  with minerva ROMs

- XAW use Xt/Athena Frame around UQLX main window. The problems with SUNs OpenWindow
  now disappeared. Requires change of the WINOBJS=, WINSRCS= and XAWLIBS= libs lines 
  in the Makefile and a complete recompile

- DO_GRAB usefull to keep window managers from snatching away alt- and ctrl- key
  combinations. Disables ALL WM hotkeys - you must move the pointer out of the
  QL window to have the WM hotkey available again.
  Currently this is the default behaviour.

- SH_MEM use MIT Shared memory to speed up screen conversion. Obviously this works 
  only for local screens. While most Xserver/Xlib combinations are clever enough to 
  figure this out, other need to disable SH_MEM.
  This X extension is not very well standartised and therefore good for all
  kinds of trouble..

- VM_SCR use virtual memory tricks to detect screen changes, this is recommended
  with SYSV systems that support it - your compiler will complain if itisn't. 
  Strangely the XAW appears to use up most of the speed advantage...

- BSD some BSD related hacks, avoids compile time errors in pty.c
  SunOS<5 needs this as well as the next 2 defines..

- NO_MEMMOVE if memmove() is missing, try this

- NO_GETOPT  .. getopt() ....

Debuging flags:
---------------
rarely usefull

- VTIME simulate a virtual time/interrupts by instruction counting, usefull to get
  exactly reproducible results with TRACE

- TRACE output loads of information for each instruction executed. Regions of code
  to be traced must be specified in trace.c.

- DEBUG_ROM enable breakpoints in ROM, also enables many sorts of beautifull 
  crashes


Exotic Systems
--------------

If you use some more exotic computer there is a chance that you will need
to add some #defines in QL68000.h

On big-endian platforms you may need to 
#define BIG_ENDIAN
#define HOST_ALIGN 'num'	try num=2 and use 4 of it crashes


File Access
===========

Both QDOS diskimages and the UNIX host filesystem can be accessed,
for details see the .uqlxrc file. (note that "native" means QDOS native
disk image in this)

Actually it IS possible to use a real disk instead of the disk image, but 
for now this has many disadvantages.

The Unix FS is accessed case-sensitive which can be a real pain with
SuperBasic, but works quite good with most other software. 
On the other hand it already knows dataspace and directories.
Well don't try QPAC2/files expand tree - it tries to expand '..'
as well, recursively of course.

Floppy-Diskimages can be taken by 'dd'. On SUN the exact syntax is
dd if=/dev/rfd0 of=DiskImagename
Man pages of dd or tar usually give good hints about the floppy names, however 
one possible complication is Volume Management, refer to 'man vold'.


QDOS file headers
=================

data -type and -space work on all devices, the difficult part is to get transfer
them from your QL media to UQLX. You can use either QL diskimages accessed as flp1_
and copy the files to mdv1_ or elsewhere, or install unzip using the same procedure
or SEXEC.

Jonathan Hudson has developed a small script to set the headers from the
unix shell. It is in the utils subdirectory, I have called it xheader, 
documentation is inside the script
You may need to adapt the first line (#!/...) to point to your perl
interpreter.

Keyboard
========

usually this should work quite well, even including non-englich keyboards with exotic 
layouts, however ther are a few points to note:

	- on Keyboards where the cursor is only in the keypad, keys like
	  shift-ctrl-left will often work only if NumLock is activated.
	  This will require some very clever algorithm to fix.

	- on keyboards without "real" meta-keys, the alt-keys are usually
	  heavilly used by the window manager, resulting very often in unpleasant
	  surprises. Use -DDO_GRAB compile option for workaround



Misc
=====

the file ql.html contains a list of QL related internet starting points
plus some of my internet know-how.


Benchmarks
==========

If you get it running I would be interested in the following little benchmarks.
Please select "F1" from startup menu as this affects the speed of the second one.

B1:
10 t=date
20 for i=1 to 2000:a=sin(1)
30 print date-t

and B2:
10 t=date
15 cls
20 for i=1 to 1000:print i,
30 print date-t


The Benchmarks also show how much effect some of the optimisations
show; the old value is taken without the -DFASTLOOP optimisation.


BENCHMARKS: 		| B1			| B2
Machine			| old value		| old value
			|	new result	|	new result
---------------------------------------------------------------------
SPARC on remote 	|  4s    		| 9-15s
  display		|			|
---------------------------------------------------------------------
Linux/i486DX-33,8MB,64k	| 28s			| 71s
memory increased to 20MB|	20s		|	49s
---------------------------------------------------------------------
Linux/486DX2-66,12MB,	| 19s			| 35s
no L2 cache		|			|
---------------------------------------------------------------------
Linux/P133/32Mb/S3 	|  4s			| 9s
Trio/1G Scsi		|			|
---------------------------------------------------------------------
Linux/Cyrix 686 PR166	|  3.1s			|  6.3s
			|	2.7		|	6.5s
---------------------------------------------------------------------
Linux AMD 5x86 P75 UMC	|			|
256KB Cache, 16 MB 	|	8s		|	19s
---------------------------------------------------------------------
HP-9000/715-65/64MB	|  7s			| 15s  
---------------------------------------------------------------------
SGI MIPS R5000/64MB	|  4s			|  8s
---------------------------------------------------------------------

