Primeiros Passos
Carregando Wasm no JS
WebAssembly (Wasm) é um formato binário que roda a velocidade quase nativa nos navegadores. instantiateStreaming carrega e compila um arquivo .wasm. As exportações são funções chamáveis a partir do JavaScript.
// Load and instantiate a .wasm module
WebAssembly.instantiateStreaming(fetch('module.wasm'))
.then(result => {
const { instance } = result;
// call exported functions
console.log(instance.exports.add(2, 3)); // 5
});
// Alternative: from ArrayBuffer
const bytes = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
WebAssembly.instantiate(bytes).then(result => {
console.log(result.instance.exports);
});WebAssembly Module e Instance
WebAssembly.Module é a representação compilada e sem estado — segura para reusar em múltiplas instâncias. WebAssembly.Instance guarda o estado em runtime (memória, globals). Compilar uma vez e instanciar muitas é eficiente para criar workers paralelos.
// Two-step: compile then instantiate
const module = await WebAssembly.compile(bytes);
const instance = await WebAssembly.instantiate(module, importObject);
console.log(instance.exports.add(1, 2));
// Module is stateless & shareable across instances
const instance2 = await WebAssembly.instantiate(module, importObject);
// Each instance has its own memory and globalsSuporte de Navegadores e Detecção de Recursos
WebAssembly 1.0 é suportado em cada um dos navegadores modernos. Propostas mais novas (SIMD, exceções, threads, GC) precisam de detecção de recursos. WebAssembly.validate verifica se os bytes formam um módulo válido sem compilar.
// Check basic WebAssembly support
if (typeof WebAssembly !== 'undefined') {
console.log('WebAssembly is supported');
}
// Verify the engine can actually compile
WebAssembly.validate(new Uint8Array([
0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00
])); // true if valid module
// Feature-detect newer proposals
const hasSIMD = typeof WebAssembly.Module !== 'undefined';
const hasExceptions = 'exceptions' in WebAssembly;Streaming vs Não-Streaming
instantiateStreaming compila o módulo conforme ele é transmitido pela rede — inicialização mais rápida. O servidor DEVE enviar 'Content-Type: application/wasm'. Se usar um CDN ou host estático sem esse header, caia para o caminho com ArrayBuffer.
// Streaming (preferred): compiles while downloading
WebAssembly.instantiateStreaming(fetch('m.wasm'), imports);
// Non-streaming: must download fully first
const res = await fetch('m.wasm');
const buf = await res.arrayBuffer();
WebAssembly.instantiate(buf, imports);
// Streaming requires correct MIME type:
// Content-Type: application/wasmNúmero Mágico e Header do Wasm
O número mágico binário do Wasm é a string ASCII '\0asm' seguida de uma versão de 4 bytes little-endian. Esse header permite validar que um arquivo é Wasm antes de compilar. O formato é organizado em seções (Type, Import, Function, Memory, etc.).
// Every .wasm file starts with this 8-byte header:
// 0x00 0x61 0x73 0x6d -> "\0asm"
// 0x01 0x00 0x00 0x00 -> version 1
const magic = [0x00, 0x61, 0x73, 0x6d];
const version = [0x01, 0x00, 0x00, 0x00];
// Quick validity check
function isWasm(bytes) {
return bytes[0] === 0x00 && bytes[1] === 0x61
&& bytes[2] === 0x73 && bytes[3] === 0x6d;
}Hello Wasm (Exemplo Mínimo)
Um app Wasm mínimo: o módulo importa uma função 'log' do JS e exporta 'greet' que a chama. O formato WAT (WebAssembly Text) é a representação legível, compilada para binário com wat2wasm. Os navegadores só executam a forma binária.
<!-- index.html -->
<script>
WebAssembly.instantiateStreaming(fetch('hello.wasm'))
.then(({ instance }) => {
instance.exports.greet(); // logs "Hello, Wasm!"
});
</script>
;; hello.wat (compiled to hello.wasm via wat2wasm)
(module
(import "console" "log" (func $log (param i32)))
(func (export "greet")
i32.const 72 ;; 'H'
call $log
)
)Formato de Texto WAT
Module e S-Expressões
WAT (WebAssembly Text format) é a representação textual do Wasm. Tudo é envolvido numa s-expressão (module ...). As instruções são escritas em ordem baseada em pilha: operandos empilhados primeiro, depois a operação os consome.
;; WAT uses s-expressions: (keyword args...)
(module
;; function definitions, exports, etc. go here
)
;; Nested expressions form the instruction sequence
(module
(func $add (param $a i32) (param $b i32) (result i32)
local.get $a
local.get $b
i32.add
)
(export "add" (func $add))
)Comentários no WAT
WAT suporta dois estilos de comentário: ';;' para linha única e '(; ... ;)' para comentários de bloco. Comentários de bloco podem aninhar e atravessar várias linhas — úteis para desativar trechos de código durante o desenvolvimento.
;; Single-line comment (starts with ;;)
(func (export "f")
i32.const 1 ;; push 1
drop ;; discard
)
(; Block comment
can span
multiple lines ;)
(func (export "g")
nop
)Sintaxe de Definição de Funções
Funções são declaradas com (func ...). Parâmetros usam (param $nome tipo) e resultados usam (result tipo). O '$nome' é opcional — sem ele, funções/locais são referenciados por índice numérico. Retornos de múltiplos valores exigem a proposta multi-value (amplamente suportada).
;; Named function with params and result
(func $name (param $p1 i32) (param $p2 f64) (result i32)
;; body
)
;; Anonymous function (referenced by index)
(func (param i32) (result i32)
local.get 0
)
;; Multiple results (multi-value proposal)
(func $swap (param i32 i32) (result i32 i32)
local.get 1
local.get 0
)Export e Import Inline
WAT suporta anotações inline (export "nome") e (import "módulo" "campo") em funções, memórias, tabelas e globals — uma abreviação das formas estendidas (export ...) / (import ...). Ambas compilam para a mesma saída binária.
;; Inline export on a function
(func (export "add") (param i32 i32) (result i32)
local.get 0
local.get 1
i32.add
)
;; Inline import
(func $log (import "env" "log") (param i32))
;; Inline export on memory
(memory (export "mem") 1)
;; Expanded form (equivalent)
(func $add (param i32 i32) (result i32) ...)
(export "add" (func $add))Segmentos de Dados
Segmentos de dados inicializam a memória linear na instanciação (active) ou preguiçosamente via memory.init (passive). Strings incluem sequências de escape como \00 para terminador nulo e \n para quebra de linha. data.drop libera o armazenamento do segmento depois de copiar.
;; Initialize memory with bytes at offset 0
(memory 1)
(data (i32.const 0) "Hello, Wasm!\00")
;; Named data segment (active)
(data $msg (i32.const 0) "Hello\00")
;; Passive data segment (used with memory.init)
(data $passive "lazy-loaded bytes")
;; Drop a data segment to free its memory
(data.drop $msg)Conversão wat2wasm e wasm2wat
WABT (WebAssembly Binary Toolkit) fornece wat2wasm (texto→binário), wasm2wat (binário→texto), wasm-validate e wasm-objdump. Essenciais para inspecionar, depurar e escrever módulos Wasm à mão. A forma .wat é para humanos; a forma .wasm é o que os navegadores executam.
# Install the WebAssembly Binary Toolkit (WABT)
# macOS: brew install wabt
# Ubuntu: apt install wabt
# Convert text -> binary
wat2wasm hello.wat -o hello.wasm
# Convert binary -> text (disassemble)
wasm2wat hello.wasm -o hello.wat
# Validate a .wasm file
wasm-validate hello.wasm
# Print module structure
wasm-objdump -x hello.wasmTipos de Valor
Tipos Básicos (i32/i64/f32/f64)
Wasm tem apenas quatro tipos básicos de valor: i32, i64, f32, f64. A sinalidade dos inteiros é determinada pela operação (ex.: i32.div_s vs i32.div_u), não pelo tipo. Isso mantém o sistema de tipos mínimo e previsível.
;; Wasm has exactly four basic value types:
;; i32 - 32-bit integer
;; i64 - 64-bit integer
;; f32 - 32-bit float
;; f64 - 64-bit float
(func (param i32) (param i64) (param f32) (param f64)
(result f64)
local.get 2 ;; f32
f64.promote_f32
)
;; Integers are signed or unsigned PER OPERATION,
;; not per type. Use i32.add_s / i32.div_u etc.Literais Numéricos no WAT
Literais numéricos no WAT suportam formas decimal, hex (0x) e binária (0b). Floats suportam notação científica, infinito (inf) e NaN. Literais WAT são sem sinal por padrão — inteiros negativos são codificados com um '-' inicial.
;; Integer literals
i32.const 42
i32.const -7
i32.const 0xff ;; hex
i32.const 0b1010 ;; binary
;; Float literals
f64.const 3.14
f64.const 1e10
f64.const -0.0
f64.const inf
f64.const nan
;; 64-bit
i64.const 9007199254740992 ;; 2^53Conversões de Tipo
Conversões usam um esquema de nomes consistente: extend (menor→maior), wrap (maior→menor), convert (int↔float), reinterpret (cast em nível de bits), demote/promote (precisão float). Variantes com sinal usam _s, sem sinal usam _u.
;; Extend i32 to i64
i64.extend_i32_s ;; sign-extend
i64.extend_i32_u ;; zero-extend
;; Wrap i64 to i32
i32.wrap_i64
;; Integer <-> Float
f32.convert_i32_s
f64.convert_i64_u
i32.trunc_f32_s ;; truncate (toward zero)
i32.reinterpret_f32 ;; bit-level reinterpret
;; Demote / promote floats
f32.demote_f64
f64.promote_f32Tipo SIMD v128
O tipo v128 empacota 16 bytes num único registrador SIMD. As lanes são endereçadas como i32x4 (4×int32), f32x4 (4×float32), i16x8, i8x16, f64x2. SIMD acelera cargas de imagem/áudio/cripto operando em múltiplos valores por instrução.
;; SIMD: 128-bit vector type (fixed-width SIMD proposal)
(module
(func (param v128) (result v128)
local.get 0
v128.not ;; bitwise NOT
)
(func (result v128)
v128.const i32x4 1 2 3 4
)
)
;; Vector operations: i32x4, i16x8, i8x16, f32x4, f64x2
v128.const f32x4 1.0 2.0 3.0 4.0
i32x4.addTipos de Referência (funcref/externref)
A proposta de reference types adiciona funcref (ponteiro de função) e externref (referência opaca ao host). externref é poderoso: permite que o Wasm segure objetos JS sem copiar ou serializar. Combinado com tabelas, permite padrões flexíveis de callback.
;; Reference types proposal adds:
;; funcref - reference to a function (in a table)
;; externref - opaque reference to a host (JS) object
(module
(table 1 funcref)
(func (param externref) (result externref)
local.get 0 ;; pass through a JS object
)
)
;; In JS, externref lets you pass arbitrary objects
;; through Wasm without serialization:
instance.exports.store({ hello: 'world' });Funções
Definindo e Chamando Funções
Funções são a unidade fundamental de código. call invoca uma função por nome/índice. Os argumentos são empilhados antes da chamada; os resultados ficam na pilha quando a função retorna. A pilha precisa casar com a declaração (result ...).
(module
(func $add (param $a i32) (param $b i32) (result i32)
local.get $a
local.get $b
i32.add
)
(func $double (param $x i32) (result i32)
local.get $x
local.get $x
i32.add ;; or: i32.const 2 i32.mul
)
(func (export "use")
i32.const 5
i32.const 7
call $add ;; -> 12 on stack
drop
)
)Parâmetros e Variáveis Locais
Parâmetros são locais imutáveis indexados a partir de 0. Locais declarados (local $nome tipo) são inicializados com zero e mutáveis. Use local.get, local.set e local.tee (set + deixa na pilha). Locais são o único armazenamento mutável do Wasm fora de memória/globals.
(func $f (param $a i32) (param $b i32) (result i32)
(local $sum i32) ;; mutable local
(local $i i32)
local.get $a
local.get $b
i32.add
local.set $sum ;; store into local
i32.const 0
local.set $i
local.get $sum
)
;; tee: set and keep on stack
local.tee $sum ;; $sum = top; stays on stackMúltiplos Valores de Retorno
A proposta multi-value permite que funções retornem múltiplos valores (e aceitem zero). Todas as engines principais suportam desde 2020. Isso elimina a necessidade de parâmetros de saída via memória e torna idiomas como swap/minmax naturais.
;; Multi-value: return two i32 values
(func $minmax (param $a i32) (param $b i32) (result i32 i32)
local.get $a
local.get $b
i32.lt_s
if (result i32 i32)
local.get $a
local.get $b
else
local.get $b
local.get $a
end
)
;; Caller receives both on the stack
(func (export "use")
i32.const 3
i32.const 8
call $minmax
;; stack: [min=3, max=8]
drop drop
)Recursão
Wasm suporta recursão direta — uma função pode chamar a si mesma. Não há otimização de tail-call no Wasm MVP (a proposta tail-call adiciona return_call). Recursão profunda arrisca estouro de pilha, então loops iterativos são preferidos em código de produção.
(module
(func $fact (param $n i32) (result i32)
local.get $n
i32.const 1
i32.le_s
if (result i32)
i32.const 1
else
local.get $n
local.get $n
i32.const 1
i32.sub
call $fact ;; recursive call
i32.mul
end
)
(export "factorial" (func $fact))
)Export Inline e Chamadas Nomeadas
(export "nome") inline numa definição de função é abreviação de uma declaração (export ...) separada. call_ref (proposta de reference types) invoca uma função via funcref diretamente, permitindo valores de função de primeira classe sem busca em tabela.
(module
;; Inline export on definition
(func $add (export "add") (param i32 i32) (result i32)
local.get 0
local.get 1
i32.add
)
;; call_ref: call via funcref (reference types)
(func $caller (param $f funcref) (param i32) (result i32)
local.get 1
local.get 0
call_ref (param i32) (result i32)
)
)Função Start
Um módulo pode declarar uma função (start $func) que roda automaticamente na instanciação — útil para inicialização. Não recebe argumentos e não retorna nada. Apenas uma função start é permitida por módulo.
(module
(func $init
;; runs once at instantiation
i32.const 0
i32.const 42
i32.store
)
(start $init) ;; declare as start function
(memory (export "mem") 1)
)
;; The start function runs automatically after
;; instantiation, before instantiate() resolves.
;; It takes no params and returns nothing.Memória
Declarando Memória Linear
A memória linear é uma região contígua semelhante a ArrayBuffer, crescida em páginas de 64KiB. (memory 1 10) declara inicial=1, máximo=10. A memória é o único jeito de passar dados em bloco (strings, arrays) entre Wasm e JS. Exporte-a para acessar do JS.
(module
;; 1 page = 64KiB. Declare 1 page, max 10.
(memory $mem 1 10)
(export "memory" (memory $mem))
;; JS-side: read/write the exported memory
;; const buf = new Uint8Array(instance.exports.memory.buffer);
)Memory Grow
memory.grow adiciona páginas e retorna o tamanho anterior (em páginas), ou -1 em falha. Crucialmente, crescer desanexa o ArrayBuffer subjacente — todas as views TypedArray existentes ficam inutilizáveis. Sempre recrie as views após qualquer chamada de grow.
(func $grow (result i32)
i32.const 1 ;; request 1 more page
memory.grow ;; returns previous size (or -1)
)
;; In JS, growing detaches the old buffer!
const prev = instance.exports.grow();
const buf = new Uint8Array(instance.exports.memory.buffer);
// OLD buf references are now detached — re-create views!Operações Load e Store
Loads/stores têm variantes por tamanho (8/16/32/64 bits) e extensão de sinal (_s/_u). offset=N adiciona uma constante ao operando de endereço; align= é uma dica (deve ser ≤ tamanho). Cada um dos endereços são offsets em bytes na memória linear.
;; Load: read from memory at address (top of stack)
i32.load offset=0 align=2 ;; 4-byte aligned load
i32.load8_u ;; 1 byte, zero-extended
i32.load16_s ;; 2 bytes, sign-extended
f64.load ;; 8-byte float load
;; Store: write value at address
i32.const 100 ;; address
i32.const 42 ;; value
i32.store ;; mem[100] = 42
i32.const 100
i32.const 0xFF
i32.store8 ;; write 1 byteTamanhos de Memória e Alinhamento
Alinhamento no Wasm é uma dica de desempenho, não uma restrição de correção — acesso desalinhado sempre funciona. O valor 'align' não deve exceder o tamanho natural da operação. memory.size retorna o número atual de páginas (cada uma 64KiB).
;; Each load/store has a natural alignment:
;; i32.load -> 4 bytes
;; i64.load -> 8 bytes
;; f32.load -> 4 bytes
;; i32.load8 -> 1 byte
;; Explicit alignment hint (does not affect correctness)
i32.load align=2 ;; may be slower but still works
;; memory.size returns current pages
(func $pages (result i32)
memory.size
)Memória Compartilhada e Atômicas
Memória compartilhada (proposta de threads) permite que múltiplas instâncias/Workers do Wasm compartilhem uma memória para paralelismo. Operações atômicas (i32.atomic.load/store/rmw.add/cmpxchg) fornecem sincronização. Exige isolamento cross-origin (headers COOP/COEP) nos navegadores.
(module
;; Shared memory (threads proposal)
(memory 1 1 shared)
(export "memory" (memory 0))
;; Atomic operations
(func (param i32 i32)
local.get 0 ;; address
local.get 1 ;; value
i32.atomic.store
)
(func (param i32) (result i32)
local.get 0
i32.atomic.load
)
(func (param i32) (result i32)
local.get 0
i32.const 1
i32.atomic.rmw.add ;; atomic read-modify-write
)
)Lendo Strings da Memória
Wasm não tem tipo string nativo — strings são sequências de bytes na memória linear, tipicamente passadas como pares (ponteiro, comprimento). TextEncoder/TextDecoder cuidam da conversão UTF-8. Sempre garanta que a região da memória é grande o suficiente antes de escrever.
// Wasm has no string type — strings live in linear memory.
// Decode UTF-8 from a (ptr, len) pair returned by Wasm:
function readString(memory, ptr, len) {
const bytes = new Uint8Array(memory.buffer, ptr, len);
return new TextDecoder('utf-8').decode(bytes);
}
// Writing a string into Wasm memory:
function writeString(memory, str, ptr) {
const bytes = new TextEncoder().encode(str);
const view = new Uint8Array(memory.buffer, ptr, bytes.length);
view.set(bytes);
return bytes.length; // return length
}Tabelas
Declarando Tabelas
Tabelas são arrays de referências (tipicamente funcref) usados para chamadas indiretas e despacho dinâmico. Diferente da memória (que guarda bytes), tabelas guardam referências opacas que o Wasm não pode forjar. Segmentos (elem ...) inicializam os slots da tabela na instanciação.
(module
;; A table of function references, initial size 1
(table 1 funcref)
(export "table" (table 0))
;; With max size
(table $t 4 16 funcref)
;; elem segment: initialize table slots
(elem (i32.const 0) $fn1 $fn2 $fn3)
(func $fn1)
(func $fn2)
(func $fn3)
)Tabelas funcref e call_indirect
call_indirect despacha uma chamada por um item da tabela, por índice. A declaração (type ...) é obrigatória — o Wasm verifica em runtime se a assinatura da função corresponde (mismatch de assinatura gera trap). Esta é a base de vtables e despacho OO no Wasm.
(module
(type $bin (func (param i32 i32) (result i32)))
(table 3 funcref)
(func $add (param i32 i32) (result i32)
local.get 0 local.get 1 i32.add)
(func $sub (param i32 i32) (result i32)
local.get 0 local.get 1 i32.sub)
(func $mul (param i32 i32) (result i32)
local.get 0 local.get 1 i32.mul)
(elem (i32.const 0) $add $sub $mul)
(func (export "dispatch") (param i32 i32 i32) (result i32)
local.get 0 ;; arg a
local.get 1 ;; arg b
local.get 2 ;; table index
call_indirect (type $bin)
)
)Grow, Get e Set de Tabela
table.grow acrescenta slots e retorna o tamanho anterior (ou -1). table.get/table.set leem/escrevem itens por índice. Crescer uma tabela permite registrar callbacks em runtime. Tamanho inicial + limites máximos de crescimento para evitar alocação descontrolada.
(func $addSlot (param funcref) (result i32)
local.get 0
i32.const 1 ;; grow by 1
table.grow ;; returns old size, or -1
)
(func $read (param i32) (result funcref)
local.get 0
table.get
)
(func $write (param i32 funcref)
local.get 0 ;; index
local.get 1 ;; funcref
table.set
)Tabelas externref para Objetos do Host
Tabelas externref armazenam referências opacas a objetos do host (JS) — o Wasm pode segurá-las e passá-las adiante, mas não pode inspecionar seu conteúdo. Ideal para registro de callbacks, tabelas de handles JS e ponte de APIs orientadas a objeto do JS para o Wasm.
(module
;; Table holding opaque JS objects
(table 8 externref)
(export "table" (table 0))
(func $store (param i32 externref)
local.get 0
local.get 1
table.set
)
(func $load (param i32) (result externref)
local.get 0
table.get
)
)
// JS: pass arbitrary objects
instance.exports.store(2, { callback: () => 42 });Padrão de Despacho Dinâmico
O padrão de despacho dinâmico: guarde operações numa tabela e depois chame com call_indirect por índice. Combinado com a verificação de tipo obrigatória, isso dá polimorfismo estilo vtable seguro. É assim que enums Rust, funções virtuais C++ e interpretadores implementam despacho.
(module
(type $op (func (param i32 i32) (result i32)))
(table 4 funcref)
(elem (i32.const 0) $add $sub $mul $div)
(func $add (param i32 i32) (result i32)
local.get 0 local.get 1 i32.add)
(func $sub (param i32 i32) (result i32)
local.get 0 local.get 1 i32.sub)
(func $mul (param i32 i32) (result i32)
local.get 0 local.get 1 i32.mul)
(func $div (param i32 i32) (result i32)
local.get 0 local.get 1 i32.div_s)
(func (export "apply") (param $op i32) (param $a i32) (param $b i32)
(result i32)
local.get $a
local.get $b
local.get $op
call_indirect (type $op)
)
)Globals
Declarando Globals
Globals são valores únicos no nível do módulo, imutáveis (padrão) ou mutáveis (mut). Persistem entre chamadas de função e são úteis para contadores, flags de configuração e constantes. Globals mutáveis são o único estado mutável compartilhado fora de memória/tabelas.
(module
;; Immutable global (const)
(global $counter (mut i32) (i32.const 0))
;; Read-only global
(global $pi f64 (f64.const 3.14159265))
(func $increment
global.get $counter
i32.const 1
i32.add
global.set $counter
)
)Globals Mutáveis vs Imutáveis
Sem 'mut', um global é imutável e global.set é erro de compilação. O inicializador deve ser uma expressão constante (ex.: i32.const, ref.null, global.get de um global importado imutável). Prefira imutável por padrão, por segurança.
(module
;; (global $name type init) -> immutable
;; (global $name (mut type) init) -> mutable
(global $version i32 (i32.const 3))
;; global.set $version ;; ERROR: immutable
(global $state (mut i32) (i32.const 0))
(func (export "toggle")
global.get $state
i32.eqz
if
i32.const 1 global.set $state
else
i32.const 0 global.set $state
end
)
)Importando Globals
Globals importados permitem que o host injete valores de configuração (ou objetos WebAssembly.Global) num módulo na instanciação. Globals importados imutáveis podem inicializar outros globals. WebAssembly.Global é o wrapper visível ao JS para globals mutáveis compartilhados.
(module
;; Import a global from JS
(global $env (import "env" "version") i32)
;; Mutable imported global
(global $flag (import "env" "flag") (mut i32))
(func (export "ver") (result i32)
global.get $env
)
)
// JS side
const imports = {
env: {
version: 3,
flag: new WebAssembly.Global({ value: 'i32', mutable: true }, 0)
}
};Exportando e Compartilhando Globals
Globals exportados são acessíveis do JS como objetos WebAssembly.Global com uma propriedade .value (legível e, se mutável, gravável). Compartilhar um objeto Global entre múltiplas instâncias de módulo é uma forma limpa de coordenar estado sem tocar na memória.
(module
(global $g (export "counter") (mut i32) (i32.const 0))
(func (export "inc")
global.get $g
i32.const 1
i32.add
global.set $g
)
)
// JS reads/writes the global directly
const g = instance.exports.counter;
g.value; // 0
instance.exports.inc();
g.value; // 1
g.value = 100; // write directlyCasos de Uso de Globals
Globals servem a três padrões: (1) constantes de configuração importadas, (2) contadores/estado persistentes compartilhados entre instâncias, (3) resultados de cálculo em cache. São mais simples que memória para valores únicos e visíveis a múltiplas instâncias se compartilhados via JS.
(module
;; Configuration constants
(global $maxSize (import "config" "maxSize") i32)
(global $debug (import "config" "debug") i32)
;; Persistent counters
(global $calls (mut i32) (i32.const 0))
(func (export "handle") (result i32)
global.get $calls
i32.const 1
i32.add
global.set $calls
global.get $calls
)
)Imports e Exports
Importando Funções
Imports permitem que o Wasm chame funções do host (JS). Cada import é identificado por um nome de dois níveis (módulo, campo). O objeto de import passado ao instantiate precisa corresponder a esses nomes. Imports são como o Wasm alcança o mundo exterior — I/O, logging, agendamento.
(module
;; Import a function under module.field naming
(func $log (import "console" "log") (param i32))
(func $now (import "env" "now") (result f64))
(func (export "run")
i32.const 42
call $log ;; -> console.log(42)
call $now
drop
)
)
// JS
WebAssembly.instantiateStreaming(fetch('m.wasm'), {
console: { log: x => console.log('wasm:', x) },
env: { now: () => performance.now() }
});Importando Memória
Importar memória permite que múltiplos módulos Wasm (e o JS) compartilhem uma região de memória — a base para 'bibliotecas' Wasm. Um módulo aloca e escreve; outro lê. Isso compõe módulos sem copiar dados e é o precursor do component model.
(module
(memory (import "env" "memory") 1)
(func (export "writeHi")
i32.const 0
i32.const 72 ;; 'H'
i32.store8
)
)
// Shared memory across multiple modules:
const memory = new WebAssembly.Memory({ initial: 1 });
WebAssembly.instantiateStreaming(fetch('a.wasm'), { env: { memory } });
WebAssembly.instantiateStreaming(fetch('b.wasm'), { env: { memory } });
// Both modules read/write the SAME memoryImportando Globals e Tabelas
Globals e tabelas também podem ser importados, habilitando estado compartilhado e tabelas de ponteiros de função entre módulos. WebAssembly.Table é o construtor JS. Globals mutáveis importados deixam o host influenciar o comportamento do Wasm dinamicamente, sem reconstruir o módulo.
(module
(global $seed (import "env" "seed") i32)
(table (import "env" "table") 4 funcref)
(func (export "rand") (result i32)
global.get $seed
i32.const 1103515245
i32.mul
i32.const 12345
i32.add
;; (truncated LCG step)
)
)
// JS provides the imports
const imports = {
env: {
seed: 42,
table: new WebAssembly.Table({
element: 'funcref', initial: 4, maximum: 16
})
}
};Exportando Funções, Memória, Tabelas
Tudo o que é declarado num módulo pode ser exportado: funções, memória, tabelas, globals. As exportações viram propriedades em instance.exports. Exportações de memória dão ao JS uma visão do heap linear; globals exportados expõem objetos WebAssembly.Global; tabelas exportadas expõem referências de função.
(module
(memory 1)
(table 2 funcref)
(global $c (mut i32) (i32.const 0))
(func (export "add") (param i32 i32) (result i32)
local.get 0 local.get 1 i32.add)
(export "memory" (memory 0))
(export "table" (table 0))
(export "counter" (global $c))
)
// JS usage
const { add, memory, table, counter } = instance.exports;
add(2, 3); // 5
new Uint8Array(memory.buffer); // raw bytes
table.get(0); // funcref
counter.value; // 0Imports e Exports Inline
Anotações inline (import "m" "f") e (export "nome") são açúcar sintático — compilam para o mesmo binário que as formas separadas (import ...)/(export ...). Uma única definição pode ter export inline, mas imports e exports são declarados separadamente para itens importados.
(module
;; Inline import (compact form)
(func $log (import "env" "log") (param i32))
;; Inline export on function
(func (export "add") (param i32 i32) (result i32)
local.get 0 local.get 1 i32.add
)
;; Inline export on memory
(memory (export "mem") 1)
;; Inline import + export combined is NOT allowed;
;; a definition imports OR exports, not both.
)Boas Práticas do Objeto de Import
Estruture o objeto de import para corresponder aos nomes (módulo, campo) do módulo. Valide os imports obrigatórios antes da instanciação para dar erros claros. Envolva funções do host com try/catch quando apropriado — um throw não capturado dentro de um import gera trap no chamador Wasm.
// Build a typed import object
const imports = {
env: {
log: (i) => console.log('[wasm]', i),
now: () => performance.now(),
abort: () => { throw new Error('wasm abort'); },
memory: new WebAssembly.Memory({ initial: 1 }),
seed: 42,
}
};
// Validate imports before instantiation:
function checkImports(imports, required) {
for (const [mod, fields] of Object.entries(required)) {
for (const f of fields) {
if (!imports[mod]?.[f] === undefined) {
throw new Error(`Missing import: ${mod}.${f}`);
}
}
}
}Fluxo de Controle
block
block cria um escopo rotulado do qual as ramificações saem (via br). Ramificações no Wasm são estruturadas — só podem saltar para o fim de um block/loop/if envolvente. Um block com (result ...) deixa seu valor na pilha quando se salta para ele ou quando o fluxo passa por ele.
;; block: a labeled group with a single exit
(block $b
i32.const 1
i32.const 2
i32.add
;; br $b exits the block (with optional value)
br $b
;; unreachable code
)
;; stack now has the result of the block
;; Blocks can produce a value (multi-value):
(block $b (result i32)
i32.const 42
br $b
)loop
loop é como block, mas br $loop salta para o TOPO do loop (continuando a iteração) em vez do fim. É o oposto do block. Wasm não tem palavras-chave for/while — a iteração é construída com loop + um br_if condicional.
;; loop: a block whose br jumps back to the TOP
(func $count (param $n i32) (result i32)
(local $i i32) (local $sum i32)
i32.const 0 local.set $i
i32.const 0 local.set $sum
(loop $loop
local.get $i
local.get $n
i32.lt_s
if
local.get $sum
local.get $i
i32.add
local.set $sum
local.get $i
i32.const 1
i32.add
local.set $i
br $loop ;; jump back to loop start
end
)
local.get $sum
)if / else
if consome um i32 da pilha (não zero = verdadeiro). A cláusula (result ...) faz o if produzir um valor quando ambos os ramos concordam no tipo. if sem else é permitido; o ramo pode estar vazio. if é açúcar para block + br_if.
;; if consumes a condition from the stack
(func $abs (param $x i32) (result i32)
local.get $x
if (result i32)
local.get $x
else
i32.const 0
local.get $x
i32.sub ;; negate
end
)
;; if without else (no result)
(func (param i32)
local.get 0
if
;; do something only if non-zero
end
)br e br_if
br $label salta para o FIM do block/if nomeado (ou o TOPO de um loop). br_if faz o mesmo condicionalmente. Labels também podem ser numéricos (br 0 = mais interno). Ramificar com um valor o deixa na pilha — a forma idiomática do Wasm de retornar cedo.
;; br: unconditional branch to a label
(block $outer
(block $inner
br $inner ;; exits inner
br $outer ;; exits outer (unreachable here)
)
)
;; br_if: branch only if top of stack is non-zero
(func $clamp (param $x i32) (result i32)
(block $done (result i32)
local.get $x
i32.const 100
i32.gt_s
br_if $done ;; if x > 100, branch with...
i32.const 100 ;; ...100 on the stack
local.get $x
i32.const 0
i32.lt_s
br_if $done ;; if x < 0, branch with...
i32.const 0 ;; ...0
local.get $x ;; else x
)
)br_table (switch)
br_table implementa um switch: consome um índice i32 e salta para um dos labels listados, ou o último label (padrão) se estiver fora do intervalo. Aninhe os blocks do mais externo para o mais interno para que cada caso possa retornar seu valor. É a forma mais eficiente de despachar por tag.
;; br_table: jump table (like a C switch)
(func $dayName (param $d i32) (result i32)
(block $default
(block $sat
(block $sun
local.get $d
br_table $sun $sat $default
)
i32.const 0 ;; Sunday
return
)
i32.const 6 ;; Saturday
return
)
i32.const -1 ;; default
)
;; br_table $l0 $l1 $l2 ... $default
;; index 0 -> $l0, 1 -> $l1, ... out-of-range -> $defaultreturn e unreachable
return sai imediatamente da função com o valor na pilha. unreachable sempre gera trap (lança exceção em runtime) — usado para marcar caminhos de código que nunca deveriam executar, parecido com assert(false). Ambos são válvulas de escape de fluxo de controle além do modelo estruturado de blocos.
(func $find (param $arr i32) (param $len i32) (param $key i32)
(result i32)
(local $i i32)
i32.const 0 local.set $i
(block $notFound
(loop $loop
local.get $i
local.get $len
i32.ge_s
br_if $notFound
;; load arr[i] and compare...
local.get $i
i32.const 1
i32.add
local.set $i
br $loop
)
)
unreachable ;; traps if reached
)
;; return: early exit from the function
;; unreachable: always traps (used to mark bugs)Interoperabilidade com JS
Passando Números
i32/f32/f64 mapeiam diretamente para números JS. i64 mapeia para BigInt do JS (inteiros grandes excedem o intervalo seguro de Number). Use sempre BigInt para parâmetros/retornos i64. A conversão é zero-copy na fronteira, mas cruzá-la com frequência tem custo — agrupe operações no Wasm.
// Numbers pass directly across the Wasm/JS boundary.
const exports = instance.exports;
exports.add(2, 3); // 5 (i32 -> JS number)
exports.square(4); // 16
exports.compute(1.5, 2.5); // f64 -> JS number
// i64 caveat: before BigInt integration, i64 returns
// caused problems. Now Wasm i64 maps to JS BigInt:
const big = exports.bigResult(); // 9007199254740993n
// Passing a BigInt to an i64 param:
exports.takeBigInt(123n);Passando Strings
Strings atravessam a fronteira como sequências de bytes UTF-8: o JS as codifica na memória do Wasm e depois passa (ponteiro, comprimento). Frequentemente o Wasm exporta helpers alloc/free, ou você empacota ambos num único i64 (32 baixos = ptr, 32 altos = len). Sempre libere ou reutilize o buffer para evitar vazamentos.
// Wasm has no string type. Encode UTF-8 into memory,
// pass (ptr, len) to Wasm:
function passString(memory, str) {
const bytes = new TextEncoder().encode(str);
const ptr = instance.exports.alloc(bytes.length);
new Uint8Array(memory.buffer, ptr, bytes.length).set(bytes);
instance.exports.processString(ptr, bytes.length);
instance.exports.dealloc(ptr, bytes.length);
}
// Receiving a string back:
function recvString(memory, ptrLen) {
const ptr = ptrLen >>> 0;
const len = ptrLen >>> 32;
const bytes = new Uint8Array(memory.buffer, ptr, len);
return new TextDecoder().decode(bytes);
}Passando Arrays e Dados em Bloco
Para dados numéricos em bloco, veja a memória do Wasm como um TypedArray do tipo certo (Float32Array, Int32Array, etc.) e use .set() para copiar. Este é o caminho mais rápido — tipo memcpy. Lembre do alinhamento do ponteiro (4 bytes para i32/f32, 8 bytes para i64/f64) e sempre libere a memória.
// Write a JS array into Wasm memory:
function passArray(memory, arr) {
const view = new Float32Array(memory.buffer);
const ptr = instance.exports.alloc(arr.length * 4);
const offset = ptr / 4;
for (let i = 0; i < arr.length; i++) view[offset + i] = arr[i];
return ptr;
}
// Faster: use TypedArray.set with a subarray
function passArrayFast(memory, arr) {
const ptr = instance.exports.alloc(arr.length * 4);
new Float32Array(memory.buffer, ptr, arr.length).set(arr);
return ptr;
}Gestão de Memória Através da Fronteira
A memória do Wasm é gerenciada manualmente — não há garbage collector. Se o Wasm exporta alloc/free (ou você usa um helper estilo malloc), envolva o acesso JS em try/finally para garantir a liberação. Cuidado com memory.grow desanexando views de ArrayBuffer — recrie as views depois de crescer.
// Wasm has no GC — JS must manage allocations.
// Pattern: Wasm exports alloc/free, JS uses them:
const { memory, alloc, free, process } = instance.exports;
function withBuffer(size, fn) {
const ptr = alloc(size);
try {
return fn(new Uint8Array(memory.buffer, ptr, size));
} finally {
free(ptr, size);
}
}
// CAUTION: TypedArray views become detached after
// memory.grow — re-create them after any grow call.WebAssembly.Global
WebAssembly.Global é um wrapper JS em torno de um valor global do Wasm. Criar um e passá-lo a múltiplas instâncias de módulo compartilha estado mutável de forma limpa, sem tocar na memória. A propriedade .value lê/escreve o i32/i64/f32/f64 (ou v128/externref) subjacente.
// Create a global on the JS side
const counter = new WebAssembly.Global(
{ value: 'i32', mutable: true },
0
);
// Pass to Wasm at instantiation
WebAssembly.instantiateStreaming(fetch('m.wasm'), {
env: { counter }
});
// Read/write from JS
counter.value; // 0
counter.value = 10; // set
counter.value++; // 11
// Share across multiple instances
WebAssembly.instantiateStreaming(fetch('m2.wasm'), {
env: { counter } // same Global object
});WebAssembly.Table e Erros
WebAssembly.Table armazena referências de função acessíveis tanto do JS quanto do Wasm — útil para registros de callbacks e tabelas de despacho. Traps do Wasm (divisão por zero, memória fora dos limites, estouro de pilha) aparecem como WebAssembly.RuntimeError no JS — envolva chamadas arriscadas em try/catch.
// Table of function references, callable from JS indirectly
const table = new WebAssembly.Table({
element: 'funcref',
initial: 4,
maximum: 16
});
// Set a slot to a Wasm-exported function
table.set(0, instance.exports.add);
table.get(0)(2, 3); // 5
// Errors propagate as 'RuntimeError' across the boundary:
try {
instance.exports.divide(1, 0);
} catch (e) {
// e instanceof WebAssembly.RuntimeError
console.error('Wasm trapped:', e.message);
}Compilando C/C++ para Wasm
Configuração do Emscripten
Emscripten é a toolchain canônica para compilar C/C++ (e linguagens LLVM) para Wasm. Empacota Clang, Binaryen e uma libc/libstdc++ portada para o navegador. Ative o ambiente em cada sessão de shell com emsdk_env. As atualizações são frequentes — reinstale periodicamente.
# Install the Emscripten SDK
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh # Linux/macOS
# Windows: emsdk_env.bat
# Verify
emcc --version
# emcc (Emscripten gcc/clang-like replacement)Hello World em C
C padrão funciona como está — printf escreve num terminal virtual que o Emscripten fornece. main() é invocada automaticamente quando o módulo carrega. Funções chamadas do JS devem ser exportadas com EMSCRIPTEN_KEEPALIVE ou a flag -s EXPORTED_FUNCTIONS.
// hello.c
#include <stdio.h>
int add(int a, int b) {
return a + b;
}
int main() {
printf("Hello from C!\n");
printf("2 + 3 = %d\n", add(2, 3));
return 0;
}Compilando com emcc
emcc conduz a compilação. -O3 habilita otimizações agressivas (inlining, eliminação de código morto). EXPORTED_FUNCTIONS lista símbolos C (com _ inicial) a expor. MODULARIZE embrulha o loader como factory para uso em bundlers. Formatos de saída: só .wasm, .js de cola + .wasm, ou demo .html.
# Standalone .wasm (no main, exported functions only)
emcc add.c -O3 -o add.wasm \
-s EXPORTED_FUNCTIONS='["_add"]' \
-s ALLOW_MEMORY_GROWTH=1
# HTML + JS + Wasm bundle (auto-runs main)
emcc hello.c -o hello.html
# With optimizations and a specific output
emcc hello.c -O3 -s WASM=1 -o hello.js
# Common flags:
# -O0/-O1/-O2/-O3/-Os optimization level
# -s MODULARIZE=1 export as JS module
# -s EXPORT_ES6=1 ES module output
# -s ENVIRONMENT=web target only the webSaída HTML e Module do Emscripten
O objeto 'Module' do Emscripten é o runtime do lado JS: expõe funções C com prefixo _, gerencia memória (_malloc/_free) e fornece hooks (print, onRuntimeInitialized). MODULARIZE o torna uma factory que retorna Promise, adequada a bundlers e carregamento assíncrono.
// Generate a runnable HTML demo
// emcc hello.c -o hello.html
// Then open hello.html in a browser.
// Modularized loader (use from JS):
// emcc hello.c -o hello.js -s MODULARIZE=1 -s EXPORT_NAME='createModule'
import createModule from './hello.js';
const Module = await createModule({
print: (text) => console.log('C said:', text),
onRuntimeInitialized: () => {
Module._main(); // call main
const sum = Module._add(2, 3);
console.log('sum:', sum); // 5
}
});Chamando JS do C (EM_JS / EM_ASM)
EM_JS define uma função JS inline que o C pode chamar diretamente — eficiente e síncrona. EM_ASM embute um trecho JS inline. Use $0, $1, ... para argumentos. Essas macros colam o C às APIs do navegador (DOM, fetch, Web Audio) sem escrever bindings JS separados.
#include <emscripten.h>
// EM_JS: define a JS function callable from C
EM_JS(void, callAlert, (int x), {
alert("Value from C: " + x);
});
// EM_ASM: inline JS (use $n for arguments)
void logValue(int n) {
EM_ASM({
console.log("C passed:", $0);
}, n);
}
int main() {
callAlert(42);
logValue(99);
return 0;
}Suporte a Sistema de Arquivos (MEMFS)
Emscripten fornece MEMFS, um sistema de arquivos virtual em memória. fopen/fread/fwrite funcionam como no C. Use --preload-file para embutir assets no sidecar .data em tempo de compilação. Para armazenamento persistente, o IDBFS sincroniza com IndexedDB; o NODERAWFS expõe o FS real no Node.
#include <stdio.h>
#include <emscripten.h>
int main() {
// MEMFS: a virtual in-memory filesystem
FILE *f = fopen("/tmp/data.txt", "w");
fprintf(f, "Hello, MEMFS!\n");
fclose(f);
f = fopen("/tmp/data.txt", "r");
char buf[64];
fgets(buf, sizeof(buf), f);
fclose(f);
printf("%s", buf);
return 0;
}
// Preload files at compile time:
// emcc app.c -o app.html \
// --preload-file assets/data.txtCompilando Rust para Wasm
Configuração do wasm-pack
Rust compila para Wasm via o alvo wasm32-unknown-unknown. wasm-pack é a ferramenta recomendada — embrulha o cargo, roda wasm-bindgen e produz um pacote pronto para npm. Para alvos WASI, use wasm32-wasi.
# Install Rust (rustup)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Add the wasm32 target
rustup target add wasm32-unknown-unknown
# Install wasm-pack (the canonical Wasm tool for Rust)
cargo install wasm-pack
# or: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
# Verify
wasm-pack --versionEstrutura de Lib Rust
wasm-bindgen é a ponte entre Rust e JS. #[wasm_bindgen] marca itens para exportação. Strings, Vec<u8> e objetos JS são convertidos automaticamente. O atributo constructor expõe new() como construtor JS. Isso gera a cola JS que faz o Rust parecer nativo.
// src/lib.rs
use wasm_bindgen::prelude::*;
// Export a function callable from JS
#[wasm_bindgen]
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
// Export a struct with methods
#[wasm_bindgen]
pub struct Counter {
count: i32,
}
#[wasm_bindgen]
impl Counter {
#[wasm_bindgen(constructor)]
pub fn new() -> Counter {
Counter { count: 0 }
}
pub fn increment(&mut self) -> i32 {
self.count += 1;
self.count
}
}Build com wasm-pack
wasm-pack build produz um pacote npm publicável: o binário .wasm, a cola JS e arquivos .d.ts TypeScript. --target web dá um módulo ES autocontido para uso direto no navegador; --target bundler integra com webpack/vite. Os tipos gerados dão autocomplete TS completo.
# Build for the browser (npm package output)
wasm-pack build --target web
# Targets:
# --target web ES module, modern browsers
# --target bundler for webpack/rollup/vite
# --target nodejs CommonJS for Node.js
# --target no-modules global-based
# Output goes to ./pkg/
# my_crate.js JS glue
# my_crate_bg.wasm the binary
# my_crate.d.ts TypeScript types
# Use in JS:
import init, { add } from './pkg/my_crate.js';
await init(); // load the .wasm
console.log(add(2, 3)); // 5wasm-bindgen: Interop JS
Blocos extern importam funções e classes JS para o Rust. js_namespace = console chama console.log. method expõe funções JS em tipos importados. wasm-bindgen cuida das conversões de string (Rust &str <-> string JS) e da posse — sem malabarismo manual de memória.
use wasm_bindgen::prelude::*;
// Call a JS function from Rust
#[wasm_bindgen]
extern "C" {
#[wasm_bindgen(js_namespace = console)]
fn log(s: &str);
}
#[wasm_bindgen]
pub fn run() {
log("Hello from Rust!");
}
// Import a JS class
#[wasm_bindgen(module = "/js/util.js")]
extern "C" {
pub type JsCounter;
#[wasm_bindgen(constructor)]
pub fn new() -> JsCounter;
#[wasm_bindgen(method)]
pub fn tick(this: &JsCounter) -> i32;
}Chamando JS do Rust e Panics
Funções JS importadas aparecem como funções Rust comuns. Use console_error_panic_hook para obter backtraces de panic Rust legíveis no console do navegador (panics padrão geram trap sem mensagem). O atributo #[wasm_bindgen(start)] roda main() na instanciação — como o main do C.
use wasm_bindgen::prelude::*;
#[wasm_bindgen]
extern "C" {
fn alert(s: &str);
}
#[wasm_bindgen]
pub fn greet(name: &str) {
alert(&format!("Hello, {}!", name));
}
// Install a panic hook for readable errors:
#[wasm_bindgen(start)]
pub fn main() {
console_error_panic_hook::set_once();
}AssemblyScript
Configuração e Hello World
AssemblyScript é uma linguagem parecida com TypeScript que compila para Wasm. Mira desenvolvedores que querem o desempenho do Wasm sem aprender C/Rust. A sintaxe espelha o TS, mas com tipos estritos (i32 em vez de number). Use o loader ou importe o .wasm diretamente.
# Install AssemblyScript compiler
npm install -g assemblyscript
# or use the boilerplate:
npm init assemblyscript my-app
cd my-app
npm install
npm run asbuild
// assembly/index.ts
export function add(a: i32, b: i32): i32 {
return a + b;
}
// Load from JS:
import { instantiate } from "@assemblyscript/loader";
const module = await instantiate(fetch("build/release.wasm"));
console.log(module.exports.add(2, 3)); // 5Tipos no AssemblyScript
Diferente do TypeScript, o AssemblyScript impõe tipos numéricos concretos: i32, i64, f32, f64, u8, u16, u32, etc. 'number' é rejeitado em tempo de compilação. StaticArray evita GC; ArrayBuffer/TypedArray espelham as APIs JS. Tipagem estrita é o que permite compilar para Wasm eficiente.
// Distinct numeric types (NOT just 'number')
let a: i32 = 42;
let b: i64 = 9007199254740993n;
let f: f64 = 3.14;
let u: u32 = 100;
// Bool, string, arrays
let flag: bool = true;
let s: string = "hi";
let arr: i32[] = [1, 2, 3];
// Static arrays (no GC overhead)
let sa: StaticArray<i32> = [1, 2, 3];
// TypedArray-like
let buf: ArrayBuffer = new ArrayBuffer(8);Memória e Strings
AssemblyScript tem um GC pequeno para objetos gerenciados (Array, Map, String). Use __retain/__release para controlar os tempos de vida ao cruzar para o JS. O @assemblyscript/loader fornece __getString, __newString, __getArray, etc., para atravessar a fronteira.
// Strings are UTF-16 in AssemblyScript memory
export function greet(name: string): string {
return "Hello, " + name + "!";
}
// Manual memory management for buffers
export function process(len: i32): i32 {
let buf = new ArrayBuffer(len);
// ...fill buf...
let result = __retain(buf); // prevent GC
return result;
}
// In JS, use the loader's __getString/__newString:
const ptr = module.exports.greet("World");
console.log(module.exports.__getString(ptr));Exports e Pontos de Entrada
Funções e classes marcadas com export viram exportações Wasm. Classes mapeiam para objetos compatíveis com JS via o loader. _start é o ponto de entrada convencional (como o main do C). A stdlib do AssemblyScript espelha Math, Array, Map do JS — tornando a curva de migração suave.
// assembly/index.ts
export function fib(n: i32): i32 {
if (n < 2) return n;
return fib(n - 1) + fib(n - 2);
}
export class Vector {
constructor(public x: f32, public y: f32) {}
magnitude(): f32 {
return Math.sqrt(this.x * this.x + this.y * this.y);
}
}
// Module start function (runs at instantiation)
export function _start(): void {
// initialization code
}Compilação e Otimizações
asc é o compilador do AssemblyScript. --optimize (-O) roda o wasm-opt do Binaryen. --runtime controla o GC: 'full' (padrão), 'half' (menor), 'none' (manual). --importMemory permite compartilhar memória entre módulos. Source maps habilitam depuração no fonte .ts original.
# Build debug vs release
npm run asbuild # both debug and release
# or:
asc assembly/index.ts --outFile release.wasm --optimize
# Common flags
asc index.ts -o release.wasm \
--optimize \
--noAssert \
--runtime half # smaller GC runtime
--importMemory # use imported memory
--sourceMap # emit source map
# Optimize for size:
asc index.ts -o tiny.wasm --optimize --runtime none \
--conformance --noDebugWASI (WebAssembly System Interface)
O que é WASI
WASI é uma interface de sistema portátil e baseada em capacidades para Wasm fora do navegador. Diferente da web, em que o Wasm chama o JS, o WASI dá ao Wasm acesso direto (sanduichado) a arquivos, rede e ambiente. Segurança baseada em capacidades significa que o programa só pode tocar em recursos explicitamente pré-abertos para ele.
// WASI = WebAssembly System Interface
// A standardized API for Wasm to access OS capabilities:
// - filesystem (files, directories)
// - network sockets (preview2)
// - environment variables, args
// - clocks, random numbers
// - process exit
// Capability-based security: a Wasm program can
// ONLY access resources it was explicitly granted.
// Targets:
// wasm32-wasi (preview1)
// wasm32-wasip1 (preview1, new name)
// wasm32-wasip2 (preview2, component model)
// Runtimes: wasmtime, wasmer, WasmEdge, browser_wasi_shimRuntime wasmtime
wasmtime é o runtime WASI de referência da Bytecode Alliance. --dir pré-abre um diretório do host (concedendo acesso a arquivos). --env passa variáveis de ambiente. --net habilita rede no preview2. Sem concessões explícitas, o programa Wasm não vê nada — é a segurança por capacidades em ação.
# Install wasmtime (the reference WASI runtime)
# macOS: brew install wasmtime
# Linux: curl https://wasmtime.dev/install.sh -sSf | bash
# Windows: scoop install wasmtime
# Run a WASI module
wasmtime hello.wasm
# Pass arguments
wasmtime hello.wasm arg1 arg2
# Preopen a directory (grant filesystem access)
wasmtime --dir=. app.wasm
# Set environment variables
wasmtime --env FOO=bar app.wasm
# Allow network (preview2)
wasmtime --net allow app.wasmRodando Wasm com WASI (Exemplo em C)
Programas escritos para WASI parecem programas C comuns usando libc. Compile com clang --target=wasm32-wasi e um sysroot WASI (baixe o release do wasi-sdk). O mesmo .wasm roda em wasmtime, wasmer, WasmEdge e outros hosts WASI sem recompilação — portabilidade de verdade.
// wasi_hello.c
#include <stdio.h>
#include <unistd.h>
int main(int argc, char *argv[]) {
printf("Hello from WASI!\n");
printf("argc = %d\n", argc);
for (int i = 0; i < argc; i++) printf(" argv[%d] = %s\n", i, argv[i]);
return 0;
}
# Compile with the WASI SDK
clang --target=wasm32-wasi \
--sysroot=/path/to/wasi-sysroot \
-o hello.wasm wasi_hello.c
# Run
wasmtime hello.wasm foo bar
# Hello from WASI!
# argc = 3
# argv[0] = hello.wasm
# argv[1] = foo
# argv[2] = barAcesso ao Sistema de Arquivos WASI
WASI expõe uma API de sistema de arquivos tipo POSIX (open, read, write, close). Arquivos fora dos diretórios pré-abertos são invisíveis. Use --dir=caminho:apelido para conceder acesso e renomear. O WASI preview2 introduz interfaces de component model (wasi filesystem, wasi sockets) para APIs mais ricas.
// wasi_fs.c — read a file passed via --dir
#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
int main() {
int fd = open("input.txt", O_RDONLY);
if (fd < 0) { perror("open"); return 1; }
char buf[256];
ssize_t n = read(fd, buf, sizeof(buf) - 1);
if (n > 0) { buf[n] = '\0'; printf("%s", buf); }
close(fd);
return 0;
}
# Grant access, then run:
# wasmtime --dir=. wasi_fs.wasmAmbiente e Argumentos WASI
WASI fornece args e variáveis de ambiente via interfaces C padrão (argv, environ, getenv). O host controla o que é visível — --env concede variáveis específicas. Isso torna programas Wasm configuráveis sem mudanças de código, e limita o vazamento de segredos do host.
// wasi_env.c
#include <stdio.h>
#include <stdlib.h>
extern char **environ;
int main(int argc, char *argv[]) {
printf("Args:\n");
for (int i = 0; i < argc; i++) printf(" %s\n", argv[i]);
printf("Env:\n");
for (char **e = environ; *e; e++) printf(" %s\n", *e);
const char *home = getenv("HOME");
printf("HOME=%s\n", home ? home : "(unset)");
return 0;
}
# Run with env vars:
# wasmtime --env HOME=/tmp --env FOO=bar wasi_env.wasm a b cSockets WASI (Preview)
Sockets WASI fazem parte do preview2 (component model). wasi:sockets/tcp e wasi:sockets/udp fornecem rede; wasi:http oferece um cliente HTTP de nível mais alto. As APIs estão se estabilizando — prefira wasi:http hoje pela portabilidade. Runtimes como wasmtime e WasmEdge implementam essas interfaces.
// WASI preview2 adds TCP/UDP sockets.
// In Rust (using wasi crate):
use wasi::sockets::network::{IpAddress, IpSocketAddress};
// Component-model based sockets:
// - wasi:sockets/tcp
// - wasi:sockets/udp
// - wasi:sockets/ip-name-lookup
# Compile a Rust program for preview2:
cargo build --target wasm32-wasip2 --release
# Run with network access:
wasmtime --net allow target/wasm32-wasip2/release/myapp.wasm
// Note: socket APIs are still stabilizing.
// Use HTTP via wasi:http/types for stability.Depuração
wasm-objdump
wasm-objdump (do WABT) imprime a estrutura de um módulo: tipos, imports, exports, assinaturas de funções, desmontagem do código e tamanhos das seções. -x dá um resumo de alto nível; -d desmonta os corpos das funções em instruções tipo WAT. Essencial para entender o que um módulo realmente contém.
# Inspect a .wasm file's structure
wasm-objdump -x module.wasm # everything
wasm-objdump -d module.wasm # disassemble functions
wasm-objdump -s module.wasm # raw section contents
wasm-objdump -j Import -x m.wasm # only the Import section
# Sample -x output:
# Section Type (1) at 0x0008:
# type[0] (i32, i32) -> i32
# Section Function (3) at 0x0015:
# func[0] type=0wasm2wat para Inspeção
wasm2wat converte um .wasm binário de volta em WAT legível. Inestimável para entender módulos de terceiros, depurar comportamentos inesperados e fazer engenharia reversa. A ida e volta (wasm2wat → editar → wat2wasm) preserva o comportamento, tornando o WAT um verdadeiro formato de fonte.
# Disassemble binary to readable text
wasm2wat module.wasm -o module.wat
# View in your editor
cat module.wat
# Round-trip: edit .wat, recompile
wat2wasm module.wat -o module.wasm
# Common inspection: find exports
grep "(export" module.wat
# Find imports
grep "(import" module.watDevTools dos Navegadores
Cada um dos navegadores principais podem depurar Wasm nas DevTools: ver o WAT desmontado, definir breakpoints, inspecionar locais e a pilha de chamadas. Com source maps (Rust, AssemblyScript, Emscripten -g), as DevTools mapeiam de volta ao fonte original. Informação de depuração DWARF habilita depuração mais rica para C/C++/Rust.
// Chrome/Edge/Firefox DevTools support Wasm debugging:
// 1. Sources tab -> file tree shows .wasm entries
// 2. Click a .wasm to view disassembled WAT
// 3. Set breakpoints on function entries
// 4. Inspect the call stack and locals
// With source maps (Rust/AS), DevTools shows the
// ORIGINAL source (.rs / .ts) instead of WAT.
// Enable in chrome://flags:
// "WebAssembly debugging: Support DWARF"
// Console logging from Wasm:
// Import a JS log function and call it from WAT.
// Rust: wasm_logger / console_log crate.
// AS: console.log via env import.Source Maps
Source maps ligam instruções Wasm de volta à linguagem de origem. Rust os emite via wasm-pack; AssemblyScript via --sourceMap; Emscripten via -g4. O comentário sourceMappingURL no .wasm (seção customizada) diz às DevTools onde achar o .map. Sem ele, você depura WAT cru.
# Rust: source maps come automatically with wasm-pack
wasm-pack build --target web --dev
# AssemblyScript: emit source maps
asc index.ts -o release.wasm --sourceMap \
--sourceMap include 'src/**/*.ts'
# Emscripten: include debug info and source map
emcc app.c -g4 -O0 -o app.js \
--source-map-base http://localhost:8000/
# The .map file points DevTools back to the
# original .rs / .ts / .c source files.
# Validate a source map exists:
wasm-objdump -x app.wasm | grep sourceMappingURLErros e Traps Comuns
Erros recorrentes de Wasm: imports ausentes (nomes/tipos que não correspondem), traps (unreachable, memória fora dos limites, overflow de inteiro na divisão por zero), ArrayBuffers desanexados (após grow) e problemas de fronteira com i64. Envolva chamadas arriscadas em try/catch e valide imports/ponteiros de antemão para revelar problemas cedo.
// 1. LinkError: "import not found"
// Cause: import object missing a name.
const imports = { env: { log: console.log } };
// Must match (import "env" "log" ...) exactly.
// 2. RuntimeError: "unreachable"
// Cause: Wasm executed unreachable / panic / assert.
// 3. RuntimeError: "out of bounds memory access"
// Cause: load/store at an invalid address.
// Fix: check ptr/len before access; grow memory.
// 4. CompileError: "section size mismatch"
// Cause: corrupted or truncated .wasm file.
// 5. TypeError: "i64 not supported"
// Cause: i64 returns without BigInt integration.
// Fix: use BigInt, or return two i32 values.
// 6. "detached ArrayBuffer"
// Cause: used a TypedArray view after memory.grow.
// Fix: re-create views after grow.Otimização de Desempenho
Inlining e Flags -O
-O3 habilita inlining agressivo e otimizações de loop. wasm-opt (Binaryen) roda passadas adicionais no nível do Wasm (inlining, código morto, dobra de constantes) — sempre rode em produção. -Os/-Oz trocam um pouco de velocidade por downloads menores. -flto habilita otimização do programa inteiro.
# Compilation optimization levels
emcc app.c -O0 -o app.wasm # no optimization (debug)
emcc app.c -O1 -o app.wasm # basic
emcc app.c -O2 -o app.wasm # standard
emcc app.c -O3 -o app.wasm # aggressive (inlining)
emcc app.c -Os -o app.wasm # optimize for size
emcc app.c -Oz -o app.wasm # max size reduction
# Post-optimize with Binaryen
wasm-opt -O3 app.wasm -o app.opt.wasm
wasm-opt -Os app.wasm -o app.small.wasm
# LTO across translation units (C/C++)
emcc app.c -flto -O3 -o app.wasmLayout de Memória e Padrões de Acesso
A memória linear do Wasm é só um ArrayBuffer — o comportamento de cache da CPU se aplica. Padrões de acesso contíguos (row-major para dados row-major) são drasticamente mais rápidos que acesso com passos. Mantenha alinhamento natural (4 bytes para i32) para que loads/stores sejam instruções únicas.
// Cache-friendly access: linear, contiguous iteration
// GOOD: row-major traversal of a 2D array
for (i32 row = 0; row < rows; row++) {
for (i32 col = 0; col < cols; col++) {
sum += data[row * cols + col];
}
}
// BAD: column-major traversal (cache misses)
for (i32 col = 0; col < cols; col++) {
for (i32 row = 0; row < rows; row++) {
sum += data[row * cols + col];
}
}
// Prefer aligned access (4-byte for i32, 8 for i64).
// Allocators should respect natural alignment.Minimizando Cruzamentos da Fronteira JS
Toda chamada JS→Wasm tem custo (marshaling de argumentos, montagem da pilha). Para loops apertados, mova o loop PARA DENTRO do Wasm e chame-o uma vez com um buffer. Esta é a maior dica de desempenho do Wasm — operações em bloco superam chamadas por elemento em ordens de magnitude.
// BAD: call Wasm per element (boundary overhead)
for (let i = 0; i < arr.length; i++) {
result[i] = exports.process(arr[i]);
}
// GOOD: batch — one call for the whole array
const ptr = exports.alloc(arr.length * 4);
new Float32Array(memory.buffer, ptr, arr.length).set(arr);
exports.processBatch(ptr, arr.length); // single call
const out = Array.from(new Float32Array(memory.buffer, ptr, arr.length));
exports.free(ptr, arr.length * 4);
// Each crossing costs ~tens of nanoseconds.
// Batch loops to amortize the overhead.SIMD (Instrução Única, Múltiplos Dados)
SIMD (v128) processa 4 floats ou 4 int32 por instrução — acelerações de 4x para matemática de imagem/áudio/matrizes. Emscripten habilita com -msimd128; Rust usa intrinsics std::arch::wasm32. Auto-vetorização ajuda, mas intrinsics explícitos dão ganhos previsíveis. Amplamente suportado nos navegadores.
// C/C++ with Emscripten auto-vectorization
#include <emscripten/simd.h>
void addArrays(float *a, float *b, float *out, int n) {
for (int i = 0; i < n; i += 4) {
v128_t va = wasm_v128_load(a + i);
v128_t vb = wasm_v128_load(b + i);
wasm_v128_store(out + i, wasm_f32x4_add(va, vb));
}
}
# Compile with SIMD enabled
emcc simd.c -O3 -msimd128 -o simd.wasm
// Rust: use std::arch::wasm32 intrinsics
use std::arch::wasm32::*;
unsafe { let v = f32x4_splat(1.0); }Threads e SharedArrayBuffer
Threads do Wasm compartilham uma Memory entre Web Workers, usando atômicas para sincronização. Exige headers COOP/COEP (isolamento cross-origin). O -pthread do Emscripten emula pthreads; o std::thread do Rust funciona em wasm32-wasi-threads. Ótimo para trabalho paralelo ligado à CPU — processamento de imagem, codecs, inferência de ML.
// Enable threads in Emscripten
# emcc app.c -O3 -pthread -s PTHREAD_POOL_SIZE=4 -o app.js
// Browser requires cross-origin isolation:
// /_headers (Cloudflare/Netlify)
// Cross-Origin-Opener-Policy: same-origin
// Cross-Origin-Embedder-Policy: require-corp
// Spawn workers sharing Wasm memory:
const memory = new WebAssembly.Memory({
initial: 10, maximum: 100, shared: true
});
// Each Worker instantiates the module with this memory
// and uses Atomics for synchronization.Profiling e Benchmarks
Faca profiling com performance.now() e a aba Performance das DevTools — o Wasm aparece nos flame charts como o JS. Aqueça antes de medir (o custo de compilação é único). Compare com JS otimizado — o V8 moderno é rápido; o Wasm vence em desempenho previsível, kernels numéricos e cargas grandes, não em micro-tarefas.
// Use performance.now() for high-res timing
const t0 = performance.now();
exports.heavyWork(ptr, len);
const t1 = performance.now();
console.log(`Wasm: ${(t1 - t0).toFixed(2)}ms`);
// Compare against JS equivalent
const t2 = performance.now();
jsEquivalent(data);
console.log(`JS: ${(performance.now() - t2).toFixed(2)}ms`);
// Chrome DevTools Performance tab: profile Wasm
// like JS — flame charts show function time.
// Avoid microbenchmarks pitfalls:
// - warm up first (JIT compilation)
// - run many iterations
// - compare against OPTIMIZED JS, not naive JSWasm vs JavaScript
Comparação de Desempenho
Wasm brilha em trabalho numérico pesado (processamento de imagem, codecs, cripto, ML) — tipicamente 2-10x mais rápido que JS. Para DOM, JSON ou trabalho com muitas strings, o JS costuma ser mais rápido porque o trabalho já está em código nativo (JSON.parse do V8, DOM do navegador). Faça profiling para decidir — nunca presuma que Wasm é sempre mais rápido.
// Wasm vs JS — typical scenarios:
//
// Image processing (8MB):
// JS: 120 ms
// Wasm (-O3): 35 ms ~3.4x faster
//
// SHA-256 (1MB):
// JS: 45 ms
// Wasm: 8 ms ~5.6x faster
//
// DOM manipulation:
// JS: 5 ms
// Wasm: 20 ms SLOWER (DOM is JS-native)
//
// JSON parse:
// JS: 3 ms
// Wasm: 15 ms SLOWER (JSON.parse is C++ in V8)
//
// Rule of thumb: Wasm wins on compute-heavy numeric
// workloads; JS wins on DOM/JSON/string-heavy tasks.Casos de Uso do Wasm
Wasm é excelente em: portar codebases C/C++/Rust existentes (Figma, Photoshop web), kernels numéricos ligados à computação (imagem/ML/cripto) e plugins sanduichados. Vitórias reais incluem Figma (renderer), Photoshop (port completo do app) e Google Meet (desfoque de fundo). Para apps puramente de DOM, JS costuma ser a escolha certa.
// Strong Wasm use cases:
// - Image/video/audio processing (FFmpeg, OpenCV)
// - Games & 3D engines (Unity, Unreal)
// - Cryptography (hashing, encryption, ZK proofs)
// - Machine learning inference (ONNX, TFLite)
// - Codecs (AV1, VP9, MP3)
// - Emulators (DOSBox, retro consoles)
// - Heavy math (physics simulations, linear algebra)
// - Reusing C/C++/Rust libraries (FFI alternative)
// - Sandboxed plugins in editors (Figma, Photoshop)
// Figma: rendering engine in Wasm
// Photoshop: web port of full desktop app
// Google Meet: video background blurQuando Usar JS
JS segue sendo a escolha certa para UI, DOM, APIs de navegador e a maior parte da lógica de apps web — o V8 é fortemente otimizado. Recorra ao Wasm quando o profiling revelar um hotspot que o JS não consegue eliminar, ou ao portar uma codebase nativa existente. Uma abordagem híbrida (UI em JS + hotspots em Wasm) costuma ser ideal.
// JS is better when:
// - DOM manipulation dominates
// - Working with browser APIs (fetch, IndexedDB, WebRTC)
// - Heavy string/JSON processing
// - Small utilities and glue code
// - Rapid prototyping (no compile step)
// - Team lacks C/Rust expertise
// - Module size matters more than runtime speed
// JS engines (V8, SpiderMonkey, JSC) are highly
// optimized. For most web apps, JS is fast enough
// AND simpler to ship and maintain.
// Hybrid: keep UI in JS, offload hotspots to Wasm.Carregamento e Custo de Inicialização
Wasm tem um custo de inicialização fixo (download + compilação + instanciação) que o JS evita. Mitigue com compilação em streaming, cache de módulos compilados via Cache API e lazy-loading de Wasm não crítico. Depois do aquecimento, chamadas de função Wasm são tão rápidas quanto JS — o custo é adiantado, pago de volta por execução mais rápida.
// Wasm has upfront costs JS doesn't:
// 1. Download the .wasm binary
// 2. Compile to machine code (~10-50 ms for small modules)
// 3. Instantiate (initialize memory, run start function)
// Mitigations:
// - Cache compiled modules (WebAssembly.compileStreaming + Cache API)
// - Stream compilation (instantiateStreaming)
// - Lazy-load non-critical Wasm on demand
// - Use Web Workers to compile off the main thread
// Streaming compile of a 1MB module:
// ~30 ms download + ~10 ms compile (parallel)
// Cached: ~5 ms (re-instantiate from cached module)Custo de Interop e Overhead da Fronteira
Chamadas JS↔Wasm são baratas, mas não gratuitas (~10-100ns cada, mais para strings). Para eventos de alta frequência, agrupe no JS e chame o Wasm uma vez com um buffer. Evite passar objetos JS por chamada — use externref ou copie bytes para a memória. A fronteira é rápida para números, lenta para dados serializados.
// Each JS<->Wasm call costs ~10-100 ns:
// - Marshal arguments (i32/f64 fast; strings/objects slow)
// - Stack frame setup
// - Inlined trampoline in the engine
// Implications:
// - Don't call Wasm 1M times for tiny work — batch!
// - Don't pass large objects per-call — copy once, share memory
// - For DOM events, keep handlers in JS, call Wasm with batched data
// Pseudocode: batched event handling
let pendingEvents = [];
button.addEventListener('click', e => {
pendingEvents.push(...);
if (pendingEvents.length >= 100) {
exports.processBatch(ptr, pendingEvents.length);
pendingEvents = [];
}
});Modelo de Segurança
Modelo de Sandbox
A fundação de segurança do Wasm é o sandbox: um módulo não pode acessar memória do host, arquivos, rede ou dispositivos, a menos que o host forneça explicitamente funções para isso via imports. Isso torna o Wasm seguro para rodar código não confiável — ele só pode fazer o que seus imports permitem. Combinado com segurança de tipos, previne buffer overflows e RCE.
// Wasm executes in a sandboxed virtual machine:
// - No direct access to host memory (only its linear memory)
// - No syscalls (must go through imported functions)
// - No I/O unless the host provides it
// - Control flow is structured (no arbitrary jumps)
// - Type-checked at compile and run time
// All host access is EXPLICIT through imports.
// A module that didn't import "fs" cannot read files.
// Code:
// (module
// (import "env" "log" (func (param i32)))
// ;; the ONLY host capability this module has is log()
// )Same-Origin Policy e Fetch
Wasm não escapa do modelo de segurança do navegador — same-origin policy e CORS se aplicam a fetches de .wasm como a qualquer recurso. Wasm cross-origin exige headers CORS corretos e o tipo MIME application/wasm. Wasm também não pode burlar CSP, cookies ou qualquer outro mecanismo de segurança do navegador.
// Wasm modules obey the same-origin policy:
// - fetch('https://other-origin/x.wasm') needs CORS headers
// - The remote server must send:
// Access-Control-Allow-Origin: *
// - And the correct MIME: application/wasm
// Load cross-origin Wasm with streaming:
const { instance } = await WebAssembly.instantiateStreaming(
fetch('https://cdn.example.com/lib.wasm', {
mode: 'cors'
}),
imports
);
// Wasm cannot bypass CORS — it's subject to the
// browser's normal security model.Isolamento de Memória
A memória do Wasm é verificada por limites em runtime — qualquer acesso fora dos limites gera trap imediato em vez de corromper memória. Módulos não podem ler a memória uns dos outros, o heap JS ou endereços arbitrários do host. Ponteiros de função (call_indirect) são verificados por tipo, prevenindo falsificação de alvos de chamada. Isso elimina classes inteiras de vulnerabilidades C/C++.
// Each Wasm instance has its OWN linear memory.
// - Out-of-bounds access traps (RuntimeError)
// - One module's memory cannot read another's
// - JS writes via TypedArray views are bounds-checked
// Even shared memory (threads) requires explicit
// opt-in and is still bounded:
const mem = new WebAssembly.Memory({ initial: 1, maximum: 10 });
// Wasm code CANNOT:
// - Read JS heap
// - Read other instances' memory
// - Forge function pointers (call_indirect type-checks)
// - Read arbitrary host memory addresses
// All memory access is bounds-checked at runtime.Segurança Baseada em Capacidades
Wasm segue segurança baseada em capacidades: o objeto de import É a capacidade do módulo. Escolhendo cuidadosamente o que importar, você dá ao módulo privilégio mínimo. Um plugin que só importa log() não pode fazer mais nada. Esta é a base de sistemas de plugins seguros (Figma, Shopify functions, etc.).
// Capability security: a module can ONLY do what
// the host explicitly grants via imports.
// Strict imports = minimal privilege
const imports = {
env: {
log: msg => console.log('[wasm]', msg)
// NO file IO, NO network, NO timers
}
};
WebAssembly.instantiateStreaming(fetch('plugin.wasm'), imports);
// The plugin can ONLY call log(). It cannot:
// - Access the DOM
// - Make network requests
// - Read files
// - Spawn workers
// unless you import those capabilities.CSP e Trusted Types
Content Security Policy trata Wasm como eval — por padrão, CSP o bloqueia. Adicione 'wasm-unsafe-eval' ao script-src para permitir Wasm mantendo eval() bloqueado. É mais permissivo que unsafe-eval e recomendado para produção. A compatibilidade com Trusted Types exige embrulhar qualquer cola JS dinâmica numa policy.
// Content Security Policy applies to Wasm:
// - 'wasm-unsafe-eval' is required for instantiation
// - Without it, CSP blocks WebAssembly.compile
// HTTP header:
// Content-Security-Policy:
// default-src 'self';
// script-src 'self' 'wasm-unsafe-eval';
// Wasm output (e.g., Emscripten) often uses eval-like
// patterns for instantiation — CSP 'wasm-unsafe-eval'
// specifically allows Wasm while still blocking eval().
// Trusted Types: Wasm glue code must produce
// trusted scripts; use policy.createScript() for
// any dynamically generated JS that loads Wasm.Cadeia de Ferramentas
WABT (wat2wasm, wasm2wat)
WABT é o toolkit canônico para trabalhar com os formatos de texto e binário do Wasm. wat2wasm/wasm2wat fazem a ida e volta; wasm-objdump inspeciona a estrutura; wasm-interp roda módulos num interpretador de referência. wasm-decompile produz uma forma legível tipo C. Essencial para autoria manual, depuração e ensino.
# WABT = WebAssembly Binary Toolkit
# Install:
# macOS: brew install wabt
# Ubuntu: apt install wabt
# Windows: scoop install wabt
# Tools included:
wat2wasm hello.wat -o hello.wasm # text -> binary
wasm2wat hello.wasm -o hello.wat # binary -> text
wasm-validate hello.wasm # validate
wasm-objdump -x hello.wasm # inspect structure
wasm-interp hello.wasm # interpret (run)
wasm-decompile hello.wasm -o hello.dly # decompile to C-like
# Online: https://webassembly.github.io/wabt/demo/Emscripten SDK
Emscripten é a toolchain Wasm mais madura — compila C/C++, Fortran e outras linguagens LLVM. emcc/em++ embrulham o Clang; emcmake/emconfigure permitem build de projetos CMake/Autotools existentes sem modificação. Também fornece ports de libc, SDL, OpenGL (via WebGL) e pthreads para compatibilidade.
# Emscripten: compile C/C++/LLVM languages to Wasm
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk && ./emsdk install latest && ./emsdk activate latest
source ./emsdk_env.sh
# Key tools:
emcc # C/C++ compiler (gcc/clang-like)
em++ # C++ compiler
emcmake # wrapper for cmake
emconfigure # wrapper for ./configure
emranlib # archive tool
emar # archiver
# Common output:
emcc app.c -O3 -o app.js # JS glue + .wasm
emcc app.c -o app.html # runnable HTML demowasm-pack (Rust)
wasm-pack é a ferramenta oficial Rust→Wasm: faz build, roda wasm-bindgen, gera tipos TypeScript e empacota para npm. --target escolhe o formato de módulo JS. wasm-pack test roda testes Rust em navegadores reais via webdriver. Use o wasm-pack-template para um scaffold de projeto pronto.
# wasm-pack: build, test, publish Rust Wasm packages
cargo install wasm-pack
# Build for various targets
wasm-pack build --target web # modern browsers
wasm-pack build --target bundler # webpack/vite
wasm-pack build --target nodejs # Node.js
# Test in a headless browser
wasm-pack test --headless --chrome
# Publish to npm
wasm-pack publish
# Generate a template project
cargo generate --git https://github.com/rustwasm/wasm-pack-templateBinaryen (wasm-opt)
Binaryen é o toolkit de otimização que Emscripten e wasm-pack usam internamente. wasm-opt roda passadas no nível do Wasm (inlining, eliminação de código morto, dobra de constantes) — sempre rode em builds de produção. -O3 para velocidade, -Oz para tamanho mínimo. wasm-metadce remove exports não usados entre módulos.
# Binaryen: Wasm optimization toolkit
# Often installed via Emscripten or standalone:
npm install -g binaryen
# wasm-opt: optimize .wasm files
wasm-opt -O3 input.wasm -o output.wasm # speed
wasm-opt -Os input.wasm -o output.wasm # size
wasm-opt -Oz input.wasm -o output.wasm # min size
# Other tools:
wasm-as input.wat -o output.wasm # assemble
wasm-dis input.wasm -o output.wat # disassemble
wasm-merge a.wasm b.wasm -o merged.wasm # link
wasm-shell input.wat # interpreter
wasm-metadce input.wasm -o output.wasm # aggressive dead-codewasm-tools (Bytecode Alliance)
wasm-tools é um toolkit moderno baseado em Rust, da Bytecode Alliance. Ele analisa/imprime/valida, mas seu destaque é o suporte a component model (component new/embed/describe). É mais estrito e rápido que o WABT em muitas operações e é a ferramenta recomendada para trabalho com component model.
# wasm-tools: modern Rust-based Wasm toolkit
cargo install wasm-tools
# Subcommands:
wasm-tools parse input.wat -o output.wasm # text -> binary
wasm-tools print input.wasm -o output.wat # binary -> text
wasm-tools validate input.wasm # validate
wasm-tools component new input.wasm -o c.wasm # wrap as component
wasm-tools strip input.wasm -o stripped.wasm # remove debug info
wasm-tools objdump input.wasm # inspect
wasm-tools smith # generate random modules (fuzzing)
# Component model support is a key feature.
# Stronger WAT parsing than WABT in edge cases.Runtimes (wasmtime, wasmer, WasmEdge)
Três runtimes independentes principais: wasmtime (referência da Bytecode Alliance, melhor suporte a component model), wasmer (múltiplos backends, incluindo LLVM para pico de desempenho, bindings JS), WasmEdge (CNCF, otimizado para cloud-native e inferência de IA). Cada um implementa WASI, então o mesmo .wasm roda entre eles. Escolha pelo encaixe no ecossistema.
# wasmtime — Bytecode Alliance reference runtime
curl https://wasmtime.dev/install.sh -sSf | bash
wasmtime app.wasm
# wasmer — cross-platform, multiple backends
curl https://get.wasmer.io -sSf | sh
wasmer run app.wasm
# WasmEdge — CNCF, optimized for cloud/edge
curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash
wasmedge app.wasm
# Comparison:
# wasmtime: reference, WASI preview1+2, components
# wasmer: multiple backends (Cranelift, LLVM), JS API
# WasmEdge: AI/ML extensions, Kubernetes-friendly
// All three run WASI modules portably.Componentes e Boas Práticas
Visão Geral de Componentes Wasm
O Component Model é a evolução do Wasm: um formato de módulo que permite que componentes se comuniquem com tipos ricos (strings, records, listas) sem marshaling manual pela memória linear. Componentes se compõem como bibliotecas entre linguagens (componente Rust + componente JS). Suportado por wasmtime, WasmEdge e o ecossistema mais amplo da Bytecode Alliance.
// Component Model: a higher-level module format
// that lets Wasm modules talk to each other and hosts
// using rich types (strings, records, variants),
// not just (i32, f64).
// Core Wasm module: exports raw functions over memory.
// Component: wraps a core module, exposes typed
// interfaces described in WIT (Wasm Interface Type).
// Build flow:
// 1. Write WIT interface
// 2. Generate bindings for your language (Rust, C, JS)
// 3. Implement, compile to core .wasm
// 4. Wrap into a component with wasm-tools
// Tooling:
wasm-tools component new app.wasm -o app.wasm
// Run with wasmtime:
wasmtime app.wasm # uses component interfacesWIT (Wasm Interface Type)
WIT (Wasm Interface Type) é o IDL dos componentes — declare records, variants, enums, resources e funções. wit-bindgen gera bindings específicos por linguagem (Rust, C, JS, Python). A palavra-chave 'world' agrupa os imports e exports que um componente fornece/consume. Esta é a fundação de bibliotecas Wasm portáteis e agnósticas de linguagem.
// example.wit — describe a component's interface
package example:greeter;
interface api {
// A record type
record person {
name: string,
age: u32,
}
// A function taking/returning rich types
greet: func(p: person) -> string;
}
world greeter-world {
export api;
}
# Generate bindings:
# Rust: cargo component bindings
# JS: jco transpile
# C/C++: wit-bindgen c component.wit
# wit-bindgen is the binding generator
cargo install wit-bindgen-cliBoa Prática: Módulos Pequenos e Focados
Prefira vários módulos Wasm pequenos e focados a um monólito. Módulos menores baixam mais rápido, cacheiam melhor e podem ser carregados preguiçosamente (carregue o módulo de áudio só quando precisar). Compartilhe memória entre módulos via imports, ou use o component model para chamadas intermódulo com segurança de tipos. Rode wasm-opt -Oz em cada um.
// GOOD: One focused .wasm per concern
// - renderer.wasm (drawing)
// - audio.wasm (mixing)
// - physics.wasm (simulation)
// Loaded lazily as needed.
// BAD: One giant monolithic .wasm
// - app.wasm (1MB+, includes everything)
// Benefits of small modules:
// - Faster initial load (only what's needed)
// - Better caching (changed modules re-download)
// - Easier parallel development
// - Smaller attack surface per module
// Use wasm-opt -Oz to minimize each module.
// Share memory across modules via imports.Boa Prática: Tratamento de Erros
Traps do Wasm (divisão por zero, memória fora dos limites, unreachable) não podem ser capturados de dentro do Wasm — eles abortam a função. Projete funções exportadas para retornar códigos de erro ou tipos Result em vez de gerar trap. Capture WebAssembly.RuntimeError no lado JS como último recurso. O component model suporta variantes de erro tipadas nativamente.
// Wasm traps are unrecoverable — handle errors gracefully.
// BAD: let divide crash
(func (export "div") (param i32 i32) (result i32)
local.get 0 local.get 1 i32.div_s ;; traps on 0
)
// GOOD: return a sentinel or error code
(func (export "div") (param i32 i32) (result i32)
local.get 1
i32.eqz
if (result i32)
i32.const -1 ;; error sentinel
else
local.get 0
local.get 1
i32.div_s
end
)
// In Rust/AS: use Result<T, E> and export
// error variants via the component model.Boa Prática: Gestão de Memória
Trate a memória do Wasm como C: cada alloc precisa de um free correspondente. Exporte helpers alloc/free e envolva o uso de buffers no lado JS em try/finally. Recrie as views TypedArray após qualquer memory.grow (o ArrayBuffer se desanexa). Documente a posse: quem é responsável por liberar — quem chama ou quem é chamado? Vazamentos degradam o desempenho com o tempo.
// Export alloc/free and use them consistently.
// C/C++ (Emscripten): _malloc / _free
// Rust: wasm_bindgen's __alloc / __free
// AssemblyScript: __new / __retain / __release
// JS wrapper for safe buffer passing:
function withBuffer(size, fn) {
const ptr = exports.alloc(size);
try {
return fn(new Uint8Array(memory.buffer, ptr, size));
} finally {
exports.free(ptr, size);
}
}
// NEVER leak:
// - Re-create TypedArray views after memory.grow
// - Free buffers passed in from JS
// - For long-lived allocations, document ownershipBoa Prática: Testes e CI
Teste o Wasm em ambientes reais: wasm-pack test roda testes Rust em navegadores headless; AssemblyScript e Emscripten têm seus próprios runners. Adicione wasm-validate e verificações de tamanho ao CI. Use -s ASSERTIONS=1 (Emscripten) e builds de depuração para capturar problemas cedo. Lint com wat2wasm e sempre rode wasm-opt nos artefatos de release.
# Test Wasm just like any other code.
# Rust: wasm-pack test runs in a real browser
wasm-pack test --headless --chrome --firefox
# AssemblyScript: use the built-in test framework
npm run test
# C/C++ (Emscripten): use emcc with -s ASSERTIONS=1
# and write tests in C, run with node:
node tests.js
# Validate .wasm in CI:
wasm-validate module.wasm
# Check size budgets:
ls -la module.wasm # e.g., must be < 200KB
# Lint WAT with wat2wasm (catches syntax errors)
# Run wasm-opt -O3 to ensure optimization is applied
# GitHub Actions example:
# - uses: actions-rs/toolchain@v1
# - run: cargo install wasm-pack
# - run: wasm-pack test --headlessSnippets de WebAssembly relacionados
Copy-paste ready code for common tasks.
Module Instantiation
Compile and instantiate a .wasm module.
Linear Memory
Shared, growable byte buffer.
Tables
Function references for indirect calls.
Imports and Exports
Exchange functions, memory, and globals.
JS Interop
Pass strings through shared memory.
Text Format (WAT)
Human-readable WebAssembly.
Performance
Benchmark and parallelize WASM workloads.
Debugging
Inspect modules and handle traps.
Was this helpful?