Jerkar - Getting Started
Author : Jérôme Angibaud
Version : 0.7.0.RC1

1. Lexical
2. Install Jerkar
3. Use Jerkar with command line
3.1 Create a project
3.2 Build your project
3.3 Extra function
3.4 Explore functions and options provided out-of-thebox
4. Use with intellij
4.1 setup intellij
4.2 setup iml file
4.3 run/debug within Intellij
5. Use with Eclipse
5.1 Setup Eclipse
5.2 setup
5.3 run/debug within Eclipse

1. Lexical

These terms are used in this document, this short lexical disambiguates their meanings.

[JERKAR HOME] : refers to the folder where Jerkar is intalled. You should find jerkar.bat and jerkar shell files directly under this folder.

[JERKAR USER HOME] : refers to the folder where Jerkar stores caches, binary repository and global user configuration.

[USER HOME] : User Home within the meaning of Windows or Unix.

2. Install Jerkar

  1. unzip the distribution archive to the directory you want to install Jerkar ([JERKAR HOME])
  2. make sure that either a valid JDK is on your PATH environment variable or that a JAVA_HOME variable is pointing on
  3. add [JERKAR HOME] to your PATH environment variable
  4. execute jerkar -LH help in the command line. You should get an output starting by :
 _______           _
(_______)         | |
     _ _____  ____| |  _ _____  ____
 _  | | ___ |/ ___) |_/ |____ |/ ___)
| |_| | ____| |   |  _ (/ ___ | |
 \___/|_____)_|   |_| \_)_____|_|
                                     The 100% Java build tool.
Java Home : C:\Program Files (x86)\Java\jdk1.8.0_121\jre
Java Version : 1.8.0_121, Oracle Corporation
Jerkar Home : C:\software\jerkar                             
Jerkar User Home : C:\users\djeang\.jerkar
...

Note : -LH option stands for "Log Headers". In this mode, Jerkar displays meta-information about the running build.

3. Use Jerkar with command line

3.1 Create a project

  1. Create a new directory named 'mygroup.myproject' as the root of your project.
  2. Execute jerkar scaffold#run java# under this directory. This will generate a project skeleton with the following build class at [PROJECT DIR]/build/def/Build.java
import org.jerkar.api.depmanagement.JkDependencySet;
import org.jerkar.api.java.project.JkJavaProject;
import org.jerkar.tool.JkInit;
import org.jerkar.tool.JkRun;
import org.jerkar.tool.builtins.java.JkPluginJava;

import static org.jerkar.api.depmanagement.JkJavaDepScopes.*;

class Build extends JkRun {

    final JkPluginJava javaPlugin = getPlugin(JkPluginJava.class);

    /*
     * Configures plugins to be bound to this run class. When this method is called, option
     * fields have already been injected from command line.
     */
    @Override
    protected void setup() {
        JkJavaProject project = javaPlugin.getProject();
        project.addDependencies(dependencies());
    }

    private JkDependencySet dependencies() {  // Example of dependencies.
        return JkDependencySet.of()
                .and("com.google.guava:guava:21.0")
                .and("junit:junit:4.11", TEST);
    }

    public static void main(String[] args) {
        JkInit.instanceOf(Build.class, args).javaPlugin.clean().pack();
    }
    
}

Explanation : scaffold#run invokes 'run' method on the 'scaffold' plugin. java# forces the java plugin to be loaded. When loaded, 'java' plugin has the effect to instruct scaffold plugin extra actions for generating a Java project.

By default the project layout mimics the Maven one so sources are supposed to lie in src/main/java.

Execute jerkar java#info to see an abstract of the project setup.

3.2 Build your project

  1. Edit the Build.java source file above. For example, you can add compile dependencies.
  2. Just execute jerkar clean java#pack under the project base directory. This will compile, run test and package your project in a jar file. You can also lauch the main method from your IDE.

3.3 Extra function

If you want to create javadoc, jar sources and jar tests or checksums : just execute jerkar clean java#pack -java#pack.tests -java#pack.sources -java#pack.checksums=sha-256.

Explanation '-' prefix means that you want to set an option value. For example -java#pack.sources means that JkPluginJava.pack.sources will be injected the 'true' value.

You can also set it by default in the build class constructor :

    protected Build() {
        javaPlugin.pack.javadoc = true;
        javaPlugin.pack.sources = true;
        javaPlugin.pack.tests = true;
        javaPlugin.pack.checksums = "sha-256";
    }

3.4 Explore functions and options provided out-of-thebox

Execute jerkar help to display all what you can do from the command line for the current project. As told on the help screen, you can execute jerkar aGivenPluginName#help to display help on a specific plugin. The list of available plugins on the Jerkar classpath is displayed in help screen.

4. Use with intellij

4.1 setup intellij

As for Eclipse, you must declare the two path variables (go settings -> Apparence & behavior -> Path Variables)

4.2 setup iml file

Execute jerkar intellij#generateIml from project root folder to generate an iml file according the Build.java file.

4.3 run/debug within Intellij

You can go two ways :

Important : Make sure you choose $MODULE_DIR$ as the working directory for the Run/Debug configuration.

5. Use with Eclipse

5.1 Setup Eclipse

To use Jerkar within Eclipse, you just have to set 2 classpath variables in Eclipse.

  1. Open the Eclipse preference window : Window -> Preferences
  2. Navigate to the classpath variable panel : Java -> Build Path -> Classpath Variables
  3. Add these 2 variables :

Note : By default [Jerkar User Home] point to [User Home]/.jerkar but can be overridden by defining the environment variable JERKAR_USER_HOME.

If you have any problem to figure out the last value, just execute jerkar help -LH from anywhere and it will start logging the relevant information :

 _______    	   _
(_______)         | |                
     _ _____  ____| |  _ _____  ____ 
 _  | | ___ |/ ___) |_/ |____ |/ ___)
| |_| | ____| |   |  _ (/ ___ | |    
 \___/|_____)_|   |_| \_)_____|_|
                                     The 100% Java build tool.

Java Home : C:\UserTemp\I19451\software\jdk1.6.0_24\jre
Java Version : 1.6.0_24, Sun Microsystems Inc.
Jerkar Home : C:\software\jerkar                               <-- This is the value for JERKAR_HOME
Jerkar User Home : C:\users\djeang\.jerkar
Jerkar Repository Cache : C:\users\djeang\.jerkar\cache\repo   <-- This is the value for JERKAR_REPO
...

5.2 setup .classpath file

Execute jerkar eclipse#generateFiles from project root folder to generate a .classpath file according the Build.java file.

5.3 run/debug within Eclipse

You can go two ways :