<sect1 id="separate-compilation">
- <title>Separate compilation</title>
+ <title>Filenames and separate compilation</title>
<indexterm><primary>separate compilation</primary></indexterm>
<indexterm><primary>recompilation checker</primary></indexterm>
<indexterm><primary>make and recompilation</primary></indexterm>
- <para>This section describes how GHC supports separate
- compilation.</para>
+ <para>This section describes what files GHC expects to find, what
+ files it creates, where these files are stored, and what options
+ affect this behaviour.</para>
+
+ <para>Note that this section is written with
+ <firstterm>hierarchical modules</firstterm> in mind (see <xref
+ linkend="hierarchical-modules">); hierarchical modules are an
+ extension to Haskell 98 which extends the lexical syntax of
+ module names to include a dot ‘.’. Non-hierarchical
+ modules are thus a special case in which none of the module names
+ contain dots.</para>
+
+ <para>Pathname conventions vary from system to system. In
+ particular, the directory separator is
+ ‘<literal>/</literal>’ on Unix systems and
+ ‘<literal>\</literal>’ on Windows systems. In the
+ sections that follow, we shall consistently use
+ ‘<literal>/</literal>’ as the directory separator;
+ substitute this for the appropriate character for your
+ system.</para>
+
+ <sect2 id="source-files">
+ <title>Haskell source files</title>
+
+ <para>Each Haskell source module should be placed in a file on
+ its own.</para>
+
+ <para>The file should usually be named after the module name, by
+ replacing dots in the module name by directory separators. For
+ example, on a Unix system, the module <literal>A.B.C</literal>
+ should be placed in the file <literal>A/B/C.hs</literal>,
+ relative to some base directory. GHC's behaviour if this rule
+ is not followed is fully defined by the following section (<xref
+ linkend="output-files">).</para>
+ </sect2>
+
+ <sect2 id="output-files">
+ <title>Output files</title>
- <sect2 id="hi-files">
- <title>Interface files</title>
-
<indexterm><primary>interface files</primary></indexterm>
<indexterm><primary><literal>.hi</literal> files</primary></indexterm>
+ <indexterm><primary>object files</primary></indexterm>
+ <indexterm><primary><literal>.o</literal> files</primary></indexterm>
- <para>When GHC compiles a source file <filename>A.hs</filename>
- which contains a module <literal>A</literal>, say, it generates
- an object <filename>A.o</filename>, <emphasis>and</emphasis> a
- companion <emphasis>interface file</emphasis>
- <filename>A.hi</filename>. The interface file is merely there
- to help the compiler compile other modules in the same program.
- Interfaces are in a binary format, so don't try to look at one;
- however you <emphasis>can</emphasis> see the contents of an
- interface file by using GHC with the
- <option>--show-iface</option> option (see <xref
- linkend="hi-options">, below).</para>
-
- <para>NOTE: In general, the name of a file containing module
- <literal>M</literal> should be named <filename>M.hs</filename>
- or <literal>M.lhs</literal>. The only exception to this rule is
- module <literal>Main</literal>, which can be placed in any
- file.<indexterm><primary>filenames</primary><secondary>for
- modules</secondary> </indexterm></para>
-
- <para>The interface file for <literal>A</literal> contains
- information needed by the compiler when it compiles any module
- <literal>B</literal> that imports <literal>A</literal>, whether
- directly or indirectly. When compiling <literal>B</literal>,
- GHC will read <filename>A.hi</filename> to find the details that
- it needs to know about things defined in
- <literal>A</literal>.</para>
-
- <para>The interface file may contain all sorts of things that
- aren't explicitly exported from <literal>A</literal> by the
- programmer. For example, even though a data type is exported
- abstractly, <filename>A.hi</filename> will contain the full data
- type definition. For small function definitions,
- <filename>A.hi</filename> will contain the complete definition
- of the function. For bigger functions,
- <filename>A.hi</filename> will contain strictness information
- about the function. And so on. GHC puts much more information
- into <filename>.hi</filename> files when optimisation is turned
- on with the <option>-O</option> flag (see <xref
- linkend="options-optimise">). Without <option>-O</option> it
- puts in just the minimum; with <option>-O</option> it lobs in a
- whole pile of stuff. <indexterm><primary>optimsation, effect on
- .hi files</primary></indexterm></para>
-
- <para><filename>A.hi</filename> should really be thought of as a
- compiler-readable version of <filename>A.o</filename>. If you
- use a <filename>.hi</filename> file that wasn't generated by the
- same compilation run that generates the <filename>.o</filename>
- file the compiler may assume all sorts of incorrect things about
- <literal>A</literal>, resulting in core dumps and other
- unpleasant happenings.</para>
+ <para>When asked to compile a source file, GHC normally
+ generates two files: an <firstterm>object file</firstterm>, and
+ an <firstterm>interface file</firstterm>. </para>
+
+ <para>The object file, which normally ends in a
+ <literal>.o</literal> suffix (or <literal>.obj</literal> if
+ you're on Windows), contains the compiled code for the module.</para>
+
+ <para>The interface file,
+ which normally ends in a <literal>.hi</literal> suffix, contains
+ the information that GHC needs in order to compile further
+ modules that depend on this module. It contains things like the
+ types of exported functions, definitions of data types, and so
+ on. It is stored in a binary format, so don't try to read one;
+ use the <option>--show-iface</option> option instead (see <xref
+ linkend="hi-options">).</para>
+
+ <para>You should think of the object file and the interface file as a
+ pair, since the interface file is in a sense a compiler-readable
+ description of the contents of the object file. If the
+ interface file and object file get out of sync for any reason,
+ then the compiler may end up making assumptions about the object
+ file that aren't true; trouble will almost certainly follow.
+ For this reason, we recommend keeping object files and interface
+ files in the same place (GHC does this by default, but it is
+ possible to override the defaults as we'll explain
+ shortly).</para>
+
+ <para>Every module has a <emphasis>module name</emphasis>
+ defined in its source code (<literal>module A.B.C where
+ ...</literal>). Unless overridden with the
+ <literal>-o</literal> and <literal>-ohi</literal> flags
+ respectively, GHC always puts the object file for module
+ <literal>A.B.C</literal> in
+ <replaceable>odir</replaceable><literal>/A/B/C.</literal><replaceable>osuf</replaceable>,
+ and the interface file in the file
+ <replaceable>hidir</replaceable><literal>/A/B/C.</literal><replaceable>hisuf</replaceable>,
+ where <replaceable>hidir</replaceable>,
+ <replaceable>hisuf</replaceable>,
+ <replaceable>odir</replaceable>, and
+ <replaceable>osuf</replaceable>, defined as follows:
+
+ <variablelist>
+ <varlistentry>
+ <term><replaceable>hidir</replaceable></term>
+ <listitem>
+ <para>is the value of the <option>-hidir</option> option if
+ one was given (see below), or
+ <replaceable>root-path</replaceable> otherwise.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>hisuf</replaceable></term>
+ <listitem>
+ <para>is the value of the <option>-hisuf</option> option if
+ one was given (see below), or <literal>hi</literal>
+ otherwise.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>odir</replaceable></term>
+ <listitem>
+ <para>is the value of the <option>-odir</option> option if
+ one was given (see below), or
+ <replaceable>root-path</replaceable> otherwise.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>osuf</replaceable></term>
+ <listitem>
+ <para>is the value of the <option>-osuf</option> option if
+ one was given (see below), or <literal>o</literal>
+ otherwise (<literal>obj</literal> on Windows).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ The <replaceable>root-path</replaceable>, used in the above definitions, is derived from the
+ location of the source file, <replaceable>source-filename</replaceable>, as follows:
+
+ <variablelist>
+ <varlistentry>
+ <term>Rule 1</term>
+ <listitem>
+ <para>GHC matches <replaceable>source-filename</replaceable> against the pattern:
+
+ <screen><replaceable>root-path</replaceable>/<literal>A/B/C.</literal><replaceable>extension</replaceable></screen>
+
+ where:
+ <variablelist>
+ <varlistentry>
+ <term><replaceable>extension</replaceable></term>
+ <listitem>
+ <para>is the source file extension (usually
+ <literal>.hs</literal> or <literal>.lhs</literal>).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>root-path</replaceable></term>
+ <listitem>
+ <para>is what is left after <literal>A/B/C.</literal><replaceable>extension</replaceable>
+ has been stripped off the end of <replaceable>source-file</replaceable>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Rule 2</term>
+ <listitem>
+ <para>If <replaceable>source-filename</replaceable> does not match the pattern
+ above (presumably because it doesn't finish with <literal>A/B/C.hs</literal>
+ or <literal>A/B/C.lhs</literal>)
+ then <replaceable>root-path</replaceable> becomes the
+ whole of the directory portion of the filename. </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ For example, if GHC compiles the module
+ <literal>A.B.C</literal> in the file
+ <filename>src/A/B/C.hs</filename>, with no <literal>-odir</literal> or <literal>-hidir</literal> flags,
+ the interface file will be put in <literal>src/A/B/C.hi</literal> and the object file in
+ <literal>src/A/B/C.o</literal> (using Rule 1).
+ If the same module <literal>A.B.C</literal> was in file
+ <filename>src/ABC.hs</filename>,
+ the interface file will still be put in <literal>src/A/B/C.hi</literal> and the object file in
+ <literal>src/A/B/C.o</literal> (using Rule 2).
+ </para>
+ <para>A common use for Rule 2 is to have many modules all called <literal>Main</literal> held in
+ files <literal>Test1.hs</literal> <literal>Test2.hs</literal>, etc. Beware, though: when compiling
+ (say) <literal>Test2.hs</literal>, GHC will consult <literal>Main.hi</literal> for version information
+ from the last recompilation. Currently (a bug, really) GHC is not clever enough to spot that the source file has changed,
+ and so there is a danger that the recompilation checker will declare that no recompilation is needed when in fact it is.
+ Solution: delete the interface file first.
+ </para>
+ <para>Notice that (unless overriden with <option>-o</option> or <option>-ohi</option>) the filenames
+ of the object and interface files are always based on the module name. The reason for this is so that
+ GHC can find the interface file for module <literal>A.B.C</literal> when compiling the declaration
+ "<literal>import A.B.C</literal>".
+ </para>
</sect2>
- <sect2 id="options-finding-imports">
- <title>Finding interface files</title>
+ <sect2 id="search-path">
+ <title>The search path</title>
+ <indexterm><primary>search path</primary>
+ </indexterm>
<indexterm><primary>interface files, finding them</primary></indexterm>
<indexterm><primary>finding interface files</primary></indexterm>
<para>In your program, you import a module
<literal>Foo</literal> by saying <literal>import Foo</literal>.
- GHC goes looking for an interface file,
- <filename>Foo.hi</filename>. It has a builtin list of
- directories (notably including <filename>.</filename>) where it
- looks.</para>
+ In <option>--make</option> mode or GHCi, GHC will look for a
+ source file for <literal>Foo</literal> and arrange to compile it
+ first. Without <option>--make</option>, GHC will look for the
+ interface file for <literal>Foo</literal>, which should have
+ been created by an earlier compilation of
+ <literal>Foo</literal>. GHC uses the same strategy in each of
+ these cases for finding the appropriate file.</para>
+
+ <para>This strategy is as follows: GHC keeps a list of
+ directories called the <firstterm>search path</firstterm>. For
+ each of these directories, it tries appending
+ <replaceable>basename</replaceable><literal>.</literal><replaceable>extension</replaceable>
+ to the directory, and checks whether the file exists. The value
+ of <replaceable>basename</replaceable> is the module name with
+ dots replaced by the directory separator ('/' or '\', depending
+ on the system), and <replaceable>extension</replaceable> is a
+ source extension (<literal>hs</literal>, <literal>lhs</literal>)
+ if we are in <option>--make</option> mode and GHCi, or
+ <replaceable>hisuf</replaceable> otherwise.</para>
+
+ <para>For example, suppose the search path contains directories
+ <literal>d1</literal>, <literal>d2</literal>, and
+ <literal>d3</literal>, and we are in <literal>--make</literal>
+ mode looking for the source file for a module
+ <literal>A.B.C</literal>. GHC will look in
+ <literal>d1/A/B/C.hs</literal>, <literal>d1/A/B/C.lhs</literal>,
+ <literal>d2/A/B/C.hs</literal>, and so on.</para>
+
+ <para>The search path by default contains a single directory:
+ <quote>.</quote> (i.e. the current directory). The following
+ options can be used to add to or change the contents of the
+ search path:</para>
<variablelist>
-
<varlistentry>
- <term><option>-i<dirs></option></term>
+ <term><option>-i<replaceable>dirs</replaceable></option></term>
<listitem>
- <para><indexterm><primary><option>-i<dirs></option>
+ <para><indexterm><primary><option>-i<replaceable>dirs</replaceable></option>
</primary></indexterm>This flag appends a colon-separated
- list of <filename>dirs</filename> to the “import
- directories” list, which initially contains a single
- entry: <quote>.</quote>.</para>
-
- <para>This list is scanned before any package directories
- (see <xref linkend="packages">) when looking for imports,
- but note that if you have a home module with the same name
- as a package module then this is likely to cause trouble
- in other ways, with link errors being the least nasty
- thing that can go wrong...</para>
-
- <para>See also <XRef LinkEnd="recomp"> for the
- significance of using relative and absolute pathnames in
- the <option>-i</option> list.</para>
+ list of <filename>dirs</filename> to the search path.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option></term>
<listitem>
- <para>resets the “import directories” list
- back to nothing.</para>
+ <para>resets the search path back to nothing.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>This isn't the whole story: GHC also looks for modules in
+ pre-compiled libraries, known as packages. See the section on
+ packages (<xref linkend="packages">), for details.</para>
+ </sect2>
+
+ <sect2 id="options-output">
+ <title>Redirecting 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> <replaceable>file</replaceable></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 <replaceable>file</replaceable></option>
+ re-directs the output of that last-run phase to
+ <replaceable>file</replaceable>.</para>
+
+ <para>Note: this “feature” 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>This option is most often used when creating an
+ executable file, to set the filename of the executable.
+ For example:
+<screen> ghc -o prog --make Main</screen>
+
+ will compile the program starting with module
+ <literal>Main</literal> and put the executable in the
+ file <literal>prog</literal>.</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> <replaceable>dir</replaceable></term>
+ <indexterm><primary><option>-odir</option></primary></indexterm>
+ <listitem>
+ <para>Redirects object files to directory
+ <replaceable>dir</replaceable>. For example:</para>
+
+<Screen>
+$ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
+</Screen>
+
+ <para>The object 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>x86</filename>,
+ <filename>mips</filename>, etc).</para>
+
+ <para>Note that the <option>-odir</option> option does
+ <emphasis>not</emphasis> affect where the interface files
+ are put; use the <option>-hidir</option> option for that.
+ 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>dir</replaceable></term>
+ <indexterm><primary><option>-hidir</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Redirects all generated interface files into
+ <replaceable>dir</replaceable>, instead of the
+ default.</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>
+
+ <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>
- <para>See also the section on packages (<xref
- linkend="packages">), which describes how to use installed
- libraries.</para>
+ <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 “assembly mangling” 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="finding-hierarchical-modules">
- <title>Finding interfaces for hierarchical modules</title>
-
- <para>GHC supports a hierarchical module namespace as an
- extension to Haskell 98 (see <xref
- linkend="hierarchical-modules">).</para>
-
- <para>A module name in general consists of a sequence of
- components separated by dots
- (‘<literal>.</literal>’). When looking for
- interface files for a hierarchical module, the compiler turns
- the dots into path separators, so for example a module
- <literal>A.B.C</literal> becomes <literal>A/B/C</literal> (or
- <literal>A\B\C</literal> under Windows). Then each component of
- the import directories list is tested in turn; so for example if
- the list contains directories
- <literal>D<subscript>1</subscript></literal> to
- <literal>D<subscript>n</subscript></literal>, then the compiler
- will look for the interface in
- <literal>D<subscript>1</subscript>/A/B/C.hi</literal> first,
- then <literal>D<subscript>2</subscript>/A/B/C.hi</literal> and
- so on.</para>
-
- <para>Note that it's perfectly reasonable to have a module which
- is both a leaf and a branch of the tree. For example, if we
- have modules <literal>A.B</literal> and
- <literal>A.B.C</literal>, then <literal>A.B</literal>'s
- interface file will be in <literal>A/B.hi</literal> and
- <literal>A.B.C</literal>'s interface file will be in
- <literal>A/B/C.hi</literal>.</para>
-
- <para>For GHCi and <option>--make</option>, the search strategy
- for source files is exactly the same, just replace the
- <literal>.hi</literal> suffix in the above description with
- <literal>.hs</literal> or <literal>.lhs</literal>.</para>
+ <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
+ <dir></option><IndexTerm><Primary>-tmpdir
+ <dir> 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>
<Sect2 id="hi-options">
</listitem>
</varlistentry>
</variablelist>
-
</sect2>
<sect2 id="recomp">
<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>
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 “feature” 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…
- 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 <dir></option><IndexTerm><Primary>-odir
- <dir> option</Primary></IndexTerm> (the “Oh,
- dear” 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 “assembly mangling” 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
- <dir></option><IndexTerm><Primary>-tmpdir
- <dir> 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>
</sect1>
- &separate;
&packages;
<sect1 id="options-optimise">
projects / ghc-hetmet.git / commitdiff