[project @ 2001-09-06 15:54:48 by apt]

document -fext-core flag and set pointers to ext-core docs/tools (MERGE to STABLE pleeeeeease.)

diff --git a/ghc/docs/users_guide/5-02-notes.sgml b/ghc/docs/users_guide/5-02-notes.sgml
index 3d8042f..9e362dc 100644 (file)
--- a/ghc/docs/users_guide/5-02-notes.sgml
+++ b/ghc/docs/users_guide/5-02-notes.sgml
@@ -253,10 +253,11 @@
          <para>Emission of external Core format.  The goal is for
          other tools to be able to grab the Core resulting from GHC's
          front end manglings and optimisations.  Core format is
-         formally defined by the document <replaceable>An External
-         Representation of the GHC Core Language</replaceable> in the
-         GHC repository.  We also have sample
-         tools for reading, writing and typechecking external Core.
+         formally defined by the document <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz"
+         <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>.
+         We also have sample
+         tools for reading, writing and typechecking external Core,
+         available in the source distribution directory <literal>/fptools/ghc/utils/ext-core</literal>.
          Ultimately we plan that Core files can also be read by
          GHC.  The relevant flag is <option>-fext-core</option>.
          </para>

diff --git a/ghc/docs/users_guide/flags.sgml b/ghc/docs/users_guide/flags.sgml
index 198e287..21bf3a4 100644 (file)
--- a/ghc/docs/users_guide/flags.sgml
+++ b/ghc/docs/users_guide/flags.sgml
@@ -1270,6 +1270,33 @@
       </informaltable>
     </sect2>
 
+         
+    <sect2>
+      <title>External core file options (<xref linkend="ext-core">)</title>
+
+      <informaltable>
+       <tgroup cols=3 align=left colsep=1 rowsep=1>
+         <thead>
+           <row>
+             <entry>Flag</entry>
+             <entry>Description</entry>
+             <entry>Static/Dynamic</entry>
+             <entry>Reverse</entry>
+           </row>
+         </thead>
+         <tbody>
+           <row>
+             <entry><option>-fext-core</option></entry>
+             <entry>Generate <filename>.hcr</filename> external Core files</entry>
+             <entry>static</entry>
+             <entry>-</entry>
+           </row>
+         </tbody>
+       </tgroup>
+      </informaltable>
+    </sect2>
+       
+
     <sect2>
       <title>Compiler debugging options (<xref linkend="options-debugging">)</title>
 

diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml
index e9cb214..e01be2b 100644 (file)
--- a/ghc/docs/users_guide/using.sgml
+++ b/ghc/docs/users_guide/using.sgml
@@ -1845,6 +1845,40 @@ statements or clauses.
   </sect1>
 
 &runtime;
+
+<sect1 id="ext-core">
+  <title>Generating External Core Files</title>
+
+  <indexterm><primary>intermediate code generation</primary></indexterm>
+
+  <para>GHC can dump its optimized intermediate code (said to be in &ldquo;Core&rdquo; format) 
+  to a file as a side-effect of compilation. Core files, which are given the suffix
+  <filename>.hcr</filename>, can be read and processed by non-GHC back-end
+  tools.  The Core format is formally described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz"
+  <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>, 
+  and sample tools (in Haskell)
+  for manipulating Core files are available in the GHC source distribution 
+  directory <literal>/fptools/ghc/utils/ext-core</literal>.  
+  Note that the format of <literal>.hcr</literal> 
+  files is <emphasis>different</emphasis> (though similar) to the Core output format generated 
+  for debugging purposes (<xref linkend="options-debugging">).</para>
+
+    <variablelist>
+
+       <varlistentry>
+         <term><literal>-fext-core</literal></term>
+         <indexterm>
+           <primary><literal>-fext-core</literal></primary>
+         </indexterm>
+         <listitem>
+           <para>Generate <literal>.hcr</literal> files.</para>
+         </listitem>
+       </varlistentry>
+
+    </variablelist>
+
+</sect1>
+
 &debug;
 &flags;