= Developer Runbook (Quick Start and Tips) =
This wiki page is intended for mod developers that work with the source code.  Assuming you are using ''IntelliJ IDEA'', this documents some additional necessary steps to take above and beyond simply cloning the Git repository and importing it into IntelliJ

== 1. Sub-module Initialization ==
The repository uses a sub-module ''Hydrazine Path Engine'' which is not hosted by our repository but is hosted for the public on !GitHub [https://github.com/MadMartian/hydrazine-path-finding here].  In order for your local Git clone to be aware of this run the following command from the repository root directory the first time you clone the repository or if you are updating to [6cf515ed3c0aa43abad5bf4e0b6a7aa6e05db650] or later: 

{{{#!sh
git submodule update --init --recursive --remote
}}}

This will pull the sub-modules from external sources updated to their respective tips.

**NOTE**: If this fails it's likely because a skeletal sub-module directory already exists (i.e. `./hydrazine-path-engine/`), check to make sure you do not have any local changes in this folder and then delete this folder.  Then run the command again.

=== IntelliJ Settings ===
IntelliJ is dumb enough to make you manually dig out a settings page and explicitly enable each sub-module in the project rather than setting it up automatically.  This is a tedious extra step that is easy to forget and will have you pulling your hair out trying to figure out what's wrong with no luck.

[[Image(intellij-submodule-initialization.2017.3.5.png)]]

=== Initialize Specific Sub-Module ===
To initialize a specific sub-module instead of all of them (e.g. you have initialized ''Hydrazine'' but not ''Data Structures'') run the following commands:

{{{#!sh
git submodule init -- < sub-module name >
git submodule update -- < sub-module name >
}}}

Where `sub-module name` is the name and path of the sub-module to update relative to the root directory of the project (e.g. ''data-structures'')

== 2. Setup Decompiled Workspace ==
The first thing to do after cloning the Git repository is to run the gradle task `setupDecompWorkspace`.  This processes the ''Minecraft'' source making some necessary changes to the binary code that are expected by our source.  The most straightforward way to do this is from inside IntelliJ, but you can also do it from the command line as follows from the root directory of the project:

{{{#!sh
./gradlew setupDecompWorkspace
}}}

It may be necessary to run this from time to time after updating your local repository particularly when ''access transformer'' changes have been made in subsequent revisions.

== 3. Settings Repository for IntelliJ ==
We manage project settings for IntelliJ through another one of our own repositories.  

=== IntelliJ IDEA 2017.3.5
'''File → Settings Repository...'''

[[Image(settings-repo.2017.3.5.png)]]

=== IntelliJ IDEA 2021.1
'''File → Manage IDE Settings → Settings Repository...'''

[[Image(settings-repo.2021.1.png)]]

=== URL

The way to set this up in IntelliJ will differ from version to version.
The settings repository URL is:

''< your username >''`@gauss.extollit.com:/opt/git/intellij-settings.git`

Replace ''< your username >'' with your user name, for example mine would be `jonathan@gauss.extollit.com:/opt/git/intellij-settings.git`

When it prompts you what to do (whether overwrite local or remote) choose '''Overwrite Local'''