From 669e8627c80619d1f379daf813126ba8d6d4079e Mon Sep 17 00:00:00 2001 From: cfreksen Date: Thu, 9 Nov 2017 16:41:03 +0100 Subject: [PATCH] Update README. --- README.org | 187 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 156 insertions(+), 31 deletions(-) diff --git a/README.org b/README.org index f4d826f..f8b3af0 100644 --- a/README.org +++ b/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