==========================
ULM-Generator Installation						[TOC]
==========================

The __ULM-Generator__ allows to generate a virtual machine (i.e. a simulator
for a computer). We will work a lot in the remaining semester with virtual
machines generated by this tool. On this page you find instructions on how to
install the ULM-Generator.

:links: ULM-Generator -> https://github.com/michael-lehn/ulm-generator

Prerequisites
=============
Before you can start with the installation some required tools and libraries
are needed. 

For MacOS Users
---------------
Use `brew` to install the packages `autoconf`, `automake`, `autoconf-archive`,
`pkg-config`, `libtool`, `texlive`, `ncurses`:

---- CODE (type=txt) -----------
brew install autoconf
brew install automake
brew install autoconf-archive
brew install pkg-config
brew install libtool
brew install texlive
brew install ncurses
brew install make
--------------------------------

Z Shell 
~~~~~~~
If you use the Z shell (default shell on MacOS) you also have to prepend
`/usr/local/opt/make/libexec/gnubin` to your `PATH` variable. You can do this
by executing this command:

---- CODE (type=txt) -----------
echo 'PATH="/usr/local/opt/make/libexec/gnubin:$PATH"' >> $HOME/.zshrc
--------------------------------

Bash
~~~~
If you use Bash run

---- CODE (type=txt) -----------
echo 'PATH="/usr/local/opt/make/libexec/gnubin:$PATH"' >> $HOME/.bashrc
--------------------------------




For Linux (and WSL) Users
-------------------------

Install the packages `autoconf`, `libtool`, `autoconf-archive`, `make`,
`g++`, `pkg-config`, `libncurses5-dev`:

---- CODE (type=txt) -----------
sudo apt install autoconf
sudo apt install libtool
sudo apt install autoconf-archive
sudo apt install make
sudo apt install g++
sudo apt install pkg-config
sudo apt install libncurses5-dev
sudo apt install texlive-full
--------------------------------

Installing the Library `finalcut`
=================================

The __finalcut__ library (by Markus Gans) makes it easy to implement TUIs (Text
User Interfaces). It is used by the ULM-Generator for a debugger. In order to
install it do the following:

:links: finalcut -> https://github.com/gansm/finalcut

---- CODE (type=txt) --------------------------------------
git clone https://github.com/michael-lehn/finalcut
cd finalcut
autoreconf --install --force
./configure --prefix=/usr/local
make
sudo make install
-----------------------------------------------------------

Installing the ULM-Generator
============================

If (big if) all of the above worked you finally can install the ULM-Generator
in a local directory as follows:

---- CODE (type=txt) --------------------------------------
cd ~
git clone https://github.com/michael-lehn/ulm-generator.git
cd ulm-generator
sudo make install
-----------------------------------------------------------

Testing the (generated) ULM Debugger
====================================

Create a new directory, change into it and do the following:

---- CODE (type=txt) --------------------------------------
ulm-generator --fetch ulm-ice40.isa
ulm-generator --install ulm-ice40.isa
-----------------------------------------------------------

This will take a while and will install the tools `ulm`, `ulmas`, and `udb-tui`.
On success this should work

---- CODE (type=txt) --------------------------------------
echo "10100020202100001402000004000004302000001211000105FFFFFB0141000068656C6C6F2C20776F726C64210A00" > hello
ulm hello
udb-tui hello
-----------------------------------------------------------

With the last command `hello` will run in the debugger

--- IMAGE -----------
session05/udb-tui.png
---------------------