Build Workcraft from sources

Workcraft project uses Git as a version control system and hosts its sources on GitHub.

Get Workcraft source code ( workcraft repo) and submodules for its backend tools (workcraft-dist-template repo) and documentation (workcraft-doc repo) :

git clone https://github.com/workcraft/workcraft.git
cd workcraft
git submodule update --init --remote

Use the conventional Git workflow to contribute to the development of Workcraft, as describe in numerous tutorials.

Workcraft requires Java JDK 17 or newer for a successful build and is assembled via Gradle. It is tested with both Open JDK and Oracle JDK.

These instructions use gradlew, a wrapper that downloads and runs a relatively new version of gradle. Alternatively a pre-installed version can be used.

Use the assemble task to build the core and all the plugins:

./gradlew assemble

You can run Workcraft directly after building it:

./gradlew run

Note that Workcraft relies on backend tools for some of its functionality and expects them in tools directory by default. Therefore create a symbolic link pointing to the location of the backend tools for your platform. E.g. for Linux:

ln -s dist/template/linux/tools

Testing includes a collection of JUnit tests and also checkstyle and PMD checks to enforce a sane code style throughout the Java codebase (see below). The tests should be run before proposing your changes for the merge into the master as follows:

./gradlew check

The code style is configured via config/checkstyle/checkstyle.xml and config/pmd/rules.xml. The style is similar to Google's Java style, but it is more lax and indents with four spaces. To give a quick overview of it, here is a code snippet showing the basics:

class Foo {
 
    public static final int CONSTANT = 1;
 
    private boolean myField = true;
 
    public static void barMethod(int someInt,
            String someString) {
        if (someInt > 3 || someInt < 0) {
            someFunc(someInt);
        } else {
            someString = "value is " + someInt;
        }
        List<String> myList = new ArrayList<>();
    }
}

InteliJ IDEA is the preferred development environment for Workcraft. Generate IDEA project and Workcraft application runner from Gradle config files as follows:

./gradlew idea

Now just start IDEA and open workcraft.ipr project file.

Eclipse IDE is a convenient environment for developing and debugging Workcraft. Generate Eclipse projects from Gradle config files:

./gradlew eclipse

Start Eclipse and select workcraft as the current Workspace directory. Import all Workcraft projects via the File→Import… and selecting the General→Existing Projects into Workspace item.

To run Workcraft from within Eclipse create a Java Application runner with the following configuration:

• Name: Workcraft
• Project: WorkcraftRunner
• Main class: org.workcraft.Console
• Working directory (at Arguments tab): ${workspace_loc}

If you decide to run JUnit tests from within Eclipse, e.g. for interactive debugging, then you will need to change the Working directory of the test run configuration to ${workspace_loc}.

The default code style of Eclipse uses tabs for indentation. This contradicts to the checkstyle that requires 4 spaces for each level of indentation. Therefore Eclipse settings need to be modified as follows:

• Select Windows→Preferences menu and go to the Java→Code Style→Formatter section.
• Edit the indentation policy of Eclipse [built-in] profile by changing its tab policy to Spaces only.
• Save the modified profile under a new name and select it as the active profile.

• If a wrong version of Java is used by Gradle, check what JRE/JDK installations are available and which one is actually picked:

  ./gradlew javaToolchains

• If Gradle complains about a missing JAVA_HOME environment variable even though it is set properly, the following may help in Debian-like systems:

  sudo ln -s /usr/lib/jvm/your-jdk /usr/lib/jvm/default-java

• If you hit disk quota for your home directory due to Gradle pulling too much dependencies, point GRADLE_USER_HOME environment variable to a different location with more disk space

If you happen to find a bug in Workcraft (which is quite likely), please help the developers by filing a bug report.