digital-asset/daml
1
1
Fork 0
mirror of https://github.com/digital-asset/daml.git synced 2024-09-20 09:17:43 +03:00
Code Issues Projects Releases Wiki Activity
ed431b4717
daml/daml-lf/archive
History
Neil Mitchell ed431b4717
Move Tuple and Either types to DA.Types (#1099) 
* Add a helper function to qualify things with respect to a module

* Supress some warnings I saw when building

* Move Tuple* and Either to daml-prim:DA.Types, so they have a nice name for Java users (instead of GHC.Tuple or DA.Internal.Prelude)

* Add copyright header

* Update daml-foundations/daml-ghc/daml-prim-src/DA/Types.daml

Co-Authored-By: Martin Huschenbett <martin.huschenbett@posteo.me>

* Update daml-foundations/daml-ghc/daml-prim-src/DA/Types.daml

Co-Authored-By: Martin Huschenbett <martin.huschenbett@posteo.me>

* Update the daml-lf translation of tuple types

* Fix up the scala bindings for how to use types

* Clarify what action people need to take following the release notes

* Fix an expected test

* Clarify the changelogs even more

* Run ScalaFmt

* Clean up the release notes a bit

* Use the changelog from Beth

* Update the release notes again

* Update docs/source/support/release-notes.rst

Co-Authored-By: Gerolf Seitz <gerolf.seitz@digitalasset.com>

* Fix up the scenario error messages
2019-05-13 16:36:21 +01:00
..
da remove major LF dev version (#681) 2019-04-26 13:10:09 -04:00
src Move Tuple and Either types to DA.Types (#1099) 2019-05-13 16:36:21 +01:00
BUILD.bazel remove major LF dev version (#681) 2019-04-26 13:10:09 -04:00
README.md Fix broken link (#530) 2019-04-16 16:14:43 +02:00

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:

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.