Update README.
This commit is contained in:
cfreksen
parent
3ddab21f72
commit
669e8627c8
187
README.org
187
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.
|
||||
#+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
|
||||
|
|
|
|||
Loading…
Reference in New Issue