From f896e1d3bfdf2e05a61d57fd024946e68e5ff9ac Mon Sep 17 00:00:00 2001 From: hanez Date: Wed, 18 Feb 2026 17:39:10 +0100 Subject: [PATCH] Holiday is over, now I have fun again. No code changes. (0.38.11) --- docs/README.md | 16 +++++++++++++ docs/bytecode-format.md | 29 ++++++++++++++++++++++++ docs/cli.md | 38 +++++++++++++++++++++++++++++++ docs/contributing.md | 40 +++++++++++++++++++++++++++++++++ docs/embedding.md | 29 ++++++++++++++++++++++++ docs/errors-and-diagnostics.md | 21 +++++++++++++++++ docs/faq.md | 22 ++++++++++++++++++ docs/performance.md | 21 +++++++++++++++++ docs/roadmap.md | 21 +++++++++++++++++ docs/security-and-sandboxing.md | 17 ++++++++++++++ docs/stdlib.md | 26 +++++++++++++++++++++ docs/style-guide.md | 25 +++++++++++++++++++++ docs/writing-tests.md | 24 ++++++++++++++++++++ 13 files changed, 329 insertions(+) create mode 100644 docs/bytecode-format.md create mode 100644 docs/cli.md create mode 100644 docs/contributing.md create mode 100644 docs/embedding.md create mode 100644 docs/errors-and-diagnostics.md create mode 100644 docs/faq.md create mode 100644 docs/performance.md create mode 100644 docs/roadmap.md create mode 100644 docs/security-and-sandboxing.md create mode 100644 docs/stdlib.md create mode 100644 docs/style-guide.md create mode 100644 docs/writing-tests.md diff --git a/docs/README.md b/docs/README.md index b9abdd8..eb01ea2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,22 @@ This file serves as an index of the documents in this directory. Links are relat - [testing.md](./testing.md) — How to build and run tests/targets with CMake/CTest, and where to add new tests. - [troubleshooting.md](./troubleshooting.md) — Common issues and quick fixes for build, includes, and REPL usage. +## New and supplemental guides + +- [build.md](./build.md) — How to build Fun with CMake, available targets, and build options (FUN_DEBUG, FUN_USE_MUSL, FUN_WITH_CPP, FUN_WITH_RUST). +- [cli.md](./cli.md) — Command‑line usage of the `fun` executable: synopsis, options, exit codes, includes and library paths. +- [contributing.md](./contributing.md) — How to contribute: project structure, coding style, running tests, and PR guidelines. +- [style-guide.md](./style-guide.md) — Coding conventions for C and Fun (indentation, naming, idioms). +- [stdlib.md](./stdlib.md) — Overview of the standard library modules under ./lib with one‑line summaries. +- [embedding.md](./embedding.md) — Embedding the VM from C/Rust, lifecycle, and host integration tips. +- [errors-and-diagnostics.md](./errors-and-diagnostics.md) — Understanding parser/runtime errors and enabling diagnostics. +- [performance.md](./performance.md) — Build/runtime tuning tips and patterns for better performance. +- [security-and-sandboxing.md](./security-and-sandboxing.md) — Trust boundaries, I/O expectations, and capability restrictions. +- [faq.md](./faq.md) — Frequently asked questions and quick answers. +- [writing-tests.md](./writing-tests.md) — How to author new tests for Fun and opcode components. +- [bytecode-format.md](./bytecode-format.md) — Reference for the bytecode format (split out from internals for convenience). +- [roadmap.md](./roadmap.md) — High‑level direction, planned features, and pointers to issues. + ## Tips - When building from the repo without installing, set `FUN_LIB_DIR` to the local `./lib` directory so examples and the REPL can locate the stdlib. diff --git a/docs/bytecode-format.md b/docs/bytecode-format.md new file mode 100644 index 0000000..6d58d76 --- /dev/null +++ b/docs/bytecode-format.md @@ -0,0 +1,29 @@ +# Bytecode Format (Overview) + +This document summarizes the Fun bytecode format. For deep VM details, see `docs/internals.md`. + +## Goals +- Compact representation for fast loading and dispatch +- Stable header with room for versioning + +## File layout (typical) +1. Header + - Magic number / signature + - Format version + - Flags (endianness, feature bits) + - Offsets to sections +2. Constants table + - Literals: numbers, strings, compound constants +3. Code section + - Functions/procedures with instruction streams + - Line/column mapping (optional for debugging) +4. Auxiliary tables + - Imports/exports, names, debug info (optional) + +## Instructions +- Fixed-size or small-variant opcodes grouped by domain (math, logic, stack, call, control flow, etc.). +- Operands encoded inline following the opcode (width varies by instruction). + +## Versioning and compatibility +- The header’s version field allows the VM to refuse or translate older/newer formats. +- Keep additions backward-compatible when possible by appending sections or flags. diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..ff036fa --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,38 @@ +# Fun CLI + +Reference for the `fun` command-line interface. + +## Synopsis +``` +fun [options] [-- args...] +``` + +If no script is supplied and interactive mode is available, `fun` starts a REPL (see `docs/repl.md`). + +## Common options +- `-i`, `--repl` — start an interactive REPL +- `-v`, `--version` — print version and exit +- `-h`, `--help` — show help and exit + +Options may vary between versions; run `fun --help` to see what your build supports. + +## Exit codes +- `0` — success +- non-zero — error during parse, compile, or runtime + +## Includes and library paths +- `FUN_LIB_DIR` — environment variable that points to the stdlib location; when running from the repo, set this to `./lib`. +- `DEFAULT_LIB_DIR` — compiled-in fallback path determined at build/install time. + +See also: `docs/includes.md` for namespaced includes and search order. + +## Examples +Run a script: +``` +FUN_LIB_DIR=./lib ./build_debug/fun examples/hello.fun +``` + +Start the REPL: +``` +./build_debug/fun -i +``` diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..806c833 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,40 @@ +# Contributing to Fun + +Thanks for your interest in contributing! This guide covers the basics to get you productive quickly. + +## Getting started +- Clone the repo and build (see `docs/build.md`). +- Run tests locally (see `docs/testing.md`). +- Explore examples (see `docs/examples.md`). + +## Project structure +- `src/` — C core, VM, and opcode implementations (`src/vm/*`). +- `lib/` — Standard library written in Fun. +- `examples/` — Example programs and showcases. +- `docs/` — Documentation. +- `spec/` — Language specification drafts. + +## Code style +- C: C99, two-space indent, no tabs. Keep functions short and focused. +- Fun: two-space indent, snake_case for functions, PascalCase for classes/constructors. +- Prefer clear names over abbreviations. See `docs/style-guide.md`. + +## Development workflow +1. Create a small, focused branch. +2. Add/adjust tests for behavior changes (see `docs/writing-tests.md`). +3. Update docs if user-visible behavior changes. +4. Submit a PR with a clear description and rationale. + +## Commit/PR guidelines +- Keep commits atomic; include test updates with the change. +- Reference related issues. +- Include benchmarks only when meaningful and reproducible. + +## Reporting bugs +Please include: +- Reproducer script (minimal), expected vs. actual behavior +- Build options and platform +- `fun --version` output + +## Code of Conduct +Be respectful and inclusive. See `CODE_OF_CONDUCT.md` in the repository root. diff --git a/docs/embedding.md b/docs/embedding.md new file mode 100644 index 0000000..f603250 --- /dev/null +++ b/docs/embedding.md @@ -0,0 +1,29 @@ +# Embedding Fun + +This guide outlines how to embed the Fun VM in a host application and extend it from C/Rust. + +## Overview +- The VM is implemented in C (see `src/vm/`). +- Optional Rust-based opcodes can be enabled via `FUN_WITH_RUST` (see `docs/rust.md`). + +## Embedding from C +While the exact API surface may evolve, a typical embedding flow looks like: +1. Initialize the VM/runtime and allocate a context. +2. Load/compile Fun source or bytecode. +3. Push arguments or set globals as needed. +4. Execute entry function or script body. +5. Retrieve results and clean up. + +See `src/vm/core` and related headers for public entry points and value types. + +### Hosting considerations +- Threading: share VM state cautiously or create one VM per thread. +- Memory: clarify ownership of strings/buffers crossing the boundary. +- Errors: propagate parse/runtime errors back to the host with useful messages. + +## Extending with Rust +When `FUN_WITH_RUST=ON`, a Rust static library from `src/rust/` is built and linked. You can: +- Implement new opcodes/functions in Rust. +- Expose a C ABI for the VM to call into. + +See `docs/rust.md` for details and example code. diff --git a/docs/errors-and-diagnostics.md b/docs/errors-and-diagnostics.md new file mode 100644 index 0000000..f2b5757 --- /dev/null +++ b/docs/errors-and-diagnostics.md @@ -0,0 +1,21 @@ +# Errors and Diagnostics + +This guide helps you understand common error messages and how to collect useful diagnostics. + +## Common error classes +- Parse errors: syntax/indentation problems detected before execution. +- Name/lookup errors: missing variables, functions, or modules. +- Runtime errors: type mismatches, out-of-range access, invalid operations. + +## Enabling diagnostics +- Build with `-DFUN_DEBUG=ON` to enable additional assertions and debug messages (see `docs/build.md`). +- Run with smaller, focused scripts to isolate issues. + +## Getting useful reports +- Capture the minimal script that reproduces the issue. +- Note your build options and platform. +- Record the full error output from the CLI (`fun`), including line/column if present. + +## Tips +- Use prints or logging sparingly to narrow down failing code. +- Start from a passing simple case and add complexity until it breaks. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..82947b4 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,22 @@ +# FAQ + +Answers to common questions. + +## I built Fun but includes aren’t found +Set `FUN_LIB_DIR` to the repository’s `./lib` directory when running without installation: +``` +FUN_LIB_DIR=./lib ./build_debug/fun examples/hello.fun +``` +See `docs/includes.md`. + +## How do I start the REPL? +Run `fun -i` (or run `fun` without a script, depending on version). See `docs/repl.md`. + +## Which build target should I use? +Use the aggregate `build` target to build `fun`, `fun_test`, and `test_opcodes`. See `docs/build.md`. + +## Where are the standard libraries? +Under `./lib/`. See `docs/stdlib.md` for an overview. + +## Where can I find internals and opcodes? +Browse `src/vm/` and `docs/internals.md` / `docs/opcodes.md`. diff --git a/docs/performance.md b/docs/performance.md new file mode 100644 index 0000000..ed926cc --- /dev/null +++ b/docs/performance.md @@ -0,0 +1,21 @@ +# Performance Guide + +Tips for getting good performance from Fun programs and builds. + +## Build configuration +- Use `-DCMAKE_BUILD_TYPE=Release` for production binaries. +- Consider `FUN_DEBUG=OFF` to remove extra checks in hot paths. +- `FUN_USE_MUSL=ON` can help with static/portable builds; measure performance for your use case. + +## Language-level tips +- Prefer pre-sized arrays/maps when possible to reduce reallocations. +- Avoid unnecessary string concatenations in loops; accumulate in arrays and `join`. +- Push work to native ops where available (e.g., regex, JSON, math helpers). + +## Algorithmic choices +- Choose appropriate data structures (arrays for ordered scans, maps for key lookups). +- Cache repeated computations or lookups when safe. + +## Measuring +- Create small, representative benchmarks. +- Compare Debug vs. Release to ensure changes are meaningful. diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..4792b8f --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,21 @@ +# Roadmap + +This page outlines high-level areas of focus and points to places where you can help. + +## Themes +- Developer experience: docs, examples, REPL polish +- Optional extensions: stabilize and document supported integrations +- Performance: steady improvements in hot paths and data structures +- Safety: clearer error messages, diagnostics, and sandboxing guidance + +## Near-term +- Expand CLI reference and examples (`docs/cli.md`) +- Improve testing docs and coverage (`docs/writing-tests.md`) +- Fill gaps in stdlib documentation (`docs/stdlib.md`) + +## Medium-term +- Bytecode/reference updates as internals evolve (`docs/bytecode-format.md`, `docs/internals.md`) +- Embedding guides and host API stability (`docs/embedding.md`, `docs/rust.md`) + +## Contributing +See `docs/contributing.md` for how to propose and implement items. Track concrete tasks via repository issues and PRs. diff --git a/docs/security-and-sandboxing.md b/docs/security-and-sandboxing.md new file mode 100644 index 0000000..9bdf970 --- /dev/null +++ b/docs/security-and-sandboxing.md @@ -0,0 +1,17 @@ +# Security and Sandboxing + +Understand the trust boundaries and how to run Fun code safely. + +## Trust model +- By default, Fun code can access functionality exposed by the stdlib and any enabled extensions. +- File and network access depend on available modules and host configuration. + +## Running untrusted code +- Prefer running in a container/VM with restricted filesystem and network. +- Limit available stdlib/modules by controlling `FUN_LIB_DIR` contents. +- Use OS-level sandboxing (seccomp, AppArmor, SELinux, chroot) where applicable. + +## Best practices +- Avoid running as root. +- Validate and sanitize inputs at module boundaries. +- Keep your build minimal; disable unneeded extensions at compile time. diff --git a/docs/stdlib.md b/docs/stdlib.md new file mode 100644 index 0000000..a075823 --- /dev/null +++ b/docs/stdlib.md @@ -0,0 +1,26 @@ +# Standard Library Overview + +This page provides a quick orientation to the standard library located under `./lib/`. + +The stdlib is written in Fun and organized by domain. Below are top-level modules and what they generally cover. Refer to the source for full APIs and examples. + +## Module index (selected) +- `crypt/` — cryptographic helpers (hashing, encoding helpers). See also `lib/crypt`. +- `encoding/` — text/binary encodings and conversions. +- `io/` — file and stream utilities. +- `net/` — basic networking helpers. +- `regex/` — regular expression utilities (PCRE2 when available). +- `ui/` — UI helpers (e.g., Tk if enabled at build time). +- `utils/` — small reusable helpers and utilities. + +Note: Availability of some modules can depend on optional extensions selected at build time (see `docs/build.md`). + +## Using modules +```fun +include "utils/strings.fun" as strings + +let s = strings.trim(" hello ") +print(s) +``` + +For search paths and namespacing details, see `docs/includes.md` and `docs/cli.md` (FUN_LIB_DIR and DEFAULT_LIB_DIR). diff --git a/docs/style-guide.md b/docs/style-guide.md new file mode 100644 index 0000000..5c97cc9 --- /dev/null +++ b/docs/style-guide.md @@ -0,0 +1,25 @@ +# Fun Style Guide + +Conventions for writing C and Fun code in this repository. + +## General principles +- Two-space indentation. No tabs. +- Keep lines reasonably short (~100 cols). Wrap thoughtfully. +- Prefer explicit over implicit; favor clarity. + +## C (C99) +- Indentation: two spaces, K&R-ish braces. +- Naming: `snake_case` for functions and variables; `CAPS_SNAKE` for macros. +- Error handling: return error codes or booleans; avoid hidden globals. +- Headers: minimize includes in headers; forward-declare where practical. +- Memory: clearly document ownership; free what you allocate. + +## Fun language +- Indentation: two spaces. +- Naming: `snake_case` for functions/variables; `PascalCase` for classes/constructors. +- Modules: one primary concept per file; export a minimal, cohesive API. +- Idioms: prefer arrays and maps over ad-hoc structures; keep functions small. + +## Formatting and tools +- No auto-formatters required; follow these simple rules. +- Keep diffs small and focused; avoid reformat-only commits. diff --git a/docs/writing-tests.md b/docs/writing-tests.md new file mode 100644 index 0000000..a371aed --- /dev/null +++ b/docs/writing-tests.md @@ -0,0 +1,24 @@ +# Writing Tests + +How to author tests for Fun and its opcode implementations. + +## Test kinds +- VM/opcode tests: exercise bytecode operations and VM behavior (target: `test_opcodes`). +- Language/runtime tests: exercise user-visible features and stdlib behavior (target: `fun_test`). + +See `docs/testing.md` for how to build and run these targets with CTest. + +## Adding new tests +The exact layout may evolve; generally: +- Add new test sources alongside existing ones used by `fun_test`. +- For opcode-focused tests, add cases where `test_opcodes` discovers them. + +Aim for: +- Small, isolated test cases with clear assertions +- One behavior per test; descriptive names +- Minimal fixtures and setup + +## Guidelines +- Prefer black-box testing via public APIs. +- When adding features, include both positive and negative cases. +- Keep tests deterministic; avoid non-deterministic timers or random sources unless seeded.