daml/compiler/damlc/README.md
Moritz Kiefer d2b68d45d4 Rename hie-core to ghcide (#2820)
* 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
2019-09-09 13:55:16 +00:00

131 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

## 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 GHCs 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
```