---
name: build_wasm_cpp_app
kind: function
lang: bash
domain: infra
version: "0.1.0"
purity: impure
signature: "build_wasm_cpp_app(app_name: string, [--no-budget-check]) -> void"
description: "Compila una app C++ del registry (cpp/apps/<name>) a WASM via emscripten. Sale build/wasm/<name>/<name>.{html,js,wasm,wasm.gz}. Falla si gzip > 2 MB."
tags: [wasm, emscripten, cpp, build, gamedev]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
example: "bash bash/functions/infra/build_wasm_cpp_app.sh engine_smoke"
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/infra/build_wasm_cpp_app.sh"
params:
  - name: app_name
    desc: "Nombre del directorio bajo cpp/apps/. Debe contener CMakeLists.txt self-sufficient (top-level project) con guard `if(EMSCRIPTEN)` para flags wasm."
  - name: "--no-budget-check"
    desc: "Opcional. Salta verificacion de tamaño (gzip < 2 MB hard, < 1.5 MB soft)."
output: "Reporte de tamaños en stdout. Crea build/wasm/<app>/<app>.html/.js/.wasm/.wasm.gz. Exit 3 si excede budget hard."
---

# build_wasm_cpp_app

Compila apps C++ del registry a WebAssembly. Issue 0072d (parte del stack gamedev).

## Requisitos

- `emsdk` instalado y activo en el shell, o presente en `<repo>/emsdk/` (autoactiva).
- `cpp/apps/<app>/CMakeLists.txt` con bloque `if(EMSCRIPTEN) ... endif()` que define los flags wasm (USE_WEBGL2, FULL_ES3, ALLOW_MEMORY_GROWTH, etc.).
- `cpp/CMakeLists.txt` debe seguir tolerando configuracion via `emcmake`. La app target se elige con `cmake --build $BUILD_DIR --target <app>`.

## Flujo

1. Localiza `emcc` en PATH o autoactiva `<repo>/emsdk/emsdk_env.sh`.
2. `emcmake cmake -S cpp -B build/wasm/<app> -DCMAKE_BUILD_TYPE=MinSizeRel`
3. `cmake --build build/wasm/<app> --target <app> -j`
4. `gzip -9 -k <app>.wasm` y `brotli -q 11 -k <app>.wasm` (si brotli disponible).
5. Reporta tamaños y compara contra budget (1.5 MB gzip soft, 2 MB hard).

## Budgets

| Limite | Valor | Comportamiento |
|---|---|---|
| Soft | 1.5 MB gzip | Warning, sigue |
| Hard | 2 MB gzip | Exit 3, falla |

Skip con `--no-budget-check`.

## Apps soportadas

Cualquier app bajo `cpp/apps/<name>/` cuyo `CMakeLists.txt` defina target con flags emscripten. Probada con: `engine_smoke` (issue 0072a).

## Errores comunes

- `emcc no encontrado` → instalar emsdk segun instrucciones del propio script.
- `<app>.wasm no encontrado` → fallo de build. Re-ejecutar con `2>&1 | tee` para ver compiler errors.
- `wasm.gz excede budget` → revisar bloat, usar `twiggy top` o `wasm-objdump -h`. Ver issue 0072d.