From 97e0b2e7d9720e7a1105b4e90275a721c451fd18 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Sun, 2 Jun 2019 21:34:25 -0400 Subject: doc: Add tutorial for REPL setup. * doc/api.texi (Live Coding): New subsection. --- doc/api.texi | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) 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 -- cgit v1.2.3