|
1 | | -# Overview for Developers of Online Python Tutor |
| 1 | +# Developer's Guide Overview |
2 | 2 |
|
3 | 3 | This document is a starting point for anyone who wants to hack on |
4 | | -Online Python Tutor (thereafter abbreviated as OPT). |
| 4 | +Online Python Tutor (thereafter abbreviated as OPT). View it online at: |
| 5 | + |
| 6 | +https://github.com/pgbovine/OnlinePythonTutor/blob/master/v3/docs/developer-overview.md |
5 | 7 |
|
6 | 8 | Look at the Git history to see when this document was last updated; the more time |
7 | 9 | elapsed since that date, the more likely things are out-of-date. Please email |
@@ -73,5 +75,33 @@ The backend consists of: |
73 | 75 | pg_encoder.py : encodes the trace format into JSON to send to frontend |
74 | 76 | generate_json_trace.py : script to test the backend independent of the frontend |
75 | 77 | app.yaml and pythontutor.py : config files for Google App Engine |
76 | | - web_exec.py : example CGI script for deploying on CGI-enabled webservers |
| 78 | + web_exec.py : example CGI script for deploying backend on CGI-enabled webservers |
| 79 | + |
| 80 | + |
| 81 | +## Hacking on the backend |
| 82 | + |
| 83 | +To modify the backend, you will mainly need to understand `pg_logger.py` and `pg_encoder.py`. |
| 84 | + |
| 85 | +### Two quick tips for starters |
| 86 | + |
| 87 | +First, run `generate_json_trace.py` to see the trace that the backend generates for a given input Python program. |
| 88 | +This is the main way to do an "end-to-end" test on your backend modifications. For example, if you wrote a Python |
| 89 | +program stored in `example.py`, then running: |
| 90 | + |
| 91 | + python generate_json_trace.py example.py |
| 92 | + |
| 93 | +will print a JSON-formatted execution trace to stdout. This is exactly what the backend sends to the frontend. |
| 94 | +(Actually not quite: the sent trace is actually compressed to eliminate all extraneous spaces and newlines. |
| 95 | +But for testing, I've made the trace more human-readable.) |
| 96 | + |
| 97 | +Second, when you're "print debugging" in the backend, you can't simply print to stdout, since `pg_logger.py` |
| 98 | +*redirects* stdout to a buffer. Instead, you need to write all of your print statements as: |
| 99 | + |
| 100 | + print >> sys.stderr, <debug message to print> |
77 | 101 | |
| 102 | +so that the output goes to stderr. |
| 103 | + |
| 104 | +The easiest way to debug is to insert in print statements (to stderr) and then run `generate_json_trace.py` on |
| 105 | +small code examples. |
| 106 | + |
| 107 | +### |
0 commit comments