====== Build Workcraft from sources ======

===== Getting source =====

Workcraft project uses [[https://git-scm.com/ | Git]] as a version control system and hosts its sources on [[https://github.com/workcraft/ | GitHub]].

Get Workcraft source code ([[https://github.com/workcraft/workcraft/ | workcraft]] repo) and submodules for its backend tools ([[https://github.com/workcraft/workcraft-dist-template|workcraft-dist-template]] repo) and documentation ([[https://github.com/workcraft/workcraft-doc|workcraft-doc]] repo) :

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

Use the conventional Git workflow to contribute to the development of Workcraft,  as describe in numerous [[https://www.atlassian.com/git/tutorials/|tutorials]].


===== Building =====

Workcraft requires Java JDK 17 or newer for a successful build and is assembled via [[https://gradle.org/ |Gradle]]. It is tested with both [[https://adoptium.net|Open JDK]] and
[[https://www.oracle.com/technetwork/java/javase/downloads/index.html|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:
<code>
./gradlew assemble
</code>


===== Running =====

You can run Workcraft directly after building it:
<code>
./gradlew run
</code>

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: <code>
ln -s dist/template/linux/tools
</code>


===== Testing =====

Testing includes a collection of [[https://junit.org/|JUnit]] tests and also [[https://github.com/checkstyle/checkstyle|checkstyle]] and [[https://pmd.github.io/|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:
<code>
./gradlew check
</code>


===== Code style =====

The code style is configured via ''config/checkstyle/checkstyle.xml'' and ''config/pmd/rules.xml''. The style is similar to [[https://google.github.io/styleguide/javaguide.html | 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:
<code java>
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<>();
    }
}
</code>


===== InteliJ IDEA integration ====

[[https://www.jetbrains.com/idea/|InteliJ IDEA]] is the preferred development environment for Workcraft. Generate IDEA project and Workcraft application runner from Gradle config files as follows:<code>
./gradlew idea
</code>

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

<WRAP important center round 90%>
Check that a correct version of Java is selected in //File->Project Structure...// dialog under //Project->Project SDK// section.
</WRAP>


===== Eclipse integration =====

[[https://www.eclipse.org/ | Eclipse IDE]] is a convenient environment for
developing and debugging Workcraft. Generate Eclipse projects from Gradle config files:<code>
./gradlew eclipse
</code>

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.

<WRAP important center round 90%>
Check that a correct version of Java is selected in //Windows->Preferences// dialog under //Java->Compiler// section.
</WRAP>

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.


===== Common issues =====

  * If a wrong version of Java is used by Gradle, check what JRE/JDK installations are available and which one is actually picked: <code>
./gradlew javaToolchains
</code>

  * If Gradle complains about a missing ''JAVA_HOME'' environment variable even though it is set properly, the following may help in Debian-like systems: <code>
sudo ln -s /usr/lib/jvm/your-jdk /usr/lib/jvm/default-java
</code>

  * 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

===== Reporting bugs =====

If you happen to find a bug in Workcraft (which is quite likely), please help the developers by filing a [[https://github.com/workcraft/workcraft/issues/new | bug report]].