Update instructions about C runtime

1 files changed, 86 insertions, 19 deletions

diff --git a/doc/gf-developers.t2t b/doc/gf-developers.t2t
index ed336b9a7..5b13986a2 100644
--- a/doc/gf-developers.t2t
+++ b/doc/gf-developers.t2t
@@ -361,35 +361,102 @@ bash setup.sh install
 ```
 This will install
 the C header files and libraries need to write C programs that use PGF grammars.
-Some example C programs are included in the ``utils`` subdirectory, e.g.
-``pgf-translate.c``.
+% Some example C programs are included in the ``utils`` subdirectory, e.g. ``pgf-translate.c``.
 
-When the C run-time system is installed, you can install GF with C run-time
-support by doing
+Depending on what you want to do with the C runtime, you can follow one or more of the following steps.
+
+=== 1. Use the C runtime from another programming language ===
+
+% **If you just want to use the C runtime from Python, Java, or Haskell, you don't need to change your GF installation.**
+
+==== What ====
+
+**This is the most common use case for the C runtime:** compile
+your GF grammars into PGF with the standard GF executable,
+and manipulate the PGFs from another programming language,
+using the bindings to the C runtime.
+
+==== How ====
+
+The Python, Java and Haskell bindings are found in the
+``src/runtime/{python,java,haskell-bind}`` directories,
+respecively. Compile them by following the instructions
+in the ``INSTALL`` or ``README`` files in those directories.
+
+The Python library can also be installed from PyPI using ``pip install pgf``.
+(If you are on Mac and get an error about ``clang`` version, you can try
+some of [these solutions https://stackoverflow.com/questions/63972113/big-sur-clang-invalid-version-error-due-to-macosx-deployment-target]—but be careful before removing any existing installations.)
+
+
+=== 2. Use GF shell with C runtime support ===
+
+==== What ====
+If you want to use the GF shell with C runtime functionalities, then you need to (re)compile GF with special flags.
+
+The GF shell can be started with ``gf -cshell`` or ``gf -crun`` to use
+the C run-time system instead of the Haskell run-time system.
+Only limited functionality is available when running the shell in these
+modes (use the ``help`` command in the shell for details).
+
+(Re)compiling your GF with these flags will also give you
+Haskell bindings to the C runtime, as a library called ``PGF2``,
+but if you want Python or Java bindings, you need to do step 1.
+
+% ``PGF2``: a module to import in Haskell programs, providing a binding to the C run-time system.
+
+==== How ====
+
+If you use cabal, run the following command:
 
 ```
-cabal install -fserver -fc-runtime
+cabal install -fc-runtime
 ```
-from the top directory. This give you three new things:
 
-- ``PGF2``: a module to import in Haskell programs, providing a binding to
-   the C run-time system.
+from the top directory.
 
-- The GF shell can be started with ``gf -cshell`` or ``gf -crun`` to use
-  the C run-time system instead of the Haskell run-time system.
-  Only limited functionality is available when running the shell in these
-  modes (use the ``help`` command in the shell for details).
+If you use stack, uncomment the following lines in the ``stack.yaml`` file:
 
-- ``gf -server`` mode is extended with new requests to call the C run-time
-   system, e.g. ``c-parse``, ``c-linearize`` and ``c-translate``.
+```
+flags:
+   gf:
+     c-runtime: true
+extra-lib-dirs:
+   - /usr/local/lib
+```
+
+and then run ``stack install``, also from the top directory.
+
+
+=== 3. Use GF server mode with C runtime ===
+
+==== What ====
+
+With this feature, ``gf -server`` mode is extended with new requests to call the C run-time
+system, e.g. ``c-parse``, ``c-linearize`` and ``c-translate``.
+
+==== How ====
 
+If you use cabal, run the following command:
+
+```
+cabal install -fc-runtime -fserver
+```
+from the top directory.
+
+If you use stack, add the following lines in the
+If you use stack, uncomment the following lines in the ``stack.yaml`` file:
+
+```
+flags:
+   gf:
+     c-runtime: true
+     server: true
+extra-lib-dirs:
+   - /usr/local/lib
+```
 
-=== Python and Java bindings ===
+and then run ``stack install``, also from the top directory.
 
-The C run-time system can also be used from Python and Java. Python and Java
-bindings are found in the ``src/runtime/python`` and ``src/runtime/java``
-directories, respecively. Compile them by following the instructions in
-the ``INSTALL`` files in those directories.
 
 The Python library can also be installed from PyPI using `pip install pgf`.