polyglot-tools-docs

How to run the Polyglot Code Explorer

The explorer requires a data file to run - there is a sample one checked into the codebase, but in order to do anything useful you'll want to build your own.

This is currently a two stage process:

  • Run the polyglot-code-scanner with one or more git repositories - this will produce a quite large JSON file containing the code metrics
  • Run the polyglot-code-offline-layout with the output of the scanner - this will add layout information to the JSON file

Then you can run the explorer.

You have two options for running the explorer:

  1. Download a static release from github and serve it as a static web app
  2. Run the exporer from node.js

To run the explorer from a binary release

The Explorer is not an executable file - it's a zip file containing the HTML, CSS and JavaScript files needed to run the site.

There are quite a ways to run a static web server locally - if you have Python installed, running such a web server is a one-line coomand - there are more detailed instructions here or there's a big list of similar servers in other languages here - I'll use Python 3 below.

$ unzip polyglot-code-explorer.zip
Archive: polyglot-code-explorer.zip
creating: polyglot-code-explorer/
...
$ cd polyglot-code-explorer
$ cp ../my_data_file.json data/default.json
$ python3 -m http.server
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)

Then open a browser to http://0.0.0.0:8000 to start exploring!

To run the explorer in node.js

  • Clone the repository at https://github.com/kornysietsma/polyglot-code-explorer
  • Install yarn (or you can use npm, but this is set up using yarn as that's what the react starter uses)
  • Install yarn dependencies yarn install
  • copy your JSON data file into the public/data directory in the checked out code
  • set the environment variable REACT_APP_EXPLORER_DATA to the name of your JSON file (excluding the extension). (react requires variables to start with REACT_APP for your app to see them!)
  • run yarn start and it will run the explorer in a new browser window.
  • you can set BROWSER=none to stop it opening a new window every time.

For a full example, these are the commands I run typically to process and view the QGIS codebase:

# in scanner directory
polyglot_code_scanner -c ~/samples/QGIS > ~/data/qgis.json
# in layout directory
node layout.js -i ~/data/qgis.json -o ~/data/qgis-voronoi.json
# in explorer directory
cp ~/data/qgis-voronoi.json ./public/data/qgis.json
REACT_APP_EXPLORER_DATA=qgis BROWSER=none yarn start

See the polyglot-code-scanner and polyglot-code-offline-layout howto guides for more on the parameters these apps take.

See the Explorer user interface page for more on how to use the explorer once it is running.

Edit this page on GitHub