<init>

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

1. 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.
2. Validate the schema and resolve references between types.
3. 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.
4. 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.

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.

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.

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.