Table of Contents

Build Workcraft from sources

Getting source

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.

Building

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

Running

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

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

Code style

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 integration

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.

Check that a correct version of Java is selected in File→Project Structure… dialog under Project→Project SDK section.

Eclipse integration

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.

Check that a correct version of Java is selected in Windows→Preferences dialog under Java→Compiler section.

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

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:

Common issues

Reporting bugs

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