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']
|
||||
|
||||
with open('README') as f:
|
||||
with open('pypi_readme.rst') as f:
|
||||
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(
|
||||
version='1.0.0',
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user