From 2c9ef8283ab065ee34cdf2b05655476b8c5a8cf9 Mon Sep 17 00:00:00 2001 From: Noah Pederson Date: Fri, 27 Oct 2023 19:32:09 -0500 Subject: [PATCH] Adds doc with suggestions for stdlib dev. --- doc/guide/hacking-on-the-stdlib.md | 33 ++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 doc/guide/hacking-on-the-stdlib.md diff --git a/doc/guide/hacking-on-the-stdlib.md b/doc/guide/hacking-on-the-stdlib.md new file mode 100644 index 000000000..909830423 --- /dev/null +++ b/doc/guide/hacking-on-the-stdlib.md @@ -0,0 +1,33 @@ +# Hacking on the Standard Library + +Gerbil is a growing project and your contributions are welcome! + +When working on modifications to the standard library, it's common to encountere errors +such as: + +``` +*** ERROR IN gx#core-expand-import%__% -- +*** ERROR IN "file.ss"@1.9 +--- Syntax Error: Cannot find library module +... form: :std/my/module +``` +This typically because the `gxi` or `gxc` being used is looking at the installed +standard library which will not contain your changes. To address this, run your +environment with the `build.sh` script after building. + +Example build: + +```shell +./build.sh +``` + +To test your local changes rebuild the stdlib and then use the locally built `gxi` with +the following commands: + +```shell +./build.sh stdlib +./build.sh env gxi ../your-test-file.ss +``` +**NOTE:** the execution environment when using `./build.sh env` is in the `src/` folder +in the root of the Gerbil repo. Absolute paths work as normal, but relative paths must +be adjusted for `PWD` change.