# Getting started

Un tour de 10 minutos por Niell — instalación, primer programa, segundo programa, próximos pasos. Asume Linux x86_64 con clang instalado; para otras plataformas ver [Install](install.html).

## Instalación rápida

```bash
sudo apt install -y clang xz-utils
curl -L https://niell.dev/dl/niell-linux-x86_64.xz | xz -d > niell
chmod +x niell
sudo mv niell /usr/local/bin/
niell --help
```

El binario es self-contained respecto a LLVM 18 — no necesitas instalar el toolchain de Rust. Sí necesitas `clang` porque Niell lo invoca para linkear el runtime C con el IR emitido.

## Tu primer programa

Crea `hello.niell`:

```niell
action main
  show with "hola, niell"
end
```

Compila y ejecuta:

```bash
niell hello.niell -o hello
./hello
# → hola, niell
```

`niell` produce tres archivos al lado del fuente:
- `hello` — el ejecutable nativo
- `hello.ll` — el LLVM IR generado (útil para entender qué hace el compilador)
- Outputs intermedios temporales que se limpian solos

## Un programa con tipos y acciones

Niell te deja declarar tipos compuestos y acciones que operan sobre ellos. Crea `geometry.niell`:

```niell
type Point has
  x: number
  y: number
end

action distance with a: Point, b: Point -> number
  dx: number = b.x - a.x
  dy: number = b.y - a.y
  return sqrt of (dx * dx + dy * dy)
end

action main
  origin: Point
    x = 0
    y = 0
  end
  target: Point
    x = 3
    y = 4
  end
  show with "distancia: {distance with origin, target}"
end
```

Compila y ejecuta:

```bash
niell geometry.niell -o geometry
./geometry
# → distancia: 5
```

Nota cómo:
- Los tipos van con mayúscula (`Point`), las acciones y campos con minúscula (`distance`, `x`)
- La construcción de una instancia usa `nombre: Tipo ... end` con asignación por campo
- La invocación es siempre `accion with arg1, arg2` — nunca `instancia.metodo`
- `{distance with origin, target}` interpola el resultado dentro del string

## Introspección del compilador

Niell expone su propia descripción para que humanos y herramientas puedan saber qué entiende el compilador:

```bash
niell describe --json | head -20
```

Devuelve un schema versionado con keywords, tipos primitivos, módulos built-in, prelude, y catálogo de error codes. Útil para escribir un agente que escribe Niell, o para chequear qué features están disponibles sin parsear la spec.

Para inspeccionar un código de error específico:

```bash
niell explain NIELL-PARSE-001
```

## Próximos pasos

- [01 Sintaxis](01-sintaxis.html) — sensibilidad a mayúsculas, palabras clave, operadores, precedencia
- [02 Tipos](02-tipos.html) — primitivos, relaciones estructurales, sistema de tipos
- [04 Acciones y errores](04-acciones.html) — firmas, returns, sobrecarga, `fails with`
- [Keywords](keywords.html) — catálogo completo

Si te trabas, los códigos de error de `niell` llevan referencia a la sección de la spec donde está documentada la regla — usa `niell explain <CODE>` para navegarla.