mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
489 lines
24 KiB
HTML
489 lines
24 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>wasm-fundamentals</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/wasm-fundamentals.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/wasm-fundamentals">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/wasm-fundamentals.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>wasm-fundamentals</h1><p class="lede">WebAssembly basics including binary format, modules, linear memory, WASI, and core tooling</p><h1>WebAssembly Fundamentals</h1>
|
|
<p><strong>Scope</strong>: Core WebAssembly concepts, module structure, memory model, WASI, and essential tooling <strong>Lines</strong>: ~300 <strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
|
|
<hr>
|
|
<h2>When to Use This Skill</h2>
|
|
<p>Activate this skill when:</p>
|
|
<ul><li>Starting a new WebAssembly project from any language</li><li>Understanding wasm binary and text format structure</li><li>Working with wasm modules, imports, and exports</li><li>Implementing portable executables across platforms</li><li>Using WASI for system interface access</li><li>Converting between WAT (text) and wasm (binary) formats</li><li>Debugging wasm module structure and layout</li><li>Optimizing wasm module size and performance</li></ul>
|
|
<h2>Core Concepts</h2>
|
|
<h3>Concept 1: Module Structure</h3>
|
|
<p><strong>Components</strong>:</p>
|
|
<ul><li>Types: Function signatures</li><li>Imports: External dependencies (functions, memory, tables, globals)</li><li>Functions: Internal function definitions</li><li>Tables: Indirect function call tables</li><li>Memory: Linear memory blocks</li><li>Globals: Global variables</li><li>Exports: Public API surface</li><li>Start: Optional initialization function</li></ul>
|
|
<pre><code class="lang-wat">;; WAT (WebAssembly Text Format) module
|
|
(module
|
|
;; Import host function
|
|
(import "env" "log" (func $log (param i32)))
|
|
|
|
;; Linear memory (1 page = 64KB)
|
|
(memory (export "memory") 1)
|
|
|
|
;; Export function
|
|
(func (export "add") (param $a i32) (param $b i32) (result i32)
|
|
local.get $a
|
|
local.get $b
|
|
i32.add
|
|
)
|
|
|
|
;; Table for indirect calls
|
|
(table 1 funcref)
|
|
)</code></pre>
|
|
<h3>Concept 2: Linear Memory Model</h3>
|
|
<p><strong>Characteristics</strong>:</p>
|
|
<ul><li>Contiguous byte array starting at address 0</li><li>Grows in 64KB pages (65,536 bytes)</li><li>Shared between wasm and host (JavaScript/runtime)</li><li>No garbage collection (manual memory management)</li><li>Sandboxed (cannot access outside memory)</li></ul>
|
|
<pre><code class="lang-rust">// Rust code compiling to wasm
|
|
#[no_mangle]
|
|
pub extern "C" fn allocate(size: usize) -> *mut u8 {
|
|
let mut buffer = Vec::with_capacity(size);
|
|
let ptr = buffer.as_mut_ptr();
|
|
std::mem::forget(buffer); // Prevent deallocation
|
|
ptr
|
|
}
|
|
|
|
#[no_mangle]
|
|
pub extern "C" fn deallocate(ptr: *mut u8, size: usize) {
|
|
unsafe {
|
|
let _ = Vec::from_raw_parts(ptr, 0, size);
|
|
// Automatically dropped
|
|
}
|
|
}</code></pre>
|
|
<h3>Concept 3: WASI (WebAssembly System Interface)</h3>
|
|
<p><strong>Purpose</strong>: Standardized system interface for non-web environments</p>
|
|
<p><strong>Capabilities</strong>:</p>
|
|
<ul><li>Filesystem access (with capability-based security)</li><li>Environment variables</li><li>Command-line arguments</li><li>Clock/time functions</li><li>Random number generation</li><li>Network access (preview2)</li></ul>
|
|
<pre><code class="lang-rust">// Using WASI filesystem
|
|
use std::fs::File;
|
|
use std::io::Write;
|
|
|
|
fn main() {
|
|
// WASI runtime provides sandboxed filesystem
|
|
let mut file = File::create("output.txt").unwrap();
|
|
file.write_all(b"Hello from WASI").unwrap();
|
|
}</code></pre>
|
|
<h3>Concept 4: Binary Format</h3>
|
|
<p><strong>Structure</strong>: Efficient binary encoding for fast parsing</p>
|
|
<ul><li>Magic number: <code>0x00 0x61 0x73 0x6D</code> ("\0asm")</li><li>Version: <code>0x01 0x00 0x00 0x00</code> (version 1)</li><li>Sections: Type, Import, Function, Table, Memory, Global, Export, Start, Element, Code, Data, Custom</li></ul>
|
|
<pre><code class="lang-bash"># View binary format with hexdump
|
|
hexdump -C module.wasm | head -n 5
|
|
# 00000000 00 61 73 6d 01 00 00 00 01 07 01 60 02 7f 7f 01 |.asm.......`....|
|
|
|
|
# Convert wasm to readable WAT
|
|
wasm2wat module.wasm -o module.wat
|
|
|
|
# Convert WAT back to wasm
|
|
wat2wasm module.wat -o module.wasm</code></pre>
|
|
<hr>
|
|
<h2>Patterns</h2>
|
|
<h3>Pattern 1: Creating Minimal Module</h3>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul><li>Testing wasm runtime setup</li><li>Understanding module structure</li><li>Building from scratch without toolchains</li></ul>
|
|
<pre><code class="lang-wat">;; Minimal valid wasm module
|
|
(module
|
|
(func (export "answer") (result i32)
|
|
i32.const 42
|
|
)
|
|
)</code></pre>
|
|
<pre><code class="lang-bash"># Compile and run
|
|
wat2wasm minimal.wat
|
|
# Produces minimal.wasm (~20 bytes)</code></pre>
|
|
<p><strong>Benefits</strong>:</p>
|
|
<ul><li>Smallest possible wasm file</li><li>No dependencies</li><li>Fast compilation and instantiation</li></ul>
|
|
<h3>Pattern 2: String Passing via Memory</h3>
|
|
<p><strong>Use case</strong>: Passing strings between host and wasm</p>
|
|
<pre><code class="lang-rust">// wasm module
|
|
use std::slice;
|
|
|
|
#[no_mangle]
|
|
pub extern "C" fn process_string(ptr: *const u8, len: usize) -> usize {
|
|
let input = unsafe { slice::from_raw_parts(ptr, len) };
|
|
let text = std::str::from_utf8(input).unwrap();
|
|
|
|
// Process and return length
|
|
text.len()
|
|
}</code></pre>
|
|
<pre><code class="lang-javascript">// JavaScript host
|
|
const encoder = new TextEncoder();
|
|
const str = "Hello, WebAssembly!";
|
|
const bytes = encoder.encode(str);
|
|
|
|
// Write to wasm memory
|
|
const ptr = instance.exports.allocate(bytes.length);
|
|
const memory = new Uint8Array(instance.exports.memory.buffer);
|
|
memory.set(bytes, ptr);
|
|
|
|
// Call wasm function
|
|
const result = instance.exports.process_string(ptr, bytes.length);
|
|
instance.exports.deallocate(ptr, bytes.length);</code></pre>
|
|
<h3>Pattern 3: WASI Command-Line Tool</h3>
|
|
<p><strong>Use case</strong>: Building portable CLI tools with WASI</p>
|
|
<pre><code class="lang-rust">use std::env;
|
|
use std::fs;
|
|
|
|
fn main() {
|
|
let args: Vec<String> = env::args().collect();
|
|
|
|
if args.len() < 2 {
|
|
eprintln!("Usage: {} <filename>", args[0]);
|
|
std::process::exit(1);
|
|
}
|
|
|
|
let content = fs::read_to_string(&args[1])
|
|
.expect("Failed to read file");
|
|
|
|
println!("File length: {}", content.len());
|
|
}</code></pre>
|
|
<pre><code class="lang-bash"># Compile with WASI target
|
|
rustup target add wasm32-wasi
|
|
cargo build --target wasm32-wasi --release
|
|
|
|
# Run with wasmtime (WASI runtime)
|
|
wasmtime target/wasm32-wasi/release/tool.wasm -- input.txt</code></pre>
|
|
<h3>Pattern 4: Module Inspection</h3>
|
|
<p><strong>Use case</strong>: Understanding wasm module contents</p>
|
|
<pre><code class="lang-bash"># Show module structure
|
|
wasm-objdump -x module.wasm
|
|
|
|
# Show function disassembly
|
|
wasm-objdump -d module.wasm
|
|
|
|
# Validate module
|
|
wasm-validate module.wasm
|
|
|
|
# Optimize module
|
|
wasm-opt -O3 module.wasm -o optimized.wasm</code></pre>
|
|
<h3>Pattern 5: Multi-Memory Modules (wasm 2.0)</h3>
|
|
<p><strong>When to use</strong>: Isolating memory regions</p>
|
|
<pre><code class="lang-wat">(module
|
|
;; Multiple memories
|
|
(memory $data (export "data") 1 10)
|
|
(memory $scratch (export "scratch") 1 1)
|
|
|
|
(func (export "use_memories")
|
|
;; Write to data memory
|
|
(i32.store (memory $data) (i32.const 0) (i32.const 42))
|
|
|
|
;; Write to scratch memory
|
|
(i32.store (memory $scratch) (i32.const 0) (i32.const 99))
|
|
)
|
|
)</code></pre>
|
|
<h3>Pattern 6: Error Handling with Result Types</h3>
|
|
<p><strong>Use case</strong>: Safe error propagation from wasm</p>
|
|
<pre><code class="lang-rust">// Return error codes via i32
|
|
#[no_mangle]
|
|
pub extern "C" fn divide(a: i32, b: i32, result: *mut i32) -> i32 {
|
|
if b == 0 {
|
|
return -1; // Error code
|
|
}
|
|
|
|
unsafe {
|
|
*result = a / b;
|
|
}
|
|
0 // Success code
|
|
}</code></pre>
|
|
<hr>
|
|
<h2>Quick Reference</h2>
|
|
<h3>Essential Tools</h3>
|
|
<pre><code>Tool | Purpose | Example
|
|
--------------|----------------------------|---------------------------
|
|
wat2wasm | Compile WAT to binary | wat2wasm module.wat
|
|
wasm2wat | Decompile binary to WAT | wasm2wat module.wasm
|
|
wasm-objdump | Inspect module structure | wasm-objdump -x module.wasm
|
|
wasm-validate | Validate wasm module | wasm-validate module.wasm
|
|
wasm-opt | Optimize binary size | wasm-opt -O3 in.wasm -o out.wasm
|
|
wasmtime | WASI runtime | wasmtime module.wasm</code></pre>
|
|
<h3>Value Types</h3>
|
|
<pre><code>Type | Description | Size
|
|
------|--------------------|---------
|
|
i32 | 32-bit integer | 4 bytes
|
|
i64 | 64-bit integer | 8 bytes
|
|
f32 | 32-bit float | 4 bytes
|
|
f64 | 64-bit float | 8 bytes
|
|
v128 | 128-bit vector | 16 bytes (SIMD)
|
|
funcref | Function reference | opaque
|
|
externref | External reference | opaque</code></pre>
|
|
<h3>Key Guidelines</h3>
|
|
<pre><code>✅ DO: Use WASI for portable system access
|
|
✅ DO: Validate modules before deployment
|
|
✅ DO: Use wasm-opt to minimize binary size
|
|
✅ DO: Export memory for host interaction
|
|
✅ DO: Handle out-of-bounds memory access
|
|
|
|
❌ DON'T: Assume garbage collection exists
|
|
❌ DON'T: Access memory outside bounds
|
|
❌ DON'T: Use platform-specific syscalls directly</code></pre>
|
|
<hr>
|
|
<h2>Anti-Patterns</h2>
|
|
<h3>Critical Violations</h3>
|
|
<pre><code class="lang-rust">// ❌ NEVER: Access uninitialized memory
|
|
#[no_mangle]
|
|
pub extern "C" fn unsafe_read(ptr: *const u8, len: usize) -> u8 {
|
|
unsafe {
|
|
*ptr // May be uninitialized or out of bounds
|
|
}
|
|
}
|
|
|
|
// ✅ CORRECT: Validate before access
|
|
#[no_mangle]
|
|
pub extern "C" fn safe_read(ptr: *const u8, len: usize) -> i32 {
|
|
if ptr.is_null() || len == 0 {
|
|
return -1; // Error
|
|
}
|
|
|
|
unsafe {
|
|
let slice = std::slice::from_raw_parts(ptr, len);
|
|
slice[0] as i32
|
|
}
|
|
}</code></pre>
|
|
<p>❌ <strong>Memory leaks</strong>: Forgetting to deallocate wasm-allocated memory from host ✅ <strong>Correct approach</strong>: Pair every allocate call with deallocate</p>
|
|
<h3>Common Mistakes</h3>
|
|
<pre><code class="lang-wat">;; ❌ Don't: Grow memory without checking result
|
|
(func $grow_unchecked
|
|
i32.const 10
|
|
memory.grow
|
|
drop ;; Ignoring result (-1 on failure)
|
|
)
|
|
|
|
;; ✅ Correct: Check growth success
|
|
(func $grow_checked (result i32)
|
|
i32.const 10
|
|
memory.grow
|
|
i32.const -1
|
|
i32.eq
|
|
if
|
|
i32.const 0 ;; Failed
|
|
return
|
|
end
|
|
i32.const 1 ;; Success
|
|
)</code></pre>
|
|
<p>❌ <strong>Ignoring memory growth failures</strong>: Can cause crashes ✅ <strong>Better</strong>: Always check memory.grow return value</p>
|
|
<h3>Module Size Anti-Pattern</h3>
|
|
<pre><code class="lang-bash"># ❌ Don't: Ship unoptimized debug builds
|
|
cargo build --target wasm32-unknown-unknown
|
|
# Produces large binary with debug info
|
|
|
|
# ✅ Correct: Use release mode + optimization
|
|
cargo build --target wasm32-unknown-unknown --release
|
|
wasm-opt -O3 target/wasm32-unknown-unknown/release/app.wasm \
|
|
-o optimized.wasm</code></pre>
|
|
<p>❌ <strong>Large binaries</strong>: Slow network transfer, parsing ✅ <strong>Better</strong>: Always optimize production wasm</p>
|
|
<hr>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><code>wasm-rust-toolchain.md</code> - Rust-specific wasm compilation and tooling</li><li><code>wasm-browser-integration.md</code> - Loading and using wasm in browsers</li><li><code>wasm-server-side.md</code> - Server-side wasm execution with Wasmtime</li><li><code>rust-memory-management.md</code> - Understanding Rust ownership for wasm</li><li><code>zig-memory-management.md</code> - Manual memory management patterns</li></ul>
|
|
<hr>
|
|
<p><strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/wasm-fundamentals.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |