Clarify parsing infelicity.
[ghc.git] / docs / users_guide / utils.xml
index 39f4b1a..eeb2212 100644 (file)
@@ -6,7 +6,7 @@
   <para>This section describes other program(s) which we distribute,
   that help with the Great Haskell Programming Task.</para>
 
-<!-- comment: hasktags documentation loosely based on that for hstags -->
+<!-- comment: hasktags was dropped in GHC 6.12
 
 <sect1  id ="hasktags">
        <title>Ctags and Etags for Haskell: <command>hasktags</command></title>
@@ -50,6 +50,7 @@ find -name \*.\*hs | xargs hasktags
 
 </sect1>
 
+-->
 <!-- comment: hstags doesn't work anymore
 
   <sect1 id="hstags">
@@ -186,7 +187,7 @@ tags:
       <variablelist>
        <varlistentry>
          <term><literal>-o FILE</literal> or
-         <literal>&ndash;&ndash;output=FILE</literal></term>
+         <literal>--output=FILE</literal></term>
          <listitem>
            <para>Name of the Haskell file.</para>
          </listitem>
@@ -194,7 +195,7 @@ tags:
 
        <varlistentry>
          <term><literal>-t FILE</literal> or
-         <literal>&ndash;&ndash;template=FILE</literal></term>
+         <literal>--template=FILE</literal></term>
          <listitem>
            <para>The template file (see below).</para>
          </listitem>
@@ -202,7 +203,7 @@ tags:
 
        <varlistentry>
          <term><literal>-c PROG</literal> or
-         <literal>&ndash;&ndash;cc=PROG</literal></term>
+         <literal>--cc=PROG</literal></term>
          <listitem>
            <para>The C compiler to use (default:
            <command>gcc</command>)</para>
@@ -211,7 +212,7 @@ tags:
 
        <varlistentry>
          <term><literal>-l PROG</literal> or
-         <literal>&ndash;&ndash;ld=PROG</literal></term>
+         <literal>--ld=PROG</literal></term>
          <listitem>
            <para>The linker to use (default:
            <command>gcc</command>).</para>
@@ -220,7 +221,7 @@ tags:
 
        <varlistentry>
          <term><literal>-C FLAG</literal> or
-         <literal>&ndash;&ndash;cflag=FLAG</literal></term>
+         <literal>--cflag=FLAG</literal></term>
          <listitem>
            <para>An extra flag to pass to the C compiler.</para>
          </listitem>
@@ -235,7 +236,7 @@ tags:
 
        <varlistentry>
          <term><literal>-L FLAG</literal> or
-         <literal>&ndash;&ndash;lflag=FLAG</literal></term>
+         <literal>--lflag=FLAG</literal></term>
          <listitem>
            <para>An extra flag to pass to the linker.</para>
          </listitem>
@@ -243,7 +244,7 @@ tags:
 
        <varlistentry>
          <term><literal>-i FILE</literal> or
-         <literal>&ndash;&ndash;include=FILE</literal></term>
+         <literal>--include=FILE</literal></term>
          <listitem>
            <para>As if the appropriate <literal>#include</literal>
             directive was placed in the source.</para>
@@ -252,7 +253,7 @@ tags:
 
        <varlistentry>
          <term><literal>-D NAME[=VALUE]</literal> or
-         <literal>&ndash;&ndash;define=NAME[=VALUE]</literal></term>
+         <literal>--define=NAME[=VALUE]</literal></term>
          <listitem>
            <para>As if the appropriate <literal>#define</literal>
             directive was placed in the source.</para>
@@ -260,7 +261,7 @@ tags:
        </varlistentry>
 
        <varlistentry>
-         <term><literal>&ndash;&ndash;no-compile</literal></term>
+         <term><literal>--no-compile</literal></term>
          <listitem>
            <para>Stop after writing out the intermediate C program to disk.
            The file name for the intermediate C program is the input file name
@@ -269,14 +270,42 @@ tags:
        </varlistentry>
 
        <varlistentry>
-         <term><literal>-?</literal> or <literal>&ndash;&ndash;help</literal></term>
+         <term><literal>-k</literal> or
+         <literal>--keep-files</literal></term>
+         <listitem>
+           <para>Proceed as normal, but do not delete any intermediate files.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><literal>-x</literal> or
+         <literal>--cross-compile</literal></term>
+         <listitem>
+           <para>Activate cross-compilation mode (see <xref linkend="hsc2hs_cross"/>).</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><literal>--cross-safe</literal></term>
+         <listitem>
+           <para>Restrict the .hsc directives to those supported by the
+            <literal>--cross-compile</literal> mode (see <xref linkend="hsc2hs_cross"/>).
+            This should be useful if your <literal>.hsc</literal> files
+            must be safely cross-compiled and you wish to keep
+            non-cross-compilable constructs from creeping into them.</para>
+         </listitem>
+       </varlistentry>
+
+
+       <varlistentry>
+         <term><literal>-?</literal> or <literal>--help</literal></term>
          <listitem>
            <para>Display a summary of the available flags and exit successfully.</para>
          </listitem>
        </varlistentry>
 
        <varlistentry>
-         <term><literal>-V</literal> or <literal>&ndash;&ndash;version</literal></term>
+         <term><literal>-V</literal> or <literal>--version</literal></term>
          <listitem>
            <para>Output version information and exit successfully.</para>
          </listitem>
@@ -543,6 +572,29 @@ tags:
 
     </sect2>
 
+    <sect2 id="hsc2hs_cross">
+      <title>Cross-compilation</title>
+
+      <para><command>hsc2hs</command> normally operates by creating, compiling,
+      and running a C program. That approach doesn't work when cross-compiling --
+      in this case, the C compiler's generates code for the target machine,
+      not the host machine. For this situation, there's
+      a special mode <command>hsc2hs --cross-compile</command> which can generate
+      the .hs by extracting information from compilations only -- specifically,
+      whether or not compilation fails.
+      </para>
+
+      <para>Only a subset of <literal>.hsc</literal> syntax is supported by
+      <literal>--cross-compile</literal>. The following are unsupported:
+      <itemizedlist>
+       <listitem><literal>#{const_str}</literal></listitem>
+       <listitem><literal>#{let}</literal></listitem>
+       <listitem><literal>#{def}</literal></listitem>
+       <listitem>Custom constructs</listitem>
+      </itemizedlist>
+      </para>
+    </sect2>
+
   </sect1>
 
 </chapter>
@@ -550,5 +602,6 @@ tags:
 <!-- Emacs stuff:
      ;;; Local Variables: ***
      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
+     ;;; ispell-local-dictionary: "british" ***
      ;;; End: ***
  -->