Skip to content

Development.md

Latest commit

 

History

History
230 lines (151 loc) · 6.89 KB

Development.md

File metadata and controls

230 lines (151 loc) · 6.89 KB
Raw

Development

This guide is intended for developers who want to contribute to this project. It covers the setup process, build system, grammar files, available Gradle tasks, and releasing the plugin.

Before you start, please read the guidelines found in CONTRIBUTING.md.

Table of Contents

Setup

Prerequisites

  • Java Version 21 or later
  • A JetBrains IDE (CLion, IntelliJ IDEA, etc.) -> not needed for development per se since testing will download and run the IDE plugin, but helpful for manual testing

Helpful, but not required, IDE plugins:

Build System

This project uses Gradle (Groovy DSL) to build the plugin with extensions to streamline the development and release process.

It is available in this repository already under gradlew so no installation is required.

Setup:

To update the version used:

  1. Find the version under Gradle Releases
  2. Update the version in gradle.properties under the gradleVersion property.
  3. Find the sha256 checksum under Gradle Checksums under the Binary-only section
  4. Run the following command twice to update the Gradle wrapper. The first time will download the wrapper, the second time will update it:

Linux/MacOS:

./gradlew :wrapper --gradle-distribution-sha256-sum=<checksum>

Windows:

gradlew.bat :wrapper --gradle-distribution-sha256-sum=<checksum>

Replace <checksum> with the checksum you found in step 3.

Grammar

This project defines grammar files using JFlex (lexer) and GrammarKit (parser) which are used to generate the lexer and parser code.

You will need to regenerate the lexer and parser code whenever you make changes to the grammar files.

The generated code is placed in the src/main/gen directory.

Gradle Tasks

The following tasks are useful when developing the plugin

Generate Lexer

Generate a lexer using JFlex from the Vala.flex file.

Linux/MacOS:

./gradlew generateLexer

Windows:

gradlew.bat generateLexer

See generateLexer for more details.

Generate Parser

Generate the parser and PSI using GrammarKit from the Vala.bnf file.

Linux/MacOS:

./gradlew generateParser

Windows:

gradlew.bat generateParser

See generateParser for more details.

Build Plugin

Build the plugin and prepare a ZIP archive for testing and distribution. It will be placed in the build/distributions directory.

Linux/MacOS:

./gradlew buildPlugin

Windows:

gradlew.bat buildPlugin

See buildPlugin for more details.

Run IDE

Runs a fresh IDE instance with the plugin installed and ready to test with the version and product specified in the gradle.properties file under the IntelliJ Platform Properties section.

Linux/MacOS:

./gradlew runIde

Windows:

gradlew.bat runIde

See runIde for more details.

Verify The Plugin

Verify the plugin for binary compatibility before publishing to the Marketplace using IntelliJ Plugin Verifier CLI to ensure that the plugin is compatible and adheres to the standards set by JetBrains in order to be approved.

Linux/MacOS:

./gradlew verifyPlugin

Windows:

gradlew.bat verifyPlugin

See verifyPlugin for more details.

Publish Plugin

Publishes the plugin to the marketplace via gradle task. You can also upload the plugin's ZIP manually to the marketplace if you have access to the community plugin management page.

You will need to have the following environment variables set to publish the plugin:

  • PUBLISH_TOKEN - the authorization token used for publishing
  • CERTIFICATE_CHAIN - the certificate chain used for signing
  • PRIVATE_KEY - the private key used for signing
  • PRIVATE_KEY_PASSWORD - the password for the private key used for signing

Linux/MacOS:

./gradlew publishPlugin

Windows:

gradlew.bat publishPlugin

See publishPlugin for more details.

Releasing

In order to release a new version of the plugin:

  1. Update the version in gradle.properties, following Semantic Versioning guidelines
  2. Update the changelog to include the latest changes in CHANGELOG.md following Keep a Changelog guidelines
  3. Update the draft release details in GitHub Releases with the changes and publish the release.

CI/CD via GitHub Actions will automatically build and publish the plugin to the JetBrains Marketplace when a new release is created, and likely will be available within 48 hours, pending approval by the JetBrains team.

Marketplace Description

The description for the plugin on the Marketplace is written in MarketplaceDescription.md.

It is written in Markdown and is converted to HTML by JetBrains KT Extension Kit in build.gradle under the intellijPlatform, pluginConfiguration, description property.