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.)
%************************************************************************
%* *
\item[\tr{-fvia-C}:]
\index{-fvia-C option}
+\index{-fvia-c option}
Compile via C, and don't use the native-code generator.
(There are many cases when GHC does this on its own.) You might
pick up a little bit of speed by compiling via C. If you use
\tr{_ccall_}s or \tr{_casm_}s, you probably {\em have to} use
-\tr{-fvia-C}.
+\tr{-fvia-C}.
+
+The lower-case incantation, \tr{-fvia-c}, is synonymous.
\item[\tr{-O2-for-C}:]
\index{-O2-for-C option}
%* *
\subsection[options-sanity]{Warnings and sanity-checking}
\index{sanity-checking options}
+\index{warnings}
%* *
%************************************************************************
-If you would like GHC to check that every top-level value has a type
-signature, use the \tr{-fsignatures-required}
-option.\index{-fsignatures-required option}
+GHC has a selection of options that select which types of non-fatal
+error messages, otherwise known as warnings, can be generated during
+compilation. By default, you get a standard set of warnings which are
+generally likely to indicate bugs in your program. These are:
+\tr{-fwarn-overlpapping-patterns} and \tr{-fwarn-missing-methods}.
+The following flags are simple ways to select standard ``packages'' of
+warnings:
+
+\begin{description}
+
+\item[\tr{-Wnot}:]
+\index{-Wnot option}
+
+Turns off all warnings, including the standard ones.
+
+\item[\tr{-w}:]
+\index{-w option}
+
+Synonym for \tr{-Wnot}.
+
+\item[\tr{-W}:]
+\index{-W option}
-If you would like to disallow ``name shadowing,'' i.e., an inner-scope
-value has the same name as an outer-scope value, then use the
-\tr{-fwarn-name-shadowing}
-option.\index{-fwarn-name-shadowing option}
-This option catches typographical errors that turn into hard-to-find
-bugs, e.g., in the inadvertent cyclic definition \tr{let x = ... x ... in}.
+Provides the standard warnings plus \tr{-fwarn-incomplete-patterns}
+and \tr{-fwarn-unused-names}.
+
+\item[\tr{-Wall}:]
+\index{-Wall option}
+
+Turns on all warning options.
+
+\end{description}
+
+The full set of warning options is described below. To turn off any
+warning, simply give the corresponding \tr{-fno-warn-...} option on
+the command line.
+
+\begin{description}
+
+\item[\tr{-fwarn-name-shadowing}:]
+\index{-fwarn-name-shadowing option}
+\index{shadowing, warning}
+
+This option causes a warning to be emitted whenever an inner-scope
+value has the same name as an outer-scope value, i.e. the inner value
+shadows the outer one. This can catch typographical errors that turn
+into hard-to-find bugs, e.g., in the inadvertent cyclic definition
+\tr{let x = ... x ... in}.
Consequently, this option does {\em not} allow cyclic recursive
definitions.
+\item[\tr{-fwarn-overlapping-patterns}:]
+\index{-fwarn-overlapping-patterns option}
+\index{overlapping patterns, warning}
+\index{patterns, overlapping}
+
By default, the compiler will warn you if a set of patterns are either
incomplete (i.e., you're only matching on a subset of an algebraic
data type's constructors), or overlapping, i.e.,
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}
+is a programmer mistake/error, so this option is enabled by default.
+
+\item[\tr{-fwarn-incomplete-patterns}:]
+\index{-fwarn-incomplete-patterns option}
+\index{incomplete patterns, warning}
+\index{patterns, incomplete}
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}
+applied to non-empty lists, so the compiler will emit a warning about
+this when this option is enabled.
+\item[\tr{-fwarn-missing-methods}:]
+\index{-fwarn-missing-methods option}
+\index{methods, missing}
+
+This option is on by default, and warns you whenever an instance
+declaration is missing one or more methods, and the corresponding
+class declaration has no default declaration for them.
+
+\item[\tr{-fwarn-unused-names}:]
+\index{-fwarn-unused-names}
+Have the renamer report which locally defined names are not
+used/exported. This option is not currently supported.
+
+\item[\tr{-fwarn-duplicate-exports}:]
+\index{-fwarn-duplicate-exports option}
+\index{export lists, duplicates}
+
+Have the compiler warn about duplicate entries in export lists. This
+is useful information if you maintain large export lists, and want to
+avoid the continued export of a definition after you've deleted (one)
+mention of it in the export list.
+
+This option is on by default.
+
+\end{description}
+
+If you would like GHC to check that every top-level value has a type
+signature, use the \tr{-fsignatures-required}
+option.\index{-fsignatures-required option}
If you're feeling really paranoid, the \tr{-dcore-lint}
option\index{-dcore-lint option} is a good choice. It turns on
When compiling a Haskell module, GHC may produce several files of
output (usually two).
-One file is usually an {\em interface file}. If compiling
-\tr{bar/Foo.hs}, the interface file would normally be \tr{bar/Foo.hi}.
+One file is usually an {\em interface file}. The name of the
+interface file follows the Haskell {\em module} name, i.e., if
+compiling \tr{bar/Foo.hs}, and it implements \tr{module Bar ...}, the
+interface file would normally be \tr{bar/Bar.hi}.
+
The interface output may be directed to another file
-\tr{bar2/Wurble.iface} with the option
-\tr{-ohi bar2/Wurble.iface}\index{-ohi <file> option} (not recommended).
+\tr{bar2/Wurble.iface} with the option \tr{-ohi
+bar2/Wurble.iface}\index{-ohi <file> option} (not recommended).
+
+NOTE: Having the name of the interface file follow the module name
+and not the file name, means that working with tools such as
+\tr{make(1)} become harder. \tr{make} implicitly assumes that any
+output files produced by processing a translation unit will have file
+names that can be derived from the file name of the translation unit.
+For instance, pattern rules becomes unusable.
To avoid generating an interface file at all, use a \tr{-nohi}
option.\index{-nohi option}
the new one is byte-for-byte the same as the old one; this is friendly to
\tr{make}. When an interface does change, it is often enlightening to
be informed. The \tr{-hi-diffs}\index{-hi-diffs option} option will
-make \tr{ghc} run \tr{diff} on the old and new \tr{.hi} files.
+make \tr{ghc} run \tr{diff} on the old and new \tr{.hi} files. You can
+also record the difference in the interface file itself, the
+\tr{-keep-hi-diffs}\index{-keep-hi-diffs} option takes care of that.
The \tr{.hi} files from GHC 2.xx contain ``usage'' information which
changes often and uninterestingly. If you really want to see these
pre-processor with the \tr{-opt} flags (see
\sectionref{forcing-options-through}).
-A small word of warning: \tr{-cpp} is not friendly to
-``string gaps''.\index{-cpp vs string gaps}\index{string gaps vs -cpp}
+A small word of warning: \tr{-cpp} is not friendly to ``string
+gaps''.\index{-cpp vs string gaps}\index{string gaps vs -cpp}. In
+other words, strings such as the following:
+
+\begin{verbatim}
+ strmod = "\
+ \ p \
+ \ "
+\end{verbatim}
+don't work with \tr{-cpp}; \tr{/usr/bin/cpp} elides the
+backslash-newline pairs.
+
+However, it appears that if you add a space at the end of the line,
+then \tr{cpp} (at least GNU \tr{cpp} and possibly other \tr{cpp}s)
+leaves the backslash-space pairs alone and the string gap works as
+expected.
%************************************************************************
%* *
\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}
\index{source-file options}
Sometimes it is useful to make the connection between a source file
-and the command-line options it requires, quite tight. For instance,
+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 which header files to include. Rather than
maintaining the list of files the source depends on in a
the compiler driver maintains internally, so you'll be desperately
disappointed if you try to glob etc. inside \tr{OPTIONS}.
+NOTE: the contents of OPTIONS are prepended to the command-line
+options, so you *do* have the ability to override OPTIONS settings
+via the command line.
+
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. (If you use \tr{-keep-hc-file-too} and have OPTION
projects / ghc-hetmet.git / blobdiff