Commit 3092faa7 authored by simonmar's avatar simonmar
Browse files

[project @ 2003-07-21 15:24:42 by simonmar]

Update the documentation for filenames and related options to reflect
the new story.  Now we talk about hierarchical modules from the
outset, and hopefully the whole description is somewhat clearer than
before.
parent 3a223cd2
......@@ -240,7 +240,7 @@
</sect2>
<sect2>
<title>Finding imports (<xref linkend="options-finding-imports">)</title>
<title>Finding imports (<xref linkend="search-path">)</title>
<informaltable>
<tgroup cols=3 align=left colsep=1 rowsep=1>
......
......@@ -196,7 +196,7 @@ Ok, modules loaded: Main.
<emphasis>source</emphasis> files, whereas in standard
batch-compilation mode the <option>-i</option> option is used to
specify the search path for interface files, see <xref
linkend="options-finding-imports">.</para> </footnote></para>
linkend="search-path">.</para> </footnote></para>
<para>One consequence of the way that GHCi follows dependencies
to find modules to load is that every module must have a source
......
......@@ -415,9 +415,9 @@ tuples to avoid unnecessary allocation during sequences of operations.
import qualified Control.Monad.ST.Strict as ST
</programlisting>
<para>Hierarchical modules have an impact on the way that GHC
searches for files. For a description, see <xref
linkend="finding-hierarchical-modules">.</para>
<para>For details on how GHC searches for source and interface
files in the presence of hierarchical modules, see <xref
linkend="search-path">.</para>
<para>GHC comes with a large collection of libraries arranged
hierarchically; see the accompanying library documentation.
......
......@@ -448,7 +448,7 @@ ghc &ndash;&ndash;make Main.hs
<para>The source files for the program don't all need to be in the
same directory; the <option>-i</option> option can be used to add
directories to the search path (see <xref
linkend="options-finding-imports">).</para>
linkend="search-path">).</para>
</sect1>
......@@ -552,267 +552,7 @@ ghc &ndash;&ndash;make Main.hs
standard output.</para>
</sect1>
<sect1 id="options-output">
<title>Re-directing the compilation output(s)</title>
<indexterm><primary>output-directing options</primary></indexterm>
<indexterm><primary>redirecting compilation output</primary></indexterm>
<variablelist>
<varlistentry>
<term><option>-o</option></term>
<indexterm><primary><option>-o</option></primary></indexterm>
<listitem>
<para>GHC's compiled output normally goes into a
<filename>.hc</filename>, <filename>.o</filename>, etc.,
file, depending on the last-run compilation phase. The
option <option>-o foo</option><IndexTerm><Primary>-o
option</Primary></IndexTerm> re-directs the output of that
last-run phase to file <filename>foo</filename>.</para>
<para>Note: this &ldquo;feature&rdquo; can be
counterintuitive: <command>ghc -C -o foo.o foo.hs</command>
will put the intermediate C code in the file
<filename>foo.o</filename>, name notwithstanding!</para>
<para>Note: on Windows, if the result is an executable file, the
extension "<filename>.exe</filename>" is added if the specified filename
does not already have an extension. Thus
<programlisting>
ghc -o foo Main.hs
</programlisting>
will compile and link the module <filename>Main.hs</filename>, and put the
resulting executable in <filename>foo.exe</filename> (not <filename>foo</filename>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-odir</option></term>
<indexterm><primary><option>-odir</option></primary></indexterm>
<listitem>
<para>The <option>-o</option> option isn't of much use if
you have <emphasis>several</emphasis> input files&hellip;
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
<option>-odir &lt;dir&gt;</option><IndexTerm><Primary>-odir
&lt;dir&gt; option</Primary></IndexTerm> (the &ldquo;Oh,
dear&rdquo; option). For example:</para>
<Screen>
% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
</Screen>
<para>The output files, <filename>Foo.o</filename>,
<filename>Bar.o</filename>, and
<filename>Bumble.o</filename> would be put into a
subdirectory named after the architecture of the executing
machine (<filename>sun4</filename>,
<filename>mips</filename>, etc). The directory must already
exist; it won't be created.</para>
<para>Note that the <option>-odir</option> option does
<emphasis>not</emphasis> affect where the interface files
are put. In the above example, they would still be put in
<filename>parse/Foo.hi</filename>,
<filename>parse/Bar.hi</filename>, and
<filename>gurgle/Bumble.hi</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ohi</option> <replaceable>file</replaceable></term>
<indexterm><primary><option>-ohi</option></primary>
</indexterm>
<listitem>
<para>The interface output may be directed to another file
<filename>bar2/Wurble.iface</filename> with the option
<option>-ohi bar2/Wurble.iface</option> (not
recommended).</para>
<para>WARNING: if you redirect the interface file somewhere
that GHC can't find it, then the recompilation checker may
get confused (at the least, you won't get any recompilation
avoidance). We recommend using a combination of
<option>-hidir</option> and <option>-hisuf</option> options
instead, if possible.</para>
<para>To avoid generating an interface at all, you could use
this option to redirect the interface into the bit bucket:
<literal>-ohi /dev/null</literal>, for example.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-hidir</option> <replaceable>directory</replaceable></term>
<indexterm><primary><option>-hidir</option></primary>
</indexterm>
<listitem>
<para>Redirects all generated interface files into
<replaceable>directory</replaceable>, instead of the default
which is to place the interface file in the same directory
as the source file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-osuf</option> <replaceable>suffix</replaceable></term>
<term><option>-hisuf</option> <replaceable>suffix</replaceable></term>
<term><option>-hcsuf</option> <replaceable>suffix</replaceable></term>
<indexterm><primary><option>-osuf</option></primary></indexterm>
<indexterm><primary><option>-hisuf</option></primary></indexterm>
<indexterm><primary><option>-hcsuf</option></primary></indexterm>
<listitem>
<para>EXOTICA: The <option>-osuf</option>
<replaceable>suffix</replaceable> will change the
<literal>.o</literal> file suffix for object files to
whatever you specify. We use this when compiling libraries,
so that objects for the profiling versions of the libraries
don't clobber the normal ones.</para>
<para>Similarly, the <option>-hisuf</option>
<replaceable>suffix</replaceable> will change the
<literal>.hi</literal> file suffix for non-system interface
files (see <XRef LinkEnd="hi-options">).</para>
<para>Finally, the option <option>-hcsuf</option>
<replaceable>suffix</replaceable> will change the
<literal>.hc</literal> file suffix for compiler-generated
intermediate C files.</para>
<para>The <option>-hisuf</option>/<option>-osuf</option>
game is particularly useful if you want to compile a program both with and without
profiling, in the same directory. You can say:
<Screen>
ghc ...
</Screen>
to get the ordinary version, and
<Screen>
ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all
</Screen>
to get the profiled version.</para>
</listitem>
</varlistentry>
</variablelist>
<sect2 id="keeping-intermediates">
<title>Keeping Intermediate Files</title>
<indexterm><primary>intermediate files, saving</primary>
</indexterm>
<indexterm><primary><literal>.hc</literal> files, saving</primary>
</indexterm>
<indexterm><primary><literal>.s</literal> files, saving</primary>
</indexterm>
<para>The following options are useful for keeping certain
intermediate files around, when normally GHC would throw these
away after compilation:</para>
<variablelist>
<varlistentry>
<term><option>-keep-hc-files</option></term>
<indexterm>
<primary><option>-keep-hc-files</option></primary>
</indexterm>
<listitem>
<para>Keep intermediate <literal>.hc</literal> files when
doing <literal>.hs</literal>-to-<literal>.o</literal>
compilations via C (NOTE: <literal>.hc</literal> files
aren't generated when using the native code generator, you
may need to use <option>-fvia-C</option> to force them
to be produced).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-keep-s-files</option></term>
<indexterm>
<primary><option>-keep-s-files</option></primary>
</indexterm>
<listitem>
<para>Keep intermediate <literal>.s</literal> files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-keep-raw-s-files</option></term>
<indexterm>
<primary><option>-keep-raw-s-files</option></primary>
</indexterm>
<listitem>
<para>Keep intermediate <literal>.raw-s</literal> files.
These are the direct output from the C compiler, before
GHC does &ldquo;assembly mangling&rdquo; to produce the
<literal>.s</literal> file. Again, these are not produced
when using the native code generator.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-keep-tmp-files</option></term>
<indexterm>
<primary><option>-keep-tmp-files</option></primary>
</indexterm>
<indexterm>
<primary>temporary files</primary>
<secondary>keeping</secondary>
</indexterm>
<listitem>
<para>Instructs the GHC driver not to delete any of its
temporary files, which it normally keeps in
<literal>/tmp</literal> (or possibly elsewhere; see <xref
linkend="temp-files">). Running GHC with
<option>-v</option> will show you what temporary files
were generated along the way.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="temp-files">
<title>Redirecting temporary files</title>
<indexterm>
<primary>temporary files</primary>
<secondary>redirecting</secondary>
</indexterm>
<variablelist>
<varlistentry>
<term><option>-tmpdir</option></term>
<indexterm><primary><option>-tmpdir</option></primary></indexterm>
<listitem>
<para>If you have trouble because of running out of space
in <filename>/tmp</filename> (or wherever your
installation thinks temporary files should go), you may
use the <option>-tmpdir
&lt;dir&gt;</option><IndexTerm><Primary>-tmpdir
&lt;dir&gt; option</Primary></IndexTerm> option to specify
an alternate directory. For example, <option>-tmpdir
.</option> says to put temporary files in the current
working directory.</para>
<para>Alternatively, use your <Constant>TMPDIR</Constant>
environment variable.<IndexTerm><Primary>TMPDIR
environment variable</Primary></IndexTerm> Set it to the
name of the directory where temporary files should be put.
GCC and other programs will honour the
<Constant>TMPDIR</Constant> variable as well.</para>
<para>Even better idea: Set the
<Constant>DEFAULT_TMPDIR</Constant> make variable when
building GHC, and never worry about
<Constant>TMPDIR</Constant> again. (see the build
documentation).</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
&separate;
<sect1 id="options-sanity">
<title>Warnings and sanity-checking</title>
......@@ -1157,7 +897,6 @@ f "2" = 2
</sect1>
&separate;
&packages;
<sect1 id="options-optimise">
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment