diff --git a/pypi_readme.rst b/pypi_readme.rst new file mode 100644 index 0000000..12b0705 --- /dev/null +++ b/pypi_readme.rst @@ -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, <>] + 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. diff --git a/setup.py b/setup.py index a6526c3..70eea05 100644 --- a/setup.py +++ b/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',