daml/compiler/damlc/README.md

Code layout

The following list is ordered topologicaly based on the dependency graph.

daml-preprocessor

daml-preprocessor contains the DAML preprocessor which runs our version of the record-dot-preprocessor and the preprocessor for generating Generic instances. The preprocessor also performs a few additional checks, e.g., that you do not import internal modules.

daml-opts

daml-opts contains two libraries: daml-opt-types and daml-opts.

daml-opt-types contains the Options type which controls the various flags affecting most damlc commands. Most of the options can be controlled via command line flags.

daml-opts contains the conversion from damlc’s Options type to ghcide’s IdeOptions type. This is in a separate package to avoid making everything depend on daml-preprocessor.

daml-lf-conversion

daml-lf-conversion handles the conversion from GHC’s Core to DAML-LF.

daml-ide-core

daml-ide-core is a wrapper around ghcide that adds DAML-specific rules such as rules for producing DAML-LF.

daml-doc

daml-doc contains our variant of haddock.

daml-ide

daml-ide contains the LSP layer of the IDE and wraps the corresponding LSP layer in ghcide and adds custom handlers such as those for scenario results.

daml-compiler

daml-compiler contains the implementation of a few top-level damlc commands, e.g., upgrade.

lib

lib is all of damlc but packaged as a library since that can be more convenient for tests.

exe

This is a tiny wrapper around lib to produce the damlc executable.

Developing

When working on the compiler:

da-ghcid //compiler/damlc/tests:integration-dev --reload=compiler/damlc/tests/daml-test-files --test=":main --pattern="
bazel run //compiler/damlc/tests:integration-dev -- --pattern=
bazel run damlc -- compile $PWD/MyDaml12File.daml

When working on the IDE via the test suite:

bazel run //compiler/damlc/tests:shake -- --pattern=
da-ghcid //compiler/damlc/tests:shake --test=":main --pattern="

The above commands do not execute scenarios. To do that, use a command like

bazel run damlc test $PWD/compiler/damlc/tests/bond-trading/Test.daml

At the moment, commands relying on ghc-pkg, e.g., damlc build do not work via bazel run. For testing, install the SDK with daml-sdk-head and then use daml-head damlc.

Updating daml-doc's golden tests

Run

bazel run //compiler/damlc/tests:daml-doc -- --accept

to accept the current documentation as new golden files.

Documentation

Standard library docs are exposed under the bazel rules which you can build with:

bazel build //compiler/damlc:daml-base-rst-docs
bazel build //compiler/damlc:daml-base-hoogle-docs

DAML Packages and Database

A DAML project is compiled to a DAML package and can be distributed as a DAML archive (DAR). This is essentially a zip archive containing the DAML source code of the library together with the compiled .dalf file. The damlc package loading mechanism is based on GHC's package database and uses the same .conf file format. GHC's package database is documented at https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/packages.html.

Loading packages

damlc loads packages from a package database given by the option --package-db. It creates a map from package name to DAML-LF file from all the contained .dalf files in this directory and links the created DAML-LF against these packages. It uses the .hi interface files created upon installation of the packages for type checking.

Base packages

Currently a package database is provided together with the damlc Bazel rule and bazel run damlc loads this database by default. This package database is also bundled in the damlc-dist.tar.gz tarball included in the SDK.

Building the package database

The package database that comes with damlc and the above archives can be build with

bazel build //compiler/damlc/pkg-db:pkg-db