# How to install and build Turbo Golo

This guide shows how to get a working `turbo-golo` binary. It assumes you have Go 1.26 or later and can use a terminal.

## The short way, from a checkout

```bash
git clone ssh://git@rickub.com/turbo-editors/turbo-golo.git
cd turbo-golo
make install
```

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 `golo` — the interpreter, which is also the language server — is installed. The build goes to a temporary file first, so a failed build never replaces a working installation.

Then, from any directory holding Golo scripts:

```bash
turbo-golo main.golo
```

### Options

```bash
scripts/install.sh --prefix ~/bin     # install somewhere of your choosing
scripts/install.sh --with-server      # build and install GoloScript too
scripts/install.sh --uninstall        # remove it again  (make uninstall)
scripts/install.sh --help
```

Without `--prefix`, the editor goes where `go install` would put it: `$GOBIN`, or `$GOPATH/bin` when `GOBIN` is unset — usually `~/go/bin`.

`--with-server` clones `https://codeberg.org/TypeUnsafe/golo-script` and runs its `install.sh`, which builds `golo`, `gogolo` and `wagolo` and puts them in `/usr/local/bin`. It needs `git` and Go; `wagolo` also needs TinyGo. Precompiled binaries are the other way — see [How to install GoloScript](install-goloscript.md).

## Just build it, without installing

```bash
make build
./bin/turbo-golo main.golo
```

`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.

## From the module proxy, without a checkout

```bash
go install rickub.com/turbo-editors/turbo-golo@latest
```

If the command is then "not found", the install directory is not on your `PATH`:

```bash
export PATH="$PATH:$(go env GOPATH)/bin"
```

Turbo Golo 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.

## Check it works

```bash
turbo-golo -version
turbo-golo -list-themes
```

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.

## Variants

- **You only want to run it once**: `go run rickub.com/turbo-editors/turbo-golo@latest demos/hello/hello.golo`
- **You want the binary somewhere specific**: `go build -o /usr/local/bin/turbo-golo .`
- **Your terminal has no true colour**: use `turbo-golo -theme turbo-classic`, which is built from the sixteen ANSI colours only. `turbo-dark` and `borland-light` use 24-bit colours.

## When something goes wrong

**`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.

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:

```bash
scripts/install.sh --uninstall
scripts/install.sh
```

**`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 Golo. The version comes from `go.mod`, so it cannot drift from what the code actually needs.

**`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.

**`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).

**`golo is not installed, so there will be no completion`.** Not an error: editing, colouring and themes all work without it. Install GoloScript when you want completion — [How to install GoloScript](install-goloscript.md) — or re-run the installer with `--with-server`.

## Terminal requirements

Turbo Golo 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).

## See also

- Every flag: [command line reference](../reference/cli.md)
- Getting completion working: [How to enable Golo completion](enable-completion.md)
- The interpreter itself: [How to install GoloScript](install-goloscript.md)
- A guided first session: [Your first Golo program in Turbo Golo](../tutorials/getting-started.md)
- Programs to try it on: [the demos](../../../demos/)