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.

• Download the polyglot-code-explorer.zip file from the latest release at https://github.com/kornysietsma/polyglot-code-explorer/releases
• Unzip it somewhere
• Copy your JSON file produced earlier over the data/default.json file in the unzipped site
• Load the site in a static web server

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.

Copy
$ 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:

Copy
polyglot_code_scanner --name qgis -c ~/samples/QGIS -o ~/data/qgis.json
polyglot-code-offline-layout -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

Viewing source code

This is a recent feature, it is only in explorer 0.4.0 and above.

You can run the Simple Code Server to serve up the original source code that you scanned, and then view the code for a file in the Explorer.

Note this breaks the simple code -> JSON -> view model a bit - you need all the original source code available to view code this way, rather than just the summary JSON file. But it's quite convenient for rapidly previewing code, or when looking at private code repositories that might not be on a well known github or other URL.

See the notes in the Simple Code Server description page for how to use this. (I need to update these docs to make this all a bit clearer!)

See also

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.