Gradle plugin for JastAdd development.
Can be used just to generate Java code using JastAdd, or for building a modular project using JFlex and Beaver for scanner and parser generation.
This plugin is integration tested with the following Gradle versions:
- 6.9.1
- 7.2
The Plugin is known to not work with these Gradle versions:
- 2.7
To add the plugin to your project, add this to your build.gradle
file:
plugins {
id "org.jastadd" version "1.13.1"
}
This configures the plugin to be downloaded from the Gradle plugin portal.
The JastAdd Gradle plugin can be used either as a simple code generator, or as a modular JastAdd project build system.
The non-modular mode can be used if you just want to use JastAdd to generate some code. This is useful for simple JastAdd projects.
In the modular build mode, the JastAdd Gradle plugin figures out which JastAdd source files to include in the build. The modular build can also generate a Beaver parser and JFlex scanner if needed.
The easiest way to set up a small Gradle build to generate some Java code with JastAdd is to use a non-modular JastAdd build.
Non-modular builds can be set up using the Gradle task
org.jastadd.JastAddTask
provided by the JastAdd Gradle plugin:
plugins {
id "java"
id "org.jastadd" version "1.14.0"
}
task generateJava(type: org.jastadd.JastAddTask) {
outputDir = file('src/gen')
sources = fileTree('src/jastadd')
options = [ "--package=my.ast" ]
}
You should also add these two lines to make the default compileJava
task
depend on the JastAdd-generated code:
compileJava.dependsOn 'generateJava' // Generate code before compiling.
sourceSets.main.java.srcDir 'src/gen' // Compiles the generated code.
The JastAdd Gradle plugin can run JastAdd automatically with the right source files if you use the modular build mode. The JastAdd Gradle plugin also adds tasks to generate a JFlex scanner and a Beaver parser.
A modular build can be configured by calling jastadd.configureModuleBuild()
.
This configures a couple of default tasks:
generateAst
- runs JastAdd to generate the AST classes.generateScanner
- runs JFlex to generate a scanner.preprocessParser
- preprocesses parser source files with JastAddParser.generateParser
- runs Beaver to generate a parser.
The JastAdd Gradle plugin does not yet support other scanner and parser generator tools for modular builds, but if you don't include any scanner/parser sources then scanner/parser will not be generated.
The JastAdd Gradle plugin tries to rebuild whenever you make changes that could
affect generated code, but in some cases it does not work perfectly. To ensure
a full rebuild you can run ./gradlew clean
, or pass the --rerun-tasks
option to Gradle when building your project.
If an AST class has been deleted, it is usually necessary to run ./gradlew clean
to ensure that the generated class is removed.
The JastAdd Gradle plugin sets a default JastAdd version for code generation,
but you can change this by specifying any version you would like to use. Just
add a dependency for the jastadd2
configuration in your build script:
dependencies {
jastadd2 "org.jastadd:jastadd:2.3.0"
}
Configuring a modular build requires that you provide module specifications to the JastAdd Gradle plugin. The module specifications are used to determine which files need to be passed to JastAdd for code generation.
Modules are typically declared in files named jastadd_modules
. The location
of these module files is specified using the modules
command in the jastadd
configuration. For example:
jastadd {
configureModuleBuild() // Add default build tasks for a modular build.
modules "jastadd_modules", "jastadd/java4/jastadd_modules" // Load these modules.
module "my module" // Select module to build.
}
A module file can look like this:
module("my module") {
imports "java8 frontend" // This module depends on "java8 frontend" from ExtendJ.
moduleName "My Module 1.0"
moduleVariant "frontend"
java {
basedir "src/main/java/"
include "**/*.java"
}
jastadd {
include "grammar/*.ast"
include "frontend/*.jadd"
include "frontend/*.jrag"
}
scanner {
include "scanner/Scanner.flex"
}
parser {
include "parser/Parser.parser"
}
}
The imports
statement is used to add a dependency to some other module.
The included files from all transitive dependencies are included into the
current module files.
The JastAdd Gradle plugin by default adds these options to the JastAdd code generation command:
--rewrite=cnta
--safeLazy
--visitCheck=false
--cacheCycle=false
These default options can be changed by specifying the jastaddOptions
configuration setting inside the jastadd
block in build.gradle
. For example:
jastadd {
configureModuleBuild()
modules {
module ("example") {
jastadd {
include '*.ast'
}
}
}
module = "example"
astPackage = "example"
jastaddOptions = [ "--rewrite=none", "--visitCheck=true" ]
}
Some example projects using the JastAdd Gradle plugin: