From 2d52406199e0bcc82ec1bbb5c25a175f138722f1 Mon Sep 17 00:00:00 2001
From: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>
Date: Tue, 9 Jul 2019 16:22:13 +0200
Subject: [PATCH] Document damlc code layout (#2071)

---
 compiler/damlc/README.md | 58 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/compiler/damlc/README.md b/compiler/damlc/README.md
index 54f0183d73..1197c463a0 100644
--- a/compiler/damlc/README.md
+++ b/compiler/damlc/README.md
@@ -1,3 +1,61 @@
+## 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
+`hie-core`’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 `hie-core` 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 `hie-core` 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: