Compiling from Source

KoLmafia has migrated to the GitHub repository and we are retooling for GIT and gradle builds.

The Windows section of this page is currently out of date. The Linux and macOS ones have been updated.

The good news is that the IDE setup is a lot easier. The bad news is you'll need to take some steps to build anything. In addition, we are discussing changing to a newer required JDK, so even these instructions will not be permanent.

To contribute to the Mafia project, you'll need to be able to install the Java Development Kit, connect to the SVN and be comfortable writing Java Code. Instructions for the first two are included below:

Windows

1. Download Tools
   1. Download and install Java Development Kit 1.8 or newer, available from Oracle or AdoptOpenJDK
   2. Download and install Subversion, from apache.org
   3. Download and install Tortoise SVN (or of course, another SVN program)from tortoisesvn
   4. Download and install ANT, from apache.org
2. Configure Windows Environment Variables

   

   Win 10 Environment Variable Editor

   1. Windows 10
      1. Go to settings
      2. type 'enviro' in the search
      3. click on the 'edit environment variables' suggestion
      4. add or edit ANT_HOME, JAVA_HOME, and PATH variables
         PATH should include ANT_HOME/bin and JAVA_HOME
         If ANT or JAVA installers have already set these variables, they can be updated or left alone.
3. Get Source and Build
   1. Connect to the SVN server and download the source code for the Mafia Project. Using Tortoise SVN, you have to right-click on your desktop, select "SVN Checkout", and put the URL of the repository as "svn://svn.code.sf.net/p/kolmafia/code/". Leave all other settings as they are, and click OK.
   2. Copy %ANT_HOME%/bin/ant.bat to your Desktop/kolmafia/ folder. If you have set up ANT correctly (and it's hard not to - there aren't many options) then double clicking on this file should compile the program.
4. Compiling creates a "build" and "dist" folder. The end program is in dist/Kolmafia.jar.

Troubleshooting

Double-Clicking ant.bat

Due to how bat files work when you double-click them, ant.bat will auto-close before you can read its output.

1. ant assumes that builds are done from a command shell. You'll need to run from the command shell to execute any ant target other than the default, such as ant.bat update exec or ant.bat daily
   ant -projecthelp will list all main targets
2. An easy workaround is to add a "pause" near the bottom of the file before it has a chance to auto-close on you.
   When you run it again, you'll be able to read its output and it will exit after you Press any key to continue...
3. Alternatively, you can create a wrapper batch file that calls the existing ant.bat file and adds a pause after executing it. This method allows you to set different ant targets and also prevents updates to ant from overwriting your modifications.

Example of a very simple MyWrapper.bat file

# This is a wrapper batch file
# First it runs ant
call ant.bat daily
# Then it pauses
pause

tools.jar not found

If you get an error message about "tools.jar" not being found, this means you're trying to build with the JRE (which doesn't contain this file) rather than the JDK (which contains it).
To fix this, right click on my computer -> properties -> advanced system settings -> Environment Variables... then make sure your PATH contains a reference to the location of your JDK directory.

Linux

Do once:

1. Install git - you probably already have this. If not, follow this guide.
2. Get an appropriate JDK. The safest and easiest way to do this is with Adoptium.
3. Clone the repo:
   1. If you have a github account:

      git clone git@github.com:kolmafia/kolmafia.git
      

      If not:

      git clone https://github.com/kolmafia/kolmafia.git

Do every session:

Set up your environment to use that JDK you just downloaded

 export PATH="/where/you/put/that/jdk/bin:${PATH}"

Actually compile:

cd /where/you/cloned/kolmafia

./gradlew clean shadowJar

Get new updates with

git pull

You have a KoLmafia jar file that can be invoked with

java -jar dist/KoLmafia-*.jar

Do other installation steps as you wish.

MacOSX (updated for Git/Gradle)

1. Verify required packages
   1. java --version
      • if not found or less than Java 11... Install Java Development Kit version 17 from Adoptium Temurin
   2. git --version
      • If not found ... Install git: Atlassian has a great document on the various ways to install Git
2. Configure development environment
   Most of these steps can be included in .profile or the equivalent for your terminal of choice.
   1. In the terminal set JAVA_HOME to the java home directory.
      /usr/libexec/java_home -V will list all known values for java_home.
      If you have multiple copies of java, choose the version you want to use. export JAVA_HOME=`/usr/libexec/java_home -v17
3. Open a new terminal window and navigate to the directory to which you wish to create kolmafia (e.g. cd ~/projects, or some similar directory)
4. Clone the source code for the KoLmafia Project.
   
   1. If you have a github account:

      git clone git@github.com:kolmafia/kolmafia.git
      

   2. If not:

      git clone https://github.com/kolmafia/kolmafia.git
      

5. Compile KoLmafia with the Gradle wrapper

   cd kolmafia && ./gradlew runShadow
   

Optional

If you intend to commit code to GitHub, you will need to follow GitHub's instructions for adding a Personal Access Token (PAT) '