Add readme in rst format for PyPI.
This commit is contained in:
cfreksen
parent
242221c89b
commit
fa021d4fc5
337
pypi_readme.rst
Normal file
337
pypi_readme.rst
Normal file
|
|
@ -0,0 +1,337 @@
|
||||||
|
Overview
|
||||||
|
========
|
||||||
|
|
||||||
|
This application is an emulator/debugger for LLVM-- as defined in the
|
||||||
|
Compiler course (dOvs) at Aarhus University.
|
||||||
|
|
||||||
|
While I hope that you will find it useful, the tool is being provided AS
|
||||||
|
IS, this means
|
||||||
|
|
||||||
|
#. There is no guarantee that emulator emulates LLVM-- correctly.
|
||||||
|
Various liberties has been taken to simplify the emulations, e.g.
|
||||||
|
values of type ``i64`` can be arbitrarily large. And there can, of
|
||||||
|
course, be bugs in the application.
|
||||||
|
#. Not all parts of LLVM-- has been implemented. While the main set of
|
||||||
|
instructions and types has been implemented at this point, you might
|
||||||
|
hit a "TODO: Not implemented yet" message.
|
||||||
|
#. Many type annotations are being ignored. This means that ill-typed
|
||||||
|
LLVM-- programs might be emulated without a problem. This can give a
|
||||||
|
false sense of security, so always use a tool like ``clang``, if you
|
||||||
|
want to check types of your generated code
|
||||||
|
#. We, as TAs, do not give support for this emulator.
|
||||||
|
#. **If your generated code works in this emulator, but not in clang,
|
||||||
|
your generated code is incorrect!** We, as TAs, will **not** accept
|
||||||
|
it.
|
||||||
|
|
||||||
|
Requirements
|
||||||
|
============
|
||||||
|
|
||||||
|
This application is written in Python. It was developed in Python 3.6,
|
||||||
|
but I expected to work for Python 3.5 and above. Note that Python 2 is
|
||||||
|
not supported.
|
||||||
|
|
||||||
|
Several Linux distributions have Python 2 as the default. You can
|
||||||
|
usually use the commands ``python3``, ``pip3``, etc. to use Python 3 on
|
||||||
|
such systems (assuming you have installed Python 3).
|
||||||
|
|
||||||
|
The application uses some third party libraries as indicated in
|
||||||
|
``requirements.txt``.
|
||||||
|
|
||||||
|
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. 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 $):
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ python --version
|
||||||
|
Python 2.7.14
|
||||||
|
$ python3 --version
|
||||||
|
Python 3.6.3
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ apt install python3
|
||||||
|
|
||||||
|
or
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ sudo apt install python3
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ 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)
|
||||||
|
|
||||||
|
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)
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ apt install python3-pip
|
||||||
|
|
||||||
|
or
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ sudo apt install python3-pip
|
||||||
|
|
||||||
|
Installation
|
||||||
|
============
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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= [1]_.
|
||||||
|
|
||||||
|
Make sure that you have Python 3 and pip installed (see above). Then
|
||||||
|
install the emulator by running
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ pip3 install llvm-minusminus-emulator
|
||||||
|
|
||||||
|
If all goes well, you are now ready to use the emulator.
|
||||||
|
|
||||||
|
Git way
|
||||||
|
-------
|
||||||
|
|
||||||
|
To get the very latest version, you can do the following
|
||||||
|
|
||||||
|
If you have not already, download the code.
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ cd path/to/folder/where/you/want/to/store/the/emulator
|
||||||
|
$ git clone git@gitlab.com:cfreksen/llvm--emulator.git
|
||||||
|
|
||||||
|
To install the software, you can use ``pip`` on the folder containing
|
||||||
|
``setup.py``:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ cd path/to/folder/where/you//stored/the/emulator/llvm--emulator
|
||||||
|
$ pip3 install .
|
||||||
|
|
||||||
|
You should now be ready to use the software.
|
||||||
|
|
||||||
|
Uninstalling
|
||||||
|
------------
|
||||||
|
|
||||||
|
To remove the emulator, just uninstall via pip:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ pip3 uninstall llvm-minusminus-emulator
|
||||||
|
|
||||||
|
Usage
|
||||||
|
=====
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ llvm--emulator --help
|
||||||
|
usage: llvm--emulator [-h] [-a AUTO_PATH]
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
To automatically step through a LLVM file (and be quite verbose about
|
||||||
|
it), you can use the ``-a`` (``--auto``) flag:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ llvm--emulator -a path/to/your/file.ll
|
||||||
|
|
||||||
|
When running the emulator you might get messages like the following:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
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'
|
||||||
|
|
||||||
|
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``
|
||||||
|
|
||||||
|
.. code:: llvm
|
||||||
|
|
||||||
|
%Ttigermain = type { i64, i64, i64 }
|
||||||
|
|
||||||
|
define i64 @tigermain (i64 %U_mainSL_8, i64 %U_mainDummy_9) {
|
||||||
|
%t = alloca %Ttigermain
|
||||||
|
%a = getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 1
|
||||||
|
store i64 9, i64* %a
|
||||||
|
%r = load i64, i64* %a
|
||||||
|
%s = add i64 100, %r
|
||||||
|
%b = getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 0
|
||||||
|
store i64 %s, i64* %b
|
||||||
|
ret i64 %s
|
||||||
|
}
|
||||||
|
|
||||||
|
Then we run the emulator:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ llvm--emulator -a some_file.ll
|
||||||
|
Parsing some_file.ll
|
||||||
|
Beginning execution of some_file.ll
|
||||||
|
Heap after globals are allocated:
|
||||||
|
[None]
|
||||||
|
|
||||||
|
Evaluating alloca %Ttigermain
|
||||||
|
alloca {i64, i64, i64} --> allocating 3 cells
|
||||||
|
%t <- 1
|
||||||
|
|
||||||
|
Evaluating getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 1
|
||||||
|
Gep formula: 1 + 0 * 3 + (1)
|
||||||
|
%a <- 2
|
||||||
|
|
||||||
|
Evaluating store i64 9, i64* %a
|
||||||
|
heap[2] <- 9
|
||||||
|
|
||||||
|
Evaluating load i64, i64* %a
|
||||||
|
load heap[2]
|
||||||
|
%r <- 9
|
||||||
|
|
||||||
|
Evaluating add i64 100, %r
|
||||||
|
add 100, 9
|
||||||
|
%s <- 109
|
||||||
|
|
||||||
|
Evaluating getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 0
|
||||||
|
Gep formula: 1 + 0 * 3 + 0
|
||||||
|
%b <- 1
|
||||||
|
|
||||||
|
Evaluating store i64 %s, i64* %b
|
||||||
|
heap[1] <- 109
|
||||||
|
|
||||||
|
Evaluating ret i64 %s
|
||||||
|
Returning 109
|
||||||
|
|
||||||
|
Stepping done!
|
||||||
|
Final ssa_env: {'U_mainSL_8': 1234, 'U_mainDummy_9': 5678, 't': 1, 'a': 2, 'r': 9, 's': 109, 'b': 1}
|
||||||
|
Final heap: [None, 109, 9, <<Garbage>>]
|
||||||
|
Program resulted in 109 after 8 steps
|
||||||
|
|
||||||
|
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 descriptive
|
||||||
|
header is:
|
||||||
|
|
||||||
|
LLVM-- Emulator -- A simple hacky emulator and debugger for LLVM--
|
||||||
|
Copyright © 2017 Casper Freksen
|
||||||
|
|
||||||
|
This program is free software: you can redistribute it and/or modify
|
||||||
|
it under the terms of the GNU General Public License as published by
|
||||||
|
the Free Software Foundation, either version 3 of the License, or
|
||||||
|
(at your option) any later version.
|
||||||
|
|
||||||
|
This program is distributed in the hope that it will be useful, but
|
||||||
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||||
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||||
|
General Public License for more details.
|
||||||
|
|
||||||
|
You should have received a copy of the GNU General Public License
|
||||||
|
along with this program. If not, see http://www.gnu.org/licenses/.
|
||||||
|
|
||||||
|
.. [1]
|
||||||
|
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.
|
||||||
10
setup.py
10
setup.py
|
|
@ -12,16 +12,8 @@ from setuptools import setup
|
||||||
|
|
||||||
packages = ['llvm_emulator']
|
packages = ['llvm_emulator']
|
||||||
|
|
||||||
with open('README') as f:
|
with open('pypi_readme.rst') as f:
|
||||||
long_description = f.read()
|
long_description = f.read()
|
||||||
try:
|
|
||||||
# Look for a org mode header within the first 200 chars. If
|
|
||||||
# nothing is found, we just use the entire readme file as the
|
|
||||||
# description, by not updating long_description
|
|
||||||
start_index = long_description.index('\n*', 0, 200) + 1
|
|
||||||
long_description = long_description[start_index:]
|
|
||||||
except:
|
|
||||||
pass
|
|
||||||
|
|
||||||
setup(
|
setup(
|
||||||
version='1.0.0',
|
version='1.0.0',
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user