# Start

You install the toolchain, make a project, then run, test, change and build it. To try Gizlang with no
install, use the [Playground](https://gizstack.com/play).

## 1. Install

:::code-group{label="Install"}
```sh title="macOS and Linux"
curl -fsSL https://gizstack.com/install | sh
```
```powershell title="Windows"
irm https://gizstack.com/install.ps1 | iex
```
:::

:::status{of="install-script"}
:::

One install gives the compiler, the standard library, the libraries (gizhw, gizml, gizfs, gizdb, gizweb), the
test runner, the formatter, the language server, live code swap and the GizDB server. It needs no administrator
account and no other build tools.

The script finds your system, downloads the installer for it and checks its SHA-256. It then checks the release
signature (Ed25519) and the SHA-256 of every file, activates the version in `~/.giz`, and adds `~/.giz/bin` to your
`PATH`. It does nothing until its last line, so a download that stops part way changes nothing. Read it first with
`curl -fsSL https://gizstack.com/install`.

Check the install:

```sh
giz --version
```

### Install options

Give options after `sh -s --`, for example `curl -fsSL https://gizstack.com/install | sh -s -- --version 0.2.0`.

| Option | Meaning |
| --- | --- |
| `--version VERSION` | Install this version. The default is the newest. |
| `--only gizdb` | Install only the GizDB server into `~/.gizdb` (`GIZDB_INSTALL=DIR` for another folder). See [the GizDB server](operations/gizdb-server.md). |
| `--no-modify-path` | Do not change shell profiles. `NO_MODIFY_PATH=1` does the same. |
| `GIZ_INSTALL=DIR` | Install into DIR instead of `~/.giz`. |

### Other channels

:::status{of="channels"}
:::

Each channel runs the same signed installer.

| Channel | Command |
| --- | --- |
| npm | `npm install -g @gizai/cli`, `npx @gizai/cli`, `bunx @gizai/cli` |
| Homebrew | `brew install gizai/tap/giz` |
| Docker | `docker run --rm -v "$PWD":/work ghcr.io/gizai/giz run main.giz` |
| GitHub Actions | `uses: gizai/setup-giz@v0` |
| Signed installer | Download it from the [download page](https://gizstack.com/download) (its address is its SHA-256), check it with `sha256sum`, then run `./giz-installer --root "$HOME/.giz"` |

The GizDB server alone has the same channels under the name `gizdb`.

### Platforms

Linux x86-64 needs glibc 2.35 or later. macOS needs 11.0 or later. The [release catalog](https://gizstack.com/api/releases) lists every
published release with its target, version and minimum platform.

:::catalog{group="install"}
:::

## 2. Make a project

```sh
giz init hello
cd hello
```

| File | Contents |
| --- | --- |
| `main.giz` | The program |
| `main.test.giz` | Its tests |
| `package.json` | The manifest: the entry, the modules with their pins, and the toolchain version |

## 3. Run it

```gizlang run
function main(): void {
    print("Hello, world");
}
```

```text output
Hello, world
```

Run it with `giz run main.giz`.

The first run compiles the program to native code against the prebuilt standard library. Later runs start from the
cache. `giz main.giz` is the short form.

## 4. Test it

```sh
giz test
```

`giz test` runs each function whose name starts with `test` in the `.test.giz` files under the folder. It keeps a pass
until the code that the test covers changes.

## 5. Change it live

```sh
giz live main.giz
```

`giz live` runs the program and replaces its code each time you save a file. Named state stays, and a function that
is running finishes on the code that it started with.

## 6. Build it

```sh
giz build main.giz -o hello
./hello
```

The result is one native executable with no runtime to install.

## Keep the toolchain current

| Task | How |
| --- | --- |
| Upgrade | `giz upgrade` (or `giz upgrade --version 0.2.0`). The active version stays installed, and stays active if the upgrade fails. |
| Pin a project's version | Put `"version": "0.2.0"` in the `gizlang` section of `package.json`. `giz` then runs that version in the folder and below, and installs it on first use. `GIZ_VERSION=VERSION` selects a version for one command. |
| Use an editor | Editors start `giz lsp` as their language server. The VS Code extension is in the [command-line guide](guides/command-line.md#vs-code). |
| Uninstall | Remove `~/.giz` (or your `GIZ_INSTALL` folder) and the line `. "$HOME/.gizstack/env"` from your shell profiles. |

A version never changes after it is published. Each file of a release has a SHA-256 in an envelope signed with
Ed25519, and the third-party notices are in `share/licenses/`. Gizlang is open source under the MIT
[license](https://gizstack.com/license), so CI, containers and agents run the same command as a person.

## Next

- [Tour](tour.md): each part of Gizlang in one short program.
- [The language](guides/language.md): the language for a TypeScript, JavaScript or Go developer.
- [A web app](guides/web.md): routes, forms, a database and tests in one native process.
- [Deploy to GizStack](https://gizstack.com/docs/platform/deploy): put an app at its own address.