# Quickstart

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

You need [Node.js](https://nodejs.org) 20.12 or later for npm. Gizlang itself does not run on Node.

```sh
npm install -g @gizai/cli
giz init hello
```

The npm package is the command line of giz.ai and GizStack (`giz`, with your account's commands; its source is
`tools/cli/npm`) and holds no toolchain. The first Gizlang command, such as `giz init`, downloads the native toolchain
for your system into `~/.giz` (about 190 MB to download, about 1.2 GB installed) and checks its SHA-256 and its
release signature (Ed25519) before it uses it. Later commands start at once. Scripts and editors can run `~/.giz/bin/giz` itself (the VS Code extension
does). No administrator account and no other build tools are necessary.

If npm answers `EACCES` (Node from apt installs global packages as root), give npm a folder of your own once:
`npm config set prefix ~/.local`, with `~/.local/bin` on your PATH, or install Node with [nvm](https://github.com/nvm-sh/nvm).

To run one command without an install: `npx @gizai/cli run main.giz`.

One install gives the compiler, the standard library, the libraries (gizdb, gizweb, gizfs, gizai, gizhw), the test
runner, the formatter, the language server, live code swap and the GizDB server.

### Platforms

The toolchain runs on Linux x86-64 with glibc 2.35 or later (Ubuntu 22.04, Debian 12 and newer). macOS and Windows come
later; until then, use Linux, WSL 2 on Windows, or the [Playground](https://gizstack.com/play). The
[release catalog](https://gizstack.com/api/releases) lists every published release with its target and version.

## 2. Make a project

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

| File | Contents |
| --- | --- |
| `main.giz` | The program |
| `main.test.giz` | Its test |
| `package.json` | The entry file and the toolchain version |

`giz init my-desk --template desk` creates a standalone GizDesk AI agent workspace instead, and `--template visits` a web server over SQL.

## 3. Run it

`main.giz` is:

```typescript gizlang
// Run it: giz run main.giz. Test it: giz test. Edit it while it runs: giz live main.giz.
export function greeting(): string {
    return "Hello, Gizlang!";
}

function main(): void {
    print(greeting());
}
```

```sh
giz run main.giz
```

```text output
Hello, Gizlang!
```

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.

To add a file, write it and import it by its path: `import {name} from "./name.giz";`. No other step is necessary.

## 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. Check, format and build it

```sh
giz check main.giz       # the errors, with their source lines, and no run
giz fmt main.giz         # lay out the file
giz build main.giz -o hello
./hello
```

The result of `giz build` is one native executable with no runtime to install.

## Keep the toolchain current

| Task | How |
| --- | --- |
| Upgrade | `npm install -g @gizai/cli@latest` |
| Pin a project's version | `giz init` puts `"version"` 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 | `giz vscode` installs the Gizlang extension into VS Code; it finds VS Code where it was installed, or says how to install it. Other editors start `giz lsp` as their language server ([command-line guide](guides/command-line.md#vs-code)). |
| Uninstall | `npm uninstall -g @gizai/cli`, then remove `~/.giz`. |

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 Apache 2.0
[license](https://github.com/gizai/gizlang/blob/main/LICENSE).

## Choose your next step

After the first program, choose the shortest path to a useful result.

| Goal | Next page | Result |
| --- | --- | --- |
| See the platform quickly | [Learning and examples](learning.md#platform-tour) | Run one example for each major subsystem |
| Learn the language | [Language guide](guides/language.md) | Write typed native programs |
| Build a web application | [GizWeb guide](guides/web.md) and [Todo lab](labs/todo-app.md) | Ship routes, forms, data and tests |
| Query or operate data | [GizDB guide](guides/data.md) | Store and query application data |
| Run models | [Compute guide](guides/compute.md) | Run tensors and generative models |
| Build an agent | [Agent guide](guides/agent.md) and [GizDesk lab](labs/gizdesk.md) | Connect models, tools and knowledge |

The [Learning page](learning.md) combines the platform tour with role-based paths and complete labs.

## Next

- [Learn Gizlang](learning.md): platform tour, learning paths, examples and complete labs.
- [The language](guides/language.md): the language for a TypeScript, JavaScript or Go developer.
- [Differences from TypeScript](reference/typescript.md): what a TypeScript developer must know first.
- [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.