The Hello-World Embedder

An embedder is any C++ program that hosts V8 (Chrome and Node are just very large embedders). The official samples/hello-world.cc is the smallest possible one. Let's read it as a story in four nested layers, then compile and run it on the V8 you built in Lesson 3.

The shape of every embedder: nested scopes

Before the code, the mental model. An embedder is a set of nested setups, each one a C++ object whose constructor enters something and whose destructor leaves it (that's the RAII idiom — "Resource Acquisition Is Initialization"; the object's lifetime is the resource's lifetime). The nesting, outer to inner:

All definitions quoted from v8.dev/docs/embed.

The code (the JS-running core of hello-world.cc)

This is the current official sample, trimmed to the JavaScript path (the real file also runs a WebAssembly snippet — same pattern). Read the comments top to bottom:

// modern V8 uses granular headers, not a single v8.h
#include "include/libplatform/libplatform.h"
#include "include/v8-context.h"
#include "include/v8-initialization.h"
#include "include/v8-isolate.h"
#include "include/v8-local-handle.h"
#include "include/v8-primitive.h"
#include "include/v8-script.h"

int main(int argc, char* argv[]) {
  // 1. Process-wide init — do this once. Order matters: platform BEFORE Initialize.
  v8::V8::InitializeICUDefaultLocation(argv[0]);
  v8::V8::InitializeExternalStartupData(argv[0]);
  std::unique_ptr<v8::Platform> platform = v8::platform::NewDefaultPlatform();
  v8::V8::InitializePlatform(platform.get());
  v8::V8::Initialize();

  // 2. Create an Isolate (a VM instance with its own heap).
  v8::Isolate::CreateParams create_params;
  create_params.array_buffer_allocator =
      v8::ArrayBuffer::Allocator::NewDefaultAllocator();
  v8::Isolate* isolate = v8::Isolate::New(create_params);
  {
    v8::Isolate::Scope isolate_scope(isolate);   // make this isolate current
    v8::HandleScope handle_scope(isolate);       // 3. container for Local handles (stack-only)

    // 4. Create and enter a Context (an isolated JS environment).
    v8::Local<v8::Context> context = v8::Context::New(isolate);
    v8::Context::Scope context_scope(context);
    {
      // 5. The actual work: source -> compile -> run -> read result.
      v8::Local<v8::String> source =
          v8::String::NewFromUtf8Literal(isolate, "'Hello' + ', World!'");
      v8::Local<v8::Script> script =
          v8::Script::Compile(context, source).ToLocalChecked();
      v8::Local<v8::Value> result = script->Run(context).ToLocalChecked();

      // 6. Convert the JS string result to UTF-8 and print it.
      v8::String::Utf8Value utf8(isolate, result);
      printf("%s\n", *utf8);              // => Hello, World!
    }
  }

  // 7. Tear down in reverse order.
  isolate->Dispose();
  v8::V8::Dispose();
  v8::V8::DisposePlatform();
  delete create_params.array_buffer_allocator;
  return 0;
}

Verbatim structure from samples/hello-world.cc (current main). Note modern V8 uses DisposePlatform(), not the older ShutdownPlatform().

Three things worth pausing on

Compile and run it hands-on

cd ~/v8/v8
clang++ -I. -Iinclude samples/hello-world.cc -o hello_world \
  -fno-rtti -std=c++20 \
  -DV8_COMPRESS_POINTERS -DV8_ENABLE_SANDBOX \
  -Lout.gn/arm64.release.sample/obj/ \
  -lv8_monolith -lv8_libbase -lv8_libplatform \
  -ldl -pthread

./hello_world

Hello, World!
3 + 4 = 7        # from the WebAssembly part of the sample

Check yourself feedback loop

Where this lands you

You've compiled a real embedder and driven V8 from C++ — boot, context, compile, run, read result, tear down. But we glossed over one thing: those Local<T> handles, and why every value is wrapped in one. Lesson 5 goes deep on handles and scopes — Local vs Global, and the GC reason they're mandatory (which Lesson 8 already spoiled: the heap moves).

Reference: V8 Glossary (embedding terms) · Related: Lesson 8 (why handles)