Skip to content

Google Summer of Code 2015 Starter Task

Jump to bottom
John Vilk edited this page Mar 5, 2015 · 16 revisions

If you're potentially interested in working on Doppio for Google Summer of Code, then you're at the right wiki page!

  • If you were interested in our idea involving network sockets (or want to do something with DoppioJVM), read on.
  • If you were interested in the Python Interpreter, Ninia, then click here.

This document will walk you through setting up a development environment for Doppio, building Doppio and DoppioJVM, adding a native method to DoppioJVM, and opening up a pull request.

In this document, we will get you up and running with DoppioJVM, and will walk you through writing your first pull request.

Getting Started with Doppio

First, let's get Doppio up and running.

Background Information

If you have never programmed in TypeScript before, you should read our TypeScript Background Information article.

Prerequisites

Before doing anything, you should install the following items:

  • Node v0.12 (Note: The current bleeding-edge version of Doppio is incompatible with v0.10.)
    • We use Node to build Doppio/DoppioJVM. In addition, DoppioJVM can run on the command line using Node, which is useful during development.
  • Java JDK 8
  • Git

You'll also need to install the following Node modules globally:

npm install -g grunt-cli bower

We also recommend that you install the GitHub Atom editor, and install the atom-typescript and autocomplete plus plugins. This setup will give you intelligent autocomplete using TypeScript's type annotations, which is invaluable when working in a complex project like Doppio!

Fork the Repository

You'll be adding a new native method for DoppioJVM in this tutorial and contributing your changes back. You'll use a pull request to contribute your changes back, which means you'll need to fork our repository first.

Click here to fork the Doppio repository.

You'll make modifications to your fork, and then create a pull request from your fork to our main version of the repository to integrate your changes.

Build Doppio

Clone your fork, and switch to the new-objects branch. This is the current branch that we are developing in:

git clone https://github.com/yourusername/doppio
cd doppio
git checkout new-objects

Then, install the needed Node and Bower dependencies:

npm install
bower install

Finally, build Doppio/DoppioJVM (NOTE: This will download ~40MB of files!):

grunt release-cli

When complete, you can run doppio using ./doppio (or, if in Windows, doppio.bat):

$ ./doppio
Usage: node build/release-cli/console/runner.js [flags]  /path/to/classfile [args for main()]
    -classpath, -cp           JVM classpath, "path1:...:pathN"
    -D                        set a system property, "name[=value]"
    -jar                      add JAR to classpath and run its Main-Class (if found)
    -help, -h                 print this help message
    -X                        print help on non-standard options
    -enableassertions, -ea    enable debug assertions

You can write and run Java programs using Doppio, e.g.:

class Test {
  public static void main(String[] args) {
    System.out.println("Hello World!");
  }
}

$ javac Test.java
$ ./doppio Test
Hello World!

Starter Task: Write a Missing Native Method

Your starter task is to write a missing native method from the Java Class Library for DoppioJVM. First, we will introduce native methods. Then, we will detail the starter task.

Introduction to Native Methods

Native methods are normally written in C/C++, but in DoppioJVM they are written in TypeScript. These methods interact with native resources that cannot normally be accessed from within Java.

For example, when you write a Java program that reads a file, it will eventually need to call FileInputStream.open, which is marked native in the source code. DoppioJVM implements FileInputStream.open in src/natives/java_io.ts. (Note that DoppioJVM uses the JDK from Ubuntu, which sometimes renames methods; here, open was renamed to open0.)

Many native methods are much simpler than FileInputStream.open, such as java.lang.StrictMath.sin.

Task Details

Your task is to:

  1. Find a native method that DoppioJVM does not implement.
  2. Add a test to classes.tests or change an existing test to make it test the missing native method.
  3. Implement the native method so that DoppioJVM passes your new test.
  4. Open a pull request with the fix.
  5. Work with Doppio developers until your fix is ready to be merged.

Find an unimplemented native method

Unimplemented native methods are easy to identify, because we've added boilerplate code that throws an UnsatisfiedLinkError. For example, we haven't implemented StrictMath.hypot.. Search around for a native method that does this, and see if it's something you might be able to implement! Once you find a method, we recommend that you look at the source code for OpenJDK8, which often contains comments that describe what each native method does.

Write a test

Any *.java file in classes/test are automatically added to our test suite. You can run our test suite with grunt test.

If you want to run a single test, then:

  1. Compile a release version of DoppioJVM with grunt release-cli
  2. Run the test-runner on the test: node build/release-cli/console/test_runner.js classes/test/Annotations

Each test simply prints out information. Our test runner runs each test natively (using the java command) and in DoppioJVM (using doppio). So your test code should print out data that indicates whether or not your native method is working properly.

We recommend that you write a failing test first before implementing the native method!

Write the native method

Once you've written your tests, write the native method. If you've installed the GitHub Atom editor and the plugins we suggested, you'll get autocomplete suggestions while writing your code.

Questions?

If you have any specific questions, feel free to email our mailing list or drop into IRC at #plasma-umass@irc.freenode.net.

Clone this wiki locally