wire-compiler / com.squareup.wire.schema / WireRun

WireRun

data class WireRun

An invocation of the Wire compiler. Each invocation performs the following operations:

Read source .proto files directly from the file system or from archive files (ie. .jar and .zip files). This will also load imported .proto files from either the sourcePath or protoPath. The collection of loaded type declarations is called a schema.
Validate the schema and resolve references between types.
Optionally prune the schema. This builds a new schema that is a subset of the original. The new schema contains only types that are both transitively reachable from treeShakingRoots and not in treeShakingRubbish.
Call each target. It will generate sources for protos in the sourcePath that are in its Target.includes, that are not in its Target.excludes, and that haven't already been emitted by an earlier target.

Source Directories and Archives

The sourcePath and protoPath lists contain locations that are of the following forms:

Locations of .proto files.
Locations of directories that contain a tree of .proto files. Typically this is a directory ending in src/main/proto.
Locations of .zip and .jar archives that contain a tree of .proto files. Typically this is a .jar file from a Maven repository.

When one .proto message imports another, the import is resolved from the base of each location and archive. If the build is in the unfortunate situation where an import could be resolved by multiple files, whichever was listed first takes precedence.

Although the content and structure of sourcePath and protoPath are the same, only types defined in sourcePath are used to generate sources.

Matching Packages, Types, and Members

The treeShakingRoots, treeShakingRubbish, Target.includes and Target.excludes lists contain strings that select proto types and members. Strings in these lists are in one of these forms:

Package names followed by .*, like squareup.dinosaurs.*. This matches types defined in the package and its descendant packages. A lone asterisk * matches all packages.
Fully-qualified type names like squareup.dinosaurs.Dinosaur. Types may be messages, enums, or services.
Fully-qualified member names like squareup.dinosaurs.Dinosaur#name. These are type names followed by # followed by a member name. Members may be message fields, enum constants, or service RPCs.

It is an error to specify mutually-redundant values in any of these lists. For example, the list [squareup.dinosaurs, squareup.dinosaurs.Dinosaur] is invalid because the second element is already matched by the first.

Every element in each lists must apply to at least one declaration. Otherwise that option is unnecessary and a possible typo.

Composability

There are many moving parts in this system! For most applications it is safe to use sourcePath and targets only. The other options are for the benefit of large and modular applications.

Use protoPath when one proto module depends on another proto module.

These .proto files are used for checking dependencies only. It is assumed that the sources for these protos are generated elsewhere.

Use tree shaking to remove unwanted types.

Tree shaking can be used to create a small-as-possible generated footprint even if the source declarations are large. This works like ProGuard and other code shrinking compilers: it allows you to benefit from a shared codebase without creating a large artifact.

Use multiple targets to split generated code across multiple programming languages.

If your project is already using generated Java, it’s difficult to switch to generated Kotlin. Instead of switching everything over at once you can use multiple targets to switch over incrementally. Targets consume their types; subsequent targets get whatever types are left over.

Constructors

<init>

WireRun(sourcePath: List<Location>, protoPath: List<Location> = listOf(), treeShakingRoots: List<String> = listOf("*"), treeShakingRubbish: List<String> = listOf(), since: String? = null, until: String? = null, targets: List<Target>, proto3Preview: Boolean = false)

An invocation of the Wire compiler. Each invocation performs the following operations:

Properties

proto3Preview	`val proto3Preview: Boolean` True to build proto3 artifacts. This is unsupported and does not work.
protoPath	`val protoPath: List<Location>` Sources `.proto` files for this task to use when resolving references.
since	`val since: String?` The exclusive lower bound of the version range. Fields with `until` values greater than this are retained.
sourcePath	`val sourcePath: List<Location>` Source `.proto` files for this task to generate from.
targets	`val targets: List<Target>` Action to take with the loaded, resolved, and possibly-pruned schema.
treeShakingRoots	`val treeShakingRoots: List<String>` The roots of the schema model. Wire will prune the schema model to only include types in this list and the types transitively required by them.
treeShakingRubbish	`val treeShakingRubbish: List<String>` Types and members that will be stripped from the schema model. Wire will remove the elements themselves and also all references to them.
until	`val until: String?` The inclusive upper bound of the version range. Fields with `since` values less than or equal to this are retained.

Functions

execute

fun execute(fs: FileSystem = FileSystems.getDefault(), logger: WireLogger = ConsoleWireLogger()): Unit