Skip to content

GitLab

Commit 7d67a216 authored by simonmar's avatar simonmar
Browse files

[project @ 2001-02-15 17:33:53 by simonmar] 

More documentation rewriting...  I'm particularly proud of the "flag
reference" section, please check it out.
parent b8644e3d
Expand all Hide whitespace changes
Inline Side-by-side
ghc/docs/users_guide/debugging.sgml
View file @ 7d67a216
......@@ -11,123 +11,6 @@ HACKER TERRITORY. HACKER TERRITORY.
(You were warned.)
</Para>
<Sect2 id="replacing-phases">
<Title>Replacing the program for one or more phases.
</Title>
<Para>
<IndexTerm><Primary>GHC phases, changing</Primary></IndexTerm>
<IndexTerm><Primary>phases, changing GHC</Primary></IndexTerm>
You may specify that a different program be used for one of the phases
of the compilation system, in place of whatever the driver <Command>ghc</Command> has
wired into it. For example, you might want to try a different
assembler. The
<Option>-pgm&lt;phase-code&gt;&lt;program-name&gt;</Option><IndexTerm><Primary>-pgm&lt;phase&gt;&lt;stuff&gt;
option</Primary></IndexTerm> option to <Command>ghc</Command> will cause it to use <Literal>&lt;program-name&gt;</Literal>
for phase <Literal>&lt;phase-code&gt;</Literal>, where the codes to indicate the phases are:
</Para>
<Para>
<InformalTable>
<TGroup Cols="2">
<ColSpec Align="Left" Colsep="0">
<ColSpec Align="Left" Colsep="0">
<TBody>
<Row>
<Entry><Emphasis>code</Emphasis> </Entry>
<Entry><Emphasis>phase</Emphasis> </Entry>
</Row>
<Row>
<Entry>
L </Entry>
<Entry> literate pre-processor </Entry>
</Row>
<Row>
<Entry>
P </Entry>
<Entry> C pre-processor (if -cpp only) </Entry>
</Row>
<Row>
<Entry>
C </Entry>
<Entry> Haskell compiler </Entry>
</Row>
<Row>
<Entry>
c </Entry>
<Entry> C compiler</Entry>
</Row>
<Row>
<Entry>
a </Entry>
<Entry> assembler </Entry>
</Row>
<Row>
<Entry>
l </Entry>
<Entry> linker </Entry>
</Row>
<Row>
<Entry>
dep </Entry>
<Entry> Makefile dependency generator </Entry>
</Row>
</TBody>
</TGroup>
</InformalTable>
</Para>
</Sect2>
<Sect2 id="forcing-options-through">
<Title>Forcing options to a particular phase.
</Title>
<Para>
<IndexTerm><Primary>forcing GHC-phase options</Primary></IndexTerm>
</Para>
<Para>
The preceding sections describe driver options that are mostly
applicable to one particular phase. You may also <Emphasis>force</Emphasis> a
specific option <Option>&lt;option&gt;</Option> to be passed to a particular phase
<Literal>&lt;phase-code&gt;</Literal> by feeding the driver the option
<Option>-opt&lt;phase-code&gt;&lt;option&gt;</Option>.<IndexTerm><Primary>-opt&lt;phase&gt;&lt;stuff&gt;
option</Primary></IndexTerm> The codes to indicate the phases are the same as in the
previous section.
</Para>
<Para>
So, for example, to force an <Option>-Ewurble</Option> option to the assembler, you
would tell the driver <Option>-opta-Ewurble</Option> (the dash before the E is
required).
</Para>
<Para>
Besides getting options to the Haskell compiler with <Option>-optC&lt;blah&gt;</Option>,
you can get options through to its runtime system with
<Option>-optCrts&lt;blah&gt;</Option><IndexTerm><Primary>-optCrts&lt;blah&gt; option</Primary></IndexTerm>.
</Para>
<Para>
So, for example: when I want to use my normal driver but with my
profiled compiler binary, I use this script:
<ProgramListing>
#! /bin/sh
exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
-pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
-optCrts-i0.5 \
-optCrts-PT \
"$@"
</ProgramListing>
</Para>
</Sect2>
<Sect2 id="dumping-output">
<Title>Dumping out compiler intermediate structures
......@@ -195,31 +78,6 @@ renamer output
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-minimal-imports</Option>:</Term>
<ListItem>
<Para>
Dump to the file "M.imports" (where M is the module being compiled)
a "minimal" set of import declarations. You can safely replace
all the import declarations in "M.hs" with those found in "M.imports".
Why would you want to do that? Because the "minimal" imports (a) import
everything explicitly, by name, and (b) import nothing that is not required.
It can be quite painful to maintain this property by hand, so this flag is
intended to reduce the labour.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-hi-diffs</Option>:</Term>
<ListItem>
<Para>
Dump to stdout a summary of the differences between the existing interface file (if any)
for this module, and the new one.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-tc</Option>:</Term>
<ListItem>
......
ghc/docs/users_guide/flags.sgml 0 → 100644
View file @ 7d67a216
This diff is collapsed.
ghc/docs/users_guide/glasgow_exts.sgml
View file @ 7d67a216
......@@ -139,63 +139,142 @@ program), you may wish to check if there are libraries that provide a
<xref linkend="book-hslibs">.
</Para>
<Sect1 id="language-options">
<Title>Language variations
</Title>
<Para> There are several flags that control what variation of the language are permitted.
Leaving out all of them gives you standard Haskell 98.</Para>
<VariableList>
<VarListEntry>
<Term><Option>-fglasgow-exts</Option>:</Term>
<ListItem>
<Para>This simultaneously enables all of the extensions to Haskell 98 described in this
chapter, except where otherwise noted. </Para>
</ListItem> </VarListEntry>
<VarListEntry>
<Term><Option>-fno-monomorphism-restriction</Option>:</Term>
<ListItem>
<Para> Switch off the Haskell 98 monomorphism restriction. Independent of the <Option>-fglasgow-exts</Option>
flag. </Para>
</ListItem> </VarListEntry>
<VarListEntry>
<Term><Option>-fallow-overlapping-instances</Option>,
<Option>-fallow-undecidable-instances</Option>,
<Option>-fcontext-stack</Option>:</Term>
<ListItem>
<Para> See <XRef LinkEnd="instance-decls">.
Only relevant if you also use <Option>-fglasgow-exts</Option>.
</Para>
</ListItem> </VarListEntry>
<VarListEntry>
<Term><Option>-fignore-asserts</Option>:</Term>
<ListItem>
<Para> See <XRef LinkEnd="sec-assertions">.
Only relevant if you also use <Option>-fglasgow-exts</Option>.
</Para>
</ListItem> </VarListEntry>
<VarListEntry>
<Term> <Option>-finline-phase</Option>:</Term>
<ListItem>
<Para> See <XRef LinkEnd="rewrite-rules">.
Only relevant if you also use <Option>-fglasgow-exts</Option>.</para>
</ListItem> </VarListEntry>
<sect1 id="options-language">
<title>Language options</title>
<indexterm><primary>language</primary><secondary>option</secondary>
</indexterm>
<indexterm><primary>options</primary><secondary>language</secondary>
</indexterm>
<indexterm><primary>extensions</primary><secondary>options controlling</secondary>
</indexterm>
<para> These flags control what variation of the language are
permitted. Leaving out all of them gives you standard Haskell
98.</Para>
<variablelist>
<varlistentry>
<term><option>-fglasgow-exts</option>:</term>
<indexterm><primary><option>-fglasgow-exts</option></primary></indexterm>
<listitem>
<para>This simultaneously enables all of the extensions to
Haskell 98 described in <xref
linkend="ghc-language-features">, except where otherwise
noted. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-fno-monomorphism-restriction</option>:</term>
<indexterm><primary><option>-fno-monomorphism-restriction</option></primary></indexterm>
<listitem>
<para> Switch off the Haskell 98 monomorphism restriction.
Independent of the <Option>-fglasgow-exts</Option>
flag. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-fallow-overlapping-instances</option></term>
<term><option>-fallow-undecidable-instances</option></term>
<term><option>-fcontext-stack</option></term>
<indexterm><primary><option>-fallow-overlapping-instances</option></primary></indexterm>
<indexterm><primary><option>-fallow-undecidable-instances</option></primary></indexterm>
<indexterm><primary><option>-fcontext-stack</option></primary></indexterm>
<listitem>
<para> See <XRef LinkEnd="instance-decls">. Only relevant
if you also use <option>-fglasgow-exts</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-fignore-asserts</option>:</term>
<indexterm><primary><option>-fignore-asserts</option></primary></indexterm>
<listitem>
<para>See <XRef LinkEnd="sec-assertions">. Only relevant if
you also use <option>-fglasgow-exts</option>.</Para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-finline-phase</option></term>
<indexterm><primary><option>-finline-phase</option></primary></indexterm>
<listitem>
<para>See <XRef LinkEnd="rewrite-rules">. Only relevant if
you also use <Option>-fglasgow-exts</Option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-fgenerics</option></term>
<indexterm><primary><option>-fgenerics</option></primary></indexterm>
<listitem>
<para>See <XRef LinkEnd="generic-classes">. Independent of
<Option>-fglasgow-exts</Option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-fno-implicit-prelude</option></term>
<listitem>
<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. 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:</para>
<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>
<VarListEntry>
<Term> <Option>-fgenerics</Option>:</Term>
<ListItem>
<Para> See <XRef LinkEnd="generic-classes">.
Independent of <Option>-fglasgow-exts</Option>.
</Para>
</ListItem> </VarListEntry>
</listitem>
</varlistentry>
</VariableList>
</variablelist>
</sect1>
<Sect1 id="primitives">
......
ghc/docs/users_guide/packages.sgml 0 → 100644
View file @ 7d67a216
<sect1 id="packages">
<title>Packages</title>
<indexterm><primary>packages</primary></indexterm>
<para>Packages are collections of libraries, conveniently grouped
together as a single entity. The package system is flexible: a
package may consist of Haskell code, foreign language code (eg. C
libraries), or a mixture of the two. A package is a good way to
group together related Haskell modules, and is essential if you
intend to make the modules into a Windows DLL (see below).</para>
<para>Because packages can contain both Haskell and C libraries, they
are also a good way to provide convenient access to a Haskell
layer over a C library.</para>
<para>GHC comes with several packages (see <xref
linkend="book-hslibs">), and packages can be added/removed from an
existing GHC installation.</para>
<sect2 id="listing-packages">
<title>Listing the available packages</title>
<indexterm><primary>packages</primary>
<secondary>listing</secondary></indexterm>
<para>To see what packages are currently installed, use the
<literal>--list-packages</literal> option:</para>
<indexterm><primary><literal>--list-packages</literal></primary>
</indexterm>
<screen>
$ ghc --list-packages
gmp, rts, std, lang, concurrent, data, net, posix, text, util
</screen>
<para>Note that your GHC installation might have a slightly
different set of packages installed.</para>
<para>The <literal>gmp</literal> and <literal>rts</literal>
packages are always present, and represent the multi-precision
integer and runtime system libraries respectively. The
<literal>std</literal> package contains the Haskell prelude.
The rest of the packages are optional libraries.</para>
</sect2>
<sect2 id="using-packages">
<title>Using a package</title>
<indexterm><primary>packages</primary>
<secondary>using</secondary></indexterm>
<para>To use a package, add the <literal>-package</literal> flag
to the command line:</para>
<variablelist>
<varlistentry>
<term><option>-package &lt;lib&gt;</option></term>
<indexterm><primary>-package &lt;lib&gt; option</primary></indexterm>
<listitem>
<para>This option brings into scope all the modules from
package <literal>&lt;lib&gt;</literal> (they still have to
be imported in your Haskell source, however). It also
causes the relevant libraries to be linked when linking is
being done.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Some packages depend on other packages, for example the
<literal>text</literal> package makes use of some of the modules
in the <literal>lang</literal> package. The package system
takes care of all these dependencies, so that when you say
<literal>-package text</literal> on the command line, you
automatically get <literal>-package lang</literal> too.</para>
</sect2>
<sect2 id="building-packages">
<title>Building a package from Haskell source</title>
<indexterm><primary>packages</primary>
<secondary>building</secondary></indexterm>
<para>It takes some special considerations to build a new
package:</para>
<itemizedlist>
<listitem>
<para>A package may contain several Haskell modules. A
package may span many directories, or many packages may
exist in a single directory. Packages may not be mutually
recursive.</para>
</listitem>
<listitem>
<para>A package has a name
(e.g. <filename>std</filename>)</para>
</listitem>
<listitem>
<para>The Haskell code in a package may be built into one or
more Unix libraries (e.g. <filename>libHSfoo.a</filename>),
or a single DLL on Windows
(e.g. <filename>HSfoo.dll</filename>). The restriction to a
single DLL on Windows is that the package system is used to
tell the compiler when it should make an inter-DLL call
rather than an intra-DLL call (inter-DLL calls require an
extra indirection).</para>
</listitem>
<listitem>
<para>GHC does not maintain detailed cross-package
dependency information. It does remember which modules in
other packages the current module depends on, but not which
things within those imported things.</para>
</listitem>
</itemizedlist>
<para>To compile a module which is to be part of a new package,
use the <literal>-package-name</literal> option:</para>
<variablelist>
<varlistentry>
<term><option>-package-name &lt;foo&gt;</option></term>
<indexterm><primary><literal>-package-name</literal></primary>
<secondary>option</secondary></indexterm>
<listitem>
<para>This option is added to the command line when
compiling a module that is destined to be part of package
<literal>foo</literal>. If this flag is omitted then the
default package <literal>Main</literal> is assumed.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Failure to use the <literal>-package-name</literal> option
when compiling a package will result in disaster on Windows, but
is relatively harmless on Unix at the moment (it will just cause
a few extra dependencies in some interface files). However,
bear in mind that we might add support for Unix shared libraries
at some point in the future.</para>
<para>It is worth noting that on Windows, because each package
is built as a DLL, and a reference to a DLL costs an extra
indirection, intra-package references are cheaper than
inter-package references. Of course, this applies to the
<filename>Main</filename> package as well.</para>
</sect2>
<sect2 id="package-management">
<title>Package management</title>
<indexterm><primary>packages</primary>
<secondary>management</secondary></indexterm>
<para>GHC uses a package configuration file, called
<literal>packages.conf</literal>, which can be found in your GHC
install directory. This file isn't intended to be edited
directly, instead GHC provides options for adding & removing
packages:</para>
<variablelist>
<varlistentry>
<term><option>--add-package</option></term>
<indexterm><primary><literal>--add-package</literal></primary>
<secondary>option</secondary></indexterm>
<listitem>
<para>Reads a package specification (see below) on stdin,
and adds it to the database of installed packages. The
package specification must be a package that isn't already
installed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--delete-package &lt;foo&gt;</option></term>
<indexterm><primary><literal>--delete-package</literal></primary>
<secondary>option</secondary></indexterm>
<listitem>
<para>Removes the specified package from the installed
configuration.</para>
</listitem>
</varlistentry>
</variablelist>
<para>In both cases, the old package configuration file is saved
in <literal>packages.conf.old</literal> in your GHC install
directory, so in an emergency you can always copy this file into
<literal>package.conf</literal> to restore the old
settings.</para>
<para>A package specification looks like this:</para>
<screen>
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>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>
<listitem>
<para>A list of directories containing interface files
(<literal>.hi</literal> files) for this package.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>library_dirs</literal></term>
<indexterm><primary><literal>library_dirs</literal></primary>
<secondary>package specification</secondary></indexterm>
<listitem>
<para>A list of directories containing libraries for this
package.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hs_libraries</literal></term>
<indexterm><primary><literal>hs_libraries</literal></primary>
<secondary>package specification</secondary></indexterm>
<listitem>
<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>