Syntactic grep for JavaScript.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Currently, no binaries are available for use and jsgrep must be built from source.

Building from source


  • CMake (2.8+)
  • V8 source
  • Node.js (v7+)
  • xxd

Building V8

Refer to

Run gn args and paste the following config:

is_debug = false
enable_nacl = false
enable_nacl_nonsfi = false
exclude_unwind_tables = true
icu_use_data_file = false
is_component_build = false
is_official_build = true
msan_track_origins = 0
symbol_level = 0
use_udev = false
v8_enable_i18n_support = false
v8_use_external_startup_data = false
v8_static_library = true

To see the list of available options, run:

gn args --list

To compile, run ninja:

ninja -C v8

Building jsgrep-ql

The JavaScript runtime package is needed by the jsgrep binary (the C++ part) in order to evaluate queries. The following snippet will pre-compile the JavaScript into a single .js file which is then converted to a binary object and will be embedded into the jsgrep binary by CMake.

(cd packages/jsgrep-ql; npm install && npm run build)

Building jsgrep

The environment variable V8_DIR must be set to the source directory of V8 which you built.

You'll need to run cmake to generate the makefile then run make.

mkdir build
(cd build; cmake .. && make -j5)

If you want to customize the build parameters, run ccmake .. instead of cmake...


jsgrep C++ tests

jsgrep tests can be run with the binary found at build/jsgrep-tests. You must turn on JSGREP_BUILD_TESTS in cmake in order to generate the target.

jsgrep-ql JavaScript tests

jsgrep-ql tests can be run with npm:

(cd packages/jsgrep-ql && npm test)

During development, you can run the tests interactively in watch mode by supplying -w and it's likely you'll want to use the dot reporter:

(cd packages/jsgrep-ql && npm test -- -w --reporter dot)


You'll need a bunch of terminal sessions for this:

  1. jsgrep-ql grammar build watcher:

The following will watch any changes you make to jsgrep-ql/grammar/jsgrep- and run nearleyc to generate the compiled grammar.

(cd packages/jsgrep-ql && npm run build-grammar:watch)

The output will be found at jsgrep-ql/src/grammar.js and it is required in order to build the JS bundle.

  1. jsgrep-ql bundle build watcher:

The following command will watch any changes to the evaluation source files jsgrep-ql/src/**/*.js and re-compile the bundle that will be used by the C++ backend.

(cd packages/jsgrep-ql && npm run build-bundle:watch)

The output will be found under jsgrep-ql/dist/jsgrep-ql.js.

  1. jsgrep build:

Now that you have the JS bundle ready (grammar embedded), you can compile the C++ backend:

(cd build && cmake .. && make -j10)

The output will be found at build/jsgrep.

  1. [OPTIONAL] jsgrep tests

If you want to run the C++ tests too, tell cmake to generate that target:

(cd build && cmake -DJSGREP_BUILD_TESTS=true .. && make -j10)

The binary will be found at build/jsgrep-tests.

  1. [OPTIONAL] jsgrep-ql tests:

If you want to run the JavaScript engine tests, the following snippet will re- run the tests anytime the source files change:

(cd packages/jsgrep-ql; npm run test:watch)


The MIT license. Copyright 2017 Ahmad Amireh See COPYING.

Libraries linked to by jsgrep and their respective licenses: