XRoar - a Dragon/Tandy Coco emulator
Copyright 2003-2021 Ciaran Anscomb <xroar@6809.org.uk>

XRoar is a Dragon emulator that runs on a wide variety of platforms.
Due to hardware similarities, XRoar also emulates the Tandy Colour
Computer (CoCo) models 1 & 2.  Some features are:

   * Emulates Dragon 32, Dragon 64, Dragon 200-E, Tandy CoCo 1 & 2, and
     compatibles.
   * Emulates DragonDOS, Delta and RSDOS disk systems.
   * Emulates the Orchestra 90-CC stereo sound cartridge.
   * Supports both raw and translated keyboard modes.
   * Reads and writes virtual cassettes (compact '.cas' files and audio
     files).
   * Reads and writes VDK, JVC and DMK format virtual floppy diskettes.
   * Saves and loads machine snapshots.
   * Provides a GDB target for remote debugging.
   * Games Master Cartridge support, including SN76489 sound chip.
   * MOOH RAM expansion + SPI support.
   * Glenside IDE support.

   XRoar is easily built from source under Linux, and binary packages
are provided for Mac OS X and Windows.

   XRoar can also be compiled to WebAssembly, and redistributing it in
this form may provide a convenient way for users to run your Dragon
software.  See XRoar Online (https://www.6809.org.uk/xroar/online/) for
an example.

   XRoar is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.

   XRoar is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

   You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

   This README contains extracts from the manual.  Binary packages
contain the full manual as a PDF, which is also available from the XRoar
home page (https://www.6809.org.uk/xroar/).


Getting started
***************

Installation & running
======================

Pre-built binary packages are available from the XRoar home page
(https://www.6809.org.uk/xroar/).  If one is not available for your
architecture, you will need to build from source.  XRoar should build
and run on any POSIX-like system for which SDL version 2 is available.

   You will also need BASIC ROM images--binary dumps of the firmware
from an original machine.  The originals were part-written by Microsoft,
so they are not distributed in the XRoar packages.

Mac OS X binary package
-----------------------

Download and unzip the appropriate '.zip' distribution for your system.
Drag the application icon to '/Applications/'.

   For troubleshooting or testing options, it's often a good idea to run
from the command line, but application packages don't make that trivial.
A symbolic link to somewhere in your 'PATH' is all that's required.
e.g.:

     $ sudo ln -s /Applications/XRoar.app/Contents/MacOS/xroar \
             /usr/local/bin/xroar

   After this, you can start the emulator by simply typing 'xroar'
followed by any command line options.

   ROM images should be placed in a directory you create under your
'HOME' named '~/Library/XRoar/roms/' (not the system directory,
'/Library/').  Name any configuration file you create
'~/Library/XRoar/xroar.conf'.

   The Mac OS X build provides a menu for access to certain features,
and often accepts the more familiar 'Command'+KEY in place of the
'Ctrl'+KEY shortcuts listed in this manual.

Windows binary package
----------------------

Download and unzip the appropriate '.zip' distribution for your system.

   The easiest way forward is to simply put ROM images into the
directory created when you unzip the distribution, and then run the
'.exe' straight from there.  You can also put any configuration file
('xroar.conf') here.

   However, if you want to avoid having to move files around each time
you upgrade, you can create 'Documents/XRoar' to contain your
configuration file, and a subdirectory of that, 'Documents/XRoar/roms'
for ROM images.

   Note when troubleshooting that the logging from the Windows binary is
probably only going to be visible if you run it with the '-C' option
(must be the first option) to allocate a console.

   The Windows build provides menu-based access to certain features.


Building from source
====================

Dependencies
------------

If there is no binary package for your system, you will have to build
from source.  XRoar can use various backend toolkits, and you will need
to ensure you have their development files installed.  If you're using
Debian, this can (at the time of writing) be achieved with the following
simple command:

     $ sudo apt install build-essential libsndfile1-dev libgtk2.0-dev \
             libgtkglext1-dev libasound2-dev

   Under Mac OS X, first be sure to install Apple's Xcode
(https://developer.apple.com/xcode/) package.  The easiest way to then
ensure you have XRoar's dependencies available is to use a system like
Homebrew (https://brew.sh/) or MacPorts (http://www.macports.org/).  For
Homebrew, the following command will install the required dependencies:

     $ brew install libsndfile sdl2

   Otherwise, you'll have to do a bit of platform-specific research to
ensure you have all the dependencies for a full build:

   GTK+ (http://www.gtk.org/), the GIMP toolkit, provides the most
full-featured user interface.  It is only usable as such if you also
have GtkGlExt (http://projects.gnome.org/gtkglext/), an OpenGL extension
used to provide video output.  Otherwise, it can provide a file
requester for use by other user interfaces.

   SDL (http://www.libsdl.org/), Simple Directmedia Layer, provides a
slightly more basic user experience.  Menus are added using native code
under Mac OS X and Windows; any other target using SDL will support only
keyboard shortcuts.  Unless you are building for Linux, SDL is required
to use joysticks.  Version 2 required.

   POSIX Regular Expressions are used in option parsing, so TRE
(https://laurikari.net/tre/about/) is required on non-POSIX platforms
(e.g.  Windows).

   Other supported audio APIs: OSS, ALSA, PulseAudio, CoreAudio.  Some
other options are still in the code base, but have not been tested in a
while.

   libsndfile (http://www.mega-nerd.com/libsndfile/) is recommended to
enable support for using audio files as cassette images.

Compilation
-----------

Once you have the dependencies, building XRoar follows a familiar
procedure:

     $ gzip -dc xroar-0.37.1.tar.gz | tar xvf -
     $ cd xroar-0.37.1
     $ ./configure
     $ make
     $ sudo make install

   The 'configure' script has a lot of options guiding what it tests
for, specifying cross-compilation, changing the install path, etc.  List
them all with the '--help' option.

   By default, 'configure' will set up an install _prefix_ of
'/usr/local', but this can be changed by using the '--prefix=PATH'
option.

   Once built, run 'make install' as root (or use 'sudo', as in the
example above) to install the binary and info documentation on your
system.  The executable is called 'xroar'.  ROM images should be placed
either in your home directory as '~/.xroar/roms/', or under the
installation _prefix_ as '_prefix_/share/xroar/roms/'.  Any
configuration file should be created as '~/.xroar/xroar.conf'.

   XRoar can be built on one platform to run on another.  The Windows
binary package is built like this.  To specify a cross-compile, use the
'--host=HOST' argument to 'configure'.  For example, to build for
Windows, you might use './configure --host=i686-w64-mingw32'.  Getting
everything "just so" for a cross-build can be a tricky procedure, and
the details are beyond the scope of this manual.

   XRoar can be built to a WebAssembly target using Emscripten
(https://emscripten.org/).  With the SDK installed, run 'emconfigure
./configure --enable-wasm' to set up the build environment.  Build with
'emmake make'.  HTML/JavaScript and CSS examples for interfacing to the
output are included in the 'wasm/' subdirectory.

