</Para>
<Para>
-The option <Option>-E</Option><IndexTerm><Primary>-E option</Primary></IndexTerm> 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
+The option <Option>-E</Option><IndexTerm><Primary>-E
+option</Primary></IndexTerm> runs just the pre-processing passes of
+the compiler, dumping the result in a file. Note that this differs
+from all GHCs prior to version 4.11, in which the result was dumped to the
+standard output. 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 <Option>-cpp</Option>, the
-output is the de-litted version of the original source.
+through the grinder that is the C pre-processor. Sans
+<Option>-cpp</Option>, the output is the de-litted version of the
+original source.
</Para>
<Para>
<Para>
<IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>
GHC normally imports <Filename>Prelude.hi</Filename> files for you. If you'd rather it
-didn't, then give it a <Option>-fno-implicit-prelude</Option> option. You are
-unlikely to get very far without a Prelude, but, hey, it's a free
-country.
+didn't, then give it a <Option>-fno-implicit-prelude</Option> option.
+The idea is that you can then import a Prelude of your own. (But don't call it <Literal>Prelude</Literal>;
+the Haskell module namespace is flat, and you must not conflict with any Prelude module.)
+</Para>
+<Para>
+Even though you have not imported the Prelude, all the built-in syntax still refers to
+the built-in Haskell Prelude types and values, as specified by the Haskell Report.
+For example, the type <Literal>[Int]</Literal>
+still means <Literal>Prelude.[] Int</Literal>; tuples continue to refer to the standard Prelude
+tuples; the translation for list comprehensions continues to use <Literal>Prelude.map</Literal> etc.
+</Para>
+<Para> With one group of exceptions! You may want to define your own numeric class hierarchy.
+It completely defeats that purpose if the literal "1" means "<Literal>Prelude.fromInteger 1</Literal>",
+which is what the Haskell Report specifies. So the <Option>-fno-implicit-prelude</Option> flag causes
+the following pieces of built-in syntax to refer to whatever is in scope, not the Prelude versions:
+<ItemizedList>
+<ListItem>
+<Para>
+Integer and fractional literals mean "<Literal>fromInteger 1</Literal>" and "<Literal>fromRational 3.2</Literal>",
+not the Prelude-qualified versions; both in expressions and in patterns.
+</Para>
+</ListItem>
+<ListItem>
+<Para>
+Negation (e.g. "<Literal>- (f x)</Literal>") means "<Literal>negate (f x)</Literal>" (not <Literal>Prelude.negate</Literal>).
+</Para>
+</ListItem>
+<ListItem>
+<Para>
+In an n+k pattern, the standard Prelude <Literal>Ord</Literal> class is used for comparison, but the
+necessary subtraction uses
+whatever "<Literal>(-)</Literal>" is in scope (not "<Literal>Prelude.(-)</Literal>").
+</Para>
+</ListItem>
+</ItemizedList>
</Para>
</ListItem>
</VarListEntry>
<para>A package specification looks like this:</para>
<screen>
- ("mypkg",
- "4.08",
- Package
- {
- import_dirs = ["/usr/local/lib/imports/mypkg"],
- library_dirs = ["/usr/local/lib"],
- libraries = ["HSmypkg", "HSmypkg_cbits"],
- include_dirs = [],
- c_includes = ["HsMyPkg.h"],
- package_deps = ["text", "data"],
- extra_ghc_opts = [],
- extra_cc_opts = [],
- extra_ld_opts = ["-lmy_clib"]
- }
- )
+ Package {
+ name = "mypkg",
+ import_dirs = ["/usr/local/lib/imports/mypkg"],
+ library_dirs = ["/usr/local/lib"],
+ hs_libraries = ["HSmypkg" ],
+ extra_libraries = ["HSmypkg_cbits"],
+ include_dirs = [],
+ c_includes = ["HsMyPkg.h"],
+ package_deps = ["text", "data"],
+ extra_ghc_opts = [],
+ extra_cc_opts = [],
+ extra_ld_opts = ["-lmy_clib"]
+ }
</screen>
- <para>The first line is the name of the package, for use with
- the <literal>-package</literal> flag and as listed in the
- <literal>--list-packages</literal> list. The second line is the
- version of GHC that was used to compile any Haskell code in this
- package (GHC will refuse to add the package if its version
- number differs from this one). The rest of the components of
- the package specification may be specified in any order, and
- are:</para>
+ <para>Components of a package specification may be specified in
+ any order, and are:</para>
<variablelist>
<varlistentry>
+ <term><literal>name</literal></term>
+ <indexterm><primary><literal>name</literal></primary>
+ <secondary>package specification</secondary></indexterm>
+ <listitem>
+ <para>The package's name, for use with
+ the <literal>-package</literal> flag and as listed in the
+ <literal>--list-packages</literal> list.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>import_dirs</literal></term>
<indexterm><primary><literal>import_dirs</literal></primary>
<secondary>package specification</secondary></indexterm>
</varlistentry>
<varlistentry>
- <term><literal>libraries</literal></term>
- <indexterm><primary><literal>libraries</literal></primary>
+ <term><literal>hs_libraries</literal></term>
+ <indexterm><primary><literal>hs_libraries</literal></primary>
<secondary>package specification</secondary></indexterm>
<listitem>
- <para>A list of libraries for this package, with the
- <literal>.a</literal> or <literal>.dll</literal> suffix
- omitted. On Unix, the <literal>lib</literal> prefix is
- also omitted.</para>
+ <para>A list of libraries containing Haskell code for this
+ package, with the <literal>.a</literal> or
+ <literal>.dll</literal> suffix omitted. On Unix, the
+ <literal>lib</literal> prefix is also omitted.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>extra_libraries</literal></term>
+ <indexterm><primary><literal>extra_libraries</literal></primary>
+ <secondary>package specification</secondary></indexterm>
+ <listitem>
+ <para>A list of extra libraries for this package. The
+ difference between <literal>hs_libraries</literal> and
+ <literal>extra_libraries</literal> is that
+ <literal>hs_libraries</literal> normally have several
+ versions, to support profiling, parallel and other build
+ options. The various versions are given different
+ suffixes to distinguish them, for example the profiling
+ version of the standard prelude library is named
+ <filename>libHSstd_p.a</filename>, with the
+ <literal>_p</literal> indicating that this is a profiling
+ version. The suffix is added automatically by GHC for
+ <literal>hs_libraries</literal> only, no suffix is added
+ for libraries in
+ <literal>extra_libraries</literal>.</para>
+
+ <para>Also, <literal>extra_libraries</literal> are placed
+ on the linker command line before the
+ <literal>hs_libraries</literal> for the same package. If
+ your package has dependencies in the other direction, you
+ might need to make two separate packages.</para>
</listitem>
</varlistentry>
</Para>
</ListItem>
</VarListEntry>
+
<VarListEntry>
-<Term><Option>-funfolding-con-discount<n></Option>:</Term>
+<Term><Option>-funfolding-update-in-place<n></Option>:</Term>
<ListItem>
<Para>
-<IndexTerm><Primary>-funfolding-con-discount option</Primary></IndexTerm>
-<IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
-<IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
-(Default: 2) If the compiler decides that it can eliminate some
-computation by performing an unfolding, then this is a discount factor
-that it applies to the funciton size before deciding whether to unfold
-it or not.
-</Para>
-
-<Para>
-OK, folks, these magic numbers `30', `8', and '2' are mildly
-arbitrary; they are of the “seem to be OK” variety. The `8' is the
-more critical one; it's what determines how eager GHC is about
-expanding unfoldings.
+Switches on an experimental "optimisation". Switching it on makes the compiler
+a little keener to inline a function that returns a constructor, if the context is
+that of a thunk.
+<ProgramListing>
+ x = plusInt a b
+</ProgramListing>
+If we inlined plusInt we might get an opportunity to use update-in-place for
+the thunk 'x'.
</Para>
</ListItem>
</VarListEntry>
+
<VarListEntry>
<Term><Option>-funbox-strict-fields</Option>:</Term>
<ListItem>
</Para>
</ListItem>
</VarListEntry>
+<VarListEntry>
+<Term><Option>-fexcess-precision</Option>:</Term>
+<ListItem>
+<Para>
+When this option is given, intermediate floating point values can have
+a <Emphasis>greater</Emphasis> precision/range than the final type.
+Generally this is a good thing, but some programs may rely on the
+exact precision/range of <Literal>Float</Literal>/<Literal>Double</Literal>
+values and should not use this option for their compilation.
+</Para>
+</ListItem>
+</VarListEntry>
</VariableList>
</Para>
</Para>
<Para>
-If you are using a Haskell “system library” (e.g., the POSIX
-library), just use the <Option>-package posix</Option> option, and the correct code
-should be linked in.
+If you are using a Haskell “package” (e.g., the POSIX
+library), just use the <Option>-package posix</Option> option, and the
+correct code should be linked in. See <xref linkend="packages"> for
+more details.
</Para>
</ListItem>
</VarListEntry>
<Term><Option>-C[<us>]</Option>:</Term>
<ListItem>
<Para>
-<IndexTerm><Primary>-C<us> RTS option</Primary></IndexTerm>
-Sets the context switch interval to <Literal><us></Literal> microseconds. A context
-switch will occur at the next heap allocation after the timer expires.
-With <Option>-C0</Option> or <Option>-C</Option>, context switches will occur as often as
-possible (at every heap allocation). By default, context switches
-occur every 10 milliseconds. Note that many interval timers are only
-capable of 10 millisecond granularity, so the default setting may be
-the finest granularity possible, short of a context switch at every
-heap allocation.
-</Para>
-
-<Para>
-[NOTE: this option currently has no effect (version 4.00). Context
-switches happen when the current heap block is full, i.e. every 4k of
-allocation].
+<IndexTerm><Primary>-C<us> RTS option</Primary></IndexTerm> Sets
+the context switch interval to <Literal><s></Literal> seconds.
+A context switch will occur at the next heap block allocation after
+the timer expires (a heap block allocation occurs every 4k of
+allocation). With <Option>-C0</Option> or <Option>-C</Option>,
+context switches will occur as often as possible (at every heap block
+allocation). By default, context switches occur every 20ms
+milliseconds. Note that GHC's internal timer ticks every 20ms, and
+the context switch timer is always a multiple of this timer, so 20ms
+is the maximum granularity available for timed context switches.
</Para>
</ListItem>
</VarListEntry>
projects / ghc-hetmet.git / blobdiff