Skip to content

Latest commit

 

History

History
208 lines (144 loc) · 9.24 KB

DEV_NOTE.md

File metadata and controls

208 lines (144 loc) · 9.24 KB
Raw

Developer Documentation for LPhy

Gradle

  1. Install OpenJDK 17 and Gradle 7.x.

You can look at Setup development environment for more details.

  1. Always execute a build with the wrapper, as recommended by Gradle user guide, where --info provides more information about the process:
./gradlew build --info

The command below makes a "clean" build by deleting previous build and ignores caching:

./gradlew clean build --info --no-build-cache

When you run the build task above, it will include jar task to create a jar file, distribution tasks because we have defined it in the build file, as well as test task to run unit tests.

If you want to build without tests, you can use -x to exclude it:

./gradlew build -x test
  1. Distribution of the project:

The zip file, named as "lphy-studio-${versoin}.zip", will be created inside the sub-folder "build/distributions" under the lphy-studio module, after build.

But if you want to create the zip without rebuilding the project, you can go to the Gradle toolbar, expand lphy-studio => Tasks => distribution, and click distZip. More details about distributing jar files are available in the user guide of distribution plugin.

  1. Run LPhy studio application through Gradle: 
./gradlew :lphy-studio:run

Please note there are two applications in the project, so you need to specify which subproject the task run is coming from, such as :lphy-studio. If the subproject is not given, then it will trigger two applications at once.

Or through IntelliJ Gradle toolbar (normally on the right side of IntelliJ window frame). Expand lphy-studio => Tasks => application, as shown in the screenshot on the right, and click run.

  1. Publish to Maven central repository:
./gradlew clean
./gradlew publish --info 
    -Psigning.secretKeyRingFile=/path/to/.gnupg/mysecret.gpg 
    -Psigning.password=mypswd -Psigning.keyId=last8symbols 
    -Possrh.user=myuser -Possrh.pswd=mypswd

This supplies information of both your authentications for signing and publishing.

5.1 GPG

The property signing.password is the passphrase of gpg used to protect your private key. Run gpg --list-keys to find your keyId, which is a super long string mixed with letters and numbers, and assign the last 8 symbols to the property signing.keyId in the command line. Please remember to distribute your public key to a GPG keyserver before release deployment.

5.2 Sonatype

ossrh.user and ossrh.pswd are used to login your JIRA account in Sonatype. If your password contains special characters, you can use single quotes to wrap the string to avoid errors. More details are available in Sonatype's publish guide and release rules.

Note: once published, you will not be able to remove/update/modify the artifact in Sonatype. So for testing purpose, assign the version in build.gradle.kts to contain the suffix "-SNAPSHOT", the artifact will be published to https://s01.oss.sonatype.org/content/repositories/snapshots/io/github/linguaphylo/, which can be updated.

See also Snapshot Repository vs Release Repository and Best Practices for releasing with 3rd party SNAPSHOT dependencies.

  1. Release deployment

You need to manually deploy your release from OSSRH to the Central Repository.

See also Publishing your Kotlin Multiplatform library to Maven Central.

Upgrade the wrapper

If it is not the latest version (e.g. version 7.5 at the time of writing), you can use the following command to upgrade the wrapper:

./gradlew wrapper --gradle-version 7.5
./gradlew -v

We choose Gradle + Kotlin.

Please also see Gradle Kotlin DSL Primer and the benefit switching from Groovy to Kotlin.

Please also see Declaring Dependencies between Subprojects.

IntelliJ

Dependencies

The LPhy project and its extensions use the Gradle dependency configurations. IntelliJ provides nice GUI to add and manage dependencies in your Gradle project.

Please see an example of LPhy extension.

When the dependencies are changed in the Gradle build, you can simply click the "refresh" icon in the top right corner of IntelliJ. It will complete updates automatically.

But to update a snapshot version, which you cannot change from the dependencies in the Gradle build, you have to click "Refresh Gradle Dependencies" to download the latest snapshot version from Maven repo. Then click the task clean and build sequentially to rebuild the project. See also force updating all the snapshot Gradle dependencies in intelliJ.

Breakpoints failed in Java class

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.

Alternative, you can use the terminal to run the Gradle tasks.

Release procedure

  1. Make sure all versions not containing the postfix "SNAPSHOT". Run ./gradlew clean build --no-build-cache, which will run all unit tests as well. In the end, it creates a Zip file lphy-studio-1.x.x.zip in $PROJECT_DIR/lphy-studio/distributions.

  2. Run the task lphyDoc to generate LPhy docs. The output will be in the directory $PROJECT_DIR/lphy/doc as default.

For the extension developer, you need to change the script to set the arguments passed main method in your lphyDoc from setArgs(listOf("$version")) into setArgs(listOf("$version", "$EXT_NAME", "$CLS_NAME")), where $EXT_NAME is your extension name appeared in the doc title, and $CLS_NAME is the full class name with package that implements LPhyExtension, such as phylonco.lphy.spi.Phylonco in the Phylonco extension.

  1. Create a pre-release in Github, and upload the Zip file. In addition, if you do not publish the jars to the Maven central repository, you need to provide the jar file and its source jar in the release.

  2. Run ./gradlew publish --info -P... to publish to the Maven central repository. Please note: once published, you will not be able to remove/update/modify the jar.

  3. Follow the instruction of the releasing deployment to complete publishing at https://s01.oss.sonatype.org/.

For snapshots, check https://s01.oss.sonatype.org/content/repositories/snapshots/io/github/linguaphylo/. For releases, check https://s01.oss.sonatype.org/content/repositories/releases/io/github/linguaphylo/.

Tips:

Useful Links