compily/compily_lisp repository overview

⁠CompileBox

This gem allows you to set up your rails or other ruby-made app to run arbitrary code snippets securely in docker containers.

⁠Requirements

In order to use this gem, you must:

• Have docker installed and running on your computer
• your computer must be running a *nix-based OS
  • Ubuntu, macOS, Redhat, etc are all fine. This will not run on windows.

To install docker, please see https://www.docker.com/get-docker⁠

⁠Installation

Add this line to your application's Gemfile:

gem 'compile_box'

And then execute:

$ bundle

Or install it yourself as:

$ gem install compile_box

After installing the gem, initialize the docker containers with:

$ bundle exec CompileBox initialize

This will download the docker containers from docker hub. If for some reason you want to build them manually from the Dockerfiles, use the following command instead:

$ bundle exec CompileBox build

Note: Running the build command may take a while (up to 15 minutes) as it is initializing more than 12 individual docker containers. However, running this a second time will not take as long (although you shouldn't need to).

⁠Usage

Once the gem is installed and initialized, you can use it by adding the following to your ruby file:

Add the necessary require:

require 'compile_box'

Then, to compile/run a piece of code, use the compile() method:

CompileBox.compile(language, code, stdin: input, timeout_value: 10)

⁠compile() method parameters:

The compile() method takes the following parameters:

⁠Required Fields:

• language - (str) - A string identifying the language to compile as.
  • Builtin values you can use for this are: c#, c, c++, clojure, java, go, javascript, php, python, ruby, scala, vb.net bash, objective-c, mysql, perl
• code - (str) - The string containing the code you want to compile/run

⁠Optional Fields:

• stdin - (str) - The string containing what you want the program you are running to use as standard input (e.g. Java's System.in will pull input from this file)
• timeout_value - (int) The number of seconds after which the the program will timeout and kill itself. (The default is 10.)
• tmp_root - (str) - This is the string containing the full path to the tmp folder that you want to use for temporarily storing running docker containers. If you are running this on Rails, you should supply the value File.join(Rails.root, 'tmp'). If no value is supplied, it will create a tmp directory in whatever working directory this method is called from.
• memory - (str) - The maximum amount of memory the program is allowed to take up. This should be in the form "[int][unit]" where [int] is the number of units, and [unit] is one of M,G,etc (megabytes, gigabytes, etc). The minimum allowed value is 4M, and the default value is 10M.
• ext_langs - (hash) - This is a hash containing all the relevant information necessary to the gem to add a new language. Adding new languages will be covered more in depth in its own section, but for the purpose of this field, the format of the hash should be as follows (The following is an example of adding the languages ruby and objective-c):

{ "ruby" => {
    compiler_name: 'ruby',
    file_name: 'file.rb',
    output_command: '',
    language_name: 'Ruby',
    extra_arguments: '',
    container: 'compily_ruby'
  },
  "objective-c" => {
    compiler_name: 'gcc',
    file_name: 'file.m',
    output_command: ' /usercode/a.out',
    language_name: 'Objective-C',
    extra_arguments: "\' -o /usercode/a.out -I/usr/include/GNUstep -L/usr/lib/GNUstep -lobjc -lgnustep-base -Wall -fconstant-string-class=NSConstantString\'" ,
    container: 'compily_clike'
  } 
}

⁠Adding new Languages

TODO: Add documentation for how to add new languages including setting up docker containers

⁠Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org⁠.

⁠Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ephraimrothschild/compile_box⁠.