hanez/fun
1
0
Fork 0
forked from fun/fun
Code Pull requests Activity
fun/web/documentation/troubleshooting/troubleshooting.md

3.1 KiB
Raw Blame History

layout published noToc noComments noDate title subtitle description permalink lang tags
page true false false false Troubleshooting Guide Common issues and quick fixes for build, includes, and REPL usage. Common issues and quick fixes for build, includes, and REPL usage. /documentation/troubleshooting/ en
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:

Include error: cannot read '<io/console.fun>'

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:

export FUN_LIB_DIR="$(pwd)/lib"
./build/fun examples/include_lib.fun

Windows (PowerShell):

$env:FUN_LIB_DIR = "$PWD/lib"
./build/fun.exe .\examples\include_lib.fun

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:
cmake -S . -B build -DFUN_WITH_REPL=ON
cmake --build build --target fun
FUN_LIB_DIR="$(pwd)/lib" ./build/fun

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.