Development Environment Setup

This guide will walk you through setting up the development environment to build OpenRocket from the source code.

Prerequisites

  • JDK 17. OpenRocket is developed using Java 17, so you will need to install it to build and run OpenRocket. If you have multiple versions of Java installed, ensure that Java 17 is the default version.

  • Git. Git is a version control system that is used to manage the source code for OpenRocket. You will need to install Git to clone the OpenRocket repository.

  • GitHub Account. GitHub is a platform for hosting Git repositories. You will need a GitHub account to fork the OpenRocket repository and submit pull requests.

  • Gradle. OpenRocket uses Gradle as its build system. You will need to install Gradle to build OpenRocket.

Obtaining the Source Code

The source code for OpenRocket is hosted on GitHub. However, you cannot change this code directly. This is because the OpenRocket repository is the official repository for the project, and only the project maintainers can make changes to it. This is to ensure that the codebase remains stable and consistent. Instead, you must fork the OpenRocket repository, which creates a personal copy of the repository that you can make changes to. You can then submit a pull request to the OpenRocket repository to propose your changes.

Forking the Repository

The first step is to fork the OpenRocket repository. As mentioned earlier, the OpenRocket repository is the official repository for the project, and only the project maintainers can make changes to it.

Go to the OpenRocket repository on GitHub (link) and click the Fork button:

Forking the official OpenRocket repository.

Forking the official OpenRocket repository on github.com/openrocket/openrocket.

You can leave the default settings and click Create fork. This will create a copy of the OpenRocket repository in your GitHub account:

Your forked repo.

Your forked repo.

You can always retrieve your forked repository under your GitHub account, under Your repositories, or by visiting the URL https://github.com/<your_username>/openrocket (replace <your_username> with your actual username).

Cloning the Repository

Now that you have forked the OpenRocket repository, you can clone it to your local machine. To do this, open a terminal and run the following command (replace [YOUR USERNAME] with your GitHub username):

# Use the following command if you have set up SSH keys with GitHub
git clone git@github.com:[YOUR USERNAME]/openrocket.git

# Otherwise, clone the repository using HTTPS
git clone https://github.com/[YOUR USERNAME]/openrocket.git

This will clone the OpenRocket repository to your local machine. You can now make changes to the code and push them to your forked repository.

One final step you need to do is to initialize the submodules. OpenRocket uses submodules for some of its dependencies. To initialize the submodules, run the following commands:

git submodule init
git submodule update

Keeping your Fork in Sync

Once you have forked the OpenRocket repository, you will need to keep your fork in sync with the official repository. This is because the official repository may have changes that are not in your fork, and you will want to keep your fork up-to-date with the latest changes. For example, in the following image you can see that your fork is 10 commits behind the official repository:

An outdated forked repo.

An outdated forked repo.

Luckily, GitHub makes it easy to keep your fork in sync with the official repository. You can do this by clicking the Sync fork button on your forked repository page and then clicking the Update branch button:

Syncing your forked repo on GitHub.

Syncing your forked repo on GitHub.

If all went well, your fork should now be up-to-date with the official repository:

An up-to-date forked repo.

An up-to-date forked repo.

Warning

It is important to keep your fork in sync with the official repository. If you don’t, you may encounter conflicts when you try to submit a pull request.

Regularly check your forked repository to see if it is behind the official repository. If it is, sync your fork!

Now you have updated your fork, but you still need to update your local repository (your clone). To do this, you need to fetch the changes from the official repository and pull them into your local repository. You can do this by running the following commands:

git fetch && git pull

Setting Up the Development Environment

This section will guide you through setting up the development environment to build OpenRocket from the source code.

IntelliJ IDEA

IntelliJ IDEA is a popular Java IDE that is used by many developers. It has a lot of features that make it easier to develop Java applications. We highly recommend using IntelliJ IDEA for developing OpenRocket. You can download the Community Edition for free from the JetBrains website (scroll down to “IntelliJ IDEA Community Edition” and click the download button).

Once you have downloaded and installed IntelliJ IDEA, you can open the OpenRocket project:

  1. Start IntelliJ IDEA

  2. Import the OpenRocket project

    In IntelliJ, select File ‣ New ‣ Project from Existing Sources…. This will open a file dialog. Navigate to the directory where you cloned OpenRocket and select the build.gradle file in the root openrocket directory and click Open.

  3. Import Project as Gradle Project

    IntelliJ should automatically detect that this is a Gradle project. If prompted, select Load Gradle Project.

    Load Gradle Project.

    IntelliJ IDEA will automatically detect that this is a Gradle project and prompt you to load it. Click Load Gradle Project.

    If you do not have this pop-up or if you have dismissed it, you can still import the project as a Gradle project. Open the build.gradle file in the root openrocket directory in IntelliJ (double-click the file in IntelliJ’s project view). Then right-click anywhere in the file and select Link Gradle Project.

    Linking the Gradle project from the :file:`build.gradle` file.

    Linking the Gradle project from the build.gradle file.

  4. Configure JDK for the Project

    • Go to File ‣ Project Structure ‣ (Project Settings ‣) Project.

    • Set the Project SDK to JDK 17.

      Set the project SDK.

      Set the project SDK to JDK 17.

      If JDK 17 is not listed, you can download it from the Project Structure dialog by going to (Platform Settings ‣) SDKs, clicking the + button, and selecting Download JDK.... Then select version 17 and any vendor (e.g. OpenJDK, Amazon Corretto, …).

    • Confirm in the Project Structure dialog under (Project Settings ‣) Modules that the SDK in each module is set to JDK 17. If not, you can change it by selecting the module and setting the SDK in the right pane. Ensure that the list view on the bottom-right does not show <No SDK>. If it does, click the Module SDK dropdown and click (again) on the JDK 17 SDK.

    Set the module SDK.

    Set the module SDK to JDK 17.

    • Under Settings ‣ Build, Execution, Deployment ‣ Build Tools ‣ Gradle, set the Gradle JVM to the same JDK 17.

    Note

    The repository does not track which JDK you use. Only shared project configuration lives in .idea (the run configurations, the inspection profile and the file encodings); the project SDK, the module SDKs and the Gradle JVM are all local settings, so you are free to point them at whichever JDK 17 installation you have. Which Java release the code is compiled against is decided by the Gradle build (standardJavaRelease(17) in build.gradle), not by the IDE.

  5. Run the Application By default, IntelliJ should be set up with 3 run configurations:

    • SwingStartup: Run the application from within IntelliJ. You will use this configuration most of the time. You can also run it in debug mode by clicking the green bug icon next to the play button. The configuration invokes the Gradle run task, so the IDE launches OpenRocket exactly the way ./gradlew run does.

    • openrocket-jar: Run all the unit tests and build the application as a JAR file.

    • openrocket-test: Only run the unit tests.

    Note

    OpenRocket is built as a set of Java modules (JPMS), and the build applies a --patch-module workaround for core/libs/script-api-1.0.jar, which carries an old copy of the javax.script packages. A plain IntelliJ Application run configuration does not apply that patch and fails at startup with Module script.api contains package javax.script. Launch the application through Gradle rather than through a hand-made Application configuration.

    Default installed run configurations.

    The default installed run configurations.

    You can run the application by selecting the SwingStartup configuration and clicking the green play button. This will instantiate the OpenRocket application from within IntelliJ IDEA. If you want to stop the running application, click the red square button on the top-right in IntelliJ.

    Running OpenRocket from IntelliJ IDEA.

    Running OpenRocket directly from IntelliJ IDEA.

  6. That’s it! You can now start developing OpenRocket. 🚀

Command Line Interface

It is also possible to develop in a text editor and build OpenRocket from the command line using Gradle. Please refer to the Building and Releasing section for all the possible Gradle tasks. To run OpenRocket, you can use:

./gradlew run

Troubleshooting

  1. JDK Not Recognized

    Ensure that the JDK path is correctly configured in File ‣ Project Structure ‣ SDKs.

  2. Gradle Sync Issues

    • If IntelliJ fails to import Gradle projects correctly, try refreshing the Gradle project by clicking on the “Reload All Gradle Projects” icon in the Gradle tool window.

    • Ensure the gradle-wrapper.properties file points to the correct Gradle version which supports Java 17.

  3. Error: Could not find or load main class info.openrocket.swing.startup.SwingStartup Caused by: java.lang.ClassNotFoundException: info.openrocket.swing.startup.SwingStartup Error when running the SwingStartup configuration in IntelliJ.

    • Ensure that you have loaded the project from Gradle when you first opened the project in IntelliJ (step 3 in the IntelliJ setup).

  4. Error occurred during initialization of boot layer — java.lang.module.ResolutionException: Module script.api contains package javax.script

    This happens when the application is started through an IntelliJ Application run configuration instead of through Gradle. See the note in step 5 of the IntelliJ setup: use the SwingStartup configuration (or ./gradlew run), which applies the --patch-module workaround the modular build needs.

  5. An IDE settings file keeps showing up as modified

    Only the run configurations, the inspection profile, the file encodings and the project name are tracked in .idea; everything else is ignored on purpose, because it is local IDE state. If a file that should be ignored keeps reappearing, check that it is not still tracked with git ls-files .idea.