<commit_before>---
title: 'Getting started with embedding V8'
description: 'This document introduces some key V8 concepts and provides a “hello world” example to get you started with V8 code.'
---
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. It helps you to make your own application’s C++ objects and methods available to JavaScript, and to make JavaScript objects and functions available to your C++ application.

## Hello world

Let’s look at a [Hello World example](https://chromium.googlesource.com/v8/v8/+/branch-heads/6.8/samples/hello-world.cc) 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:

- 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 advanced guide](/docs/embed#advanced-guide).

## Run the example

Follow the steps below to run the example yourself:

1. Download the V8 source code by following [the Git instructions](/docs/source-code#using-git).
1. The instructions for this hello world example have last been tested with V8 v7.1.11. You can check out this branch with `git checkout refs/tags/7.1.11 -b sample -t`
1. Create a build configuration using the helper script:

    ```bash
    tools/dev/v8gen.py x64.release.sample
    ```

    You can inspect and manually edit the build configuration by running:

    ```bash
    gn args out.gn/x64.release.sample
    ```

1. Build the static library on a Linux 64 system:

    ```bash
    ninja -C out.gn/x64.release.sample v8_monolith
    ```

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

    ```bash
    g++ -I. -Iinclude samples/hello-world.cc -o hello_world -lv8_monolith -Lout.gn/x64.release.sample/obj/ -pthread -std=c++0x -DV8_COMPRESS_POINTERS
    ```

1. For more complex code, V8 fails without an ICU data file. Copy this file to where your binary is stored:

    ```bash
    cp out.gn/x64.release.sample/icudtl.dat .
    ```

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

    ```bash
    ./hello_world
    ```

1. It prints `Hello, World!`. Yay!

If you are looking for an example which is in sync with master, check out the file [`hello-world.cc`](https://chromium.googlesource.com/v8/v8/+/master/samples/hello-world.cc). This is a very simple example and you’ll likely want to do more than just execute scripts as strings. [The advanced guide below](#advanced-guide) contains more information for V8 embedders.

## More example code

The following samples are provided as part of the source code download.

### [`process.cc`](https://github.com/v8/v8/blob/master/samples/process.cc)

This sample provides the code necessary to extend a hypothetical HTTP request processing application — which could be part of a web server, for example — so that it is scriptable. It takes a JavaScript script as an argument, which must provide a function called `Process`. The JavaScript `Process` function can be used to, for example, collect information such as how many hits each page served by the fictional web server gets.<commit_msg>Change -std=c++0x to -std=c++14 for hello_world.cc (#530)<commit_after>---
title: 'Getting started with embedding V8'
description: 'This document introduces some key V8 concepts and provides a “hello world” example to get you started with V8 code.'
---
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. It helps you to make your own application’s C++ objects and methods available to JavaScript, and to make JavaScript objects and functions available to your C++ application.

## Hello world

Let’s look at a [Hello World example](https://chromium.googlesource.com/v8/v8/+/branch-heads/6.8/samples/hello-world.cc) 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:

- 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 advanced guide](/docs/embed#advanced-guide).

## Run the example

Follow the steps below to run the example yourself:

1. Download the V8 source code by following [the Git instructions](/docs/source-code#using-git).
1. The instructions for this hello world example have last been tested with V8 v7.1.11. You can check out this branch with `git checkout refs/tags/7.1.11 -b sample -t`
1. Create a build configuration using the helper script:

    ```bash
    tools/dev/v8gen.py x64.release.sample
    ```

    You can inspect and manually edit the build configuration by running:

    ```bash
    gn args out.gn/x64.release.sample
    ```

1. Build the static library on a Linux 64 system:

    ```bash
    ninja -C out.gn/x64.release.sample v8_monolith
    ```

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

    ```bash
    g++ -I. -Iinclude samples/hello-world.cc -o hello_world -lv8_monolith -Lout.gn/x64.release.sample/obj/ -pthread -std=c++14 -DV8_COMPRESS_POINTERS
    ```

1. For more complex code, V8 fails without an ICU data file. Copy this file to where your binary is stored:

    ```bash
    cp out.gn/x64.release.sample/icudtl.dat .
    ```

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

    ```bash
    ./hello_world
    ```

1. It prints `Hello, World!`. Yay!

If you are looking for an example which is in sync with master, check out the file [`hello-world.cc`](https://chromium.googlesource.com/v8/v8/+/master/samples/hello-world.cc). This is a very simple example and you’ll likely want to do more than just execute scripts as strings. [The advanced guide below](#advanced-guide) contains more information for V8 embedders.

## More example code

The following samples are provided as part of the source code download.

### [`process.cc`](https://github.com/v8/v8/blob/master/samples/process.cc)

This sample provides the code necessary to extend a hypothetical HTTP request processing application — which could be part of a web server, for example — so that it is scriptable. It takes a JavaScript script as an argument, which must provide a function called `Process`. The JavaScript `Process` function can be used to, for example, collect information such as how many hits each page served by the fictional web server gets.
{'fraction_non_alphanumeric': 0.07659680638722555, 'fraction_numerical': 0.015094810379241517, 'mean_word_length': 3.8353437876960195, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5350226', 'n_tokens_mistral': 2232, 'n_tokens_neox': 2108, 'n_words': 1123}