Protocompile

A Resolver is the mechanism the compiler uses to locate and load compilation inputs and their dependencies. It acts as the bridge between the compiler and your file system, network, or memory.

A Resolver can return several types of data for a given query, which determines how much work the compiler must do:

• Source code: The compiler will perform full parsing and compilation.
• AST: The compiler skips the parsing step and proceeds with the rest of the compilation.
• Descriptor proto: The compiler skips parsing and starts at the linking phase.
• Descriptor: The compiler uses the descriptor as-is, performing no further work.

A SearchResult contains information about a proto file. Only one field should be set. If multiple fields are set, the compiler follows a specific priority order (from highest to lowest preference):

1. Desc (protoreflect.FileDescriptor): A fully linked descriptor. If present, the compiler does minimal work.
2. ParseResult (parser.Result): Packages both an AST and a descriptor. This is more efficient than an AST and provides better error messages than a raw descriptor.
3. Proto (*descriptorpb.FileDescriptorProto): A descriptor proto. The compiler will link this with dependencies.
4. AST (*ast.FileNode): The abstract syntax tree. The compiler will convert this to a descriptor proto.
5. Source (io.Reader): Raw source code. The compiler will parse this into an AST.

To create a basic compiler that resolves files from the local file system based on the current working directory, use the protocompile.Compiler struct with a protocompile.SourceResolver.

By default, this minimal configuration:

• Uses parallelism equal to the number of detected CPU cores.
• Does not generate source code info in the resulting descriptors.
• Fails fast at the first error encountered.

compiler := protocompile.Compiler{
    Resolver: &protocompile.SourceResolver{},
}

The Compiler is the primary entrypoint for turning protobuf source files (or intermediate representations like ASTs or descriptor protos) into fully linked descriptors.

To use it, you must provide a Resolver which handles locating source code and dependencies. The compilation process follows five steps: parsing into an AST, converting AST to descriptor protos, linking descriptors, interpreting options, and computing source code information.

// Example usage (requires a Resolver implementation)
compiler := &protocompile.Compiler{
    Resolver: myResolver,
}

// Compile specific files
files, err := compiler.Compile(ctx, "path/to/file.proto", "path/to/another.proto")
if err != nil {
    // handle error
}
// Use the resulting linker.Files

The WithStandardImports function wraps an existing Resolver and adds support for standard Google protobuf imports (like descriptor.proto).

Note on Extension Declarations: As of v0.14.0, the standard imports returned by this function do not include extension declarations (e.g., in descriptor.proto) because they are only available in source and not in the embedded descriptors of the Protobuf Go module. If you need these declarations to prevent illegal re-definitions of custom features, use wellknownimports.WithStandardImports instead.

// Wrap your existing resolver with standard imports
resolver := protocompile.WithStandardImports(myBaseResolver)

The SourceResolver resolves file names by returning their raw source code.

• ImportPaths: If provided, all file paths are searched relative to these paths. If empty, paths are relative to the current working directory.
• Accessor: An optional function to retrieve file contents. If nil, it defaults to os.Open.

resolver := &protocompile.SourceResolver{
    ImportPaths: []string{"./proto", "/usr/local/include"},
    // Accessor is optional; defaults to os.Open
}

If a Resolver implementation panics during compilation, the Compiler will recover and return a PanicError.

To access the details of the panic (such as the file being processed and the stack trace), you should use errors.As to check for a *protocompile.PanicError.

var panicErr *protocompile.PanicError
if errors.As(err, &panicErr) {
    fmt.Printf("Panic in file %s: %v\n", panicErr.File, panicErr.Value)
    fmt.Printf("Stack trace: %s\n", panicErr.Stack)
}