Getting Started
===============

Prerequisites
-------------

- `Zig 0.15.2 <https://ziglang.org/download/>`_
- QBE (optional, required for ``bear qbe <file> -c``)
- LLVM (optional, required for ``bear llvm <file> -c``)

Building from Source
--------------------

Clone the repository and build with Zig::

    git clone https://github.com/navid-m/bearvm
    cd bearvm
    zig build

This produces the ``bear`` binary in ``zig-out/bin/``. Add it to your
``PATH`` or invoke it directly.

Platform Support
----------------

BearVM runs on macOS, Linux, and Windows.

The experimental JIT backend (``bear jit``) only targets aarch64 (Apple
Silicon) and is not available on other platforms or architectures.

Your First Program
------------------

Create a file called ``hello.bear``::

    @main(): int {
        call puts("Hello, world!")
        ret 0
    }

Run it through the interpreter::

    bear hello.bear

Expected output::

    Hello, world!

A Slightly Larger Example
--------------------------

The following program computes the 10th Fibonacci number using an iterative
loop in SSA form::

    @fib(%n: int): int {
    entry:
        %a0 = const 0
        %b0 = const 1
        %i0 = const 0
        jmp loop_cond

    loop_cond:
        %a = phi [entry: %a0, loop_body: %a_next]
        %b = phi [entry: %b0, loop_body: %b_next]
        %i = phi [entry: %i0, loop_body: %i_next]

        %cond = lt %i, %n
        br_if %cond, loop_body, loop_end

    loop_body:
        %tmp    = add %a, %b
        %a_next = %b
        %b_next = %tmp
        %i_next = add %i, 1
        jmp loop_cond

    loop_end:
        ret %a
    }

    @main(): int {
    entry:
        %n      = const 10
        %result = call fib(%n)
        call puts(%result)
        call flush()
        ret 0
    }

Run it::

    bear fib.bear

The same program using the high-level ``while`` sugar, which lowers to the
same representation::

    @fib(%n: int): int {
        %a = const 0
        %b = const 1
        %i = const 0
        while (lt %i, %n) {
            %tmp = add %a, %b
            %a   = %b
            %b   = %tmp
            %i   = add %i, 1
        }
        ret %a
    }

    @main(): int {
        %result = call fib(10)
        call puts(%result)
        call flush()
        ret 0
    }

Next Steps
----------

- See :doc:`language` for a full description of the IR syntax.
- See :doc:`instructions` for the complete instruction reference.
- See :doc:`backends` for compiling to native code via QBE or LLVM.
- See :doc:`cli` for all available CLI flags.