d8 shell — the foundation for every embedding lesson that follows.
Until now you've borrowed V8 from Node. To embed V8 you need the engine as a library you compile and link against. That means checking out the real source and building it with Google's toolchain. Heads-up before you start:
You already have these from our setup check — verify them:
xcode-select --install # Xcode Command Line Tools (you have Xcode)
sudo xcodebuild -license accept
git --version && python3 --versionPer v8.dev/docs/build: install Xcode and accept
its license. Do not run the Linux-only install-build-deps.sh on macOS.
depot_tools is Google's wrapper around git/gn/ninja. It even vendors its own Python, so there's nothing else to install.
cd ~
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
echo 'export PATH="$HOME/depot_tools:$PATH"' >> ~/.zshrc
source ~/.zshrcSource: v8.dev/docs/source-code → depot_tools tutorial.
fetch v8 is the one-time checkout — it configures gclient and pulls V8 plus all its
dependencies. (Later, gclient sync re-syncs deps after you git pull.)
mkdir ~/v8
cd ~/v8
fetch v8 # one-time; this is the long download
cd v8Source: v8.dev/docs/source-code (verbatim).
gmtools/dev/gm.py ("gm") is V8's all-in-one helper: it generates build files, builds,
and can run tests. On Apple Silicon, the native target is arm64.release (the
docs' examples say x64 because they're written for Intel).
alias gm=~/v8/v8/tools/dev/gm.py
gm arm64.release # builds default targets incl. d8 → out/arm64.release/When it finishes, your shell is here:
out/arm64.release/d8 --version
echo "1 + 1" | out/arm64.release/d8 # prints 2
out/arm64.release/d8 # interactive REPL — Ctrl-D to exitSource: v8.dev/docs/build-gn. The
gm default targets include d8; to build only it, use the manual path below.
gm wraps these two steps:
gn gen out/arm64.release --args='is_debug=false target_cpu="arm64"'
ninja -C out/arm64.release d8target_cpu="arm64" — not v8_target_cpu,
which the docs use only for the cross-compiling simulator.
To link V8 into your own C++ program (next lesson), you need it as one static library — the "monolith". A predefined config sets the right GN args for you:
tools/dev/v8gen.py arm64.release.sample
ninja -C out.gn/arm64.release.sample v8_monolithThe .sample config expands to exactly these four args (you could spell them out with
gn gen instead — equivalent):
v8_monolithic=true is_component_build=false
v8_use_external_startup_data=false use_custom_libcxx=falseThis produces out.gn/arm64.release.sample/obj/libv8_monolith.a — the library you'll
link in Lesson 4.
Source: v8.dev/docs/embed; the four-arg
expansion confirmed in V8's infra/mb/mb_config.pyl.
git clone https://github.com/v8/v8 and try to build it — that mirror has
no dependencies. You must use fetch v8 via depot_tools.
(2) Keep your -L library path consistent with how you generated: v8gen.py
writes to out.gn/…, a bare gn gen writes to wherever you point it
(out/…). Mixing them up = "library not found".
| Artifact | What it is |
|---|---|
| depot_tools | Google's build toolchain wrapper (git helpers, gn, ninja, vendored Python). |
| fetch v8 | The checkout command — pulls V8 + all deps. One-time; gclient sync updates later. |
| GN | Meta-build system: turns build args into ninja files. (gn gen.) |
| ninja | The fast build executor that actually compiles. (ninja -C out/… target.) |
| d8 | V8's developer shell — a minimal embedder. Runs JS files, has a REPL, exposes all the flags from Lessons 1–2 & 7–8. |
| libv8_monolith.a | V8 as a single static library, ready to link into your own C++ host (Lesson 4). |
d8. Everything you did in Node now
works on your own engine: out/arm64.release/d8 --print-bytecode --print-bytecode-filter=add /tmp/v8demo.js.
Same flags, but now it's your build. See the flags cheat sheet.
git clone github.com/v8/v8 and build it?fetch v8
stalls, gm errors, or a flag isn't recognized, paste the output to me and I'll help
debug. Also good: "Walk me through what gclient actually did," or "How do I update my
checkout later?" If you'd rather not spend the disk/time right now, tell me and we can keep
using Node's V8 for the embedding lessons' concepts and you can build later.
You have a compiled V8, a working d8, and libv8_monolith.a ready to link.
Next: Lesson 4 — the Hello-World Embedder. You'll compile a ~60-line C++ program that creates
its own V8 engine instance, runs a script, and prints the result — your first time driving V8
from the outside.
Reference: V8 Glossary · Inspection Flags (now work on d8)