github.com/jhump/protocompile@v0.0.0-20221021153901-4f6f732835e8/linker/doc.go (about)

     1  // Package linker contains logic and APIs related to linking a protobuf file.
     2  // The process of linking involves resolving all symbol references to the
     3  // referenced descriptor. The result of linking is a "rich" descriptor that
     4  // is more useful than just a descriptor proto since the links allow easy
     5  // traversal of a protobuf type schema and the relationships between elements.
     6  //
     7  // Files
     8  //
     9  // This package uses an augmentation to protoreflect.FileDescriptor instances
    10  // in the form of the File interface. There are also factory functions for
    11  // promoting a FileDescriptor into a linker.File. This new interface provides
    12  // additional methods for resolving symbols in the file.
    13  //
    14  // This interface is both the result of linking but also an input to the linking
    15  // process, as all dependencies of a file to be linked must be provided in this
    16  // form. The actual result of the Link function is a super-interface of File:
    17  // Result. The linker.Result interface provides even more functions, which are
    18  // needed for subsequent compilation steps: interpreting options and generating
    19  // source code info.
    20  //
    21  // Symbols
    22  //
    23  // This package has a type named Symbols which represents a symbol table. This
    24  // is usually an internal detail when linking, but callers can provide an
    25  // instance so that symbols across multiple compile/link operations all have
    26  // access to the same table. This allows for detection of cases where multiple
    27  // files try to declare elements with conflicting fully-qualified names or
    28  // declare extensions for a particular extendable message that have conflicting
    29  // tag numbers.
    30  //
    31  // The calling code simply uses the same Symbols instance across all compile
    32  // operations and if any files processed have such conflicts, they can be
    33  // reported.
    34  package linker