From e86062aaad7776e7c1c57392ad17eac6c0abb6e0 Mon Sep 17 00:00:00 2001 From: hanez Date: Wed, 26 Nov 2025 00:57:45 +0100 Subject: [PATCH] Handbook update. No code changes. (0.30.0) --- README.md | 96 ----------------------------------------------- docs/handbook.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index 5030290..0d9dd59 100644 --- a/README.md +++ b/README.md @@ -86,102 +86,6 @@ In the [examples/](https://git.xw3.org/fun/fun/src/branch/main/examples) directo A complete API documentation will follow. -## Development - -This section is a work in progress... Please excuse the lack of more information. There are daily updates here. - -### Rules - -- Every commit message must contain the version at the end in the following format (1.2.3) -- Every commit requires a version incrementation in CMakeLists.txt before committing. Documentation updates do not increment the version but must contain the current version in each commit message. -- Version numbering follows "[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)" - -### Development systems - -- [GNU](https://gnu.org/)/[Linux](https://kernel.org/) ([Arch](https://archlinux.org/)/[Artix](https://artixlinux.org/), [Debian](https://www.debian.org/)) using [GCC](https://gcc.gnu.org/) and the [GNU C library](https://www.gnu.org/software/libc/) ([glibc](https://en.wikipedia.org/wiki/Glibc)) -- GNU/Linux ([Alpine](https://alpinelinux.org/)) using GCC and the [musl libc](https://musl.libc.org/) -- [FreeBSD](https://www.freebsd.org/) using [Clang](https://clang.llvm.org/) and the [BSD libc](https://en.wikipedia.org/wiki/C_standard_library#BSD_libc) -- [Windows](https://en.wikipedia.org/wiki/Microsoft_Windows) using [Cygwin](https://www.cygwin.com/) and GCC. - -### Other systems - -- [macOS](https://en.wikipedia.org/wiki/MacOS), [NetBSD](https://netbsd.org/), [OpenBSD](https://www.openbsd.org/), etc. should fully work, but I don't know. I do not use these systems actually. You wanna try and report? - -### To Do - -Everything... ;) No, a lot of stuff works already, but only a tiny set of functionality is available in the Fun programming language. It grows from day to day... - -### Build Fun - -Linux/UNIX only covered here for now. - -Clone repository: - -```bash -git clone https://git.xw3.org/fun/fun.git -``` - -Change directory: - -```bash -cd fun -``` - -Build: - -```bash -# Note: Every -D flag must be of the form NAME=VALUE (e.g., -DFUN_WITH_REPL=ON) -cmake -S . -B build -DFUN_DEBUG=OFF -DFUN_WITH_PCSC=OFF -DFUN_WITH_REPL=ON -DFUN_WITH_JSON=ON -cmake --build build --target fun -``` - -CMake options you can toggle (all require NAME=VALUE): - -- FUN_DEBUG=ON|OFF — verbose debug logging in the VM (default OFF) -- FUN_WITH_CURL=ON|OFF — enable CURL support using libcurl (default OFF) -- FUN_WITH_JSON=ON|OFF — enable JSON support via json-c (default OFF) -- FUN_WITH_PCRE2=ON|OFF — enable PCRE2 Perl-Compatible Regular Expressions support (default OFF) -- FUN_WITH_PCSC=ON|OFF — enable PCSC smart card support (default OFF) -- FUN_WITH_REPL=ON|OFF — enable the interactive REPL (default ON) - -That's it! For testing it, run: - -```bash -FUN_LIB_DIR="$(pwd)/lib" ./build/fun ./demo.fun -``` - -To see what's going on, run: - -```bash -FUN_LIB_DIR="$(pwd)/lib" ./build/fun --trace ./demo.fun -``` - -To switch into the REPL after an error, run: - -```bash -FUN_LIB_DIR="$(pwd)/lib" ./build/fun --repl-on-error --trace ./demo.fun -``` - -Both --repl-on-error and --trace are optional but can always be combined. To get -more debug information, you need to build Fun with -DFUN_DEBUG=ON. - -To directly run the REPL, you have to run: - -```bash -FUN_LIB_DIR="$(pwd)/lib" ./build/fun -``` - -But be sure to build Fun with -DFUN_WITH_REPL=ON. - -Tip: If you saw an error like this when configuring with CMake: - - CMake Error: Parse error in command line argument: FUN_WITH_JSON - Should be: VAR:type=value - -it means a -D flag was passed without a value. Always specify options as -DNAME=VALUE, for example: - - -DFUN_WITH_JSON=ON - ## Author Johannes Findeisen diff --git a/docs/handbook.md b/docs/handbook.md index 460ca53..ba6b434 100644 --- a/docs/handbook.md +++ b/docs/handbook.md @@ -506,6 +506,104 @@ The PCSC functions in the VM interface with pcsc-lite/WinSCard. Transmit returns --- +## Development + +This section is a work in progress... Please excuse the lack of more information. There are daily updates here. + +### Rules + +- Every commit message must contain the version at the end in the following format (1.2.3) +- Every commit requires a version incrementation in CMakeLists.txt before committing. Documentation updates do not increment the version but must contain the current version in each commit message. +- Version numbering follows "[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)" + +### Development systems + +- [GNU](https://gnu.org/)/[Linux](https://kernel.org/) ([Arch](https://archlinux.org/)/[Artix](https://artixlinux.org/), [Debian](https://www.debian.org/)) using [GCC](https://gcc.gnu.org/) and the [GNU C library](https://www.gnu.org/software/libc/) ([glibc](https://en.wikipedia.org/wiki/Glibc)) +- GNU/Linux ([Alpine](https://alpinelinux.org/)) using GCC and the [musl libc](https://musl.libc.org/) +- [FreeBSD](https://www.freebsd.org/) using [Clang](https://clang.llvm.org/) and the [BSD libc](https://en.wikipedia.org/wiki/C_standard_library#BSD_libc) +- [Windows](https://en.wikipedia.org/wiki/Microsoft_Windows) using [Cygwin](https://www.cygwin.com/) and GCC. + +### Other systems + +- [macOS](https://en.wikipedia.org/wiki/MacOS), [NetBSD](https://netbsd.org/), [OpenBSD](https://www.openbsd.org/), etc. should fully work, but I don't know. I do not use these systems actually. You wanna try and report? + +### To Do + +Everything... ;) No, a lot of stuff works already, but only a tiny set of functionality is available in the Fun programming language. It grows from day to day... + +### Build Fun + +Linux/UNIX only covered here for now. + +Clone repository: + +```bash +git clone https://git.xw3.org/fun/fun.git +``` + +Change directory: + +```bash +cd fun +``` + +Build: + +```bash +# Note: Every -D flag must be of the form NAME=VALUE (e.g., -DFUN_WITH_REPL=ON) +cmake -S . -B build -DFUN_DEBUG=OFF -DFUN_WITH_PCSC=OFF -DFUN_WITH_REPL=ON -DFUN_WITH_JSON=ON +cmake --build build --target fun +``` + +CMake options you can toggle (all require NAME=VALUE): + +- FUN_DEBUG=ON|OFF — verbose debug logging in the VM (default OFF) +- FUN_WITH_CURL=ON|OFF — enable CURL support using libcurl (default OFF) +- FUN_WITH_JSON=ON|OFF — enable JSON support via json-c (default OFF) +- FUN_WITH_PCRE2=ON|OFF — enable PCRE2 Perl-Compatible Regular Expressions support (default OFF) +- FUN_WITH_PCSC=ON|OFF — enable PCSC smart card support (default OFF) +- FUN_WITH_REPL=ON|OFF — enable the interactive REPL (default ON) + +That's it! For testing it, run: + +```bash +FUN_LIB_DIR="$(pwd)/lib" ./build/fun ./demo.fun +``` + +To see what's going on, run: + +```bash +FUN_LIB_DIR="$(pwd)/lib" ./build/fun --trace ./demo.fun +``` + +To switch into the REPL after an error, run: + +```bash +FUN_LIB_DIR="$(pwd)/lib" ./build/fun --repl-on-error --trace ./demo.fun +``` + +Both --repl-on-error and --trace are optional but can always be combined. To get +more debug information, you need to build Fun with -DFUN_DEBUG=ON. + +To directly run the REPL, you have to run: + +```bash +FUN_LIB_DIR="$(pwd)/lib" ./build/fun +``` + +But be sure to build Fun with -DFUN_WITH_REPL=ON. + +Tip: If you saw an error like this when configuring with CMake: + + CMake Error: Parse error in command line argument: FUN_WITH_JSON + Should be: VAR:type=value + +it means a -D flag was passed without a value. Always specify options as -DNAME=VALUE, for example: + + -DFUN_WITH_JSON=ON + +--- + ## Contributing and further reading - Browse lib/ for up-to-date stdlib APIs; many files document their own public interfaces in comments at the top.