Update README.

This commit is contained in:
cfreksen 2017-11-09 16:41:03 +01:00
parent 3ddab21f72
commit 669e8627c8
No known key found for this signature in database
GPG Key ID: EAC13EE101008978

View File

@ -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.
#+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
Installation includes
- Downloading and installing dependencies
- Downloading the emulator
- Storing the emulator libraries where your other Python libraries
are
- Adding a small script to easily start the emulator
Currently, to install the software you have to install the
dependencies via ~pip~, e.g.
#+BEGIN_SRC sh
$ pip install -r requirements.txt
#+END_SRC
** Pip way
The recommended way to quickly install and use the emulator, is to
install it via pip. The name on PyPI (where pip gets the software
from) is =llvm-minusminus-emulator=[fn:0].
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
installing and setting up the application. Once that is done,
installation and usage will hopefully be more streamlined.
#+BEGIN_SRC sh
$ pip3 install llvm-minusminus-emulator
#+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
emulator script:
If installing the emulator went well, a script (~llvm--emulator~)
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/
$ ./emulator.py
#+END_SRC
$ llvm--emulator --help
usage: llvm--emulator [-h] [-a AUTO_PATH]
Use the ~-h~ (~--help~) flag for information on more options:
#+BEGIN_SRC sh
$ ./emulator.py -h
A hacky LLVM-- emulator/debugger
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
~setuptools~. This will affect how the emulator can be invoked. The
hope is that it will be installed into your =bin= folder, so that
you can use the emulator without having to navigate to it.
When running the emulator you might get messages like the following:
#+BEGIN_SRC sh
WARNING: Couldn't open 'parser.out'. [Errno 13] Permission denied: '/usr/lib/python3.6/site-packages/llvm_emulator/parser.out'
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
Parsing ../some_file.ll
Beginning execution of ../some_file.ll
$ llvm--emulator -a some_file.ll
Parsing 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