Fun Programming Language

A statically typed programming language that transpiles to C, built for predictable performance, straightforward tooling, and portable deployment.

Language Guide · Reference · Examples · VS Code

## Overview Fun is a compiled language implemented in Zig that lowers Fun source code to readable C. The project focuses on a compact language surface, strong static typing, practical concurrency, and an editor-friendly toolchain built around formatting, diagnostics, and language-server support. The language provides high-level default numerics (`num`, `dec`), fixed-width scalar types (`i32`, `u64`, `f32`, `f64`), and arbitrary-width integers (`iN`, `uN`) so the same codebase can target ergonomic application code and lower-level systems work. ## Why Fun - Predictable compilation model: Fun compiles through C, making generated output inspectable and portable across common platform toolchains. - Practical type system: the language combines simple defaults with low-level numeric control when exact layout or width matters. - Built-in concurrency primitives: virtual threads, channels, async/await, and task coordination are first-class parts of the language and standard library. - Tooling-first workflow: formatting, diagnostics, a language server, and editor integrations are part of the day-to-day development experience. - Compact standard library: the core library covers collections, filesystem, networking, serialization, synchronization, and C interop signatures. ## Core Capabilities - Static typing with explicit, readable syntax - Transpilation to C with debug-friendly source mapping - Pattern matching via `fit` - Data-carrying enums and generic compounds - Default parameter values - Virtual-thread concurrency with `fork` - Standard-library support for channels, tasks, threads, filesystem access, JSON, TOML, networking, and more - CLI tooling for formatting, diagnostics, AST inspection, and code generation ## Installation ### Prerequisites - [Zig](https://ziglang.org/download/) matching the version declared in [build.zig.zon](build.zig.zon) - macOS, Linux, or Windows ### Build From Source ```sh git clone https://github.com/omdxp/fun.git cd fun zig build ``` This produces the compiler and language server in `zig-out/bin/`. To install the compiler together with the standard library layout used by the runtime and editor tooling: ```sh zig build install ``` ### Release Bundles Release assets are published as install bundles containing the compiler, the standard library under `share/fun/`, and platform-specific install assets. - Windows releases are available as `.msi` installers and portable `.zip` archives. - Portable archives preserve the same `bin/` and `share/fun/` layout as an installed release. - Windows portable packages include `README-portable.txt` with platform-specific startup notes. At runtime, the compiler discovers the standard library in this order: 1. `FUN_STDLIB_DIR` 2. `/../share/fun` 3. Common system install locations for the active platform `std.c.*` modules are signature-only C interop definitions used for typechecking and tooling. `std.*` modules without the `.c` namespace are Fun-native standard library modules. ## Quickstart Create `hello.fn`: ```fun imp std.c.io; fun main(str[] args) { printf("Hello, World!\n"); } ``` Build the toolchain and run the program: ```sh zig build ./zig-out/bin/fun -in hello.fn ``` ## CLI ```text Usage: fun -in [-fmt | -fmt-all | -fmt-diag | -fmt-check | -fmt-check-all] [-out ] [-no-exec] [-outf] [-ast] [-g] [-help] [-- ] fun -fmt-check-all [-in ] fun -version ``` Key workflows: - `fun -in file.fn` compiles and runs a Fun program. - `fun -fmt`, `fun -fmt-all`, and `fun -fmt-check-all` enforce formatting across a file or tree. - `fun -fmt-diag -no-exec` formats and collects diagnostics in a single pass. - `fun -g` emits debug-friendly Fun-to-C source mapping for native debugger workflows. ### C Compiler Selection By default, `fun` selects a platform compiler unless `FUN_CC` is set. - macOS and Linux: `zig cc`, `clang`, `gcc`, `cc` - Windows: `zig cc`, `clang`, `gcc`, `cl` You can override the compiler with: - `FUN_CC`: base compiler command, or a full template when it includes `{src}` and `{out}` - `FUN_CC_ARGS`: additional arguments appended to the base command Examples: - `FUN_CC=clang` - `FUN_CC=zig` with `FUN_CC_ARGS="cc"` - `FUN_CC="clang -O2 {src} -o {out}"` #### Windows Notes When using `cl`, run Fun from **Developer PowerShell for Visual Studio** (or after `VsDevCmd.bat`) so MSVC environment variables are initialized. Recommended stable Windows setup: ```powershell $env:FUN_CC = "zig" $env:FUN_CC_ARGS = "cc" ``` Use `cl` only when the Visual Studio toolchain environment is already active: ```powershell $env:FUN_CC = "cl /nologo /Fe{out} {src}" $env:FUN_CC_ARGS = "" ``` ## Tooling And Editor Support The repository includes `fls`, the Fun language server. It communicates over LSP and supports diagnostics, formatting-aware workflows, hover, completion, go-to-definition, and related editor features. ### VS Code The official VS Code extension is published on the Visual Studio Marketplace: [Fun (FLS) for VS Code](https://marketplace.visualstudio.com/items?itemName=omdxp.fun-language). 1. Build `fun` and `fls` with `zig build`. 2. Install the published extension from the marketplace. 3. For local development, packaging, or extension source, see [editors/vscode](editors/vscode). ### Other Editors Vim, Neovim, Emacs, JetBrains, and Sublime setup notes are available in [editors/README.md](editors/README.md). ### GitHub Syntax Highlighting This repository maps `.fn` files to Zig highlighting on GitHub via [/.gitattributes](.gitattributes). Native Fun highlighting can be added upstream by contributing a Fun definition and TextMate grammar to GitHub Linguist. ## Documentation - [Public documentation site](https://omdxp.github.io/fun/): primary documentation entry point - [Language guide](https://omdxp.github.io/fun/#language): public language overview and feature guide - [Reference](https://omdxp.github.io/fun/#reference): public language and library reference - [Interactive playground](https://omdxp.github.io/fun/#playground): runnable browser-based examples - [docs/architecture.md](docs/architecture.md): implementation structure and compiler pipeline - [docs/channel-runtime-conformance.md](docs/channel-runtime-conformance.md): backend conformance matrix and runtime thresholds - [docs/faq.md](docs/faq.md): common questions about the language and tooling - [docs/](docs/): source Markdown that feeds the published documentation ## Examples The [examples/](examples/) directory is organized for incremental exploration: - foundational language examples - advanced language features and concurrency patterns - import and module-organization scenarios - standard-library usage examples - negative and edge-case programs used for diagnostics and behavior validation Representative entry points: - [examples/test.fn](examples/test.fn) - [examples/advanced/custom_functions.fn](examples/advanced/custom_functions.fn) - [examples/imports/main.fn](examples/imports/main.fn) - [examples/stdlib/json_basic.fn](examples/stdlib/json_basic.fn) ## CI And Automation Use the published setup action to install Fun in GitHub Actions: ```yaml jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: omdxp/setup-fun@v1 with: version: latest - run: fun -version ``` ## Repository Layout - `cmd/`: command-line entrypoints - `modules/`: compiler and tooling modules - `stdlib/`: standard library source and documentation - `examples/`: sample Fun programs - `tests/`: repository test suites - `editors/`: editor integrations and language tooling packages - `build.zig`: Zig build definition ## Contributing Contribution guidelines, development expectations, and pull-request workflow are documented in [CONTRIBUTING.md](CONTRIBUTING.md). ## Changelog Release history and notable changes are tracked in [CHANGELOG.md](CHANGELOG.md). ## License Fun is released under the MIT License. See [LICENSE](LICENSE) for the full text.