turbo-editors/turbo-moonbit · getting-started.md

turbo-editors/turbo-moonbitpublic⑂ Fork 0

⑂ cc1f59535e31ad5d5a940f517c7375fbc8c663a0

getting-started.md · 217 lines · 6.8 KBmarkdown    Blame HistoryRaw
📦 Turbo MoonBit   1# Tutorial: your first MoonBit program in Turbo MoonBit
3By the end of this tutorial you will have written, formatted, run and broken a small MoonBit program without leaving the editor — and seen the editor tell you where the mistake was.
5No prior knowledge of Turbo MoonBit is needed. You need Go 1.26 or later to build the editor, and the MoonBit toolchain to build the program.
7## Prerequisites
12
15You should see something like:
18go version go1.26.5 linux/arm64
21Check the MoonBit toolchain:
24moon version --all
27You should see three lines, each ending in a path:
30moon 0.1.20260904 (94521db 2026-09-04) ~/.moon/bin/moon
31moonc v0.10.12+1634b282e (2026-09-07) ~/.moon/bin/moonc
32moonrun 0.1.20260904 (94521db 2026-09-04) ~/.moon/bin/moonrun
35If that command is not found, install the toolchain first — [one command does it](../how-to/install-the-moonbit-toolchain.md).
37## Step 1 — Install the editor
40git clone https://rickub.com/turbo-editors/turbo-moonbit.git
41cd turbo-moonbit
42make install
45The installer builds, installs, and then checks what it installed. The last lines are:
48==> Checking the language server
49  ✓ moon-lsp at ~/.moon/bin/moon-lsp
51
54We now have a `turbo-moonbit` command.
56## Step 2 — Make a project
60moon new hello
65Created username/hello at hello
68`moon new` writes a `moon.mod`, a `moon.pkg`, a library file, some test files, and a `cmd/main/main.mbt` with a hello-world in it. **`moon.mod` is what Turbo MoonBit looks for** to find the root of a project, and it is the directory `moon-lsp` will be started in.
70## Step 3 — Open the file
73turbo-moonbit cmd/main/main.mbt
76The screen fills. Along the top:
79 File  Edit  Search  Run  Code  Options  Window  Snippets  MoonBit  Help
82Ten menus, and the ninth is named after the language. Along the bottom, at the right-hand end, you should see:
851:1  LSP: ready
88`LSP: ready` means `moon-lsp` started in this directory. We will use it in Step 8.
90## Step 4 — Write the program
92Select everything with `Ctrl-A` and press `Delete`, then type this in. Type it exactly; we will look at the colours next.
94
96struct Greeting {
97  name : String
98  times : Int
102fn greet(g : Greeting) -> Unit {
103  for i in 0..<g.times {
104    println("Hello, \{g.name}! (\{i + 1})")
109
110  greet({ name: "MoonBit", times: 3 })
114Press `F2` to save. The star beside `main.mbt` in the window's title goes away.
116## Step 5 — Read the colours
118Look at what you have typed. In the default `turbo-classic` theme:
120| What | Colour |
121| --- | --- |
122| `struct`, `fn`, `for`, `in` | bright white, bold — keywords |
123| `Greeting`, `String`, `Int`, `Unit` | bright cyan — types |
124| `greet`, where it is declared and where it is called | bright yellow, bold — functions |
125| `println` | bright cyan, bold — a name the language provides |
126| `name`, `times`, `g`, `i` | bright yellow — ordinary names |
127| `"Hello, \{g.name}! (\{i + 1})"` | green, **all of it** — one string |
128| `0`, `1`, `3` | magenta — numbers |
129| `///\|` | grey — a comment |
131Two of those rows are worth a second look.
133**`Greeting` is cyan and `greet` is yellow**, and nothing in the editor was told which of them is a type. MoonBit's own rule decides it: a name beginning with a capital can only be a type, a trait or a constructor.
135**The string is green from the first quote to the last**, interpolations included. The `\{g.name}` inside it is not coloured as code — [and that is on purpose](../explanation/colouring-and-completion.md).
137## Step 6 — Give the project its tools
139Press `F10` to open the menu bar, then `→` **eight times** to reach **MoonBit** — past Edit, Search, Run, Code, Options, Window and Snippets. Faster: press `Alt-M`.
141The menu holds two items, and only one of them is available:
144┌───────────────────┐
145│ Create tools file │
146│ Open tools file   │   ← greyed out; there is no file to open yet
147└───────────────────┘
150Choose **Create tools file**.
152A second window opens on the file that was just written, `.turbo-moonbit/tools.toml`. Read it if you like — it explains every key it uses — then press `Ctrl-W` to close it.
154Open the MoonBit menu again. It now holds nine commands, and the two items have swapped: `Create tools file` is greyed out, and `Open tools file` is the one you can choose.
156## Step 7 — Format it, and run it
158Press `Alt-M` and choose **Format**.
160A dialog opens, fills in, and says `— exit 0`. Press `Escape`.
162Look at the last line of your `main` function. It has changed:
164
165  greet({ name: "MoonBit", times: 3, })
168`moon fmt` added a trailing comma, and the editor reloaded the file it had just been told had changed underneath it.
170Now `Alt-M`, then **Run**. A box asks for a value before the command runs:
173┌──────────────── Run ────────────────┐
174│  package, e.g. cmd/main             │
176└─────────────────────────────────────┘
179Type `cmd/main` and press `Enter`. A terminal window opens and the program runs in it:
182Hello, MoonBit! (1)
183Hello, MoonBit! (2)
184Hello, MoonBit! (3)
187A terminal rather than a dialog, because a program that reads the keyboard has to be answerable. The program has finished, so the window has stopped behaving like a terminal and every key reaches the editor again: press `Ctrl-W` to close it.
189## Step 8 — Break it, and see where
191Go to the `println` line and change `g.name` to `g.nam`. Press `F2` to save.
193Within a second or two, two things happen. A red `×` appears in the gutter, just left of that line's number. And the status bar reads:
196⚠ The value identifier nam is unbound.
199Nothing asked for that. `moon-lsp` publishes it by itself whenever it re-reads the file.
201Put the `e` back and save again; both the mark and the message go away.
203## Step 9 — Change the theme
205`F10`, then `→` **five times** to reach **Options** — past Edit, Search, Run and Code. Choose **Theme…**.
207A list opens on the theme you are in. Press `↓` to `cobalt` and `Enter`. The whole screen changes, keeping the same shape.
209Press `Alt-X` to leave. The editor asks about unsaved files first, if there are any.
211## What now?
213You have made a MoonBit project, written a program in the editor, formatted it, run it, broken it, and seen the editor say where. To go further:
215- To do specific things → the [how-to guides](../how-to/)
216- To see exactly what is coloured and how → [languages coloured](../reference/languages.md)
217- To understand why the editor is built this way → the [explanation](../explanation/)

📦 Turbo MoonBit cc1f595 k33g 15h ago	1	# Tutorial: your first MoonBit program in Turbo MoonBit
	2
	3	By the end of this tutorial you will have written, formatted, run and broken a small MoonBit program without leaving the editor — and seen the editor tell you where the mistake was.
	4
	5	No prior knowledge of Turbo MoonBit is needed. You need Go 1.26 or later to build the editor, and the MoonBit toolchain to build the program.
	6
	7	## Prerequisites
	8
	9	Check Go:
	10
	11	```bash
	12	go version
	13	```
	14
	15	You should see something like:
	16
	17	```
	18	go version go1.26.5 linux/arm64
	19	```
	20
	21	Check the MoonBit toolchain:
	22
	23	```bash
	24	moon version --all
	25	```
	26
	27	You should see three lines, each ending in a path:
	28
	29	```
	30	moon 0.1.20260904 (94521db 2026-09-04) ~/.moon/bin/moon
	31	moonc v0.10.12+1634b282e (2026-09-07) ~/.moon/bin/moonc
	32	moonrun 0.1.20260904 (94521db 2026-09-04) ~/.moon/bin/moonrun
	33	```
	34
	35	If that command is not found, install the toolchain first — [one command does it](../how-to/install-the-moonbit-toolchain.md).
	36
	37	## Step 1 — Install the editor
	38
	39	```bash
	40	git clone https://rickub.com/turbo-editors/turbo-moonbit.git
	41	cd turbo-moonbit
	42	make install
	43	```
	44
	45	The installer builds, installs, and then checks what it installed. The last lines are:
	46
	47	```
	48	==> Checking the language server
	49	✓ moon-lsp at ~/.moon/bin/moon-lsp
	50
	51	==> Ready
	52	```
	53
	54	We now have a `turbo-moonbit` command.
	55
	56	## Step 2 — Make a project
	57
	58	```bash
	59	cd /tmp
	60	moon new hello
	61	cd hello
	62	```
	63
	64	```
65	Created username/hello at hello
66	```
67
68	`moon new` writes a `moon.mod`, a `moon.pkg`, a library file, some test files, and a `cmd/main/main.mbt` with a hello-world in it. `moon.mod` is what Turbo MoonBit looks for to find the root of a project, and it is the directory `moon-lsp` will be started in.
69
70	## Step 3 — Open the file
71
72	```bash
73	turbo-moonbit cmd/main/main.mbt
74	```
75
76	The screen fills. Along the top:
77
78	```
79	File Edit Search Run Code Options Window Snippets MoonBit Help
80	```
81
82	Ten menus, and the ninth is named after the language. Along the bottom, at the right-hand end, you should see:
83
84	```
85	1:1 LSP: ready
86	```
87
88	`LSP: ready` means `moon-lsp` started in this directory. We will use it in Step 8.
89
90	## Step 4 — Write the program
91
92	Select everything with `Ctrl-A` and press `Delete`, then type this in. Type it exactly; we will look at the colours next.
93
94	```moonbit
95	///\|
96	struct Greeting {
97	name : String
98	times : Int
99	}
100
101	///\|
102	fn greet(g : Greeting) -> Unit {
103	for i in 0..<g.times {
104	println("Hello, \{g.name}! (\{i + 1})")
105	}
106	}
107
108	///\|
109	fn main {
110	greet({ name: "MoonBit", times: 3 })
111	}
112	```
113
114	Press `F2` to save. The star beside `main.mbt` in the window's title goes away.
115
116	## Step 5 — Read the colours
117
118	Look at what you have typed. In the default `turbo-classic` theme:
119
120	\| What \| Colour \|
121	\| --- \| --- \|
122	\| `struct`, `fn`, `for`, `in` \| bright white, bold — keywords \|
123	\| `Greeting`, `String`, `Int`, `Unit` \| bright cyan — types \|
124	\| `greet`, where it is declared and where it is called \| bright yellow, bold — functions \|
125	\| `println` \| bright cyan, bold — a name the language provides \|
126	\| `name`, `times`, `g`, `i` \| bright yellow — ordinary names \|
127	\| `"Hello, \{g.name}! (\{i + 1})"` \| green, all of it — one string \|
128	\| `0`, `1`, `3` \| magenta — numbers \|
129	\| `///\\|` \| grey — a comment \|
130
131	Two of those rows are worth a second look.
132
133	`Greeting` is cyan and `greet` is yellow, and nothing in the editor was told which of them is a type. MoonBit's own rule decides it: a name beginning with a capital can only be a type, a trait or a constructor.
134
135	The string is green from the first quote to the last, interpolations included. The `\{g.name}` inside it is not coloured as code — [and that is on purpose](../explanation/colouring-and-completion.md).
136
137	## Step 6 — Give the project its tools
138
139	Press `F10` to open the menu bar, then `→` eight times to reach MoonBit — past Edit, Search, Run, Code, Options, Window and Snippets. Faster: press `Alt-M`.
140
141	The menu holds two items, and only one of them is available:
142
143	```
144	┌───────────────────┐
145	│ Create tools file │
146	│ Open tools file │ ← greyed out; there is no file to open yet
147	└───────────────────┘
148	```
149
150	Choose Create tools file.
151
152	A second window opens on the file that was just written, `.turbo-moonbit/tools.toml`. Read it if you like — it explains every key it uses — then press `Ctrl-W` to close it.
153
154	Open the MoonBit menu again. It now holds nine commands, and the two items have swapped: `Create tools file` is greyed out, and `Open tools file` is the one you can choose.
155
156	## Step 7 — Format it, and run it
157
158	Press `Alt-M` and choose Format.
159
160	A dialog opens, fills in, and says `— exit 0`. Press `Escape`.
161
162	Look at the last line of your `main` function. It has changed:
163
164	```moonbit
165	greet({ name: "MoonBit", times: 3, })
166	```
167
168	`moon fmt` added a trailing comma, and the editor reloaded the file it had just been told had changed underneath it.
169
170	Now `Alt-M`, then Run. A box asks for a value before the command runs:
171
172	```
173	┌──────────────── Run ────────────────┐
174	│ package, e.g. cmd/main │
175	│ [ ] │
176	└─────────────────────────────────────┘
177	```
178
179	Type `cmd/main` and press `Enter`. A terminal window opens and the program runs in it:
180
181	```
182	Hello, MoonBit! (1)
183	Hello, MoonBit! (2)
184	Hello, MoonBit! (3)
185	```
186
187	A terminal rather than a dialog, because a program that reads the keyboard has to be answerable. The program has finished, so the window has stopped behaving like a terminal and every key reaches the editor again: press `Ctrl-W` to close it.
188
189	## Step 8 — Break it, and see where
190
191	Go to the `println` line and change `g.name` to `g.nam`. Press `F2` to save.
192
193	Within a second or two, two things happen. A red `×` appears in the gutter, just left of that line's number. And the status bar reads:
194
195	```
196	⚠ The value identifier nam is unbound.
197	```
198
199	Nothing asked for that. `moon-lsp` publishes it by itself whenever it re-reads the file.
200
201	Put the `e` back and save again; both the mark and the message go away.
202
203	## Step 9 — Change the theme
204
205	`F10`, then `→` five times to reach Options — past Edit, Search, Run and Code. Choose Theme….
206
207	A list opens on the theme you are in. Press `↓` to `cobalt` and `Enter`. The whole screen changes, keeping the same shape.
208
209	Press `Alt-X` to leave. The editor asks about unsaved files first, if there are any.
210
211	## What now?
212
213	You have made a MoonBit project, written a program in the editor, formatted it, run it, broken it, and seen the editor say where. To go further:
214
215	- To do specific things → the [how-to guides](../how-to/)
216	- To see exactly what is coloured and how → [languages coloured](../reference/languages.md)
217	- To understand why the editor is built this way → the [explanation](../explanation/)