-
Notifications
You must be signed in to change notification settings - Fork 176
Google Summer of Code 2015 Starter Task
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.
First, let's get Doppio up and running.
If you have never programmed in TypeScript before, you should read our TypeScript Background Information article.
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!
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.
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!
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.
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
.
Your task is to:
- Find a native method that DoppioJVM does not implement.
- Add a test to
classes.tests
or change an existing test to make it test the missing native method. - Implement the native method so that DoppioJVM passes your new test.
- Open a pull request with the fix.
- Work with Doppio developers until your fix is ready to be merged.
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.
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:
- Compile a release version of DoppioJVM with
grunt release-cli
- 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!
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.
If you have any specific questions, feel free to email our mailing list or drop into IRC at #[email protected].