# Build and run

## The fastest route: the Shell

```
vml run examples/c/app/tetris.c        # source  -> run it directly
vml run ~/main.vml                 # text assembly -> run it
vml run ~/main.vmb                 # bytecode -> run it (fastest)
```

`vml run` **detects the extension for you**, so you never have to think about which path it takes.

## Tap through the Files page

**Files** page -> tap a file name -> pick from the menu:

- **Compile** -> produces the next artifact down the chain (`.c` -> `.vml`, `.vml` -> `.vmb`)
- **Run** -> runs it directly

The artifact appears in the **same directory**, under the same base name. If a file of that name is
already there, you are asked to overwrite / rename / cancel.

## How long a compile takes on a phone

- **C is the slowest**: a program that pulls in the standard library takes **one to two minutes** to
  compile in the front end and link (on a phone it really is on the order of a minute)
- Scripting languages such as Python / Lua / BASIC are much faster (a few seconds)
- **Loading a `.vmb` is nearly instant** - so if you run the same program again and again, compiling
  to `.vmb` first and then running it saves the most time

> Do not assume it has frozen while compiling: the input cell shows `⋯`, and the `~>` prompt comes
> back when it is done.

## Can a stuck compile lock me out?

No. Front end compilation is synchronous and **has no cancellation entry point at all**, so the host
adds a **watchdog**: if it is still not done after 180 seconds, control comes back to you (that
compile thread itself cannot be aborted - the point is just to stop the UI from hanging).

## Why `.vml` can still stand on its own

- **It can be read**: it is text, so you can see for yourself what instructions the compiler produced
- **It can be edited**: hand-written assembly is just as valid (`vml test` runs a piece of built-in assembly)
- **It works as an intermediate artifact**: compile `.c` to `.vml` once, then assemble to `.vmb` over
  and over without going through the front end again

## Compiler options (Settings → Compile)

Under **Settings → Compile** you can tune a few compiler behavior options. **A change takes effect
on the next compile.**

| Option | Default | Notes |
|---|---|---|
| Optimization level | Off | **Four levels**: Off / Light / Medium / Max (see below) |
| Compiler warnings | Off | Once on, compile-time warnings are shown (Basic = `-Wall`, More = `-Wextra`) |
| Treat warnings as errors | Off | Any warning counts as a failed compile (`-Werror`) |
| Debug output | Off | Turns on the diagnostic branches inside the front end, plus the warning count at the end of a compile |
| Floating point (float/double) | Hardware | Set it to Off = floating-point code **fails to compile outright** |
| 64-bit integers (long/int64) | Hardware | Same as above |

### The four optimization levels

| Level | What it does | Measured (a 46-byte hello.c) |
|---|---|---|
| **Off** | Does not delete a single instruction | 69637 instructions / 2.0 MB |
| **Light** | Clears out filler code that is unreachable after a jump | 69637 / 2.0 MB (basically unchanged) |
| **Medium** | Adds **dead code elimination**: removes library functions nobody calls | **28 / 3.1 KB** |
| **Max** | Also removes redundant jumps, clears the data segment, drops `.linked` declarations | **27 / 670 bytes** |

> **This is what "turning optimization on really makes it smaller" means**: a hello world drops from
> **2.0 MB to 670 bytes**, because it linked the whole standard library to begin with, and 99% of it
> was functions that nothing ever calls.
>
> **Games are not this dramatic** (they already use a lot of the library): Tetris 74754 -> 6282
> instructions, Gomoku 72921 -> 3544, Gorillas (BASIC) 103437 -> 29863.
>
> **Optimization does not change what a program does** - the output of the examples in all 27
> languages is **byte-for-byte identical** across the four levels (there is a test watching this).
> Its rule is "only delete what is certain to be unused": for indirect jumps, function addresses
> taken, interrupt vector tables and other cases that cannot be seen fully at compile time, it
> **prefers to keep rather than delete**.

> **Unused things get dropped**: global variables, constants, strings and whole library data
> segments (the sine table, the palette and so on) that nothing references never make it into the
> output. This is not specific to one level - data segment cleanup is always in effect; from Medium
> up, dropping library functions removes even more of it along the way.

> **"Off" reports an error, it does not degrade gracefully** - it is there to confirm whether a
> program uses floating point or 64-bit integers at all, not to let a program quietly get slower.
> Soft floating point has no corresponding library on this platform, so that level is not offered.

> These options **do not affect the default behavior**: leave them alone (optimization = Off) and
> what you compile is **byte-for-byte identical** to before.