Premiers pas
Charger du Wasm en JS
WebAssembly (Wasm) est un format binaire tournant à une vitesse quasi native dans les navigateurs. instantiateStreaming charge et compile un fichier .wasm. Les exports sont des fonctions appelables depuis 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);
});Module et instance WebAssembly
WebAssembly.Module est la représentation compilée et sans état — réutilisable en sécurité entre plusieurs instances. WebAssembly.Instance détient l'état d'exécution (mémoire, globales). Compiler une fois et instancier plusieurs fois est efficace pour lancer des workers parallèles.
// 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 globalsSupport navigateur et détection de fonctionnalités
WebAssembly 1.0 est support é par tous les navigateurs modernes. Les propositions plus récentes (SIMD, exceptions, threads, GC) exigent une détection de fonctionnalités. WebAssembly.validate vérifie si des octets forment un module valide sans compiler.
// 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 non streaming
instantiateStreaming compile le module pendant qu'il streame sur le réseau — démarrage plus rapide. Le serveur DOIT envoyer 'Content-Type: application/wasm'. Si vous utilisez un CDN ou un hébergeur statique sans cet en-tête, retombez sur le chemin 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/wasmNombre magique et en-tête Wasm
Le nombre magique du binaire Wasm est la chaîne ASCII '\0asm' suivie d'une version de 4 octets en little-endian. Cet en-tête permet de valider qu'un fichier est du Wasm avant compilation. Le format s'organise en sections (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 (exemple minimal)
Une app Wasm minimale : le module importe une fonction 'log' depuis JS et exporte 'greet' qui l'appelle. Le format WAT (WebAssembly Text) est la représentation lisible humaine, compilée en binaire avec wat2wasm. Les navigateurs n'exécutent que la forme binaire.
<!-- 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
)
)Format texte WAT
Module et s-expressions
WAT (format texte WebAssembly) est la représentation textuelle du Wasm. Tout s'enveloppe dans une s-expression (module ...). Les instructions s'écrivent en ordre basé pile : les opérandes poussés d'abord, puis l'opération les consomme.
;; 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))
)Commentaires en WAT
WAT supporte deux styles de commentaires : ';;' pour une ligne et '(; ... ;)' pour les blocs. Les commentaires de bloc peuvent s'imbriquer et s'étendre sur plusieurs lignes — utile pour désactiver des morceaux de code pendant le développement.
;; 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
)Syntaxe de définition de fonctions
Les fonctions se déclarent avec (func ...). Les paramètres utilisent (param $nom type) et les résultats (result type). Le '$nom' est optionnel — sans lui, fonctions et locales se référencent par index numérique. Les retours multi-valeurs exigent la proposition multi-value (largement supportée).
;; 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 et import inline
WAT supporte les annotations inline (export "nom") et (import "module" "champ") sur fonctions, mémoires, tables et globales — un raccourci des formes développées (export ...) / (import ...). Les deux compilent vers une sortie binaire identique.
;; 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))Segments de données
Les segments de données initialisent la mémoire linéaire à l'instanciation (actifs) ou paresseusement via memory.init (passifs). Les chaînes incluent des séquences d'échappement comme \00 pour le terminateur nul et \n pour le retour à la ligne. data.drop libère le stockage du segment après la copie.
;; 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)Conversion wat2wasm et wasm2wat
WABT (WebAssembly Binary Toolkit) fournit wat2wasm (texte→binaire), wasm2wat (binaire→texte), wasm-validate et wasm-objdump. Essentiels pour inspecter, déboguer et écrire à la main des modules Wasm. La forme .wat est pour les humains ; la forme .wasm est ce que les navigateurs exécutent.
# 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.wasmTypes de valeurs
Types de valeurs de base (i32/i64/f32/f64)
Wasm n'a que quatre types de valeurs de base : i32, i64, f32, f64. La signature des entiers se détermine par l'opération (ex. i32.div_s vs i32.div_u), pas par le type. Cela garde le système de types minimal et prévisible.
;; 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.Littéraux numériques en WAT
Les littéraux numériques en WAT supportent les formes décimale, hex (0x) et binaire (0b). Les flottants supportent la notation scientifique, l'infini (inf) et NaN. Les littéraux WAT sont non signés par défaut — les entiers négatifs s'encodent avec un '-' initial.
;; 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^53Conversions de types
Les conversions utilisent un schéma de nommage cohérent : extend (petit→grand), wrap (grand→petit), convert (entier↔flottant), reinterpret (cast au niveau bits), demote/promote (précision flottante). Les variantes signées utilisent _s, non signées _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_f32Type SIMD v128
Le type v128 packe 16 octets dans un unique registre SIMD. Les lanes s'adressent comme i32x4 (4×int32), f32x4 (4×float32), i16x8, i8x16, f64x2. Le SIMD accélère les charges image/audio/crypto en opérant sur plusieurs valeurs par instruction.
;; 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.addTypes de référence (funcref/externref)
La proposition de types de référence ajoute funcref (pointeur de fonction) et externref (référence hôte opaque). externref est puissant : il permet au Wasm de détenir des objets JS sans copie ni sérialisation. Combiné aux tables, cela permet des patterns de callbacks flexibles.
;; 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' });Fonctions
Définir et appeler des fonctions
Les fonctions sont l'unité de code fondamentale. call invoque une fonction par nom/index. Les arguments se poussent sur la pile avant l'appel ; les résultats restent sur la pile quand la fonction retourne. La pile doit correspondre à la déclaration (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
)
)Paramètres et variables locales
Les paramètres sont des locales immuables indexées à partir de 0. Les locales déclarées (local $nom type) s'initialisent à zéro et sont mutables. Utilisez local.get, local.set et local.tee (set + laisser sur la pile). Les locales sont le seul stockage mutable du Wasm hors mémoire/globales.
(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 stackValeurs de retour multiples
La proposition multi-value permet aux fonctions de retourner plusieurs valeurs (et d'en accepter zéro). Tous les grands moteurs la supportent depuis 2020. Cela supprime le besoin de paramètres de sortie via la mémoire et rend des idiomes comme swap/minmax naturels.
;; 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
)Récursion
Wasm supporte la récursion directe — une fonction peut s'appeler. Pas d'optimisation d'appel terminal dans le Wasm MVP (la proposition tail-call ajoute return_call). La récursion profonde risque le débordement de pile, donc préférez des boucles itératives en production.
(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 et appels nommés
Le (export "nom") inline sur une définition de fonction est un raccourci d'une déclaration (export ...) séparée. call_ref (proposition de types de référence) invoque une fonction via un funcref directement, permettant des valeurs de fonction de première classe sans lookup de table.
(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)
)
)Fonction start
Un module peut déclarer une fonction (start $func) qui s'exécute automatiquement à l'instanciation — utile pour l'initialisation. Elle ne prend aucun argument et ne retourne rien. Une seule fonction start par module.
(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.Mémoire
Déclarer la mémoire linéaire
La mémoire linéaire est une région contiguë façon ArrayBuffer, agrandie par pages de 64 Kio. (memory 1 10) déclare initial=1, max=10. La mémoire est la seule façon de passer des données en masse (chaînes, tableaux) entre Wasm et JS. Exportez-la pour y accéder depuis 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);
)Agrandir la mémoire
memory.grow ajoute des pages et retourne la taille précédente (en pages), ou -1 en cas d'échec. Crucial : agrandir détache l'ArrayBuffer sous-jacent — toutes les vues TypedArray existantes deviennent inutilisables. Recréez toujours les vues après tout appel 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!Opérations load et store
Les loads/stores ont des variantes par taille (8/16/32/64 bits) et extension de signe (_s/_u). offset=N ajoute une constante à l'opérande d'adresse ; align= est un indice (doit être ≤ taille). Toutes les adresses sont des offsets en octets dans la mémoire linéaire.
;; 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 byteTailles mémoire et alignement
L'alignement en Wasm est un indice de performance, pas une contrainte de justesse — l'accès non aligné marche toujours. La valeur 'align' ne doit pas dépasser la taille naturelle de l'opération. memory.size retourne le nombre courant de pages (64 Kio chacune).
;; 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
)Mémoire partagée et atomiques
La mémoire partagée (proposition threads) laisse plusieurs instances/Workers Wasm partager une mémoire pour le parallélisme. Les opérations atomiques (i32.atomic.load/store/rmw.add/cmpxchg) fournissent la synchronisation. Exige l'isolation cross-origin (en-têtes COOP/COEP) dans les navigateurs.
(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
)
)Lire des chaînes depuis la mémoire
Wasm n'a pas de type chaîne natif — les chaînes sont des séquences d'octets en mémoire linéaire, typiquement passées en paires (pointeur, longueur). TextEncoder/TextDecoder gèrent la conversion UTF-8. Assurez-vous toujours que la région mémoire est assez grande avant d'écrire.
// 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
}Tables
Déclarer des tables
Les tables sont des tableaux de références (typiquement funcref) utilisés pour les appels indirects et le dispatch dynamique. Contrairement à la mémoire (qui détient des octets), les tables détiennent des références opaques que Wasm ne peut pas forger. Les segments (elem ...) initialisent les slots de table à l'instanciation.
(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)
)Tables funcref et call_indirect
call_indirect dispatche un appel à travers une entrée de table par index. La déclaration (type ...) est obligatoire — Wasm vérifie à l'exécution que la signature de la fonction correspond (un désaccord piège). C'est le socle des vtables et du dispatch OO en 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 et set de table
table.grow ajoute des slots et retourne la taille précédente (ou -1). table.get/table.set lisent/écrivent les entrées par index. Agrandir une table permet l'enregistrement de callbacks à l'exécution. Taille initiale + bornes max pour prévenir l'allocation déchaînée.
(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
)Tables externref pour objets hôtes
Les tables externref stockent des références opaques vers des objets hôtes (JS) — Wasm peut les détenir et les transmettre mais ne peut pas inspecter leur contenu. Idéal pour l'enregistrement de callbacks, les tables de handles JS et le pontage d'API JS orientées objet vers le 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 });Pattern de dispatch dynamique
Le pattern de dispatch dynamique : stockez les opérations dans une table, puis call_indirect par index. Combiné à la vérification de type obligatoire, cela donne un polymorphisme sûr façon vtable. C'est ainsi que les enums Rust, les fonctions virtuelles C++ et les interpréteurs implémentent le dispatch.
(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)
)
)Globales
Déclarer des globales
Les globales sont des valeurs uniques au niveau du module, soit immuables (défaut) soit mutables (mut). Elles persistent entre les appels de fonctions et servent aux compteurs, flags de configuration et constantes. Les globales mutables sont le seul état mutable partagé hors mémoire/tables.
(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
)
)Globales mutables vs immuables
Sans 'mut', une globale est immuable et global.set est une erreur de compilation. L'initialiseur doit être une expression constante (ex. i32.const, ref.null, global.get d'une globale importée immuable). Choisissez l'immuable par défaut pour la sécurité.
(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
)
)Importer des globales
Les globales importées laissent l'hôte injecter des valeurs de configuration (ou des objets WebAssembly.Global) dans un module à l'instanciation. Les globales importées immuables peuvent initialiser d'autres globales. WebAssembly.Global est le wrapper visible côté JS des globales partagées mutables.
(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)
}
};Exporter et partager des globales
Les globales exportées sont accessibles depuis JS comme objets WebAssembly.Global avec une propriété .value (lisible et, si mutable, inscriptible). Partager un objet Global entre plusieurs instances de modules est une façon propre de coordonner l'état sans toucher à la mémoire.
(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 directlyCas d'usage des globales
Les globales conviennent à trois patterns : (1) constantes de configuration importées, (2) compteurs/état persistants partagés entre instances, (3) résultats de calculs mis en cache. Plus simples que la mémoire pour des valeurs uniques et visibles par plusieurs instances si partagées 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 et exports
Importer des fonctions
Les imports laissent le Wasm appeler des fonctions hôtes (JS). Chaque import s'identifie par un nom à deux niveaux (module, champ). L'objet d'import passé à instantiate doit correspondre à ces noms. Les imports sont la façon dont le Wasm atteint le monde extérieur — I/O, logging, planification.
(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() }
});Importer de la mémoire
Importer la mémoire laisse plusieurs modules Wasm (et JS) partager une région mémoire — le socle des « bibliothèques » Wasm. Un module alloue et écrit ; un autre lit. Cela compose les modules sans copier les données et est le précurseur du 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 memoryImporter globales et tables
Globales et tables peuvent aussi s'importer, permettant un état partagé et des tables de pointeurs de fonctions entre modules. WebAssembly.Table est le constructeur JS. Les globales importées mutables laissent l'hôte influencer dynamiquement le comportement du Wasm sans reconstruire le module.
(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
})
}
};Exporter fonctions, mémoire, tables
Tout ce qui se déclare dans un module peut s'exporter : fonctions, mémoire, tables, globales. Les exports deviennent des propriétés sur instance.exports. Les exports de mémoire donnent à JS une vue du tas linéaire ; les exports de globales exposent des objets WebAssembly.Global ; ceux de tables des références de fonctions.
(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 et exports inline
Les annotations inline (import "m" "f") et (export "nom") sont du sucre syntaxique — elles compilent vers le même binaire que les formes autonomes (import ...)/(export ...). Une définition unique peut porter un export inline, mais imports et exports se déclarent séparément pour les éléments importés.
(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.
)Bonnes pratiques de l'objet d'import
Structurez l'objet d'import pour matcher les noms (module, champ) du module. Validez les imports requis avant l'instanciation pour donner des erreurs claires. Enveloppez les fonctions hôtes de try/catch quand approprié — un throw non attrapé dans un import piège l'appelant 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}`);
}
}
}
}Flux de contrôle
block
block crée une portée étiquetée dont les branchements sortent (via br). Les branchements en Wasm sont structurés — ils ne peuvent sauter qu'à la fin d'un bloc/boucle/if englobant. Un bloc avec (result ...) laisse sa valeur sur la pile quand on branche vers lui ou qu'on le traverse.
;; 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 ressemble à block, mais br $boucle saute au SOMMET de la boucle (continuant l'itération) plutôt qu'à la fin. C'est l'opposé de block. Wasm n'a pas de mots-clés for/while — l'itération se bâtit depuis loop + un br_if conditionnel.
;; 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 consomme un i32 de la pile (non nul = vrai). La clause (result ...) fait que l'if produit une valeur quand les deux branches s'accordent sur le type. Un if sans else est autorisé ; la branche peut être vide. if est du sucre pour 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 et br_if
br $label saute à la FIN du bloc/if nommé (ou au SOMMET d'une boucle). br_if fait pareil conditionnellement. Les labels peuvent aussi être numériques (br 0 = le plus interne). Brancher avec une valeur la laisse sur la pile — la façon idiomatique de retourner tôt en Wasm.
;; 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 implémente un switch : il consomme un index i32 et saute vers l'un des labels listés, ou le dernier (défaut) si hors plage. Imbriquez les blocs du plus externe au plus interne pour que chaque cas puisse retourner sa valeur. La façon la plus efficace de dispatcher sur un 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 et unreachable
return quitte immédiatement la fonction avec la valeur sur la pile. unreachable piège toujours (lève une exception d'exécution) — pour marquer des chemins de code qui ne devraient jamais s'exécuter, semblable à assert(false). Les deux sont des échapatoires de flux de contrôle au-delà du modèle de blocs structurés.
(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)Interopérabilité JS
Passer des nombres
i32/f32/f64 mappent directement aux nombres JS. i64 mappe au BigInt JS (les grands entiers dépassent la plage sûre de Number). Utilisez toujours BigInt pour les paramètres/retours i64. La conversion est zero-copy à la frontière mais la franchir fréquemment a un coût — batchez les opérations dans le 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);Passer des chaînes
Les chaînes traversent la frontière comme séquences d'octets UTF-8 : JS les encode dans la mémoire Wasm, puis passe (pointeur, longueur). Souvent le Wasm exporte des helpers alloc/free, ou on packe les deux dans un i64 unique (32 bas = ptr, 32 hauts = len). Libérez ou réutilisez toujours le buffer pour éviter les fuites.
// 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);
}Passer des tableaux et données en masse
Pour des données numériques en masse, voyez la mémoire Wasm comme un TypedArray du bon type (Float32Array, Int32Array, etc.) et utilisez .set() pour copier. C'est le chemin le plus rapide — façon memcpy. Rappelez-vous l'alignement des pointeurs (4 octets pour i32/f32, 8 pour i64/f64) et libérez toujours la mémoire.
// 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;
}Gestion mémoire à travers la frontière
La mémoire Wasm se gère manuellement — pas de garbage collector. Si le Wasm exporte alloc/free (ou vous utilisez un helper façon malloc), enveloppez les accès JS de try/finally pour garantir la libération. Surveillez les vues ArrayBuffer détachées par memory.grow — recréez les vues après croissance.
// 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 est un wrapper JS autour d'une valeur globale Wasm. En créer un et le passer à plusieurs instances de modules partage l'état mutable proprement sans toucher à la mémoire. La propriété .value lit/écrit l'i32/i64/f32/f64 sous-jacent (ou v128/externref).
// 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 et erreurs
WebAssembly.Table stocke des références de fonctions accessibles à la fois depuis JS et Wasm — utile pour les registres de callbacks et tables de dispatch. Les pièges Wasm (division par zéro, mémoire hors bornes, débordement de pile) remontent comme WebAssembly.RuntimeError en JS — enveloppez les appels risqués de 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);
}Compiler du C/C++ vers Wasm
Mise en place Emscripten
Emscripten est la toolchain canonique pour compiler du C/C++ (et langages LLVM) vers Wasm. Elle regroupe Clang, Binaryen et une libc/libstdc++ portée au navigateur. Activez l'environnement dans chaque session shell avec emsdk_env. Les mises à jour sont fréquentes — réinstallez périodiquement.
# 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 en C
Le C standard marche tel quel — printf écrit dans un terminal virtuel que Emscripten fournit. main() s'invoque automatiquement au chargement du module. Les fonctions appelées depuis JS devraient s'exporter avec EMSCRIPTEN_KEEPALIVE ou le 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;
}Compiler avec emcc
emcc pilote la compilation. -O3 active les optimisations agressives (inlining, élimination de code mort). EXPORTED_FUNCTIONS liste les symboles C (préfixés _) à exposer. MODULARIZE enveloppe le loader en factory pour l'usage dans les bundlers. Formats de sortie : .wasm seul, glue .js + .wasm, ou démo .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 webSortie HTML Emscripten et Module
L'objet 'Module' d'Emscripten est le runtime côté JS : il expose les fonctions C préfixées _, gère la mémoire (_malloc/_free) et fournit des hooks (print, onRuntimeInitialized). MODULARIZE en fait une factory retournant une Promise, adaptée aux bundlers et au chargement async.
// 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
}
});Appeler du JS depuis le C (EM_JS / EM_ASM)
EM_JS définit une fonction JS inline que le C peut appeler directement — efficace et synchrone. EM_ASM embarque un extrait JS inline. Utilisez $0, $1, ... pour les arguments. Ces macros collent le C aux API du navigateur (DOM, fetch, Web Audio) sans écrire de bindings JS séparés.
#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;
}Support du système de fichiers (MEMFS)
Emscripten fournit MEMFS, un filesystem virtuel en mémoire. fopen/fread/fwrite marchent comme en C. Utilisez --preload-file pour embarquer les assets dans le sidecar .data à la compilation. Pour le stockage persistant, IDBFS se synchronise à IndexedDB ; NODERAWFS expose le vrai FS dans 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.txtCompiler du Rust vers Wasm
Mise en place wasm-pack
Rust compile vers Wasm via la cible wasm32-unknown-unknown. wasm-pack est l'outil recommandé — il enveloppe cargo, exécute wasm-bindgen et produit un package prêt pour npm. Pour les cibles WASI, utilisez wasm32-wasi à la place.
# 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 --versionStructure de lib Rust
wasm-bindgen est le pont entre Rust et JS. #[wasm_bindgen] marque les éléments à exporter. Chaînes, Vec<u8> et objets JS se convertissent automatiquement. L'attribut constructeur expose new() comme constructeur JS. Cela génère le glue JS qui fait sentir le Rust natif.
// 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
}
}Bâtir avec wasm-pack
wasm-pack build produit un package npm publiable : le binaire .wasm, le glue JS et les fichiers .d.ts TypeScript. --target web donne un module ES autonome pour usage direct navigateur ; --target bundler s'intègre à webpack/vite. Les types générés donnent l'autocomplétion TS complète.
# 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
Les blocs extern importent fonctions et classes JS en Rust. js_namespace = console appelle console.log. method expose des méthodes JS sur les types importés. wasm-bindgen gère les conversions de chaînes (&str Rust <-> chaîne JS) et la propriété — pas de jonglage mémoire manuel.
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;
}Appeler du JS depuis Rust et panics
Les fonctions JS importées apparaissent comme des fonctions Rust ordinaires. Utilisez console_error_panic_hook pour obtenir des backtraces de panic Rust lisibles dans la console du navigateur (les panics par défaut piègent sans message). L'attribut #[wasm_bindgen(start)] exécute main() à l'instanciation — comme le main du 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
Mise en place et Hello World
AssemblyScript est un langage semblable à TypeScript qui compile vers Wasm. Il vise les développeurs voulant la performance du Wasm sans apprendre C/Rust. La syntaxe rappelle TS mais avec des types stricts (i32 au lieu de number). Utilisez le loader ou importez le .wasm directement.
# 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)); // 5Types en AssemblyScript
Contrairement à TypeScript, AssemblyScript impose des types numériques concrets : i32, i64, f32, f64, u8, u16, u32, etc. 'number' est rejeté à la compilation. StaticArray évite le GC ; ArrayBuffer/TypedArray reflètent les API JS. Le typage strict est ce qui permet de compiler vers du Wasm efficace.
// 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);Mémoire et chaînes
AssemblyScript a un petit GC pour les objets gérés (Array, Map, String). Utilisez __retain/__release pour contrôler les durées de vie en traversant vers JS. Le @assemblyscript/loader fournit __getString, __newString, __getArray, etc., pour franchir la frontière.
// 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 et points d'entrée
Les fonctions et classes marquées export deviennent des exports Wasm. Les classes mappent vers des objets compatibles JS via le loader. _start est le point d'entrée conventionnel (comme le main du C). La stdlib d'AssemblyScript reflète Math, Array, Map de JS — rendant la courbe de migration douce.
// 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
}Compilation et optimisations
asc est le compilateur AssemblyScript. --optimize (-O) exécute le wasm-opt de Binaryen. --runtime contrôle le GC : 'full' (défaut), 'half' (plus petit), 'none' (manuel). --importMemory permet de partager la mémoire entre modules. Les source maps permettent le débogage dans la source .ts d'origine.
# 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)
Qu'est-ce que WASI
WASI est une interface système portable et basée capacités pour le Wasm hors navigateur. Contrairement au web où le Wasm appelle du JS, WASI donne au Wasm un accès direct (sandboxé) aux fichiers, réseau et environnement. La sécurité par capacités signifie qu'un programme ne peut toucher que les ressources explicitement pré-ouvertes pour lui.
// 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 est le runtime WASI de référence du Bytecode Alliance. --dir pré-ouvre un répertoire hôte (accordant l'accès aux fichiers). --env passe des variables d'env. --net active le réseau en preview2. Sans accords explicites, le programme Wasm ne voit rien — la sécurité par capacités en action.
# 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.wasmExécuter du Wasm avec WASI (exemple C)
Les programmes écrits pour WASI ressemblent à des programmes C ordinaires utilisant la libc. Compilez avec clang --target=wasm32-wasi et un sysroot WASI (téléchargez la release wasi-sdk). Le même .wasm tourne sur wasmtime, wasmer, WasmEdge et d'autres hôtes WASI sans recompilation — vraie portabilité.
// 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] = barAccès au filesystem WASI
WASI expose une API de filesystem POSIX-like (open, read, write, close). Les fichiers hors des répertoires pré-ouverts sont invisibles. Utilisez --dir=chemin:alias pour accorder l'accès et renommer. WASI preview2 introduit des interfaces component-model (wasi filesystem, wasi sockets) pour des API plus riches.
// 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.wasmEnvironnement et arguments WASI
WASI fournit les args et variables d'environnement via les interfaces C standard (argv, environ, getenv). L'hôte contrôle ce qui est visible — --env accorde des variables précises. Cela rend les programmes Wasm configurables sans changement de code et limite la fuite des secrets de l'hôte.
// 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)
Les sockets WASI font partie de preview2 (component model). wasi:sockets/tcp et wasi:sockets/udp fournissent le réseau ; wasi:http un client HTTP de plus haut niveau. Les API se stabilisent — préférez wasi:http pour la portabilité aujourd'hui. Les runtimes comme wasmtime et WasmEdge les implémentent.
// 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.Débogage
wasm-objdump
wasm-objdump (de WABT) imprime la structure d'un module : types, imports, exports, signatures de fonctions, désassemblage du code et tailles des sections. -x donne un résumé de haut niveau ; -d désassemble les corps de fonctions en instructions façon WAT. Essentiel pour comprendre ce qu'un module contient réellement.
# 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 pour l'inspection
wasm2wat reconvertit un .wasm binaire en WAT lisible humain. Inestimable pour comprendre des modules tiers, déboguer des comportements inattendus et faire du reverse engineering. L'aller-retour (wasm2wat → éditer → wat2wasm) préserve le comportement, faisant du WAT un vrai format source.
# 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 du navigateur
Tous les grands navigateurs déboguent le Wasm dans les DevTools : voir le WAT désassemblé, poser des breakpoints, inspecter locales et pile d'appels. Avec des source maps (Rust, AssemblyScript, Emscripten -g), les DevTools remontent à la source d'origine. Les infos de debug DWARF permettent un débogage plus riche pour 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
Les source maps relient les instructions Wasm au langage source d'origine. Rust les émet via wasm-pack ; AssemblyScript via --sourceMap ; Emscripten via -g4. Le commentaire sourceMappingURL dans le .wasm (section custom) dit aux DevTools où trouver le .map. Sans lui, on débogue du WAT brut.
# 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 sourceMappingURLErreurs courantes et pièges
Erreurs Wasm récurrentes : imports manquants (noms/types discordants), pièges (unreachable, mémoire hors bornes, débordement entier sur division par zéro), ArrayBuffers détachés (après grow) et soucis de frontière i64. Enveloppez les appels risqués de try/catch et validez imports/pointeurs en amont pour faire remonter les problèmes tôt.
// 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.Optimisation des performances
Inlining et flags -O
-O3 active l'inlining agressif et les optimisations de boucles. wasm-opt (Binaryen) exécute des passes supplémentaires au niveau Wasm (inlining, code mort, pliage de constantes) — lancez-le toujours en production. -Os/-Oz échangent un peu de vitesse contre de plus petits téléchargements. -flto active l'optimisation de programme entier.
# 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.wasmDisposition mémoire et patterns d'accès
La mémoire linéaire Wasm n'est qu'un ArrayBuffer — le comportement du cache CPU s'applique. Les patterns d'accès contigus (row-major pour des données row-major) sont drastiquement plus rapides que l'accès à pas. Maintenez l'alignement naturel (4 octets pour i32) pour que loads/stores touchent des instructions uniques.
// 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.Minimiser les franchissements de frontière JS
Chaque appel JS→Wasm a un coût (marshal des arguments, mise en place de pile). Pour les boucles serrées, déplacez la boucle DANS le Wasm et appelez-la une fois avec un buffer. C'est le plus grand conseil de perf Wasm — les opérations en masse battent les appels par élément de plusieurs ordres de grandeur.
// 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 (instruction unique, données multiples)
Le SIMD (v128) traite 4 flottants ou 4 int32 par instruction — des gains de 4x pour les maths d'image/audio/matrice. Emscripten l'active avec -msimd128 ; Rust utilise les intrinsics std::arch::wasm32. L'auto-vectorisation peut aider, mais les intrinsics explicites donnent des gains prévisibles. Largement supporté dans les navigateurs.
// 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 et SharedArrayBuffer
Les threads Wasm partagent une Memory entre Web Workers, avec des atomiques pour la synchronisation. Exige des en-têtes COOP/COEP (isolation cross-origin). -pthread d'Emscripten émule les pthreads ; std::thread de Rust marche sur wasm32-wasi-threads. Génial pour le travail parallèle borné CPU — traitement d'image, codecs, inférence 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.Profilage et benchmarks
Profilez avec performance.now() et l'onglet Performance des DevTools — le Wasm apparaît dans les flame charts comme le JS. Warm up avant de mesurer (l'overhead de compilation est ponctuel). Comparez à du JS optimisé — le V8 moderne est rapide ; le Wasm gagne sur la performance prévisible, les noyaux numériques et les grandes charges, pas les micro-tâches.
// 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
Comparaison de performance
Le Wasm brille pour le travail numérique gourmand en calcul (traitement d'image, codecs, crypto, ML) — typiquement 2 à 10x plus rapide que le JS. Pour le DOM, le JSON ou le travail riche en chaînes, le JS est souvent plus rapide car le travail est déjà en code natif (JSON.parse de V8, DOM du navigateur). Profilez pour décider — ne présumez jamais que le Wasm est toujours plus rapide.
// 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.Cas d'usage du Wasm
Le Wasm excelle à : porter des bases de code C/C++/Rust existantes (Figma, Photoshop web), les noyaux numériques gourmands en calcul (image/ML/crypto) et les plugins sandboxés. Des gains réels : Figma (renderer), Photoshop (port complet de l'app) et Google Meet (flou d'arrière-plan). Pour les apps purement DOM, le JS est généralement le bon choix.
// 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 blurQuand utiliser le JS
Le JS reste le bon choix pour l'UI, le DOM, les API navigateur et la plupart de la logique d'app web — V8 est lourdement optimisé. Recourez au Wasm quand le profilage révèle un hotspot que le JS ne peut pas optimiser, ou pour porter une base de code native existante. Une approche hybride (UI JS + hotspots Wasm) est souvent idéale.
// 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.Coût de chargement et de démarrage
Le Wasm a un coût de démarrage fixe (téléchargement + compilation + instanciation) que le JS évite. Mitigez avec la compilation en streaming, la mise en cache des modules compilés via l'API Cache et le chargement paresseux du Wasm non critique. Après le warm-up, les appels de fonctions Wasm sont aussi rapides que le JS — le coût est initial, remboursé par une exécution plus rapide.
// 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)Coût d'interop et overhead de frontière
Les appels JS↔Wasm sont bon marché mais pas gratuits (~10-100 ns chacun, plus pour les chaînes). Pour les événements à haute fréquence, batchez en JS et appelez le Wasm une fois avec un buffer. Évitez de passer des objets JS par appel — utilisez externref ou copiez les octets en mémoire. La frontière est rapide pour les nombres, lente pour les données sérialisées.
// 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 = [];
}
});Modèle de sécurité
Modèle sandbox
Le socle de sécurité du Wasm est le sandbox : un module ne peut pas accéder à la mémoire, fichiers, réseau ou devices de l'hôte sauf si l'hôte fournit explicitement des fonctions pour eux via les imports. Cela rend sûr l'exécution de code non fiable — il ne peut faire que ce que ses imports autorisent. Combiné à la sûreté de type, cela prévient buffer overflows et 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 et fetch
Le Wasm n'échappe pas au modèle de sécurité du navigateur — la same-origin policy et le CORS s'appliquent aux fetch de .wasm comme à toute ressource. Le Wasm cross-origin exige des en-têtes CORS appropriés et le type MIME application/wasm. Le Wasm ne peut pas non plus contourner CSP, cookies ni aucun autre mécanisme de sécurité du navigateur.
// 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.Isolation mémoire
La mémoire Wasm est bornée à l'exécution — tout accès hors bornes piège immédiatement au lieu de corrompre la mémoire. Les modules ne peuvent lire la mémoire des autres, le tas JS ni des adresses hôtes arbitraires. Les pointeurs de fonctions (call_indirect) sont vérifiés en type, prévenant la falsification de cible d'appel. Cela élimine des classes entières de vulnérabilités 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.Sécurité par capacités
Le Wasm suit la sécurité par capacités : l'objet d'import EST les capacités du module. En choisissant soigneusement quoi importer, on donne au module un privilège minimal. Un plugin qui n'importe que log() ne peut rien faire d'autre. C'est le socle des systèmes de plugins sûrs (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 et Trusted Types
La Content Security Policy traite le Wasm comme eval — par défaut, CSP le bloque. Ajoutez 'wasm-unsafe-eval' à script-src pour autoriser le Wasm tout en gardant eval() bloqué. Plus permissif que unsafe-eval et recommandé en production. La compatibilité Trusted Types exige d'envelopper tout glue JS dynamique dans une 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.Chaîne d'outils
WABT (wat2wasm, wasm2wat)
WABT est le toolkit canonique pour travailler les formats texte et binaire du Wasm. wat2wasm/wasm2wat en aller-retour ; wasm-objdump inspecte la structure ; wasm-interp exécute les modules dans un interpréteur de référence. wasm-decompile produit une forme lisible façon C. Essentiel pour écrire à la main, déboguer et enseigner.
# 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 est la toolchain Wasm la plus mature — compile C/C++, Fortran et autres langages LLVM. emcc/em++ enveloppent Clang ; emcmake/emconfigure permettent de bâtir des projets CMake/Autotools existants sans modification. Elle fournit aussi libc, SDL, OpenGL (via WebGL) et des ports pthreads pour la compatibilité.
# 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 est l'outil officiel Rust→Wasm : bâtir, exécuter wasm-bindgen, générer les types TypeScript et packager pour npm. --target choisit le format de module JS. wasm-pack test exécute les tests Rust dans de vrais navigateurs via webdriver. Utilisez wasm-pack-template pour un scaffold de projet prêt.
# 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 est le toolkit d'optimisation qu'Emscripten et wasm-pack utilisent en interne. wasm-opt exécute des passes au niveau Wasm (inlining, élimination de code mort, pliage de constantes) — lancez-le toujours sur les builds de production. -O3 pour la vitesse, -Oz pour la taille minimale. wasm-metadce retire les exports inutilisés entre modules.
# 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 est un toolkit moderne basé Rust du Bytecode Alliance. Il parse/imprime/valide, mais sa fonctionnalité vedette est le support du component model (component new/embed/describe). Plus strict et plus rapide que WABT pour beaucoup d'opérations et l'outil recommandé pour le travail 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)
Trois grands runtimes autonomes : wasmtime (référence du Bytecode Alliance, meilleur support component-model), wasmer (plusieurs backends dont LLVM pour la performance pic, bindings JS), WasmEdge (CNCF, optimisé cloud-native et inférence IA). Tous implémentent WASI, donc le même .wasm tourne entre eux. Choisissez selon l'écosystème.
# 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.Components et bonnes pratiques
Aperçu des Wasm Components
Le Component Model est l'évolution du Wasm : un format de module qui laisse les components communiquer avec des types riches (chaînes, records, listes) sans marshal manuel à travers la mémoire linéaire. Les components se composent comme des bibliothèques entre langages (component Rust + component JS). Supporté par wasmtime, WasmEdge et l'écosystème élargi du 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) est l'IDL des components — déclarez records, variants, enums, resources et fonctions. wit-bindgen génère les bindings spécifiques aux langages (Rust, C, JS, Python). Le mot-clé 'world' regroupe les imports et exports qu'un component fournit/consomme. C'est le socle des bibliothèques Wasm portables et agnostiques du langage.
// 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-cliBonne pratique : petits modules focalisés
Préférez plusieurs petits modules Wasm focalisés à un monolithe. Les modules plus petits se téléchargent plus vite, se cachent mieux et peuvent se charger paresseusement (charger le module audio seulement au besoin). Partagez la mémoire entre modules via les imports, ou utilisez le component model pour des appels inter-modules type-safe. Lancez wasm-opt -Oz sur chacun.
// 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.Bonne pratique : gestion des erreurs
Les pièges Wasm (division par zéro, mémoire hors bornes, unreachable) ne s'attrapent pas depuis l'intérieur du Wasm — ils avortent la fonction. Concevez les fonctions exportées pour retourner des codes d'erreur ou types Result au lieu de piéger. Attrapez WebAssembly.RuntimeError côté JS en dernier recours. Le component model supporte nativement des variants d'erreur typés.
// 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.Bonne pratique : gestion mémoire
Traitez la mémoire Wasm comme du C : chaque alloc exige un free correspondant. Exportez des helpers alloc/free et enveloppez l'usage de buffers côté JS de try/finally. Recréez les vues TypedArray après tout memory.grow (l'ArrayBuffer se détache). Documentez la propriété : qui est responsable de libérer — l'appelant ou l'appelé ? Les fuites dégradent la performance dans le temps.
// 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 ownershipBonne pratique : tests et CI
Testez le Wasm dans de vrais environnements : wasm-pack test exécute les tests Rust dans des navigateurs headless ; AssemblyScript et Emscripten ont leurs propres runners. Ajoutez wasm-validate et des vérifications de taille à la CI. Utilisez -s ASSERTIONS=1 (Emscripten) et des builds debug pour attraper les soucis tôt. Lint avec wat2wasm et lancez toujours wasm-opt sur les artefacts 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 WebAssembly associés
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?