Skip to content

Latest commit

 

History

History
162 lines (120 loc) · 6.69 KB

v8.md

File metadata and controls

162 lines (120 loc) · 6.69 KB

Installing Google's V8 engine

PHP-JS depends on the Google V8 Javascript engine to parse and execute user supplied Javascripts. To install PHP-JS, you therefore first have to make sure that you have the V8 engine installed on your system.

The frustrating point here is that the V8 engine is updated all the time, and that it is mainly developed to be used inside Google's own Chrome browser. The guys at Google do not have good documentation online about how to use or install it, and it is also not advisable to rely on a precompiled V8 engine that is available in standard Linux repositories, as that version is probably outdated.

If you insist, you can follow the official Google tutorial to install V8, but we think it is too vague, so we created our own step by step walkthrough.

Download & install depot_tools

It is not possible to download the latest V8 source code from a website or FTP server. To get the source, you need to access Google's own GIT repository. Google created its own wrapper to access their repository, which is called "depot_tools". Before you can even download the V8 source code, you therefore first need to install this "depot_tools" package.

Depot_tools has its own tutorial, but again we provide our own here.

Using the terminal, navigate to the directory where you want to store depot_tools (your home directory is often good enough) and download the project using the following terminal command:

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git 

This creates a "depot_tools" directory that is full of utilities and commands that are needed to access Google repositories. The next thing that you have to do is include this "depot_tools" directory in your PATH variable, so that the instructions become accessible.

Below is the command to update your PATH variable. Do not exit the terminal, or your path variable will be reset to the default.

export PATH=`pwd`/depot_tools:"$PATH"

To test if depot_tools is correctly configured, type the following command:

gclient 

If installed correctly, a list of possible commands appears, and a .gclient directory is created in your home directory. (When I gave the "gclient" command I had the feeling that I did something wrong, because the output looks like an error message, but that is OK, you only have to give the command to ensure that this .gclient directory is created).

Download & build V8

Next up is downloading the actual V8 source code. Navigate to the folder where you want to store the V8 source folder (once again, your home directory is often good enough). The "depot_tools" that you have just installed provides the "fetch" command that can now be used for downloading V8:

fetch v8
cd v8

This might take some time. After downloading is complete, you will be put inside the v8 source directory. By default, the "fetch" command lets you use the most up-to-date (unstable!) version of the v8 engine. This might work for you, but often this version will simply segfault.

The versions that we have tested with are 5.x, which seem to work. Usually, the last known good release version works. However, because this is a moving target, we cannot say for sure that PHP-JS works with this version. Always strive to either use a 5.x-lkgr version, as the current branch head or version may not even work.

To select this version to be built, execute the following command:

git checkout 5.9-lkgr
gclient sync

This may take some time, as the google client needs to sync the build tools.

Before we can build, we need to generate the build files. Google uses the ninja build system, and their internal gn tool to generate build files for them. To generate these build files, execute the following command:

gn gen out.gn/library --args='is_debug=false is_component_build=true v8_enable_i18n_support=false'

This creates a subdirectory library in the out.gn folder containing the ninja build files and later the built targets. You might wonder about the command line arguments is_debug, is_component_build and v8_enable_i18n_support, because is_component_build and v8_enable_i18n_support are not in the official installation guide.

Well, the is_debug argument speaks for itself, we want to build it as a release version without debug symbols.

The is_compnent_build tells the compiler to build V8 as a shared library. PHP-JS is a PHP extension, and PHP loads all its extensions as shared object files, which can not be linked with static libraries. Therefore, we need V8 available as a shared library.

The v8_enable_i18n_support makes sure that the compiler will not build the i18n library that is included in the downloaded v8 source. The i18n library is already installed on your system, and we found out that it is better to use this system wide default i18n installation, instead of the version that is included in the v8 source. This prevents clashes between the system i18n library and the v8-provided i18n library (the shared object names are the same and a package update could wipe it, or - if you install it in some other directory - won't find it).

You can now build v8, using the following command:

ninja -C out.gn/library libv8.so

Install V8

After building v8, you have to install it on your server. If you have experience with compiling, you'd expect that some sort of install option could be used here, but the v8 Makefile uses the deprecated buildsystem and does not support the install option. You therefore will have to copy all the relevant v8 files to the appropriate directories on your system.

This can be done in two steps: first you copy the include files, and then the shared library files. The target of the copy operation is a matter of taste, you should either copy the header files to the system wide /usr/include directory, and the shared object files to /usr/lib, or - if you are more of a purist, and want to reserve the /usr directory for automatically installed packages - to the /usr/local/include and /usr/local/lib directories:

Approach 1:

sudo cp include/*.h /usr/include
sudo cp out.gn/library/*.so /usr/lib 

The alternative, more purist approach:

sudo cp include/*.h /usr/local/include
sudo cp out.gn/library/*.so /usr/local/lib 

That's it! You now have successfully installed Google's V8 JavaScript Engine. One more step is sometimes necessary to update the cache of available shared libraries:

sudo ldconfig

After you've done all that, please don't remove the v8 build folder. As there are some files of it that we'll need to actually build PHP-JS.