Simplify plugin configuration

[JojOatXGME]

Pull Request Details

Sorry, but I got carried away over the weekend. This PR greatly simplifies the configuration of the plugin in a backward compatible manner (although I deprecated some properties). You may pick individual changes as you which, they are separated into semantically coherent commits.

The new minimal configuration looks like this:

grammarKit {
    lexerSource = layout.projectDirectory.file("<path to *.flex file>")
    parserSource = layout.projectDirectory.file("<path to *.bnf file>")
}

This configuration is mostly equivalent to the following configuration, as it would have to be written manually before my changes:

sourceSets {
    main {
        java {
            srcDir(layout.buildDirectory.dir("generated/sources/grammarkit-lexer/java/main"))
            srcDir(tasks.generateParser)
        }
    }
}

tasks {
    generateLexer {
        sourceFile = layout.projectDirectory.file("<path to *.flex file>")
        targetOutputDir = layout.buildDirectory.dir("generated/sources/grammarkit-lexer/java/main/<pkg>")
        purgeOldFiles = true
    }

    generateParser {
        sourceFile = layout.projectDirectory.file("<path to *.bnf file>")
        targetRootOutputDir = layout.buildDirectory.dir("generated/sources/grammarkit-parser/java/main")
        pathToParser = "<relative path to parser java file>"
        pathToPsiRoot = "<relative path to psi files>"
        purgeOldFiles = true
    }

    compileJava {
        dependsOn(generateLexer)
    }
}

Description

The new, much shorter configuration is possible due to the following individual changes:

• Allow GenerateLexerTask to create a subdirectory for the package. This allows us to give the output directory to SourceDirectorySet.srcDir directly. The new behavior is applied if the new property targetRootOutputDir is used, which replaces targetOutputDir. (362e9fc)
• Make GenerateParserTask.pathToParser and pathToPsiRoot optional. These properties are not needed in most cases, as they are only restricting purgeOldFiles to specific sub-paths of the output directory. (05af194)
• Make purging stale files the default. Without purging stale files, incremental builds may run into errors. When the build cache is enabled, even :clean may not be able to fix such issues. For backwards compatibility, the new behavior is only applied when the previously mentioned properties (which were mandatory) are no-longer used. (87ac815)
• Add default values for targetRootOutputDir in both tasks. This simplifies the configuration and encourages people to use separate output directories for each task. Overlapping output directories are discouraged by Gradle and may cause issues with the build cache. (a8c60bd)
• Introduce lexerSource and parserSource in the plugin extension. These properties make it possible to specify the source files without having to configure the individual tasks directly. When this property is used, the corresponding tasks are also added as sources to the main source set. (86022b4)

I also revised some existing tests in commit a204e86 and 5228085, but this doesn't have much impact on the other changes. I updated the changelog in commit 1a13907.

Related Issue

• resolves Make pathToParser and pathToPsiRoot optional #178

Motivation and Context

This change makes using the plugin much easier.

• You no-longer have to manually configure the directory for the generated files
• Stale files are purged by default, preventing build failures in incremental builds
• Duplicating information from the source files in the build configuration is no-longer necessary
  • The package of the lexer
  • The package of the parser
  • The class name of the parser
  • The package containing the PSI classes
• You no-longer have to set up task dependencies manually

How Has This Been Tested

I created various “unit” tests to test my changes. (I tripled the total amount of unit tests in this repository.) Furthermore, I tried out the new version with, and without simplifying the configuration on the nix-idea plugin.

Types of changes

• Docs change / refactoring / dependency upgrade
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change) – but I deprecated stuff

Checklist

• I have read the CONTRIBUTING document.
• My code follows the code style of this project. – Where do I get the code style?
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

[JojOatXGME]

I don't think the build failure on GitHub Actions is caused by my changes. The error actually looks quite familiar to me. I think I once fixed the same issue at JetBrains/gradle-changelog-plugin#170. 😅

[JojOatXGME]

FYI, I also asked at gradle/gradle#9021 (comment) whether it is possible to tell Gradle to clean the output directory for you. Unfortunately, it doesn't seem to be possible right now.

[JojOatXGME]

I rebased this pull request on the current master after #187 has been merged to fix the build.