summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2019-06-02 21:34:25 -0400
committerDavid Thompson <dthompson2@worcester.edu>2019-06-02 21:34:58 -0400
commit97e0b2e7d9720e7a1105b4e90275a721c451fd18 (patch)
treebebf2ba198ba704f7547c67cef927bce031ffe10 /doc
parentea78262bf60c6f227a9c2641c623bc286af06a33 (diff)
doc: Add tutorial for REPL setup.
* doc/api.texi (Live Coding): New subsection.
Diffstat (limited to 'doc')
-rw-r--r--doc/api.texi33
1 files changed, 33 insertions, 0 deletions
diff --git a/doc/api.texi b/doc/api.texi
index beb9e44..3ea911b 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -350,6 +350,39 @@ The default behavior is to re-throw the error.
@end deffn
+@subsection Live Coding
+
+One of the biggest appeals of any Lisp dialect is the ability to use
+the ``read-eval-print loop'' (REPL for short) to build programs
+iteratively and interactively while the program is running. However,
+programs that run in an event loop and respond to user input (such as
+a video game) require special care for this workflow to be pleasant.
+Chickadee provides no built-in support for live coding, but it's
+fairly easy to hook up a special kind of REPL yourself.
+
+First, create a cooperative REPL server (It's important to use Guile's
+cooperative REPL server instead of the standard REPL server in
+@code{(system repl server)} to avoid thread synchronization issues):
+
+@example
+(use-modules (system repl coop-server))
+
+(define repl (spawn-coop-repl-server))
+@end example
+
+Then, in the game loop's update procedure, add this:
+
+@example
+(poll-coop-repl-server repl)
+@end example
+
+To use the REPL, connect to it via port 37146. Telnet will do the
+trick, but using the @uref{https://www.nongnu.org/geiser/, Geiser}
+extension for Emacs is by far the best way to develop at the REPL with
+Guile. Use @code{M-x connect-to-guile} to connect to the REPL server.
+
+Happy hacking!
+
@node Math
@section Math