mighty-gerbils · vyzo · Sep 7, 2023 · Sep 7, 2023
diff --git a/doc/guide/README.md b/doc/guide/README.md
@@ -39,8 +39,8 @@ to the configure script (see below).
 
 
 ## Build Instructions
-After unpacking a release or checking out the source code from Github, let
-`$GERBIL_HOME` be the top directory of Gerbil source.
+After unpacking a release or checking out the source code from Github,
+cd into the `gerbil` directory.
 
 Gerbil takes quite a while to compile, if you wish it to build faster, you can:
 ```

diff --git a/doc/guide/bootstrap.md b/doc/guide/bootstrap.md
@@ -2,7 +2,7 @@
 
 If you have made changes to the core prelude, expander, or the compiler, you will also want to update the compiled bootstrap modules.
 
-This can be accomplished with the following incantations in `$GERBIL_HOME/src`.
+This can be accomplished with the following incantations in `$GERBIL_SRCDIR/src`.
 
 To compile the core prelude bootstrap:
 ```

diff --git a/doc/guide/emacs.md b/doc/guide/emacs.md
@@ -11,8 +11,7 @@ You can add it to your autoload path (eg by linking in `$HOME/.emacs.d`) and add
 (autoload 'gerbil-mode "gerbil-mode" "Gerbil editing mode." t)
 ```
 
-You should further utilize Gambit's inferior mode, as it offers debugger integration with sources on emacs.
-It lives in [$GAMBIT_HOME/share/emacs/site-lisp/gambit.el](https://github.com/gambit/gambit/blob/master/misc/gambit.el).
+You should further utilize Gambit's inferior mode, as it offers debugger integration with sources on emacs. By default it is installed in `$GERBIL_INSTALL_PREFIX/share/emacs/site-lisp/gambit.el` alongside `gerbil-mode.el`.
 
 
 You can add it to your autoload path and then add this to your `.emacs`:
@@ -24,16 +23,15 @@ You can add it to your autoload path and then add this to your `.emacs`:
 You can then make `gxi` your scheme program by setting `scheme-program-name`:
 ```
 (defvar gerbil-program-name
-  (expand-file-name "/opt/gerbil/bin/gxi")) ; Set this for your GERBIL_HOME
+  (expand-file-name "/opt/gerbil/bin/gxi")) ; default installation, adjust for your GERBIL_INSTALL_PREFIX
 (setq scheme-program-name gerbil-program-name)
 ```
 
 And you can now run Gerbil with `M-x run-scheme`.
 
 Note that both `gerbil-mode.el` and `gambit.el` are installed by
-default in `GERBIL_HOME/share/emacs/site-lisp` when installing gerbil.
+default in `$GERBIL_INSTAL_PREFIX/share/emacs/site-lisp` when installing gerbil.
 
-N.B. Up to v0.16 the editing mode file was gerbil.el. After `v0.16-48-g46f10016`, gerbil mode has been migrated to gerbil-mode.el; see [#510](https://github.com/vyzo/gerbil/issues/510) for migrating.
 
 ## Treadmill: An Alternative
 
@@ -44,13 +42,13 @@ N.B. Up to v0.16 the editing mode file was gerbil.el. After `v0.16-48-g46f10016`
 Gerbil comes with a tool to build emacs tags from Gerbil sources, called `gxtags`.
 
 By default, the build script creates tags for the system in
-`$GERBIL_HOME/src/TAGS`. This tags table contains all exported symbols
+`$GERBIL_SRCDIR/src/TAGS`. This tags table contains all exported symbols
 for the Gerbil prelude, standard library, compiler and expander. They
 allow you to easily browse Gerbil code, and also explore the system.
 
 You can load the tags table with `M-x visit-tags-table` and selecting the tags file.
 If you want it to be a permanent part of your editing experience, you can add
-`$GERBIL_HOME/src` to your tags table list by adding this to your .emacs:
+`$GERBIL_SRCDIR/src` to your tags table list by adding this to your .emacs:
 ```
 (visit-tags-table "~/gerbil/src/TAGS")
 ```
@@ -99,12 +97,12 @@ See drewc's [guide](https://gist.github.com/drewc/5f260537b7914a2b999c8a539fb480
 ## Use-Package Example Configuration
 
 Example [use-package](https://github.com/jwiegley/use-package) definition to get you
-hacking in no time. All you have to do is to set the environment variables
-`GERBIL_HOME` and `GAMBIT_HOME` and copy the code snippet below into your Emacs config.
+hacking in no time. All you have to do is to set the environment variables `GERBIL_INSTALL_PREFX`
+and `GERBIL_SRCDIR` and copy the code snippet below into your Emacs config.
 
 ``` elisp
 (use-package gerbil-mode
-  :when (getenv "GERBIL_HOME")
+  :when (getenv "GERBIL_INSTALL_PREFIX")
   :ensure nil
   :defer t
   :mode (("\\.ss\\'"  . gerbil-mode)
@@ -116,24 +114,22 @@ hacking in no time. All you have to do is to set the environment variables
               :map gerbil-mode-map
               (("C-S-l" . clear-comint-buffer)))
   :init
-  (setf gambit (getenv "GAMBIT_HOME"))
-  (setf gerbil (getenv "GERBIL_HOME"))
+  (setf gambit (getenv "GAMBIT_INSTALL_PREFIX"))
+  (setf gerbil (getenv "GERBIL_INSTALL_PREFIX"))
+  (setf gerbil-src (getenv "GERBIL_SRCDIR"))
   (autoload 'gerbil-mode
-    (concat gerbil "/etc/gerbil-mode.el") "Gerbil editing mode." t)
+    (concat gerbil "/share/emacs/site-list/gerbil-mode.el") "Gerbil editing mode." t)
   :hook
   ((gerbil-mode . linum-mode)
    (inferior-scheme-mode-hook . gambit-inferior-mode))
   :config
   (require 'gambit
-           (concat gambit
-                   (if (equal "nixos" (system-name))
-                     "/share/emacs/site-lisp/gambit.el"
-                     "/misc/gambit.el")))
+           (concat gambit "/share/emacs/site-lisp/gambit.el"))
   (setf scheme-program-name (concat gerbil "/bin/gxi"))
 
   (let ((tags (locate-dominating-file default-directory "TAGS")))
     (when tags (visit-tags-table tags)))
-  (visit-tags-table (concat gerbil "/src/TAGS"))
+  (visit-tags-table (concat gerbil-src "/src/TAGS"))
 
   (when (package-installed-p 'smartparens)
     (sp-pair "'" nil :actions :rem)

diff --git a/doc/guide/intro.md b/doc/guide/intro.md
@@ -779,20 +779,22 @@ you need the following import statement:
 The library module is defined in a file named `json.ss` in the Gerbil
 std library source tree. The module declares that it is part of the
 `std/text` package, which places compiler artefacts in the
-`$GERBIL_HOME/lib/std/text` directory.
+`$GERBIL_PREFIX/lib/std/text` directory.
 The namespace prefix for identifiers defined in the module is
 `std/text/json#`.
 
 When writing a library module, you should choose an appropriate package
 for your code.
 The package is specified with a `package: package-path` declaration
-at the top of a module. It effects the namespace of the module and
+at the top of a module or with a `package:` entry in the `gerbil.pkg`
+plist. It effects the namespace of the module and
 placement of compiled code.
 
-By default library modules are looked up in the `$GERBIL_HOME/lib` and
-`~/.gerbil/lib` directories. You can specify additional directories to
-be searched with the `GERBIL_LOADPATH` environment variable.  You can
-also modify the load-path at runtime with `add-load-path`.
+By default library modules are looked up in the `GERBIL_INSTALL_PREFIX/lib`
+and `${GERBIL_PATH:~/.gerbil}/lib` directories.  You can specify
+additional directories to be searched with the `GERBIL_LOADPATH`
+environment variable.  You can also modify the load-path at runtime
+with `add-load-path`.
 
 #### Building Libraries
 
@@ -805,8 +807,10 @@ Here, we call it `util` with the expectation that the library
 and module will grow further:
 ```
 $ mkdir example
+$ cat > example/gerbil.pkg <<EOF
+(package: example)
+EOF
 $ cat > example/util.ss <<EOF
-package: example
 (export with-display-exception)
 (extern (display-exception display-exception))
 (def (with-display-exception thunk)
@@ -824,7 +828,7 @@ $ gxi
 > (import :example/util)
 ```
 
-By default, the compiler will place compiled modules in `~/.gerbil/lib`.
+By default, the compiler will place compiled modules in `${GERBIL_PATH:~/.gerbil}/lib`.
 If you want a separate directory structure for your library, you can
 specify a different directory with the `-d` option:
 ```
@@ -1496,7 +1500,7 @@ tool:
 $ gxensemble cookie
 ```
 
-This will generate a random 256-bit cookie in `$GERBIL_PATH/ensemble/cookie`.
+This will generate a random 256-bit cookie in `${GERBIL_PATH:~/.gerbil}/ensemble/cookie`.
 Note that it will not overwrite an existing cookie, unless you force
 it with `-f`.
 

diff --git a/doc/guide/shell.md b/doc/guide/shell.md
@@ -42,7 +42,7 @@ Procedural forms of `@expand` and `@expand1`.
 
 ## Customizing the Interactive Shell
 
-Whenever gxi is run interactively, after loading and initializing the runtime and expander, it loads the library interactive initialization file `$GERBIL_HOME/lib/init.ss` (source: init.ss) which greets the user, imports the `:gerbil/gambit` prelude module and provides the interactive development forms documented above.
+Whenever gxi is run interactively, after loading and initializing the runtime and expander, it loads the library interactive initialization file `$GERBIL_INSTALL_PREFIX/lib/init.ss` (source: init.ss) which greets the user, imports the `:gerbil/gambit` prelude module and provides the interactive development forms documented above.
 
 After loading the library initialization file, gxi checks for a user specific interactive initialization file. If the file `~/.gerbil/init.ss` exists, then it is loaded in the top (interaction) environment. This allows you to customize your interactive Gerbil shell.
 
@@ -55,7 +55,7 @@ Here is a small example `~/.gerbil/init.ss` that provides useful functionality:
 (add-load-path "/path/to/your/gerbil/project/src")
 
 ;; only useful if you intend to do core Gerbil development
-;; (add-load-path (path-expand "src" (getenv "GERBIL_HOME")))
+;; (add-load-path (path-expand "src" (getenv "GERBIL_SRCDIR")))
 
 ;; import your personal gerbil libraries
 (import :my/stuff :more/of/my/stuff)

diff --git a/doc/tutorials/httpd.md b/doc/tutorials/httpd.md
@@ -4,17 +4,8 @@
 
 In this tutorial we illustrate web programming with the embedded Gerbil http server.
 
-This tutorial requires a very recent version of Gambit that supports raw devices ([gambit#272](https://github.com/gambit/gambit/pull/272)).
-
-The source code for the tutorial  is available at [$GERBIL_HOME/src/tutorial/httpd](https://github.com/vyzo/gerbil/tree/master/src/tutorial/httpd).
-You can build the source code using the build script:
-```bash
-$ cd $GERBIL_HOME/src/tutorial/httpd
-$ ./build.ss
-
-```
-
-This builds a single binary, `simpled`, in the tutorial directory.
+The source code for the tutorial is available at [src/tutorial/httpd](https://github.com/vyzo/gerbil/tree/master/src/tutorial/httpd).
+You can build the code using the [build script](https://github.com/vyzo/gerbil/tree/master/src/tutorial/httpd/build.ss).
 
 ## A Simple Web Server
 
@@ -193,15 +184,15 @@ location / {
         # Forward requests to Gerbil production port
         proxy_pass http://localhost:8080;
         proxy_buffering off; # Single page apps work faster with it
-        proxy_set_header X-Real-IP $remote_addr; 
+        proxy_set_header X-Real-IP $remote_addr;
     }
 }
 ```
 
 Notes:
 
 - www.example.com should be replaced with your domain name or server IP address. Note that multiple values are supported, such as `server_name  domain1.com www.domain1.com;`
-- The line `proxy_pass http://localhost:8080;` should be set to the appropriate port as determined in your Gerbil `getopt` configuration. Replace *8080* with the port number that Gerbil's httpd will be listening on. 
+- The line `proxy_pass http://localhost:8080;` should be set to the appropriate port as determined in your Gerbil `getopt` configuration. Replace *8080* with the port number that Gerbil's httpd will be listening on.
 
 If you have edited the file /etc/nginx/sites-available/default, you are ready to go. If you've created another profile, you will need to symlink to this file in /etc/nginx/sites-enabled.
 
@@ -224,7 +215,6 @@ After=network.target
 StartLimitIntervalSec=0
 
 [Service]
-Environment=GERBIL_HOME=/path/to/gerbil/home
 Type=simple
 Restart=always
 RestartSec=5
@@ -240,7 +230,6 @@ WantedBy=multi-user.target
 In the above example:
 
 - Replace `my-server website` with an appropriate description.
-- Replace `/path/to/gerbil/home` with the appropriate GERBIL_HOME environment path.
 - Replace `/srv/my-server` with an appropriate working directory, possibly the directory of your project on the server.
 - Replace `/srv/my-server/my-server` with the path to your compiled Gerbil binary.
 - Replace `web` with an existing user and group (as created with `useradd`). Systemd will run your server with the privileges of this user. Note that this user must have read and execute privileges for your binary and workingDirectory.

diff --git a/doc/tutorials/kvstore.md b/doc/tutorials/kvstore.md
@@ -9,27 +9,12 @@ programmatic API or through the command line.
 
 This tutorial requires [LMDB](https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database).
 You need to first install it, and then build the LMDB bindings in stdlib, as they are
-not built by default.
+not built by default. You can do this during installation by running `configure` with
+the `--enable-lmdb` option.
 
-So, after installing LMDB, enable and build the LMDB bindings:
-```bash
-$ cd $GERBIL_HOME/src
-$ sed -i 's/lmdb #f/lmdb #t/' std/build-features.ss
-$ ./build.sh stdlib
-...
-```
 
-The source code for the tutorial is available at [$GERBIL\_HOME/src/tutorial/kvstore](https://github.com/vyzo/gerbil/tree/master/src/tutorial/kvstore).
-You can now build the kvstore tutorial using the [build script](https://github.com/vyzo/gerbil/tree/master/src/tutorial/kvstore/build.ss) so that you can use the programs:
-```bash
-$ cd $GERBIL_HOME/src/tutorial/kvstore
-$ ./build.ss
-... compile proto
-... compile server
-... compile kvstore-svc
-... compile kvstorec
-... compile exe kvstorec -> ~/.gerbil/bin/kvstorec
-```
+The source code for the tutorial is available at [src/tutorial/kvstore](https://github.com/vyzo/gerbil/tree/master/src/tutorial/kvstore).
+You can build the kvstore tutorial code using the [build script](https://github.com/vyzo/gerbil/tree/master/src/tutorial/kvstore/build.ss) so that you can use the programs.
 
 ## The kvstore protocol
 

diff --git a/doc/tutorials/languages.md b/doc/tutorials/languages.md
@@ -4,19 +4,8 @@ Here we explore language extensibility in Gerbil by defining custom preludes.
 
 ## Preliminaries
 
-The source code for all the examples is available at [$GERBIL_HOME/src/tutorial/lang](https://github.com/vyzo/gerbil/tree/master/src/tutorial/lang).
-You should visit that directory and compile the tutorial custom preludes so that you can try out
-the examples in the interpreter:
-```bash
-$ cd $GERBIL_HOME/src/tutorial/lang
-$ ./build.ss
-... compile dot-app
-... compile auto-export
-... compile sexp
-... compile scuby-etc
-... compile scuby-grammar
-... compile scuby
-```
+The source code for all the examples is available at [src/tutorial/lang](https://github.com/vyzo/gerbil/tree/master/src/tutorial/lang).
+You can build the tutorial code using the [build script](https://github.com/vyzo/gerbil/tree/master/src/tutorial/lang/build.ss).
 
 ## Custom Languages in the REPL
 

diff --git a/doc/tutorials/proxy.md b/doc/tutorials/proxy.md
@@ -18,7 +18,7 @@ The last program is an anonymous SOCKS4 proxy, written again using the
 
 ## Preliminaries
 
-The source code for the tutorial is available at [$GERBIL_HOME/src/tutorial/proxy](https://github.com/vyzo/gerbil/tree/master/src/tutorial/proxy).
+The source code for the tutorial is available at [src/tutorial/proxy](https://github.com/vyzo/gerbil/tree/master/src/tutorial/proxy).
 You can build the programs using the [build script](https://github.com/vyzo/gerbil/tree/master/src/tutorial/proxy/build.ss).
 
 ## A Transparent TCP Proxy