docs/development/scheduler.md

Developing the Aurora Scheduler
===============================

The Aurora scheduler is written in Java code and built with [Gradle](http://gradle.org).


Prerequisite
============

When using Apache Aurora checked out from the source repository or the binary
distribution, the Gradle wrapper and JavaScript dependencies are provided.
However, you need to manually install them when using the source release
downloads:

1. Install Gradle following the instructions on the [Gradle web site](http://gradle.org)
2. From the root directory of the Apache Aurora project generate the Gradle
wrapper by running:

    gradle wrapper


Getting Started
===============

You will need Java 8 installed and on your `PATH` or unzipped somewhere with `JAVA_HOME` set. Then

    ./gradlew tasks

will bootstrap the build system and show available tasks. This can take a while the first time you
run it but subsequent runs will be much faster due to cached artifacts.

Running the Tests
-----------------
Aurora has a comprehensive unit test suite. To run the tests use

    ./gradlew build

Gradle will only re-run tests when dependencies of them have changed. To force a re-run of all
tests use

    ./gradlew clean build

Running the build with code quality checks
------------------------------------------
To speed up development iteration, the plain gradle commands will not run static analysis tools.
However, you should run these before posting a review diff, and **always** run this before pushing a
commit to origin/master.

    ./gradlew build -Pq

Running integration tests
-------------------------
To run the same tests that are run in the Apache Aurora continuous integration
environment:

    ./build-support/jenkins/build.sh

In addition, there is an end-to-end test that runs a suite of aurora commands
using a virtual cluster:

    ./src/test/sh/org/apache/aurora/e2e/test_end_to_end.sh

Creating a bundle for deployment
--------------------------------
Gradle can create a zip file containing Aurora, all of its dependencies, and a launch script with

    ./gradlew distZip

or a tar file containing the same files with

    ./gradlew distTar

The output file will be written to `dist/distributions/aurora-scheduler.zip` or
`dist/distributions/aurora-scheduler.tar`.



Developing Aurora Java code
===========================

Setting up an IDE
-----------------
Gradle can generate project files for your IDE. To generate an IntelliJ IDEA project run

    ./gradlew idea

and import the generated `aurora.ipr` file.

Adding or Upgrading a Dependency
--------------------------------
New dependencies can be added from Maven central by adding a `compile` dependency to `build.gradle`.
For example, to add a dependency on `com.example`'s `example-lib` 1.0 add this block:

    compile 'com.example:example-lib:1.0'

NOTE: Anyone thinking about adding a new dependency should first familiarize themselves with the
Apache Foundation's third-party licensing
[policy](http://www.apache.org/legal/resolved.html#category-x).



Developing the Aurora Build System
==================================

Bootstrapping Gradle
--------------------
The following files were autogenerated by `gradle wrapper` using gradle's
[Wrapper](http://www.gradle.org/docs/current/dsl/org.gradle.api.tasks.wrapper.Wrapper.html) plugin and
should not be modified directly:

    ./gradlew
    ./gradlew.bat
    ./gradle/wrapper/gradle-wrapper.jar
    ./gradle/wrapper/gradle-wrapper.properties

To upgrade Gradle unpack the new version somewhere, run `/path/to/new/gradle wrapper` in the
repository root and commit the changed files.