Complete Development Environment Setup using IntelliJ Idea

Overview

This goes over a complete development environment setup for MegaMek, MegaMekLab, and MekHQ. It assumes you have some familiarity with your operating system of choice. For all three major platforms, you'll need to make sure you have Git and a Java Development Kit already installed. We are currently using Java 17 for development.

Table of Contents

1. Download and Install IntelliJ IDEA
2. Create Accounts and Account Setup
3. Git Configuration
4. Initialize Git Repositories
5. Download Reference Copies (Recommended)
6. Setup IDEA
7. MekHQ Inspection

Step 1: Download and Install IntelliJ IDEA

This is currently the preferred IDE for development and the one we'll be going over. We are looking at getting instructions for Eclipse and VS Code as well but will take time. There are certain features of IDEA that make it ideal to ensure compliance with our Coding Style configuration.

Download the installer for your platform and run through the initial setup. Unless you have a paid account, or access to the GitHub Education, use the Community Edition.

On Windows, there are a few changes that we recommend during installation that you make as indicated below in the image.

For Windows users, go ahead and restart. It'll help prevent potential problems later. For all other platforms, carry on.

Step 2: Create Accounts and Account Setup

You're here on GitHub so, if you haven't already, make a GitHub account and create a fork of the three repositories into your account. This can be done by navigating to each one and clicking the Fork button in the top right of the page. Process should be near instant.

The three repositories are at MegaMek, MegaMekLab, and MekHQ respectfully.

Be sure to also join our Discord so you can converse with the rest of the development team and get any additional help along the way as well as get early insights into what is being worked on.

Step 3: Git Configuration

The follow steps are recommended and may later be enforced. Need to configure Git with your name (can be your user name or actual name, something we can use to identify you in essence) and an email address that is verified by GitHub. These two things allows Git to show that they are verified commits by you.

git config --global user.name "John Doe"
git config --global user.email [email protected]

As an added step, we encourage you to also Sign your commits. This is an extra step that ensures the commits you make really are coming from you as only you'll have the key for it. The instructions for that can be found here

Step 4: Clone and setup local copies

Setup a folder somewhere on your computer to hold your development work. On macOS, if you create a ~/Developer account you'll get a special icon for it. We suggest a similar path for Linux users as well to keep it in your home folder.

For Windows users, make sure that where you put the folder is NOT managed by OneDrive as it WILL mess things up. We'd suggest at C:\Developer.

Inside of this Developer folder, create a folder called MegaMek to store the three repositories. Whether you wish to contribute to all three or not, we strongly urge you to clone all three as changes in MegaMek or MegaMekLab CAN impact MekHQ and MegaMekLab, and to compile MekHQ you also need MegaMek and MegaMekLab.

Inside this MegaMek folder, clone the three repositories. If you're using a Git GUI, follow their instructions on how to do that. From a terminal window however, enter the following commands:

git clone https://github.com/JohnDoe/megamek
git clone https://github.com/JohnDoe/megameklab
git clone https://github.com/JohnDoe/mekhq

An optional step that will make updating the repositories easier is to run the following commands which configures the main repositories as upstreams to yours.

cd megamek
git remote add upstream https://github.com/MegaMek/megamek
git fetch --all
git pull upstream master
git push
cd ../megameklab
git remote add upstream https://github.com/MegaMek/megameklab
git fetch --all
git pull upstream master
git push
cd ../mekhq
git remote add upstream https://github.com/MegaMek/mekhq
git fetch --all
git pull upstream master
git push

These commands change into each folder, adds the main repositories as upstream remotes, fetches the latest changes into the current branch, and then pushes then to your fork. If all things go well, there will be no errors.

Updating forks with latest changes

Before starting work on a new branch, it is advised you update all to the latest revisions which can be done as follows from the parent MegaMek (not repository) folder:

cd megamek
git switch master
git pull upstream master
git push

cd ../megameklab
git switch master
git pull upstream master
git push

cd ../mekhq
git switch master
git pull upstream master
git push

Step 5: Download Reference Copies (Recommended)

Go to here and download the latest released version of the MekHQ bundle. These allow one to refer to the previous behavior while coding, and are great for keeping ones test campaign files in. For easier references, it is advisable to store them within the same parent MegaMek folder.

Step 6: Setup IDEA

Load up IDEA and go through the initial Welcome screens. You'll eventually get to a screen similar to this:

Click on Open and navigate to where you cloned the repositories and open up MekHQ. You'll get a popup talking about project configurations, select Gradle Project.

Give it a few minutes to do what it needs to do. It'll import MekHQ, MegaMekLab, and MegaMek for you automatically. Need to make 2 additional changes to ensure you stick closely with our Style Guide. We use an EditorConfig file to enforce most of the settings and this will change from time to time as the Development team tweaks it. Good news is IDEA helps with this by reading in the file for you automatically and will enforce them over local settings.

Under IDEA Settings, the following two things need to be configured if they are different than shown. First is related to Imports:

And the other for Actions on Save:

These two things adjusts the import styling at the top of the file to unify it across the entire code base and reduce the chance of errors happening due to the wrong Type being imported.

The second thing will do code cleanup on the file you're working on to ensure it matches the Code Style. This helps ensure you are following the established guide to make it easier for everyone.

To ensure everything is setup correctly, need to run the testAll command from MekHQ. This will perform a cleanAll for all three projects then run all three tests. If that succeeds, everything is in good order and you're ready to go!

Note: Warnings are to be expected but so long as no errors show up, things are fine.

Step 7: MekHQ Inspection

MekHQ makes use of some amount of runtime and reflection code use, to make sure that methods that are used show as being in use we have to teach IntelliJ inspection module to understand the custom annotations we have.

Here I show you how to specifically recognize methods annotated with @Subscribe as potentially being in use, instead of showing up marked as unused.

First open Settings, then Editor and inside Editor you select Inspections:

In that window you will select the search bar and write Unused, or look for the entry Java > Declaration redundancy > Unused declaration, click in that entry and look into the lower right corner of the window.

There you can see the options pane for the Unused declaration inspection, click in the tab which says Entry points and there you will find the button Annotations..., you click on it.

The button Annotations... will open a small dialog, in it you will select the top most + button in the top panel.

Write the name of the annotation we want, in this case is Subscribe, it will show up in the list of possible choices, select it and click Ok. Now click Ok in the dialog to finish the addition of this annotation to it, and then click Apply in the Settings dialog and close it by clicking Ok

Updated: 2025-04-26 - Scoppio