This document introduces some key V8 concepts and provides a hello world example to get you started with V8 code.

Audience

This document is intended for C++ programmers who want to embed the V8 JavaScript engine within a C++ application.

Hello World

Let's look at a Hello World example that takes a JavaScript statement as a string argument, executes it as JavaScript code, and prints the result to standard out.

First, some key concepts you will need:

  • An isolate is a VM instance with its own heap.
  • A local handle is a pointer to an object. All V8 objects are accessed using handles. They are necessary because of the way the V8 garbage collector works.
  • A handle scope can be thought of as a container for any number of handles. When you've finished with your handles, instead of deleting each one individually you can simply delete their scope.
  • A context is an execution environment that allows separate, unrelated, JavaScript code to run in a single instance of V8. You must explicitly specify the context in which you want any JavaScript code to be run.

These concepts are discussed in greater detail in the [[Embedder‘s Guide|Embedder’s Guide]].

Run the Example

Follow the steps below to run the example yourself:

  1. Download the V8 source code by following the [[git|Using-Git]] instructions.

  2. The instructions for this hello world example has last been tested with V8 7.1.11. You can check out this branch with git checkout refs/tags/7.1.11 -b sample -t

  3. Create a build configuration using the helper script: tools/dev/v8gen.py x64.release.sample. You can inspect and manually edit the build configuration by running gn args out.gn/x64.release.sample.

  4. Build via ninja -C out.gn/x64.release.sample v8_monolith on a Linux x64 system to generate the static library.

  5. Compile hello-world.cc, linking to the static library created in the build process. For example, on 64bit Linux using the GNU compiler:

    g++ -I. -Iinclude samples/hello-world.cc -o hello_world -lv8_monolith -Lout.gn/x64.release.sample/obj/ -pthread -std=c++0x
    
  6. For more complex code, V8 will fail without an ICU data file. Copy this file to where your binary is stored:

    cp out.gn/x64.release.sample/icudtl.dat .
    
  7. Run the hello_world executable file at the command line. e.g. On Linux, in the V8 directory, run: ./hello_world

  8. You will see Hello, World!.

Of course this is a very simple example and it‘s likely you’ll want to do more than just execute scripts as strings! For more information see the [[Embedder‘s Guide|Embedder’s Guide]]. If you are looking for an example which is in sync with master simply check out the file hello-world.cc.