Hlb update and document external build steps (digital-asset#2769)

* stack setup for HLB and Nim * build_packages.sh and daml-ledger.cabal * update README * export-package for daml-ledger * export-package, run here * find tmp daml-ledger * update README for review comments * ref daml instructions * further improve the process and documentation in response to comments * have -with-rtsopts match the bazel build * fixes for Gary
TuranDev · Sep 9, 2019 · 69b520c · 69b520c
1 parent a700261
commit 69b520c
Show file tree

Hide file tree

Showing 10 changed files with 207 additions and 258 deletions.
diff --git a/.gitignore b/.gitignore
@@ -89,3 +89,6 @@ daml-lf/gen
 daml-lf/build.sbt
 .markdown-preview.html
 compiler/damlc/output
+language-support/hs/bindings/gen
+language-support/hs/bindings/*.cabal
+language-support/hs/bindings/examples/nim/*.cabal
diff --git a/language-support/hs/bindings/README.md b/language-support/hs/bindings/README.md
@@ -21,21 +21,44 @@ You can find some usage examples
 [here](/language-support/hs/bindings/test/DA/Ledger/Tests.hs) and
 [here](/language-support/hs/bindings/examples/chat/src/DA/Ledger/App/Chat/ChatLedger.hs).
 
-Using these bindings **outside of this repository** can be a bit
-tricky since there are quite a few packages required that are not
-published to Hackage at the moment.
-
-To make things a bit easier there is a `build_packages.sh` script in
-this directory that you can run as follows: `./build_packages.sh
-TARGET_DIR`.  This will build the tarballs for all cabal packages and
-put them in `TARGET_DIR`. If `TARGET_DIR` does not already contain a
-`cabal.project` file, it will also create a `cabal.project` file that
-references the created tarballs so all dependencies should be resolved
-properly. You will also need to install gRPC 1.22, see
-https://github.com/grpc/grpc/blob/master/BUILDING.md for installation
-instructions. If you install it in a non-standard location, you need
-to adjust extra-lib-dirs and extra-include-dirs for
-grpc-haskell-core. The default `cabal.project` file contains an
-example of how to do this.
-
-The main package for the ledger bindings is called `daml-ledger`.
+
+# Using these bindings **outside of this repository**
+
+*Note: These instructions document the current process. We do plan make it simpler!*
+
+These bindings can be exported as a standalone Haskell package `daml-ledger` using `stack`. Currently, `stack` references the code directly in the `daml` repo. The only annoyance is that part of the Haskell code for `daml-ledger` is generated from `.proto` files, and this generation step must be performed using the `bazel` build. We plan to simplify this step by directly providing `daml-ledger` as a package on hackage. Instructions for working with the daml repo can be found here: https://github.com/digital-asset/daml
+
+As well as `stack`, the only other prerequisite is to have `grpc` installed. (`grpc` is not required to generate the `daml-ledger` package, but it is required to use it).
+
+We are currently using gRPC version `1.23.0`. To install `grpc`  requires building `grpc` from source (really!). See detailed instructions here: https://github.com/grpc/grpc/blob/master/BUILDING.md.
+
+In the instructions below we do `make install` for grpc despite the warning from the `grpc` build instructions:
+
+> *"WARNING: After installing with make install there is no easy way to uninstall, which can cause issues if you later want to remove the grpc and/or protobuf installation or upgrade to a newer version."*
+
+If you decide against the `make install`, or choose a different install location, you will need to adjust the settings of `extra-lib-dirs` and `extra-include-dirs` in your `stack.yaml` config.
+
+Also, in the instructions below we export the `daml-ledger` package to `/tmp` which matches the location declared in the `stack.yaml` of the example application `nim`. If you export somewhere else, you will need to adapt your `stack.yaml`
+
+## Download and build grpc at version 1.23.0
+
+    git clone -b v1.23.0 https://github.com/grpc/grpc
+    cd grpc
+    git submodule update --init
+    make
+    make prefix=/usr/local/grpc install
+
+## Clone daml repo, and export the daml-ledger package
+
+    cd /tmp
+    git clone https://github.com/digital-asset/daml.git
+    cd daml
+    eval $(dev-env/bin/dade-assist)
+    language-support/hs/bindings/export-package.sh /tmp
+
+## Write a DAML Ledger App in Haskell (or copy one!), and build it
+
+    cd /tmp
+    cp -rp /tmp/daml/language-support/hs/bindings/examples/nim nim
+    cd nim
+    stack build
diff --git a/language-support/hs/bindings/build_packages.sh b/language-support/hs/bindings/build_packages.sh
diff --git a/language-support/hs/bindings/daml-ledger.cabal b/language-support/hs/bindings/daml-ledger.cabal
diff --git a/language-support/hs/bindings/examples/nim/package.yaml b/language-support/hs/bindings/examples/nim/package.yaml
@@ -0,0 +1,37 @@
+name:                nim
+version:             0.1.0.0
+description:         Play Nim on a DAML Ledger
+license:             Apache-2.0
+author:              The DAML Authors
+maintainer:          nick.chapman@digitalasset.com
+github:              https://github.com/digital-asset/daml
+
+dependencies:
+- ansi-terminal
+- base >= 4.7 && < 5
+- containers
+- daml-ledger
+- extra
+- haskeline
+- random
+- text
+- transformers
+- uuid
+
+executables:
+  nim-exe:
+    main:                DA.Ledger.App.Nim.Main
+    source-dirs:         src
+    ghc-options:
+    - -Wall
+    - -Wno-name-shadowing
+    - -threaded
+    - -rtsopts
+    - '"-with-rtsopts=-N2 -qg -I0"'
+
+    default-extensions:
+    - LambdaCase
+    - NamedFieldPuns
+    - OverloadedStrings
+    - RecordWildCards
+    - ScopedTypeVariables
diff --git a/language-support/hs/bindings/examples/nim/stack.yaml b/language-support/hs/bindings/examples/nim/stack.yaml
@@ -0,0 +1,23 @@
+resolver: lts-14.3
+
+extra-lib-dirs:
+- /usr/local/grpc/lib
+
+extra-include-dirs:
+- /usr/local/grpc/include
+
+extra-deps:
+
+- git: https://github.com/awakesecurity/proto3-suite
+  commit: 3f6dd6f612cf2eba3c05798926ff924b0d5ab4fa
+
+- git: https://github.com/awakesecurity/proto3-wire
+  commit: 4f355bbac895d577d8a28f567ab4380f042ccc24
+
+- git: https://github.com/awakesecurity/gRPC-haskell
+  commit: be70fc49b0dc25313f57d0e6c6ba2a9fa46b9e6b
+  subdirs:
+  - .
+  - core
+
+- archive: /tmp/daml-ledger-0.1.0.0.tar.gz