Getting Started with Embedding

Peter Marshall edited this page May 24, 2018 · 11 revisions
Clone this wiki locally

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.

Run the Example

Follow the steps below to run the example yourself:

  1. Download the V8 source code by following the git instructions.

  2. This hello world example is compatible with version 6.8. You can check out this branch with git checkout -b 6.8 -t branch-heads/6.8

  3. Create a build configuration using the helper script: tools/dev/v8gen.py x64.release

  4. Edit the default build configuration by running gn args out.gn/x64.release. Add these lines to your configuration:

    is_component_build = false
    v8_static_library = true
    use_custom_libcxx = false
    use_custom_libcxx_for_host = false
    
  5. Build via ninja -C out.gn/x64.release on a Linux x64 system to generate the correct binaries.

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

    g++ -I. -Iinclude samples/hello-world.cc -o hello-world -Wl,--start-group \
    out.gn/x64.release/obj/{libv8_{base,libbase,external_snapshot,libplatform,libsampler},\
    third_party/icu/libicu{uc,i18n},src/inspector/libinspector}.a \
    -Wl,--end-group -lrt -ldl -pthread -std=c++0x
    
  7. V8 requires its 'startup snapshot' to run. Copy the snapshot files to where your binary is stored: cp out.gn/x64.release/*.bin .

  8. For more complex code, V8 will fail without an ICU data file. Copy this file as well: cp out.gn/x64.release/icudtl.dat .

  9. Run the hello_world executable file at the command line. e.g. On Linux, in the V8 directory, run: ./hello_world

  10. 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. If you are looking for an example which is in sync with master simply check out the file hello-world.cc.