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 matching the version declared in build.zig.zon
• macOS, Linux, or Windows

Build From Source

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:

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. <exe>/../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:

imp std.c.io;

fun main(str[] args) {
  printf("Hello, World!\n");
}

Build the toolchain and run the program:

zig build
./zig-out/bin/fun -in hello.fn

CLI

Usage:
  fun -in <input_file> [-fmt | -fmt-all | -fmt-diag | -fmt-check | -fmt-check-all] [-out <output_file>] [-no-exec] [-outf] [-ast] [-g] [-help] [-- <program args...>]
  fun -fmt-check-all [-in <file_or_dir>]
  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:

$env:FUN_CC = "zig"
$env:FUN_CC_ARGS = "cc"

Use cl only when the Visual Studio toolchain environment is already active:

$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.

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.

Other Editors

Vim, Neovim, Emacs, JetBrains, and Sublime setup notes are available in editors/README.md.

GitHub Syntax Highlighting

This repository maps .fn files to Zig highlighting on GitHub via /.gitattributes. Native Fun highlighting can be added upstream by contributing a Fun definition and TextMate grammar to GitHub Linguist.

Documentation

• Public documentation site: primary documentation entry point
• Language guide: public language overview and feature guide
• Reference: public language and library reference
• Interactive playground: runnable browser-based examples
• docs/architecture.md: implementation structure and compiler pipeline
• docs/channel-runtime-conformance.md: backend conformance matrix and runtime thresholds
• docs/faq.md: common questions about the language and tooling
• docs/: source Markdown that feeds the published documentation

Examples

The 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/advanced/custom_functions.fn
• examples/imports/main.fn
• examples/stdlib/json_basic.fn

CI And Automation

Use the published setup action to install Fun in GitHub Actions:

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.

Changelog

Release history and notable changes are tracked in CHANGELOG.md.

License

Fun is released under the MIT License. See LICENSE for the full text.