KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

sbt-avrohugger

★ 135 Open GitHub ↗

sbt plugin for generating Scala sources for Apache Avro schemas and protocols.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# sbt-avrohugger

sbt plugin for generating Scala case classes and ADTs from Apache Avro schemas, idls, datafiles, and protocols.

* Plugin for sbt 1 and 2
* Parses Schemas and IDLs with Avro 1.12
* Generates Code Compatible with Avro 1.11, 1.12, and Scala 2, 3
* Depends on [avrohugger](https://github.com/julianpeeters/avrohugger)

Install the plugin
---------------------------------------

Add the following lines to the file `myproject/project/plugins.sbt` in your
project directory:

addSbtPlugin("com.julianpeeters" % "sbt-avrohugger" % "2.17.1")

Usage
-----

The following tasks and settings are automatically imported to your build:

### Tasks:

| Name                       | Description                                                                                     |
| -------------------------- | -----------------------------------------------------------------------------------------------:|
| `avroScalaGenerate`        |  Compiles the Avro files into Scala case classes.                                               |
| `avroScalaGenerateSpecific`|  Compiles the Avro files into Scala case classes implementing `SpecificRecord`.                 |

#### Compile

Wire the tasks into `compile` in your `build.sbt`:

e.g.: `Compile / sourceGenerators += (Compile / avroScalaGenerate).taskValue`

By [default](https://github.com/julianpeeters/sbt-avrohugger#settings), the plugin looks for Avro files in `src/main/avro` and generates Scala files in `$sourceManaged`, e.g., `target/out/jvm/scala-3.3.7/myprojectname/src_managed/main/compiled_avro/` (to choose different locations, please see [Changing Settings](https://github.com/julianpeeters/sbt-avrohugger#changing-settings)).

#### Test

And/Or wire the tasks into the `Test` config, putting Avro files in `src/test/avro`:

e.g.: `Test / sourceGenerators += (Test / avroScalaGenerate).taskValue`

#### Manually

To run the tasks manually, please see [Changing Settings](https://github.com/julianpeeters/sbt-avrohugger#changing-settings) or the [sbt docs](http://www.scala-sbt.org/1.x/docs/Howto-Customizing-Paths.html#Add+an+additional+source+directory) in order to ensure the compiler will be able to find the generated files.

#### Watch Avro Files

To enable file-watching for avro files, e.g. in `~compile`, use:

e.g.: `watchSources ++= ((Compile / avroSourceDirectory).value ** "*.avdl").get`

### Settings:

_**Standard Settings**_

| Name                       | Default                               | Description                              |
| -------------------------- | -------------------------------------:| ----------------------------------------:|
| `avroSourceDirectories`    | `Seq("src/main/avro")`              | List of paths containing `*.avsc`, `*.avdl`, and/or `*.avro` files.|
| `avroScalaSource`          | `$sourceManaged/main/compiled_avro` | Path for the generated `*.scala` or `*.java`  files.|
| `avroScalaCustomTypes`     | `Standard.defaultTypes`             | Customizable Type Mapping.|
| `avroScalaCustomNamespace` | `Map.empty[String, String]`         | Map for reassigning namespaces.|

_**SpecificRecord Settings**_

| Name                               | Default                               | Description                                                      |
| ---------------------------------- | -------------------------------------:| ----------------------------------------------------------------:|
| `avroSpecificSourceDirectories`    | `Seq("src/main/avro")`              | Path containing `*.avsc`, `*.avdl`, and/or `*.avro` files. |
| `avroSpecificScalaSource`          | `$sourceManaged/main/compiled_avro` | Path for the generated `*.scala` or `*.java`  files.         |
| `avroScalaSpecificCustomTypes`     | `SpecificRecord.defaultTypes`             | Customizable Type Mapping.|
| `avroScalaSpecificCustomNamespace` | `Map.empty[String, String]`         | Map for reassigning namespaces.                                  |

Changing Settings
-----------------

Settings for each format's task can be extended/overridden by adding lines to your `build.sbt` file.

E.g., to change how classes of `SpecificRecords` format are generated, use:

```scala    
Compile / avroSpecificSourceDirectories += (Compile / sourceDirectory).value / "myavro"

Compile / avroSpecificScalaSource := new java.io.File("myScalaSource")

Compile / avroScalaSpecificCustomNamespace := Map("my.example"->"my.overridden.ex", "test.*" -> "wildcarded")

Compile / avroScalaSpecificCustomTypes := {
  avrohugger.format.SpecificRecord.defaultTypes.copy(
    array = avrohugger.types.ScalaVector)
}
```

* `record` can be assigned to `ScalaCaseClass` and `ScalaCaseClassWithSchema` (with schema in a companion object)
* `array` can be assigned to `ScalaSeq`, `ScalaArray`, `ScalaList`, and `ScalaVector`
* `enum` can be assigned to `JavaEnum`, `Scala3Enum`, `ScalaCaseObjectEnum`, `EnumAsScalaString`, and `ScalaEnumeration`
* `fixed` can be assigned to , `ScalaCaseClassWrapper` and `ScalaCaseClassWrapperWithSchema`(with schema in a companion object)
* `union` can be assigned to `OptionEitherShapelessCoproduct` (incompatible with `Specific`), `OptionalShapelessCoproduct` and `OptionScala3UnionType` (incompatible with `Standard`)
* `int`, `long`, `float`, `double` can be assigned to `ScalaInt`, `ScalaLong`, `ScalaFloat`, `ScalaDouble`
* `date` logical type can be assigned to `JavaTimeLocalDate` and `JavaSqlDate`
* `timestamp-millis` logical type can be assigned to `JavaTimeInstant` and `JavaSqlTimestamp`
* `uuid` logical type can be assigned to `UUID`
* `decimal` can be assigned to e.g. `ScalaBigDecimal(Some(BigDecimal.RoundingMode.HALF_EVEN))` and `ScalaBigDecimalWithPrecision(None)` (via Shapeless Tagged Types)
* `protocol` can be assigned to `ScalaADT` and `NoTypeGenerated` (see [Protocol Support](https://github.com/julianpeeters/avrohugger#protocol-support))

Datatypes
---------

Supports generating case classes with arbitrary fields of the following
datatypes: see [avrohugger docs - supported datatypes](https://github.com/julianpeeters/avrohugger#supports-generating-case-classes-with-arbitrary-fields-of-the-following-datatypes)

Testing
-------

Please run unit tests in `src/test/scala` with `+test`, and integration tests
in `src/sbt-test` with `+scripted sbt-avrohugger/*`, or, e.g. `+scripted sbt-avrohugger/specific`.

Credits
-------

`sbt-avrohugger` is based on [sbt-avro](https://github.com/sbt/sbt-avro) originally developed by [Juan Manuel Caicedo](http://cavorite.com/), and depends on [avrohugger](https://github.com/julianpeeters/avrohugger).

Contributors
------------

| | | |
| :--- | :--- | :--- |
| [Marius Soutier](https://github.com/mariussoutier) [Vince Tse](https://github.com/vtonehundred) [Saket](https://github.com/skate056) [Raúl Raja Martínez](https://github.com/raulraja) [Marco Stefani](https://github.com/inafets) [Sacha Barber](https://github.com/sachabarber) [sullis](https://github.com/sullis) [Alexandre Bertails](https://github.com/betehess) [Alexander Khotyanov](https://github.com/aksharp) [Kevin](https://github.com/kewitschka) | [Brennan Saeta](https://github.com/saeta) [Jerome Wacongne](https://github.com/ch4mpy) [Jon Morra](https://github.com/jon-morra-zefr) [Paul Snively](https://github.com/PaulAtBanno) [Diego E. Alonso Blas](https://github.com/diesalbla) [Andrew Gustafson](https://github.com/agustafson) [Jonas Grabber](https://github.com/jobegrabber) [mcenkar](https://github.com/mcenkar) [Andrzej Ressel](https://github.com/andrzejressel) | [Daniel Lundin](https://github.com/dln) [Ryan Koval](http://github.ryankoval.com) [Simonas Gelazevicius](https://github.com/simsasg) [Zach Cox](https://github.com/zcox) [Chris Albright](https://github.com/chrisalbright) [Fede Fernández](https://github.com/fedefernandez) [natefitzgerald](https://github.com/natefitzgerald) [Angel Sanadinov](https://github.com/sndnv) [Mikołaj Jakubowski](https://github.com/mkljakubowski)

#### Fork away, just make sure the tests pass before you send a pull request.

#### Criticism is appreciated.

sbt-avrohugger

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README