turbo-editors/turbo-js · install.md

⑂ v1.0.1

install.md · 100 lines · 5.4 KBmarkdown    Blame HistoryRaw
   1# How to install and build Turbo JS
3This guide shows how to get a working `turbo-js` binary. It assumes you have Go 1.26 or later and can use a terminal.
5## The short way, from a checkout
8git clone ssh://git@rickub.com/turbo-editors/turbo-js.git
9cd turbo-js
10make install
13That builds the editor, puts it where your shell looks for commands, and tells you what it found: the Go version it built with, where the binary went, whether that directory is on your `PATH`, and whether `typescript-language-server` — the language server — is installed. The build goes to a temporary file first, so a failed build never replaces a working installation.
15Then, from any Node.js project:
18turbo-js main.js
21### Options
24scripts/install.sh --prefix ~/bin     # install somewhere of your choosing
25scripts/install.sh --with-server      # install the language server too
26scripts/install.sh --uninstall        # remove it again  (make uninstall)
27scripts/install.sh --help
30Without `--prefix`, the editor goes where `go install` would put it: `$GOBIN`, or `$GOPATH/bin` when `GOBIN` is unset — usually `~/go/bin`.
32`--with-server` runs `npm install -g typescript-language-server typescript@6`, so it needs `npm` — that is, Node.js; see [How to install Node.js](install-node.md). The `@6` is not optional: TypeScript 7 ships no `tsserver.js`, and a `typescript-language-server` installed beside it fails to start. The installer then checks the server by running `typescript-language-server --version` rather than trusting that the file exists, because a version manager can leave a shim on `PATH` for a Node that has since been removed.
34## Just build it, without installing
37
38./bin/turbo-js main.js
41`make build` also runs `scripts/check-version.sh` on what it built, so a binary that does not report the version the build meant fails the build rather than shipping.
43## From the module proxy, without a checkout
46go install rickub.com/turbo-editors/turbo-js@latest
49If the command is then "not found", the install directory is not on your `PATH`:
52export PATH="$PATH:$(go env GOPATH)/bin"
55Turbo JS has not been tagged yet, so until its first release `@latest` names the newest commit and the binary reports `devel` rather than a number; [the version number](../reference/versioning.md) explains why.
57## Check it works
60turbo-js -version
61turbo-js -list-themes
64The first names the commit the binary was built from, which is what to quote in a bug report; [the version number](../reference/versioning.md) explains what each form means. The second prints the themes compiled into the binary and tells you where your own would go.
66## Variants
68- **You only want to run it once**: `go run rickub.com/turbo-editors/turbo-js@latest main.js`
69- **You want the binary somewhere specific**: `go build -o /usr/local/bin/turbo-js .`
70- **Your terminal has no true colour**: use `turbo-js -theme turbo-classic`, which is built from the sixteen ANSI colours only. `turbo-dark` and `borland-light` use 24-bit colours.
72## When something goes wrong
74**`the installed binary does not run`.** The installer prints whatever the system said just above that line — read it first, because it names the actual problem.
76The installer replaces the binary rather than writing over the one that is there, so a reinstall gives the file a fresh identity. That matters on macOS, which caches a binary's code signature against its inode: writing new bytes into the old inode leaves the cached signature describing something else, and the kernel then refuses to run a binary that built and installed perfectly. If you have an older copy installed by something that used `cp`, removing it first clears any such state:
79scripts/install.sh --uninstall
80scripts/install.sh
83**`Go x.y or later is needed`.** The editor is written in Go, so building it needs a Go toolchain even though it is an editor for JavaScript. The version comes from `go.mod`, so it cannot drift from what the code actually needs.
85**`build failed; nothing was installed`.** Your existing installation is untouched — the build goes to a temporary file first. The compiler's own output is printed above the message.
87**`the build did not carry its version; nothing was installed`.** The binary built but does not report the version the installer stamped into it — a linker flag naming a symbol that no longer exists, usually. Nothing is installed; the check that failed is described under [the version number](../reference/versioning.md#checked-at-build-time).
89**`typescript-language-server is not installed, so there will be no completion`.** Not an error: editing, colouring and themes all work without it. Install the server when you want completion — [How to enable JavaScript completion](enable-completion.md) — or re-run the installer with `--with-server`.
91## Terminal requirements
93Turbo JS needs a terminal that reports its size and supports mouse reporting — every mainstream one does. It reads `TERM` through tcell; if the display is wrong, check that `TERM` matches your terminal (`xterm-256color` is a safe default).
95## See also
97- Every flag: [command line reference](../reference/cli.md)
98- Getting completion working: [How to enable JavaScript completion](enable-completion.md)
99- Node.js itself: [How to install Node.js](install-node.md)
100- A guided first session: [Your first JavaScript program in Turbo JS](../tutorials/getting-started.md)

📦 Turbo JS 91999d1 k33g 12h ago	1	# How to install and build Turbo JS
	2
	3	This guide shows how to get a working `turbo-js` binary. It assumes you have Go 1.26 or later and can use a terminal.
	4
	5	## The short way, from a checkout
	6
	7	```bash
	8	git clone ssh://git@rickub.com/turbo-editors/turbo-js.git
	9	cd turbo-js
	10	make install
	11	```
	12
	13	That builds the editor, puts it where your shell looks for commands, and tells you what it found: the Go version it built with, where the binary went, whether that directory is on your `PATH`, and whether `typescript-language-server` — the language server — is installed. The build goes to a temporary file first, so a failed build never replaces a working installation.
	14
	15	Then, from any Node.js project:
	16
	17	```bash
	18	turbo-js main.js
	19	```
	20
	21	### Options
	22
	23	```bash
	24	scripts/install.sh --prefix ~/bin # install somewhere of your choosing
	25	scripts/install.sh --with-server # install the language server too
	26	scripts/install.sh --uninstall # remove it again (make uninstall)
	27	scripts/install.sh --help
	28	```
	29
	30	Without `--prefix`, the editor goes where `go install` would put it: `$GOBIN`, or `$GOPATH/bin` when `GOBIN` is unset — usually `~/go/bin`.
	31
	32	`--with-server` runs `npm install -g typescript-language-server typescript@6`, so it needs `npm` — that is, Node.js; see [How to install Node.js](install-node.md). The `@6` is not optional: TypeScript 7 ships no `tsserver.js`, and a `typescript-language-server` installed beside it fails to start. The installer then checks the server by running `typescript-language-server --version` rather than trusting that the file exists, because a version manager can leave a shim on `PATH` for a Node that has since been removed.
	33
	34	## Just build it, without installing
	35
	36	```bash
	37	make build
	38	./bin/turbo-js main.js
	39	```
	40
	41	`make build` also runs `scripts/check-version.sh` on what it built, so a binary that does not report the version the build meant fails the build rather than shipping.
	42
	43	## From the module proxy, without a checkout
	44
	45	```bash
	46	go install rickub.com/turbo-editors/turbo-js@latest
	47	```
	48
	49	If the command is then "not found", the install directory is not on your `PATH`:
	50
	51	```bash
	52	export PATH="$PATH:$(go env GOPATH)/bin"
	53	```
	54
	55	Turbo JS has not been tagged yet, so until its first release `@latest` names the newest commit and the binary reports `devel` rather than a number; [the version number](../reference/versioning.md) explains why.
	56
	57	## Check it works
	58
	59	```bash
	60	turbo-js -version
	61	turbo-js -list-themes
	62	```
	63
	64	The first names the commit the binary was built from, which is what to quote in a bug report; [the version number](../reference/versioning.md) explains what each form means. The second prints the themes compiled into the binary and tells you where your own would go.
65
66	## Variants
67
68	- You only want to run it once: `go run rickub.com/turbo-editors/turbo-js@latest main.js`
69	- You want the binary somewhere specific: `go build -o /usr/local/bin/turbo-js .`
70	- Your terminal has no true colour: use `turbo-js -theme turbo-classic`, which is built from the sixteen ANSI colours only. `turbo-dark` and `borland-light` use 24-bit colours.
71
72	## When something goes wrong
73
74	`the installed binary does not run`. The installer prints whatever the system said just above that line — read it first, because it names the actual problem.
75
76	The installer replaces the binary rather than writing over the one that is there, so a reinstall gives the file a fresh identity. That matters on macOS, which caches a binary's code signature against its inode: writing new bytes into the old inode leaves the cached signature describing something else, and the kernel then refuses to run a binary that built and installed perfectly. If you have an older copy installed by something that used `cp`, removing it first clears any such state:
77
78	```bash
79	scripts/install.sh --uninstall
80	scripts/install.sh
81	```
82
83	`Go x.y or later is needed`. The editor is written in Go, so building it needs a Go toolchain even though it is an editor for JavaScript. The version comes from `go.mod`, so it cannot drift from what the code actually needs.
84
85	`build failed; nothing was installed`. Your existing installation is untouched — the build goes to a temporary file first. The compiler's own output is printed above the message.
86
87	`the build did not carry its version; nothing was installed`. The binary built but does not report the version the installer stamped into it — a linker flag naming a symbol that no longer exists, usually. Nothing is installed; the check that failed is described under [the version number](../reference/versioning.md#checked-at-build-time).
88
89	`typescript-language-server is not installed, so there will be no completion`. Not an error: editing, colouring and themes all work without it. Install the server when you want completion — [How to enable JavaScript completion](enable-completion.md) — or re-run the installer with `--with-server`.
90
91	## Terminal requirements
92
93	Turbo JS needs a terminal that reports its size and supports mouse reporting — every mainstream one does. It reads `TERM` through tcell; if the display is wrong, check that `TERM` matches your terminal (`xterm-256color` is a safe default).
94
95	## See also
96
97	- Every flag: [command line reference](../reference/cli.md)
98	- Getting completion working: [How to enable JavaScript completion](enable-completion.md)
99	- Node.js itself: [How to install Node.js](install-node.md)
100	- A guided first session: [Your first JavaScript program in Turbo JS](../tutorials/getting-started.md)