Conceptos básicos de WebAssembly y TinyGo

10 ejemplos para empezar con WASM y TinyGo: 7 básicos y 3 intermedios.

Prerrequisitos

• Instala Go 1.26.x desde go.dev/dl.
• Instala un runtime WASI: brew install wasmtime (macOS) o descárgalo desde wasmtime.dev.
• Opcional: instala TinyGo desde tinygo.org/getting-started y verifica con tinygo version.
• Crea un módulo temporal: mkdir wasmdemo && cd wasmdemo && go mod init example.com/wasmdemo.

Ejemplos básicos

1. Compila "hello world" a WASI

La prueba más pequeña de que Go emite un módulo .wasm ejecutable.

package main
 
import "fmt"
 
func main() {
    fmt.Println("hello from wasip1/wasm")
}

GOOS=wasip1 GOARCH=wasm go build -o hello.wasm .
wasmtime run hello.wasm

• GOOS=wasip1 selecciona las importaciones de WASI Preview 1 en lugar de las llamadas al sistema de Linux.
• La salida es un único artefacto hello.wasm, sin binario de Go separado.
• wasmtime run proporciona las importaciones del host WASI que el módulo espera.

Relacionado: Compilación con GOOS=wasip1 GOARCH=wasm - banderas y opciones del enlazador

2. Elimina símbolos de depuración para un WASM más pequeño

Reduce el tamaño de descarga con banderas estándar del enlazador.

GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o hello.wasm .

• -s omite la tabla de símbolos; -w omite la información de depuración DWARF.
• Seguro para compilaciones de lanzamiento; conserva los artefactos sin despojar para la depuración de perfiles si es necesario.
• Las reducciones de tamaño son modestas en comparación con la elección de TinyGo, pero las banderas son gratuitas.

Relacionado: Optimización de tamaño de WASM: TinyGo vs gc WASM - tácticas de tamaño más profundas

3. Lee variables de entorno WASI

WASI expone os.Getenv a través de importaciones del host.

package main
 
import (
    "fmt"
    "os"
)
 
func main() {
    fmt.Println("USER=", os.Getenv("USER"))
}

wasmtime run --env USER=ada hello-env.wasm

• No todos los hosts pre-pueblan las mismas claves que Linux.
• Pasa banderas --env explícitas en wasmtime para pruebas reproducibles.
• Trata el entorno como una capacidad que el host otorga, no como un estado global implícito.

4. Escribe un archivo a través de pre-apertura WASI

El acceso al sistema de archivos requiere que el host pre-abra directorios.

GOOS=wasip1 GOARCH=wasm go build -o write.wasm .
mkdir -p /tmp/wasmout
wasmtime run --dir /tmp/wasmout::/data write.wasm

os.WriteFile("/data/out.txt", []byte("ok"), 0o644)

• Las rutas dentro del invitado se mapean a directorios del host a través de la sintaxis --dir host::guest.
• Falla cerrado si el directorio no está pre-abierto; bueno para sandboxing.
• Refleja este patrón en wazero con montajes de directorios FSConfig.

5. TinyGo "hello" en WASM

TinyGo emite módulos mucho más pequeños cuando su subconjunto de stdlib es suficiente.

package main
 
import "fmt"
 
func main() {
    fmt.Println("hello from tinygo wasm")
}

tinygo build -target=wasm -o tinyhello.wasm .
wasmtime run tinyhello.wasm

• -target=wasm selecciona el backend WASM genérico (verifica las placas específicas por separado).
• Confirma qué paquetes de la biblioteca estándar soporta tu versión de TinyGo antes de portar bibliotecas.
• Espera arranques en frío más rápidos en hosts con restricciones de tamaño.

Relacionado: TinyGo para microcontroladores y WASM con restricciones - objetivos de placa

6. Esqueleto de compilación para navegador

Aísla los puntos de entrada solo para el navegador de las compilaciones WASI.

//go:build js && wasm
 
package main
 
import "syscall/js"
 
func main() {
    js.Global().Get("console").Call("log", "hello browser")
    select {}
}

GOOS=js GOARCH=wasm go build -o main.wasm .

• select {} mantiene main vivo para que los callbacks puedan activarse.
• Empareja con wasm_exec.js de $(go env GOROOT)/misc/wasm/wasm_exec.js en hosts de HTML.
• No importes syscall/js en paquetes wasip1.

Relacionado: syscall/js: Go en el navegador - callbacks DOM

7. Lista las exportaciones de WASM con wasm-tools

Inspecciona la superficie del módulo antes de incrustarlo.

wasm-tools print hello.wasm | head

• Confirma _start, la exportación de memoria y los nombres de importación WASI.
• Las importaciones que no coinciden son la principal razón por la que la instanciación falla en los hosts.
• Añade wasm-tools a través de cargo install wasm-tools o tu gestor de paquetes.

Ejemplos intermedios

8. Incrusta WASI en Go con wazero

Ejecuta un módulo invitado desde un servicio Go sin cgo.

package main
 
import (
    "context"
    "os"
 
    "github.com/tetratelabs/wazero"
    "github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
)
 
func main() {
    ctx := context.Background()
    r := wazero.NewRuntime(ctx)
    defer r.Close(ctx)
    wasi_snapshot_preview1.MustInstantiate(ctx, r)
 
    wasmBytes, _ := os.ReadFile("hello.wasm")
    mod, _ := r.Instantiate(ctx, wasmBytes)
    defer mod.Close(ctx)
 
    start := mod.ExportedFunction("_start")
    _, _ = start.Call(ctx)
}

• wasi_snapshot_preview1 registra las importaciones WASI que el módulo Go necesita.
• Instantiate compila y carga el bytecode; reutiliza Runtime entre solicitudes en servidores.
• Pasa plazos de context para limitar el tiempo de ejecución del invitado.

Relacionado: Runtimes Host WASI: wasmtime, wazero y Spin - comparación de runtimes

9. Prueba de humo de CI para artefactos WASM

Detecta compilaciones rotas antes de desplegar.

GOOS=wasip1 GOARCH=wasm go build -o /tmp/app.wasm ./...
wasmtime run /tmp/app.wasm

• Añade el trabajo junto a las comprobaciones de compilación GOOS=linux GOARCH=amd64.
• Falla el pipeline en códigos de salida distintos de cero de wasmtime run.
• Fija las versiones de wasmtime y tinygo en las imágenes de CI para reproducibilidad.

Relacionado: Mejores prácticas de WebAssembly y TinyGo - higiene de CI e importaciones

10. Compara tamaños de binarios gc vs TinyGo

Toma decisiones basadas en datos sobre las herramientas.

GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o gc.wasm .
tinygo build -target=wasm -o tiny.wasm .
ls -lh gc.wasm tiny.wasm

• Registra los tamaños en ADRs al elegir TinyGo vs gc para funciones de borde.
• Empareja el tamaño con datos de benchmark: el runtime de TinyGo difiere del planificador de gc.
• Vuelve a medir después de las actualizaciones menores de Go; 1.26 mejoró la memoria del heap, no siempre el tamaño del archivo.

Relacionado: Guía de decisión: Go nativo vs TinyGo vs Rust WASM - compensaciones clasificadas

Versiones de la pila: Esta página se escribió para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).