Gradle vs IDE Generation¶
Grammar-Kit offers three ways to generate parser code: from the IDE (Ctrl+Shift+G), from the Gradle plugin, and from the command-line JAR. Each approach makes different trade-offs between feature completeness, automation, and reproducibility. This page helps you choose the right one for your project.
Feature Comparison¶
| Capability | IDE | Gradle Plugin | CLI |
|---|---|---|---|
| Preferred upstream workflow | Yes | No | No |
Output directory resolved from parserClass in project context | Yes | No, configured in build | No, explicit output dir |
| Background progress / notification | Yes | No | No |
Supports mixin | Yes | No | Not the recommended path |
Supports psiImplUtilClass method injection | Yes | No | Not the recommended path |
| May lose precision in generics / annotations | No | Yes | Yes |
| Syntax-api / Kotlin parser generation | Yes | Not documented in current Gradle guidance | No, CLI is classic-generation oriented |
The most significant difference is that the IDE workflow can work with the incomplete PSI support code in your project, while build-time generation cannot. Current upstream docs describe the practical result this way: mixin is unsupported, psiImplUtilClass is unsupported, and generic signatures and annotations may be less precise in Gradle and CLI generation.
IDE Generation¶
IDE generation is the recommended approach during active grammar development. It provides the tightest feedback loop: edit the grammar, press Ctrl+Shift+G, and the generator writes files directly into your source tree. The IDE resolves output directories automatically from the parserClass attribute using PackageIndex, so you do not need to configure paths manually.
The generation runs as a background task with a progress indicator and reports results through a notification showing file count, total size, and duration. After generation, the IDE refreshes its virtual file system so you can immediately use the new code.
IDE generation is also the only way to use Live Preview (Ctrl+Alt+P), which lets you test grammar changes against sample input in real time without regenerating.
Gradle and CLI Generation¶
The Gradle plugin and CLI are both automation paths, but they are not interchangeable. The Gradle plugin is the build-oriented path discussed on this page. The standalone CLI JAR is a lighter-weight command-line utility.
The Gradle plugin integrates with Gradle's task dependency and up-to-date checking, so generation runs only when the grammar file changes. The CLI JAR is a simpler option for scripts or build systems other than Gradle.
Current upstream source keeps the CLI path focused on classic Java generation. Upstream also labels standalone usage as a proof of concept rather than the primary supported path, so do not treat it as the syntax-api / Kotlin parser generation path.
The limitations are the same for Gradle and CLI generation in current upstream docs: mixin is unsupported, psiImplUtilClass is unsupported, and generic signatures and annotations may be less precise. If your grammar uses neither customization and does not depend on exact generated signatures, these limitations may not affect you.
For details on configuring the Gradle plugin, see Gradle Plugin Setup.
Choosing an Approach¶
The right strategy depends on whether your grammar uses mixin or psiImplUtilClass and how your team manages generated code.
If your grammar uses mixin or psiImplUtilClass, generate from the IDE and commit the generated files to version control. CI compiles the committed sources without running the generator. This gives you correct output from the IDE workflow while keeping builds reproducible.
If your grammar uses neither mixin nor psiImplUtilClass, the Gradle plugin works well as the sole generation method. Add src/main/gen to .gitignore and let every build (local and CI) regenerate from the grammar. This avoids merge conflicts in generated files and guarantees that the committed grammar is the single source of truth.
A hybrid approach works for teams transitioning between methods: generate from the IDE during development for fast feedback and accurate output, then verify in CI that the Gradle plugin produces compilable code. Over time, you can reduce reliance on IDE generation as you remove mixin dependencies.
Whichever approach you choose, keep the grammar file itself in version control and document the generation method in your project's build instructions.