Documentation refactoring. No code changes. (0.40.5)

web/documentation/troubleshooting.md

@@ -1,103 +0,0 @@
----
-layout: page
-published: true
-noToc: false
-noComments: false
-noDate: false
-title: Fun - Troubleshooting Guide
-subtitle: Common issues and quick fixes for build, includes, and REPL usage.
-description: Common issues and quick fixes for build, includes, and REPL usage.
-permalink: /documentation/troubleshooting/
-lang: en
-tags:
-- build
-- common
-- fixes
-- includes
-- issues
-- quick
-- troubleshooting
----
-
-
-This page lists common issues when building and running Fun from a source checkout and how to fix them quickly.
-
-## Includes cannot be found
-
-Error example:
-
-<pre>Include error: cannot read '<io/console.fun>'
-</pre>
-Fix:
-- When running from the repository without installing, set `FUN_LIB_DIR` to the local `./lib` directory so angle‑bracket includes resolve correctly.
-
-Linux/macOS/BSD:
-
-<pre>export FUN_LIB_DIR="$(pwd)/lib"
-./build/fun examples/include_lib.fun
-</pre>
-Windows (PowerShell):
-
-<pre>$env:FUN_LIB_DIR = "$PWD/lib"
-./build/fun.exe .\examples\include_lib.fun
-</pre>
-If `FUN_LIB_DIR` is not set, the interpreter tries a compile‑time `DEFAULT_LIB_DIR`, and finally falls back to `./lib` relative to the current working directory. Be mindful of where you run the `fun` binary from.
-
-See includes.md for more details.
-
-## REPL does not start
-
-Symptoms:
-- Running the executable just exits, or `--repl-on-error` is not recognized.
-
-Fix:
-- Build with `-DFUN_WITH_REPL=ON` and rebuild the `fun` target. Then launch without arguments:
-
-<pre>cmake -S . -B build -DFUN_WITH_REPL=ON
-cmake --build build --target fun
-FUN_LIB_DIR="$(pwd)/lib" ./build/fun
-</pre>
-See repl.md for usage tips and features.
-
-## Linker errors for optional libraries (JSON, PCRE2, CURL, SQLite, etc.)
-
-Symptoms:
-- Build fails when enabling an optional feature.
-
-Fix:
-- Ensure the development packages for the chosen library are installed (headers + libs).
-- Toggle features individually with `-DFUN_WITH_JSON=ON`, `-DFUN_WITH_PCRE2=ON`, etc., and verify your system provides them.
-
-## Bytecode or opcode mismatch errors after refactors
-
-Symptoms:
-- Crashes or incorrect behavior after editing src/vm or src/bytecode.h.
-
-Fix:
-- Rebuild cleanly to ensure all amalgamated C units are recompiled.
-- Verify opcode_names[] in src/vm.h matches enum ordering in src/bytecode.h.
-- Re-run with `--trace` and (optionally) `--dump-bytecode` to inspect control flow.
-
-## Paths differ when running from IDE vs. shell
-
-Symptoms:
-- Includes resolve in one environment but not the other; `./lib` fallback behaves differently.
-
-Fix:
-- Always set `FUN_LIB_DIR` explicitly in the run configuration of your IDE and in your shell session.
-- Confirm the working directory of the launch configuration; relative includes use `$PWD`.
-
-## Windows-specific quoting issues
-
-Symptoms:
-- Setting environment variables has no effect; include paths remain unresolved.
-
-Fix:
-- In CMD use: `set FUN_LIB_DIR=%CD%\lib && build\fun.exe examples\include_lib.fun`
-- In PowerShell use: `$env:FUN_LIB_DIR = "$PWD\lib"; .\build\fun.exe .\examples\include_lib.fun`
-
-## Getting help
-
-- Run the interpreter with `--help` to see supported flags.
-- Explore documentation/handbook.md and documentation/repl.md.
-- Check the examples under `examples/` for an interactive tour.