How to Add a Language to Beaker

Beaker supports many languages and has a plugin API so you can add your own. The current procedure and API have serious weaknesses and we plan on making major changes for version 2.0, though hopefully some problems can be fixed before then.

The main requirement is that you are able to wrap a HTTP server around your language, so that Beaker can send code to it for evaluation.

For example the F# plugin was implemented by a 3rd party and is distributed independently of Beaker.

This guide does not assume you are able to compile Beaker, you just need a working downloaded application. You will probably need to compile/develop in your own language. You do need to edit and add files to Beaker though. On Linux and Windows, Beaker is distributed as a zip file, and so its contents are easily accessible. On Mac, if you have copied it to your /Applications folder, then you can access the contents at /Applications/Beaker.app/Contents/Resources/dist

If you can compile Beaker, then this guide is good for IPython-style backends. The API spec has related information, but is just a start.

Copy an existing language

Use an existing langauge as a starting point. If there is already an IPython backend for your language then use our IPython plugin. Otherwise, use Groovy. The existing plugins are located in the plugin/ directory. The main components of each plugin are a javascript file for the client, and a python script to start the HTTP server. Some of the languages also have a runtime to support things like autotranslation but you can get started without that. So choose a language to start with, duplicate and rename the directory that contains it and you should have a file structure looking similar to the following, where newLang is the name for our added language:

plugin/
    clojure/
    cpp/
    newLang/
    ...

Adding a new language

• After the above step edit the files in the following directories so that your language is included in the build process: plugin/settings.gradle, core/config/builds/dev/settings.gradle.
• Edit the following files by updating the path to the newLang/ directory and to the newLangPlugin file where relevant : plugin/newLang/src/dist/newLang.js , plugin/newLang/build.gradle , plugin/newLang/src/dist/newLangPlugin.
• Check the permissions of the newLangPlugin file by executing the ls -l command in the directory containing said file. If the execute permision is not set, then execute this command chmod +x newLangPlugin.
• Edit core/src/main/web/plugin/init/addevalplugins.js and add your language to the list, picking colors and a short name for your language's badge.
• Install Docker according their guide here.
• Build your new image with the name beaker by executing docker build -t beaker . (don’t forget the . period).This will take around 10 minutes for the first build.
• After the build has finished, execute docker run -p "8800:8800" beaker.
• Copy the generated password and go to https://localhost:8800.
• Enter the password and you should be able to run Beaker. Add your language to a notebook via the Language manager (called the Plugin manager in old versions of Beaker), though to actually execute code it will still use the language from which you copied it, so far you have just cloned an existing language.
• Clean up after yourself by executing the following sequence of commands:
  • docker ps (processes list)
  • docker rm -f <ps-id> (removes process with id )
  • docker images (images list)
  • docker rmi -f <img-id> (removes image with id )

Modify

In the newLang/ directory change the contents for your new language. Make the python script start your HTTP server, and match up the REST calls from the client to your server. That's it!

Let us know

We are very interested in hearing about your work with Beaker, as well as any problems or questions you have.