Setup Development Environment

This page will introduce how to setup the development environment for working on the LPhy or LPhyBEAST extensions. Before we start, please install the following softwares in your local machine:

1. Java 17, such as OpenJDK 17;
2. Gradle 7.x;
3. The latest version of IntelliJ;
4. The latest version of Kotlin plugin.

Loading the existing project

You can load a Gradle project from IntelliJ, by choosing the project folder, after you click Open button from the “Welcome to IntelliJ” window. It may take several minutes for indexing when the project is loaded first time. You can look at the progress bar to see whether the loading is completed.

For example, assuming LinguaPhylo does not exist, then after you click Open, you need to choose the “linguaPhylo” folder.

Figure 1: Open the existing project.

We recommend you run the Gradle build from the terminal once, before opening a new Gradle project.

Please note IntelliJ will automatically import the modules and dependencies from Gradle’s settings and build files. You are not supposed to change project structure settings in IntelliJ, becasuse the changes might be lost after reimporting.

Java

The LPhy and LPhyBEAST is developed on Java 17 (LTS). We recommend you install OpenJDK 17. You can simply download it and decompress into your JAVA_HOME folder.

Please configure your IntelliJ project SDK to 17, and also set language level to 17.

Figure 2: Project SDK.

Working with multiple Java versions

If you have multiple Java versions installed in Linux or Mac OS, you can use the following command to switch to Java 17 from another version.

export JAVA_HOME=`/usr/libexec/java_home -v 17`

Use /usr/libexec/java_home to show your JAVA_HOME, and /usr/libexec/java_home -V to list all available Java versions in your operating system.

Gradle

They are also the Gradle projects. Please install Gradle 7.x before you start. Type ./gradlew -v in the terminal to test if the Gradle is installed properly.

Please configure your IntelliJ Gradle JVM to 17. You can go to “Preferences”, and expand Build, Execution, Deployment => Build Tools => Gradle. In addition, it is important to set Build and run using “IntelliJ IDEA”, otherwise breakpoints will not work in Java class using the default option “Gradle”. But if you want to debug the Gradle build file, you have to change this to “Gradle” option.

Figure 3: Gradle JVM.

Alternative, you can use the terminal to run the Gradle tasks. Please alos see LPhy developer note

IntelliJ and Kotlin plugin

In addition, you need to download the latest version of IntelliJ, and Kotlin plugin.

Figure 4: Kotlin plugin.

Common problem

If your build failed and there was the red text showing “an API of a component compatible with Java 17 …”, then you need to check if your Java version is 17. In the screenshot below, the Java version was 1.8.

Figure 5: Build failed because of Java version.

Project structure

The extension project supposes to contain 3 modules, also known as sub-projects in Gradle. They are located in the subfolders under the project root folder.

1. mypackage-beast contains the BEAST 2 extension classes;
2. mypackage-lphy contains LPhy extension classes;
3. mypackage-lphybeast contains the mapping classes between BEAST 2 and LPhy.

The project folder structure looks like:

mypackage
    ├── build.gradle.kts
    ├── examples
    ├── mypackage-beast
    │    ├── build.gradle.kts
    │    ├── lib
    │    └── src
    │         ├── main
    │         │    └── java
    │         │          └── mypackage.beast.*
    │         └── test
    ├── mypackage-lphy
    │    ├── build.gradle.kts
    │    ├── doc
    │    ├── lib
    │    └── src
    │         ├── main
    │         │    ├── java
    │         │    │     ├── mypackage.lphy.*
    │         │    │     └── module-info.java
    │         │    └── resources
    │         │          └── META-INF
    │         │                 └── services
    │         │                        └── lphy.spi.LPhyExtension
    │         └── test
    │    
    ├── mypackage-lphybeast
    │    ├── build.gradle.kts
    │    ├── lib
    │    └── src
    │         ├── main
    │         │    └── java
    │         │          ├── mypackage.lphybeast.*
    │         │          └── module-info.java
    │         └── test
    ├──settings.gradle.kts
    └──...