Overview

This goes over a complete development environment setup for MegaMek, MegaMekLab, and MekHQ. It starts assuming a completely fresh Windows computer, which was my starting state for the guide. This includes setting up a composite build for the three programs, so that the local code is used for all builds.

Table of Contents

1. Install Base Programs
   1. Install Notepad++
   2. Install a Zipper - 7-Zip
   3. Install Git
   4. Install JDK
   5. Install IntelliJ IDEA
   6. Install Discord
2. Create Accounts and Account Setup
   1. Create GitHub Account and Setup Forks
   2. Create Discord Account and Join Our Discord Server
3. Reboot Your Computer (Recommended)
4. Setup Git
5. Initialize Git Repositories
6. Rename Git Repositories (Optional)
7. Download Reference Copies (Recommended)
8. Setup Composite Build
   1. MegaMekLab
   2. MekHQ
   3. Save the File Changes
9. Setup IDEA

Step 1: Install Base Programs

This goes over downloading and installing the base programs you will need to work on the suite.

Step 1.1: Install Notepad++

1. Download the latest version listed here. We recommend downloading the 64-bit installer.
2. Run the installer to install Notepad++.

Step 1.2: Install a Zipper - 7-Zip

1. Select your preferred zipper. We recommend using 7-Zip. Do not use the built-in Windows Zipper (see here for reasons why).
2. Download the latest stable (non-Alpha/Beta/Dev) release listed here. I recommend downloading the 64-bit exe installer.
3. Run the installer to install 7-Zip.

Step 1.3: Install Git

1. Download the installer here for your operating system. You do NOT want a GUI client as the vast majority of people find them harder to use.
2. Start running the installer, selecting options as desired (I left mine as the default) until you reach the default editor.
3. Change the default editor to Notepad++, as per below.

4. Continue through the installer. We use the recommended settings, and highly recommend the "Checkout Windows-style, commit Unix-style line endings", "Use MinTTY", and "Enable file system caching" option selections, all of which should be as per default.

Step 1.4: Install JDK

This is best covered by this guide.

Step 1.5: Installing IntelliJ IDEA

1. Download the installer here. We recommend the Community version, .exe installer.
2. Run the installer. The only part you'll need to make changes to is the installation options. We recommend (and use) the following settings.

3. We went with restart later, which is step 3.

Step 1.6: Install Discord

1. Download the installer here for your operating system.
2. Run the installer.

Step 2: Create Accounts and Account Setup

Step 2.1: Create GitHub Account and Setup Forks

1. Go to here.
2. Select Sign Up (at the top right)
3. Go through the sign up to create your account.
4. Open the MegaMek, MegaMekLab, and MekHQ GitHub pages.
5. Select Fork on the top right of each webpage to create the fork for that part of the suite. Don't click on the numbers, as that just opens up a list of all forks.

Step 2.2: Create Discord Account and Join Our Discord Server

1. Load the Discord App.
2. Selected Register, which is currently located right under login.
3. Fill everything in, thus creating the account.
4. Join our Discord using this link.

Step 3: Reboot Your Computer (Recommended)

With all the installs done thus far, I highly recommend rebooting your computer at this stage.

Step 4: Setup Git

1. Create a folder to hold your development setup.
2. Right click on the white space below any files and select "Git Bash Here" from the popup list.
3. Enter git config --global user.name "John Doe" into the Git terminal, replacing "John Doe" with your GitHub username.
4. Enter git config --global user.email [email protected] into the Git terminal, replacing "[email protected]" with your GitHub username.
5. Enter git init
6. Leave the terminal open, as you'll continue to need it

Step 5: Initialize Git Repositories

1. Open GitHub
2. Select your user image on the top right, and then select "Your repositories" from the dropdown.
3. Open the three repositories you previously forked.
4. In your Git terminal, type in git clone https://github.com/JohnDoe/megamek three times, replacing the link with the one from your forks one by one.
5. Enter cd megamek into the Git Terminal
6. Enter git remote add upstream https://github.com/MegaMek/megamek into the Git Terminal
7. Enter git fetch --all into the Git Terminal
8. Enter cd .. into the Git Terminal
9. Enter cd megameklab into the Git Terminal
10. Enter git remote add upstream https://github.com/MegaMek/megameklab into the Git Terminal
11. Enter git fetch --all into the Git Terminal
12. Enter cd .. into the Git Terminal
13. Enter cd mekhq into the Git Terminal
14. Enter git remote add upstream https://github.com/MegaMek/mekhq into the Git Terminal
15. Enter git fetch --all into the Git Terminal
16. Enter git push into the Git Terminal. If this executes fine, your git repositories should be properly setup. Otherwise, open a PowerShell or Command prompt window. If you opened a PowerShell window, enter cmd, then git push. It should bring up the ability to sign into GitHub using the website. If you do so, it will set up an OAuth token for the computer, which will allow you to push to GitHub going forward.

Step 6: Rename Git Repositories (Optional)

I personally rename the megamek, megameklab, and mekhq folders to mm, mml, and mhq. This makes it far faster to navigate between the repositories, but does require an additional step down the road. This leaves you with the following base file setup if you do step 7.

Step 7: Download Reference Copies (Recommended)

Go to here and download a stable and a recent dev release MekHQ bundle. These allow one to refer to the previous behaviour while coding, and are great for keeping ones test campaign files in. I put these into the same folder as the upper level of my git repositories.

Step 8: Setup Composite Build

This just provides a faster step by step guide to doing so. There's significantly more detail information about it here.

Step 8.1: MegaMekLab

1. Open the MegaMekLab folder
2. Copy the settings.gradle file, and rename the copy to settings_local.gradle.
3. Open settings_local.gradle in Notepad++.
4. Delete all of the contents
5. Paste the following text into the file, using the first version if you did the rename in Step 6 and otherwise using the second.

if (gradle.parent == null) {
    includeBuild '../mm'
}

or

if (gradle.parent == null) {
    includeBuild '../megamek'
}

6. If you did not do the rename in Step 6, your composite build in MegaMekLab is setup. Otherwise, you'll need to continue as one more file needs to be added.
7. Copy the settings_local.gradle file, and rename the copy to properties_local.gradle
8. Open properties_local.gradle in Notepad++
9. Delete all of the contents
10. Paste the following text into the file.

mmDir = '../mm'

Step 8.2: MekHQ

1. Open the MekHQ folder
2. Copy the settings.gradle file, and rename the copy to settings_local.gradle.
3. Open settings_local.gradle in Notepad++.
4. Delete all of the contents
5. Paste the following text into the file, using the first version if you did the rename in Step 6 and otherwise using the second.

includeBuild '../mm'
includeBuild '../mml'

or

includeBuild '../megamek'
includeBuild '../megameklab'

6. If you did not do the rename in Step 6, your composite build in MekHQ is setup. Otherwise, you'll need to continue as one more file needs to be added.
7. Copy the settings_local.gradle file, and rename the copy to properties_local.gradle
8. Open properties_local.gradle in Notepad++
9. Delete all of the contents
10. Paste the following text into the file.

mmDir = '../mm'
mmlDir = '../mml'

Step 8.3: Save the File Changes

You need to save all of the file changes in Notepad++ before continuing to the next step.

Step 9: Setup IDEA

1. Open IDEA. We would recommend not doing this from one of the repository folders, but instead just using the standard launcher.
2. Go through the initial load pages, which last until you hit a welcome page.
3. Select Open
4. Navigate to your local repositories. You should note that they have a black box (see below) on the folder. I believe that means that project files have been detected.

5. Select the megamek / mm folder, then press "OK"
6. Select Gradle project, as this will then automatically configure the repositories

7. Select "Trust the Project", then okay.

8. It will now load the project. You can close the daily hint and what's new, but otherwise just wait. In the backend it is doing a sync, base build, configuration, and creating an index. This will take a few minutes to do. I don't use the prebuild indexes, but that may speed it up a bit.

9. Once the sync is done and there is no longer anything mentioning indexing in the bottom right, download the Settings Repository plugin from https://plugins.jetbrains.com/plugin/7566-settings-repository/versions/stable. Choose the latest version created before your IDE download date. Go to Settings, select Plugins, click the Gear symbol and then click Install Plugin from Disk. Select the Plugin archive just downloaded and click ok. Click ok again and restart the IDE.

10. Go to File, Manage IDE Settings, and select Settings Repository.

11. Enter https://github.com/MegaMek/IDEASettings into the Upstream URL field, then select overwrite local. This will pull down the standard MegaMek configuration settings.

12. Next, go to File and select Settings.

13. Go to Code Style, expand it, and then ensure all of the code styles use the Default IDE scheme.

14. In the same settings dialog, select Inspections and change the profile from Project Default to MegaMek Default.

15. Next, go to File/Open in the top bar, and open the megameklab / mml folder. Trust the project, and open in this window.

16. Wait for the initial sync and indexing is done, but in the meanwhile watch the projects listed in the top left project view (you may have to collapse the megameklab / mml project). You should see both the megamek / mm and megameklab / mml repositories listed there pretty soon after your initial load (mine was there within a few seconds).

17. Once the sync is done and there is no longer anything mentioning indexing in the bottom right, repeat steps 11 to 13 for MegaMekLab.

18. Next, go to File/Open in the top bar, and open the mekhq / mhq folder. Trust the project, and open in this window.

19. Wait for the initial sync and indexing is done, but in the meanwhile watch the projects listed in the top left project view (you may have to collapse the mekhq / mhq project). You should see all three repositories listed there pretty soon after your initial load (mine was there within a few seconds).

20. Repeat steps 11 to 13 for MekHQ.

21. The repositories are now setup and will do a composite build.

22. This is just a verification, to ensure the build happens properly. We suggest going to the Gradle bar on the top of the right side bar, then go through the MekHQRoot/MekHQRoot/Tasks/application, and double clicking run. That will cause MegaMek, then MegaMekLab, and finally MekHQ to build. If MekHQ loads, then you've got your setup done.

Guide Information

Author: Windchild

Date: 08-Jan-2022