Sublime Text V8 Engine Build System

Published Apr 14, 2018Last updated Apr 24, 2018
Sublime Text V8 Engine Build System

I am always wanting to play with new features or test my learnings of various ECMA Specification features. You can play with upcoming features using transpilers such as Babel but I wanted a way to very quickly test features directly against the V8 Javascript engine and being an avid user of Sublime Text I wanted to set it up to be able to use the V8 Javascript engine as a build tool.

If your asking what is the V8 Javascript Engine, in short it is what executes your Javascript in the Chrome Browser but then this is from Google themselves;

"V8 is Google’s open source high-performance JavaScript engine, written in C++ and used in Google Chrome, the open source browser from Google, and in Node.js, among others. It implements ECMAScript as specified in ECMA-262, and runs on Windows 7 or later, macOS 10.5+, and Linux systems that use IA-32, ARM, or MIPS processors. V8 can run standalone, or can be embedded into any C++ application. More information can be found on V8's public wiki."

I actually use an NPM project on github for all my workings, tests and understanding of capabilities in each context. I have a project structered like you see below;

ECMA Workings Project

The instructions below will show how to install the engine via Homebrew and then add the Sublime Build for the default shipped harmony V8 release and then with that build variants for different levels of features in the engine.

Note: Unless stated all of the following has been completed in OSX, I can not verify all this will work on an other operating systems.

Install V8

We are going to use Homebrew to install the V8 Formula. This is done simply by running the following command at the command prompt in the terminal of your choice.

brew install v8

Note: If you are testing bleeding edge release it is recommended that you ensure you keep this formula up to date.

To check this is installed we then run the command.

v8 --help

This will display all the possible options for the v8 command line tool.

We are actually going to use D8 (Debug8) which is V8's own minimalist debug shell and is installed with V8.

You can check that brew has installed this by running;

d8 --help

Again this will list all the options available for the d8 tool. Amongst the list at the top you will notice some of those we will be using to enable our sublime build to use variants of the feature sets for V8 engine.

This article will not go heavily into the capabilities of the D8 tool but it is very useful for much more than we will set up here, ie profiling, examining the garbage collection and a lot more.

Below are some resources for you to follow up on for the usage of D8;

Official V8 D8 Docs

A great article by Kevin Cennis

Something Kevin Cennis mentions in his article is the availability of use of some of the D8's native methods that you can use in your code when testing / profiling. Here is a great wrapper for those natives.

Add the Build to Sublime

Know I will get to the Sublime part.

I am not sure how much you know about the extensibility of Sublime, but this is one of the reasons I love it. For any file you have open you can choose to build it with the build tool of your choice adding new ones to sublime to run any command on your opertaing system, one that works for that code obviously, .

In Sublime if you go through the tools menu to the build tools;

Tools > Build System

You will see all the build systems that are currently avaiable to sublime either by default or extension.
Mine looks like the following.

!(Sublime Build Systems)[https://s3-eu-west-1.amazonaws.com/skindc-gist/images/SublimeBuildSystems.png]

You will see the V8 Highlihted at the bottom of the list.

Ok, to create a new Build System we click on 'New Build System...' below the last item on that list just seen.
This will bring up a new build system file in the Sublime Editor and will have contents something like;

{
  "shell_cmd": "make"
}

We are now going to replace that content with the following;

{
  "cmd": ["/usr/local/bin/d8", "$file"],
  "osx": {
    "cmd": ["/usr/local/bin/d8", "$file"]  
  },
  "file_patterns": "*.js",
  "variants": [
    {
      "name": "V8 Complete",
      "osx": ["/usr/local/bin/d8", "--harmony", "$file"]
    },
    {
      "name": "V8 Stage",
      "osx": ["/usr/local/bin/d8", "--harmony --es_staging", "$file"] 
    },
    {
      "name": "V8 Experimental",
      "osx": ["/usr/local/bin/d8", "--harmony --es_staging --experimental_extras", "$file"] 
    }
  ]
}

Ok before I explain we need to save the file, and I would suggest V8.sublime-build for the filename. What ever precedes '.sublime-build' is used for the menu item. You must leave '.sublime-build' in place.

Note: Sublime should by default open up the save dialogue pointing at the right location on your filesystem for this and other user extensions but to check, for OSX it should be;
/Users/{user}/Library/Application Support/Sublime Text 3/Packages/User/
where {user} is your account and presuming your using Sublime Text 3.

Ok once you saved the file you should be able to see the new 'V8' Build in the menu we looked at early.

Now I will explain what we have set up, this will be directly about this configuration for using the d8 tool, if you want to read all the possible configurations for a custom Sublime build tool you can see it here on Sublime's official Build Tool Docs.

At the top of our setting file we have our default / root build configuration, and you can see the command here is targeting the full path to the d8 binary with the file argument. Note here that the file argument is the file you currently have open and are focused on in the Sublime application.

In the settings file we also specify file_patterns and this tells sublime that this Build is only intended for files with a name that matches thh glob '*.js' ( ie Javascript files ).

Now we declare some variants. The variants here are extensions to the root command specified at the top of the settings file and so we use them to add some arguments to the d8 command execution.

You can see the arguments that are applied and these would have been seen in the list of possible arguments when we run the command;

d8 --help

but in short the ones we specify are;

--experimental_extras (enable code compiled in via v8_experimental_extra_library_files)
      type: bool  default: false
--es_staging (enable test-worthy harmony features (for internal use only))
      type: bool  default: false
--harmony (enable all completed harmony features)
      type: bool  default: false
--harmony_shipping (enable all shipped harmony features)
      type: bool  default: true

They should be self explanatory. But what I will explain is that you can see --harmony_shipping is by default true, so our root / default execution of this build will be to that release. Then we use the variants to enable the other fetaure sets.

These particular options to the command enable whole sets of features, but if you look at the list of options you can enable individual experimental features if you wish.

Ok, now with a javascript file open, select the 'V8' build from the menu then execute the build by going to 'Build' in the menu or hitting ⌘B (on OSX). The this run our new build tool. Whoala.

You maybe asking what about the variants, ok to see the list of variants to execute you can either go to 'Build With...' in the menu or by hitting ⇧⌘B (on OSX). This will bring up a new menu at the top of the Sublime view something like the following;

Sublime Build System Variants

and there are your variants to build against.

Note: Please note that this is the raw V8 engine and so remember things that the browsers or other environments expose will not be exposed when building directly with D8. This is mostly just for quick tests for feature sets or profiling if you want to get into it. So console will not be availble but D8 does give us the print function will which print to your output pane just the same.

Please look at the Official D8 Docs and explore the result of the D8 help command as there is a lot more you can do.

Enjoy.

Discover and read more posts from Gary Law
get started