Reorganisation of the source tree

Most of the other users of the fptools build system have migrated to
Cabal, and with the move to darcs we can now flatten the source tree
without losing history, so here goes.

The main change is that the ghc/ subdir is gone, and most of what it
contained is now at the top level.  The build system now makes no
pretense at being multi-project, it is just the GHC build system.

No doubt this will break many things, and there will be a period of
instability while we fix the dependencies.  A straightforward build
should work, but I haven't yet fixed binary/source distributions.
Changes to the Building Guide will follow, too.

1 files changed, 58 insertions, 0 deletions

diff --git a/compiler/DLL-NOTES b/compiler/DLL-NOTES
new file mode 100644
index 0000000000..c710b14251
--- /dev/null
+++ b/compiler/DLL-NOTES
@@ -0,0 +1,58 @@
+                              The DLL story
+                              -------------
+
+***
+
+This file is intended to be a focal point for notes on how DLLs work. Please
+add cross-references to source and other docs, especially when you don't
+find something here that you need.
+
+***
+
+
+Introduction
+------------
+
+On Windows, DLLs are synonymous with packages (since 4.07; this change
+simplified a rather horrible mess). Hence whenever a module is to be
+compiled to go in a DLL, it must be compiled with -package-name dll-name.
+Typically, failing to do this gives Windows error message boxes of the form
+"The instruction at address <x> tried to read memory at address <x>".
+
+
+Dependencies
+------------
+
+Because references in DLLs must be fully resolved when the DLL is compiled
+(except for references to other DLLs), it is not possible for DLLs to call
+the main program. This means that the parts of the RTS and standard package
+which call the main program cannot be compiled into the relevant DLLs, and
+must instead be compiled as standalone object files and linked in to each
+executable. This gives the following picture of dependencies within a program:
+
+            ___________         ___________
+           |           |------>|           |   GHC-land  |  Application-land
+DLL-land   | HSrts.dll |       | HSstd.dll |             |
+           |___________|<------|___________|             |
+                 |                   ^                   |
+-----------------|-------------------|-------------------|
+            _____v_____         _____|______             |
+.o-land    |           |       |            |            |
+           |  Main.o   |       | PrelMain.o |-----------------------
+	   |___________|       |____________|            |          |
+                 |                                       |    ______v______
+                 |                                       |   |             |
+                  ------------------------------------------>|   Main.o    |
+                                                         |   |_____________|
+
+(The application's dependencies are not shown.)
+
+
+Bits of the compiler that deal with DLLs
+----------------------------------------
+
+basicTypes/Module.lhs is the most important place, as it deals with which
+modules identifiers are in.
+
+basicTypes/name.lhs, other bits of basicTypes/, nativeGen/, codeGen/,
+abcCSyn/, and even profiling/ have other references.