====== BUILDING XROAR ======

{{:tandy_color_computer:xroar.png?direct&600|XRoar CoCo 3 emulation}}

===== Running XRoar Online =====
All of the Build instructions below are OPTIONAL.

If you simply want to explore the Dragon and Color Computer, you can run XRoar online through these archive sites:
  * [[https://archive.org|The Internet Archive]]
  * [[https://colorcomputerarchive.com/|The Color Computer Archive]]
  * [[https://https://archive.worldofdragon.org/index.php?title=Main_Page|The Dragon Archive]]

===== Building XRoar on Debian =====

# Install Debian dependencies (current as of Debian 11 "Bullseye")
  $ sudo apt install build-essential libsndfile1-dev libgtk2.0-dev \
  >  libgtkglext1-dev libasound2-dev git emscripten

NOTE: you should only have to do this once on a fresh install of Debian

# Clone the source repository with your favorite git client of choice
  $ git clone --recurse-submodules 'https://www.6809.org.uk/git/xroar.git' SIXXIE-XROAR

Note: I capitalize directories following the OS-9 convention.

# Enter the repository directory
<code>
$ cd SIXXIE-XROAR
                 ++++++                    ExileInParadise ~ git version 2.39.2
              ++++++++++++                 ------------------------------------
          ++++++++++++++++++++             Project: xroar (20 branches, 69 tags)
       ++++++++++++++++++++++++++          HEAD: 3f4af43 (master, origin/master)
    ++++++++++++++++++++++++++++++++       Version: 1.3.1
 +++++++++++++************+++++++++++++    Created: 18 years ago
+++++++++++******************++++++++;;;   Languages:                                
+++++++++**********************++;;;;;;;              ● C (95.6 %) ● Objective-C (2.1 %) 
++++++++*********++++++******;;;;;;;;;;;              ● Perl (1.5 %) ● HTML (0.7 %) 
+++++++********++++++++++**;;;;;;;;;;;;;              ● JavaScript (0.1 %) ● CSS (0.0 %) 
+++++++*******+++++++++;;;;;;;;;;;;;;;;;              ● Other (0.0 %) 
+++++++******+++++++;;;;;;;;;;;;;;;;;;;;   Authors: 84% Ciaran Anscomb 2568
+++++++*******+++:::::;;;;;;;;;;;;;;;;;;            15% xroar 449
+++++++********::::::::::**;;;;;;;;;;;;;            1% Ciaran Anscomb 18
++++++++*********::::::******;;;;;;;;;;;   Last change: 2 hours ago
++++++:::**********************::;;;;;;;   Contributors: 10
+++::::::::******************::::::::;;;   Repo: https://www.6809.org.uk/git/xroar.git
 :::::::::::::************:::::::::::::    Commits: 3067
    ::::::::::::::::::::::::::::::::       Lines of code: 48079
       ::::::::::::::::::::::::::          Size: 2.50 MiB (272 files)
          ::::::::::::::::::::             License: GPL-3.0-only, LGPL-3.0-only
              ::::::::::::                 
                 ::::::                                            

</code>

# Read the README (no, really!)
  $ less README

**You DID read the README, right?**

# Use autogen.sh to use autoconf to build a configure script
  $ ./autogen.sh

NOTE: you should only need to do this once on a fresh clone of the repo.

# Use ./configure to create the configuration files
  $ ./configure
  <output of lots of configure checks going through and finding things in your build environment>

# Use make to build your XRoar
  $ make
  <output of lots of CC something.o building compiled object files and linking them>
  
# Use make to check your build
  $ make check
  <output of make check going through directories>

# Use make to install your custom XRoar
  $ sudo make install
  <output running install to move files and set owners, groups, permissions>
  $ which xroar
  /usr/local/bin/xroar

# Read the manual (no, really!)
  * [[https://www.6809.org.uk/xroar/doc/xroar.shtml|XRoar manual]]

**You DID read the [[https://www.6809.org.uk/xroar/doc/xroar.shtml|XRoar manual]], right?**

# Download any ROM images, cartridge, tape, and disk images necessary
  * [[https://archive.org|The Internet Archive]]
  * [[https://colorcomputerarchive.com/|The Color Computer Archive]]
  * [[https://https://archive.worldofdragon.org/index.php?title=Main_Page|The Dragon Archive]]

# Make a ROMs directory
  $ mkdir -p ~/.xroar/roms/

# Install ROMs
Copy the ROM files from your download folder into ~/.xroar/roms 

Example ROMs folder content:
<code>
$ tree .xroar/roms
├── bas10.rom
├── bas11.rom
├── bas12.rom
├── bas13.rom
├── coco3p.rom
├── coco3.rom
├── d200e_1.rom
├── d200e_2.rom
├── d32.rom
├── d64_1.rom
├── d64_2.rom
├── ddos10.rom
├── ddos40.rom
├── disk10.rom
├── disk11.rom
├── disk1.dsk
├── dplus49b.rom
├── extbas10.rom
├── extbas11.rom
├── hdbdw3bck.rom
├── mc10.rom
├── mx1600bas.rom
├── orch90.rom
└── sdose6.rom
</code>

# Test your XRoar
  $ xroar -machine dragon32 <dragon32 media>
  $ xroar -machine coco3 -tv-input rgb <coco3 media>
  $ xroar -machine mc10 <mc10 media>

# OPTIONAL: configure to build WebAssembly version of XRoar to run from web server in browser
  $ make clean
  $ emconfigure ./configure --enable-wasm --enable-dependency-tracking --host x86_64-pc-linux-gnu
  <lots of output of doing configure again>

# OPTIONAL: build WebAssembly version of XRoar
  $ emmake make
  <output of lots of emcc building object files  

# OPTIONAL: install XRoar WebAssembly version to your web server
  - Copy the repo "wasm" subdirectory to your web server
  - Copy the src/xroar.js binary to your web server "wasm" subdirectory
  - Copy the src/xroar.wasm binary to your web server "wasm" subdirectory
  - NOTE: the name of the binary must match what is in xroar.js
  - Copy your XRoar ROMs, Cartridge, Tape, and Disk images to your web server "wasm" subdirectory
  - NOTE: XRoar does not ship with ROMs, or other images - visit the archives for these
  - Edit wasm/software.js to include configurations for your ROMs, cartridges, tapes, and disk images following the examples included in the default file
  - NOTE: this can take a lot of fiddling to get right - be patient with yourself
  - NOTE2: I have to frequently check the [[https://www.6809.org.uk/xroar/doc/xroar.shtml|XRoar manual]] for options and spellings
  - Open your webserver/wasm/ path in your browser to start testing your configuration

{{:tandy_color_computer:xroaronline.png?direct&600|XRoar Online}}

===== RTS =====
Return to [[:Top]] or [[:Tandy Color Computer:]]