pre-processor phase to be run, that is, the pre-processor will be run
over your Haskell source file before continuing.
-The option \tr{-E}\index{-E option} runs just the C-preprocessor part
-of the C-compiling phase, sending the result to stdout [I think]. (For
-debugging, usually.)
+The option \tr{-E}\index{-E option} runs just the pre-processing
+passes of the compiler, outputting the result on stdout before
+stopping. If used in conjunction with -cpp, the output is the
+code blocks of the original (literal) source after having put it
+through the grinder that is the C pre-processor. Sans \tr{-cpp}, the
+output is the de-litted version of the original source.
+
+The option \tr{-optcpp-E}\index{-optcpp-E option} runs just the
+pre-processing stage of the C-compiling phase, sending the result to
+stdout. (For debugging or obfuscation contests, usually.)
%************************************************************************
%* *
f [] = 0
f (_:xs) = 1
f "2" = 2
+
+g [] = 2
\end{verbatim}
-where the last pattern match won't ever be reached, as the second
-pattern overlaps it. More often than not, `completeness' of
-patterns is a programmer mistake/error, but if you don't want
-the compiler to ``baby-sit'', use \tr{-fno-warn-incomplete-patterns} option
-to turn them off.\index{-fno-warn-incomplete-patterns option}.
+where the last pattern match in \tr{f} won't ever be reached, as the
+second pattern overlaps it. More often than not, redundant patterns
+is a programmer mistake/error, but if you don't want the compiler to
+``baby-sit'', use the \tr{-fno-warn-overlapping-patterns} option to
+turn these warnings off.\index{-fno-warn-overlapping-patterns option}
+
+Similarly for incomplete patterns, the function \tr{g} will fail when
+applied to non-empty lists, so the compiler will by default emit a
+warning about this. The option \tr{-fno-warn-incomplete-patterns}
+turns rhis off.\index{-fno-warn-incomplete-pattern option}
+
If you're feeling really paranoid, the \tr{-dcore-lint}
option\index{-dcore-lint option} is a good choice. It turns on
with the \tr{-fignore-interface-pragmas}\index{-fignore-interface-pragmas option}
option.
+When compiling without optimisations on, the compiler is extra-careful
+about not slurping in data constructors and instance declarations that
+it will not need. If you believe it is getting it wrong and not
+importing stuff which you think it should, this optimisation can be
+turned off with \tr{-fno-prune-tydecls} and \tr{-fno-prune-instdecls}.
+\index{-fno-prune-tydecls option}\index{-fno-prune-instdecls}
+
See also \sectionref{options-linker}, which describes how the linker
finds standard Haskell libraries.
%************************************************************************
%* *
\subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
+\index{include-file-option}
\index{C compiler options}
\index{GCC options}
-\index{include file option}
%* *
%************************************************************************
\item[\tr{-ddump-raw-asm}:]
\index{-ddump-raw-asm option}
Dump out the assembly-language stuff, before the ``mangler'' gets it.
+
+\item[\tr{-ddump-rn-trace}:]
+\index{-ddump-rn-trace}
+Make the renamer be *real* chatty about what it is upto.
+
+\item[\tr{-dshow-rn-stats}:]
+\index{-dshow-rn-stats}
+Print out summary of what kind of information the renamer had to bring
+in.
+\item[\tr{-dshow-unused-imports}:]
+\index{-dshow-unused-imports}
+Have the renamer report what imports does not contribute.
+
+\item[\tr{-fwarn-unused-names}:]
+\index{-fwarn-unused-names}
+Have the renamer report which locally defined names are not used/exported.
+
%
%\item[\tr{-dgc-debug}:]
%\index{-dgc-debug option}
Sometimes it is useful to make the connection between a source file
and the command-line options it requires, quite tight. For instance,
if a (Glasgow) Haskell source file uses \tr{casm}s, the C back-end
-often needs to be told about header files to use,
-\ref{include file option}. Rather than maintaining the list of
-files the source depends on in a \tr{Makefile}, it is possible to
-do this directly in the source file using the \tr{OPTIONS} pragma
-\index{OPTIONS pragma}:
+often needs to be told about which header files to include. Rather than
+maintaining the list of files the source depends on in a
+\tr{Makefile} (using the \tr{-#include} command-line option), it is
+possible to do this directly in the source file using the \tr{OPTIONS}
+pragma \index{OPTIONS pragma}:
\begin{verbatim}
{-# OPTIONS -#include "foo.h" #-}
It is not recommended to move all the contents of your Makefiles into
your source files, but in some circumstances, the \tr{OPTIONS} pragma
-is the Right Thing.
+is the Right Thing. (If you use \tr{-keep-hc-file-too} and have OPTION
+flags in your module, the OPTIONS will get put into the generated .hc
+file).
+
+%----------------------------------------------------------------------
+\subsubsection{How to compile mutually recursive modules}
+\index{module system, recursion}
+
+Currently, the compiler does not have proper support for dealing with
+mutually recursive modules:
+
+\begin{verbatim}
+module A where
+
+import B
+
+newtype A = A Int
+
+f :: B -> A
+f (B x) = A x
+--------
+module B where
+
+import A
+
+data B = B !Int
+
+g :: A -> B
+g (A x) = B x
+\end{verbatim}
+
+When compiling either module A and B, the compiler will try (in vain)
+to look for the interface file of the other. So, to get mutually
+recursive modules off the ground, you need to hand write an interface
+file for A or B, so as to break the loop. For the example at hand, the
+boot interface file for A would like the following:
+
+\begin{verbatim}
+_interface_ A 1
+_exports_
+A A(A) f;
+_declarations_
+1 newtype A = A PrelBase.Int ;
+1 f _:_ B.B -> A.A ;;
+\end{verbatim}
+
+To make sure you get the syntax right, tailoring an existing interface
+file is a Good Idea.
+
+{\bf Note:} This is all a temporary solution, a version of the compiler
+that handles mutually recursive properly without the manual
+construction of interface file, is in the works.
%----------------------------------------------------------------------
%\subsubsection[arity-checking]{Options to insert arity-checking code}
projects / ghc-hetmet.git / blobdiff