7467925aa1
* Fetch status.proto from remote, simplify JS gRPC codegen Fetch the `status.proto` file (part of the standard gRPC distribution) from a distribution channel. _Moreover_, use the recently introduced `proto_gen` rule to simplify how the gRPC code for the Node.js bindings are generated (and remove the need to have `google/rpc/status.proto` locally in the repository. * Add plugin_runfiles option to proto_gen This allows use to add additional files to the bazel sandbox so that plugins can refer to them. This will subsequently be used by the protoc-gen-doc plugin. Also, pass the plugin options via --name_opt parameter. * Add missing status.proto dependency /language-support/java and /ledger * Build proto docs using the proto_gen rule To make this work, I had to turn on the bazel build flag `--protocopt=--include_source_info` because we cannot turn enable this flag only for specific build rules. * Make /ledger-api/grpc-definitions:docs public again * Revert to the old style of passing plugin arguments to --name_out=options:path * Suppress output of unzipping * Fix link for google.rpc.Status in proto-docs |
||
|---|---|---|
| .. | ||
| da | ||
| src | ||
| BUILD.bazel | ||
| README.md | ||
DAML-LF archive
This component contains the .proto definitions specifying the format
in which DAML-LF packages are stored -- the DAML-LF archive.
The entry point definition is Archive in da/daml_lf.proto. Archive
contains some metadata about the actual archive (currently the hashing
function and the hash), and then a binary blob containing the archive.
The binary blob must be an ArchivePayload -- we keep it in binary form
to facilitate hashing, signing, etc. The encoding and decoding of the
payload is handled by Haskell and Java libraries in daml-core-package,
so that consumers and producers do not really need to worry about it.
ArchivePayload is a sum type containing the various DAML-LF versions
supported by the DAML-LF archive. Currently we have two versions:
DAML-LF-0, which is the legacy DAML core;DAML-LF-1, which is the first version of DAML-LF as specified by https://github.com/DACH-NY/da/blob/master/daml-foundations/daml-tools/docs/daml-lf-specification/source/index.rst.
Building
It produces two libraries containing code to encode / decode such definition, a Haskell one and a Java one:
$ bazel build //daml-lf/archive:daml_lf_haskell_proto
$ bazel build //daml-lf/archive:daml_lf_java_proto
Editing the .proto definitions
When editing the proto definitions, you must make sure to not change them in a backwards-incompatible way. To make sure this doesn't happen:
- DO NOT delete message fields;
- DO NOT change the number of a message field or an enum value;
- DO NOT change the type of a message field;
Note that "fields" include oneof fields. Also note that the "don't
delete fields" rule is there not because they introduce a backwards
incompatible change, but rather because after a field has been deleted
another commiter might redefine it with a different type without
realizing.
What is OK is renaming message fields while keeping the number and semantics unchanged. For example, if you have
message Foo {
bytes blah = 1;
}
it's OK to change it to
message Foo {
// this field is deprecated -- use baz instead!
bytes blah_deprecated = 1;
string baz = 2;
}
Conversion from the .proto to AST
The .proto definitions contain the serialized format for DAML-LF
packages, however the code to convert from the .proto definitions to
the actual AST lives elsewhere.