README.rst 4.26 KB
Newer Older
John Zhang's avatar
John Zhang committed
1 2 3
==============================
PyPy-Mu: A Mu Backend for PyPy
==============================
Zixian Cai's avatar
Zixian Cai committed
4 5
.. image:: https://gitlab.anu.edu.au/mu/mu-client-pypy/badges/mu-rewrite/build.svg
    :target: https://gitlab.anu.edu.au/mu/mu-client-pypy/commits/mu-rewrite
Samuele Pedroni's avatar
Samuele Pedroni committed
6

John Zhang's avatar
John Zhang committed
7
Welcome to PyPy-Mu!
Samuele Pedroni's avatar
Samuele Pedroni committed
8

John Zhang's avatar
John Zhang committed
9 10
PyPy-Mu is a fork of `PyPy <http://pypy.org>`__ that aims to
add a `Mu Micro Virtual Machine <http://microvm.org>`__ backend for it.
Samuele Pedroni's avatar
Samuele Pedroni committed
11

John Zhang's avatar
John Zhang committed
12 13
This project is currently under active development,
right now we can compile PyPy interpreter with `--no-allworkingmodules` option.
Armin Rigo's avatar
Armin Rigo committed
14

John Zhang's avatar
John Zhang committed
15 16
Building
========
Armin Rigo's avatar
Armin Rigo committed
17

John Zhang's avatar
John Zhang committed
18 19
Obtaining a Mu implementation
-----------------------------
Samuele Pedroni's avatar
Samuele Pedroni committed
20

John Zhang's avatar
John Zhang committed
21 22 23 24
The reference implementation (Holstein) for Mu can be found `here <https://gitlab.anu.edu.au/mu/mu-impl-ref2>`__.
Build the Mu implementation, make sure to build the C binding as well.
The fast implementation (Zebu) for Mu can be found `here <https://gitlab.anu.edu.au/mu/mu-impl-fast>`__.
This implementation is still in progress.
Samuele Pedroni's avatar
Samuele Pedroni committed
25

John Zhang's avatar
John Zhang committed
26 27
Reference implementation is targetted by default.
You can specify which implementation to target using the flag ``--mu-impl=<impl>`` to RPython.
Samuele Pedroni's avatar
Samuele Pedroni committed
28

29

John Zhang's avatar
John Zhang committed
30 31 32 33
Setting up environment variable
-------------------------------
.. role:: bash(code)
    :language: bash
34

John Zhang's avatar
John Zhang committed
35 36 37
RPython Mu API binding requires ``$MU_HOLSTEIN`` and/or ``$MU_ZEBU`` environment variable to be set.
You need to set them to point to the cloned Mu implementation repository.

John Zhang's avatar
John Zhang committed
38 39 40 41 42 43 44 45
Apply Patch to PyPy/RPython Source Code
---------------------------------------

You may need to also apply the patch to PyPy/RPython source code in fixing some problems.
Some of these changes are acknowledged and committed on the PyPy upstream, some are yet resolved.

::

46
    $ git apply *.patch
John Zhang's avatar
John Zhang committed
47 48 49
    


John Zhang's avatar
John Zhang committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
Compiling & Executing RPython Target
------------------------------------

Specify :bash:`-b mu` option to compile using the Mu backend:

::

    $ rpython/bin/rpython -b mu <target>

This builds the program bundle and dumpts out a boot image as ``<target>-mu`` in the current directory.
The nature of the boot image is implementation defined.
Currently for Holstein, it is a zip file; for Zebu, it is a binary executable.

Note the default Mu code generation backend is API (building bundle through API calls).
This back-end can be slow for compiling larger RPython programs.
An alternative is caching the calls into C sources, and run from there (remove the overhead of RPython FFI).
To specify the code generation back-end, use the flag ``--mu-codegen=<backend>``, which takes ``c`` or ``api``.


To run the dumped boot image under Holstein, use the `runmu.sh` shell script.

::

    $ $MU_HOLSTEIN/tools/runmu.sh <mu-flags> <bootimage> <program-args>
74

John Zhang's avatar
John Zhang committed
75
--------------------------
76

John Zhang's avatar
John Zhang committed
77
Why not try compiling the PyPy interpreter (currently with some limitations)?
Alex Gaynor's avatar
Alex Gaynor committed
78

John Zhang's avatar
John Zhang committed
79
::
80

John Zhang's avatar
John Zhang committed
81 82
    $ PYTHONPATH=$PYPY_MU pypy rpython/bin/rpython -O3 -b mu --mu-vmargs='sosSize=780M\nlosSize=780M' --mu-codegen=c --no-shared $PYPY_MU/pypy/goal/targetpypystandalone.py --no-allworkingmodules
    $ $MU/tools/runmu.sh --staticCheck=false --sourceInfo=false --vmLog=ERROR --sosSize=780M --losSize=780M $PYPY_MU/pypy/bin/pypy-mu
83

Zixian Cai's avatar
Zixian Cai committed
84
Note: when building the pypy interpreter, put the boot image under pypy/bin, so that PyPy can initialise the path correctly.
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112

What can I contribute?
======================

Please have a look at `issues <https://gitlab.anu.edu.au/mu/mu-client-pypy/issues>`__,
but in general we need help in following areas:

- Retargetting RPython JIT to Mu
- Adding more RPython level optimizations
- Getting more modules working on Mu (including Holstien and Zebu).

Where can I get help?
=====================

Following sections are kindly borrowed from `mu-client-ghc <https://gitlab.anu.edu.au/mu/mu-client-ghc>`__.

This project is under active development, at present by Zixian Cai (u5937495@anu.edu.au),
to whom you should direct most (code-related) questions.

Previous work was done by John Zhang (John.Zhang@anu.edu.au),
Timm Allman (tallman@cs.umass.edu) and Ben Kushigian (bkushigian@umass.edu) - they may be in a better position to
answer certain questions about some of the existing code, but bear in mind that
they are not currently working on this project and thus generally have other
things to do with their time.

Administrative inquiries should be sent to the supervisors - namely Steve
Blackburn (steve.blackburn@anu.edu.au) and Tony Hosking
(antony.hosking@anu.edu.au).