ZEsarUX Installation Instructions
---------------------------------

This file explains how to install ZEsarUX on Unix systems: GNU/Linux, FreeBSD, Mac OS X, Raspberry, Haiku, AROS, FiwixOS, Sortix, Minix3
Note that most of the information that applies to Linux also applies to FreeBSD.

For Haiku, AROS, FiwixOS, Sortix or Minix3 instructions, see near the end of this file

For Windows specific instructions please see the INSTALLWINDOWS file.


# Other versions provided by 3rd parties:

Arch Linux:
https://aur.archlinux.org/packages/zesarux/

Slackware:
https://slackware.pkgs.org/14.2/slackonly-x86_64/ZEsarUX-6.0-x86_64-1_slonly.txz.html

Retropie/EmulationStation:
http://emulationstation.org/

Open Pandora:
https://repo.openpandora.org/?page=detail&app=zesarux

PocketCHIP:
https://bbs.nextthing.co/t/tutorial-zesarux-8-bit-computer-emulator/8532

MorhpOS: can be compiled using the provided patch.



Quick Compilation for Debian Based Systems
------------------------------------------

In case you don't want to read all this file and you use a Debian based system (Debian, Ubuntu, etc), just run the following:

apt-get -y install git gcc make libncurses-dev libssl-dev xorg-dev libpulse-dev libsndfile1-dev libasound2-dev

export CFLAGS="-O3"
export LDFLAGS="-O3"

./configure --enable-ssl --disable-caca --disable-aa --disable-cursesw --prefix /usr && make clean && make -j2


You can run it by just executing: ./zesarux

If you want to install it:
su root
make install

And it will be located in your path and can be called by just running: zesarux



Core Requirements
-----------------

- gcc compiler.
- unix compatible operating system.


The following is a list of recommended minimum features for each operating system.


# GNU/Linux and other Unix systems (except Raspberry-raspbian)

- x11
- libpthreads
- alsa
- pulse
- no specific distribution nor kernel version is required, so it should run in all GNU/Linux machines


# macOS

- Mac OS X 10.5 or higher
- gcc, which can be installed with XCode. libpthreads is also included with XCode.
- Video support is provided by Cocoa driver, but you can also try to compile using X11 or another video driver.


# Raspberry Pi (Raspbian)

A Raspberry Pi 2 is recommended a minimum. The Raspberry Pi 1 is a bit too slow for ZEsarUX, but you can run at normal Spectrum speed by setting overclock on the Pi, having Real Video setting disabled and using the Spectrum reduced core

- libpthreads
- alsa
- SDL
- fbdev

Video support is provided by Framebuffer driver (fbdev), but you can also try to compile using X11, SDL or another video driver.

SDL 1.2 is recommended, to use SDL audio. SDL audio works better than alsa. You can install SDL libraries with:

    $ apt-get install libsdl1.2-dev


NOTE: SDL2 support is experimental.



Options Features
----------------

The following is a list of complete features, all of which are optional.


# Video Drivers

- x11 (on GNU/Linux, other Unix and Raspberry): needs x11libs, x11extlibs, xf86vidmode, xxf86vm. On debian-based systems the command "apt-get install xorg-dev" will be enough
- x11 (on Mac OS X): needs XQuartz
- cocoa (on Mac OS X): Compiling supported using XCode.
- SDL 1.2 (on GNU/Linux, other Unix and Raspberry): needs sdllib-1.2. SDL2 is experimental. Run "apt-get install libsdl1.2-dev" on debian-based systems
- caca: cacalib
- aa: aalib
- curses: curses-dev. You can also install cursesw to have 64x48 text resolution. Run "apt-get install libncurses-dev" on debian-based systems
- stdout: termios includes


# Audio Drivers

- OSS (dsp) (on GNU/Linux, other Unix and Raspberry): needs soundcard includes. Usually included on GNU/Linux systems.
- alsa (on GNU/Linux, other Unix and Raspberry): needs alsalibs. Also needed if you want midi output. Run "apt-get install libasound2-dev" on debian-based systems
- pulse (on GNU/Linux, other Unix and Raspberry): needs pulselibs. Run "apt-get install libpulse-dev" on debian-based systems
- SDL 1.2 (on GNU/Linux, other Unix and Raspberry): needs sdllib. SDL2 is experimental.
- coreaudio (on Mac OS X): Compiling supported using XCode.


# Audio Output to a File

- libsndfile to output audio to wav files. Run "apt-get install libsndfile1-dev" on debian-based systems
- Raw audio is always supported.


# Other Enhancements

- pthreads: pthread includes. Usually included on all Unix systems.
- ssl library: to have the speccy online browser. Add "--enable-ssl" setting to the configure script. Run "apt-get install libssl-dev" on debian-based systems
ssl library is not included on Mac anymore; you can easily install it using https://brew.sh, after that, do a "brew install openssl"



Compiling ZEsarUX
-----------------

The quick way to compile and run ZEsarUX is:


    $ cd src
    $ ./configure
    $ make clean
    $ make
    $ ./zesarux


However, you can tune the compilation process a bit, depending on your operating system:


* macOS

    $ ./configure
    $ make clean
    $ make
    $ ./zesarux


* GNU/Linux and other Unix systems (except Raspberry-raspbian)

    $ ./configure
    $ make clean
    $ make
    $ ./zesarux


* Raspberry-raspbian

    $ export CFLAGS=-O3
    $ export LDFLAGS=-O3

    $ ./configure --enable-raspberry
    $ make clean
    $ make
    $ ./zesarux

Even more, if you have a slow device like the Raspberry Pi 1 or Zero, I recommend you:

    $ ./configure --enable-raspberry --spectrum-reduced-core --disable-memptr --disable-visualmem --disable-cpustats

This will also ensure that the "reduced core" is on by default, which uses less cpu, although you can also switch it from command line, or at runtime. Also we do not compile memptr, visualmem and cpu stats, which use a bit more cpu


NOTE: by using the reduced core some features will NOT be available. See the FAQ file, where it talks about the Spectrum reduced core



Install and Run ZEsarUX
-----------------------

As I said, it is possible to run the emulator from the current directory without installing, just by running:
    $ ./zesarux


If you want to install it, the following are the instructions for the different operating systems:


# macOS

    $ make macapp

This will create a "macos" folder, which contains the "ZEsarUX.app" along with a compressed ".dmg" file.

You may wish to move this to your "Applications" folder.



# GNU/Linux and other Unix systems

If installing from source code:

    $ su root
    $ make install


If installing from binary:

    $ su root
    $ ./install.sh



Note for Raspberry Pi

The recommended way to start the emulator is using the following settings:

--disableborder --zoom 1 --fullscreen --vo fbdev --ao sdl --no-detect-realvideo


Note for Haiku
--------------

I'm using Haiku OS Beta 5 64 bits, so the following may change in different versions.

You can run the following sentences as a quick start:

--
pkgman install libsdl_devel
git clone https://github.com/chernandezba/zesarux.git
cd zesarux/src
./configure
make
--

Please don't ask me about Haiku help, I'm not an expert on this OS ;)


Note for AROS
-------------

To compile:

-Open shell
-Then, on the shell, run "sh" shell command, which opens a Unix-compatible shell:
sh

-Then run :

export LDFLAGS="-nix"
sh configure --other-unix --disable-pthreads
make


Note for FiwixOS
----------------

- Be sure to boot FiwixOS on standard VGA mode (not VESA)

- Compile:

export CFLAGS="-DSHORT_SLEEP_TIMER"
export LIBS="-lvga"
./configure --disable-pthreads --disable-networking --disable-aa
make

- Start the first time with:
./zesarux --zoom 1 --sdl-8bit-color --sdl-force-win-size 320 200 --sdl-hwsurface --disableborder --ao null --disable-autoframeskip --vo sdl --enable-zxdesktop --zxdesktop-width 64 --zxdesktop-height 0 --zxdesktop-disable-footer-switch

- Note: the most important settings are:
--sdl-8bit-color --sdl-force-win-size 320 200 --vo sdl

If not set this, probably ZEsarUX will generate a segmentation fault due to small video mode


Note for Sortix
---------------

- Compile:

export LIBS="-ldisplay -ltermcap"
sh ./configure --disable-pthreads --other-unix
make


Note for Minix3
---------------

- Compile:

export CFLAGS="-DMINIX3 -DCURSES_NOT_NCURSES"

./configure --c-compiler clang
make

- F5 is usually mapped on Minix3 to dump kernel environment, so in this case, to open
ZEsarUX menu, use the End key


Utilities
---------

These can be compiled with:

    $ make utilities
