sbt-avro

Overview

sbt-avro is a sbt plugin for generating Java sources for Avro schemas. It also supports referencing schemas from different files.

Usage

Installing the plugin

Add the plugin according to the sbt documentation.

For instance, add the following lines to project/plugins.sbt:

addSbtPlugin("com.github.sbt" % "sbt-avro" % "3.5.0")

Enable the plugin in your build.sbt and select the desired avro version to use:

enablePlugins(SbtAvro)
avroVersion := "1.12.0"

Config

An avro configuration will be added to the project. Libraries defined with this scope will be loaded by the sbt plugin to generate the avro classes.

Settings

Project settings

Name	Default	Description
avroAdditionalDependencies	avro-compiler % avroVersion % "avro", avro % avroVersion % "compile"	Additional dependencies to be added to library dependencies.
avroCompiler	com.github.sbt.avro.AvroCompilerBridge	Sbt avro compiler class.
avroCreateSetters	true	Generate setters.
avroEnableDecimalLogicalType	true	Use java.math.BigDecimal instead of java.nio.ByteBuffer for logical type decimal.
avroFieldVisibility	public	Field visibility for the properties. Possible values: private, public.
avroOptionalGetters	false (requires avro 1.10+)	Generate getters that return Optional for nullable fields.
avroStringType	CharSequence	Type for representing strings. Possible values: CharSequence, String, Utf8.
avroUseNamespace	false	Validate that directory layout reflects namespaces, i.e. com/myorg/MyRecord.avsc.
avroVersion	1.12.0	Avro version to use in the project.

Scoped settings (Compile/Test)

Name	Default	Description
avroGenerate / target	sourceManaged / compiled_avro / $config	Source directory for generated .java files.
avroSource	sourceDirectory / $config / avro	Default Avro source directory for *.avsc, *.avdl and *.avpr files.
avroSpecificRecords	Seq.empty	List of fully qualified Avro record class names to recompile with current avro version and settings.
avroDependencyIncludeFilter	Compile: avro classifier artifacts in Avro config Test: nothing	Filter for including modules containing avro dependencies.
avroUmanagedSourceDirectories	Seq(avroSource)	Unmanaged Avro source directories, which contain manually created sources.
avroUnpackDependencies / excludeFilter	HiddenFileFilter	Filter for excluding avro specification files from unpacking.
avroUnpackDependencies / includeFilter	AllPassFilter	Filter for including avro specification files to unpack.
avroUnpackDependencies / target	sourceManaged / avro / $config	Target directory for schemas packaged in the dependencies
packageAvro / artifactClassifier	Some("avro")	Classifier for avro artifact
packageAvro / publishArtifact	false	Enable / Disable avro artifact publishing

Scoped Tasks (Compile/Test)

Name	Description
avroGenerate	Generate Java sources for Avro schemas. This task is automatically executed before compile.
avroUnpackDependencies	Unpack avro schemas from dependencies. This task is automatically executed before avroGenerate.
packageAvro	Produces an avro artifact, such as a jar containing avro schemas.

Examples

For example, to change the Java type of the string fields, add the following lines to build.sbt:

avroStringType := "String"

If you depend on an artifact with previously generated avro java classes with string fields as CharSequence, you can recompile them with String by also adding the following

Compile / avroSpecificRecords += "com.example.MyAvroRecord" // lib must be added in the avro scope

Packaging Avro files

Avro sources (*.avsc, *.avdl and *.avpr files) can be packaged in a separate jar with the source type and avro classifier by running packageAvro.

By default, sbt-avro does not publish this. You can enable it with

Compile / packageAvro / publishArtifact := true

Declaring dependencies

You can specify a dependency on an avro source artifact that contains the schemas like so:

libraryDependencies += "org" % "name" % "rev" % "avro" classifier "avro"

If some avro schemas are not packaged in a source/avro artifact, you can update the avroDependencyIncludeFilter setting to instruct the plugin to look for schemas in the desired dependency:

libraryDependencies += "org" % "name" % "rev" % "avro" // module containing avro schemas
Compile / avroDependencyIncludeFilter := configurationFilter("avro") && moduleFilter(organization = "org", name = "name")

If some artifact is meant to be used in the test scope only, you can do the following

libraryDependencies += "org" % "name" % "rev" % "avro" classifier "avro"
Compile / avroDependencyIncludeFilter ~= { old => old -- moduleFilter(organization = "org", name = "name") }
Test / avroDependencyIncludeFilter := configurationFilter("avro") && moduleFilter(organization = "org", name = "name")

License

This program is distributed under the BSD license. See the file LICENSE for more details.

Credits

sbt-avro is maintained by the sbt Community. The initial code was based on a similar plugin: sbt-protobuf. Feel free to file issues or pull requests.

Contributors

• Ashwanth Kumar
• Ben McCann
• Brennan Saeta
• Daniel Lundin
• Juan Manuel Caicedo
• Julian Peeters
• Jérôme Wacongne
• Kellen Dye
• Martin Achenbach
• Michel Davit
• Mārtiņš Kalvāns
• Neville Li
• Oskar Jung
• Przemysław Dubaniewicz
• Ryan Koval
• Saket Kumar
• Vince Tse