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 [CodingAgainstWorldPainter 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 [https://www.jidesoft.com/evaluation/ here], with user ID and password documented [https://www.jidesoft.com/forum/viewtopic.php?t=10 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= projectName= licenceKey= }}} '''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 [https://developer.apple.com/library/archive/samplecode/AppleJavaExtensions/Introduction/Intro.html 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: {{{#!xml jdk 9 PATH TO JAVA 9 JDK jdk 1.8 PATH TO JAVA 8 JDK }}} = 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 [DevelopingWorldPainter this] page.