IntelliJ Setup

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

Exactly nothing below here is accurate, and we'll need to do a thorough cleanup of the build page and the IDE setup page.

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.

IntelliJ IDEA is an IDE for developing Java applications. This guide assumes that you have a recent enough version of Java JDK, Ant, and IntelliJ IDEA. Completing Compiling from Source is a requirement for this guide, although experienced developers can skip to whatever step is appropriate.

The following instructions are based on IntelliJ IDEA 2021.2 Community Edition. Instructions for other versions/editions of IntelliJ may be slightly different.

Create a Project

Choice 1: Create a new project

If you already have a working copy of KoLmafia's source code, you can go to choice 2 instead.

1. Start IntelliJ IDEA. In the Welcome to IntelliJ IDEA dialog, click Get from VCS.
   
2. In the Get from Version Control dialog, select the Repository URL tab.
   1. In Version control, select Subversion.
      
   2. Add a new repository location. To do so, click the + button next to Repositories.
      
      1. In the New Repository Location popup, enter the URL to KoLmafia's Subversion repository. Currently, this is https://svn.code.sf.net/p/kolmafia/code.
         
      2. Click OK to close the popup.
   3. Once the repository has been added, click the repository URL to highlight it, then click Check Out.
      
3. If the Destination Directory popup appears, choose a directory to check out the working copy.
   Caution: Don't choose a common directory like C:\Users\<username>\Documents. Instead, create a new directory under it (by clicking the folder icon) and give it an appropriate name (e.g. kolmafia).
   
   Click OK to continue.
4. If the SVN Checkout Options popup appears, leave everything as-is and click OK.
5. If the Subversion Working Copy Format popup appears, choose the latest version (which is 1.8 format as of writing) and click OK.
6. IntelliJ will generate a new project. If it asks you whether to add kolmafia.iml to Subversion, you may click Cancel to skip it.

Choice 2: Load an existing working copy into IntelliJ

1. From the IntelliJ IDEA File Menu, choose New>New Project from Existing Sources...
2. Choose the directory with the kolmafia build.xml file and press Open
3. Choose Create Project from Existing Sources and press Next
4. Enter the name KoLmafia and press Next
5. Verify that the project is visible to IDEA and press Finish

Add the Ant Build File

1. Open the Ant Toolbar Item (typically on the right side, and not very large)
2. Click the + button to add a build file
3. Choose build.xml from the file selector and press Open
4. Verify that a list of ANT targets appears in the Ant Toolbar

Configure Project

Check Project Settings

1. In the top menu, select File > Project Structure... to launch the Project Structure dialog.
2. In the left menu, select Project Settings > Project
   1. set the Name to kolmafia
   2. set the Project SDK to a version installed on your system. This must be at least 1.8.
   3. set the project language level to 8
   4. set the project compiler output path to the <project dir>\build subdirectory
      
3. In the left menu, select Project Settings > Libraries
   1. Add a project library with the name kol-library-jars:
      1. Click the + button (New Project Library), then select Java to add a new project library
         
      2. If the Select Library Files popup appears, navigate to <project dir>\lib\jar directory and select all JAR files. You can shift+click the first and last JAR files to select multiple files at once.
         
         Click OK to close the popup.
      3. If the Choose Modules popup appears, ensure that kolmafia is highlighted, then click OK.
         
      4. If you followed the steps above, IntelliJ will create a project library using the name of the first JAR file.
         To rename it, select the library, then select the Name field and enter kol-library-jars.
         • 

           Before renaming
         • 

           After renaming
   2. Repeat the steps above to add a project library with the name kol-source-jars, selecting all JAR files under <project dir>\src\jar\.
   3. Repeat the steps above to add a project library with the name kol-test-jars, selecting all JAR files under <project dir>\lib\testjar\.
   4. Click Apply.
4. In the left menu, select Project Settings > Modules
   1. Select the Dependencies tab
      1. If you followed the instructions so far, this section will have libraries with incorrect names (i.e. using the names of the first JAR file in each library). Select them all and click - to remove them.
         
      2. Add the correct project libraries by clicking +, then Library.
         
         1. In the Choose Libraries dialog, select all project libraries we added so far, then click Add Selected.
            
   2. Select the Sources tab
      1. Right-click the lib and src folders. If the and verify that each is marked as Sources
      2. Right-click the test folder. If the folder is not marked as Tests, click the menu item to check it.
         
   3. Select the Paths tab
      1. Select Inherit project compile output path
         
5. Click OK to close the Project Structure dialog

Add Run/Debug Configuration

1. In the top menu, select Run > Edit Configurations... to launch the Run/Debug Configurations dialog.
2. Click the + button, then choose Application to add a new configuration
3. In the Name Field, enter "KoLmafia"
4. Click the icon that looks like a document ("Browse...") to the right of the Main Class field.
   1. If the Choose Main Class popup appears, wait until IntelliJ populates the list of possible main classes, then choose KoLmafia and click OK
5. Add any VM or program arguments needed (typically none)
6. Enter the working directory. This is where KoLmafia will store your user data when launched from inside IntelliJ (e.g. C:\Users\<user>\Documents\kolmafia-workdir).
   Caution: This should be different from the project directory!
7. Add the "before launch" tasks:
   1. Click Modify options at the top right and select Add before launch task
   2. Add the set.released.false Ant task:
      1. Click the + button to the right of Before launch, then Run Ant target.
      2. If the Choose Ant Target to Execute popup appears, select set.released.false and click OK.
   3. Repeat the steps above to add the set.version Ant task
   4. Repeat the steps above to add the unset.properties Ant task
   5. Drag-and-drop the tasks to ensure that each task is executed in the following order:
      1. Run Ant target 'set.released.false'
      2. Run Ant target 'set.version'
      3. Build
      4. Run Ant target 'unset.properties'
8. Click OK to close the Run/Debug Configurations dialog.

Test by pressing the Run arrow next to your config name in the toolbar at the top of the window.

Optional Steps

• Setup SVN to update from IntelliJ (can still be done from the command line or a tool)
  1. TODO: FIXME...
• To use the Reformat Code feature, download the KoLMafia Style Definitions and import them in the IntelliJ Code Style Preferences.