Command-line arguments are either options or file names.
Command-line options begin with \tr{-}. They may {\em not} be
-grouped: \tr{-vO} is different from \tr{-v -O}.
-Options need not precede filenames: e.g., \tr{ghc *.o -o foo}.
-All options are processed
-and then apply to all files; you cannot, for example,
-invoke \tr{ghc -c -O1 Foo.hs -O2 Bar.hs} to apply different
-optimisation levels to the files \tr{Foo.hs} and \tr{Bar.hs}. For
-conflicting options, e.g., \tr{-c -S}, we reserve the right to do
-anything we want. (Usually, the last one applies.)
+grouped: \tr{-vO} is different from \tr{-v -O}. Options need not
+precede filenames: e.g., \tr{ghc *.o -o foo}. All options are
+processed and then applied to all files; you cannot, for example, invoke
+\tr{ghc -c -O1 Foo.hs -O2 Bar.hs} to apply different optimisation
+levels to the files \tr{Foo.hs} and \tr{Bar.hs}. For conflicting
+options, e.g., \tr{-c -S}, we reserve the right to do anything we
+want. (Usually, the last one applies.)
Options related to profiling, Glasgow extensions to Haskell (e.g.,
-unboxed values), Concurrent and Parallel Haskell are
-described in \sectionref{profiling}, \sectionref{glasgow-exts}, and
+unboxed values), Concurrent and Parallel Haskell are described in
+\sectionref{profiling}, \sectionref{glasgow-exts}, and
\sectionref{concurrent-and-parallel}, respectively.
%************************************************************************
Knowing that you ran the right bits in the right order is always the
first thing we want to verify.
+If you're just interested in the compiler version number, the
+\tr{--version}\index{--version option} option prints out a
+one-line string containing the requested info.
+
%************************************************************************
%* *
\subsection[options-order]{Running the right phases in the right order}
%files as if they had suffix \pl{<suf>}. [NOT IMPLEMENTED YET]
The option \tr{-cpp}\index{-cpp option} must be given for the C
-pre-processor phase to be run.
+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 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{-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{-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.)
%************************************************************************
%* *
Once you choose a \tr{-O*} ``package,'' stick with it---don't chop and
change. Modules' interfaces {\em will} change with a shift to a new
-\tr{-O*} option, and you will have to recompile all importing modules
-before your program can again be run safely.
+\tr{-O*} option, and you may have to recompile a large chunk of all
+importing modules before your program can again be run
+safely\sectionref{recomp}.
\begin{description}
\item[No \tr{-O*}-type option specified:]
\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}
\index{GCC optimisation}
The C~compiler (GCC) is run with \tr{-O} turned on. (It has
-to be, actually.)
+to be, actually).
If you want to run GCC with \tr{-O2}---which may be worth a few
percent in execution speed---you can give a
%************************************************************************
%* *
-\subsection[options-sanity]{Sanity-checking options}
+\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}
+
+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}
-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{-fname-shadowing-not-ok}
-option.\index{-fname-shadowing-not-ok 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}.
+\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.,
+
+\begin{verbatim}
+f :: String -> Int
+f [] = 0
+f (_:xs) = 1
+f "2" = 2
+
+g [] = 2
+\end{verbatim}
+
+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, 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 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
heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
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
\tr{ghc -C -o foo.o foo.hs} will put the intermediate C code in the
file \tr{foo.o}, name notwithstanding!
-EXOTICA: But the \tr{-o} option isn't much use if you have {\em
-several} input files... Non-interface output files are normally put
+EXOTICA: But the \tr{-o} option isn't of much use if you have {\em
+several} input files... Non-interface output files are normally put
in the same directory as their corresponding input file came from.
You may specify that they be put in another directory using the
\tr{-odir <dir>}\index{-odir <dir> option} (the ``Oh, dear'' option).
the directory where temporary files should be put. GCC and other
programs will honour the \tr{TMPDIR} variable as well.
-EVEN BETTER IDEA: Configure GHC with \tr{--with-tmpdir=<mumble>} when
-you build it, and never worry about \tr{TMPDIR} again.
+EVEN BETTER IDEA: Set the \tr{TMPDIR} variable when building
+GHC, and never worry about \tr{TMPDIR} again. (see the build
+documentation).
%************************************************************************
%* *
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.
\index{__HASKELL1__ macro}
If defined to $n$, that means GHC supports the
Haskell language defined in the Haskell report version $1.n$.
-Currently 3.
+Currently 4.
NB: This macro is set both when pre-processing Haskell source and
when pre-processing generated C (\tr{.hc}) files.
\item[\tr{__GLASGOW_HASKELL__}:]
\index{__GLASGOW_HASKELL__ macro}
For version $n$ of the GHC system, this will be \tr{#define}d to
-$100 \times n$. So, for version~2.01, it is 201.
+$100 \times n$. So, for version~2.02, it is 202.
This macro is {\em only} set when pre-processing Haskell source.
({\em Not} when pre-processing generated C.)
\item[\tr{__CONCURRENT_HASKELL__}:]
\index{__CONCURRENT_HASKELL__ macro}
Only defined when \tr{-concurrent} is in use!
-This symbol is
-defined when pre-processing Haskell (input) and pre-processing C (GHC
-output).
+This symbol is defined when pre-processing Haskell (input) and
+pre-processing C (GHC output).
\item[\tr{__PARALLEL_HASKELL__}:]
\index{__PARALLEL_HASKELL__ macro}
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.
%************************************************************************
%* *
\subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
+\index{include-file-option}
\index{C compiler options}
\index{GCC options}
%* *
\index{-dgcc-lint option (GCC paranoia)}
If you are compiling with lots of \tr{ccalls}, etc., you may need to
-tell the C~compiler about some \tr{#include} files. There is no
+tell the C~compiler about some \tr{#include} files. There is no real
pretty way to do this, but you can use this hack from the
command-line:
\begin{verbatim}
% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
\end{verbatim}
-\index{-#include <file> option}
+
%************************************************************************
%* *
library), just use the \tr{-syslib hbc} option, and the correct code
should be linked in.
-Please see \sectionref{syslibs} for information about
-``system libraries.''
+%Please see \sectionref{syslibs} for information about
+%``system libraries.''
\item[\tr{-L<dir>}:]
\index{-L<dir> 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{-dgc-debug}:]
%\index{-dgc-debug option}
trademark of Peyton Jones Enterprises, plc.)
%----------------------------------------------------------------------
+\subsubsection[source-file-options]{Command line options in source files}
+\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,
+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
+\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" #-}
+module X where
+
+...
+\end{verbatim}
+
+\tr{OPTIONS} pragmas are only looked for at the top of your source
+files, upto the first (non-literate,non-empty) line not containing
+\tr{OPTIONS}. Multiple \tr{OPTIONS} pragmas are recognised. Note
+that your command shell does not get to the source file options, they
+are just included literally in the array of command-line arguments
+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
+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}
%\index{arity checking}
%
projects / ghc-hetmet.git / blobdiff