{
    "info": {
        "author": "Casper Freksen",
        "author_email": "cfreksen@cs.au.dk",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Environment :: Console",
            "Intended Audience :: Developers",
            "Intended Audience :: Education",
            "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
            "Natural Language :: English",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3 :: Only",
            "Topic :: Software Development :: Debuggers",
            "Topic :: System :: Emulators"
        ],
        "description": "Overview\n========\n\nThis application is an emulator/debugger for LLVM-- as defined in the\nCompiler course (dOvs) at Aarhus University.\n\nWhile I hope that you will find it useful, the tool is being provided AS\nIS, this means\n\n#. There is no guarantee that emulator emulates LLVM-- correctly. Various\n   liberties has been taken to simplify the emulations, e.g. values of\n   type ``i64`` can be arbitrarily large. And there can, of course, be\n   bugs in the application.\n#. Not all parts of LLVM-- has been implemented. While the main set of\n   instructions and types has been implemented at this point, you might\n   hit a \"TODO: Not implemented yet\" message.\n#. Many type annotations are being ignored. This means that ill-typed\n   LLVM-- programs might be emulated without a problem. This can give a\n   false sense of security, so always use a tool like ``clang``, if you\n   want to check types of your generated code\n#. We, as TAs, do not give support for this emulator.\n#. **If your generated code works in this emulator, but not in clang,\n   your generated code is incorrect!** We, as TAs, will **not** accept\n   it.\n\nRequirements\n============\n\nThis application is written in Python. It was developed in Python 3.6,\nbut I expected to work for Python 3.5 and above. Note that Python 2 is\nnot supported.\n\nSeveral Linux distributions have Python 2 as the default. You can\nusually use the commands ``python3``, ``pip3``, etc. to use Python 3 on\nsuch systems (assuming you have installed Python 3).\n\nThe application uses some third party libraries as indicated in\n``requirements.txt``.\n\nThis project is designed for Linux, though I do not expect there to be\nany issues on other platforms. As a consequence the commands given below\nare designed for a Linux shell. Lines beginning with a dollar sign ($)\nindicate commands you enter into your terminal, other lines are output\nfrom running those commands\n\nGetting Python 3\n----------------\n\nTo see if you already have Python 3 installed, try running (the lines\nbeginning with $):\n\n.. code:: bash\n\n    $ python --version\n    Python 2.7.14\n    $ python3 --version\n    Python 3.6.3\n\nIf one of these commands gives a version number >= 3, you have Python 3\nthrough that command (without ``--version``, of course). In the example\nabove, I need to use the command ``python3`` in order to use the correct\nversion of Python for this emulator.\n\nOtherwise, you could try to install Python 3 via your package manager.\nDepending on which Linux distribution you use, you could try something\nlike\n\n.. code:: bash\n\n    $ apt install python3\n\nor\n\n.. code:: bash\n\n    $ sudo apt install python3\n\nGetting pip for Python 3\n------------------------\n\nYou need pip to (easily) install Python packages. If your Linux\ndistribution came with Python 2 and pip, the pip you have might not work\nfor Python 3. Let us first check that:\n\n.. code:: bash\n\n    $ pip --version\n    pip 9.0.1 from /usr/lib/python2.7/site-packages (python 2.7)\n    $ pip3 --version\n    pip 9.0.1 from /usr/lib/python3.6/site-packages (python 3.6)\n\nAs with the Python version commands in the last section, I have to use\n``pip3``. If I just used ``pip`` packages would be installed for Python\n2, which I do not want.\n\nPip should come with newer versions of Python. If you have a new version\nof Python, but no pip, you might need to install it seperately. You\ncould try (depending on your Linux distribution)\n\n.. code:: bash\n\n    $ apt install python3-pip\n\nor\n\n.. code:: bash\n\n    $ sudo apt install python3-pip\n\nInstallation\n============\n\nInstallation includes\n\n-  Downloading and installing dependencies\n-  Downloading the emulator\n-  Storing the emulator libraries where your other Python libraries are\n-  Adding a small script to easily start the emulator\n\nPip way\n-------\n\nThe recommended way to quickly install and use the emulator, is to\ninstall it via pip. The name on PyPI (where pip gets the software from)\nis ``llvm-minusminus-emulator`` [1]_.\n\nMake sure that you have Python 3 and pip installed (see above). Then\ninstall the emulator by running\n\n.. code:: bash\n\n    $ pip3 install llvm-minusminus-emulator\n\nIf all goes well, you are now ready to use the emulator.\n\nGit way\n-------\n\nTo get the very latest version, you can do the following\n\nIf you have not already, download the code.\n\n.. code:: bash\n\n    $ cd path/to/folder/where/you/want/to/store/the/emulator\n    $ git clone git@gitlab.com:cfreksen/llvm--emulator.git\n\nTo install the software, you can use ``pip`` on the folder containing\n``setup.py``:\n\n.. code:: bash\n\n    $ cd path/to/folder/where/you//stored/the/emulator/llvm--emulator\n    $ pip3 install .\n\nYou should now be ready to use the software.\n\nUninstalling\n------------\n\nTo remove the emulator, just uninstall via pip:\n\n.. code:: bash\n\n    $ pip3 uninstall llvm-minusminus-emulator\n\nUsage\n=====\n\nIf installing the emulator went well, a script (``llvm--emulator``)\nshould have been added to your ``bin`` folder. This means that you can\nstart the emulator (wherever you are), by running that script:\n\n.. code:: bash\n\n    $ llvm--emulator --help\n    usage: llvm--emulator [-h] {auto} ...\n\n    A hacky LLVM-- emulator/debugger\n\n    positional arguments:\n      {auto}\n        auto      Automatically step through llvm in a given file\n\n    optional arguments:\n      -h, --help  show this help message and exit\n\nTo automatically step through a LLVM file (and be quite verbose about\nit), you can use the ``auto`` command:\n\n.. code:: bash\n\n    $ llvm--emulator auto path/to/your/file.ll\n\nWhen running the emulator you might get messages like the following:\n\n.. code:: bash\n\n    WARNING: Couldn't open 'parser.out'. [Errno 13] Permission denied: '/usr/lib/python3.6/site-packages/llvm_emulator/parser.out'\n    WARNING: Couldn't create 'parsetab'. [Errno 13] Permission denied: '/usr/lib/python3.6/site-packages/llvm_emulator/parsetab.py'\n\nThis is because the script does not have permission to write files among\nyour Python libraries. This is because the parser inside the emulator\ntries to cache its parsing table (think of ``tiger.grm.sml``) where the\nparsing code is located. If does not have permission to do that, it\nstill parses your LLVM code; it just needs to rebuild the parsing table\nnext time you run the emulator. These warnings should be safe to ignore.\n\nI have tried to fix this issue without success, so hopefully you can\nlive with a few warning messages.\n\nExample\n-------\n\nLet us say, that we have the following LLVM-- code in ``some_file.ll``\n\n.. code:: llvm\n\n    %Ttigermain = type { i64, i64, i64 }\n\n    define i64 @tigermain (i64 %U_mainSL_8, i64 %U_mainDummy_9) {\n        %t = alloca %Ttigermain\n        %a = getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 1\n        store i64 9, i64* %a\n        %r = load i64, i64* %a\n        %s = add i64 100, %r\n        %b = getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 0\n        store i64 %s, i64* %b\n        ret i64 %s\n    }\n\nThen we run the emulator:\n\n.. code:: bash\n\n    $ llvm--emulator -a some_file.ll\n    Parsing some_file.ll\n    Beginning execution of some_file.ll\n    Heap after globals are allocated:\n    [None]\n\n    Evaluating alloca %Ttigermain\n    alloca {i64, i64, i64}  -->  allocating 3 cells\n    %t <- 1\n\n    Evaluating getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 1\n    Gep formula: 1 + 0 * 3 + (1)\n    %a <- 2\n\n    Evaluating store i64 9, i64* %a\n    heap[2] <- 9\n\n    Evaluating load i64, i64* %a\n    load heap[2]\n    %r <- 9\n\n    Evaluating add i64 100, %r\n    add 100, 9\n    %s <- 109\n\n    Evaluating getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 0\n    Gep formula: 1 + 0 * 3 + 0\n    %b <- 1\n\n    Evaluating store i64 %s, i64* %b\n    heap[1] <- 109\n\n    Evaluating ret i64 %s\n    Returning 109\n\n    Stepping done!\n    Final ssa_env: {'U_mainSL_8': 1234, 'U_mainDummy_9': 5678, 't': 1, 'a': 2, 'r': 9, 's': 109, 'b': 1}\n    Final heap: [None, 109, 9, <<Garbage>>]\n    Program resulted in 109 after 8 steps\n\nThis shows which values variables have as they are encountered as well\nas the order the instructions are evaluated.\n\nAlternatives\n------------\n\nIf the ``llvm--emulator`` script does not work for you, you can inspect\nit in the ``path/to/emulator/repository/bin/`` folder (assuming you have\nthe source code. See the section 'Installation:Git Way', or look at the\ncode online on https://gitlab.com/cfreksen/llvm--emulator). It should be\nclear enough what the script does, and if you know a bit of Python, you\nshould be able to tweak it to your needs.\n\nKnown Issues/Missing Features\n=============================\n\nHere some of the known major issues/missing features are listed. This\nlist might be updated, should the issues be fixed/the features\nimplemented:\n\nInteractive mode\n----------------\n\nThere is currently no support for stepping through the code one key\npress at a time. Similarly, there is no support for inserting\nbreakpoints, or looking up the current values in memory/registers via\ncommands.\n\nBuiltin functions\n-----------------\n\nWhen generating LLVM code from Tiger code, there can be several calls to\nfunctions defined in a file called ``runtime.c``. Many of these\nfunctions are not implemented in the emulator. However, ``allocRecord``,\n``initArray``, and ``print`` are so that will hopefully be enough for\nthe majority of your LLVM programs.\n\nLicense\n=======\n\nThe code in this project is licensed under GPLv3+. The full licensing\ntext can be found in the ``LICENSE`` file, while a small but descriptive\nheader is:\n\n    LLVM-- Emulator -- A simple hacky emulator and debugger for LLVM--\n    Copyright \u00a9 2017 Casper Freksen\n\n    This program is free software: you can redistribute it and/or modify\n    it under the terms of the GNU General Public License as published by\n    the Free Software Foundation, either version 3 of the License, or\n    (at your option) any later version.\n\n    This program is distributed in the hope that it will be useful, but\n    WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\n    General Public License for more details.\n\n    You should have received a copy of the GNU General Public License\n    along with this program. If not, see http://www.gnu.org/licenses/.\n\n.. [1]\n   I know the name is ugly, but Python packaging was not happy about the\n   double dash in ``llvm--emulator``, and ``llvm-emulator`` makes it\n   sound like it covers the entire LLVM IR language.",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://gitlab.com/cfreksen/llvm--emulator",
        "keywords": "llvm debugger",
        "license": "GPLv3+",
        "maintainer": "",
        "maintainer_email": "",
        "name": "llvm-minusminus-emulator",
        "package_url": "https://pypi.org/project/llvm-minusminus-emulator/",
        "platform": "",
        "project_url": "https://pypi.org/project/llvm-minusminus-emulator/",
        "project_urls": {
            "Homepage": "https://gitlab.com/cfreksen/llvm--emulator"
        },
        "release_url": "https://pypi.org/project/llvm-minusminus-emulator/1.1.0/",
        "requires_dist": null,
        "requires_python": "~=3.5",
        "summary": "A simple hacky emulator/debugger for LLVM--",
        "version": "1.1.0"
    },
    "last_serial": 3333270,
    "releases": {
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4237b0658d69819d5a8e8089461df4af",
                    "sha256": "29aa02801390560cf3f390026112ecebe56a72d16fce826698f6453282b187d2"
                },
                "downloads": -1,
                "filename": "llvm-minusminus-emulator-1.0.1.tar.gz",
                "has_sig": true,
                "md5_digest": "4237b0658d69819d5a8e8089461df4af",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": "~=3.5",
                "size": 32906,
                "upload_time": "2017-11-09T16:02:41",
                "url": "https://files.pythonhosted.org/packages/b3/75/a17528999a800cb0d1e5fa9d595e33a1ad03346ef4eb189acbd21895e868/llvm-minusminus-emulator-1.0.1.tar.gz"
            }
        ],
        "1.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "15164a511104aaf3b74e76adb1e7da9c",
                    "sha256": "87958c08d4addd385dc90bf818d2313dc8b0a83efa74555b35e26cf8c1aa0769"
                },
                "downloads": -1,
                "filename": "llvm-minusminus-emulator-1.0.2.tar.gz",
                "has_sig": true,
                "md5_digest": "15164a511104aaf3b74e76adb1e7da9c",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": "~=3.5",
                "size": 33919,
                "upload_time": "2017-11-09T16:13:12",
                "url": "https://files.pythonhosted.org/packages/13/08/9a2a6fb2d3ac7ca21a8bfd1fc5cbaec504f2128ae5aad842c2c3f9377fe3/llvm-minusminus-emulator-1.0.2.tar.gz"
            }
        ],
        "1.0.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "94cfe40601c504b9fa6a625e22dd3cce",
                    "sha256": "caf0de1ec617df4eb33f58ca3cc92d9199fd4fe6eb01eda438a7a18e9fbf6d29"
                },
                "downloads": -1,
                "filename": "llvm-minusminus-emulator-1.0.3.tar.gz",
                "has_sig": true,
                "md5_digest": "94cfe40601c504b9fa6a625e22dd3cce",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": "~=3.5",
                "size": 33987,
                "upload_time": "2017-11-09T17:25:06",
                "url": "https://files.pythonhosted.org/packages/b1/a5/6e1a993b9be84cccdf800bf7c2693e514915b600b756e672c97ce3ec4b84/llvm-minusminus-emulator-1.0.3.tar.gz"
            }
        ],
        "1.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "3b1c54cab5431b9ce1b5581eb48834b0",
                    "sha256": "e75a5702d267540c570c71cc8b9022c9a99aa33f12845655ce8241e3359cd286"
                },
                "downloads": -1,
                "filename": "llvm-minusminus-emulator-1.1.0.tar.gz",
                "has_sig": true,
                "md5_digest": "3b1c54cab5431b9ce1b5581eb48834b0",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": "~=3.5",
                "size": 35351,
                "upload_time": "2017-11-14T23:12:47",
                "url": "https://files.pythonhosted.org/packages/bc/da/0cfa3d50d39395bcc71c98a9cb9dc799ea4513836bc690bd1ff4224ae803/llvm-minusminus-emulator-1.1.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "3b1c54cab5431b9ce1b5581eb48834b0",
                "sha256": "e75a5702d267540c570c71cc8b9022c9a99aa33f12845655ce8241e3359cd286"
            },
            "downloads": -1,
            "filename": "llvm-minusminus-emulator-1.1.0.tar.gz",
            "has_sig": true,
            "md5_digest": "3b1c54cab5431b9ce1b5581eb48834b0",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "~=3.5",
            "size": 35351,
            "upload_time": "2017-11-14T23:12:47",
            "url": "https://files.pythonhosted.org/packages/bc/da/0cfa3d50d39395bcc71c98a9cb9dc799ea4513836bc690bd1ff4224ae803/llvm-minusminus-emulator-1.1.0.tar.gz"
        }
    ]
}