// vMac README for the Unix/X Window, SVGALib/Linux, and NeXTSTEP ports 
// Port by Michael Hanni (mhanni@sprintmail.com)
// README by Ray Ruvinskiy (rruvin@sprint.ca)

[Make sure to read INSTALL for lots of help on compiling vMac.]

NOTE: Using this software shows your acceptance to the End User License 
	Agreement which was shown to you before downloading vMac. If you
	have not read or accepted it, you are not entitled to use this
        software!!!
	Please read the LICENSE file (located in the same directory as the
	README), make sure you understand it and accept its terms. If you
	don't accept vMac's End User License Agreement, please delete vMac
	from your machine.
	
0. Brief introduction
1. Getting vMac
2. Compiling vMac
3. Installing vMac
4. Running vMac
5. While vMac is running...
6. If you run vMac with WindowMaker...
7. Troubleshooting
9. Documentation
9. How to help...


0. Brief introduction
---------------------

What is vMac? vMac is a free software emulator that emulates the Apple
Macintosh Plus(tm). That means that vMac does not cost anything, and
does not use any hardware. A lot of the Macintosh Plus' functionality is
already implemented in this port, and that includes: 

- 68000 CPU, 68010 CPU, 68020 CPU + 68881 FPU emulation
- 4 MB of RAM
- Keyboard support
- Mouse support
- Floppy support
- HardDisk support (However, vMac will treat all harddisks or partitions 
		       as floppies).
- Sound support (soon!)
- Can run MacOS (System Software) versions up to 7.5.5

Currently, work is being done on IceCube, a new CPU emulator which will
replace UAE's CPU emulator which we use currently, and other stuff :). 

1. Getting vMac
---------------

vMac's homepage is at http://www.vMac.org. If that doesn't work, try
http://leb.net/vmac. If *that* doesn't work, try again another day, the
site is probably down :\. Click on the Download link, fill a few
blanks and download vMac. If you are reading this, however, you have
probably already downloaded vMac. This section is here just in case...

2. Compiling vMac
-----------------

NOTE: SKIP THIS SECTION IF YOU DOWNLOADED THE PRECOMPILED VERSION OF
vMac.

Run:
./configure			If you want the X/NoGUI port.
./configure --enable-motifgui 	If you want the X/MotifGUI port.
				If your Motif or Lesstif libs are in neither
				/usr/X11R6/lib nor /usr/local/lib run:
				LIBS="/where/Lesstif.or.Motif/is" 
				./configure --enable-motifgui
				The same applies for the GTK GUI too.
./configure --with-svga		If you want the Linux/SVGALib port.
./configure --with-nextstep	If you want the NeXTSTEP port.

Other configure command line pramateres:
--enable-scanline		Compile to use Scanline redraw.
--enable-mitshm			Compile to use MITSHM in Scanline redraw - 
				this can improves speed on non-accelerated
				servers, such as the ones that come with 
				MkLinux, and it requires Scanline.

Edit config.h and fiddle with the compile parameters to suite your
needs. The options are well explained in the file. There are really no
options in this file anymore, but still you might want to check it out.

Run "make" with no parameters.

Read the INSTALL file for more details!!!

3. Installing vMac
------------------

Create a separate directory for vMac and copy the vMac binary there. You have 
to have a ROM in a file taken from a real Macintosh Plus in order to use
the emulator.

NOTE: LEGALLY, YOU HAVE THE RIGHT TO USE A MAC ROM _ONLY_ IF YOU OWN A
REAL MAC PLUS. ALSO, YOU MUSTN'T USE YOUR REAL MAC AND HAVE vMac RUNNING
AT THE SAME TIME.

If you do not have a ROM in a file, and you do own a real Macintosh
Plus, read README.rom.

You also need a System Software disk image. System 6.0.8, System 7.0,
and System 7.0.1 are distributed freely and can be downloaded from
Apple's FTP site (ftp://ftp.apple.com), or the vMac Application Site
(VAS - http://www.hostus.com/vas). A considerably large selection of
Macintosh applications and games can also be found on VAS.

Once you've got your ROM and MacOS disk image, edit .vmacrc and modify
it to suite your system (and desires). All options are self explanatory.

If you want to use a real floppy put /dev/fd0 (for example) beside
DrivePathx= (when x = 1, 2, or 3). If you want to use a hard disk or a
partition put /dev/hdb3 (for example) beside DrivePathx=. Of course, you
should indicate the real name of the partition/floppy you want to use.

4. Running vMac
---------------

Launch vMac and if everything is alright, vMac should boot within a
minute. Voila, you can run Macintosh software on your UNIX box.

Please note that starting from version 0.1.9.2, .vmacrc replaces vMac.cfg,
and vmac.PRAM replaces vMac.PRAM. Both files should now be *only* on your home
directory.

Press F12 (or use the GUI, if you compiled vMac with a GUI) to quit the
emulator.

5. While vMac is running...
---------------------------
 
Summary of keyboard interface:
        Ctrl    : This key emulates the Option key on the Mac. 
        Mod1    : This key emulates the Command [or Pretzel] key on the Mac. (*)
        Shift   : This key emulates the Shift key on the Mac.
        CapsLock: This key emulates the CapsLock key on the Mac.
        Keypad  : The gray keypad emulates the Macintosh Plus keypad.
                  The regular [white] keypad acts like under Num-Lock.
        F12     : This key makes vMac quit

(*) You can change Mod1's keysyms using xmodmap or any other xmodmap 
    user interface, such as xkeycaps. Usually, Alt_L and Alt_R are mapped
    to Mod1.

6. If you run vMac with WindowMaker...
--------------------------------------

If you do not know what WindowMaker is, skip this section. If you want
to know what WindowMaker is, go to http://www.windowmaker.org.

If you use WindowMaker, you might want to dock vMac. It is possible. You
just have make sure .vmacrc (vMac's configuration file) is in your home
directory, and that you have indicated the full paths to the ROM and disk
images. Then you can dock vMac by launching it and dragging its app icon
to the dock.

7. Troubleshooting
------------------

Look at the Troubleshooting section in the INSTALL file. This section
currently deals with very elementary stuff. Hopefully (or then again,
maybe not) it will be expanded in the future.

A) When vMac starts, a floppy with a question mark on it appears - the
   Mac can't find your disk image/parition/floppy. Double check the path.

B) When vMac starts, a floppy with an X on it appears - the Mac can't
   boot off your floppy/disk image/partition.

C) It takes longer for vMac to boot when I run it with 4 MB RAM than
   when I run it with 1 MB of RAM - this is natural. It takes time to
   check for all that RAM.

D) MacOS 7.6 and higher won't boot! - MacOS version 7.6 and higher don't even
   work on a real Macintosh Plus. Downgrade...

E) vMac is running incredibly slowly with MacOS x.x.x - You might have a
   slow machine. You might try to remove extensions and control panels
   from System Folder:Extensions and/or System Folder:Control Panels.
   You might not have enough RAM on your machine. You might want to try to
   downgrade your MacOS version. You may try to recompile vMac to emulate a
   68000 CPU or use the 68000 binary if you use the 68020 one. If you use
   SVGALib port you may try to increase the frame rate (the video quality 
   will be worse though). You may also try fiddling with the
   NumInstrucions value in .vmacrc (amount of instructions per event).

F) When I try to boot System 7 or higher, the Mac writes something like
   "You need more RAM to boot this version of the System Software" - 
   tell vMac to emulate more RAM.

G) My 800 KB floppy won't work - 800 KB floppies can't be read by regular
   PC floppy controllers. It's impossible. If you insist on using 800 KB
   floppies with vMac you could try getting Catweasel (another floppy
   controller) which will allow your PC to read 800 KB floppies.

H) In the SVGALib port, the mouse doesn't work if it's in MouseSystems mode -
   Currently it just doesn't work. Switch it back to Microsoft mode :-).

I) The System 7.0.1/System 7.1 disk image I downloaded from VAS doesn't work - 
   Some people have problems downloading from VAS. Try downloading a couple of
   times. If you still don't succeed, there's nothing we can do so, stop 
   e-mailing port authors about it! :-)

To get help with any other problem, e-mail the port author.

8. Documentation
----------------

The documentation for this port of vMac consists of this README, the 
INSTALL file, the LICENSE file and a man page (vmac.1.gz).

To view the man page gunzip it, and put it in either /usr/man/cat1 or
/usr/man/preformat/cat1. Then in order to view it, run "man vmac". If those
directories do not exist, do not create them; there's no point to it. For now,
you will still be able view the man page if you have less by running "less vmac.1".

The Official vMac FAQ is at http://members.aol.com/william234.

Please read *all* documentation before e-mailing the port auhtor with questions.

9. How to help...
-----------------

If you'd like to help, please e-mail the port author you want to help to. 
The e-mail addresses of porters are located on vMac's site 
(http://www.vMac.org), in the "Developers" section (login as "Guest"), in
the Port Roster. We appreciate all help we can get so if you are
able/willing to donate some of your time, we'll probably find something 
for you to do.
