Instructions for building WorldPainter from source:

Prerequisites

WorldPainter is coded in Java (​https://www.oracle.com/java/index.html) and uses Maven (​https://maven.apache.org/) as the build system, so you must have a JDK installed (at least version 9), and Maven (at least version 3). These instructions assume that both are correctly installed and added to the PATH so that you can execute java and mvn commands from the command line, but if you are going to be using an IDE exclusively that is not necessary. The WorldPainter sources do not include any IDE metadata and are not dependent on any particular IDE for being built.

The source code is contained in a Git repository hosted on GitHub, so for checking out the source code you will need to have Git installed, although it is also possible to download the source code from GitHub as a zip file so this is not essential.

Knowledge and experience

WorldPainter is a large and complex program. You'll need a good understanding of Java (up to version 8) to be able to understand the code and work on it. If you want to work on the GUI you'll need at least a good working knowledge of Swing as well. Since the build system is Maven, you'll need some experience with that as well, including how to install artifacts in your local Maven repository, which you will need to do below.

Using WorldPainter in your own code

If you only want to write your own code making use of WorldPainter, rather than make changes to WorldPainter itself, then you don't need to build WorldPainter! The WorldPainter binaries, along with Javadoc and source code jars, are in Maven Central. For details, see this page.

Check out the source code

The WorldPainter source code is hosted on GitHub: ​https://github.com/Captain-Chaos/WorldPainter

Check it out from there, or fork it and then check out your own fork. The command for checking out the code anonymously from the command line is:

git clone https://github.com/Captain-Chaos/WorldPainter.git

Install missing dependencies

WorldPainter uses some dependencies which are not present in Maven Central, either because they are commercial products, or they are too old, or the creators aren't aware of Maven. Some of these dependencies (JPen; the NetBeans Dark Look and Feel) are hosted in a private Maven repo on www.worldpainter.net (see the pom.xml for the WorldPainter module), but some you will have to download and install manually:

TODO: JPen has native libraries, which are currently missing (meaning the tablet support won't actually work. This has yet to be incorporated in the build somehow.

JIDE Docking Framework

For the docks, WorldPainter uses the JIDE Docking Framework (​https://www.jidesoft.com/products/dock.htm), which is a commercial product. For development, you can download an evaluation version of the product ​here, with user ID and password documented ​here (note that you need to create a forum account to access the second link). The evaluation version will expire after two months, but you can keep downloading it again whenever it expires for two more months of development time.

Once you have your copy, either the evaluation version or the release version, install the jide-common.jar, jide-dock.jar and jide-plaf-jdk7.jar files in your local Maven repository by executing the following commands from inside the directory where you extracted them:

mvn install:install-file -DgroupId=com.jidesoft -DartifactId=jide-plaf-jdk7 -Dversion=3.7.13 -Dpackaging=jar -Dfile=jide-plaf-jdk7-3.7.13.jar
mvn install:install-file -DgroupId=com.jidesoft -DartifactId=jide-dock -Dversion=3.7.13 -Dpackaging=jar -Dfile=jide-dock-3.7.13.jar
mvn install:install-file -DgroupId=com.jidesoft -DartifactId=jide-common -Dversion=3.7.13 -Dpackaging=jar -Dfile=jide-common-3.7.13.jar

Note: if you downloaded a different version than 3.7.13 you must use the correct version numbers in these commands, and update the version numbers in the pom.xml of the WPGUI module!

If you ever want to distribute your own version of WorldPainter (although I respectfully request that you don't), you'll have to download the release version of the framework and get your own licence. JIDE Software give out open source licences, which are free. When using the release version of the framework, you have to create a file called src/main/resources/jide_licence.properties in the WPGUI module to fill in your actual licence details. It should have the following contents, filling in the actual values in place of the texts after the equals signs:

companyName=<company name>
projectName=<project name>
licenceKey=<licence key>

Note: make sure not to commit that file to any publicly visible source code repository, as your licence is associated with you and may not be used by other people!

Alternatively you could remove the JIDE Docking Framework from the code and replace it with some alternative docking framework. It's a lot of work, but doable.

Apple Java Extensions

To integrate with Mac OS X on Java 8, the Apple Java Extensions are needed. They are proprietary code which cannot be distributed by us so you will have to download it manually and install it in your local repo the same way as above. They can currently be found ​here. Download the .zip file and extract the .jar file from it. Install it in your local repo with the following command:

mvn install:install-file -DgroupId=com.apple -DartifactId=AppleJavaExtensions -Dversion=1.6 -Dpackaging=jar -Dfile=AppleJavaExtensions.jar

Of course if you are not interested in running the code on Apple Mac OS X, or running it on Java 8, you can also just remove this dependency and the code that uses it. WorldPainter will still run on Mac OS X on Java 8, but it will be less well integrated into the menus.

Set up Maven toolchains

WorldPainter uses the Maven toolchain framework (​https://maven.apache.org/guides/mini/guide-using-toolchains.html) to find the JDK's it needs. You need to follow the instructions on that page to configure two toolchains: one of type jdk and version 1.8 pointing to a Java 8 JDK, and one of type jdk and version 9 pointing to a Java 9 JDK. You can do this by placing a file called toolchains.xml in your ~/.m2 or $HOME\.m2 directory with the following contents:

<toolchains>
        <toolchain>
                <type>jdk</type>
                <provides>
                        <version>9</version>
                </provides>
                <configuration>
                        <jdkHome>PATH TO JAVA 9 JDK</jdkHome>
                </configuration>
        </toolchain>
        <toolchain>
                <type>jdk</type>
                <provides>
                        <version>1.8</version>
                </provides>
                <configuration>
                        <jdkHome>PATH TO JAVA 8 JDK</jdkHome>
                </configuration>
        </toolchain>
</toolchains>

Build WorldPainter

Once all dependencies are installed and the toolchains set up you can build WorldPainter from the command line or using your favourite IDE by executing the following command from inside the WorldPainter directory, or using your favourite IDE to build the WorldPainter module or invoke the install Maven goal on it. There are some rudimentary unit tests, but they take a while to run and don't contribute much, so I recommend skipping them:

mvn install -DskipTests=true

Repeat this whenever you change code in any of the modules below the WorldPainter directory. Or of course use your favourite IDE, preferably one with good Maven support, to build the project.

Run WorldPainter

Once it is built, you can run WorldPainter from the command line with the following command, executed from inside the WPGUI directory:

mvn exec:exec

You can also define a run configuration in your favourite IDE. The main class is org.pepsoft.worldpainter.Main.

Develop WorldPainter

For a few pointers, pitfalls and gotchas about developing WorldPainter, see this page.