Skip to content

Commit eda1672

Browse files
committed
Update v3/docs/developer-overview.md
1 parent 635498e commit eda1672

1 file changed

Lines changed: 33 additions & 3 deletions

File tree

v3/docs/developer-overview.md

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1-
# Overview for Developers of Online Python Tutor
1+
# Developer's Guide Overview
22

33
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
57

68
Look at the Git history to see when this document was last updated; the more time
79
elapsed since that date, the more likely things are out-of-date. Please email
@@ -73,5 +75,33 @@ The backend consists of:
7375
pg_encoder.py : encodes the trace format into JSON to send to frontend
7476
generate_json_trace.py : script to test the backend independent of the frontend
7577
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>
77101
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

Comments
 (0)