Thrift gradle plugins

Overview

This repository contains two "opiniated" gradle plugins to work with Thrift:

• thrift-build-plugin: extracts thrift schemas from configured sources and generates the files needed by your project.

  This plugin is meant for projects that consume thrift schemas. It is designed for seamless integration to the build process of your component. It draws inspiration from protobuf-gradle-plugin (but without support for Android). I also tried to use the most recent features of gradle (f.ex. task configuration avoidance).

• thrift-distribution-plugin (TODO): generates multiple distributions of thrift API

  This plugin is meant for projects that hold centralized thrift schemas and needs to produce its content generated to various languages and in various formats.

Both plugins are designed to be as consistent as possible with the java build and distribution plugins.

How to use the plugins

This repository was meant as an exercise for me to get familiar with gradle. I have therefore chosen not to publish it to the central gradle repository. You are welcome to branch off from the repo and let me know if there is a bug in the implementation but I won't offer any support. You can publish the plugin to the package repository of your choice and apply it to your plugins

What do I get

Thrift build plugin

The plugin allows you to download, extract and generate code for the thrift schemas needed by your project with minimal configuration needed.

The thrift build plugin exposes two tasks per SourceSet:

• compile#SourceSetName#Thrift or compileThrift for "main": generates code for thrift schemas specified.

• extract#SourceSetName#Thrift or extractThrift for "main": extract schemas from the dependencies you configured (more on that below).

The plugin will attempt to add the operations to your build DAG before the compilation in the language you configured.

For example, for code generation to java and "main" the following DAG is generated:

    (extractThrift ->) compileThrift -> compileJava

The extract task is only included if schemas are downloaded from external dependencies.

If compile#language# is not found, compileThrift should be explicitly added to the list of tasks to run and the generated data can be found in the SourceSet inside the SourceDirectorySet called thriftCompiled.

Examples

You can find examples of how to use the plugins in the resource folder of my functional tests (src/test/kotlin/resources/builds).

How to configure the plugins

The thrift build plugin

The plugin consists of three components:

• an extension called thrift: you use it to configure the code generation by thrift. For example, which executable to use, which language to generate, where to put the schemas downloaded and the data generated by thrift.

thrift {
  executable {
      // configure the thrift compiler. It can point to a file to the file system or an external dependency to download.
      // if not specified, the plugin will simply execute "thrift [options] file"
      artifact = file("src/main/resources/thrift")

      // which options to pass to the thrift compiler (f.ex. debug, verbose)
      options = listOf("-v")
  }

  // Each SourceSet can configure the code it generates through a CompileExtension
  sourceSetOptions {
      named("main") {
          // the language to generate to. default: java
          language = "java"

          // a filter that specifies which schemas to generate (compilation is recursive)
          // default: everything i.e. "**/*.thrift" 
          files = listOf("**/service.thrift")

          // the generate options. default: empty list
          options = listOf("fullcamel", "beans")

          // the output directory for the generated files. default: see below
          outputDirectory = file("src/main/thrift/compiled")
      }
  }
  
  // if you download thrift schemas from an external dependency (more on that below) you can configure the directory 
  // where the downloaded data is saved. 
  // default: "buildDir/download/trhift/#SourceSetName#".
  extractOutputDirectory = file("src/main/thrift/schemas")

  // the parent directory to use for all files generted by thrift. Only relevant if no outputDirectory is configured 
  // by a compiled extension. The generated files will be saved under "compileOutputDirectory/#SourceSetName#".
  // default: "buildDir/generated-sources/thrift"
  compileOutputDirectory = file("src/main/thrift/compiled")
}

• a source directory set called thrift: each SourceSet (f.ex. "main") is extended with a SourceDirectorySet for thrift schemas.

  If your schemas are part of the repository (as opposed to downloaded from an external dependency) you can simply add their location to the aforementioned SourceDirectorySet and they will be added to the scope of thrift code generation.

sourceSets {
    main {
        thrift {
            srcDir(file("src/main/thrift"))
        }
    }
}

• _dependency configurations called thrift for main and #SourceSetName#Thrift for the rest: this allows you to specify thrift schemas from external dependencies that will be downloaded and decompressed (if .zip, .tar) before being added to the schemas to generate.

They work the same way as other dependencies like implementation:

dependencies {
    // NOTE: the plugin does not provide you with dependency to thriftlib. You need to add it if you compile java services.
    implementation("org.apache.thrift:libthrift:0.13.+")
    
    // the schemas to generate
    thrift("com.pjcampi.thrift:schemas:0.1.0")
    testThrift(files("src/test/resources/schemas.zip"))
}