Patch handbook · Tutorials

Build real programs one step at a time.

Each tutorial starts from source you can read, run and change. The visual Designer edits that same Patch source, so the code remains the durable project model.

create number count = 0

change count:
  add 1

show count

Tutorial 1 · Beginner · about 5 minutes

Your first Patch program

Open Patch Studio.

Use the hosted Studio from the main navigation or an Offline Studio Stage 1 build.

Replace the editor contents.

create text message = "Hello, Patch!"
show message

Press Run.

The result area shows the value of message. create introduces persistent program state; show observes it.

Nothing changes implicitly. When you want to mutate persistent state, use an explicit change block.

Open hello-world.patch Open Patch Studio

Tutorial 2 · Beginner · about 10 minutes

Build a Counter window

This small app combines persistent state, a Form, controls, interpolation, an event and an explicit semantic change.

create number count = 0

window "Counter" size 420, 240:
  text "Count: {count}" at 24, 24 size 220, 32
  button "Add" as add_button at 24, 72 size 120, 38

when add_button clicked:
  change count:
    add 1

Run the program.

The Window starts with count 0.

Click Add.

The event receives control flow, but the persistent state changes only because the handler contains change count.

Edit visually.

Switch to Designer, move the Button and resize it. Patch Studio writes the geometry back to ordinary source.

Open counter-window.patch

Tutorial 3 · Beginner

Use Patch Studio like a RAD IDE

1. Form selector

Choose the active Form. Inactive Forms stay as lightweight source-backed shells, while the active Form is materialized for visual editing.

2. Component Palette

Add controls from the searchable palette. Current authoring includes ordinary controls plus structural components such as Tabs, Table, TreeView, Panel, Picture, Shape, PaintBox, Timer, StatusBar and ImageList.

3. Object Inspector

Edit source-backed properties, layout, events and structural data. Unsupported operations fail closed instead of silently writing hidden state.

4. Source remains primary

Undo/redo, duplication, z-order, layout, Form operations and structural editors all resolve back to Patch source rather than a second persistent form model.

For a complete seven-Form stress example, load Workshop Desk from Patch Studio or inspect the repository example.

Open Workshop Desk

Tutorial 4 · Beginner

Conditions and loops

create number score = 0

repeat 4:
  if count == 2 or count == 4:
    change score:
      add count

show score

A literal repeat exposes its 1-based iteration as count. Here only iterations 2 and 4 mutate score, so the program shows 6.

Control-flow example Simple conditions

Tutorial 5 · Intermediate

Recipes and bounded Change Contracts

create thing player:
  name = "Mia"
  score = 0

allow reward:
  player.score may increase up to 10

make reward(player):
  change player:
    add 5 to score

do reward(player)
show player.score

make names reusable behavior and do invokes it. The allow declaration constrains semantic authority by direction and magnitude. Patch's formal assurance claim is intentionally narrower than the full product language, so consult the Language and research contracts for the exact mechanized subset.

Change capability example Language reference

Tutorial 6 · Intermediate

Work with GUI data without hidden state

Selections from ListBox, Table and TreeView are transient toolkit values. They become persistent only when your event handler explicitly applies a Patch change.

create list fruits = ["Banana", "Mango"]

window "Fruit Picker":
  listbox "Apple", "Banana", "Cherry", "Mango" as fruits

when fruits changed:
  change fruits:
    set = value

Because fruits is list state, supported targets use a multi-selection ListBox and expose the current transient selection through value.

ComboBox example Checkbox example More GUI examples

Tutorial 7 · Ship it

Check, run and build your software

patch check app.patch
patch run app.patch
patch build app.patch --target web
patch doctor --json

Web

Patch can build standalone Console and Window Web applications for supported source.

Desktop

The current native Ready line is Native GUI IR 1.9 / payload v19 / runtime v1.10. Button ImageList images and application/Form icons are Current Ready on Windows, macOS and Linux. PNG/JPEG Picture, Shape and PaintBox, including draw image, are Current Ready. WebP/SVG stay deferred under native-picture-formats/1.0. Studio/Web-only controls stay fail-closed on that line. Payload v17/runtime v1.8 is an explicit Offline Compiler compatibility underlay, not the default.

Offline Studio

Stage 1 supports offline authoring, Designer/Object Inspector and Run on every published distribution. Stage 2 R0.2 host-native Window Build inside the IDE is available for Windows x64, macOS Apple Silicon and Linux x64. Windows ARM64, Linux ARM64, macOS Intel and the portable Node bundle remain Stage 1 for installed native Build.

Downloads and build choices Build reference

Tutorial 8 · Everyday workflow

Read errors and diagnose the toolchain

Patch diagnostics use stable codes and source locations where available. Patch Studio also exposes local diagnostic reporting without uploading source text.

patch check app.patch --json
patch doctor --json

Use check for source/compiler diagnostics and doctor for compiler/backend health. In Studio, Run, Build and Change Contract errors are mapped back to Patch locations when the backend can establish them safely.

Troubleshooting Continue with examples

Where to go next

Browse examples

Choose a tested program by topic and difficulty.

Example library

Exact syntax

Use the Language page when you need the current syntax and product boundaries.

Language reference

Build locally

Download Offline Studio or the standalone compiler for supported platforms.

Downloads