Foundation Execution model

# Getting Started

This page gets you from zero to a runnable Klyn file. It explains how scripts are launched, what a minimal source file looks like, and which rules matter immediately when you move from a one-file experiment to a real module.

Running a Script

The Klyn executable runs a source file directly. The most common workflow is:

    klyn hello.kn

Running `klyn` with no file starts the interactive REPL, which is useful for short experiments and checking type behavior quickly.

    klyn

Performance note

Klyn caches compiled object files and reuses them when possible. In normal usage, you run source files directly and let the toolchain decide whether recompilation is needed.

Installing the VS Code Extension

The Klyn distribution includes a Visual Studio Code extension package in the Klyn tools directory. `$KLYN_HOME` identifies the active Klyn installation directory.

    code --install-extension "$KLYN_HOME/tools/klyn-language-support.vsix"

On Windows PowerShell, use the environment variable syntax for Windows paths:

    code --install-extension "$env:KLYN_HOME\tools\klyn-language-support.vsix"

If the `code` command is not available in your terminal, open VS Code, run Extensions: Install from VSIX... from the Command Palette, then select `tools/klyn-language-support.vsix` from the Klyn home directory.

Compilation Cache

Compiled object files live in the versioned Klyn cache, not next to source files. When a cached `.o` file is newer than its `.kn` source, Klyn reuses it instead of compiling again. This is the normal and fastest startup path.

    klyn hello.kn

Use `--clean` only when you intentionally need a complete rebuild. It removes the current version cache, including the standard-library cache, before executing the source.

    klyn --clean hello.kn

Your First Program

A minimal script can be as small as one statement:

    print("Hello, Klyn!")

A more representative example already shows imports, explicit typing, and block syntax:

    import klyn.math

    attempts as Int = 3

    while attempts > 0:
        value = Int(Random.random() * 10)
        print(value)
        attempts--

Executable Scripts and Shebang

Klyn scripts may start with a shebang when you want to execute them directly from a shell:

    #!/usr/bin/env klyn

    print("Hello from a Klyn script")

This is optional. It is mainly useful for command-line tools and local automation.

A Realistic First Module

    const LIMIT as Int = 5

    def describe(value as Int) as String:
        return "small" if value < LIMIT else "large"

    class Counter:
        public property current as Int = 0

        public tick() as Void:
            this.current++

    counter = Counter()
    while counter.current < LIMIT:
        counter.tick()

    print(describe(counter.current))

Part | What it shows
--- | ---
`const LIMIT as Int = 5` | Constants are immutable and can be declared with explicit typing.
`def describe(...)` | Top-level functions use `def`.
`class Counter:` | Classes use indentation-based blocks, not braces.
`this.current++` | Properties are accessed with regular dot notation.

Common Beginner Mistakes
Watch for these errors early

- Writing an import inside a function. Imports are module-level only.
- Using tabs for indentation. Klyn expects spaces.
- Assuming type inference means dynamic typing. It does not.
- Placing an import after executable code instead of keeping imports at the beginning.

Building a Standalone Executable

Klyn can also produce a native executable from a startup source file:

    klyn -x App.kn
    # Equivalent long option
    klyn --executable App.kn

The output file is written in the current working directory and named after the source file: `App` on Linux and `App.exe` on Windows. The generated executable links the Klyn runtime and the compiled object files required by the application, so it can run on a compatible machine without a separate Klyn installation.

    ./App first-argument second-argument

Static dependency model

Executable generation embeds the dependencies known at compile time. Dynamic code loaded later through `eval`, `compile`, or advanced reflection is intentionally outside this first static packaging model and will need explicit configuration when used.

On Linux, the Klyn package installs the native build support files used by this mode under `/opt/klyn/lib/native`, including `libklyncore.a` and the standalone link flags.

Next Step

Continue with Lexical Structure to understand comments, indentation, literals, and source-file rules in detail.