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, 80 insertions, 0 deletions

diff --git a/driver/ghc-usage.txt b/driver/ghc-usage.txt
new file mode 100644
index 0000000000..e95d5846b9
--- /dev/null
+++ b/driver/ghc-usage.txt
@@ -0,0 +1,80 @@
+Usage:
+
+    $$ [command-line-options-and-input-files]
+
+To compile and link a complete Haskell program, run the compiler like
+so:
+
+    $$ --make Main
+
+where the module Main is in a file named Main.hs (or Main.lhs) in the
+current directory.  The other modules in the program will be located
+and compiled automatically, and the linked program will be placed in
+the file `a.out' (or `Main.exe' on Windows).
+
+Alternatively, $$ can be used to compile files individually.  Each
+input file is guided through (some of the) possible phases of a
+compilation:
+
+    - unlit:	extract code from a "literate program"
+    - hscpp:	run code through the C pre-processor (if -cpp flag given)
+    - hsc:	run the Haskell compiler proper
+    - gcc:	run the C compiler (if compiling via C)
+    - as:	run the assembler
+    - ld:	run the linker
+
+For each input file, the phase to START with is determined by the
+file's suffix:
+
+    - .lhs	literate Haskell		 unlit
+    - .hs	plain Haskell			 ghc
+    - .hc	C from the Haskell compiler	 gcc
+    - .c	C not from the Haskell compiler  gcc
+    - .s	assembly language		 as
+    - other	passed directly to the linker	 ld
+
+The phase at which to STOP processing is determined by a command-line
+option:
+
+    -E		stop after generating preprocessed, de-litted Haskell
+		     (used in conjunction with -cpp)
+    -C		stop after generating C (.hc output)
+    -S		stop after generating assembler (.s output)
+    -c		stop after generating object files (.o output)
+
+Other commonly-used options are:
+
+    -v[n]	    Control verbosity (n is 0--5, normal verbosity level is 1,
+	              -v alone is equivalent to -v3)
+
+    -fglasgow-exts  Allow Glasgow extensions (unboxed types, etc.)
+
+    -O		    An `optimising' package of compiler flags, for faster code
+
+    -prof	    Compile for cost-centre profiling
+		     (add -auto-all for automagic cost-centres on all
+		      top-level functions)
+
+    -H14m	    Increase compiler's heap size (might make compilation
+		    faster, especially on large source files).
+
+    -M              Output Makefile rules recording the
+		    dependencies of a list of Haskell files.
+
+Given the above, here are some TYPICAL invocations of $$:
+
+    # compile a Haskell module to a .o file, optimising:
+    % $$ -c -O Foo.hs
+    # link three .o files into an executable called "test":
+    % $$ -o test Foo.o Bar.o Baz.o
+    # compile a Haskell module to C (a .hc file), using a bigger heap:
+    % $$ -C -H16m Foo.hs
+    # compile Haskell-produced C (.hc) to assembly language:
+    % $$ -S Foo.hc
+
+The User's Guide has more information about GHC's *many* options.  An
+online copy can be found here:
+
+   http://www.haskell.org/ghc/documentation.html
+
+------------------------------------------------------------------------