XRoar - a Dragon and Tandy 8-bit computer emulatorCopyright 2003-2023 Ciaran Anscomb <xroar@6809.org.uk>Introduction============XRoar emulates the Dragon 32/64; Tandy Colour Computers 1, 2 and 3; theTandy MC-10; and some other similar machines or clones.  It runs on awide variety of platforms.  Emulated hardware includes:   * Dragon 32, 64, and 200-E; Tandy CoCo 1, 2, & 3; Tandy MC-10; Matra     & Hachette Alice 4K.   * DragonDOS, Delta and RS-DOS disk controller cartridges.   * Orchestra 90-CC stereo sound cartridge.   * Games Master Cartridge, including the SN76489 sound chip.   * Glenside IDE cartridge, with IDE hard disk image support.   * NX32 and MOOH RAM expansions, with SPI and SD card image support.   Other features include:   * Raw and translated keyboard modes.   * Read and write tape images (compact '.cas' files or audio, e.g.     '.wav').   * Read and write VDK, JVC and DMK format floppy disk images.   * Becker port for communication with remote servers.   * Save and load machine snapshots.   * GDB target for remote debugging.   XRoar is easily built from source under Linux, and binary packagesare provided for Mac OS X+ and Windows.   XRoar can also be compiled to WebAssembly, and redistributing it inthis form may provide a convenient way for users to run your Dragonsoftware.  See XRoar Online (https://www.6809.org.uk/xroar/online/) foran example.   XRoar is free software; you can redistribute it and/or modify itunder the terms of the GNU General Public License as published by theFree Software Foundation, either version 3 of the License, or (at youroption) any later version.   XRoar is distributed in the hope that it will be useful, but WITHOUTANY WARRANTY; without even the implied warranty of MERCHANTABILITY orFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License formore details.   You should have received a copy of the GNU General Public Licensealong with this program.  If not, see <https://www.gnu.org/licenses/>.   This README contains extracts from the manual.  Binary packagescontain the full manual as a PDF, which is also available from the XRoarhome page (https://www.6809.org.uk/xroar/).Recent changes==============Version 1.4 replaces the '-ccr simulated' cross-colour renderer withmore CPU-intensive code that also handles PAL. The old NTSC-onlyrenderer is still available using '-ccr partial'.  Some video optionscan be changed on the fly in a new TV Controls dialog.   Version 1.3 changes the default floppy disk write-back behaviour.The old behaviour erred on the side of protecting image files fromaccidental modification.  Enough people have complained about this--orat least, the small number that have complained have done soloudly--that XRoar will now rewrite changes to the backing file bydefault.  Run with the '-no-disk-write-back' option to revert to the oldbehaviour.  XRoar will still rename the old version of a file to have a'.bak' extension if possible, and also tries harder not to rewrite thefile if no writes have occurred.   Version 1.0 introduced support for the Tandy Colour Computer 3 andthe Tandy MC-10.  Version 1.1 adds proper support for the MC-10's Frenchcousin, the Matra & Hachette Alice (4K).   Snapshots now store much more state, and of course support the newemulated machines, but this means the format had to change.  Snapshotsfrom the last 0.x release are still recognised, and can be loaded, butthis support is likely to be removed in time.   Tape emulation now supports manual pause control.  On the MC-10, thisdefaults to paused, as it has no ability to remotely control the tapemotor.  You will need to un-pause after typing 'CLOAD' or 'CLOADM' onthe MC-10 (File -> Cassette -> Play, or from the tape control tool;autorunning will do this automatically).   Previously, the Glenside IDE controller would use a fixed HD imagefile in the current working directory.  You must now specify an imagewith the '-load-hd0' option.  You can also now attach a second hard diskimage with '-load-hd1', if you have software that can access it.   Similarly, the NX32 and MOOH cartridges would use a fixed SD imagefile, and you must now specify it with the '-load-hd0' option.   Old IDE images, including those created by XRoar, will have a '.img'file extension.  In order to distinguish these files from similar imageswith no header information, you should now rename these to have a '.ide'extension.Installation************Binary packages===============Pre-built binary packages are available from the XRoar home page(https://www.6809.org.uk/xroar/).  If one is not available for yourarchitecture, you will need to build from source.  XRoar should buildand run on any POSIX-like system for which SDL version 2 is available.   You will also need BASIC ROM images--binary dumps of the firmwarefrom 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 runfrom 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 thedirectory 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 timeyou upgrade, you can create 'Documents/XRoar' to contain yourconfiguration file, and a subdirectory of that, 'Documents/XRoar/roms'for ROM images.   Note when troubleshooting that the logging from the Windows binary isprobably 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 buildfrom source.  XRoar can use various backend toolkits, and you will needto ensure you have their development files installed.  If you're usingDebian, this can (at the time of writing) be achieved with the followingsimple 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 thenensure you have XRoar's dependencies available is to use a system likeHomebrew (https://brew.sh/) or MacPorts (http://www.macports.org/).  ForHomebrew, the following command will install the required dependencies:     $ brew install libsndfile sdl2   Otherwise, you'll have to do a bit of platform-specific research toensure you have all the dependencies for a full build:   GTK+ (http://www.gtk.org/), the GIMP toolkit, provides the mostfull-featured user interface.  It is only usable as such if you alsohave GtkGlExt (http://projects.gnome.org/gtkglext/), an OpenGL extensionused to provide video output.  Otherwise, it can provide a filerequester for use by other user interfaces.  Version 2 only.   SDL (http://www.libsdl.org/), Simple Directmedia Layer, provides aslightly more basic user experience.  Menus are added using native codeunder Mac OS X+ and Windows; any other target using SDL will support onlykeyboard shortcuts.  Unless you are building for Linux, SDL is requiredto 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.  Someother options are still in the code base, but have not been tested in awhile.   libsndfile (http://www.mega-nerd.com/libsndfile/) is recommended toenable support for using audio files as cassette images.Compilation-----------Once you have the dependencies, building XRoar follows a familiarprocedure:(1)     $ gzip -dc xroar-1.4.tar.gz | tar xvf -     $ cd xroar-1.4     $ ./configure     $ make     $ sudo make install   The 'configure' script has a lot of options guiding what it testsfor, specifying cross-compilation, changing the install path, etc.  Listthem 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 theexample above) to install the binary and info documentation on yoursystem.  The executable is called 'xroar'.  ROM images should be placedeither in your home directory as '~/.xroar/roms/', or under theinstallation _prefix_ as '_prefix_/share/xroar/roms/'.  Anyconfiguration file should be created as '~/.xroar/xroar.conf'.   XRoar can be built on one platform to run on another.  The Windowsbinary package is built like this.  To specify a cross-compile, use the'--host=HOST' argument to 'configure'.  For example, to build forWindows, you might use './configure --host=i686-w64-mingw32'.  Gettingeverything _just so_ for a cross-build can be a tricky procedure, andthe 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 theoutput are included in the 'wasm/' subdirectory.   ---------- Footnotes ----------   (1) If you have cloned the git repository, you will need GNU BuildSystem packages installed: 'autoconf', etc.  Running './autogen.sh'should then generate the configure script, which you can run as normal.