you're famililar with Hugs<indexterm><primary>Hugs</primary>
</indexterm>, then you'll be right at home with GHCi. However, GHCi
also has support for interactively loading compiled code, as well as
- supporting all<footnote><para>except the FFI, at the moment</para>
+ supporting all<footnote><para>except <literal>foreign export</literal>, at the moment</para>
</footnote>the language extensions that GHC provides.</para>
<indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
<indexterm><primary>Foreign Function Interface</primary><secondary>GHCi support</secondary></indexterm>
$ ghci
___ ___ _
/ _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 4.11, For Haskell 98.
+ / /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98.
/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
\____/\/ /_/\____/|_| Type :? for help.
<screen>
Prelude> 1+2
3
-PrePrelude> let x = 42 in x / 9
+Prelude> let x = 42 in x / 9
4.666666666666667
Prelude>
</screen>
in the same directory and you can't call them all
<filename>Main.hs</filename>.</para>
+ <para>One consequence of the way that GHCi follows dependencies
+ to find modules to load is that every module must have a source
+ file. The only exception to the rule is modules that come from
+ a package, including the <literal>Prelude</literal> and standard
+ libraries such as <literal>IO</literal> and
+ <literal>Complex</literal>. If you attempt to load a module for
+ which GHCi can't find a source file, even if there are object
+ and interface files for the module, you'll get an error
+ message.</para>
+
<para>One final note: if you load a module called Main, it must
contain a <literal>main</literal> function, just like in
GHC.</para>
</sect2>
</sect1>
- <sect1>
+ <sect1 id="ghci-invokation">
<title>Invoking GHCi</title>
<indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
<indexterm><primary><option>--interactive</option></primary></indexterm>
<para>GHCi is invoked with the command <literal>ghci</literal> or
- <literal>ghc --interactive</literal>. A module or filename can
- also be specified on the command line; this instructs GHCi to load
- the that module or filename (and all the modules it depends on),
- just as if you had said <literal>:load
- <replaceable>module</replaceable></literal> at the GHCi prompt
- (see <xref linkend="ghci-commands">). For example, to start GHCi
- and load the program whose topmost module is in the file
- <literal>Main.hs</literal>, we could say:</para>
+ <literal>ghc --interactive</literal>. One or more modules or
+ filenames can also be specified on the command line; this
+ instructs GHCi to load the specified modules or filenames (and all
+ the modules they depend on), just as if you had said
+ <literal>:load <replaceable>modules</replaceable></literal> at the
+ GHCi prompt (see <xref linkend="ghci-commands">). For example, to
+ start GHCi and load the program whose topmost module is in the
+ file <literal>Main.hs</literal>, we could say:</para>
<screen>
$ ghci Main.hs
</screen>
- <para>Note: only <emphasis>one</emphasis> module name or filename
- may be given on the command line.</para>
-
<para>Most of the command-line options accepted by GHC (see <xref
linkend="using-ghc">) also make sense in interactive mode. The ones
that don't make sense are mostly obvious; for example, GHCi
<indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
<para>GHCi can make use of all the packages that come with GHC,
- but note: packages <emphasis>must</emphasis> be specified on the
- GHCi command line, you can't add extra packages after GHCi has
- started up. For example, to start up GHCi with the
- <literal>text</literal> package loaded:</para>
+ For example, to start up GHCi with the <literal>text</literal>
+ package loaded:</para>
<screen>
$ ghci -package text
___ ___ _
/ _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 4.11, For Haskell 98.
+ / /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98.
/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
\____/\/ /_/\____/|_| Type :? for help.
<literal>text</literal> package makes use of one or more of the
modules in <literal>lang</literal>, and therefore has a
dependency on it.</para>
+
+ <para>The following command works to load new packages into a
+ running GHCi:</para>
+
+<screen>
+Prelude> :set -package <replaceable>name</replaceable>
+</screen>
+
+ <para>But note that doing this will cause all currently loaded
+ modules to be unloaded, and you'll be dumped back into the
+ Prelude.</para>
</sect2>
<sect2>
<para>On systems with <literal>.so</literal>-style shared
libraries, the actual library loaded will the
- <filename>lib<replaceable>lib</replaceable>.so</filename>. If
- no such library exists on the standard library search path,
- including paths given using
- <literal>-L<replaceable>path</replaceable></literal>, then
- <literal>ghci</literal> will signal an error.</para>
+ <filename>lib<replaceable>lib</replaceable>.so</filename>. GHCi
+ searches the following places for libraries, in this order:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Paths specified using the
+ <literal>-L<replaceable>path</replaceable></literal>
+ command-line option,</para>
+ </listitem>
+ <listitem>
+ <para>the standard library search path for your system,
+ which on some systems may be overriden by setting the
+ <literal>LD_LIBRARY_PATH</literal> environment
+ variable.</para>
+ </listitem>
+ </itemizedlist>
<para>On systems with <literal>.dll</literal>-style shared
libraries, the actual library loaded will be
<filename><replaceable>lib</replaceable>.dll</filename>. Again,
GHCi will signal an error if it can't find the library.</para>
+
+ <para>GHCi can also load plain object files
+ (<literal>.o</literal> or <literal>.obj</literal> depending on
+ your platform) from the command-line. Just add the name the
+ object file to the command line.</para>
</sect2>
</sect1>
<variablelist>
<varlistentry>
+ <term><literal>:add</literal>
+ <replaceable>module</replaceable> ...</term>
+ <indexterm><primary><literal>:add</literal></primary></indexterm>
+ <listitem>
+ <para>Add <replaceable>module</replaceable>(s) to the
+ current <firstterm>target set</firstterm>, and perform a
+ reload.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>:cd</literal> <replaceable>dir</replaceable></term>
<indexterm><primary><literal>:cd</literal></primary></indexterm>
<listitem>
</varlistentry>
<varlistentry>
- <term><literal>:load</literal> <replaceable>module</replaceable></term>
+ <term><literal>:info</literal> <replaceable>name</replaceable>
+ ...</term>
+ <indexterm><primary><literal>:info</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Displays information about the given name(s). For
+ example, if <replaceable>name</replaceable> is a class, then
+ the class methods and their types will be printed; if
+ <replaceable>name</replaceable> is a type constructor, then
+ its definition will be printed; if
+ <replaceable>name</replaceable> is a function, then its type
+ will be printed. If <replaceable>name</replaceable> has
+ been loaded from a source file, then GHCi will also display
+ the location of its definition in the source.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>:load</literal>
+ <replaceable>module</replaceable> ...</term>
<indexterm><primary><literal>:load</literal></primary></indexterm>
<listitem>
- <para>Recursively loads <replaceable>module</replaceable>
- (which may be a module name or filename), and all the
- modules it depends on. All previously loaded modules are
- forgotten. The module <replaceable>module</replaceable> is
- known as the <firstterm>target</firstterm>.</para>
+ <para>Recursively loads the specified
+ <replaceable>module</replaceable>s, and all the modules they
+ depend on. Here, each <replaceable>module</replaceable>
+ must be a module name or filename, but may not be the name
+ of a module in a package.</para>
+
+ <para>All previously loaded modules, except package modules,
+ are forgotten. The new set of modules is known as the
+ <firstterm>target set</firstterm>.</para>
+
+ <para>After a <literal>:load</literal> command, the current
+ context is set to:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><replaceable>module</replaceable>, if it was loaded
+ successfully, or</para>
+ </listitem>
+ <listitem>
+ <para>the most recently successfully loaded module, if
+ any other modules were loaded as a result of the current
+ <literal>:load</literal>, or</para>
+ </listitem>
+ <listitem>
+ <para><literal>Prelude</literal> otherwise.</para>
+ </listitem>
+ </itemizedlist>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term><literal>:quit</literal> <replaceable>module</replaceable></term>
+ <term><literal>:quit</literal></term>
<indexterm><primary><literal>:quit</literal></primary></indexterm>
<listitem>
<para>Quits GHCi. You can also quit by typing a control-D
<term><literal>:reload</literal></term>
<indexterm><primary><literal>:reload</literal></primary></indexterm>
<listitem>
- <para>Attempts to reload the current target (see
- <literal>:load</literal>) if it, or any module it depends
- on, has changed. Note that this may entail loading new
- modules, or even dropping modules which are no longer
- indirectly required by the target.</para>
+ <para>Attempts to reload the current target set (see
+ <literal>:load</literal>) if any of the modules in the set,
+ or any dependent module, has changed. Note that this may
+ entail loading new modules, or dropping modules which are no
+ longer indirectly required by the target.</para>
</listitem>
</varlistentry>
<para><xref linkend="flag-reference"> lists the reverse for each
option where applicable.</para>
- <para>Certain static options (<option>-I</option>,
- <option>-i</option>, and <option>-l</option> in particular) will
- also work, but may not take effect until the next reload.</para>
+ <para>Certain static options (<option>-package</option>,
+ <option>-I</option>, <option>-i</option>, and
+ <option>-l</option> in particular) will also work, but some may
+ not take effect until the next reload.</para>
<indexterm><primary>static</primary><secondary>options</secondary></indexterm>
</sect2>
</sect1>
- <sect1>
- <title>The <filename>.ghci</filename> file</title>
+ <sect1 id="ghci-dot-files">
+ <title>The <filename>.ghci</filename> file</title>
<indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
</indexterm>
<indexterm><primary>startup</primary><secondary>files, GHCi</secondary>
a static one, but in fact it works to set it using
<literal>:set</literal> like this. The changes won't take effect
until the next <literal>:load</literal>, though.)</para>
+
+ <para>Two command-line options control whether the
+ <filename>.ghci</filename> files are read:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-ignore-dot-ghci</option></term>
+ <indexterm><primary><option>-ignore-dot-ghci</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Don't read either <filename>./.ghci</filename> or
+ <filename>$HOME/.ghci</filename> when starting up.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-read-dot-ghci</option></term>
+ <indexterm><primary><option>-read-dot-ghci</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Read <filename>.ghci</filename> and
+ <filename>$HOME/.ghci</filename>. This is normally the
+ default, but the <option>-read-dot-ghci</option> option may
+ be used to override a previous
+ <option>-ignore-dot-ghci</option> option.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
</sect1>
<sect1>
<variablelist>
<varlistentry>
- <term><literal>System.exit</literal> causes GHCi to exit!</term>
- <indexterm><primary><literal>System.exit</literal></primary><secondary>in
- GHCi</secondary></indexterm>
+ <term>GHCi complains about <function>main</function> not being
+ in scope when I load a module.</term>
+ <indexterm><primary><function>main</function></primary><secondary>with GHCi</secondary>
+ </indexterm>
<listitem>
- <para>Yes, it does.</para>
+ <para>You probably omitted the <literal>module</literal>
+ declaration at the top of the module, which causes the
+ module name to default to <literal>Main</literal>. In
+ Haskell, the <literal>Main</literal> module must define a
+ function called <function>main</function>. Admittedly this
+ doesn't make a great deal of sense for an interpreter, but
+ the rule was kept for compatibility with GHC.</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term>The interpreter can't load modules with FFI
+ <term>The interpreter can't load modules with foreign export
declarations!</term>
<listitem>
<para>Unfortunately not. We haven't implemented it yet.
</varlistentry>
<varlistentry>
- <term>Hugs has a <literal>:add</literal> command for adding
- modules without throwing away any that are already loaded.
- Why doesn't this work in GHCi?</term>
- <listitem>
- <para>We haven't implemented it yet. Sorry about that.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><literal>-O</literal> doesn't work with GHCi!</term>
<indexterm><primary><option>-O</option></primary>
</indexterm>
projects / ghc-hetmet.git / blobdiff