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

Start

You install the toolchain, make a project, then run, test, change and build it. To try Gizlang with no install, use the Playground.

1. Install

macOS and Linux

curl -fsSL https://gizstack.com/install | sh

Windows

irm https://gizstack.com/install.ps1 | iex

Available Runs today, as shown. Roadmap

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:

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

Coming In development. This is the design it ships to. Roadmap

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 (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 lists every published release with its target, version and minimum platform.

Signed installerAvailable
One file for each platform, checked by SHA-256 and an Ed25519 signature.
One-command installAvailable
curl -fsSL https://gizstack.com/install | sh, with upgrade and version pins.
macOSComing
Apple Silicon and Intel.
WindowsComing
x86-64 and ARM64.
npm, Homebrew, Docker, GitHub ActionsComing
The same signed release through the channel you use.

2. Make a project

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

gizlangRun

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

text

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

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

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

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.
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, so CI, containers and agents run the same command as a person.

Tour: each part of Gizlang in one short program.
The language: the language for a TypeScript, JavaScript or Go developer.
A web app: routes, forms, a database and tests in one native process.
Deploy to GizStack: put an app at its own address.