Documentation refactoring. No code changes. (0.40.5)

web/documentation/fun/fun.md

@@ -0,0 +1,93 @@
+---
+layout: page
+published: true
+noToc: false
+noComments: false
+noDate: false
+title: Fun - Fun executable, full usage guide
+subtitle: Full usage guide for the `fun` executable, invocation patterns, REPL, env vars, include paths, examples, and install locations.
+description: Full usage guide for the `fun` executable, invocation patterns, REPL, env vars, include paths, examples, and install locations.
+permalink: /documentation/fun/
+lang: en
+tags:
+- env
+- examples
+- executable
+- full
+- include
+- install
+- invocation
+- locations
+- paths
+- patterns
+- vars
+---
+
+This document explains how to use the `fun` binary after building or installing it: invocation patterns, options, environment variables, include/search paths, REPL, and examples.
+
+## Synopsis
+
+<pre>fun [options] [script.fun] [-- args...]</pre>
+- 
+- If [script.fun] is provided, `fun` runs the script.
+- If omitted and the build enables the REPL, `fun` starts an interactive session.
+
+## Options
+- `-i`, `--repl` — start the interactive REPL explicitly (if built with REPL support)
+- `-v`, `--version` — print version and exit
+- `-h`, `--help` — show usage info and exit
+
+Notes:
+- Available options may vary by build configuration. Always check `fun --help` for your binary.
+
+## Exit codes
+- `0` — success
+- non‑zero — error during parse, compile, or runtime
+
+## Standard library and includes
+`fun` searches for modules included from `.fun` code in these locations:
+
+1. The path provided by the environment variable `FUN_LIB_DIR` (highest precedence)
+2. The compiled‑in default `DEFAULT_LIB_DIR` (configured during build/install)
+
+Tips:
+- When running from the repository without installing, set `FUN_LIB_DIR` to the local `./lib` directory so examples can find the stdlib.
+- See also: `documentation/includes.md` for namespacing (`include ... as ...`) and search order details.
+
+## REPL
+If interactive mode is enabled at build time, starting `fun` with `-i` (or without a script) opens the REPL.
+
+Useful commands/patterns in REPL:
+- Enter expressions and statements directly.
+- Use arrow keys/history for editing (availability depends on build flags).
+- See `documentation/repl.md` for details and tips.
+
+## Running scripts
+Basic run (installed system‑wide):
+<pre>fun /usr/share/fun/examples/hello.fun</pre>
+
+Running from a build tree (not installed):
+
+<pre>FUN_LIB_DIR=./lib /path/to/build_dir/fun examples/hello.fun</pre>
+
+Passing arguments to scripts (arguments after `--` are forwarded to the script environment):
+<pre>fun myscript.fun -- arg1 arg2</pre>
+
+## Build and install locations
+
+- Build targets: `fun` is produced by the `fun` target. In CLion/CMake, typical build directories are `build_debug` or `build_release`.
+- Install locations (by default):
+  - Binary: `/usr/bin/fun`
+  - Stdlib: `/usr/share/fun/lib`
+  - Examples (optional): `/usr/share/fun/examples`
+
+To stage an install without touching the system:
+
+<pre>DESTDIR=./tmp/stage cmake --build [build_dir] --target install
+./tmp/stage/usr/bin/fun ./examples/hello.fun</pre>
+
+## See also
+- [../cli/](../cli/) — concise CLI reference (synopsis/options/exit codes)
+- [../funstx/](../funstx/) — syntax checker for `.fun` files with optional `--fix`
+- [../examples/](../examples/) — how to run the bundled examples
+- [../includes/](../includes) — include paths, namespacing, and `FUN_LIB_DIR`