Update README.

README.org

@@ -38,50 +38,148 @@
 
   This project is designed for Linux, though I do not expect there to
   be any issues on other platforms. As a consequence the commands
-  given below are designed for a Linux shell.
+  given below are designed for a Linux shell. Lines beginning with a
+  dollar sign ($) indicate commands you enter into your terminal,
+  other lines are output from running those commands
+
+** Getting Python 3
+   To see if you already have Python 3 installed, try running (the
+   lines beginning with $):
+   #+BEGIN_SRC sh
+     $ python --version
+     Python 2.7.14
+     $ python3 --version
+     Python 3.6.3
+   #+END_SRC
+   If one of these commands gives a version number >= 3, you have
+   Python 3 through that command (without ~--version~, of course). In
+   the example above, I need to use the command ~python3~ in order to
+   use the correct version of Python for this emulator.
+
+   Otherwise, you could try to install Python 3 via your package
+   manager. Depending on which Linux distribution you use, you could
+   try something like
+   #+BEGIN_SRC sh
+     $ apt install python3
+   #+END_SRC
+   or
+   #+BEGIN_SRC sh
+     $ sudo apt install python3
+   #+END_SRC
+
+** Getting pip for Python 3
+   You need pip to (easily) install Python packages. If your Linux
+   distribution came with Python 2 and pip, the pip you have might not
+   work for Python 3. Let us first check that:
+
+   #+BEGIN_SRC sh
+     $ pip --version
+     pip 9.0.1 from /usr/lib/python2.7/site-packages (python 2.7)
+     $ pip3 --version
+     pip 9.0.1 from /usr/lib/python3.6/site-packages (python 3.6)
+   #+END_SRC
+   As with the Python version commands in the last section, I have to
+   use ~pip3~. If I just used ~pip~ packages would be installed for
+   Python 2, which I do not want.
+
+   Pip should come with newer versions of Python. If you have a new
+   version of Python, but no pip, you might need to install it
+   seperately. You could try (depending on your Linux distribution)
+   #+BEGIN_SRC sh
+     $ apt install python3-pip
+   #+END_SRC
+   or
+   #+BEGIN_SRC sh
+     $ sudo apt install python3-pip
+   #+END_SRC
 
 * Installation
-  If you have not already, download the code.
+  Installation includes
-  #+BEGIN_SRC sh
+  - Downloading and installing dependencies
-    $ cd path/to/folder/where/you/want/to/store/the/emulator
+  - Downloading the emulator
-    $ git clone git@gitlab.com:cfreksen/llvm--emulator.git
+  - Storing the emulator libraries where your other Python libraries
-  #+END_SRC
+    are
+  - Adding a small script to easily start the emulator
 
-  Currently, to install the software you have to install the
+** Pip way
-  dependencies via ~pip~, e.g.
+   The recommended way to quickly install and use the emulator, is to
-  #+BEGIN_SRC sh
+   install it via pip. The name on PyPI (where pip gets the software
-    $ pip install -r requirements.txt
+   from) is =llvm-minusminus-emulator=[fn:0].
-  #+END_SRC
 
-  You should now be ready to use the software.
+   Make sure that you have Python 3 and pip installed (see above).
+   Then install the emulator by running
 
-  There is currently work being done to use ~setuptools~ to handle
+   #+BEGIN_SRC sh
-  installing and setting up the application. Once that is done,
+     $ pip3 install llvm-minusminus-emulator
-  installation and usage will hopefully be more streamlined.
+   #+END_SRC
+
+   If all goes well, you are now ready to use the emulator.
+
+[fn:0] I know the name is ugly, but Python packaging was not happy
+about the double dash in =llvm--emulator=, and =llvm-emulator= makes
+it sound like it covers the entire LLVM IR language.
+
+** Git way
+   To get the very latest version, you can do the following
+
+   If you have not already, download the code.
+   #+BEGIN_SRC sh
+     $ cd path/to/folder/where/you/want/to/store/the/emulator
+     $ git clone git@gitlab.com:cfreksen/llvm--emulator.git
+   #+END_SRC
+
+   To install the software, you can use ~pip~ on the folder containing
+ =setup.py=:
+   #+BEGIN_SRC sh
+     $ cd path/to/folder/where/you//stored/the/emulator/llvm--emulator
+     $ pip3 install .
+   #+END_SRC
+
+   You should now be ready to use the software.
+
+** Uninstalling
+   To remove the emulator, just uninstall via pip:
+   #+BEGIN_SRC sh
+     $ pip3 uninstall llvm-minusminus-emulator
+   #+END_SRC
 
 * Usage
-  You use the application by entering its directory and envoking the
+  If installing the emulator went well, a script (~llvm--emulator~)
-  emulator script:
+  should have been added to your =bin= folder. This means that you can
+  start the emulator (wherever you are), by running that script:
   #+BEGIN_SRC sh
-    $ cd path/to/the/repository/llvm_emulator/
+    $ llvm--emulator --help
-    $ ./emulator.py
+    usage: llvm--emulator [-h] [-a AUTO_PATH]
-  #+END_SRC
 
-  Use the ~-h~ (~--help~) flag for information on more options:
+    A hacky LLVM-- emulator/debugger
-  #+BEGIN_SRC sh
+
-    $ ./emulator.py -h
+    optional arguments:
+      -h, --help            show this help message and exit
+      -a AUTO_PATH, --auto AUTO_PATH
+                            Automatically step through llvm in the given file
   #+END_SRC
 
   To automatically step through a LLVM file (and be quite verbose
   about it), you can use the ~-a~ (~--auto~) flag:
   #+BEGIN_SRC sh
-    $ ./emulator.py -a path/to/your/file.ll
+    $ llvm--emulator -a path/to/your/file.ll
   #+END_SRC
 
-  As mentioned above, there is work being done on using
+  When running the emulator you might get messages like the following:
- ~setuptools~. This will affect how the emulator can be invoked. The
+  #+BEGIN_SRC sh
-  hope is that it will be installed into your =bin= folder, so that
+    WARNING: Couldn't open 'parser.out'. [Errno 13] Permission denied: '/usr/lib/python3.6/site-packages/llvm_emulator/parser.out'
-  you can use the emulator without having to navigate to it.
+    WARNING: Couldn't create 'parsetab'. [Errno 13] Permission denied: '/usr/lib/python3.6/site-packages/llvm_emulator/parsetab.py'
+  #+END_SRC
+  This is because the script does not have permission to write files
+  among your Python libraries. This is because the parser inside the
+  emulator tries to cache its parsing table (think of =tiger.grm.sml=)
+  where the parsing code is located. If does not have permission to do
+  that, it still parses your LLVM code; it just needs to rebuild the
+  parsing table next time you run the emulator. These warnings should
+  be safe to ignore.
+
+  I have tried to fix this issue without success, so hopefully you can
+  live with a few warning messages.
 
 ** Example
    Let us say, that we have the following LLVM-- code in =some_file.ll=
@@ -102,9 +200,9 @@
 
    Then we run the emulator:
    #+BEGIN_SRC sh
-     $ ./emulator.py -a ../some_file.ll
+     $ llvm--emulator -a some_file.ll
-     Parsing ../some_file.ll
+     Parsing some_file.ll
-     Beginning execution of ../some_file.ll
+     Beginning execution of some_file.ll
      Heap after globals are allocated:
      [None]
 
@@ -146,6 +244,33 @@
    This shows which values variables have as they are encountered as
    well as the order the instructions are evaluated.
 
+** Alternatives
+   If the =llvm--emulator= script does not work for you, you can
+   inspect it in the =path/to/emulator/repository/bin/= folder
+   (assuming you have the source code. See the section
+   'Installation:Git Way', or look at the code online on
+   [[https://gitlab.com/cfreksen/llvm--emulator]]). It should be clear
+   enough what the script does, and if you know a bit of Python, you
+   should be able to tweak it to your needs.
+
+* Known Issues/Missing Features
+  Here some of the known major issues/missing features are
+  listed. This list might be updated, should the issues be fixed/the
+  features implemented:
+
+** Interactive mode
+   There is currently no support for stepping through the code one key
+   press at a time. Similarly, there is no support for inserting
+   breakpoints, or looking up the current values in memory/registers
+   via commands.
+
+** Builtin functions
+   When generating LLVM code from Tiger code, there can be several
+   calls to functions defined in a file called =runtime.c=. Many of
+   these functions are not implemented in the emulator. However,
+ ~allocRecord~, ~initArray~, and ~print~ are so that will hopefully
+   be enough for the majority of your LLVM programs.
+
 * License
   The code in this project is licensed under GPLv3+. The full
   licensing text can be found in the ~LICENSE~ file, while a small but