d68d3eb74a
* Freeze DAML-LF 1.8
Two minor points that I did not mention in the previous PR:
We also include the renaming of structural records to `struct` and the
renaming of `Map` to `TextMap`.
There are some minor changes around the LF encoder tests which need to
be able to emit package metadata properly so I’ve added it to the
parser. Sorry for not splitting that out.
Following the process used for the DAML-LF 1.7 release, this does not
yet include the frozen proto file.
changelog_begin
- [DAML-LF] Release DAML-LF 1.8:
* Rename structural records to ``Struct``. Note that
structural records are not exposed in DAML.
* Rename ``Map`` to ``TextMap``.
* Add type synonyms. Note that type synonyms are not serializable.
* Add package metadata, i.e., package names and versions.
Note that the default output of ``damlc`` is stil DAML-LF 1.7. You
can produce DAML-LF 1.8 by passing ``--target=1.8``.
changelog_end
* Update encoder
* Update java codegen tests
* Update comment in scala codegen
* Handle TSynApp in interface reader
* Bump lf_stable_version to 1.7
* Fix kvutils tests
|
||
|---|---|---|
| .. | ||
| src | ||
| archive.bzl | ||
| 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. All the
proto definitions are kept in the directory
src/protorotobuf/com/digitalasset/daml_lf_dev/
The entry point definition is Archive in
src/protorotobuf/com/digitalasset/daml_lf_dev/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 major versions:
DAML-LF-0, which is the deprecated legacy DAML core;DAML-LF-1, which is the first version of DAML-LF as specified by https://github.com/digital-asset/daml/blob/master/daml-lf/spec/daml-lf-1.rst.
Snapshot versions
The component contains also an arbitrary number of snapshots of the
protobuf definitions as they were as the time a particular version of
DAML-LF was frozen. Those snapshots are kept in the directories
src/protorotobuf/com/digitalasset/daml_lf_x_y/, where x.y is a
already frozen DAML-LF version. A snapshot for version x.y can be
used to read any DAML-LF version from 1.0 to x.y without suffering
breaking changes (at the generated code level) often introduced in the
current version.
Building
It produces several libraries containing code to encode / decode such definition, a Haskell one, and several Java ones:
$ bazel build //daml-lf/archive:daml_lf_archive_haskell_proto
$ bazel build //daml-lf/archive:daml_lf_dev_archive_java_proto
$ bazel build //daml-lf/archive:daml_lf_1_6_archive_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.