mirror of
https://github.com/digital-asset/daml.git
synced 2024-11-10 10:46:11 +03:00
d2b68d45d4
* Rename hie-core to ghcide The name `hie-core` has caused a lot of confusion as to how we relate to haskell-ide-engine so changing it should hopefully help with that. I also think that ghcide is still a good name once we hopefully integrate with haskell-ide-engine more closely. The name ghcide seems to have a reasonable amount of support on Twitter https://twitter.com/ndm_haskell/status/1170681262987710464 which is of course the only good way to come up with names. * Add a readme that points people to the new directory. * Fix bogus replacements * Use a proper link * links are hard
131 lines
3.9 KiB
Markdown
131 lines
3.9 KiB
Markdown
## 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
|
||
```
|